@hecer/yoke 0.2.0 → 0.7.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,9 @@ function main(argv) {
                     }
                     timeoutMinutes = v;
                 }
-                return runLoopCommand(targetDir, { maxIterations: rawMax, agent, isolate, reviewer, review, timeoutMinutes });
+                return runLoopCommand(targetDir, { maxIterations: rawMax, agent, isolate, reviewer, review, timeoutMinutes, json });
             }
-            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>] [--json]> [targetDir]');
             return 1;
         }
         case 'new': {
@@ -233,12 +237,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 } 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,11 @@ 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');
+}
 export function runLoop(opts) {
     let iterations = 0;
     const reporter = opts.reporter ?? noopReporter;
@@ -31,6 +37,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');
@@ -54,6 +71,8 @@ export function runLoop(opts) {
                 opts.git.addWorktree(opts.targetDir, wt);
                 const result = opts.runner({ targetDir: wt, story });
                 iterations++;
+                if (result.tokens)
+                    reporter.addTokens(result.tokens);
                 // 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');
@@ -118,6 +137,8 @@ export function runLoop(opts) {
         }
         const result = opts.runner({ targetDir: opts.targetDir, story });
         iterations++;
+        if (result.tokens)
+            reporter.addTokens(result.tokens);
         // 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 +190,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);

package/dist/loop/reporter.js

@@ -49,14 +49,20 @@ 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;
+    const persist = (status, logLabel, consoleLine) => {
+        const next = tokens ? { ...status, tokens: { ...tokens } } : status;
         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) {
@@ -81,11 +87,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() { }, phase() { }, blocked() { }, complete() { }, capReached() { }, paused() { }, addTokens() { },
 };

package/dist/loop/run-command.js

@@ -8,6 +8,7 @@ import { makeRunner, makeReviewRunner, isAgentAvailable } from './runner.js';
 import { commandVerifier, retryingVerifier } from './verify.js';
 import { readStatus, makeReporter } from './reporter.js';
 import { acquireLock, releaseLock } from './lock.js';
+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) {
@@ -80,6 +81,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 +93,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 });
     }
     let review = opts.reviewRunner;
     if (!review && (opts.review || opts.reviewer)) {
@@ -118,15 +124,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);