@hecer/yoke 0.2.0 → 0.7.0

package/dist/loop/runner.js

@@ -1,4 +1,6 @@
 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) {
@@ -12,7 +14,7 @@ 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.', '- 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 +25,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 +36,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 +59,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 +181,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 +220,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)), 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

@@ -13,6 +13,8 @@ export const YokeConfigSchema = z.object({
     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,8 @@ export const YOKE_IGNORE_LINES = [
     '.yoke/loop-status.json',
     '.yoke/loop.log',
     '.yoke/loop.lock',
+    '.yoke/loop.pause',
+    '.yoke/runner.pid',
     '.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`;
+}

package/dist/update/check.js

@@ -0,0 +1,86 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+export const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+// Machine-global (not per-project): one cache under the user's home dir.
+export function cachePath() {
+    return join(homedir(), '.yoke', 'update-check.json');
+}
+export function readCache(file = cachePath()) {
+    if (!existsSync(file))
+        return null;
+    try {
+        const raw = JSON.parse(readFileSync(file, 'utf8'));
+        if (typeof raw.checkedAt === 'string' && typeof raw.latest === 'string') {
+            return { checkedAt: raw.checkedAt, latest: raw.latest };
+        }
+    }
+    catch { /* malformed — treat as absent */ }
+    return null;
+}
+export function writeCache(cache, file = cachePath()) {
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify(cache));
+}
+// Strict numeric triple compare; prerelease suffixes are stripped (a prerelease
+// of the same triple is not "newer"). Malformed input is never newer.
+export function isNewer(candidate, current) {
+    const triple = (v) => {
+        const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v.trim());
+        return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+    };
+    const a = triple(candidate);
+    const b = triple(current);
+    if (!a || !b)
+        return false;
+    for (let i = 0; i < 3; i++) {
+        if (a[i] !== b[i])
+            return a[i] > b[i];
+    }
+    return false;
+}
+export function isStale(cache, now) {
+    if (!cache)
+        return true;
+    const t = Date.parse(cache.checkedAt);
+    if (!Number.isFinite(t))
+        return true;
+    return now.getTime() - t > CHECK_INTERVAL_MS;
+}
+export function currentYokeVersion() {
+    // src/update/ and dist/update/ both sit two levels below the package root.
+    const pkg = JSON.parse(readFileSync(fileURLToPath(new URL('../../package.json', import.meta.url)), 'utf8'));
+    return pkg.version;
+}
+function spawnDetachedRefresh() {
+    const refresh = fileURLToPath(new URL('./refresh.js', import.meta.url));
+    try {
+        spawn(process.execPath, [refresh], { detached: true, stdio: 'ignore' }).unref();
+    }
+    catch { /* best-effort — next invocation retries */ }
+}
+// Print (to stderr) a one-line hint when a newer version is cached; kick off a
+// detached cache refresh when stale. Silent in CI, --json runs, non-TTY pipes,
+// and under YOKE_NO_UPDATE_CHECK=1. Never throws, never blocks.
+export function maybeNotifyUpdate(currentVersion, opts = {}) {
+    const env = opts.env ?? process.env;
+    if (env.YOKE_NO_UPDATE_CHECK || env.CI)
+        return;
+    const argv = opts.argv ?? process.argv;
+    if (argv.includes('--json'))
+        return;
+    const tty = opts.tty ?? process.stderr.isTTY === true;
+    if (!tty)
+        return;
+    const cache = readCache(opts.cacheFile);
+    if (isStale(cache, opts.now ?? new Date())) {
+        (opts.spawnRefresh ?? spawnDetachedRefresh)();
+        return;
+    }
+    if (cache && isNewer(cache.latest, currentVersion)) {
+        const print = opts.print ?? ((m) => console.error(m));
+        print(`yoke ${currentVersion} → ${cache.latest} available — run: yoke upgrade   (disable this check: YOKE_NO_UPDATE_CHECK=1)`);
+    }
+}

package/dist/update/refresh.js

@@ -0,0 +1,28 @@
+import { pathToFileURL } from 'node:url';
+import { writeCache } from './check.js';
+// Detached background refresher (spawned by maybeNotifyUpdate when the cache
+// is stale): one small registry request, write the cache, exit. Failures are
+// silent by design — the notifier simply retries on a later invocation.
+const REGISTRY_LATEST = 'https://registry.npmjs.org/@hecer%2fyoke/latest';
+export async function refreshOnce(opts = {}) {
+    const fetchFn = opts.fetchFn ?? fetch;
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), opts.timeoutMs ?? 5000);
+    try {
+        const res = await fetchFn(REGISTRY_LATEST, { signal: ctrl.signal });
+        if (!res.ok)
+            return;
+        const body = await res.json();
+        if (typeof body.version === 'string') {
+            writeCache({ checkedAt: (opts.now ?? new Date()).toISOString(), latest: body.version }, opts.cacheFile);
+        }
+    }
+    catch { /* offline / blocked / registry down — silent */ }
+    finally {
+        clearTimeout(timer);
+    }
+}
+const isMain = process.argv[1] ? pathToFileURL(process.argv[1]).href === import.meta.url : false;
+if (isMain) {
+    refreshOnce().then(() => process.exit(0));
+}

package/dist/update/upgrade.js

@@ -0,0 +1,30 @@
+import { execSync } from 'node:child_process';
+import { readCache, isNewer, currentYokeVersion } from './check.js';
+// `yoke upgrade` — the explicit path to the latest release.
+export function runUpgrade(opts = {}) {
+    const exec = opts.exec ?? ((cmd) => { execSync(cmd, { stdio: 'inherit' }); });
+    console.log('Upgrading @hecer/yoke to latest...');
+    try {
+        exec('npm install -g @hecer/yoke@latest');
+    }
+    catch (e) {
+        console.error(`Upgrade failed: ${e.message}`);
+        console.error('Running from a git clone? Upgrade with: git pull && npm install && npm run build');
+        return 1;
+    }
+    console.log('✓ upgraded — the new version is active on the next yoke invocation.');
+    return 0;
+}
+// Opt-in auto-upgrade (`update.auto: true` in .yoke/config.yaml), evaluated at
+// loop START only — never mid-run: the current process keeps executing the
+// version it started with; the upgrade takes effect on the next invocation.
+export function maybeAutoUpgrade(auto, opts = {}) {
+    if (auto !== true)
+        return;
+    const cache = readCache(opts.cacheFile);
+    const current = currentYokeVersion();
+    if (cache && isNewer(cache.latest, current)) {
+        console.error(`update.auto: upgrading yoke ${current} → ${cache.latest} (this run continues on ${current}; the upgrade applies from the next run)`);
+        runUpgrade(opts);
+    }
+}