@hecer/yoke 0.2.0

package/dist/loop/loop.js

@@ -0,0 +1,190 @@
+import { join, relative } from 'node:path';
+import { loadPrd, savePrd, selectNextStory, allPass, progress } from './prd.js';
+import { stopTheLineGate, preDispatchGate } from './gates.js';
+import { appendDecision, contextDir } from '../context/context.js';
+import { noopReporter } from './reporter.js';
+function blockReason(base, targetDir, git) {
+    let dirty = false;
+    try {
+        dirty = !git.isClean(targetDir);
+    }
+    catch { /* ignore */ }
+    return dirty
+        ? `${base} (working tree has uncommitted changes from the blocked story — review/clean before re-running)`
+        : base;
+}
+export function runLoop(opts) {
+    let iterations = 0;
+    const reporter = opts.reporter ?? noopReporter;
+    const initial = loadPrd(opts.prdPath);
+    if (initial.length === 0) {
+        reporter.blocked('PRD has no stories');
+        return { status: 'blocked', iterations: 0, reason: 'PRD has no stories', finalProgress: { passed: 0, total: 0 } };
+    }
+    for (;;) {
+        const stories = loadPrd(opts.prdPath);
+        if (allPass(stories)) {
+            reporter.complete(progress(stories));
+            return { status: 'complete', iterations, finalProgress: progress(stories) };
+        }
+        if (iterations >= opts.maxIterations) {
+            reporter.capReached(progress(stories));
+            return { status: 'cap-reached', iterations, finalProgress: progress(stories) };
+        }
+        const pre = preDispatchGate(opts.targetDir, opts.git);
+        if (!pre.ok) {
+            reporter.blocked(pre.reason ?? 'pre-dispatch gate failed');
+            return { status: 'blocked', iterations, reason: pre.reason, finalProgress: progress(stories) };
+        }
+        const story = selectNextStory(stories);
+        if (!story) {
+            reporter.complete(progress(stories));
+            return { status: 'complete', iterations, finalProgress: progress(stories) };
+        }
+        const stl = stopTheLineGate(story);
+        if (!stl.ok) {
+            reporter.blocked(stl.reason ?? 'stop-the-line gate failed');
+            return { status: 'blocked', iterations, reason: stl.reason, finalProgress: progress(stories) };
+        }
+        reporter.storyStart({ id: story.id, title: story.title }, iterations + 1, progress(stories));
+        if (opts.isolate) {
+            const wt = join(opts.targetDir, '.yoke', 'worktrees', story.id);
+            const wtPrd = join(wt, relative(opts.targetDir, opts.prdPath));
+            try {
+                opts.git.addWorktree(opts.targetDir, wt);
+                const result = opts.runner({ targetDir: wt, story });
+                iterations++;
+                // Verify is the source of truth — NOT the runner's exit code. A spurious non-zero
+                // exit (e.g. a Windows .cmd wrapper ghost) must not block a story whose tests are green.
+                reporter.phase('verifying');
+                const prevStory = process.env.YOKE_STORY;
+                process.env.YOKE_STORY = story.id;
+                let verdict;
+                try {
+                    verdict = opts.verify(wt);
+                }
+                finally {
+                    if (prevStory === undefined)
+                        delete process.env.YOKE_STORY;
+                    else
+                        process.env.YOKE_STORY = prevStory;
+                }
+                if (!verdict.passed) {
+                    const base = result.success
+                        ? `story ${story.id} did not verify: ${verdict.summary}`
+                        : `story ${story.id} runner failed (${result.summary}) and verify is red: ${verdict.summary}`;
+                    const reason = blockReason(base, opts.targetDir, opts.git);
+                    reporter.blocked(reason);
+                    return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+                }
+                const summary = result.success
+                    ? result.summary
+                    : `${result.summary} (runner exited non-zero but verify is green)`;
+                if (opts.review) {
+                    reporter.phase('reviewing');
+                    const reviewResult = opts.review({ targetDir: wt, story });
+                    if (!reviewResult.success) {
+                        const reason = blockReason(`story ${story.id} rejected in review: ${reviewResult.summary}`, opts.targetDir, opts.git);
+                        reporter.blocked(reason);
+                        return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+                    }
+                }
+                // The worktree is a checkout of committed HEAD, so the agent above reads
+                // context from HEAD's .yoke/context — commit context changes for --isolate
+                // to honour them. We write the decision here so `integrate` carries it back.
+                reporter.phase('committing');
+                appendDecision(contextDir(wt), {
+                    storyId: story.id,
+                    title: story.title,
+                    summary,
+                });
+                const updated = stories.map(s => (s.id === story.id ? { ...s, passes: true } : s));
+                savePrd(wtPrd, updated);
+                opts.git.commitAll(wt, `yoke: complete ${story.id} ${story.title}`);
+                opts.git.integrate(opts.targetDir, wt);
+            }
+            catch (e) {
+                const reason = blockReason(`isolated iteration failed for ${story.id}: ${e.message}`, opts.targetDir, opts.git);
+                reporter.blocked(reason);
+                return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+            }
+            finally {
+                try {
+                    opts.git.removeWorktree(opts.targetDir, wt);
+                }
+                catch { /* cleanup is best-effort */ }
+            }
+            continue;
+        }
+        const result = opts.runner({ targetDir: opts.targetDir, story });
+        iterations++;
+        // Verify is the source of truth — NOT the runner's exit code. A spurious non-zero
+        // exit (e.g. a Windows .cmd wrapper ghost) must not block a story whose tests are green.
+        reporter.phase('verifying');
+        const prevStory = process.env.YOKE_STORY;
+        process.env.YOKE_STORY = story.id;
+        let verdict;
+        try {
+            verdict = opts.verify(opts.targetDir);
+        }
+        finally {
+            if (prevStory === undefined)
+                delete process.env.YOKE_STORY;
+            else
+                process.env.YOKE_STORY = prevStory;
+        }
+        if (!verdict.passed) {
+            const base = result.success
+                ? `story ${story.id} did not verify: ${verdict.summary}`
+                : `story ${story.id} runner failed (${result.summary}) and verify is red: ${verdict.summary}`;
+            const reason = blockReason(base, opts.targetDir, opts.git);
+            reporter.blocked(reason);
+            return {
+                status: 'blocked',
+                iterations,
+                reason,
+                finalProgress: progress(stories),
+            };
+        }
+        const summary = result.success
+            ? result.summary
+            : `${result.summary} (runner exited non-zero but verify is green)`;
+        if (opts.review) {
+            reporter.phase('reviewing');
+            const reviewResult = opts.review({ targetDir: opts.targetDir, story });
+            if (!reviewResult.success) {
+                const reason = blockReason(`story ${story.id} rejected in review: ${reviewResult.summary}`, opts.targetDir, opts.git);
+                reporter.blocked(reason);
+                return {
+                    status: 'blocked',
+                    iterations,
+                    reason,
+                    finalProgress: progress(stories),
+                };
+            }
+        }
+        reporter.phase('committing');
+        const dec = appendDecision(contextDir(opts.targetDir), {
+            storyId: story.id,
+            title: story.title,
+            summary,
+        });
+        const updated = stories.map(s => (s.id === story.id ? { ...s, passes: true } : s));
+        savePrd(opts.prdPath, updated);
+        try {
+            opts.git.commitAll(opts.targetDir, `yoke: complete ${story.id} ${story.title}`);
+        }
+        catch (e) {
+            savePrd(opts.prdPath, stories); // revert — never persist passes:true without a commit
+            dec.rollback(); // and never leave an orphan decision
+            const reason = blockReason(`commit failed for ${story.id}: ${e.message}`, opts.targetDir, opts.git);
+            reporter.blocked(reason);
+            return {
+                status: 'blocked',
+                iterations,
+                reason,
+                finalProgress: progress(stories),
+            };
+        }
+    }
+}

package/dist/loop/prd.js

@@ -0,0 +1,29 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { parse, stringify } from 'yaml';
+import { z } from 'zod';
+export const StorySchema = z.object({
+    id: z.string().min(1),
+    title: z.string().min(1),
+    priority: z.number(),
+    acceptance: z.array(z.string().min(1)),
+    passes: z.boolean(),
+});
+const PrdSchema = z.array(StorySchema);
+export function loadPrd(file) {
+    return PrdSchema.parse(parse(readFileSync(file, 'utf8')));
+}
+export function savePrd(file, stories) {
+    writeFileSync(file, stringify(stories));
+}
+export function selectNextStory(stories) {
+    const open = stories.filter(s => !s.passes);
+    if (open.length === 0)
+        return null;
+    return open.reduce((best, s) => (s.priority < best.priority ? s : best));
+}
+export function allPass(stories) {
+    return stories.length > 0 && stories.every(s => s.passes);
+}
+export function progress(stories) {
+    return { passed: stories.filter(s => s.passes).length, total: stories.length };
+}

package/dist/loop/reporter.js

@@ -0,0 +1,91 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync, appendFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+export const LOG_CAP_BYTES = 256 * 1024;
+// Append a line to .yoke/loop.log, keeping the file bounded: once it exceeds
+// capBytes, truncate to the recent tail (starting at a line boundary) so the log
+// can never grow without bound across many loop runs.
+export function appendLog(dir, line, capBytes = LOG_CAP_BYTES) {
+    const file = join(dir, '.yoke', 'loop.log');
+    mkdirSync(join(dir, '.yoke'), { recursive: true });
+    appendFileSync(file, line + '\n');
+    let size;
+    try {
+        size = statSync(file).size;
+    }
+    catch {
+        return;
+    }
+    if (size <= capBytes)
+        return;
+    const content = readFileSync(file, 'utf8');
+    const tail = content.slice(content.length - Math.floor(capBytes / 2));
+    const nl = tail.indexOf('\n');
+    const trimmed = nl >= 0 ? tail.slice(nl + 1) : tail;
+    writeFileSync(file, `# … loop.log truncated …\n${trimmed}`);
+}
+function statusPath(dir) {
+    return join(dir, '.yoke', 'loop-status.json');
+}
+export function writeStatus(dir, status) {
+    const file = statusPath(dir);
+    mkdirSync(join(dir, '.yoke'), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(status, null, 2));
+    renameSync(tmp, file);
+}
+export function readStatus(dir) {
+    const file = statusPath(dir);
+    if (!existsSync(file))
+        return null;
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function makeReporter(dir, opts = {}, now = () => new Date()) {
+    const sink = opts.log ?? ((line) => process.stdout.write(line + '\n'));
+    const emitConsole = (line) => { if (!opts.quiet)
+        sink(line); };
+    let current = null;
+    const persist = (next, logLabel, consoleLine) => {
+        current = next;
+        try {
+            writeStatus(dir, next);
+            appendLog(dir, `${next.updatedAt}  ${logLabel}  ${next.story ?? '-'}  ${next.reason ?? ''}`.trimEnd());
+        }
+        catch { /* observability must never abort the loop */ }
+        emitConsole(consoleLine);
+    };
+    return {
+        storyStart(story, iteration, progress) {
+            const ts = now().toISOString();
+            persist({ state: 'running', phase: 'implementing', story: story.id, storyTitle: story.title,
+                iteration, progress, startedAt: ts, updatedAt: ts }, 'implementing', `▶ ${story.id} (${progress.passed}/${progress.total}) — implementing…`);
+        },
+        phase(phase) {
+            if (!current)
+                return;
+            persist({ ...current, phase, updatedAt: now().toISOString() }, phase, `  · ${phase}…`);
+        },
+        blocked(reason) {
+            const base = current ?? emptyStatus(now().toISOString());
+            persist({ ...base, state: 'blocked', reason, updatedAt: now().toISOString() }, 'blocked', `■ blocked on ${base.story ?? '?'}: ${reason}`);
+        },
+        complete(progress) {
+            persist({ ...(current ?? emptyStatus(now().toISOString())), state: 'complete', phase: undefined,
+                progress, reason: undefined, updatedAt: now().toISOString() }, 'complete', `✔ loop complete — ${progress.passed}/${progress.total}`);
+        },
+        capReached(progress) {
+            persist({ ...(current ?? emptyStatus(now().toISOString())), state: 'cap-reached', phase: undefined,
+                progress, updatedAt: now().toISOString() }, 'cap-reached', `◾ iteration cap reached — ${progress.passed}/${progress.total}`);
+        },
+    };
+}
+function emptyStatus(ts) {
+    return { state: 'running', iteration: 0, progress: { passed: 0, total: 0 }, startedAt: ts, updatedAt: ts };
+}
+export const noopReporter = {
+    storyStart() { }, phase() { }, blocked() { }, complete() { }, capReached() { },
+};

package/dist/loop/run-command.js

@@ -0,0 +1,134 @@
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { loadConfig, saveConfig, defaultConfig, resolveVerifyCommand } from '../retrofit/config.js';
+import { loadPrd, progress } from './prd.js';
+import { runLoop } from './loop.js';
+import { realGitOps } from './git.js';
+import { makeRunner, makeReviewRunner, isAgentAvailable } from './runner.js';
+import { commandVerifier, retryingVerifier } from './verify.js';
+import { readStatus, makeReporter } from './reporter.js';
+import { acquireLock, releaseLock } from './lock.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) {
+    const ms = Math.max(0, now.getTime() - Date.parse(fromIso));
+    const s = Math.floor(ms / 1000);
+    if (s < 60)
+        return `${s}s ago`;
+    const m = Math.floor(s / 60);
+    if (m < 60)
+        return `${m}m ago`;
+    const h = Math.floor(m / 60);
+    if (h < 24)
+        return `${h}h ago`;
+    return `${Math.floor(h / 24)}d ago`;
+}
+export function prdPath(targetDir) {
+    return join(targetDir, '.yoke', 'prd.yaml');
+}
+export function setLoopEnabled(targetDir, enabled) {
+    // TODO(C2): resolve bundled canon version instead of placeholder
+    const config = loadConfig(targetDir) ?? defaultConfig('0.0.0');
+    config.loop = { enabled };
+    saveConfig(targetDir, config);
+}
+export function loopStatus(targetDir, now = () => new Date()) {
+    const config = loadConfig(targetDir);
+    const enabled = config?.loop.enabled ?? false;
+    const path = prdPath(targetDir);
+    let prog = 'no PRD';
+    if (existsSync(path)) {
+        const p = progress(loadPrd(path));
+        prog = `${p.passed}/${p.total} stories pass`;
+    }
+    const st = readStatus(targetDir);
+    if (!st)
+        return `Loop: ${enabled ? 'enabled' : 'disabled'}\nPRD: ${prog}`;
+    const head = `Loop: ${st.state.toUpperCase()}${st.story ? ` on ${st.story}${st.storyTitle ? ` "${st.storyTitle}"` : ''}` : ''}`;
+    const meta = [st.phase, `iteration ${st.iteration}`, `${st.progress.passed}/${st.progress.total}`, `updated ${relativeTime(st.updatedAt, now())}`]
+        .filter(Boolean).join(' · ');
+    const lines = [head, `  ${meta}`];
+    if (st.reason)
+        lines.push(`  reason: ${st.reason}`);
+    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())}`);
+    }
+    return lines.join('\n');
+}
+export function resolveIdleMs(flagMinutes, configMinutes) {
+    const minutes = flagMinutes ?? configMinutes ?? DEFAULT_IDLE_MINUTES;
+    return minutes > 0 ? minutes * 60_000 : 0;
+}
+export function runLoopCommand(targetDir, opts) {
+    const config = loadConfig(targetDir);
+    if (!config?.loop.enabled) {
+        console.error('Loop is disabled. Enable it with: yoke loop on');
+        return 2;
+    }
+    const path = prdPath(targetDir);
+    if (!existsSync(path)) {
+        console.error(`No PRD found at ${path}. Create one (see canon loop/prd.schema.md).`);
+        return 2;
+    }
+    let verify = opts.verify;
+    if (!verify) {
+        const command = resolveVerifyCommand(targetDir, config);
+        if (!command) {
+            console.error('No verify command configured. Set verify.command in .yoke/config.yaml (e.g. "npm test") so the loop can confirm tests pass before marking work done.');
+            return 2;
+        }
+        verify = retryingVerifier(commandVerifier(command), config.verify?.retries ?? 1);
+    }
+    const available = opts.isAvailable ?? isAgentAvailable;
+    const runnerAgent = opts.agent ?? config.agents[0] ?? 'claude';
+    const idleMs = resolveIdleMs(opts.timeoutMinutes, config.loop.timeoutMinutes);
+    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>.`);
+            return 2;
+        }
+        runner = makeRunner(runnerAgent, idleMs);
+    }
+    let review = opts.reviewRunner;
+    if (!review && (opts.review || opts.reviewer)) {
+        const reviewerAgent = opts.reviewer ?? runnerAgent;
+        if (!available(reviewerAgent)) {
+            console.error(`Reviewer agent CLI "${reviewerAgent}" was not found on PATH. Install it, or pick another with --reviewer=<claude|codex|gemini>.`);
+            return 2;
+        }
+        review = makeReviewRunner(reviewerAgent, idleMs);
+    }
+    const lock = acquireLock(targetDir);
+    if (!lock.acquired) {
+        console.error(`Another loop is already running here (pid ${lock.holderPid}). If that is wrong, run: yoke loop cleanup`);
+        return 2;
+    }
+    if (lock.stalePid !== undefined) {
+        console.warn(`Took over a stale loop lock (pid ${lock.stalePid} is gone).`);
+    }
+    try {
+        const result = runLoop({
+            prdPath: path,
+            targetDir,
+            runner,
+            git: opts.git ?? realGitOps,
+            verify,
+            maxIterations: opts.maxIterations,
+            isolate: opts.isolate ?? false,
+            review,
+            reporter: opts.reporter ?? makeReporter(targetDir),
+        });
+        console.log(`Loop ${result.status} after ${result.iterations} iteration(s): ${result.finalProgress.passed}/${result.finalProgress.total} stories pass`);
+        if (result.reason)
+            console.log(`Reason: ${result.reason}`);
+        if (result.reason && /api key|please run \/login|not logged in/i.test(result.reason)) {
+            console.log('Hint: the agent CLI has no credentials in this environment. Set ANTHROPIC_API_KEY or log the agent in for headless use.');
+        }
+        return result.status === 'complete' ? 0 : 1;
+    }
+    finally {
+        releaseLock(targetDir);
+    }
+}

package/dist/loop/runner.js

@@ -0,0 +1,157 @@
+import { execFileSync, execSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { loadContext, formatForPrompt, contextDir } from '../context/context.js';
+export function contextBlockFor(targetDir) {
+    return formatForPrompt(loadContext(contextDir(targetDir)));
+}
+export function buildClaudePrompt(story, context) {
+    const criteria = story.acceptance.map(a => `- ${a}`).join('\n');
+    const lines = [
+        'You are an autonomous coding agent running inside the Yoke loop.',
+        'Implement ONLY this story and nothing else. Follow test-driven development.',
+    ];
+    if (context)
+        lines.push('', context);
+    lines.push('', `Story ${story.id}: ${story.title}`, 'Acceptance criteria (Definition of Done):', criteria, '', "When done, ensure the project's full test suite passes.", 'Do NOT commit — the loop commits on your behalf after verifying.');
+    return lines.join('\n');
+}
+export function buildReviewPrompt(story, context) {
+    const criteria = story.acceptance.map(a => `- ${a}`).join('\n');
+    const lines = [
+        'You are an independent reviewer inside the Yoke loop. You did NOT implement this change.',
+        'Review the current uncommitted working-tree changes against the story below.',
+    ];
+    if (context)
+        lines.push('', context);
+    lines.push('', `Story ${story.id}: ${story.title}`, 'Acceptance criteria:', criteria, '', 'Approve by exiting 0 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), exit non-zero to reject.', 'Do not modify files. Do not commit.');
+    return lines.join('\n');
+}
+export function buildStandaloneReviewPrompt(scope, focus) {
+    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\`).`,
+        'Judge it for correctness, unmet intent, missing tests, and obvious bug or security risks.',
+    ];
+    if (focus)
+        lines.push(`Pay particular attention to: ${focus}.`);
+    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.', 'Do not modify files. Do not commit.');
+    return lines.join('\n');
+}
+const AGENT_SPECS = {
+    claude: { command: 'claude', baseArgs: ['-p'] },
+    codex: { command: 'codex', baseArgs: ['exec'] },
+    gemini: { command: 'gemini', baseArgs: ['-p'] },
+};
+export function agentInvocation(agent, prompt, cwd) {
+    const spec = AGENT_SPECS[agent];
+    return { command: spec.command, args: spec.baseArgs, input: prompt, cwd };
+}
+export function claudeInvocation(prompt, cwd) {
+    return agentInvocation('claude', prompt, cwd);
+}
+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));
+}
+// 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.
+export function buildWatchdogInvocation(inv, idleTimeoutMs) {
+    if (idleTimeoutMs <= 0)
+        return inv;
+    return {
+        command: 'node',
+        args: [watchdogPath(), `--idle-ms=${idleTimeoutMs}`, '--', inv.command, ...inv.args],
+        input: inv.input,
+        cwd: inv.cwd,
+    };
+}
+// Execute a CLI invocation. On Windows the agent CLIs are `.cmd` shims that
+// execFileSync cannot resolve without a shell; but passing an args array with
+// shell:true triggers DEP0190. So on win32 we run a single command string via
+// execSync (our args are literal flags, never user data — the prompt is piped via
+// stdin), which avoids the warning. On other platforms execFileSync with no shell
+// is already warning-free. Throws on a non-zero exit (caller catches).
+// Build a win32 command string, quoting only args that contain whitespace.
+// Existing agent flags (claude -p, codex exec) have no spaces, so they are
+// unchanged; an absolute watchdog path with spaces gets quoted.
+export function win32CommandString(command, args) {
+    const q = (s) => (/\s/.test(s) ? `"${s}"` : s);
+    return [command, ...args].map(q).join(' ');
+}
+function runCli(inv) {
+    if (process.platform === 'win32') {
+        execSync(win32CommandString(inv.command, inv.args), {
+            cwd: inv.cwd,
+            input: inv.input,
+            stdio: ['pipe', 'inherit', 'inherit'],
+        });
+    }
+    else {
+        execFileSync(inv.command, inv.args, {
+            cwd: inv.cwd,
+            input: inv.input,
+            stdio: ['pipe', 'inherit', 'inherit'],
+        });
+    }
+}
+// Probe whether a CLI is on PATH via `<command> --version`. Same win32/other split
+// as runCli to stay DEP0190-free. Never throws.
+function probeVersion(command) {
+    try {
+        if (process.platform === 'win32') {
+            execSync(`${command} --version`, { stdio: 'pipe', timeout: 5000 });
+        }
+        else {
+            execFileSync(command, ['--version'], { stdio: 'pipe', timeout: 5000 });
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// Reusable one-shot invocation runner for callers outside the loop (e.g. `yoke review`).
+// Mirrors makeRunner's try/catch: success=true when the CLI exits 0, false when it throws.
+export function runAgent(inv) {
+    try {
+        runCli(inv);
+        return { success: true, summary: 'exited 0' };
+    }
+    catch (e) {
+        return { success: false, summary: e.message };
+    }
+}
+export function makeRunner(agent, idleTimeoutMs = 0) {
+    return (ctx) => {
+        const base = agentInvocation(agent, buildClaudePrompt(ctx.story, contextBlockFor(ctx.targetDir)), ctx.targetDir);
+        const inv = buildWatchdogInvocation(base, idleTimeoutMs);
+        try {
+            // NOTE: the loop trusts the agent's exit code as a proxy for "it ran".
+            // Independent verification happens in the loop (Baustein C2), not here.
+            runCli(inv);
+            return { success: true, summary: `${agent} implemented ${ctx.story.id}` };
+        }
+        catch (e) {
+            return { success: false, summary: `${agent} failed on ${ctx.story.id}: ${e.message}` };
+        }
+    };
+}
+export const claudeRunner = makeRunner('claude');
+export function makeReviewRunner(agent, idleTimeoutMs = 0) {
+    return (ctx) => {
+        const base = agentInvocation(agent, buildReviewPrompt(ctx.story, contextBlockFor(ctx.targetDir)), ctx.targetDir);
+        const inv = buildWatchdogInvocation(base, idleTimeoutMs);
+        try {
+            runCli(inv);
+            return { success: true, summary: `${agent} approved ${ctx.story.id}` };
+        }
+        catch (e) {
+            return { success: false, summary: `${agent} rejected ${ctx.story.id}: ${e.message}` };
+        }
+    };
+}
+// 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) {
+    return probeVersion(AGENT_SPECS[agent].command);
+}

package/dist/loop/verify.js

@@ -0,0 +1,38 @@
+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) {
+    return (targetDir) => {
+        try {
+            execSync(command, { cwd: targetDir, stdio: 'pipe', timeout: 600_000 });
+            return { passed: true, summary: `verify 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}` };
+        }
+    };
+}
+// Re-run a failing verifier up to `retries` times; the first pass wins. Lets a
+// transient flake (e.g. a load-induced async timeout) self-heal while a real
+// failure still fails (it stays red across every attempt).
+export function retryingVerifier(inner, retries) {
+    return (targetDir) => {
+        let last = inner(targetDir);
+        let attempt = 0;
+        while (!last.passed && attempt < retries) {
+            attempt++;
+            last = inner(targetDir);
+        }
+        if (last.passed && attempt > 0) {
+            return { passed: true, summary: `${last.summary} (passed on retry ${attempt})` };
+        }
+        if (!last.passed && attempt > 0) {
+            return { passed: false, summary: `${last.summary} (still failing after ${attempt} retr${attempt === 1 ? 'y' : 'ies'})` };
+        }
+        return last;
+    };
+}