@hecer/yoke 0.2.0 → 0.8.0

package/dist/loop/run-command.js

@@ -6,8 +6,9 @@ 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 { readStatus, makeReporter, fmtDuration } from './reporter.js';
 import { acquireLock, releaseLock } from './lock.js';
+import { maybeAutoUpgrade } from '../update/upgrade.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) {
@@ -45,9 +46,13 @@ export function loopStatus(targetDir, now = () => new Date()) {
     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())}`]
+    const pct = st.percent !== undefined ? ` (${st.percent}%)` : '';
+    const meta = [st.phase, `iteration ${st.iteration}`, `${st.progress.passed}/${st.progress.total}${pct}`, `updated ${relativeTime(st.updatedAt, now())}`]
         .filter(Boolean).join(' · ');
     const lines = [head, `  ${meta}`];
+    if (st.state === 'running' && st.eta && st.eta.remainingStories > 0) {
+        lines.push(`  ~${fmtDuration(st.eta.etaMs)} remaining (Ø ${fmtDuration(st.eta.avgStoryMs)}/story)`);
+    }
     if (st.reason)
         lines.push(`  reason: ${st.reason}`);
     const ageMs = now().getTime() - Date.parse(st.updatedAt);
@@ -80,6 +85,9 @@ export function runLoopCommand(targetDir, opts) {
         }
         verify = retryingVerifier(commandVerifier(command), config.verify?.retries ?? 1);
     }
+    // Opt-in self-update, loop START only — this run keeps executing the version
+    // it started with; a fetched upgrade applies from the next invocation.
+    maybeAutoUpgrade(config.update?.auto);
     const available = opts.isAvailable ?? isAgentAvailable;
     const runnerAgent = opts.agent ?? config.agents[0] ?? 'claude';
     const idleMs = resolveIdleMs(opts.timeoutMinutes, config.loop.timeoutMinutes);
@@ -89,7 +97,9 @@ export function runLoopCommand(targetDir, opts) {
             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);
+        // 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.
+        runner = makeRunner(runnerAgent, idleMs, { tokenReport: opts.json === true, onAmbiguity: opts.onAmbiguity ?? config.loop.onAmbiguity });
     }
     let review = opts.reviewRunner;
     if (!review && (opts.review || opts.reviewer)) {
@@ -118,15 +128,22 @@ export function runLoopCommand(targetDir, opts) {
             maxIterations: opts.maxIterations,
             isolate: opts.isolate ?? false,
             review,
-            reporter: opts.reporter ?? makeReporter(targetDir),
+            reporter: opts.reporter ?? makeReporter(targetDir, { json: opts.json }),
         });
-        console.log(`Loop ${result.status} after ${result.iterations} iteration(s): ${result.finalProgress.passed}/${result.finalProgress.total} stories pass`);
+        // 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`);
         if (result.reason)
-            console.log(`Reason: ${result.reason}`);
+            say(`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.');
+            say('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;
+        // Exit codes: 0 complete · 1 blocked/cap-reached · 2 config error (handled above) · 3 paused (loop.pause consumed at a story boundary)
+        if (result.status === 'complete')
+            return 0;
+        if (result.status === 'paused')
+            return 3;
+        return 1;
     }
     finally {
         releaseLock(targetDir);

package/dist/loop/runner.js

@@ -1,10 +1,12 @@
 import { execFileSync, execSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
 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) {
+export function buildClaudePrompt(story, context, onAmbiguity = 'resolve') {
     const criteria = story.acceptance.map(a => `- ${a}`).join('\n');
     const lines = [
         'You are an autonomous coding agent running inside the Yoke loop.',
@@ -12,7 +14,9 @@ export function buildClaudePrompt(story, context) {
     ];
     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.');
+    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.', '', 'Working rules:', '- Add nothing beyond what the story requires: no extra features, abstractions, comments, or defensive code for cases that cannot happen.', '- Do not create summary, plan, or analysis documents — only files the story itself needs.', '- If a check fails, fix the root cause; never bypass it (e.g. --no-verify) or pass by weakening tests.', '- Report the outcome faithfully: if a criterion is unmet or tests fail, say so plainly instead of claiming success.', '- Never ask questions or wait for input — you run unattended and nobody can answer.', onAmbiguity === 'abort'
+        ? '- If an acceptance criterion is genuinely undecidable, do NOT guess: write the open question(s) to .yoke/ambiguity.md, change nothing else, and stop.'
+        : '- If an acceptance criterion is ambiguous, resolve it yourself in the way most consistent with the other criteria and the existing code, and state your interpretation in your final message.', '- Keep your final message to a few short sentences: what changed and what you verified.');
     return lines.join('\n');
 }
 export function buildReviewPrompt(story, context) {
@@ -23,7 +27,7 @@ export function buildReviewPrompt(story, context) {
     ];
     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.');
+    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.', 'Base your verdict only on what the diff and test runs actually show — never assume unverified behavior.', 'Do not modify files. Do not commit.', 'Keep your verdict to a few short sentences.');
     return lines.join('\n');
 }
 export function buildStandaloneReviewPrompt(scope, focus) {
@@ -34,13 +38,21 @@ export function buildStandaloneReviewPrompt(scope, focus) {
     ];
     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.');
+    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.', 'Do not modify files. Do not commit.', 'Keep your verdict to a few short sentences.');
     return lines.join('\n');
 }
+// Headless agents must run non-interactively: with plain `-p` the CLI denies
+// every file-write/permission prompt, so the implementer "runs" (exit 0) but
+// produces NOTHING. The loop then sees a clean tree + green pre-existing tests
+// and falsely marks the story done. Granting autonomous permissions makes the
+// implementer actually able to write files and run the verify command.
+// (The loop is opt-in and scoped to the target project dir.)
 const AGENT_SPECS = {
-    claude: { command: 'claude', baseArgs: ['-p'] },
-    codex: { command: 'codex', baseArgs: ['exec'] },
-    gemini: { command: 'gemini', baseArgs: ['-p'] },
+    claude: { command: 'claude', baseArgs: ['-p', '--dangerously-skip-permissions'] },
+    codex: { command: 'codex', baseArgs: ['exec', '--dangerously-bypass-approvals-and-sandbox'] },
+    // gemini: no `-p` — current Gemini CLI (0.33+) requires a value after -p, and
+    // piped (non-TTY) stdin already selects headless mode on its own.
+    gemini: { command: 'gemini', baseArgs: ['--yolo'] },
 };
 export function agentInvocation(agent, prompt, cwd) {
     const spec = AGENT_SPECS[agent];
@@ -49,18 +61,95 @@ export function agentInvocation(agent, prompt, cwd) {
 export function claudeInvocation(prompt, cwd) {
     return agentInvocation('claude', prompt, cwd);
 }
+// Token-reporting variant: stream-json makes claude emit per-message usage on stdout
+// (--verbose is required by the CLI for stream-json in -p mode). Prompt still via stdin.
+// Derived from the base spec so the headless permission-bypass flag rides along.
+export function claudeStreamJsonInvocation(prompt, cwd) {
+    return { command: 'claude', args: [...AGENT_SPECS.claude.baseArgs, '--output-format', 'stream-json', '--verbose'], input: prompt, cwd };
+}
+// Pick the runner invocation. Claude ALWAYS runs in stream-json mode: plain `-p`
+// prints nothing until the run finishes, so the idle watchdog saw a healthy
+// long story as a dead process and killed it at exactly the idle window — and
+// the user saw dead air the whole time. stream-json emits per-message output,
+// which doubles as liveness. Token usage rides along for free. Other agents
+// keep their plain invocation (no machine-readable stream to gain).
+export function runnerInvocation(agent, prompt, cwd, _tokenReport = false) {
+    if (agent === 'claude')
+        return claudeStreamJsonInvocation(prompt, cwd);
+    return agentInvocation(agent, prompt, cwd);
+}
+// Parse claude stream-json output into cumulative token usage. Defensive by design:
+// non-JSON lines and unknown message shapes are ignored. The final "result" message
+// carries the run's cumulative usage — prefer it (last one wins); if it is absent
+// (e.g. the process died mid-run), fall back to summing assistant-message usage.
+// Also tracks the model id: the "system"/"init" message and "assistant" messages both
+// carry a model field — the LAST one seen across the stream wins; absent if none did.
+export function parseClaudeStreamUsage(lines) {
+    const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : 0);
+    const usageOf = (v) => {
+        if (typeof v !== 'object' || v === null)
+            return null;
+        const u = v;
+        if (u.input_tokens === undefined && u.output_tokens === undefined)
+            return null;
+        return { input: num(u.input_tokens), output: num(u.output_tokens) };
+    };
+    const modelOf = (v) => (typeof v === 'string' && v.length > 0 ? v : undefined);
+    let assistantIn = 0;
+    let assistantOut = 0;
+    let result;
+    let model;
+    for (const line of lines) {
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (typeof msg !== 'object' || msg === null || Array.isArray(msg))
+            continue;
+        const m = msg;
+        if (m.type === 'result') {
+            const u = usageOf(m.usage);
+            if (u)
+                result = { inputTokens: u.input, outputTokens: u.output };
+        }
+        else if (m.type === 'assistant') {
+            const message = m.message;
+            const u = usageOf(message?.usage);
+            if (u) {
+                assistantIn += u.input;
+                assistantOut += u.output;
+            }
+            model = modelOf(message?.model) ?? model;
+        }
+        else if (m.type === 'system' && m.subtype === 'init') {
+            model = modelOf(m.model) ?? model;
+        }
+    }
+    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));
 }
 // 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.
+// If the run dir has a .yoke dir, the watchdog also records its pids in
+// .yoke/runner.pid so `yoke loop cleanup` can reap orphans PROJECT-SCOPED —
+// 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) {
     if (idleTimeoutMs <= 0)
         return inv;
+    const yokeDir = join(inv.cwd, '.yoke');
+    const pidArgs = existsSync(yokeDir) ? [`--pid-file=${join(yokeDir, 'runner.pid')}`] : [];
     return {
         command: 'node',
-        args: [watchdogPath(), `--idle-ms=${idleTimeoutMs}`, '--', inv.command, ...inv.args],
+        args: [watchdogPath(), `--idle-ms=${idleTimeoutMs}`, ...pidArgs, '--', inv.command, ...inv.args],
         input: inv.input,
         cwd: inv.cwd,
     };
@@ -94,15 +183,27 @@ function runCli(inv) {
         });
     }
 }
+// Like runCli, but with stdout PIPED and returned (stderr stays inherited) — for
+// token reporting, where the agent's stdout is a machine-readable stream-json feed.
+// The watchdog wrapper forwards the child's stdout to its own, so piping still works
+// 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'
+        ? execSync(win32CommandString(inv.command, inv.args), opts)
+        : execFileSync(inv.command, inv.args, opts);
+}
 // Probe whether a CLI is on PATH via `<command> --version`. Same win32/other split
-// as runCli to stay DEP0190-free. Never throws.
+// as runCli to stay DEP0190-free. Never throws. Timeout is generous because some
+// agent CLIs cold-start slowly (gemini needs ~6s on Windows; 5s misreported it
+// as "not installed").
 function probeVersion(command) {
     try {
         if (process.platform === 'win32') {
-            execSync(`${command} --version`, { stdio: 'pipe', timeout: 5000 });
+            execSync(`${command} --version`, { stdio: 'pipe', timeout: 20000 });
         }
         else {
-            execFileSync(command, ['--version'], { stdio: 'pipe', timeout: 5000 });
+            execFileSync(command, ['--version'], { stdio: 'pipe', timeout: 20000 });
         }
         return true;
     }
@@ -121,14 +222,32 @@ export function runAgent(inv) {
         return { success: false, summary: e.message };
     }
 }
-export function makeRunner(agent, idleTimeoutMs = 0) {
+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
+    // redundant for claude and meaningless elsewhere; kept for caller compatibility.
+    const captureTokens = agent === 'claude';
     return (ctx) => {
-        const base = agentInvocation(agent, buildClaudePrompt(ctx.story, contextBlockFor(ctx.targetDir)), ctx.targetDir);
+        const base = runnerInvocation(agent, buildClaudePrompt(ctx.story, contextBlockFor(ctx.targetDir), opts.onAmbiguity), ctx.targetDir, captureTokens);
         const inv = buildWatchdogInvocation(base, idleTimeoutMs);
+        if (captureTokens) {
+            const capture = opts.execCapture ?? runCliCapture;
+            try {
+                const out = capture(inv);
+                return { success: true, summary: `${agent} implemented ${ctx.story.id}`, tokens: parseClaudeStreamUsage(out.split(/\r?\n/)) };
+            }
+            catch (e) {
+                // Salvage usage from whatever the agent streamed before dying — those tokens were spent.
+                const partial = e.stdout;
+                const tokens = partial == null ? undefined : parseClaudeStreamUsage(String(partial).split(/\r?\n/));
+                return { success: false, summary: `${agent} failed on ${ctx.story.id}: ${e.message}`, tokens };
+            }
+        }
         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);
+            ;
+            (opts.exec ?? runCli)(inv);
             return { success: true, summary: `${agent} implemented ${ctx.story.id}` };
         }
         catch (e) {

package/dist/loop/watchdog.js

@@ -1,5 +1,31 @@
 import { spawn } from 'node:child_process';
+import { writeFileSync, rmSync } from 'node:fs';
 import { pathToFileURL } from 'node:url';
+// Kill one recorded process tree, platform-appropriately. Exported for
+// `yoke loop cleanup` (scoped reaping of recorded runner pids).
+export function killProcessTree(pid) {
+    if (process.platform === 'win32') {
+        try {
+            spawn('taskkill', ['/PID', String(pid), '/T', '/F'], { stdio: 'ignore' });
+        }
+        catch { /* best-effort */ }
+    }
+    else {
+        try {
+            process.kill(pid, 'SIGKILL');
+        }
+        catch { /* already gone */ }
+    }
+}
+// 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.
+function taskkillTree(pid, _force) {
+    try {
+        spawn('taskkill', ['/PID', String(pid), '/T', '/F'], { stdio: 'ignore' });
+    }
+    catch { /* best-effort */ }
+}
 export function runWatchdog(opts) {
     const spawnFn = opts.spawnFn ?? spawn;
     const out = opts.out ?? ((d) => process.stdout.write(d));
@@ -11,7 +37,36 @@ export function runWatchdog(opts) {
         }
         catch { /* no stdin */ }
     }
+    if (opts.pidFile && child.pid !== undefined) {
+        try {
+            writeFileSync(opts.pidFile, JSON.stringify({ watchdogPid: process.pid, childPid: child.pid, startedAt: new Date().toISOString() }));
+        }
+        catch { /* best-effort — cleanup falls back to worktree/lock handling */ }
+    }
+    const removePidFile = () => {
+        if (opts.pidFile) {
+            try {
+                rmSync(opts.pidFile, { force: true });
+            }
+            catch { /* best-effort */ }
+        }
+    };
     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);
+    // Terminate the child — via the tree-killer when we have one and a pid,
+    // otherwise per-process signals (POSIX default; SIGKILL is uncatchable).
+    const terminate = (child, force) => {
+        if (killTree && child.pid !== undefined) {
+            killTree(child.pid, force);
+            return;
+        }
+        try {
+            child.kill(force ? 'SIGKILL' : 'SIGTERM');
+        }
+        catch { /* already gone */ }
+    };
     return new Promise((resolve) => {
         let timer;
         let graceTimer;
@@ -41,28 +96,22 @@ export function runWatchdog(opts) {
             timer = setTimeout(() => {
                 timer = undefined;
                 killedForIdle = true;
-                try {
-                    child.kill('SIGTERM');
-                }
-                catch { /* already gone */ }
-                // Escalation: a child that catches/ignores SIGTERM would never emit
+                terminate(child, false);
+                // Escalation: a child that catches/ignores the soft kill would never emit
                 // 'close' and the promise would hang forever — defeating the watchdog.
-                // SIGKILL is uncatchable, so the child must close and we resolve.
-                // win32 limitation: with shell:true, SIGKILL on the shell may orphan
-                // grandchild processes (a resource-cleanup edge, not a hang) — not fixed here.
+                // POSIX: SIGKILL is uncatchable. win32: taskkill /T /F again as a retry —
+                // and crucially the TREE dies, not just the shell, so no orphaned agent
+                // keeps writing to the worktree or burning API tokens.
                 graceTimer = setTimeout(() => {
                     graceTimer = undefined;
-                    try {
-                        child.kill('SIGKILL');
-                    }
-                    catch { /* already gone */ }
+                    terminate(child, true);
                 }, graceMs);
             }, opts.idleMs);
         };
         child.stdout.on('data', (d) => { out(d); arm(); });
         child.stderr.on('data', (d) => { err(d); arm(); });
-        child.on('error', () => { clear(); resolve(127); });
-        child.on('close', (code) => { clear(); resolve(killedForIdle ? 124 : (code ?? 0)); });
+        child.on('error', () => { clear(); removePidFile(); resolve(127); });
+        child.on('close', (code) => { clear(); removePidFile(); resolve(killedForIdle ? 124 : (code ?? 0)); });
         arm();
     });
 }
@@ -72,15 +121,16 @@ export function parseWatchdogArgs(argv) {
     const rest = sep === -1 ? [] : argv.slice(sep + 1);
     const idleArg = flags.find((a) => a.startsWith('--idle-ms='));
     const idleMs = idleArg ? Number(idleArg.slice('--idle-ms='.length)) : 0;
+    const pidFile = flags.find((a) => a.startsWith('--pid-file='))?.slice('--pid-file='.length);
     const [command, ...args] = rest;
-    return { idleMs: Number.isFinite(idleMs) ? idleMs : 0, command: command ?? '', args };
+    return { idleMs: Number.isFinite(idleMs) ? idleMs : 0, command: command ?? '', args, ...(pidFile ? { pidFile } : {}) };
 }
 const isMain = process.argv[1] ? pathToFileURL(process.argv[1]).href === import.meta.url : false;
 if (isMain) {
-    const { idleMs, command, args } = parseWatchdogArgs(process.argv.slice(2));
+    const { idleMs, command, args, pidFile } = parseWatchdogArgs(process.argv.slice(2));
     if (!command) {
         process.stderr.write('watchdog: no command given\n');
         process.exit(2);
     }
-    runWatchdog({ command, args, idleMs, stdin: process.stdin }).then((code) => process.exit(code));
+    runWatchdog({ command, args, idleMs, stdin: process.stdin, pidFile }).then((code) => process.exit(code));
 }

package/dist/retrofit/apply.js

@@ -1,12 +1,15 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { mergeJson } from './merge-json.js';
+import { carryPreserved } from './preserve.js';
 export function applyActions(actions, targetDir, opts) {
     const results = [];
     for (const action of actions) {
         const dest = join(targetDir, action.target);
         let status;
         let backedUp;
+        let content = action.content;
+        let reason = action.reason;
         if (existsSync(dest)) {
             if (action.ifAbsent) {
                 results.push({ target: action.target, status: 'unchanged', reason: `${action.reason} (exists, left untouched)` });
@@ -34,7 +37,11 @@ export function applyActions(actions, targetDir, opts) {
                 results.push({ target: action.target, status: 'merged', backedUp, reason: action.reason });
                 continue;
             }
-            if (current === action.content) {
+            // Carry user content marked with yoke preserve markers into the new file.
+            content = carryPreserved(current, action.content);
+            if (content !== action.content)
+                reason = `${action.reason} (preserve block kept)`;
+            if (current === content) {
                 results.push({ target: action.target, status: 'unchanged', reason: action.reason });
                 continue;
             }
@@ -47,8 +54,8 @@ export function applyActions(actions, targetDir, opts) {
             status = 'created';
         }
         mkdirSync(dirname(dest), { recursive: true });
-        writeFileSync(dest, action.content);
-        results.push({ target: action.target, status, backedUp, reason: action.reason });
+        writeFileSync(dest, content);
+        results.push({ target: action.target, status, backedUp, reason });
     }
     return results;
 }

package/dist/retrofit/config.js

@@ -9,10 +9,18 @@ const SmokeSchema = z.object({ baseUrl: z.string().min(1), flows: z.array(SmokeF
 export const YokeConfigSchema = z.object({
     canonVersion: z.string().min(1),
     agents: z.array(AgentSchema),
-    loop: z.object({ enabled: z.boolean(), timeoutMinutes: z.number().optional() }),
+    loop: z.object({
+        enabled: z.boolean(),
+        timeoutMinutes: z.number().optional(),
+        // Ambiguous acceptance criteria: 'resolve' (default — agent decides and continues)
+        // or 'abort' (agent stops the story via .yoke/ambiguity.md for a human decision).
+        onAmbiguity: z.enum(['resolve', 'abort']).optional(),
+    }),
     verify: z.object({ command: z.string().min(1), retries: z.number().int().nonnegative().optional() }).optional(),
     codeGraph: CodeGraphSchema.optional(),
     smoke: SmokeSchema.optional(),
+    // Opt-in: upgrade yoke at loop START when a newer version is cached (never mid-run).
+    update: z.object({ auto: z.boolean() }).optional(),
 });
 export function defaultConfig(canonVersion) {
     return { canonVersion, agents: [], loop: { enabled: false } };

package/dist/retrofit/gitignore.js

@@ -6,6 +6,10 @@ export const YOKE_IGNORE_LINES = [
     '.yoke/loop-status.json',
     '.yoke/loop.log',
     '.yoke/loop.lock',
+    '.yoke/loop.pause',
+    '.yoke/runner.pid',
+    '.yoke/ambiguity.md',
+    '.yoke/story-durations.json',
     '.yoke/proof/',
 ];
 const HEADER = '# Yoke runtime artifacts (managed by yoke retrofit)';

package/dist/retrofit/planners/claude.js

@@ -4,6 +4,7 @@ import { loadManifest } from '../../canon/manifest.js';
 import { mcpServers, rtkInstruction } from '../tools.js';
 import { hasWsl } from '../wsl.js';
 import { detectGstack } from '../gstack.js';
+import { PRESERVE_SCAFFOLD } from '../preserve.js';
 const GSTACK_COMPOSE = `## Composed tools (gstack detected)
 
 This project also has [gstack](https://github.com/garrytan/gstack) installed. For capabilities Yoke does not ship, prefer gstack's skills:
@@ -17,7 +18,9 @@ const claudeMd = (rtkNote, composeNote) => `# Project Instructions
 This project uses the Yoke harness. Baseline instructions:
 
 @AGENTS.md
-${rtkNote ? `\n${rtkNote}\n` : ''}${composeNote ? `\n${composeNote}\n` : ''}`;
+${rtkNote ? `\n${rtkNote}\n` : ''}${composeNote ? `\n${composeNote}\n` : ''}
+${PRESERVE_SCAFFOLD}
+`;
 export function planClaude(canonDir, targetDir, wslAvailable = hasWsl(), codeGraph = 'graphify', gstackDetected = detectGstack(targetDir)) {
     const manifest = loadManifest(join(canonDir, 'manifest.yaml'));
     const actions = [];

package/dist/retrofit/planners/gemini.js

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 import { loadManifest } from '../../canon/manifest.js';
 import { parseFrontmatter } from '../../canon/frontmatter.js';
 import { mcpServers, rtkInstruction } from '../tools.js';
+import { PRESERVE_SCAFFOLD } from '../preserve.js';
 function tomlString(s) {
     return '"""\n' + s.replace(/\\/g, '\\\\').replace(/"""/g, '\\"\\"\\"') + '\n"""';
 }
@@ -14,7 +15,7 @@ export function planGemini(canonDir, _targetDir, codeGraph = 'graphify') {
     actions.push({
         kind: 'write',
         target: 'GEMINI.md',
-        content: `${baseline}\n${rtkInstruction()}\n`,
+        content: `${baseline}\n${rtkInstruction()}\n\n${PRESERVE_SCAFFOLD}\n`,
         reason: 'baseline + rtk instruction (no hook on Gemini)',
     });
     // One TOML slash command per skill.

package/dist/retrofit/preserve.js

@@ -0,0 +1,51 @@
+export const PRESERVE_START = '<!-- yoke:preserve:start -->';
+export const PRESERVE_END = '<!-- yoke:preserve:end -->';
+export const PRESERVE_SCAFFOLD = `${PRESERVE_START}
+<!-- Project-specific instructions go here. Yoke keeps this block across retrofits. -->
+${PRESERVE_END}`;
+/**
+ * Extract the inner content of every balanced preserve-marker pair, in order.
+ * An unbalanced start marker (no matching end) is ignored from that point on.
+ */
+export function extractPreserveBlocks(content) {
+    const blocks = [];
+    let idx = 0;
+    for (;;) {
+        const start = content.indexOf(PRESERVE_START, idx);
+        if (start === -1)
+            break;
+        const innerStart = start + PRESERVE_START.length;
+        const end = content.indexOf(PRESERVE_END, innerStart);
+        if (end === -1)
+            break;
+        blocks.push(content
+            .slice(innerStart, end)
+            .replace(/^\r?\n/, '')
+            .replace(/\r?\n[ \t]*$/, ''));
+        idx = end + PRESERVE_END.length;
+    }
+    return blocks;
+}
+/**
+ * Carry the preserve blocks of `current` (the file on disk) into `incoming`
+ * (the freshly generated content).
+ *
+ * - `current` has no blocks → `incoming` is returned unchanged.
+ * - `incoming` has a marker pair (the scaffold) → its inner is replaced with
+ *   the preserved content (multiple blocks joined by a blank line).
+ * - `incoming` has no markers → one preserved block is appended at the end.
+ */
+export function carryPreserved(current, incoming) {
+    const blocks = extractPreserveBlocks(current);
+    if (blocks.length === 0)
+        return incoming;
+    const inner = blocks.join('\n\n');
+    const start = incoming.indexOf(PRESERVE_START);
+    const end = start === -1 ? -1 : incoming.indexOf(PRESERVE_END, start + PRESERVE_START.length);
+    if (start !== -1 && end !== -1) {
+        return (incoming.slice(0, start + PRESERVE_START.length) +
+            '\n' + inner + '\n' +
+            incoming.slice(end));
+    }
+    return incoming.replace(/\n*$/, '\n\n') + `${PRESERVE_START}\n${inner}\n${PRESERVE_END}\n`;
+}