@hecer/yoke 1.20.0 → 1.22.0

package/dist/loop/candidate-cleanup.js

@@ -17,6 +17,8 @@ export class CandidateCleanup {
     }
     cancelNow(reason) {
         for (const state of this.#states.values()) {
+            if (state.completed.has('remove') || state.completed.has('retain'))
+                continue;
             state.ownership.controller.abort(reason);
             this.onLifecycle?.(state.ownership, 'cleaning', reason);
             void this.#runStage(state, 'cancel', () => this.lifecycle.cancel(state.ownership, reason));
@@ -26,6 +28,8 @@ export class CandidateCleanup {
         const state = this.#states.get(ownership.candidateId);
         if (!state)
             return;
+        if (state.preserve)
+            return this.preserve(ownership, reason, state.preserve);
         ownership.controller.abort(reason);
         this.onLifecycle?.(ownership, 'cleaning', reason);
         if (!await this.#runStage(state, 'cancel', () => this.lifecycle.cancel(ownership, reason)))
@@ -41,6 +45,29 @@ export class CandidateCleanup {
                 await this.cleanup(state.ownership, reason);
         }
     }
+    async preserve(ownership, reason, phase) {
+        const state = this.#states.get(ownership.candidateId);
+        if (!state || state.completed.has('remove') || state.completed.has('retain'))
+            return;
+        if (!this.lifecycle.retain || !state.materialized)
+            return this.cleanup(ownership, reason);
+        state.preserve = phase;
+        ownership.controller.abort(reason);
+        if (!await this.#runStage(state, 'cancel', () => this.lifecycle.cancel(ownership, reason)))
+            return;
+        if (!await this.#runStage(state, 'reap', () => this.lifecycle.reap(ownership)))
+            return;
+        if (await this.#runStage(state, 'retain', () => this.lifecycle.retain(ownership, reason, phase)))
+            this.onLifecycle?.(ownership, 'retained', reason);
+    }
+    async preserveAll(reason, phase) {
+        for (const state of this.#states.values())
+            await this.preserve(state.ownership, reason, phase(state.ownership.candidateId));
+    }
+    retainedSummary() {
+        const paths = [...this.#states.values()].filter(state => state.completed.has('retain')).map(state => state.ownership.worktree.path);
+        return paths.length ? `; work retained at ${paths.join(', ')}` : '';
+    }
     hasFailures() {
         return [...this.#states.values()].some(state => state.failed.size > 0);
     }
@@ -48,23 +75,26 @@ export class CandidateCleanup {
         return this.recovery().flatMap(item => item.failedStages.map(failure => `${item.ownership.candidateId}:${failure.stage}: ${failure.summary}`)).join('; ');
     }
     recovery() {
-        return [...this.#states.values()].filter(state => state.failed.size > 0).map(state => ({
-            ownership: {
-                candidateId: state.ownership.candidateId,
-                coordinatorId: state.ownership.coordinatorId,
-                ownerToken: state.ownership.ownerToken,
-                storyId: state.ownership.storyId,
-                provider: { ...state.ownership.provider },
-                worktree: { ...state.ownership.worktree },
-            },
-            materialized: state.materialized,
-            completedStages: stageOrder.filter(stage => state.completed.has(stage)),
-            failedStages: stageOrder.flatMap(stage => {
-                const summary = state.failed.get(stage);
-                return summary ? [{ stage, summary }] : [];
-            }),
-            pendingStages: stageOrder.filter(stage => !state.completed.has(stage) && !state.failed.has(stage)),
-        }));
+        return [...this.#states.values()].filter(state => state.failed.size > 0).map(state => {
+            const stages = state.preserve ? ['cancel', 'reap', 'retain'] : stageOrder;
+            return {
+                ownership: {
+                    candidateId: state.ownership.candidateId,
+                    coordinatorId: state.ownership.coordinatorId,
+                    ownerToken: state.ownership.ownerToken,
+                    storyId: state.ownership.storyId,
+                    provider: { ...state.ownership.provider },
+                    worktree: { ...state.ownership.worktree },
+                },
+                materialized: state.materialized,
+                completedStages: stages.filter(stage => state.completed.has(stage)),
+                failedStages: stages.flatMap(stage => {
+                    const summary = state.failed.get(stage);
+                    return summary ? [{ stage, summary }] : [];
+                }),
+                pendingStages: stages.filter(stage => !state.completed.has(stage) && !state.failed.has(stage)),
+            };
+        });
     }
     #runStage(state, stage, operation) {
         if (state.completed.has(stage))

package/dist/loop/candidates.js

@@ -16,6 +16,7 @@ export async function coordinateCandidates(input) {
     const owned = [];
     const outcomes = new Map();
     const cleanup = new CandidateCleanup(input.lifecycle, input.onLifecycle);
+    const preserveAll = (reason) => cleanup.preserveAll(reason, id => outcomes.get(id)?.kind === 'candidate' ? 'integration' : 'implementation');
     const terminalize = async (candidate, reason) => {
         const result = outcomes.get(candidate.candidateId) ?? {
             kind: 'cancelled', storyId: candidate.storyId, worktree: candidate.worktree.path,
@@ -37,11 +38,11 @@ export async function coordinateCandidates(input) {
     input.signal?.addEventListener('abort', cancelActive, { once: true });
     const finishPaused = async () => {
         await terminalizeAll('candidate coordination paused');
-        await cleanup.cleanupAll('candidate coordination paused');
+        await preserveAll('candidate coordination paused');
         ensureActive();
         return cleanup.hasFailures()
             ? blocked(cleanup, 'cleanup-error', 'candidate pause cleanup failed')
-            : { kind: 'paused', summary: 'candidate coordination paused' };
+            : { kind: 'paused', summary: `candidate coordination paused${cleanup.retainedSummary()}` };
     };
     try {
         const paths = new Set();
@@ -91,7 +92,8 @@ export async function coordinateCandidates(input) {
                 case 'review-failure':
                     input.onLifecycle?.(run.owned, 'cleaning', run.result.summary);
                     await input.recordElimination?.({ ...run.owned, result: run.result });
-                    await cleanup.cleanup(run.owned, run.result.summary);
+                    if (!input.lifecycle.retain)
+                        await cleanup.cleanup(run.owned, run.result.summary);
                     ensureActive();
                     break;
                 case 'paused':
@@ -101,8 +103,11 @@ export async function coordinateCandidates(input) {
         ensureActive();
         if (input.pause?.())
             return await finishPaused();
-        if (green.length === 0)
+        if (green.length === 0) {
+            if (input.lifecycle.retain)
+                await preserveAll('no candidate passed every mechanical gate');
             return blocked(cleanup, 'zero-green', 'no candidate passed every mechanical gate');
+        }
         for (const candidate of green)
             input.onLifecycle?.(candidate, 'selecting');
         input.onSelecting?.();
@@ -116,7 +121,8 @@ export async function coordinateCandidates(input) {
             ensureActive,
             discard: async (candidate) => {
                 await input.recordElimination?.(candidate);
-                await cleanup.cleanup(candidate, 'candidate was not selected');
+                if (!input.lifecycle.retain)
+                    await cleanup.cleanup(candidate, 'candidate was not selected');
             },
         });
         ensureActive();
@@ -125,7 +131,7 @@ export async function coordinateCandidates(input) {
         if (selection.kind === 'inconsistent') {
             for (const candidate of green)
                 await input.recordElimination?.({ ...candidate, result: candidate.result }, `selection-inconsistent: ${selection.reason}`);
-            await cleanup.cleanupAll(`candidate selection was inconsistent: ${selection.reason}`);
+            await preserveAll(`candidate selection was inconsistent: ${selection.reason}`);
             ensureActive();
             if (input.pause?.())
                 return await finishPaused();
@@ -144,7 +150,7 @@ export async function coordinateCandidates(input) {
         if (input.pause?.())
             return await finishPaused();
         if (cleanup.hasFailures()) {
-            await cleanup.cleanup(selection.candidate, 'candidate cleanup failed');
+            await cleanup.preserve(selection.candidate, 'candidate cleanup failed', 'integration');
             ensureActive();
             if (input.pause?.())
                 return await finishPaused();
@@ -163,13 +169,13 @@ export async function coordinateCandidates(input) {
         catch (proofError) {
             proofFailure = message(proofError);
         }
-        await cleanup.cleanupAll('candidate coordinator failed');
+        await preserveAll('candidate coordinator failed');
         if (proofFailure)
             return blocked(cleanup, 'cleanup-error', `candidate terminal proof failed: ${proofFailure}`);
         if (input.signal?.aborted) {
             return cleanup.hasFailures()
                 ? blocked(cleanup, 'cleanup-error', 'candidate cancellation cleanup failed')
-                : { kind: 'cancelled', summary: cancellationSummary(input.signal) };
+                : { kind: 'cancelled', summary: cancellationSummary(input.signal) + cleanup.retainedSummary() };
         }
         if (input.pause?.()) {
             try {
@@ -179,7 +185,7 @@ export async function coordinateCandidates(input) {
                 if (input.signal?.aborted) {
                     return cleanup.hasFailures()
                         ? blocked(cleanup, 'cleanup-error', 'candidate cancellation cleanup failed')
-                        : { kind: 'cancelled', summary: cancellationSummary(input.signal) };
+                        : { kind: 'cancelled', summary: cancellationSummary(input.signal) + cleanup.retainedSummary() };
                 }
                 return blocked(cleanup, 'coordinator-error', message(pauseError));
             }
@@ -224,5 +230,5 @@ function blocked(cleanup, reason, summary) {
     const recovery = cleanup.recovery();
     return cleanup.hasFailures()
         ? { kind: 'blocked', reason: 'cleanup-error', summary: cleanup.failureSummary(), recovery }
-        : { kind: 'blocked', reason, summary };
+        : { kind: 'blocked', reason, summary: summary + cleanup.retainedSummary() };
 }

package/dist/loop/cleanup.js

@@ -8,6 +8,7 @@ import { killProcessForCleanup, killProcessTreeForCleanup } from './watchdog.js'
 import { cleanupClaims } from './claims.js';
 import { clearStatus } from './reporter.js';
 import { discardParallelRecoveryRecords } from './recovery.js';
+import { listProjects } from '../dashboard/registry.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,
@@ -266,3 +267,102 @@ function markCandidateWorktreeRemoved(targetDir, worktree) {
         }
     }
 }
+export function pruneWorktrees(targetDir, opts = {}) {
+    const result = { targetDir, removed: [], failed: [] };
+    const wtDir = join(targetDir, '.yoke', 'worktrees');
+    const candidates = new Set();
+    if (existsSync(wtDir)) {
+        try {
+            for (const entry of readdirSync(wtDir, { withFileTypes: true })) {
+                if (entry.isDirectory())
+                    candidates.add(join(wtDir, entry.name));
+            }
+        }
+        catch { /* ignore read errors */ }
+    }
+    try {
+        const raw = execFileSync('git', ['worktree', 'list', '--porcelain'], { cwd: targetDir, stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8' });
+        const lines = raw.split(/\r?\n/);
+        for (const line of lines) {
+            if (line.startsWith('worktree ')) {
+                const wtPath = line.slice(9).trim();
+                if (wtPath.includes('.yoke/worktrees') || wtPath.includes('.yoke\\worktrees') || wtPath.includes('/.worktrees/') || wtPath.includes('\\.worktrees\\') || wtPath.includes('-story')) {
+                    candidates.add(wtPath);
+                }
+            }
+        }
+    }
+    catch { /* not a git repo or git error */ }
+    for (const wtPath of candidates) {
+        try {
+            try {
+                execFileSync('git', ['worktree', 'remove', '--force', wtPath], { cwd: targetDir, stdio: ['ignore', 'pipe', 'pipe'] });
+            }
+            catch {
+                if (existsSync(wtPath)) {
+                    rmSync(wtPath, { recursive: true, force: true });
+                }
+            }
+            markCandidateWorktreeRemoved(targetDir, wtPath);
+            result.removed.push(wtPath);
+        }
+        catch (e) {
+            result.failed.push(`${wtPath}: ${e.message}`);
+        }
+    }
+    try {
+        execFileSync('git', ['worktree', 'prune'], { cwd: targetDir, stdio: ['ignore', 'pipe', 'pipe'] });
+    }
+    catch { /* best-effort */ }
+    return result;
+}
+export function listWorktrees(targetDir) {
+    const wtDir = join(targetDir, '.yoke', 'worktrees');
+    const candidates = new Set();
+    if (existsSync(wtDir)) {
+        try {
+            for (const entry of readdirSync(wtDir, { withFileTypes: true })) {
+                if (entry.isDirectory())
+                    candidates.add(join(wtDir, entry.name));
+            }
+        }
+        catch { /* ignore read errors */ }
+    }
+    try {
+        const raw = execFileSync('git', ['worktree', 'list', '--porcelain'], { cwd: targetDir, stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8' });
+        const lines = raw.split(/\r?\n/);
+        for (const line of lines) {
+            if (line.startsWith('worktree ')) {
+                const wtPath = line.slice(9).trim();
+                if (wtPath.includes('.yoke/worktrees') || wtPath.includes('.yoke\\worktrees') || wtPath.includes('/.worktrees/') || wtPath.includes('\\.worktrees\\') || wtPath.includes('-story')) {
+                    candidates.add(wtPath);
+                }
+            }
+        }
+    }
+    catch { /* not a git repo or git error */ }
+    return [...candidates];
+}
+export function listFleetWorktrees() {
+    const projects = listProjects();
+    const results = {};
+    for (const proj of projects) {
+        if (proj.root && !proj.error && existsSync(proj.root)) {
+            const list = listWorktrees(proj.root);
+            if (list.length > 0) {
+                results[proj.name || proj.root] = list;
+            }
+        }
+    }
+    return results;
+}
+export function pruneFleetWorktrees(opts = {}) {
+    const projects = listProjects();
+    const fleetResults = {};
+    for (const proj of projects) {
+        if (proj.root && !proj.error && existsSync(proj.root)) {
+            fleetResults[proj.name || proj.root] = pruneWorktrees(proj.root, opts);
+        }
+    }
+    return fleetResults;
+}

package/dist/loop/dispatcher.js

@@ -1,4 +1,6 @@
+import { observeFailure, clearFailureProgress } from './failure.js';
 import { randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
 import { join, relative } from 'node:path';
 import { appendDecision, contextDir } from '../context/context.js';
 import { acquireClaim, heartbeatClaim, releaseClaim, requestClaimCancellation } from './claims.js';
@@ -76,6 +78,7 @@ export function createDispatcher(options) {
     const reopened = [];
     const failed = [];
     const failureReasons = new Map();
+    const failureDetails = new Map();
     const integrationBlocks = [];
     let iterations = 0;
     let providerIndex = 0;
@@ -144,6 +147,32 @@ export function createDispatcher(options) {
         removeWorktree: () => undefined,
         releaseClaim: releaseCandidateClaim,
     });
+    const cleanupProcessOnly = createWorkerCleanup({
+        cleanupProcess: options.worktrees.cleanupProcess,
+        removeWorktree: () => undefined,
+        releaseClaim: () => undefined,
+    });
+    const retainWorker = (input, reason, phase) => {
+        if (!options.worktrees.retain) {
+            if (input.worktree.recovered)
+                cleanupRetained(input);
+            else
+                cleanup(input);
+            return;
+        }
+        let recorded = false;
+        try {
+            // The trusted record must exist before relinquishing this worktree's claim.
+            options.worktrees.retain(input, reason, phase);
+            recorded = true;
+        }
+        finally {
+            if (recorded)
+                cleanupRetained(input);
+            else
+                cleanupProcessOnly(input);
+        }
+    };
     const persistPass = (input) => {
         if (!options.prdPath)
             return;
@@ -155,12 +184,23 @@ export function createDispatcher(options) {
     const enqueue = (input, result) => {
         let reason = 'integrated verification failed';
         let retained = false;
+        let retentionRecorded = false;
         let recoveryBaseCommit = input.worktree.baseCommit;
         const integrationQueuedAt = Date.now();
         let integrationStartedAt;
         const integrationController = new AbortController();
         integrationControllers.set(input.story.id, integrationController);
         let integrationLease;
+        let routingSettled = false;
+        const settleRouting = (verified, failureKind) => {
+            if (routingSettled)
+                return;
+            routingSettled = true;
+            if (failureKind)
+                result.routing.recordOutcome?.(verified, failureKind);
+            else
+                result.routing.recordOutcome?.(verified);
+        };
         const task = queue.enqueue({
             storyId: input.story.id,
             rebase: async () => {
@@ -213,27 +253,36 @@ export function createDispatcher(options) {
                     input.story.passes = true;
                     integrated.push(input.story.id);
                     options.onAccepted?.(input.story);
-                    result.routing.recordOutcome?.(true);
+                    settleRouting(true);
+                    clearFailureProgress(options.targetDir, input.story.id);
                     return;
                 case 'integrated-but-blocked':
                     input.story.passes = true;
                     integrated.push(input.story.id);
                     options.onAccepted?.(input.story);
                     integrationBlocks.push(merge.reason);
-                    result.routing.recordOutcome?.(true);
+                    settleRouting(true);
+                    clearFailureProgress(options.targetDir, input.story.id);
                     return;
                 case 'reopened':
                     reopened.push(input.story.id);
                     reason = merge.reason;
+                    const observed = existsSync(input.worktree.path) ? observeFailure({ root: options.targetDir, directory: input.worktree.path, story: input.story, stage: 'integration', summary: reason }) : undefined;
+                    if (observed) {
+                        failureDetails.set(input.story.id, observed.failure);
+                        if (observed.action !== 'retry')
+                            reason = observed.feedback;
+                    }
                     if (options.worktrees.retain) {
                         // Retain first, then report/release. Recovery evidence must precede cleanup.
                         retained = true;
-                        options.worktrees.retain({ ...input, worktree: { ...input.worktree, baseCommit: recoveryBaseCommit } }, reason);
+                        options.worktrees.retain({ ...input, worktree: { ...input.worktree, baseCommit: recoveryBaseCommit } }, reason, observed && observed.action !== 'retry' ? 'implementation' : 'integration');
+                        retentionRecorded = true;
                         failed.push(input.story.id);
                         failureReasons.set(input.story.id, `${reason}; candidate retained at ${input.worktree.path}`);
                     }
                     options.onReopened?.(input.story, { reason, worktree: input.worktree.path, baseCommit: recoveryBaseCommit, ownerToken: input.ownerToken });
-                    result.routing.recordOutcome?.(false);
+                    settleRouting(false, cancellationReason ? 'infrastructure' : undefined);
                     return;
                 default: {
                     const unexpected = merge;
@@ -241,20 +290,29 @@ export function createDispatcher(options) {
                 }
             }
         }).finally(async () => {
-            queued.delete(input.story.id);
-            integrationControllers.delete(input.story.id);
-            options.gates.integrationPhase?.(input, undefined);
+            // A thrown gate/retention operation also terminates this measured attempt;
+            // recovery retains code, but cannot resurrect an in-memory outcome callback.
             try {
-                if (integrationLease)
-                    await integrationLease.release();
-                options.onIntegrationMetrics?.(input, Date.now() - integrationQueuedAt, integrationStartedAt === undefined ? undefined : Date.now() - integrationStartedAt);
+                settleRouting(false, 'infrastructure');
             }
             finally {
-                if (retained)
-                    cleanupRetained(input);
-                else
-                    cleanup(input);
-                reportProgress();
+                queued.delete(input.story.id);
+                integrationControllers.delete(input.story.id);
+                try {
+                    options.gates.integrationPhase?.(input, undefined);
+                    if (integrationLease)
+                        await integrationLease.release();
+                    options.onIntegrationMetrics?.(input, Date.now() - integrationQueuedAt, integrationStartedAt === undefined ? undefined : Date.now() - integrationStartedAt);
+                }
+                finally {
+                    if (retained && retentionRecorded)
+                        cleanupRetained(input);
+                    else if (retained)
+                        cleanupProcessOnly(input);
+                    else
+                        cleanup(input);
+                    reportProgress();
+                }
             }
         });
         queued.set(input.story.id, task);
@@ -274,7 +332,7 @@ export function createDispatcher(options) {
             return;
         }
         const controller = new AbortController();
-        const candidateRace = Boolean(options.candidateCount && options.candidateCount > 1 && options.candidateCoordinator);
+        const candidateRace = Boolean(!worktree.recovered && options.candidateCount && options.candidateCount > 1 && options.candidateCoordinator);
         const input = { story, worktree, provider, cancellation: { signal: controller.signal }, dispatcherId, ownerToken, ...(candidateRace ? { candidateRace: true } : {}) };
         if (!claims.acquire(input)) {
             if (!worktree.recovered)
@@ -286,6 +344,7 @@ export function createDispatcher(options) {
         if (story.area)
             areas.add(story.area);
         const candidateDispatch = candidateRace;
+        let workerStarted = false;
         const activeWorker = { input, controller, task: Promise.resolve(), phase: options.acquireResource ? 'waiting-resource' : 'implementing' };
         // Durable admission reporting must succeed before the worker microtask can start.
         active.set(story.id, activeWorker);
@@ -309,11 +368,12 @@ export function createDispatcher(options) {
             try {
                 if (worktree.recovered)
                     options.worktrees.cleanupProcess?.(input);
-                if (worktree.recovered)
+                if (worktree.recovered && worktree.recovery?.phase !== 'implementation')
                     return { source: 'worker', result: {
                             kind: 'candidate', storyId: story.id, worktree: worktree.path, baseCommit: worktree.baseCommit,
                             provider, summary: 'retained candidate recovered for independent integration checks', evidence: { criteria: [] }, routing: { outcome: 'pending-integration' },
                         } };
+                workerStarted = true;
                 return await (candidateDispatch && options.candidateCoordinator
                     ? Promise.resolve(options.candidateCoordinator(input)).then(coordinateCandidates).then(result => ({ source: 'candidates', result }))
                     : options.worker(input).then(result => ({ source: 'worker', result })));
@@ -362,26 +422,27 @@ export function createDispatcher(options) {
             if (result.kind === 'paused') {
                 if (result.reason === 'decision')
                     cancel(`critical decision required for story ${input.story.id}: ${result.summary}`);
+                else if (result.reason === 'ambiguity')
+                    cancel(`ambiguity requires resolution for story ${input.story.id}: ${result.summary}`);
                 else
                     paused = true;
-                cleanup(input);
+                retainWorker(input, result.summary, 'implementation');
                 reportProgress();
                 return;
             }
             if (result.kind !== 'candidate') {
                 failed.push(story.id);
                 failureReasons.set(story.id, result.summary);
-                cleanup(input);
+                if (result.failure)
+                    failureDetails.set(story.id, result.failure);
+                retainWorker(input, result.summary, 'implementation');
                 reportProgress();
                 return;
             }
             if (cancellationReason || paused || options.pause?.()) {
                 paused = true;
-                result.routing.recordOutcome?.(false);
-                if (input.worktree.recovered)
-                    cleanupRetained(input);
-                else
-                    cleanup(input);
+                result.routing.recordOutcome?.(false, 'infrastructure');
+                retainWorker(input, cancellationReason ?? 'paused after worker checks passed; integration is pending', 'integration');
                 reportProgress();
                 return;
             }
@@ -391,7 +452,9 @@ export function createDispatcher(options) {
             failed.push(story.id);
             failureReasons.set(story.id, error instanceof Error ? error.message : String(error));
             try {
-                if (input.worktree.recovered)
+                if (workerStarted && !candidateDispatch)
+                    retainWorker(input, error instanceof Error ? error.message : String(error), 'implementation');
+                else if (input.worktree.recovered)
                     cleanupRetained(input);
                 else
                     cleanup(input);
@@ -459,7 +522,7 @@ export function createDispatcher(options) {
             if (failed.length > 0) {
                 const storyId = failed[0];
                 const detail = storyId ? failureReasons.get(storyId) : undefined;
-                return { status: 'blocked', ...(storyId && detail ? { reason: `${reopened.includes(storyId) ? `story ${storyId} integration rejected` : `worker ${storyId} failed`}: ${detail}` } : {}), iterations, integrated, reopened, failed };
+                return { status: 'blocked', ...(storyId && failureDetails.has(storyId) ? { failure: failureDetails.get(storyId) } : {}), ...(storyId && detail ? { reason: `${reopened.includes(storyId) ? `story ${storyId} integration rejected` : `worker ${storyId} failed`}: ${detail}` } : {}), iterations, integrated, reopened, failed };
             }
             if (iterations >= options.maxIterations)
                 return { status: 'cap-reached', iterations, integrated, reopened, failed };

package/dist/loop/failure.js

@@ -0,0 +1,104 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { basename, dirname } from 'node:path';
+import { z } from 'zod';
+import { workspaceFingerprint } from '../workspace/fingerprint.js';
+import { statePath } from '../workspace/state.js';
+import { currentContractKey, readPlanningFile } from '../routing/contracts.js';
+const RecordSchema = z.object({
+    version: z.literal(1), fingerprint: z.string().regex(/^[a-f0-9]{64}$/u), signature: z.string().regex(/^[a-f0-9]{64}$/u),
+    repeats: z.number().int().min(1).max(1_000_000), summary: z.string().max(4096), updatedAt: z.string().datetime(),
+}).strict();
+function recordPath(root, storyId, scope) {
+    const key = createHash('sha256').update(JSON.stringify(storyId ?? null)).digest('hex');
+    const suffix = scope === undefined ? '' : `.${createHash('sha256').update(scope).digest('hex')}`;
+    return statePath(root, 'failure-progress', `${key}${suffix}.json`);
+}
+function stableFailureSummary(summary) {
+    return summary.replace(/\u001b\[[0-9;]*m/gu, '')
+        .replace(/\[(?:full|truncated) output:[^\]]*\]/gu, '[saved output]')
+        .replace(/\[… omitted; \d+ lines, \d+ bytes total …\]/gu, '[omitted output]')
+        .split(/\r?\n/u).map(line => {
+        // Known test-reporter metadata is not a different failure. Preserve
+        // assertion values, error codes and other numbers in diagnostic content.
+        if (/^\s*Start at\s+\d{2}:\d{2}:\d{2}\s*$/u.test(line))
+            return '';
+        if (/^\s*Duration\s+[\d.]+(?:ms|s)\s+\((?:transform|setup|collect|import|tests|environment|prepare)\b.*\)\s*$/u.test(line))
+            return '';
+        if (/^\s*Time:\s+[\d.]+\s*s(?:, estimated [\d.]+\s*s)?\s*$/u.test(line))
+            return '';
+        return /^\s*[✓✔✗✘×❯]\s/u.test(line) ? line.replace(/\s+[\d.]+(?:ms|s)\s*$/u, ' [duration]') : line;
+    }).join('\n').replace(/\s+/gu, ' ').trim().slice(0, 4096);
+}
+/** Per-story failure checkpoint, outside isolated workers and independent of provider. */
+export function observeFailure(input) {
+    const base = {
+        kind: input.stage === 'completion' ? 'completion-failed' : 'verification-failed',
+        stage: input.stage, ...(input.story ? { storyId: input.story.id } : {}),
+    };
+    try {
+        const file = recordPath(input.root, input.story?.id, input.scope);
+        let previous;
+        try {
+            const stat = lstatSync(file);
+            if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 16384)
+                throw Error('Invalid failure progress record');
+            previous = RecordSchema.parse(JSON.parse(readFileSync(file, 'utf8')));
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        // Use the same approved parent contract as durable routing reservations:
+        // a revised plan/upstream contract must unblock a retained, unchanged worker.
+        const contract = input.story ? currentContractKey(input.root, input.story) : readPlanningFile(input.root, '.yoke/plan.md', 80_000) ?? '';
+        const fingerprint = createHash('sha256').update(workspaceFingerprint(input.directory)).update(JSON.stringify(input.story ?? null)).update(contract).digest('hex');
+        const summary = stableFailureSummary(input.summary);
+        const signature = createHash('sha256').update(JSON.stringify([input.stage, summary])).digest('hex');
+        const repeats = previous?.fingerprint === fingerprint && previous.signature === signature ? Math.min(1_000_000, previous.repeats + 1) : 1;
+        const record = RecordSchema.parse({ version: 1, fingerprint, signature, repeats, summary, updatedAt: new Date().toISOString() });
+        mkdirSync(dirname(file), { recursive: true });
+        const temporary = statePath(input.root, 'failure-progress', `${randomUUID()}.tmp`);
+        try {
+            writeFileSync(temporary, JSON.stringify(record), { flag: 'wx', mode: 0o600 });
+            recordPath(input.root, input.story?.id, input.scope);
+            renameSync(temporary, file);
+        }
+        finally {
+            rmSync(temporary, { force: true });
+        }
+        const failure = { ...base, fingerprint, signature, repeats };
+        if (repeats >= 3)
+            return {
+                action: 'blocked', failure: { ...failure, kind: 'no-progress' },
+                feedback: `Stopped after ${repeats} unchanged failures at ${input.stage}. The diagnostic retry did not change the code, acceptance contract, or failure. Preserve this work and replan or resolve the blocker before automatic continuation. Last failure: ${input.summary}`,
+            };
+        if (repeats === 2)
+            return {
+                action: 'diagnose', failure,
+                feedback: `The same ${input.stage} failure occurred twice on unchanged code and acceptance. Before another edit, diagnose the root cause from the saved evidence and use a different, testable hypothesis; do not repeat the previous failed action. One diagnostic attempt remains.\n${input.summary}`,
+            };
+        return { action: 'retry', failure, feedback: input.summary };
+    }
+    catch (error) {
+        return { action: 'blocked', failure: { ...base, kind: 'no-progress' }, feedback: `Failure progress could not be verified; automatic continuation stopped: ${error instanceof Error ? error.message : String(error)}. Last failure: ${input.summary}` };
+    }
+}
+export function clearFailureProgress(root, storyId) {
+    const file = recordPath(root, storyId);
+    rmSync(file, { force: true });
+    let names;
+    try {
+        names = readdirSync(dirname(file));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    const prefix = `${basename(file, '.json')}.`;
+    for (const name of names) {
+        if (name.startsWith(prefix) && /^[a-f0-9]{64}\.json$/u.test(name.slice(prefix.length)))
+            rmSync(statePath(root, 'failure-progress', name), { force: true });
+    }
+}