@hecer/yoke 1.20.0 → 1.22.0

package/dist/loop/gate-snapshot.js

@@ -0,0 +1,19 @@
+import { createHash } from 'node:crypto';
+import { workspaceFingerprint } from '../workspace/fingerprint.js';
+export function gateIdentity(directory, story) {
+    try {
+        return createHash('sha256').update(workspaceFingerprint(directory)).update(JSON.stringify(story)).digest('hex');
+    }
+    catch {
+        // Unavailable identity disables reuse; it never turns an unchecked state green.
+        return undefined;
+    }
+}
+export function snapshotGates(directory, story, before, evidence) {
+    if (!before || before !== gateIdentity(directory, story))
+        return undefined;
+    return { identity: before, evidence };
+}
+export function reuseGates(directory, story, snapshot) {
+    return snapshot && snapshot.identity === gateIdentity(directory, story) ? snapshot.evidence : undefined;
+}

package/dist/loop/git.js

@@ -1,6 +1,6 @@
 import { execFileSync } from 'node:child_process';
 import { sanitizeCommitMessage } from './identity.js';
-export const RUNTIME_PATHS = [".yoke/supervision", ".yoke/provider-processes", '.yoke/claims', '.yoke/worktrees', '.yoke/artifacts', '.yoke/events', '.yoke/history', '.yoke/routing', '.yoke/checks', '.yoke/integration-recovery', '.yoke/run-state.json', '.yoke/run-state.*.tmp', '.yoke/goal.json', '.yoke/goal.pause', '.yoke/loop.pause', '.yoke/loop-status.json', '.yoke/loop.lock', '.yoke/loop.lock.takeover', '.yoke/loop.lock.takeover.recovery', '.yoke/runner.pid', '.yoke/story-durations.json'];
+export const RUNTIME_PATHS = [".yoke/supervision", ".yoke/provider-processes", '.yoke/claims', '.yoke/worktrees', '.yoke/artifacts', '.yoke/events', '.yoke/history', '.yoke/routing', '.yoke/routing-attempts', '.yoke/checks', '.yoke/integration-recovery', '.yoke/failure-progress', '.yoke/run-state.json', '.yoke/run-state.*.tmp', '.yoke/goal.json', '.yoke/goal.pause', '.yoke/loop.pause', '.yoke/loop-status.json', '.yoke/loop.lock', '.yoke/loop.lock.takeover', '.yoke/loop.lock.takeover.recovery', '.yoke/runner.pid', '.yoke/story-durations.json'];
 // Directory pathspecs include descendants and also exclude the directory entry.
 export const RUNTIME_EXCLUDES = RUNTIME_PATHS.map(path => `:(exclude)${path}`);
 export function stageImplementation(dir) {

package/dist/loop/loop.js

@@ -4,6 +4,8 @@ import { acceptanceProtectionProblem } from '../check/command.js';
 import { join, relative } from 'node:path';
 import { isAcceptanceCriterion, loadPrd, savePrd, selectNextStory, allPass, progress, storyPathSegment } from './prd.js';
 import { stopTheLineGate, preDispatchGate } from './gates.js';
+import { observeFailure, clearFailureProgress } from './failure.js';
+import { gateIdentity, snapshotGates, reuseGates } from './gate-snapshot.js';
 import { appendDecision, contextDir } from '../context/context.js';
 import { noopReporter } from './reporter.js';
 import { consumeDecisionRequest } from './decision.js';
@@ -68,7 +70,8 @@ function runQualityReview(opts, executionDir, story, reporter) {
         }
         return { kind: 'passed' };
     };
-    return runQualityRepairLoop({
+    let failure;
+    const outcome = runQualityRepairLoop({
         quality: qualityAssessment
             ? round => {
                 reporter.phase('comparing');
@@ -85,7 +88,13 @@ function runQualityReview(opts, executionDir, story, reporter) {
             reporter.phase('repairing');
             if (!opts.repair)
                 return { kind: 'blocked', summary: 'repair callback is not configured' };
-            const result = opts.repair({ targetDir: executionDir, story }, request);
+            const observed = observeFailure({ root: opts.targetDir, directory: executionDir, story, stage: 'quality', summary: JSON.stringify(request.finding) });
+            if (observed.action === 'blocked') {
+                failure = observed.failure;
+                return { kind: 'blocked', summary: observed.feedback };
+            }
+            const targetedRequest = observed.action === 'diagnose' ? { ...request, finding: { ...request.finding, message: observed.feedback } } : request;
+            const result = opts.repair({ targetDir: executionDir, story }, targetedRequest);
             return result.success ? { kind: 'repaired' } : { kind: 'blocked', summary: result.summary };
         },
         rerunGates,
@@ -96,6 +105,7 @@ function runQualityReview(opts, executionDir, story, reporter) {
                 reporter.quality({ ...status, ...qualityMetadata });
         },
     });
+    return { ...outcome, ...(failure ? { failure } : {}) };
 }
 // 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.
@@ -146,7 +156,7 @@ function runGate(gate, dir, storyId) {
             process.env.YOKE_STORY = prev;
     }
 }
-function consumeAmbiguity(dir) {
+export function consumeAmbiguity(dir) {
     const file = ambiguityFilePath(dir);
     if (!existsSync(file))
         return null;
@@ -167,14 +177,14 @@ function runCompletionGate(opts, stories) {
         return null;
     const previous = process.env.YOKE_PHASE;
     process.env.YOKE_PHASE = 'completion';
-    let verdict;
+    let reason;
     try {
-        verdict = opts.completion(opts.targetDir);
+        const verdict = opts.completion(opts.targetDir);
+        if (!verdict.passed)
+            reason = `integrated system did not verify: ${verdict.summary}`;
     }
     catch (error) {
-        const reason = `integrated completion gate failed: ${error.message}`;
-        (opts.reporter ?? noopReporter).blocked(reason);
-        return { status: 'blocked', iterations: 0, reason, finalProgress: progress(stories) };
+        reason = `integrated completion gate failed: ${error.message}`;
     }
     finally {
         if (previous === undefined)
@@ -182,11 +192,15 @@ function runCompletionGate(opts, stories) {
         else
             process.env.YOKE_PHASE = previous;
     }
-    if (verdict.passed)
+    if (!reason) {
+        clearFailureProgress(opts.targetDir);
         return null;
-    const reason = `integrated system did not verify: ${verdict.summary}`;
-    (opts.reporter ?? noopReporter).blocked(reason);
-    return { status: 'blocked', iterations: 0, reason, finalProgress: progress(stories) };
+    }
+    const observed = observeFailure({ root: opts.targetDir, directory: opts.targetDir, stage: 'completion', summary: reason });
+    if (observed.action !== 'retry')
+        reason = observed.feedback;
+    (opts.reporter ?? noopReporter).blocked(reason, observed.failure);
+    return { status: 'blocked', iterations: 0, reason, failure: observed.failure, finalProgress: progress(stories) };
 }
 function runCriterionGates(opts, executionDir, story) {
     const protectionProblem = acceptanceProtectionProblem(executionDir, opts.targetDir);
@@ -313,86 +327,88 @@ export function runLoop(opts) {
             const wt = join(opts.targetDir, '.yoke', 'worktrees', storyPathSegment(story.id));
             const wtPrd = join(wt, relative(opts.targetDir, opts.prdPath));
             let landed = null;
+            let activeRouting;
             try {
                 opts.git.addWorktree(opts.targetDir, wt);
-                const result = runImplementation(opts, wt, story, reporter);
+                const implementation = runImplementation(opts, wt, story, reporter);
+                const result = implementation.result;
+                activeRouting = result.routing;
                 iterations++;
                 if (result.tokens)
                     reporter.addTokens(result.tokens);
                 if (result.infrastructureFailure || result.routing?.blocked) {
                     if (result.infrastructureFailure)
                         result.routing?.recordOutcome(false, "infrastructure");
-                    reporter.blocked(result.summary);
-                    return { status: "blocked", iterations, reason: result.summary, finalProgress: progress(stories) };
+                    reporter.blocked(result.summary, implementation.failure);
+                    return { status: "blocked", iterations, reason: result.summary, ...(implementation.failure ? { failure: implementation.failure } : {}), finalProgress: progress(stories) };
                 }
                 let decision;
                 try {
                     decision = consumeDecisionRequest(wt, opts.targetDir, story.id);
                 }
                 catch (error) {
+                    result.routing?.recordOutcome(false, 'infrastructure');
                     const reason = `invalid critical decision request for story ${story.id}: ${error.message}`;
                     reporter.blocked(reason);
                     return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
                 }
                 if (decision) {
+                    result.routing?.recordOutcome(false, 'infrastructure');
                     const reason = `critical decision required for story ${story.id}: ${decision.question}`;
                     reporter.blocked(reason);
                     return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
                 }
                 const ambiguity = consumeAmbiguity(wt);
                 if (ambiguity) {
+                    result.routing?.recordOutcome(false, 'infrastructure');
                     const reason = `story ${story.id} stopped: ambiguous acceptance criteria — ${ambiguity}`;
                     reporter.blocked(reason);
                     return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
                 }
-                const criteriaVerdict = runCriterionGates(opts, wt, story);
+                const verified = reuseGates(wt, story, implementation.gates);
+                const criteriaVerdict = verified?.criteria ?? runCriterionGates(opts, wt, story);
                 if (!criteriaVerdict.passed) {
                     result.routing?.recordOutcome(false);
                     const reason = blockReason(`story ${story.id} lacks acceptance evidence: ${criteriaVerdict.summary}`, opts.targetDir, opts.git);
-                    reporter.blocked(reason);
-                    return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+                    return blockedMechanicalGate(opts, wt, story, 'criterion', criteriaVerdict.summary, reason, iterations, 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');
-                const verdict = runGate(opts.verify, wt, story.id);
+                const verdict = verified?.verify ?? runGate(opts.verify, wt, story.id);
                 if (!verdict.passed) {
                     result.routing?.recordOutcome(false);
                     const base = result.success
                         ? `story ${story.id} did not verify: ${verdict.summary}`
                         : `story ${story.id} runner failed (${result.summary}) and verify is red: ${verdict.summary}`;
                     const reason = blockReason(base, opts.targetDir, opts.git);
-                    reporter.blocked(reason);
-                    return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+                    return blockedMechanicalGate(opts, wt, story, 'verify', verdict.summary, reason, iterations, stories);
                 }
                 if (opts.design) {
                     reporter.phase('design');
-                    const designVerdict = runGate(opts.design, wt, story.id);
+                    const designVerdict = verified?.design ?? runGate(opts.design, wt, story.id);
                     if (!designVerdict.passed) {
                         result.routing?.recordOutcome(false);
                         const reason = blockReason(`story ${story.id} failed its design gate: ${designVerdict.summary}`, opts.targetDir, opts.git);
-                        reporter.blocked(reason);
-                        return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+                        return blockedMechanicalGate(opts, wt, story, 'design', designVerdict.summary, reason, iterations, stories);
                     }
                 }
                 if (opts.perf) {
                     reporter.phase('perf');
-                    const perfVerdict = runGate(opts.perf, wt, story.id);
+                    const perfVerdict = verified?.perf ?? runGate(opts.perf, wt, story.id);
                     if (!perfVerdict.passed) {
                         result.routing?.recordOutcome(false);
                         const reason = blockReason(`story ${story.id} exceeded its performance budget: ${perfVerdict.summary}`, opts.targetDir, opts.git);
-                        reporter.blocked(reason);
-                        return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+                        return blockedMechanicalGate(opts, wt, story, 'perf', perfVerdict.summary, reason, iterations, stories);
                     }
                 }
                 if (opts.audit) {
                     reporter.phase('audit');
-                    const auditVerdict = runGate(opts.audit, wt, story.id);
+                    const auditVerdict = verified?.audit ?? runGate(opts.audit, wt, story.id);
                     if (!auditVerdict.passed) {
                         result.routing?.recordOutcome(false);
                         const reason = blockReason(`story ${story.id} failed security audit: ${auditVerdict.summary}`, opts.targetDir, opts.git);
-                        reporter.blocked(reason);
-                        return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+                        return blockedMechanicalGate(opts, wt, story, 'audit', auditVerdict.summary, reason, iterations, stories);
                     }
                 }
                 const summary = result.success
@@ -401,14 +417,15 @@ export function runLoop(opts) {
                 const repairOutcome = runQualityReview(opts, wt, story, reporter);
                 if (repairOutcome) {
                     if (repairOutcome.kind === 'paused') {
+                        result.routing?.recordOutcome(false, 'infrastructure');
                         reporter.paused(progress(stories));
                         return { status: 'paused', iterations, finalProgress: progress(stories) };
                     }
                     const reason = repairBlockReason(repairOutcome, story, opts.targetDir, opts.git);
                     if (reason) {
                         result.routing?.recordOutcome(false);
-                        reporter.blocked(reason);
-                        return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+                        reporter.blocked(reason, repairOutcome.failure);
+                        return { status: 'blocked', iterations, reason, ...(repairOutcome.failure ? { failure: repairOutcome.failure } : {}), finalProgress: progress(stories) };
                     }
                 }
                 const protection = acceptanceProtectionProblem(wt, opts.targetDir);
@@ -431,9 +448,11 @@ export function runLoop(opts) {
                 opts.git.commitAll(wt, `yoke: complete ${story.id} ${story.title}`, opts.commitIdentity);
                 opts.git.integrate(opts.targetDir, wt);
                 result.routing?.recordOutcome(true);
+                clearFailureProgress(opts.targetDir, story.id);
                 landed = progress(updated);
             }
             catch (e) {
+                activeRouting?.recordOutcome(false, 'infrastructure');
                 const reason = blockReason(`isolated iteration failed for ${story.id}: ${e.message}`, opts.targetDir, opts.git);
                 reporter.blocked(reason);
                 return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
@@ -452,89 +471,84 @@ export function runLoop(opts) {
                 reporter.storyDone({ id: story.id, title: story.title }, landed);
             continue;
         }
-        const result = runImplementation(opts, opts.targetDir, story, reporter);
+        const implementation = runImplementation(opts, opts.targetDir, story, reporter);
+        const result = implementation.result;
         iterations++;
         if (result.tokens)
             reporter.addTokens(result.tokens);
         if (result.infrastructureFailure || result.routing?.blocked) {
             if (result.infrastructureFailure)
                 result.routing?.recordOutcome(false, "infrastructure");
-            reporter.blocked(result.summary);
-            return { status: "blocked", iterations, reason: result.summary, finalProgress: progress(stories) };
+            reporter.blocked(result.summary, implementation.failure);
+            return { status: "blocked", iterations, reason: result.summary, ...(implementation.failure ? { failure: implementation.failure } : {}), finalProgress: progress(stories) };
         }
         let decision;
         try {
             decision = consumeDecisionRequest(opts.targetDir, opts.targetDir, story.id);
         }
         catch (error) {
+            result.routing?.recordOutcome(false, 'infrastructure');
             const reason = `invalid critical decision request for story ${story.id}: ${error.message}`;
             reporter.blocked(reason);
             return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
         }
         if (decision) {
+            result.routing?.recordOutcome(false, 'infrastructure');
             const reason = `critical decision required for story ${story.id}: ${decision.question}`;
             reporter.blocked(reason);
             return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
         }
         const ambiguity = consumeAmbiguity(opts.targetDir);
         if (ambiguity) {
+            result.routing?.recordOutcome(false, 'infrastructure');
             const reason = `story ${story.id} stopped: ambiguous acceptance criteria — ${ambiguity}`;
             reporter.blocked(reason);
             return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
         }
-        const criteriaVerdict = runCriterionGates(opts, opts.targetDir, story);
+        const verified = reuseGates(opts.targetDir, story, implementation.gates);
+        const criteriaVerdict = verified?.criteria ?? runCriterionGates(opts, opts.targetDir, story);
         if (!criteriaVerdict.passed) {
             result.routing?.recordOutcome(false);
             const reason = blockReason(`story ${story.id} lacks acceptance evidence: ${criteriaVerdict.summary}`, opts.targetDir, opts.git);
-            reporter.blocked(reason);
-            return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+            return blockedMechanicalGate(opts, opts.targetDir, story, 'criterion', criteriaVerdict.summary, reason, iterations, 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');
-        const verdict = runGate(opts.verify, opts.targetDir, story.id);
+        const verdict = verified?.verify ?? runGate(opts.verify, opts.targetDir, story.id);
         if (!verdict.passed) {
             result.routing?.recordOutcome(false);
             const base = result.success
                 ? `story ${story.id} did not verify: ${verdict.summary}`
                 : `story ${story.id} runner failed (${result.summary}) and verify is red: ${verdict.summary}`;
             const reason = blockReason(base, opts.targetDir, opts.git);
-            reporter.blocked(reason);
-            return {
-                status: 'blocked',
-                iterations,
-                reason,
-                finalProgress: progress(stories),
-            };
+            return blockedMechanicalGate(opts, opts.targetDir, story, 'verify', verdict.summary, reason, iterations, stories);
         }
         if (opts.design) {
             reporter.phase('design');
-            const designVerdict = runGate(opts.design, opts.targetDir, story.id);
+            const designVerdict = verified?.design ?? runGate(opts.design, opts.targetDir, story.id);
             if (!designVerdict.passed) {
                 result.routing?.recordOutcome(false);
                 const reason = blockReason(`story ${story.id} failed its design gate: ${designVerdict.summary}`, opts.targetDir, opts.git);
-                reporter.blocked(reason);
-                return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+                return blockedMechanicalGate(opts, opts.targetDir, story, 'design', designVerdict.summary, reason, iterations, stories);
             }
         }
         if (opts.perf) {
             reporter.phase('perf');
-            const perfVerdict = runGate(opts.perf, opts.targetDir, story.id);
+            const perfVerdict = verified?.perf ?? runGate(opts.perf, opts.targetDir, story.id);
             if (!perfVerdict.passed) {
                 result.routing?.recordOutcome(false);
                 const reason = blockReason(`story ${story.id} exceeded its performance budget: ${perfVerdict.summary}`, opts.targetDir, opts.git);
-                reporter.blocked(reason);
-                return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+                return blockedMechanicalGate(opts, opts.targetDir, story, 'perf', perfVerdict.summary, reason, iterations, stories);
             }
         }
         if (opts.audit) {
             reporter.phase('audit');
-            const auditVerdict = runGate(opts.audit, opts.targetDir, story.id);
+            const auditVerdict = verified?.audit ?? runGate(opts.audit, opts.targetDir, story.id);
             if (!auditVerdict.passed) {
                 result.routing?.recordOutcome(false);
                 const reason = blockReason(`story ${story.id} failed security audit: ${auditVerdict.summary}`, opts.targetDir, opts.git);
-                reporter.blocked(reason);
-                return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+                return blockedMechanicalGate(opts, opts.targetDir, story, 'audit', auditVerdict.summary, reason, iterations, stories);
             }
         }
         const summary = result.success
@@ -543,17 +557,19 @@ export function runLoop(opts) {
         const repairOutcome = runQualityReview(opts, opts.targetDir, story, reporter);
         if (repairOutcome) {
             if (repairOutcome.kind === 'paused') {
+                result.routing?.recordOutcome(false, 'infrastructure');
                 reporter.paused(progress(stories));
                 return { status: 'paused', iterations, finalProgress: progress(stories) };
             }
             const reason = repairBlockReason(repairOutcome, story, opts.targetDir, opts.git);
             if (reason) {
                 result.routing?.recordOutcome(false);
-                reporter.blocked(reason);
+                reporter.blocked(reason, repairOutcome.failure);
                 return {
                     status: 'blocked',
                     iterations,
                     reason,
+                    ...(repairOutcome.failure ? { failure: repairOutcome.failure } : {}),
                     finalProgress: progress(stories),
                 };
             }
@@ -564,7 +580,6 @@ export function runLoop(opts) {
             reporter.blocked(protection);
             return { status: 'blocked', iterations, reason: protection, finalProgress: progress(stories) };
         }
-        result.routing?.recordOutcome(true);
         reporter.phase('committing');
         const dec = appendDecision(contextDir(opts.targetDir), {
             storyId: story.id,
@@ -581,6 +596,7 @@ export function runLoop(opts) {
             opts.git.commitAll(opts.targetDir, `yoke: complete ${story.id} ${story.title}`, opts.commitIdentity);
         }
         catch (e) {
+            result.routing?.recordOutcome(false, 'infrastructure');
             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);
@@ -592,38 +608,56 @@ export function runLoop(opts) {
                 finalProgress: progress(stories),
             };
         }
+        result.routing?.recordOutcome(true);
+        clearFailureProgress(opts.targetDir, story.id);
         reporter.storyDone({ id: story.id, title: story.title }, progress(updated));
     }
 }
+function blockedMechanicalGate(opts, directory, story, stage, summary, reason, iterations, stories) {
+    const observed = observeFailure({ root: opts.targetDir, directory, story, stage, summary });
+    const detail = observed.action === 'retry' ? reason : `${reason}\n${observed.feedback}`;
+    (opts.reporter ?? noopReporter).blocked(detail, observed.failure);
+    return { status: 'blocked', iterations, reason: detail, failure: observed.failure, finalProgress: progress(stories) };
+}
 function runImplementation(opts, dir, story, reporter) {
-    let feedback;
+    let feedback = opts.feedback;
     for (let attempt = 0;; attempt++) {
         const result = opts.runner({ targetDir: dir, story, feedback });
         if (!result.routing?.canRetry || result.routing.blocked || attempt >= 7)
-            return result;
+            return { result };
         if (["decision-request.yaml", "ambiguity.md", "loop.pause"].some(name => existsSync(join(dir, ".yoke", name))) || existsSync(pauseFilePath(opts.targetDir)))
-            return result;
+            return { result };
         const protection = acceptanceProtectionProblem(dir, opts.targetDir);
         if (protection)
-            return result;
+            return { result };
+        const before = gateIdentity(dir, story);
         const criteria = runCriterionGates(opts, dir, story);
-        const gates = [opts.verify, opts.design, opts.perf, opts.audit].filter((gate) => Boolean(gate));
+        const evidence = { criteria };
         let verdict = criteria;
+        let failedStage = 'criterion';
         if (verdict.passed)
-            for (const gate of gates) {
+            for (const name of ['verify', 'design', 'perf', 'audit']) {
+                const gate = opts[name];
+                if (!gate)
+                    continue;
                 verdict = runGate(gate, dir, story.id);
+                failedStage = name;
+                evidence[name] = verdict;
                 if (!verdict.passed)
                     break;
             }
         if (verdict.passed)
-            return result;
+            return { result, gates: snapshotGates(dir, story, before, evidence) };
         if (knownInfrastructureFailure(verdict.summary)) {
             result.routing.recordOutcome(false, 'infrastructure');
-            return { ...result, success: false, infrastructureFailure: true, summary: verdict.summary, routing: { ...result.routing, blocked: true, canRetry: false } };
+            return { result: { ...result, success: false, infrastructureFailure: true, summary: verdict.summary, routing: { ...result.routing, blocked: true, canRetry: false } } };
         }
         result.routing.recordOutcome(false);
+        const observed = observeFailure({ root: opts.targetDir, directory: dir, story, stage: failedStage, summary: verdict.summary });
+        if (observed.action === 'blocked')
+            return { result: { ...result, success: false, summary: observed.feedback, routing: { ...result.routing, blocked: true, canRetry: false } }, failure: observed.failure };
         if (result.tokens)
             reporter.addTokens(result.tokens);
-        feedback = verdict.summary;
+        feedback = observed.feedback;
     }
 }

package/dist/loop/parallel-adapters.js

@@ -62,11 +62,11 @@ function productionAdapters(targetDir, identity) {
                 return { path, baseCommit };
             },
             cleanupProcess: cleanupProviderProcesses,
-            retain: (input, reason) => {
+            retain: (input, reason, phase = 'integration') => {
                 const file = recoveryPath(targetDir, input.story.id);
                 // Preserve the path's original ownership identity when a retry is rejected again.
                 const ownerToken = ownershipTokens.get(input.worktree.path) ?? input.ownerToken;
-                retainParallelWorktree(targetDir, file, { storyId: input.story.id, worktree: input.worktree.path, baseCommit: input.worktree.baseCommit, prdHash: acceptanceDigests.get(input.story.id), ownerToken, reason });
+                retainParallelWorktree(targetDir, file, { storyId: input.story.id, worktree: input.worktree.path, baseCommit: input.worktree.baseCommit, prdHash: acceptanceDigests.get(input.story.id), ownerToken, reason, phase });
             },
             remove: input => {
                 removeOwnedWorktree(targetDir, input, owned, removed, realGitOps);
@@ -81,13 +81,14 @@ function productionAdapters(targetDir, identity) {
             commit: input => realGitOps.commitAll(input.worktree.path, `yoke: complete ${input.story.id} ${input.story.title}`, identity),
             integrate: (input, expectedHead) => integrateCandidate(targetDir, input, expectedHead),
         },
-        candidates: primary => makeCandidateLifecycle(targetDir, primary, owned, removed, realGitOps, ownershipTokens),
+        candidates: primary => makeCandidateLifecycle(targetDir, primary, owned, removed, realGitOps, ownershipTokens, acceptanceDigests.get(primary.story.id)),
     };
 }
 function cleanupProviderProcesses(input) {
     reapProviderProcesses(input.worktree.path, isPidAlive, isProviderTreeAlive, killProcessTreeForCleanup);
 }
-function makeCandidateLifecycle(targetDir, primary, owned, removed, git, ownershipTokens) {
+function makeCandidateLifecycle(targetDir, primary, owned, removed, git, ownershipTokens, acceptanceDigest) {
+    const retainedRecords = new Map();
     return {
         reserve: input => {
             const worktree = input.candidateId === 'candidate-1'
@@ -114,6 +115,23 @@ function makeCandidateLifecycle(targetDir, primary, owned, removed, git, ownersh
         reap: ownership => {
             reapProviderProcesses(ownership.worktree.path, isPidAlive, isProviderTreeAlive, killProcessTreeForCleanup);
         },
+        ...(ownershipTokens && acceptanceDigest ? {
+            retain: (ownership, reason, phase) => {
+                // The first retained candidate resumes through the existing dispatcher recovery path.
+                // Additional alternatives remain inspectable without creating a second scheduler.
+                const ownerToken = ownershipTokens.get(ownership.worktree.path) ?? ownership.ownerToken;
+                const suffix = createHash('sha256').update(ownerToken).digest('hex').slice(0, 24);
+                const file = retainedRecords.get(ownership.worktree.path) ?? (retainedRecords.size === 0
+                    ? recoveryPath(targetDir, ownership.storyId)
+                    : statePath(targetDir, 'integration-recovery', `${storyPathSegment(ownership.storyId)}-candidate-${suffix}.json`));
+                retainedRecords.set(ownership.worktree.path, file);
+                retainParallelWorktree(targetDir, file, {
+                    storyId: ownership.storyId, worktree: ownership.worktree.path, baseCommit: ownership.worktree.baseCommit,
+                    prdHash: acceptanceDigest, ownerToken, reason, phase,
+                });
+                writeCandidateStatus(targetDir, ownership, ownership.worktree.path, 'retained', reason);
+            },
+        } : {}),
         remove: ownership => {
             removeOwnedWorktree(targetDir, ownership, owned, removed, git);
             writeCandidateStatus(targetDir, ownership, ownership.worktree.path, 'removed');

package/dist/loop/parallel-command.js

@@ -1,4 +1,5 @@
 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,6 +13,7 @@ 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;
     input = { ...input, verify: path => {
@@ -96,6 +98,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 +130,29 @@ 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}`;
+        }
+        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 +161,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 +204,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 +314,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 +365,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 };