@hecer/yoke 1.21.1 → 1.23.0

package/dist/loop/parallel-command.js

@@ -1,4 +1,6 @@
+import { cacheIsolationProblem } from './cache-isolation.js';
 import { existsSync, rmSync } from 'node:fs';
+import { observeFailure, clearFailureProgress } from './failure.js';
 import { acceptanceProtectionProblem } from '../check/command.js';
 import { makeAsyncAdaptiveRunner } from '../routing/router.js';
 import { resolvePlanner } from '../routing/planning.js';
@@ -12,12 +14,25 @@ import { loadPrd, progress } from './prd.js';
 import { makeAsyncRunner } from './runner.js';
 import { runStoryWorker } from './worker.js';
 import { acquireSharedWorker, sharedPoolStatus } from './resource-pool.js';
+import { providerTelemetryUsage } from '../observability/usage.js';
 export async function runParallelLoopCommand(input) {
-    const originalVerify = input.verify;
+    const originalVerify = input.verify, originalCriterion = input.verifyCriterion;
+    const cacheProblem = (path) => !input.git && path !== input.targetDir ? cacheIsolationProblem(path) : undefined;
     input = { ...input, verify: path => {
-            const problem = acceptanceProtectionProblem(path, input.targetDir);
+            const problem = cacheProblem(path) ?? acceptanceProtectionProblem(path, input.targetDir);
             return problem ? { passed: false, summary: problem } : originalVerify(path);
+        }, verifyCriterion: (path, story, criterion) => {
+            const problem = cacheProblem(path);
+            return problem ? { passed: false, summary: problem } : originalCriterion(path, story, criterion);
         } };
+    for (const name of ['design', 'perf', 'audit']) {
+        const gate = input[name];
+        if (gate)
+            input = { ...input, [name]: (path) => {
+                    const problem = cacheProblem(path);
+                    return problem ? { passed: false, summary: problem } : gate(path);
+                } };
+    }
     const adapters = makeParallelAdapters(input.targetDir, input.identity, input.git);
     if (!adapters.git.isClean(input.targetDir)) {
         input.reporter.blocked('target working tree is not clean');
@@ -96,6 +111,8 @@ export async function runParallelLoopCommand(input) {
                 baseCommit: workerInput.worktree.baseCommit,
                 provider: workerInput.provider,
                 runner,
+                feedback: workerInput.worktree.recovery?.feedback,
+                failureRoot: input.targetDir,
                 verify: input.verify,
                 design: input.design,
                 verifyCriterion: input.verifyCriterion,
@@ -126,11 +143,31 @@ export async function runParallelLoopCommand(input) {
     const result = await dispatcher.run();
     const finalProgress = progress(loadPrd(input.prdPath));
     if (result.status === 'complete' && input.completion) {
-        const gate = input.completion(input.targetDir);
-        if (!gate.passed) {
-            input.reporter.blocked(gate.summary);
+        const previous = process.env.YOKE_PHASE;
+        process.env.YOKE_PHASE = 'completion';
+        let reason;
+        try {
+            const gate = input.completion(input.targetDir);
+            if (!gate.passed)
+                reason = `integrated system did not verify: ${gate.summary}`;
+            else if (!adapters.git.isClean(input.targetDir))
+                reason = 'completion command left source or final assets dirty; preserve changes and move rerun proofs to ignored runtime paths before resuming';
+        }
+        catch (error) {
+            reason = `integrated completion gate failed: ${error instanceof Error ? error.message : String(error)}`;
+        }
+        finally {
+            if (previous === undefined)
+                delete process.env.YOKE_PHASE;
+            else
+                process.env.YOKE_PHASE = previous;
+        }
+        if (reason) {
+            const observed = observeFailure({ root: input.targetDir, directory: input.targetDir, stage: 'completion', summary: reason });
+            input.reporter.blocked(observed.action === 'retry' ? reason : observed.feedback, observed.failure);
             return 1;
         }
+        clearFailureProgress(input.targetDir);
     }
     if (result.status === 'complete')
         input.reporter.complete(finalProgress);
@@ -139,7 +176,7 @@ export async function runParallelLoopCommand(input) {
     else if (result.status === 'cap-reached')
         input.reporter.capReached(finalProgress);
     else
-        input.reporter.blocked(result.reason ?? `parallel dispatcher ${result.status}`);
+        input.reporter.blocked(result.reason ?? `parallel dispatcher ${result.status}`, result.failure);
     return result.status === 'complete' ? 0 : result.status === 'paused' ? 3 : 1;
 }
 function candidateCoordinatorInput(input, adapters, worker, pause) {
@@ -182,6 +219,8 @@ function candidateDefinitions(input, worker, candidateCount, pause) {
             worker: {
                 provider: worker.provider,
                 runner,
+                failureRoot: input.targetDir,
+                failureScope: candidateId,
                 verify: input.verify,
                 design: input.design,
                 verifyCriterion: input.verifyCriterion,
@@ -290,6 +329,9 @@ function asyncRunner(input, provider, signal, workerId) {
             strategy: input.routing.strategy,
             maxCandidates: input.routing.maxCandidates,
             maxAttempts: input.routing.maxAttempts,
+            optimization: input.routing.optimization,
+            accountingScope: input.accountingScope,
+            executionPolicyKey: input.executionPolicyKey,
             planner: resolvePlanner({ planning: input.planning }, input.runnerAgent, input.selection),
             assessmentPolicy: input.routing.assessmentPolicy,
             fallback: input.routing.fallback,
@@ -338,7 +380,7 @@ function asyncRunner(input, provider, signal, workerId) {
     };
 }
 export function providerProcessResultToAgentResult(agent, storyId, result) {
-    const tokens = result.telemetry.tokens;
+    const tokens = providerTelemetryUsage(result.telemetry);
     const telemetry = tokens ? { tokens } : {};
     switch (result.kind) {
         case 'succeeded': return { success: true, summary: `${agent} implemented ${storyId}`, ...telemetry };

package/dist/loop/proof-retention.js

@@ -0,0 +1,70 @@
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve, isAbsolute } from 'node:path';
+import { workspaceFingerprint } from '../workspace/fingerprint.js';
+import { storyPathSegment } from './prd.js';
+const hash = (data) => createHash('sha256').update(data).digest('hex');
+function safePath(root, path) {
+    const rel = relative(resolve(root), resolve(path));
+    if (isAbsolute(rel) || rel === '..' || rel.startsWith('../') || rel.startsWith('..\\'))
+        throw new Error('Proof path escaped workspace');
+    let current = root;
+    for (const segment of rel.split(/[\\/]/u).filter(Boolean)) {
+        current = join(current, segment);
+        try {
+            if (lstatSync(current).isSymbolicLink())
+                throw new Error(`Proof path must not contain a link: ${current}`);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+}
+/** Copy selected proof into an immutable runtime snapshot; errors preserve the candidate. */
+export function retainRuntimeProof(directory, storyId, targetDirectory) {
+    const entries = [];
+    const walk = (dir, base, prefix = '') => {
+        safePath(directory, dir);
+        if (!existsSync(dir))
+            return;
+        for (const name of readdirSync(dir).sort()) {
+            const file = join(dir, name);
+            safePath(directory, file);
+            const stat = lstatSync(file);
+            if (stat.isDirectory())
+                walk(file, base, prefix);
+            else if (stat.isFile()) {
+                const bytes = readFileSync(file);
+                entries.push({ path: (prefix + relative(base, file)).replace(/\\/gu, '/'), sha256: hash(bytes), bytes });
+            }
+            else
+                throw new Error(`Unsupported proof entry: ${file}`);
+        }
+    };
+    const artifacts = join(directory, '.yoke/artifacts'), proof = join(directory, '.yoke/proof');
+    walk(artifacts, artifacts);
+    walk(proof, proof, 'proof/');
+    if (!entries.length)
+        return;
+    const config = ['config.yaml', 'acceptance.yaml', 'prd.yaml'].map(name => {
+        const path = join(directory, '.yoke', name);
+        safePath(directory, path);
+        return [name, existsSync(path) ? hash(readFileSync(path)) : 'missing'];
+    });
+    const manifest = JSON.stringify({ version: 1, source: workspaceFingerprint(directory), config: hash(JSON.stringify(config)), environment: hash(JSON.stringify({ platform: process.platform, arch: process.arch, versions: process.versions })), files: entries.map(({ path, sha256 }) => ({ path, sha256 })) }, null, 2) + '\n';
+    const destination = join(targetDirectory, '.yoke/proof', storyPathSegment(storyId), 'runtime-artifacts', hash(manifest));
+    for (const { path, sha256, bytes } of [...entries, { path: 'manifest.json', sha256: hash(manifest), bytes: Buffer.from(manifest) }]) {
+        const copied = join(destination, path);
+        safePath(targetDirectory, copied);
+        mkdirSync(dirname(copied), { recursive: true });
+        if (existsSync(copied)) {
+            if (hash(readFileSync(copied)) !== sha256)
+                throw new Error(`Retained proof hash mismatch: ${path}`);
+        }
+        else
+            writeFileSync(copied, bytes, { mode: 0o600, flag: 'wx' });
+        if (hash(readFileSync(copied)) !== sha256)
+            throw new Error(`Proof copy hash mismatch: ${path}`);
+    }
+}

package/dist/loop/recovery.js

@@ -52,10 +52,12 @@ export function prepareIsolatedWorktree(directory, worktree, resume) {
     // Record is outside the worker checkout and binds reuse to its source state.
     writeFileSync(record, JSON.stringify({ version: 1, root, worktree: wt, base, prdHash }), { mode: 0o600 });
 }
-const ParallelRecovery = z.object({
+const LegacyParallelRecovery = z.object({
     version: z.literal(1), root: z.string().max(4096), storyId: z.string().max(1024), worktree: z.string().max(4096), baseCommit: z.string().max(128),
     prdHash: z.string().length(64), ownerToken: z.string().min(1).max(256), reason: z.string().max(16384), state: z.literal('retained'), recordedAt: z.string().datetime(),
 }).strict();
+const CurrentParallelRecovery = LegacyParallelRecovery.extend({ version: z.literal(2), phase: z.enum(['implementation', 'integration']) });
+const ParallelRecovery = z.discriminatedUnion('version', [LegacyParallelRecovery, CurrentParallelRecovery]);
 export function parallelAcceptanceDigest(directory) {
     // Accepted sibling stories change only passes. Their acceptance contracts remain protected.
     const contract = loadPrd(join(directory, '.yoke', 'prd.yaml')).map(({ passes: _passes, ...story }) => story);
@@ -84,7 +86,7 @@ export function discardParallelRecoveryRecords(directory) {
 export function retainParallelWorktree(directory, file, input) {
     const root = realpathSync(directory);
     const worktree = realpathSync(input.worktree);
-    const record = ParallelRecovery.parse({ version: 1, root, ...input, reason: input.reason.slice(0, 16384), worktree, state: 'retained', recordedAt: new Date().toISOString() });
+    const record = CurrentParallelRecovery.parse({ version: 2, root, ...input, phase: input.phase ?? 'integration', reason: input.reason.slice(0, 16384), worktree, state: 'retained', recordedAt: new Date().toISOString() });
     const safe = parallelRecordPath(directory, file);
     mkdirSync(dirname(safe), { recursive: true });
     const temp = statePath(directory, 'integration-recovery', `${randomUUID()}.tmp`);
@@ -107,6 +109,8 @@ export function recoverParallelWorktree(directory, file, storyId) {
     if (stat.size > 65536)
         throw new Error('Parallel recovery record is too large');
     const saved = ParallelRecovery.parse(JSON.parse(readFileSync(safe, 'utf8')));
+    // Existing records describe independently checked candidates awaiting integration.
+    const phase = saved.version === 1 ? 'integration' : saved.phase;
     if (!existsSync(saved.worktree))
         throw new Error(`Retained candidate is missing: ${saved.worktree}; resolve its recovery record before retrying`);
     const root = realpathSync(directory);
@@ -117,8 +121,22 @@ export function recoverParallelWorktree(directory, file, storyId) {
     if (saved.storyId !== storyId || pathIdentity(saved.root) !== pathIdentity(root) || pathIdentity(actual) !== pathIdentity(saved.worktree) || isAbsolute(rel) || rel !== expectedName)
         throw new Error('Retained candidate ownership or path binding is invalid');
     const git = (args, cwd = root) => execFileSync('git', args, { cwd, encoding: 'utf8', stdio: 'pipe' }).trim();
-    if (saved.baseCommit !== git(['rev-parse', 'HEAD']) || saved.prdHash !== parallelAcceptanceDigest(root))
-        throw new Error(`Retained candidate is stale against target or PRD: ${actual}; reconcile it before retrying`);
+    const stale = () => new Error(`Retained candidate is stale against target or PRD: ${actual}; reconcile it before retrying`);
+    if (saved.prdHash !== parallelAcceptanceDigest(root))
+        throw stale();
+    if (saved.baseCommit !== git(['rev-parse', 'HEAD'])) {
+        if (phase === 'integration')
+            throw stale();
+        // Siblings may have integrated while this worker was still incomplete. Reuse
+        // its original checkout only for a forward target; integration still rebases
+        // and independently verifies the combined tree before accepting the story.
+        try {
+            git(['merge-base', '--is-ancestor', saved.baseCommit, 'HEAD']);
+        }
+        catch {
+            throw stale();
+        }
+    }
     const common = realpathSync(resolve(root, git(['rev-parse', '--git-common-dir'])));
     if (pathIdentity(realpathSync(resolve(actual, git(['rev-parse', '--git-common-dir'], actual)))) !== pathIdentity(common))
         throw new Error('Retained candidate belongs to another repository');
@@ -126,5 +144,5 @@ export function recoverParallelWorktree(directory, file, storyId) {
     if (!registered.some(path => pathIdentity(path) === pathIdentity(actual)))
         throw new Error('Retained candidate is not a registered worktree');
     git(['merge-base', '--is-ancestor', saved.baseCommit, 'HEAD'], actual);
-    return { path: actual, baseCommit: saved.baseCommit, recovered: true, ownerToken: saved.ownerToken };
+    return { path: actual, baseCommit: saved.baseCommit, recovered: true, ownerToken: saved.ownerToken, recovery: { phase, feedback: saved.reason } };
 }

package/dist/loop/reporter.js

@@ -4,6 +4,7 @@ import { join } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { appendEvent } from '../observability/events.js';
 import { estimateDurations, validDuration } from '../estimation/durations.js';
+import { recordActiveRoutingUsage, markActiveRoutingUsageIncomplete } from '../routing/attempts.js';
 export const LOG_CAP_BYTES = 256 * 1024;
 // Append a line to .yoke/loop.log, keeping the file bounded: once it exceeds
 // capBytes, truncate to the recent tail (starting at a line boundary) so the log
@@ -225,15 +226,15 @@ export function makeReporter(dir, opts = {}, now = () => new Date()) {
             const base = phase === 'exploring' || phase === 'waiting-exploration' || phase === 'waiting-recovery'
                 ? (({ story: _story, storyTitle: _storyTitle, ...withoutStory }) => withoutStory)(status)
                 : status;
-            persist({ ...base, state: 'running', phase, ...(progress ? { progress } : {}), ...(reason ? { reason } : { reason: undefined }), updatedAt: now().toISOString() }, phase, `  · ${phase}…`);
+            persist({ ...base, state: 'running', phase, failure: undefined, ...(progress ? { progress } : {}), ...(reason ? { reason } : { reason: undefined }), updatedAt: now().toISOString() }, phase, `  · ${phase}…`);
         },
-        blocked(reason) {
+        blocked(reason, failure) {
             const base = current ?? emptyStatus(now().toISOString());
-            persist({ ...withoutParallel(base), state: 'blocked', reason, updatedAt: now().toISOString() }, 'blocked', `■ blocked on ${base.story ?? '?'}: ${reason}`);
+            persist({ ...withoutParallel(base), state: 'blocked', reason, failure, updatedAt: now().toISOString() }, 'blocked', `■ blocked on ${base.story ?? '?'}: ${reason}`);
         },
         complete(progress) {
             persist({ ...withoutParallel(current ?? emptyStatus(now().toISOString())), state: 'complete', phase: undefined,
-                progress, reason: undefined, updatedAt: now().toISOString() }, 'complete', `✔ loop complete — ${progress.passed}/${progress.total}`);
+                progress, reason: undefined, failure: undefined, updatedAt: now().toISOString() }, 'complete', `✔ loop complete — ${progress.passed}/${progress.total}`);
         },
         capReached(progress) {
             persist({ ...withoutParallel(current ?? emptyStatus(now().toISOString())), state: 'cap-reached', phase: undefined,
@@ -334,7 +335,7 @@ export function makeReporter(dir, opts = {}, now = () => new Date()) {
                 return;
             }
             const { integrator: _integrator, ...withoutIntegrator } = parallel;
-            persist({ ...base, parallel: withoutIntegrator, updatedAt: now().toISOString() }, 'parallel-integrator', '  · integration complete');
+            persist({ ...base, parallel: withoutIntegrator, updatedAt: now().toISOString() }, 'parallel-integrator', '  · integrator idle');
         },
         addTokens(usage) {
             if (![usage.inputTokens, usage.outputTokens].every(value => Number.isFinite(value) && value >= 0))
@@ -345,6 +346,22 @@ export function makeReporter(dir, opts = {}, now = () => new Date()) {
                 if (value !== undefined && (!Number.isFinite(value) || value < 0))
                     delete usage[key];
             }
+            if (!usage.calls?.length && !usage.callId)
+                usage.callId = randomUUID();
+            const costRole = usage.role && ['reviewer', 'critic', 'repair', 'quality-critic', 'quality-repair', 'candidate-selection'].includes(usage.role);
+            if (usage.storyId && (usage.routingAttemptId || (costRole && !usage.calls?.length))) {
+                try {
+                    recordActiveRoutingUsage(dir, usage.storyId, usage);
+                }
+                catch {
+                    // Accounting failures must disqualify economic evidence without losing
+                    // the independent event below or interrupting a useful implementation.
+                    try {
+                        markActiveRoutingUsageIncomplete(dir, usage.storyId);
+                    }
+                    catch { /* Router finalization also fails closed on corrupt accounting. */ }
+                }
+            }
             const calls = usage.calls?.length ? usage.calls : [{ usageAvailable: usage.measurementComplete !== false, totalCostUsd: usage.totalCostUsd }];
             measuredCalls += calls.filter(call => call.usageAvailable !== false).length;
             unknownCalls += calls.filter(call => call.usageAvailable === false).length;

package/dist/loop/run-command.js

@@ -1,4 +1,5 @@
 import { roleSelection } from "../routing/capability.js";
+import { createHash } from 'node:crypto';
 import { join } from 'node:path';
 import { existsSync, unlinkSync } from 'node:fs';
 import { loadConfig, saveConfig, defaultConfig, resolveOutputPolicy, resolveVerifyCommand } from '../retrofit/config.js';
@@ -31,6 +32,15 @@ import { MAX_PROJECT_WORKERS, sharedPoolStatus, withSharedWorkerSync } from './r
 import { runPrdExplore } from '../prd/explore.js';
 export const DEFAULT_IDLE_MINUTES = 20;
 const STALE_MINUTES = 20; // a running status older than this likely means the loop died
+const nativeReporters = new WeakSet();
+function executionPolicyFingerprint(policy) {
+    const canonical = JSON.stringify(policy, (_key, value) => {
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            return value;
+        return Object.fromEntries(Object.keys(value).sort().map(key => [key, value[key]]));
+    });
+    return createHash('sha256').update(canonical).digest('hex');
+}
 export function relativeTime(fromIso, now) {
     const ms = Math.max(0, now.getTime() - Date.parse(fromIso));
     const s = Math.floor(ms / 1000);
@@ -66,7 +76,12 @@ export function loopStatus(targetDir, now = () => new Date(), opts) {
     if (opts?.compact) {
         if (!st)
             return `state=${enabled ? 'enabled' : 'disabled'} prd="${prog}"`;
-        return `state=${st.state} story=${st.story ?? 'none'} progress=${st.progress.passed}/${st.progress.total} phase=${st.phase} updated=${relativeTime(st.updatedAt, now())}`;
+        const workers = [...(st.parallel?.workers ?? [])].sort((a, b) => a.story.localeCompare(b.story));
+        const work = (worker) => `${encodeURIComponent(worker.story)}:${worker.phase ?? 'working'}`;
+        const integrator = st.parallel?.integrator;
+        const story = st.story ?? integrator?.story ?? workers[0]?.story ?? 'none';
+        const parallel = st.parallel ? ` workers=${workers.map(work).join(',') || 'none'} integrator=${integrator ? work(integrator) : 'none'} waiting=${st.parallel.waitingWorkers ?? 0} queued=${st.parallel.queuedIntegrations ?? st.parallel.queuedCandidates}` : '';
+        return `state=${st.state} story=${encodeURIComponent(story)} progress=${st.progress.passed}/${st.progress.total} phase=${st.phase ?? (st.parallel ? 'parallel' : st.state)}${parallel} updated=${relativeTime(st.updatedAt, now())}`;
     }
     const sharedPoolLine = () => {
         try {
@@ -241,6 +256,8 @@ async function runContinuousExploration(targetDir, options) {
     }
     const limitDeadline = options.savedRun?.exploreDeadline ?? (options.exploreLimitMs === undefined ? undefined : Date.now() + options.exploreLimitMs);
     const reporter = options.reporter ?? makeReporter(targetDir, { json: options.json, quiet: true });
+    if (!options.reporter)
+        nativeReporters.add(reporter);
     let config;
     try {
         config = loadConfig(targetDir);
@@ -261,6 +278,7 @@ async function runContinuousExploration(targetDir, options) {
     let reviewerAgent = options.reviewer ?? (reviewRequested ? SUPPORTED_AGENTS.find(agent => agent !== defaultImplementationAgent && available(agent)) : undefined);
     let explorationAgent = defaultExplorer;
     let retryWorktree = false;
+    let retryFeedback;
     const safeBatchSize = () => {
         if (retryWorktree)
             return 1;
@@ -365,6 +383,7 @@ async function runContinuousExploration(targetDir, options) {
             resultCode = await Promise.resolve(runLoopCommand(targetDir, {
                 ...innerOptions,
                 agent: implementationAgent,
+                recoveryFeedback: retryFeedback,
                 ...(reviewRequested && reviewerAgent ? { reviewer: reviewerAgent } : {}),
                 ...(batchLimit !== undefined ? { maxIterations: batchLimit } : {}),
                 ...(retryWorktree ? { resumeWorktree: true, parallel: 1, candidates: 1 } : {}),
@@ -455,7 +474,11 @@ async function runContinuousExploration(targetDir, options) {
             }
             continue;
         }
-        if (afterStatus?.reason?.startsWith('integrated completion gate failed') && allCurrentStoriesPass(targetDir)) {
+        if (afterStatus?.failure?.kind === 'no-progress') {
+            reporter.blocked(afterStatus.reason ?? 'Automatic continuation stopped after unchanged failures', afterStatus.failure);
+            return 1;
+        }
+        if (afterStatus?.failure?.kind === 'completion-failed' && allCurrentStoriesPass(targetDir)) {
             retryWorktree = false;
             reporter.phase('exploring', `all planned tasks pass, but ${afterStatus.reason}; looking for work that can resolve the completion gate`, currentProgress(targetDir));
             const scan = await scanForWork(`The integrated completion gate is still failing: ${afterStatus.reason}`);
@@ -478,6 +501,7 @@ async function runContinuousExploration(targetDir, options) {
             continue;
         }
         retryCount++;
+        retryFeedback = afterStatus?.reason;
         advanceRecoveryProviders();
         retryWorktree = (afterStatus?.parallel?.reopened ?? 0) === 0;
         const wait = retryDelay(retryCount);
@@ -579,9 +603,10 @@ export function runLoopCommand(targetDir, opts) {
         }
     }
     const outputPolicy = resolveOutputPolicy(config);
+    const configuredVerifyCommand = opts.verify ? undefined : resolveVerifyCommand(targetDir, config);
     let verify = opts.verify;
     if (!verify) {
-        const command = resolveVerifyCommand(targetDir, config);
+        const command = configuredVerifyCommand;
         if (!command) {
             console.error('No verify command configured. Set verify.command in .yoke/config.yaml (e.g. "npm test") so the loop can confirm tests pass before marking work done.');
             return 2;
@@ -752,6 +777,73 @@ export function runLoopCommand(targetDir, opts) {
         selection: runnerSelection,
         commit: (_path, request) => commitPaths(targetDir, ['.yoke/prd.yaml'], `yoke: plan change ${request.id}`, commitIdentity),
     }));
+    const reviewerProviders = !opts.reviewRunner && (opts.review || opts.reviewer) ? SUPPORTED_AGENTS.filter(available) : [];
+    let review = opts.reviewRunner;
+    let reviewProvider = 'unknown';
+    if (!review && (opts.review || opts.reviewer)) {
+        const reviewerAgent = opts.reviewer ?? reviewerProviders.find(agent => agent !== runnerAgent);
+        if (!reviewerAgent) {
+            if (!opts.allowSelfReview) {
+                console.error('No independent reviewer CLI is available. Install or select a second agent, or pass --allow-self-review explicitly.');
+                return 2;
+            }
+        }
+        const resolvedReviewer = reviewerAgent ?? runnerAgent;
+        reviewProvider = resolvedReviewer;
+        if (resolvedReviewer === runnerAgent && !opts.allowSelfReview) {
+            console.error(`Reviewer "${resolvedReviewer}" is also the implementer. Pick another agent or pass --allow-self-review explicitly.`);
+            return 2;
+        }
+        if (!available(resolvedReviewer)) {
+            console.error(`Reviewer agent CLI "${resolvedReviewer}" was not found on PATH. Install it, or pick another with --reviewer=<${AGENT_LIST}>.`);
+            return 2;
+        }
+        review = context => {
+            const implementer = readStatus(targetDir)?.routingDecisions?.[context.story.id]?.provider ?? runnerAgent;
+            const selectedReviewer = !opts.reviewer && resolvedReviewer === implementer
+                ? reviewerProviders.find(agent => agent !== implementer) ?? resolvedReviewer : resolvedReviewer;
+            if (selectedReviewer === implementer && !opts.allowSelfReview)
+                return { success: false, summary: "Independent review requires a provider distinct from the routed implementer", reviewOutcome: { kind: "infrastructure", summary: "Routed implementation and reviewer share a provider" } };
+            reviewProvider = selectedReviewer;
+            return makeReviewRunner(selectedReviewer, idleMs, undefined, routingEnabled ? roleSelection(targetDir, config, context.story, selectedReviewer, "reviewer") : undefined)(context);
+        };
+    }
+    if (review) {
+        const reviewRunner = review;
+        review = context => {
+            const started = Date.now();
+            let result;
+            try {
+                result = reviewRunner(context);
+                return result;
+            }
+            finally {
+                executionReporter?.addTokens({ inputTokens: 0, outputTokens: 0, measurementComplete: result?.tokens !== undefined, ...result?.tokens, provider: reviewProvider, role: 'reviewer', storyId: context.story.id, durationMs: Date.now() - started });
+            }
+        };
+    }
+    // Only native, attributable roles justify comparisons of complete attempts.
+    // Concurrent candidates have ambiguous story-wide role attribution and remain
+    // conservative until their costs can be joined to an individual alternative.
+    const completeAccounting = candidates === 1 && !opts.runner && !opts.verify && !opts.design && !opts.perf && !opts.audit
+        && !opts.reviewRunner && !opts.qualityRuntime && !opts.git && !opts.intake
+        && (!opts.reporter || nativeReporters.has(opts.reporter));
+    const accountingScope = completeAccounting ? 'execution-attempt' : undefined;
+    const executionPolicyKey = completeAccounting ? executionPolicyFingerprint({
+        version: 1,
+        mode: useParallelDispatcher ? candidates > 1 ? 'candidates' : 'parallel' : 'serial',
+        parallel, candidates, isolate: useParallelDispatcher || isolate,
+        verify: { command: configuredVerifyCommand, retries: config.verify?.retries ?? 1, requireCriteria: config.verify?.requireCriteria ?? false },
+        design: design ? { max: config.design?.max } : false,
+        perf: perf ? { command: config.perf?.command, retries: config.perf?.retries ?? 1 } : false,
+        audit: audit ? config.audit : false,
+        completion: completion ? { command: config.completion?.command, retries: config.completion?.retries ?? 1 } : false,
+        quality: quality ? { defaults: config.quality, overrides: qualityOverrides, limits: quality.repairLimits, runnerAgent, runner: config.runner, agents: config.agents } : false,
+        review: review ? { provider: reviewProvider, explicitProvider: opts.reviewer, eligibleProviders: reviewerProviders, allowSelfReview: opts.allowSelfReview ?? false } : false,
+        roleRouting: routingEnabled && (quality || review) ? config.routing : false,
+        permissions: { implementation: permissions, orchestrator: 'read-only', reviewer: 'read-only', critic: 'read-only', repair: 'safe' },
+        idleMs, ambiguityPolicy,
+    }) : undefined;
     let runner = opts.runner;
     if (!runner) {
         const requiredProviders = useParallelDispatcher
@@ -783,6 +875,9 @@ export function runLoopCommand(targetDir, opts) {
                 strategy: config.routing.strategy,
                 maxCandidates: config.routing.maxCandidates,
                 maxAttempts: config.routing.maxAttempts,
+                optimization: config.routing.optimization,
+                accountingScope,
+                executionPolicyKey,
                 planner: resolvePlanner(config, runnerAgent, runnerSelection),
                 assessmentPolicy: config.routing.assessmentPolicy,
                 fallback: config.routing.fallback,
@@ -805,50 +900,6 @@ export function runLoopCommand(targetDir, opts) {
         }
         runner = makeActionRunner(config.actions, runner);
     }
-    let review = opts.reviewRunner;
-    let reviewProvider = 'unknown';
-    if (!review && (opts.review || opts.reviewer)) {
-        const reviewerAgent = opts.reviewer ?? SUPPORTED_AGENTS.find(agent => agent !== runnerAgent && available(agent));
-        if (!reviewerAgent) {
-            if (!opts.allowSelfReview) {
-                console.error('No independent reviewer CLI is available. Install or select a second agent, or pass --allow-self-review explicitly.');
-                return 2;
-            }
-        }
-        const resolvedReviewer = reviewerAgent ?? runnerAgent;
-        reviewProvider = resolvedReviewer;
-        if (resolvedReviewer === runnerAgent && !opts.allowSelfReview) {
-            console.error(`Reviewer "${resolvedReviewer}" is also the implementer. Pick another agent or pass --allow-self-review explicitly.`);
-            return 2;
-        }
-        if (!available(resolvedReviewer)) {
-            console.error(`Reviewer agent CLI "${resolvedReviewer}" was not found on PATH. Install it, or pick another with --reviewer=<${AGENT_LIST}>.`);
-            return 2;
-        }
-        review = context => {
-            const implementer = readStatus(targetDir)?.routingDecisions?.[context.story.id]?.provider ?? runnerAgent;
-            const selectedReviewer = !opts.reviewer && resolvedReviewer === implementer
-                ? SUPPORTED_AGENTS.find(agent => agent !== implementer && available(agent)) ?? resolvedReviewer : resolvedReviewer;
-            if (selectedReviewer === implementer && !opts.allowSelfReview)
-                return { success: false, summary: "Independent review requires a provider distinct from the routed implementer", reviewOutcome: { kind: "infrastructure", summary: "Routed implementation and reviewer share a provider" } };
-            reviewProvider = selectedReviewer;
-            return makeReviewRunner(selectedReviewer, idleMs, undefined, routingEnabled ? roleSelection(targetDir, config, context.story, selectedReviewer, "reviewer") : undefined)(context);
-        };
-    }
-    if (review) {
-        const reviewRunner = review;
-        review = context => {
-            const started = Date.now();
-            let result;
-            try {
-                result = reviewRunner(context);
-                return result;
-            }
-            finally {
-                executionReporter?.addTokens({ inputTokens: 0, outputTokens: 0, measurementComplete: result?.tokens !== undefined, ...result?.tokens, provider: reviewProvider, role: 'reviewer', storyId: context.story.id, durationMs: Date.now() - started });
-            }
-        };
-    }
     if (!useParallelDispatcher) {
         if (runner) {
             const unpooled = runner;
@@ -951,6 +1002,8 @@ export function runLoopCommand(targetDir, opts) {
             providers: parallelProviders,
             affinityProviders: parallelAffinityProviders,
             routing: routingEnabled ? config.routing : undefined,
+            accountingScope,
+            executionPolicyKey,
             planning: config.planning,
             isAvailable: available,
             onAmbiguity: ambiguityPolicy,
@@ -976,6 +1029,7 @@ export function runLoopCommand(targetDir, opts) {
             prdPath: path,
             targetDir,
             runner,
+            feedback: opts.recoveryFeedback,
             git,
             commitIdentity,
             verify,

package/dist/loop/runner.js

@@ -9,6 +9,7 @@ import { loadContext, formatForPrompt, contextDir } from '../context/context.js'
 import { contextPacket } from '../context/packet.js';
 import { buildProviderInvocation, startProviderProcess } from '../agents/providers.js';
 import { parseProviderResult, parseProviderTelemetry } from '../agents/telemetry.js';
+import { providerTelemetryUsage } from '../observability/usage.js';
 import { formatReviewContract, formatReviewStdoutContract, parseReviewVerdict } from '../review/verdict.js';
 import { prepareWindowsInvocation } from '../agents/windows-launch.js';
 import { readSupervision } from '../agents/supervision.js';
@@ -31,7 +32,7 @@ export function buildClaudePrompt(story, context, onAmbiguity = 'resolve', perfC
     ];
     if (context)
         lines.push('', context);
-    lines.push('', `Story ${story.id}: ${story.title}`, 'Acceptance criteria (Definition of Done):', criteria, ...(story.assessment ? ['Planner approach:', story.assessment.approach] : []), '', "When done, ensure the project's full test suite passes.", 'Do NOT commit — the loop commits on your behalf after verifying.', '', 'Working rules:', '- Add nothing beyond what the story requires: no extra features, abstractions, comments, or defensive code for cases that cannot happen.', '- Do not create summary, plan, or analysis documents — only files the story itself needs.', '- If a check fails, fix the root cause; never bypass it (e.g. --no-verify) or pass by weakening tests.', '- Report the outcome faithfully: if a criterion is unmet or tests fail, say so plainly instead of claiming success.', '- Never ask questions or wait for input — you run unattended and nobody can answer.', onAmbiguity === 'abort'
+    lines.push('', `Story ${story.id}: ${story.title}`, 'Acceptance criteria (Definition of Done):', criteria, ...(story.assessment ? ['Planner approach:', story.assessment.approach] : []), '', "When done, ensure the project's full test suite passes.", 'Do NOT commit — the loop commits on your behalf after verifying.', '', 'Working rules:', '- Use worktree-local writable dependency/runtime caches. Do not link node_modules to a target checkout when tools write .vite-temp or other caches there. Shared package download caches are allowed; preserve the configured sandbox. Report offline cache misses and network failures explicitly instead of blindly retrying.', '- Add nothing beyond what the story requires: no extra features, abstractions, comments, or defensive code for cases that cannot happen.', '- Do not create summary, plan, or analysis documents — only files the story itself needs.', '- If a check fails, fix the root cause; never bypass it (e.g. --no-verify) or pass by weakening tests.', '- Report the outcome faithfully: if a criterion is unmet or tests fail, say so plainly instead of claiming success.', '- Never ask questions or wait for input — you run unattended and nobody can answer.', onAmbiguity === 'abort'
         ? '- If an acceptance criterion is genuinely undecidable, do NOT guess: write the open question(s) to .yoke/ambiguity.md, change nothing else, and stop.'
         : onAmbiguity === 'critical'
             ? [
@@ -243,7 +244,7 @@ function processFailureSummary(error) {
 export function runCapturedAgent(agent, inv) {
     try {
         const output = runCliCapture(inv);
-        return { success: true, output, summary: 'exited 0', tokens: parseProviderTelemetry(agent, output.split(/\r?\n/)).tokens };
+        return { success: true, output, summary: 'exited 0', tokens: providerTelemetryUsage(parseProviderTelemetry(agent, output.split(/\r?\n/))) };
     }
     catch (error) {
         const partial = error.stdout;
@@ -252,7 +253,7 @@ export function runCapturedAgent(agent, inv) {
             success: false,
             output,
             summary: error.message,
-            tokens: output ? parseProviderTelemetry(agent, output.split(/\r?\n/)).tokens : undefined,
+            tokens: output ? providerTelemetryUsage(parseProviderTelemetry(agent, output.split(/\r?\n/))) : undefined,
         };
     }
 }
@@ -316,12 +317,12 @@ export function makeRunner(agent, idleTimeoutMs = 0, opts = {}) {
             try {
                 const out = capture(inv);
                 const telemetry = parseProviderTelemetry(agent, out.split(/\r?\n/));
-                return { success: true, summary: `${agent} implemented ${ctx.story.id}`, tokens: attributed(telemetry.tokens) };
+                return { success: true, summary: `${agent} implemented ${ctx.story.id}`, tokens: attributed(providerTelemetryUsage(telemetry)) };
             }
             catch (e) {
                 // Salvage usage from whatever the agent streamed before dying — those tokens were spent.
                 const partial = e.stdout;
-                const tokens = partial == null ? undefined : parseProviderTelemetry(agent, String(partial).split(/\r?\n/)).tokens;
+                const tokens = partial == null ? undefined : providerTelemetryUsage(parseProviderTelemetry(agent, String(partial).split(/\r?\n/)));
                 const reason = readSupervision(ctx.targetDir, new Date(started).toISOString())[0]?.reason;
                 return { success: false, infrastructureFailure: true, summary: `${agent} failed on ${ctx.story.id}: ${reason ?? e.message}`, tokens: attributed(tokens) };
             }