@hecer/yoke 1.3.0 → 1.5.0

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/verify.js

@@ -1,26 +1,80 @@
 import { execSync } from 'node:child_process';
-// Runs a shell command in the target dir; passed = exit 0. execSync goes through the
-// shell, so `npm test` resolves npm.cmd on Windows. Output is captured (not streamed).
-export function commandVerifier(command) {
+import { compactCommandOutput } from '../output/compact.js';
+import { writeOutputArtifact } from '../output/artifact.js';
+import { DEFAULT_OUTPUT_POLICY } from '../output/types.js';
+function outputText(value) {
+    if (Buffer.isBuffer(value))
+        return value.toString('utf8');
+    return typeof value === 'string' ? value : '';
+}
+function labelledOutput(stdout, stderr) {
+    const sections = [];
+    if (stdout)
+        sections.push(`=== stdout ===\n${stdout}`);
+    if (stderr)
+        sections.push(`=== stderr ===\n${stderr}`);
+    return sections.join(stdout.endsWith('\n') ? '' : '\n');
+}
+function errorMessage(error) {
+    return (error instanceof Error ? error.message : String(error))
+        .replace(/[\u0000-\u001F\u007F]/gu, ' ')
+        .slice(0, 240);
+}
+const COMMAND_CAPTURE_BYTES = 16 * 1024 * 1024;
+// Runs a shell command in the target dir; passed = exit 0. The explicit capture quota
+// avoids Node's 1 MiB default without allowing noisy commands to consume unbounded memory.
+export function commandVerifier(command, options = {}) {
     return (targetDir) => {
+        const phase = options.phase ?? 'verify';
         try {
-            execSync(command, { cwd: targetDir, stdio: 'pipe', timeout: 600_000 });
-            return { passed: true, summary: `verify passed: ${command}` };
+            execSync(command, {
+                cwd: targetDir,
+                stdio: 'pipe',
+                timeout: options.timeoutMs ?? 600_000,
+                maxBuffer: COMMAND_CAPTURE_BYTES,
+            });
+            return { passed: true, summary: `${phase} passed: ${command}` };
         }
         catch (e) {
             const err = e;
-            const out = (err.stderr?.toString('utf8') ?? '') || (err.stdout?.toString('utf8') ?? '');
-            const tail = out.trim().split('\n').slice(-5).join('\n');
-            const suffix = err.signal === 'SIGTERM' ? ' (timed out)' : (tail ? `\n${tail}` : '');
-            return { passed: false, summary: `verify failed: ${command}${suffix}` };
+            const captureExceeded = err.code === 'ENOBUFS';
+            const captured = labelledOutput(outputText(err.stdout), outputText(err.stderr));
+            const captureNotice = `[output truncated: exceeded ${COMMAND_CAPTURE_BYTES}-byte per-stream capture limit]`;
+            const raw = captureExceeded
+                ? `${captured}${captured ? '\n' : ''}=== capture ===\n${captureNotice}`
+                : captured;
+            const policy = options.policy ?? DEFAULT_OUTPUT_POLICY;
+            const compacted = compactCommandOutput(raw, { previewBytes: policy.previewBytes });
+            const timedOut = !captureExceeded && (err.signal === 'SIGTERM' || err.code === 'ETIMEDOUT');
+            const qualifier = captureExceeded
+                ? ' (capture limit exceeded)'
+                : timedOut ? ' (timed out)' : '';
+            const parts = [`${phase} failed: ${command}${qualifier}`];
+            if (compacted.preview)
+                parts.push(compacted.preview);
+            if (compacted.originalBytes > policy.artifactThresholdBytes) {
+                try {
+                    const artifact = (options.artifactWriter ?? writeOutputArtifact)(targetDir, raw, {
+                        phase,
+                        storyId: process.env.YOKE_STORY,
+                    });
+                    parts.push(captureExceeded
+                        ? artifact.marker.replace('[full output:', '[truncated output:')
+                        : artifact.marker);
+                }
+                catch (error) {
+                    parts.push(`[artifact unavailable: ${errorMessage(error)}]`);
+                }
+            }
+            return { passed: false, summary: parts.join('\n') };
         }
     };
 }
 /** Execute the proof commands attached to one acceptance criterion. */
-export function commandsVerifier(commands) {
+export function commandsVerifier(commands, options = {}) {
     return (targetDir) => {
         for (const command of commands) {
-            const result = commandVerifier(command)(targetDir);
+            const result = commandVerifier(command, options)(targetDir);
             if (!result.passed)
                 return result;
         }

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