@hecer/yoke 1.3.0 → 1.4.0

package/dist/loop/run-command.js

@@ -12,9 +12,12 @@ import { maybeAutoUpgrade } from '../update/upgrade.js';
 import { resolveCommitIdentity } from './identity.js';
 import { runAudit } from '../audit/command.js';
 import { detectHostAgent, resolveRunnerAgent } from '../agents/host.js';
-import { clearDecisionResume, decisionProcessingExists, decisionRequestId, formatPendingDecision, readPendingDecision, writeDecisionResume, } from './decision.js';
+import { buildTrustedDecisionResumeState, clearDecisionResume, decisionProcessingExists, decisionRequestId, formatPendingDecision, readPendingDecision, writeDecisionResume, } from './decision.js';
 import { makeAdaptiveRunner } from '../routing/router.js';
 import { runChangeApply } from '../change/inbox.js';
+import { createQualityCommandHooks } from '../quality/command.js';
+import { resolveQualityPolicy } from '../quality/types.js';
+import { runParallelLoopCommand } from './parallel-command.js';
 export const DEFAULT_IDLE_MINUTES = 20;
 const STALE_MINUTES = 20; // a running status older than this likely means the loop died
 export function relativeTime(fromIso, now) {
@@ -61,6 +64,24 @@ export function loopStatus(targetDir, now = () => new Date()) {
     }
     if (st.reason)
         lines.push(`  reason: ${st.reason}`);
+    if (st.quality)
+        lines.push(`  quality: round ${st.quality.currentRound} · ${st.quality.usedRepairs}${st.quality.unbounded ? ' unbounded repairs' : `/${st.quality.maxRepairs ?? 0} repairs`} · ${st.quality.policy}`);
+    if (st.parallel)
+        lines.push(`  parallel ${st.parallel.dispatcherId}: ${st.parallel.activeWorkers}/${st.parallel.maxConcurrency} workers · ${st.parallel.queuedCandidates} queued · ${st.parallel.integrated} integrated · ${st.parallel.reopened} reopened`);
+    const integrator = st.parallel?.integrator;
+    if (integrator) {
+        const quality = integrator.quality
+            ? ` · quality round ${integrator.quality.currentRound} · ${integrator.quality.usedRepairs}${integrator.quality.unbounded ? ' unbounded repairs' : `/${integrator.quality.maxRepairs ?? 0} repairs`}`
+            : '';
+        lines.push(`  integrator ${integrator.story} "${integrator.storyTitle}" (${integrator.provider}${integrator.model ? `/${integrator.model}` : ''}) · ${integrator.phase ?? 'working'}${quality}`);
+    }
+    for (const worker of st.parallel?.workers ?? []) {
+        const quality = worker.quality
+            ? ` · quality round ${worker.quality.currentRound} · ${worker.quality.usedRepairs}${worker.quality.unbounded ? ' unbounded repairs' : `/${worker.quality.maxRepairs ?? 0} repairs`}`
+            : '';
+        const candidate = worker.candidateId ? ` candidate ${worker.candidateId} · ${worker.worktree ?? 'worktree unknown'} · ${worker.lifecycle ?? 'working'}` : '';
+        lines.push(`  worker ${worker.story} "${worker.storyTitle}" (${worker.provider}${worker.model ? `/${worker.model}` : ''})${candidate} · ${worker.phase ?? 'working'}${quality}`);
+    }
     const ageMs = now().getTime() - Date.parse(st.updatedAt);
     if (st.state === 'running' && ageMs > STALE_MINUTES * 60_000) {
         lines.push(`  ⚠ possibly stuck — no update in ${relativeTime(st.updatedAt, now())}`);
@@ -72,11 +93,27 @@ export function resolveIdleMs(flagMinutes, configMinutes) {
     return minutes > 0 ? minutes * 60_000 : 0;
 }
 export function runLoopCommand(targetDir, opts) {
-    if ((opts.parallel ?? 1) > 1) {
-        console.error('Parallel CLI workers are not enabled yet. The dependency-aware dispatcher and merge queue are available as APIs; use --parallel=1 for the synchronous provider runner.');
+    const parallel = opts.parallel ?? 1;
+    const candidates = opts.candidates ?? 1;
+    if (!Number.isInteger(parallel) || parallel < 1) {
+        console.error('--parallel must be a positive integer');
+        return 2;
+    }
+    if (!Number.isInteger(candidates) || candidates < 1 || candidates > 5) {
+        console.error('--candidates must be an integer from 1 to 5');
         return 2;
     }
     const config = loadConfig(targetDir);
+    const maxParallelCandidates = config?.quality?.maxParallelCandidates ?? 1;
+    if (candidates > maxParallelCandidates) {
+        console.error(`--candidates=${candidates} exceeds quality.maxParallelCandidates=${maxParallelCandidates}`);
+        return 2;
+    }
+    const qualityDisabled = opts.quality === false || (!config?.quality?.enabled && opts.quality !== true && opts.qualityUnbounded !== true);
+    if (candidates > 1 && qualityDisabled) {
+        console.error(`--candidates=${candidates} requires quality; quality cannot be disabled for candidate dispatch.`);
+        return 2;
+    }
     if (!config?.loop.enabled) {
         console.error('Loop is disabled. Enable it with: yoke loop on');
         return 2;
@@ -100,6 +137,13 @@ export function runLoopCommand(targetDir, opts) {
         console.error(`No PRD found at ${path}. Create one (see canon loop/prd.schema.md).`);
         return 2;
     }
+    if (candidates > 1) {
+        const missingQuality = loadPrd(path).find(story => !story.passes && !story.quality);
+        if (missingQuality) {
+            console.error(`Story ${missingQuality.id} needs a quality declaration before --candidates=${candidates} can dispatch.`);
+            return 2;
+        }
+    }
     let verify = opts.verify;
     if (!verify) {
         const command = resolveVerifyCommand(targetDir, config);
@@ -146,8 +190,84 @@ export function runLoopCommand(targetDir, opts) {
         announce(`Commits: ${commitIdentity.authorName} <${commitIdentity.authorEmail}> · co-authors: ${commitIdentity.allowCoAuthors ? 'allowed' : 'disabled'}`);
     }
     const idleMs = resolveIdleMs(opts.timeoutMinutes, config.loop.timeoutMinutes);
+    const qualityOverrides = {
+        ...(opts.qualityUnbounded ? { quality: true, qualityUnbounded: true } : opts.quality !== undefined ? { quality: opts.quality } : {}),
+        ...(opts.qualityRounds !== undefined ? { qualityRounds: opts.qualityRounds } : {}),
+        ...(opts.qualityMinutes !== undefined ? { qualityMinutes: opts.qualityMinutes } : {}),
+        ...(opts.qualityPolicy ? { qualityPolicy: opts.qualityPolicy } : {}),
+        ...(opts.candidates !== undefined ? { candidates: opts.candidates } : {}),
+    };
+    if (qualityOverrides.qualityUnbounded) {
+        console.error('WARNING: Quality repair limits are unbounded for this invocation. Mechanical gates, watchdog, isolation, and commit safety remain active.');
+    }
+    const configuredCriticAgent = config.quality?.critic?.agent ?? config.quality?.criticAgent ?? config.agents.find(agent => agent !== runnerAgent) ?? runnerAgent;
+    const configuredCriticModel = config.quality?.critic?.model ?? config.quality?.criticModel ?? (configuredCriticAgent === runnerAgent ? config.runner?.model : undefined);
+    if (candidates > 1 && !configuredCriticModel) {
+        console.error('Quality candidate selection requires quality.critic.model (or legacy quality.criticModel) before any runner or worktree is started.');
+        return 2;
+    }
+    const quality = createQualityCommandHooks({
+        targetDir,
+        config,
+        runnerAgent,
+        idleMs,
+        policy: qualityOverrides,
+        ...(opts.qualityRuntime ? { runtime: opts.qualityRuntime } : {}),
+    });
+    if (quality) {
+        const resolved = resolveQualityPolicy({ defaults: config.quality, overrides: qualityOverrides });
+        const criticAgent = configuredCriticAgent;
+        const repairAgent = config.quality?.repair?.agent ?? config.quality?.repairAgent ?? runnerAgent;
+        const limit = resolved.limits.unbounded ? 'unbounded' : `${resolved.limits.maxRounds ?? 3} rounds/${resolved.limits.maxMinutes ?? 60} minutes`;
+        const announce = opts.json ? console.error : console.log;
+        announce(`Quality: ${resolved.policy} · critic: ${criticAgent}${configuredCriticModel ? `/${configuredCriticModel}` : '/provider-default'} · repair: ${repairAgent}${config.quality?.repair?.model ?? config.quality?.repairModel ? `/${config.quality?.repair?.model ?? config.quality?.repairModel}` : '/provider-default'} · permissions: read-only critic/safe repair · budget: ${limit}`);
+    }
     const permissions = opts.permissions ?? config.runner?.permissions ?? 'safe';
     const routingEnabled = opts.routing ?? config.routing?.enabled ?? false;
+    const runnerSelection = {
+        model: config.runner?.model,
+        reasoningEffort: config.runner?.reasoningEffort,
+        bare: config.runner?.bare,
+        ...((routingEnabled || opts.routing === false) ? { nativeMultiAgent: false } : {}),
+    };
+    if ((parallel > 1 || candidates > 1) && routingEnabled) {
+        console.error('Adaptive routing is not available with parallel workers or quality candidates. Run with --parallel=1 --candidates=1 or disable routing.');
+        return 2;
+    }
+    const parallelProviders = [{
+            provider: runnerAgent,
+            ...(runnerSelection.model ? { model: runnerSelection.model } : {}),
+            ...(runnerSelection.reasoningEffort ? { reasoningEffort: runnerSelection.reasoningEffort } : {}),
+        }];
+    const parallelAffinityProviders = (config.routing?.workers ?? []).map(worker => ({
+        provider: worker.agent,
+        ...(worker.model ? { model: worker.model } : {}),
+        ...(worker.reasoningEffort ? { reasoningEffort: worker.reasoningEffort } : {}),
+    }));
+    const parallelStories = parallel > 1 || candidates > 1 ? loadPrd(path).filter(story => !story.passes) : [];
+    const ambiguousAffinityProvider = [...new Set(parallelStories.flatMap(story => story.agent ? [story.agent] : []))]
+        .find(agent => parallelAffinityProviders.filter(provider => provider.provider === agent).length > 1);
+    if (ambiguousAffinityProvider) {
+        console.error(`Parallel affinity provider "${ambiguousAffinityProvider}" has multiple profiles. Configure exactly one profile for each story agent.`);
+        return 2;
+    }
+    if (opts.runner) {
+        const mismatchedAffinity = parallelStories.find(story => {
+            if (!story.agent)
+                return false;
+            const provider = parallelAffinityProviders.find(candidate => candidate.provider === story.agent)
+                ?? parallelProviders.find(candidate => candidate.provider === story.agent);
+            return !provider
+                || provider.provider !== runnerAgent
+                || provider.model !== runnerSelection.model
+                || provider.reasoningEffort !== runnerSelection.reasoningEffort;
+        });
+        if (mismatchedAffinity) {
+            console.error(`Injected runner cannot truthfully execute affinity provider for story ${mismatchedAffinity.id}. Remove the affinity or use the configured provider runner.`);
+            return 2;
+        }
+    }
+    const ambiguityPolicy = opts.decisionPolicy ?? opts.onAmbiguity ?? config.loop.decisionPolicy ?? config.loop.onAmbiguity ?? 'auto';
     if (routingEnabled && (!config.routing || config.routing.workers.length === 0)) {
         console.error('Adaptive routing was requested, but no worker profiles are configured. Run yoke setup . --routing or add routing.workers to .yoke/config.yaml.');
         return 2;
@@ -167,23 +287,22 @@ export function runLoopCommand(targetDir, opts) {
     }));
     let runner = opts.runner;
     if (!runner) {
-        if (!available(runnerAgent)) {
-            console.error(`Agent CLI "${runnerAgent}" was not found on PATH. Install it, or pick another with --runner=<claude|codex|gemini>.`);
+        const requiredProviders = parallel > 1 || candidates > 1
+            ? [...new Set(loadPrd(path).filter(story => !story.passes).map(story => story.agent ?? runnerAgent))]
+            : [runnerAgent];
+        const unavailableProvider = requiredProviders.find(agent => !available(agent));
+        if (unavailableProvider) {
+            console.error(`Agent CLI "${unavailableProvider}" was not found on PATH. Install it, or pick another with --runner=<claude|codex|gemini>.`);
             return 2;
         }
         // Token reporting is part of the machine interface: in --json mode a claude
         // runner switches to stream-json so cumulative usage rides on every status.
         const runnerOpts = {
             tokenReport: opts.json === true,
-            onAmbiguity: opts.decisionPolicy ?? opts.onAmbiguity ?? config.loop.decisionPolicy ?? config.loop.onAmbiguity ?? 'auto',
+            onAmbiguity: ambiguityPolicy,
             perfCommand: config.perf?.command,
             permissions,
-            selection: {
-                model: config.runner?.model,
-                reasoningEffort: config.runner?.reasoningEffort,
-                bare: config.runner?.bare,
-                ...((routingEnabled || opts.routing === false) ? { nativeMultiAgent: false } : {}),
-            },
+            selection: runnerSelection,
         };
         runner = routingEnabled && config.routing
             ? makeAdaptiveRunner({
@@ -237,8 +356,75 @@ export function runLoopCommand(targetDir, opts) {
     if (lock.stalePid !== undefined) {
         console.warn(`Took over a stale loop lock (pid ${lock.stalePid} is gone).`);
     }
+    const reporter = opts.reporter ?? makeReporter(targetDir, { json: opts.json });
+    const buildResume = (storyId, requestId) => buildTrustedDecisionResumeState({
+        storyId,
+        requestId,
+        ...(opts.maxIterations !== undefined ? { maxIterations: opts.maxIterations } : {}),
+        agent: runnerAgent,
+        isolate: parallel > 1 || candidates > 1 || (opts.isolate ?? false),
+        reviewer: opts.reviewer,
+        review: opts.review === true || opts.reviewRunner !== undefined,
+        allowSelfReview: opts.allowSelfReview ?? false,
+        timeoutMinutes: opts.timeoutMinutes ?? config.loop.timeoutMinutes,
+        json: opts.json ?? false,
+        onAmbiguity: opts.decisionPolicy ? undefined : opts.onAmbiguity === 'resolve' || opts.onAmbiguity === 'abort' ? opts.onAmbiguity : (config.loop.decisionPolicy ? undefined : config.loop.onAmbiguity),
+        decisionPolicy: opts.decisionPolicy ?? (opts.onAmbiguity ? (opts.onAmbiguity === 'auto' || opts.onAmbiguity === 'critical' ? opts.onAmbiguity : undefined) : config.loop.decisionPolicy),
+        permissions,
+        parallel,
+        routing: routingEnabled,
+        ...(qualityOverrides.quality !== undefined ? { quality: qualityOverrides.quality } : {}),
+        ...(opts.qualityRounds !== undefined ? { qualityRounds: opts.qualityRounds } : {}),
+        ...(opts.qualityMinutes !== undefined ? { qualityMinutes: opts.qualityMinutes } : {}),
+        ...(opts.qualityPolicy ? { qualityPolicy: opts.qualityPolicy } : {}),
+        ...(opts.candidates !== undefined ? { candidates: opts.candidates } : {}),
+    });
+    const reconcileDecisionResume = () => {
+        try {
+            const pendingDecision = readPendingDecision(targetDir);
+            if (pendingDecision) {
+                writeDecisionResume(targetDir, buildResume(pendingDecision.storyId, decisionRequestId(pendingDecision)));
+            }
+            else {
+                clearDecisionResume(targetDir);
+            }
+            return undefined;
+        }
+        catch (error) {
+            reporter.blocked(`could not persist trusted decision resume state: ${error instanceof Error ? error.message : String(error)}`);
+            return 1;
+        }
+    };
+    if (parallel > 1 || candidates > 1) {
+        return runParallelLoopCommand({
+            targetDir,
+            prdPath: path,
+            maxConcurrency: parallel,
+            candidateCount: candidates,
+            maxIterations: opts.maxIterations ?? Number.POSITIVE_INFINITY,
+            runner: opts.runner,
+            runnerAgent,
+            idleMs,
+            permissions,
+            selection: runnerSelection,
+            providers: parallelProviders,
+            affinityProviders: parallelAffinityProviders,
+            onAmbiguity: ambiguityPolicy,
+            git: opts.git,
+            identity: commitIdentity,
+            verify,
+            verifyCriterion: (dir, _story, criterion) => commandsVerifier(criterion.verify)(dir),
+            requireCriterionEvidence: config.verify?.requireCriteria ?? false,
+            perf,
+            audit,
+            review,
+            reporter,
+            completion,
+            quality,
+            onCriticalDecision: decision => writeDecisionResume(targetDir, buildResume(decision.storyId, decisionRequestId(decision))),
+        }).then(code => reconcileDecisionResume() ?? code).finally(() => releaseLock(targetDir, lock.ownerToken));
+    }
     try {
-        const reporter = opts.reporter ?? makeReporter(targetDir, { json: opts.json });
         const maxIterations = opts.maxIterations ?? Number.POSITIVE_INFINITY;
         const result = runLoop({
             prdPath: path,
@@ -257,45 +443,12 @@ export function runLoopCommand(targetDir, opts) {
             isolate: (opts.parallel ?? 1) > 1 ? true : (opts.isolate ?? false),
             review,
             reporter,
+            ...(quality ?? {}),
+            ...(quality ? { qualityEnabled: quality.qualityEnabled, qualityMetadata: quality.qualityMetadata } : {}),
         });
-        try {
-            const pendingDecision = readPendingDecision(targetDir);
-            if (pendingDecision) {
-                writeDecisionResume(targetDir, {
-                    version: 1,
-                    storyId: pendingDecision.storyId,
-                    requestId: decisionRequestId(pendingDecision),
-                    answered: false,
-                    ...(opts.maxIterations !== undefined ? { maxIterations: opts.maxIterations } : {}),
-                    agent: runnerAgent,
-                    isolate: opts.isolate ?? false,
-                    reviewer: opts.reviewer,
-                    review: opts.review === true || opts.reviewRunner !== undefined,
-                    allowSelfReview: opts.allowSelfReview ?? false,
-                    timeoutMinutes: opts.timeoutMinutes ?? config.loop.timeoutMinutes,
-                    json: opts.json ?? false,
-                    onAmbiguity: opts.decisionPolicy
-                        ? undefined
-                        : opts.onAmbiguity === 'resolve' || opts.onAmbiguity === 'abort'
-                            ? opts.onAmbiguity
-                            : (config.loop.decisionPolicy ? undefined : config.loop.onAmbiguity),
-                    decisionPolicy: opts.decisionPolicy
-                        ?? (opts.onAmbiguity
-                            ? (opts.onAmbiguity === 'auto' || opts.onAmbiguity === 'critical' ? opts.onAmbiguity : undefined)
-                            : config.loop.decisionPolicy),
-                    permissions,
-                    parallel: opts.parallel ?? 1,
-                    routing: routingEnabled,
-                });
-            }
-            else
-                clearDecisionResume(targetDir);
-        }
-        catch (error) {
-            const reason = `could not persist trusted decision resume state: ${error.message}`;
-            reporter.blocked(reason);
-            return 1;
-        }
+        const resumeCode = reconcileDecisionResume();
+        if (resumeCode !== undefined)
+            return resumeCode;
         // In json mode stdout belongs to the NDJSON stream — route the narrative summary to stderr.
         const say = opts.json ? (line) => console.error(line) : (line) => console.log(line);
         say(`Loop ${result.status} after ${result.iterations} iteration(s): ${result.finalProgress.passed}/${result.finalProgress.total} stories pass`);

package/dist/loop/runner.js

@@ -1,12 +1,13 @@
 import { isAcceptanceCriterion } from './prd.js';
 import { execFileSync, execSync } from 'node:child_process';
-import { existsSync, mkdirSync, rmSync } from 'node:fs';
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
 import { join } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { loadContext, formatForPrompt, contextDir } from '../context/context.js';
-import { buildProviderInvocation } from '../agents/providers.js';
-import { parseProviderTelemetry } from '../agents/telemetry.js';
-import { formatReviewContract, readReviewVerdict, reviewVerdictPath } from '../review/verdict.js';
+import { buildProviderInvocation, startProviderProcess } from '../agents/providers.js';
+import { parseProviderResult, parseProviderTelemetry } from '../agents/telemetry.js';
+import { formatReviewContract, formatReviewStdoutContract, parseReviewVerdict } from '../review/verdict.js';
 export function contextBlockFor(targetDir) {
     return formatForPrompt(loadContext(contextDir(targetDir)));
 }
@@ -40,7 +41,7 @@ export function buildClaudePrompt(story, context, onAmbiguity = 'resolve', perfC
     lines.push('- Keep your final message to a few short sentences: what changed and what you verified.');
     return lines.join('\n');
 }
-export function buildReviewPrompt(story, context, verdictPath) {
+export function buildReviewPrompt(story, context, verdictPath, provider) {
     const criteria = formatAcceptance(story);
     const lines = [
         'You are an independent reviewer inside the Yoke loop. You did NOT implement this change.',
@@ -51,11 +52,10 @@ export function buildReviewPrompt(story, context, verdictPath) {
     lines.push('', `Story ${story.id}: ${story.title}`, 'Acceptance criteria:', criteria, '', 'Approve ONLY if every acceptance criterion is met and the change is sound.', 'If you find ANY blocking issue (an unmet criterion, a bug, a missing test), reject.', 'Base your verdict only on what the diff and test runs actually show — never assume unverified behavior.', verdictPath
         ? 'Do not modify project source, tests, configuration, or generated artifacts. The verdict file named below is the only permitted write. Do not commit.'
         : 'Do not modify files. Do not commit.', 'Keep your verdict to a few short sentences.');
-    if (verdictPath)
-        lines.push('', formatReviewContract(verdictPath));
+    lines.push('', verdictPath ? formatReviewContract(verdictPath, provider) : formatReviewStdoutContract(provider ?? 'claude'));
     return lines.join('\n');
 }
-export function buildStandaloneReviewPrompt(scope, focus, verdictPath) {
+export function buildStandaloneReviewPrompt(scope, focus, verdictPath, provider) {
     const lines = [
         'You are an independent reviewer. You did NOT write this change.',
         `Review ${scope}. Run git yourself to see the diff (e.g. \`git diff\`, or \`git diff <base>..HEAD\`).`,
@@ -66,8 +66,7 @@ export function buildStandaloneReviewPrompt(scope, focus, verdictPath) {
     lines.push('', 'Approve by exiting 0 ONLY if the change is sound and complete.', 'If you find ANY blocking issue, exit non-zero to reject and explain what is wrong.', 'Base your verdict only on what the diff and test runs actually show — never assume unverified behavior.', verdictPath
         ? 'Do not modify project source, tests, configuration, or generated artifacts. The verdict file named below is the only permitted write. Do not commit.'
         : 'Do not modify files. Do not commit.', 'Keep your verdict to a few short sentences.');
-    if (verdictPath)
-        lines.push('', formatReviewContract(verdictPath));
+    lines.push('', verdictPath ? formatReviewContract(verdictPath, provider) : formatReviewStdoutContract(provider ?? 'claude'));
     return lines.join('\n');
 }
 // Headless agents must run non-interactively: with plain `-p` the CLI denies
@@ -150,9 +149,13 @@ export function parseClaudeStreamUsage(lines) {
     const usage = result ?? { inputTokens: assistantIn, outputTokens: assistantOut };
     return model ? { ...usage, model } : usage;
 }
-function watchdogPath() {
-    // runner.js and watchdog.js sit side by side (dist/loop/ at runtime, src/loop/ under tsx)
-    return fileURLToPath(new URL('./watchdog.js', import.meta.url));
+function watchdogArgs() {
+    const compiled = fileURLToPath(new URL('./watchdog.js', import.meta.url));
+    if (existsSync(compiled))
+        return [compiled];
+    const source = fileURLToPath(new URL('./watchdog.ts', import.meta.url));
+    const tsxLoader = pathToFileURL(createRequire(import.meta.url).resolve('tsx')).href;
+    return ['--import', tsxLoader, source];
 }
 // When idleTimeoutMs > 0, run the agent THROUGH the watchdog so a silent hang is
 // killed after idleTimeoutMs of no output. The prompt still flows via stdin.
@@ -161,14 +164,14 @@ function watchdogPath() {
 // killing by process-name/command-line pattern takes down other projects'
 // runners too. (Plain repos, e.g. `yoke review` outside a yoke project, get
 // no pid file rather than a littered .yoke dir.)
-export function buildWatchdogInvocation(inv, idleTimeoutMs) {
+export function buildWatchdogInvocation(inv, idleTimeoutMs, ownershipRoot = inv.cwd) {
     if (idleTimeoutMs <= 0)
         return inv;
-    const yokeDir = join(inv.cwd, '.yoke');
+    const yokeDir = join(ownershipRoot, '.yoke');
     const pidArgs = existsSync(yokeDir) ? [`--pid-file=${join(yokeDir, 'runner.pid')}`] : [];
     return {
         command: 'node',
-        args: [watchdogPath(), `--idle-ms=${idleTimeoutMs}`, ...pidArgs, '--', inv.command, ...inv.args],
+        args: [...watchdogArgs(), `--idle-ms=${idleTimeoutMs}`, ...pidArgs, '--', inv.command, ...inv.args],
         input: inv.input,
         cwd: inv.cwd,
     };
@@ -187,7 +190,7 @@ export function win32CommandString(command, args) {
     return [command, ...args].map(q).join(' ');
 }
 function runCli(inv) {
-    if (process.platform === 'win32') {
+    if (process.platform === 'win32' && !/\.(?:exe|com)$/iu.test(inv.command) && inv.command !== process.execPath && inv.command !== 'node') {
         execSync(win32CommandString(inv.command, inv.args), {
             cwd: inv.cwd,
             input: inv.input,
@@ -208,7 +211,7 @@ function runCli(inv) {
 // through it. Throws on a non-zero exit; the error carries the partial stdout.
 function runCliCapture(inv) {
     const opts = { cwd: inv.cwd, input: inv.input, stdio: ['pipe', 'pipe', 'inherit'], encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 };
-    return process.platform === 'win32'
+    return process.platform === 'win32' && !/\.(?:exe|com)$/iu.test(inv.command) && inv.command !== process.execPath && inv.command !== 'node'
         ? execSync(win32CommandString(inv.command, inv.args), opts)
         : execFileSync(inv.command, inv.args, opts);
 }
@@ -225,7 +228,7 @@ function runReviewCli(inv) {
         encoding: 'utf8',
         maxBuffer: 64 * 1024 * 1024,
     };
-    if (process.platform === 'win32')
+    if (process.platform === 'win32' && !/\.(?:exe|com)$/iu.test(inv.command) && inv.command !== process.execPath && inv.command !== 'node')
         execSync(win32CommandString(inv.command, inv.args), opts);
     else
         execFileSync(inv.command, inv.args, opts);
@@ -296,6 +299,9 @@ export function runReviewAgent(inv) {
         return { success: false, summary: processFailureSummary(error) };
     }
 }
+export function makeAsyncRunner(agent, opts = {}) {
+    return (ctx) => startProviderProcess(agent, runnerInvocation(agent, buildClaudePrompt(ctx.story, contextBlockFor(ctx.targetDir), opts.onAmbiguity, opts.perfCommand), ctx.targetDir, true, opts.permissions ?? 'safe', opts.selection), opts.process);
+}
 export function makeRunner(agent, idleTimeoutMs = 0, opts = {}) {
     // Claude always streams (see runnerInvocation) — capture the stream so tokens are
     // always reported; other agents keep inherit stdio. opts.tokenReport is now
@@ -331,33 +337,62 @@ export function makeRunner(agent, idleTimeoutMs = 0, opts = {}) {
     };
 }
 export const claudeRunner = makeRunner('claude');
-export function makeReviewRunner(agent, idleTimeoutMs = 0, exec = runReviewCli) {
+export function makeReviewRunner(agent, idleTimeoutMs = 0, exec) {
     return (ctx) => {
-        const verdictPath = reviewVerdictPath(ctx.targetDir);
-        mkdirSync(join(ctx.targetDir, '.yoke'), { recursive: true });
-        rmSync(verdictPath, { force: true });
-        const base = agentInvocation(agent, buildReviewPrompt(ctx.story, contextBlockFor(ctx.targetDir), verdictPath), ctx.targetDir, 'safe');
+        const before = repositoryFingerprint(ctx.targetDir);
+        const base = agentInvocation(agent, buildReviewPrompt(ctx.story, contextBlockFor(ctx.targetDir), undefined, agent), ctx.targetDir, 'read-only');
         const inv = buildWatchdogInvocation(base, idleTimeoutMs);
         let processFailure;
+        let actualModel;
+        let output = '';
         try {
-            exec(inv);
+            const result = exec?.(inv) ?? runCapturedAgent(agent, inv);
+            if (!result.success)
+                processFailure = result.summary;
+            actualModel = result.tokens?.model;
+            output = result.output;
+            if (!exec && !actualModel && !processFailure)
+                processFailure = 'review provider did not report its model';
         }
         catch (e) {
             processFailure = processFailureSummary(e);
         }
         try {
-            const verdict = readReviewVerdict(verdictPath);
-            if (processFailure)
-                return { success: false, summary: `review process failed: ${processFailure}; verdict: ${verdict.summary}` };
+            if (repositoryFingerprint(ctx.targetDir) !== before)
+                throw new Error('reviewer modified the repository during a read-only review');
+            const expected = { provider: agent, ...(actualModel ? { model: actualModel } : {}) };
+            const verdict = parseReviewVerdict(parseProviderResult(agent, output), expected);
+            if (processFailure) {
+                return {
+                    success: false,
+                    summary: `review process failed: ${processFailure}; verdict: ${verdict.summary}`,
+                    reviewOutcome: { kind: 'infrastructure', summary: processFailure },
+                };
+            }
             return verdict.approved
-                ? { success: true, summary: `${agent} approved ${ctx.story.id}: ${verdict.summary}` }
-                : { success: false, summary: `${agent} rejected ${ctx.story.id}: ${verdict.summary}` };
+                ? reviewResult(agent, ctx.story.id, verdict, { kind: 'approved', verdict })
+                : reviewResult(agent, ctx.story.id, verdict, { kind: 'rejected', verdict });
         }
         catch (e) {
-            return { success: false, summary: `${processFailure ? `review process failed: ${processFailure}; ` : ''}${e.message}` };
+            const summary = `${processFailure ? `review process failed: ${processFailure}; ` : ''}${e.message}`;
+            return { success: false, summary, reviewOutcome: processFailure ? { kind: 'infrastructure', summary } : { kind: 'malformed', summary } };
         }
     };
 }
+export function repositoryFingerprint(targetDir) {
+    try {
+        return execFileSync('git', ['diff', '--binary', 'HEAD'], { cwd: targetDir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] })
+            + execFileSync('git', ['status', '--porcelain=v1', '-z'], { cwd: targetDir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+    }
+    catch {
+        return '';
+    }
+}
+function reviewResult(agent, storyId, verdict, reviewOutcome) {
+    return verdict.approved
+        ? { success: true, summary: `${agent} approved ${storyId}: ${verdict.summary}`, reviewOutcome }
+        : { success: false, summary: `${agent} rejected ${storyId}: ${verdict.summary}`, reviewOutcome };
+}
 // Probe whether the agent's CLI is on PATH (so the loop can refuse upfront with a
 // clear message instead of failing mid-run with spawn ENOENT). Never throws.
 export function isAgentAvailable(agent) {

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();
     });
 }