@hecer/yoke 0.2.0 → 0.8.0

package/bench/run.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+// Yoke benchmark harness.
+//
+//   node bench/run.mjs --runner=claude [--max=6] [--timeout=10] [--label=note]
+//
+// Copies the fixture into bench/.runs/<runner>-<stamp>, git-inits it, then drives
+// `yoke loop run --json` and measures from the OUTSIDE (the loop itself records no
+// durations): per-story wall-clock from NDJSON event timestamps, tokens/model from
+// the loop's token hook (claude runner only), and quality as the fixture's own
+// pre-written tests — run per story AFTER the loop finishes, on the final tree.
+import { spawn, spawnSync } from 'node:child_process'
+import { cpSync, mkdirSync, readFileSync, writeFileSync, readdirSync, statSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const benchDir = dirname(fileURLToPath(import.meta.url))
+const repoRoot = dirname(benchDir)
+const cli = join(repoRoot, 'dist', 'cli.js')
+
+const args = Object.fromEntries(
+  process.argv.slice(2).filter(a => a.startsWith('--')).map(a => {
+    const [k, v] = a.slice(2).split('=')
+    return [k, v ?? true]
+  }),
+)
+const runner = args.runner
+if (!['claude', 'codex', 'gemini'].includes(runner)) {
+  console.error('usage: node bench/run.mjs --runner=<claude|codex|gemini> [--max=6] [--timeout=10] [--label=note]')
+  process.exit(2)
+}
+const max = Number(args.max ?? 6)
+const timeout = Number(args.timeout ?? 10)
+
+const stamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19)
+const runDir = join(benchDir, '.runs', `${runner}-${stamp}`)
+mkdirSync(runDir, { recursive: true })
+cpSync(join(benchDir, 'fixtures', 'string-kit'), runDir, { recursive: true })
+
+const git = (...a) => {
+  const r = spawnSync('git', ['-C', runDir, ...a], { encoding: 'utf8' })
+  if (r.status !== 0) throw new Error(`git ${a.join(' ')} failed: ${r.stderr}`)
+}
+git('init', '-q')
+git('-c', 'user.name=bench', '-c', 'user.email=bench@yoke', 'add', '-A')
+git('-c', 'user.name=bench', '-c', 'user.email=bench@yoke', 'commit', '-q', '-m', 'bench: fixture baseline')
+
+// A nested Claude Code session refuses some operations; scrub session markers.
+const env = { ...process.env }
+for (const k of Object.keys(env)) if (k.startsWith('CLAUDE_CODE') || k === 'CLAUDECODE') delete env[k]
+
+console.error(`[bench] ${runner} → ${runDir}`)
+const t0 = Date.now()
+const events = []
+const child = spawn(process.execPath, [cli, 'loop', 'run', runDir, '--json', `--runner=${runner}`, `--max=${max}`, `--timeout=${timeout}`], {
+  env, stdio: ['ignore', 'pipe', 'inherit'],
+})
+let buf = ''
+child.stdout.on('data', d => {
+  buf += d
+  let i
+  while ((i = buf.indexOf('\n')) >= 0) {
+    const line = buf.slice(0, i).trim()
+    buf = buf.slice(i + 1)
+    if (!line) continue
+    try { events.push({ at: Date.now(), ...JSON.parse(line) }) } catch { /* non-JSON noise */ }
+  }
+})
+const exitCode = await new Promise(res => child.on('close', res))
+const wallClockMs = Date.now() - t0
+
+// Per-story duration: first event mentioning the story -> first event mentioning the next story (or end).
+const storyIds = ['STORY-1', 'STORY-2', 'STORY-3']
+const firstSeen = {}
+for (const e of events) if (e.story && !(e.story in firstSeen)) firstSeen[e.story] = e.at
+const stories = storyIds.map((id, idx) => {
+  const start = firstSeen[id]
+  const next = storyIds.slice(idx + 1).map(n => firstSeen[n]).find(v => v !== undefined)
+  const durationMs = start === undefined ? null : (next ?? t0 + wallClockMs) - start
+  const iterations = new Set(events.filter(e => e.story === id).map(e => e.iteration)).size
+  // Quality: the fixture's own tests for this story, on the final tree.
+  const q = spawnSync(process.execPath, ['--test', `tests/${id}.test.mjs`], { cwd: runDir, encoding: 'utf8' })
+  return { id, durationMs, iterations, finalTestsPass: q.status === 0 }
+})
+
+const last = events[events.length - 1] ?? {}
+let status = {}
+try { status = JSON.parse(readFileSync(join(runDir, '.yoke', 'loop-status.json'), 'utf8')) } catch { /* loop may have refused before writing status */ }
+
+// Source size (LOC in src/) as a code-economy proxy.
+const loc = (dir) => readdirSync(dir).reduce((n, f) => {
+  const p = join(dir, f)
+  if (statSync(p).isDirectory()) return n + loc(p)
+  return n + readFileSync(p, 'utf8').split('\n').filter(l => l.trim() !== '').length
+}, 0)
+
+const result = {
+  runner,
+  label: args.label ?? null,
+  yokeVersion: JSON.parse(readFileSync(join(repoRoot, 'package.json'), 'utf8')).version,
+  fixture: 'string-kit',
+  startedAt: new Date(t0).toISOString(),
+  wallClockMs,
+  exitCode,
+  finalState: last.state ?? null,
+  progress: last.progress ?? null,
+  tokens: status.tokens ?? null, // claude runner only; gemini/codex report none (documented gap)
+  stories,
+  srcLoc: loc(join(runDir, 'src')),
+}
+
+mkdirSync(join(benchDir, 'results'), { recursive: true })
+const out = join(benchDir, 'results', `${runner}-${stamp}.json`)
+writeFileSync(out, JSON.stringify(result, null, 2) + '\n')
+console.error(`[bench] done: ${out}`)
+console.log(JSON.stringify(result, null, 2))

package/canon/loop/loop-spec.md

@@ -10,6 +10,8 @@ Pass `--isolate` to run each iteration in a fresh git worktree: the agent works
 
 Pass `--review` (or `--reviewer=<claude|codex|gemini>` for a different agent) to add a role-separated review step: after the tests pass, an independent reviewer agent must approve the change before the story is committed and marked done. A rejection blocks the story (no commit). The reviewer is a fresh agent pass — the implementer never reviews its own work.
 
+Pass `--json` for machine mode: each status transition is emitted as one NDJSON line on stdout (the `.yoke/loop-status.json` shape, tagged `"type":"status"`) instead of the human narrative, so a supervisor can consume the stream instead of polling the file.
+
 When enabled and run, each iteration:
 
 1. Pre-dispatch gate: the git worktree must be clean, else `blocked`.
@@ -24,7 +26,9 @@ When enabled and run, each iteration:
    `passes: true`, committed atomically, and a decision logged. If verify fails: `blocked`.
 6. Stop when all stories `passes: true` (`complete`), or the iteration cap is reached (`cap-reached`).
 
-State lives outside the model context: the PRD file + git. The agent runner is pluggable.
+A supervisor can pause the loop by creating `.yoke/loop.pause`: at the next story boundary (before the next story is selected — the running story always finishes) the loop consumes the file, records `paused` in the status file and log, and exits with code `3`. Running `yoke loop run` again resumes.
+
+State lives outside the model context: the PRD file + git. The agent runner is pluggable. The PRD is re-read from disk at every story boundary, so stories appended to `.yoke/prd.yaml` mid-run are picked up at the next iteration without a restart.
 
 ## Limitations
 - The loop verifies via the project's test command and an optional agent review; it has no formal merge-queue or multi-reviewer quorum.

package/canon/manifest.yaml

@@ -45,3 +45,6 @@ tools:
   - { id: graphify, path: tools/graphify.md }
   - { id: playwright-mcp, path: tools/playwright-mcp.md }
   - { id: serena, path: tools/serena.md }
+  # optional companions (external installers; documented wiring only)
+  - { id: claude-mem, path: tools/claude-mem.md }
+  - { id: ui-ux-pro-max, path: tools/ui-ux-pro-max.md }

package/canon/skills/yoke-retrofit/SKILL.md

@@ -14,5 +14,6 @@ Set up (or update) the Yoke harness in the current project.
 2. Run `yoke retrofit . --agent=all --code-graph=<choice>` (or a subset of agents). Non-destructive — existing files are backed up under `.yoke/backup/` before any overwrite; `.claude/settings.json` is merged, not replaced. Generated per agent: Claude (`.claude/skills/`, `AGENTS.md`, `CLAUDE.md`, `.mcp.json`, rtk hook when WSL is available); Codex (`AGENTS.md`, `.codex/config.toml`, `RTK.md`); Gemini (`GEMINI.md`, `.gemini/commands/*.toml`, `.gemini/settings.json`).
 3. **Ask whether to enable the autonomous Loop** (default off). If yes, add `--loop`. Toggle any time with `yoke loop on|off`.
 4. Show the printed report (created/overwritten/unchanged/merged + detected agents) and where backups went. Note that the generated MCP launch commands may need adjusting to the user's local tool installs.
+5. **Preserve project content.** If the pre-retrofit `CLAUDE.md`/`GEMINI.md` had project-specific instructions (tech stack, workflow, `@`-includes), move them from the backup into the preserve block the generated file ships (`<!-- yoke:preserve:start -->` … `<!-- yoke:preserve:end -->`). Everything inside these markers survives every future `yoke retrofit` — in any yoke-written file; content outside them is replaced (but backed up).
 
 The harness includes a `minimal-code` skill (YAGNI / lazy-senior-dev) that nudges every agent to write the least code that solves the task — saving tokens and reducing maintenance.

package/canon/tools/claude-mem.md

@@ -0,0 +1,15 @@
+# Tool: claude-mem (persistent cross-session memory) — optional companion
+
+External install (not bundled): `npx claude-mem install` — https://github.com/thedotmack/claude-mem (Apache-2.0).
+Captures tool usage via lifecycle hooks, compresses it into SQLite + vector search, and injects
+relevant context into future sessions.
+
+Per-agent wiring:
+
+- **Claude Code:** first-class support — its installer registers the lifecycle hooks itself. Yoke does not duplicate that wiring; run the installer once per machine.
+- **Codex CLI / Gemini CLI:** supported by claude-mem's own multi-agent adapters; follow its docs.
+
+Interaction with the Yoke loop (deliberate boundary):
+
+- The loop's memory is **explicit and versioned**: `context/PROJECT.md`, `KNOWLEDGE.md`, `DECISIONS.md` plus the PRD. Every loop iteration starts from fresh context on purpose — reproducible, reviewable, in git.
+- claude-mem's automatic injection is **for interactive sessions**, not for loop runs. Do not enable its hooks inside a loop runner profile: injected memory is non-deterministic and bypasses the context files the gates rely on.

package/canon/tools/ui-ux-pro-max.md

@@ -0,0 +1,15 @@
+# Tool: ui-ux-pro-max (design intelligence) — optional companion
+
+External install (not bundled): `npm i -g ui-ux-pro-max-cli && uipro init --ai claude` —
+https://github.com/nextlevelbuilder/ui-ux-pro-max-skill (MIT).
+A data-driven design skill: UI styles, industry reasoning rules, palettes, font pairings,
+chart types, per-stack guidance. Its own installer targets Claude Code, Codex CLI, and
+Gemini CLI natively — run `uipro init` once per agent you use.
+
+Why it pairs with Yoke instead of being vendored:
+
+- **Division of labour:** ui-ux-pro-max makes the *generation* side better (what to build);
+  Yoke's `unslop-ui` skill, `yoke design-scan`, and `visual-verification` are the *verification*
+  side (prove it doesn't look AI-generated, prove it renders). Generate with pro-max, gate with Yoke.
+- **Not vendored on purpose:** it ships its own installer and update cadence; a copy frozen into
+  the canon would go stale. Install it directly and let `uipro update` keep it current.

package/dist/cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { pathToFileURL } from 'node:url';
+import { realpathSync } from 'node:fs';
 import { validateCanon } from './canon/validate.js';
 import { runRetrofit } from './retrofit/command.js';
 import { setLoopEnabled, loopStatus, runLoopCommand } from './loop/run-command.js';
@@ -10,6 +11,8 @@ import { runNew } from './new/command.js';
 import { runPrdDraft, runPrdCheck } from './prd/command.js';
 import { runLoopCleanup } from './loop/cleanup.js';
 import { runFlowSmoke } from './smoke/command.js';
+import { maybeNotifyUpdate, currentYokeVersion } from './update/check.js';
+import { runUpgrade } from './update/upgrade.js';
 export { runRetrofit } from './retrofit/command.js';
 export function runValidate(canonDir) {
     const issues = validateCanon(canonDir);
@@ -113,6 +116,7 @@ function main(argv) {
                     reviewer = reviewerArg;
                 }
                 const review = rest.includes('--review');
+                const json = rest.includes('--json');
                 const toArg = rest.find(a => a.startsWith('--timeout='));
                 let timeoutMinutes;
                 if (toArg) {
@@ -123,9 +127,14 @@ function main(argv) {
                     }
                     timeoutMinutes = v;
                 }
-                return runLoopCommand(targetDir, { maxIterations: rawMax, agent, isolate, reviewer, review, timeoutMinutes });
+                const oaArg = rest.find(a => a.startsWith('--on-ambiguity='))?.slice('--on-ambiguity='.length);
+                if (oaArg && oaArg !== 'resolve' && oaArg !== 'abort') {
+                    console.error(`Invalid --on-ambiguity value: ${oaArg} (expected resolve|abort)`);
+                    return 1;
+                }
+                return runLoopCommand(targetDir, { maxIterations: rawMax, agent, isolate, reviewer, review, timeoutMinutes, json, onAmbiguity: oaArg });
             }
-            console.log('usage: yoke loop <on|off|status|cleanup|run [--max=N] [--runner=<claude|codex|gemini>] [--reviewer=<claude|codex|gemini>] [--review] [--isolate] [--timeout=<minutes>]> [targetDir]');
+            console.log('usage: yoke loop <on|off|status|cleanup|run [--max=N] [--runner=<claude|codex|gemini>] [--reviewer=<claude|codex|gemini>] [--review] [--isolate] [--timeout=<minutes>] [--on-ambiguity=<resolve|abort>] [--json]> [targetDir]');
             return 1;
         }
         case 'new': {
@@ -233,12 +242,34 @@ function main(argv) {
             }
             return runDesignScan(targetDir, { max, report });
         }
+        case 'upgrade':
+            return runUpgrade();
         default:
-            console.log('usage: yoke <new <dir> [--idea="..."] | validate [canonDir] | retrofit [targetDir] [--agent=claude,codex,gemini|all] [--code-graph=graphify|serena] [--loop] | prd <draft|check> [dir] | loop <on|off|status|run|cleanup> | context <init|status> | review [dir] [--reviewer=<claude|codex|gemini>] [--base=<ref>] [--focus="..."] | design-scan [dir] [--max=N] [--report] | flow-smoke [dir] [--url=<baseUrl>] [--label=<name>]>');
+            console.log('usage: yoke <new <dir> [--idea="..."] | validate [canonDir] | retrofit [targetDir] [--agent=claude,codex,gemini|all] [--code-graph=graphify|serena] [--loop] | prd <draft|check> [dir] | loop <on|off|status|run|cleanup> | context <init|status> | review [dir] [--reviewer=<claude|codex|gemini>] [--base=<ref>] [--focus="..."] | design-scan [dir] [--max=N] [--report] | flow-smoke [dir] [--url=<baseUrl>] [--label=<name>] | upgrade>');
             return cmd ? 1 : 0;
     }
 }
-const isMain = process.argv[1] ? pathToFileURL(process.argv[1]).href === import.meta.url : false;
-if (isMain) {
-    process.exit(await main(process.argv.slice(2)));
+// Is this module the process entry point? Node realpaths the ESM entry for
+// import.meta.url but argv[1] keeps the path as typed — a globally npm-installed
+// CLI reaches this file THROUGH the node_modules/yoke symlink, so argv[1] must be
+// realpathed before comparing or the global binary silently exits without running.
+export function isMainEntry(argv1, moduleUrl) {
+    if (!argv1)
+        return false;
+    let resolved = argv1;
+    try {
+        resolved = realpathSync(argv1);
+    }
+    catch { /* nonexistent path — compare as given */ }
+    return pathToFileURL(resolved).href === moduleUrl;
+}
+if (isMainEntry(process.argv[1], import.meta.url)) {
+    const code = await main(process.argv.slice(2));
+    // Non-blocking version hint (npm/gh-style): reads a cache, maybe spawns a
+    // detached refresher. Never allowed to affect the command's outcome.
+    try {
+        maybeNotifyUpdate(currentYokeVersion());
+    }
+    catch { /* never fatal */ }
+    process.exit(code);
 }

package/dist/loop/cleanup.js

@@ -1,12 +1,53 @@
-import { existsSync, readdirSync, rmSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { lockPath, readLock, isPidAlive } from './lock.js';
-// Cleans ONLY yoke-created runtime artifacts: .yoke/worktrees/* and a stale loop.lock.
-// Never touches user-created worktrees or a lock whose holder is alive.
+import { killProcessTree } from './watchdog.js';
+// Reap orphaned runners PROJECT-SCOPED: kill only pids recorded in this project's
+// .yoke/runner.pid files (main dir + each worktree). Never by process-name or
+// command-line pattern — that takes down runners belonging to OTHER projects,
+// which then stall mid-story. Skipped entirely while the loop lock holder is
+// alive: a live loop's runner is healthy, not an orphan.
+function reapRecordedRunners(targetDir, wtDir, isAlive, killTree) {
+    const pidFiles = [join(targetDir, '.yoke', 'runner.pid')];
+    if (existsSync(wtDir)) {
+        for (const name of readdirSync(wtDir))
+            pidFiles.push(join(wtDir, name, '.yoke', 'runner.pid'));
+    }
+    let killed = 0;
+    for (const file of pidFiles) {
+        if (!existsSync(file))
+            continue;
+        try {
+            const rec = JSON.parse(readFileSync(file, 'utf8'));
+            // Child (agent tree) first, then the watchdog wrapper.
+            for (const pid of [rec.childPid, rec.watchdogPid]) {
+                if (typeof pid === 'number' && Number.isInteger(pid) && pid > 0 && isAlive(pid)) {
+                    killTree(pid);
+                    killed++;
+                }
+            }
+        }
+        catch { /* malformed record — still consume the file below */ }
+        rmSync(file, { force: true });
+    }
+    return killed;
+}
+// Cleans ONLY yoke-created runtime artifacts: recorded orphan runners,
+// .yoke/worktrees/*, and a stale loop.lock. Never touches user-created
+// worktrees, a lock whose holder is alive, or any process it did not record.
 export function runLoopCleanup(targetDir, opts = {}) {
     const git = opts.git ?? ((args, cwd) => { execFileSync('git', args, { cwd, stdio: 'pipe' }); });
+    const isAlive = opts.isAlive ?? isPidAlive;
+    const killTree = opts.killTree ?? killProcessTree;
     const wtDir = join(targetDir, '.yoke', 'worktrees');
+    const holder = readLock(targetDir);
+    const lockHeld = holder !== null && isPidAlive(holder.pid);
+    if (!lockHeld) {
+        const killed = reapRecordedRunners(targetDir, wtDir, isAlive, killTree);
+        if (killed > 0)
+            console.log(`Killed ${killed} orphaned runner process tree(s) recorded in runner.pid files.`);
+    }
     let removed = 0;
     let failed = 0;
     if (existsSync(wtDir)) {

package/dist/loop/loop.js

@@ -1,3 +1,4 @@
+import { existsSync, unlinkSync, readFileSync } from 'node:fs';
 import { join, relative } from 'node:path';
 import { loadPrd, savePrd, selectNextStory, allPass, progress } from './prd.js';
 import { stopTheLineGate, preDispatchGate } from './gates.js';
@@ -13,6 +14,34 @@ function blockReason(base, targetDir, git) {
         ? `${base} (working tree has uncommitted changes from the blocked story — review/clean before re-running)`
         : base;
 }
+// Control file a supervisor drops to pause the loop at the next story boundary.
+// The loop consumes (deletes) it and stops with state 'paused' — never mid-story.
+export function pauseFilePath(targetDir) {
+    return join(targetDir, '.yoke', 'loop.pause');
+}
+// Abort channel for an agent that hits genuinely undecidable acceptance criteria
+// (only instructed to use it under loop.onAmbiguity: abort). Honoured whenever
+// present: without this check, an agent that stopped without changes would sail
+// through verify on pre-existing green tests and be falsely marked done.
+export function ambiguityFilePath(dir) {
+    return join(dir, '.yoke', 'ambiguity.md');
+}
+function consumeAmbiguity(dir) {
+    const file = ambiguityFilePath(dir);
+    if (!existsSync(file))
+        return null;
+    let content = '';
+    try {
+        content = readFileSync(file, 'utf8');
+    }
+    catch { /* the signal alone still blocks */ }
+    try {
+        unlinkSync(file);
+    }
+    catch { /* best-effort consume */ }
+    const compact = content.replace(/\s+/g, ' ').trim().slice(0, 500);
+    return compact || 'agent reported ambiguous acceptance criteria without details';
+}
 export function runLoop(opts) {
     let iterations = 0;
     const reporter = opts.reporter ?? noopReporter;
@@ -31,6 +60,17 @@ export function runLoop(opts) {
             reporter.capReached(progress(stories));
             return { status: 'cap-reached', iterations, finalProgress: progress(stories) };
         }
+        // Story boundary: honour a pause signal before selecting the next story.
+        // complete/cap-reached above still win — pausing an already-finished loop is meaningless.
+        const pauseFile = pauseFilePath(opts.targetDir);
+        if (existsSync(pauseFile)) {
+            try {
+                unlinkSync(pauseFile);
+            }
+            catch { /* consumed best-effort — pausing still wins */ }
+            reporter.paused(progress(stories));
+            return { status: 'paused', iterations, finalProgress: progress(stories) };
+        }
         const pre = preDispatchGate(opts.targetDir, opts.git);
         if (!pre.ok) {
             reporter.blocked(pre.reason ?? 'pre-dispatch gate failed');
@@ -50,10 +90,19 @@ export function runLoop(opts) {
         if (opts.isolate) {
             const wt = join(opts.targetDir, '.yoke', 'worktrees', story.id);
             const wtPrd = join(wt, relative(opts.targetDir, opts.prdPath));
+            let landed = null;
             try {
                 opts.git.addWorktree(opts.targetDir, wt);
                 const result = opts.runner({ targetDir: wt, story });
                 iterations++;
+                if (result.tokens)
+                    reporter.addTokens(result.tokens);
+                const ambiguity = consumeAmbiguity(wt);
+                if (ambiguity) {
+                    const reason = `story ${story.id} stopped: ambiguous acceptance criteria — ${ambiguity}`;
+                    reporter.blocked(reason);
+                    return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+                }
                 // 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');
@@ -102,6 +151,7 @@ export function runLoop(opts) {
                 savePrd(wtPrd, updated);
                 opts.git.commitAll(wt, `yoke: complete ${story.id} ${story.title}`);
                 opts.git.integrate(opts.targetDir, wt);
+                landed = progress(updated);
             }
             catch (e) {
                 const reason = blockReason(`isolated iteration failed for ${story.id}: ${e.message}`, opts.targetDir, opts.git);
@@ -114,10 +164,20 @@ export function runLoop(opts) {
                 }
                 catch { /* cleanup is best-effort */ }
             }
+            if (landed)
+                reporter.storyDone({ id: story.id, title: story.title }, landed);
             continue;
         }
         const result = opts.runner({ targetDir: opts.targetDir, story });
         iterations++;
+        if (result.tokens)
+            reporter.addTokens(result.tokens);
+        const ambiguity = consumeAmbiguity(opts.targetDir);
+        if (ambiguity) {
+            const reason = `story ${story.id} stopped: ambiguous acceptance criteria — ${ambiguity}`;
+            reporter.blocked(reason);
+            return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+        }
         // 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');
@@ -169,13 +229,17 @@ export function runLoop(opts) {
             title: story.title,
             summary,
         });
-        const updated = stories.map(s => (s.id === story.id ? { ...s, passes: true } : s));
+        // Re-read the PRD from disk before persisting passes:true — a story injected
+        // mid-iteration (hot-reload) must survive this save, not be clobbered by the
+        // stale top-of-iteration copy.
+        const onDisk = loadPrd(opts.prdPath);
+        const updated = onDisk.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
+            savePrd(opts.prdPath, onDisk); // 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);
@@ -186,5 +250,6 @@ export function runLoop(opts) {
                 finalProgress: progress(stories),
             };
         }
+        reporter.storyDone({ id: story.id, title: story.title }, progress(updated));
     }
 }

package/dist/loop/reporter.js

@@ -23,6 +23,39 @@ export function appendLog(dir, line, capBytes = LOG_CAP_BYTES) {
     const trimmed = nl >= 0 ? tail.slice(nl + 1) : tail;
     writeFileSync(file, `# … loop.log truncated …\n${trimmed}`);
 }
+export function fmtDuration(ms) {
+    const s = Math.max(0, Math.round(ms / 1000));
+    if (s < 60)
+        return `${s}s`;
+    const m = Math.floor(s / 60);
+    if (m < 60)
+        return s % 60 > 0 ? `${m}m${s % 60}s` : `${m}m`;
+    const h = Math.floor(m / 60);
+    return m % 60 > 0 ? `${h}h${m % 60}m` : `${h}h`;
+}
+export const DURATION_HISTORY_CAP = 50;
+function durationsPath(dir) {
+    return join(dir, '.yoke', 'story-durations.json');
+}
+export function readDurations(dir) {
+    try {
+        const arr = JSON.parse(readFileSync(durationsPath(dir), 'utf8'));
+        if (!Array.isArray(arr))
+            return [];
+        return arr.filter((d) => typeof d?.ms === 'number' && d.ms > 0);
+    }
+    catch {
+        return [];
+    }
+}
+function appendDuration(dir, d) {
+    const all = [...readDurations(dir), d].slice(-DURATION_HISTORY_CAP);
+    try {
+        mkdirSync(join(dir, '.yoke'), { recursive: true });
+        writeFileSync(durationsPath(dir), JSON.stringify(all));
+    }
+    catch { /* observability must never abort the loop */ }
+}
 function statusPath(dir) {
     return join(dir, '.yoke', 'loop-status.json');
 }
@@ -49,20 +82,59 @@ export function makeReporter(dir, opts = {}, now = () => new Date()) {
     const emitConsole = (line) => { if (!opts.quiet)
         sink(line); };
     let current = null;
-    const persist = (next, logLabel, consoleLine) => {
+    let tokens;
+    // ETA source: durations of stories completed in THIS run beat the persisted
+    // history of earlier runs (current velocity over old experience).
+    const history = readDurations(dir).map(h => h.ms);
+    const runDurations = [];
+    let storyStartedAt = null;
+    const percentOf = (p) => (p.total > 0 ? Math.round((p.passed / p.total) * 100) : 0);
+    const etaFor = (p) => {
+        const pool = runDurations.length > 0 ? runDurations : history;
+        if (pool.length === 0)
+            return undefined;
+        const avg = pool.reduce((a, b) => a + b, 0) / pool.length;
+        const remainingStories = Math.max(0, p.total - p.passed);
+        return { avgStoryMs: Math.round(avg), remainingStories, etaMs: Math.round(avg * remainingStories) };
+    };
+    const persist = (status, logLabel, consoleLine) => {
+        const withPercent = { ...status, percent: percentOf(status.progress) };
+        const next = tokens ? { ...withPercent, tokens: { ...tokens } } : withPercent;
         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);
+        // json mode owns stdout: one machine-readable line per status write, no narrative.
+        if (opts.json)
+            sink(JSON.stringify({ type: 'status', ...next }));
+        else
+            emitConsole(consoleLine);
     };
     return {
         storyStart(story, iteration, progress) {
             const ts = now().toISOString();
+            storyStartedAt = now().getTime();
+            const eta = etaFor(progress);
+            const hint = eta ? ` · ~${fmtDuration(eta.etaMs)} left (Ø ${fmtDuration(eta.avgStoryMs)}/story)` : '';
             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…`);
+                iteration, progress, ...(eta ? { eta } : {}), startedAt: ts, updatedAt: ts }, 'implementing', `▶ ${story.id} (${progress.passed}/${progress.total} · ${percentOf(progress)}%) — implementing…${hint}`);
+        },
+        storyDone(story, progress) {
+            const t = now().getTime();
+            const ms = storyStartedAt !== null ? Math.max(0, t - storyStartedAt) : undefined;
+            storyStartedAt = null;
+            if (ms !== undefined) {
+                runDurations.push(ms);
+                appendDuration(dir, { storyId: story.id, ms });
+            }
+            const eta = etaFor(progress);
+            const base = current ?? emptyStatus(now().toISOString());
+            const took = ms !== undefined ? ` in ${fmtDuration(ms)}` : '';
+            const hint = eta && eta.remainingStories > 0 ? ` · ~${fmtDuration(eta.etaMs)} left` : '';
+            persist({ ...base, state: 'running', phase: undefined, story: story.id, storyTitle: story.title,
+                progress, ...(eta ? { eta } : {}), updatedAt: now().toISOString() }, 'story-done', `✓ ${story.id} done${took} — ${progress.passed}/${progress.total} (${percentOf(progress)}%)${hint}`);
         },
         phase(phase) {
             if (!current)
@@ -81,11 +153,23 @@ export function makeReporter(dir, opts = {}, now = () => new Date()) {
             persist({ ...(current ?? emptyStatus(now().toISOString())), state: 'cap-reached', phase: undefined,
                 progress, updatedAt: now().toISOString() }, 'cap-reached', `◾ iteration cap reached — ${progress.passed}/${progress.total}`);
         },
+        paused(progress) {
+            persist({ ...(current ?? emptyStatus(now().toISOString())), state: 'paused', phase: undefined,
+                progress, updatedAt: now().toISOString() }, 'paused', `⏸ loop paused — ${progress.passed}/${progress.total}`);
+        },
+        addTokens(usage) {
+            const model = usage.model ?? tokens?.model;
+            tokens = {
+                inputTokens: (tokens?.inputTokens ?? 0) + usage.inputTokens,
+                outputTokens: (tokens?.outputTokens ?? 0) + usage.outputTokens,
+                ...(model ? { model } : {}),
+            };
+        },
     };
 }
 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() { },
+    storyStart() { }, storyDone() { }, phase() { }, blocked() { }, complete() { }, capReached() { }, paused() { }, addTokens() { },
 };