@hecer/yoke 1.18.0 → 1.20.0

package/dist/goals/command.js

@@ -1,11 +1,11 @@
 import { loadConfig } from "../retrofit/config.js";
 import { makeAsyncAdaptiveRunner } from "../routing/router.js";
 import { resolvePlanner } from '../routing/planning.js';
-import { randomUUID } from 'node:crypto';
+import { randomUUID, createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, unlinkSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { z } from 'zod';
-import { acceptanceProtectionProblem, checkProject, loadAcceptance, protectAcceptance } from '../check/command.js';
+import { acceptanceProtectionProblem, checkProjectAsync, loadAcceptance, protectAcceptance } from '../check/command.js';
 import { acquireLock, releaseLock, isPidAlive } from '../loop/lock.js';
 import { reapProviderProcesses, isProviderTreeAlive } from '../loop/cleanup.js';
 import { killProcessTreeForCleanup } from '../loop/watchdog.js';
@@ -13,8 +13,43 @@ import { buildProviderInvocation, startProviderProcess } from '../agents/provide
 import { AgentSchema } from '../agents/contracts.js';
 import { appendEvent } from '../observability/events.js';
 import { statePath } from '../workspace/state.js';
+import { acquireSharedWorker } from '../loop/resource-pool.js';
+import { recordGoalRun } from '../loop/run-state.js';
+import { executeCodexGoal, synchronizeNativeGoal, NativeGoalUnavailableError } from './codex-native.js';
 const Attempt = z.object({ provider: AgentSchema, model: z.string().optional(), startedAt: z.string(), durationMs: z.number().nonnegative(), success: z.boolean(), summary: z.string(), checkId: z.string(), inputTokens: z.number().nonnegative().optional(), outputTokens: z.number().nonnegative().optional() });
-const Goal = z.object({ version: z.literal(1), id: z.string().uuid(), objective: z.string().trim().min(1).max(16000), status: z.enum(['active', 'running', 'paused', 'blocked', 'complete']), createdAt: z.string(), updatedAt: z.string(), maxAttempts: z.number().int().min(1).max(20), maxMinutes: z.number().positive().max(1440), tokenBudget: z.number().int().positive().optional(), attempts: z.array(Attempt), reason: z.string().optional(), lastCheck: z.string().optional(), pendingAttempt: z.object({ provider: AgentSchema, model: z.string().optional(), startedAt: z.string().datetime() }).optional() }).strict();
+const Goal = z.object({
+    version: z.literal(1), id: z.string().uuid(), objective: z.string().trim().min(1).max(16000),
+    status: z.enum(['active', 'running', 'paused', 'blocked', 'complete']), createdAt: z.string(), updatedAt: z.string(),
+    maxAttempts: z.number().int().min(1).max(20), maxMinutes: z.number().positive().max(1440),
+    maxWallMinutes: z.number().positive().max(10080).optional(), wallDurationMs: z.number().nonnegative().default(0),
+    tokenBudget: z.number().int().positive().optional(), attempts: z.array(Attempt), reason: z.string().optional(), lastCheck: z.string().optional(),
+    acceptanceBinding: z.object({ criterionIds: z.array(z.string()).min(1), manifestDigest: z.string().regex(/^[a-f0-9]{64}$/), objectiveDigest: z.string().regex(/^[a-f0-9]{64}$/) }).strict().optional(),
+    nativeBinding: z.object({ provider: z.literal('codex'), threadId: z.string().min(1), objectiveRevision: z.string().regex(/^[a-f0-9]{64}$/), modelProvider: z.string().optional(), model: z.string().optional(), usageInvalid: z.literal(true).optional(), usageBaseline: z.object({ inputTokens: z.number().int().nonnegative().safe(), outputTokens: z.number().int().nonnegative().safe(), cachedInputTokens: z.number().int().nonnegative().safe().optional(), cacheWriteInputTokens: z.number().int().nonnegative().safe().optional(), reasoningOutputTokens: z.number().int().nonnegative().safe().optional() }).strict().optional() }).strict().optional(),
+    nativeTokensUsed: z.number().nonnegative().optional(),
+    pendingRunStartedAt: z.string().datetime().optional(),
+    pendingAttempt: z.object({ provider: AgentSchema, model: z.string().optional(), startedAt: z.string().datetime() }).optional(),
+}).strict();
+const digest = (value) => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+function acceptanceBinding(root, objective, ids) {
+    const manifest = loadAcceptance(root);
+    if (!manifest || !ids.length || new Set(ids).size !== ids.length || ids.some(id => !manifest.criteria.some(c => c.id === id && c.commands.length)))
+        throw new Error('Bind a nonempty unique list of executable acceptance criteria');
+    return { criterionIds: ids, manifestDigest: digest(manifest), objectiveDigest: digest(objective) };
+}
+export function bindProjectGoal(root, ids) {
+    const lock = acquireLock(root);
+    if (!lock.acquired)
+        throw new Error('Project is busy');
+    try {
+        const goal = readProjectGoal(root);
+        if (!goal)
+            throw new Error('No project goal');
+        return save(root, { ...goal, acceptanceBinding: acceptanceBinding(root, goal.objective, ids) });
+    }
+    finally {
+        releaseLock(root, lock.ownerToken);
+    }
+}
 const goalPath = (root) => statePath(root, 'goal.json');
 function save(root, goal) {
     const parsed = Goal.parse({ ...goal, updatedAt: new Date().toISOString() });
@@ -50,7 +85,7 @@ export function createProjectGoal(root, objective, limits = {}) {
         const pause = statePath(root, 'goal.pause');
         if (existsSync(pause))
             unlinkSync(pause);
-        return save(root, Goal.parse({ version: 1, id: randomUUID(), objective, status: 'active', createdAt: now, updatedAt: now, maxAttempts: limits.maxAttempts ?? 3, maxMinutes: limits.maxMinutes ?? 30, tokenBudget: limits.tokenBudget, attempts: [] }));
+        return save(root, Goal.parse({ version: 1, id: randomUUID(), objective, status: 'active', createdAt: now, updatedAt: now, maxAttempts: limits.maxAttempts ?? 3, maxMinutes: limits.maxMinutes ?? 30, maxWallMinutes: limits.maxWallMinutes, tokenBudget: limits.tokenBudget, attempts: [], acceptanceBinding: limits.acceptanceIds ? acceptanceBinding(root, objective.trim(), limits.acceptanceIds) : undefined }));
     }
     finally {
         releaseLock(root, lock.ownerToken);
@@ -77,7 +112,7 @@ export function budgetProjectGoal(root, limits) {
         const goal = readProjectGoal(root);
         if (!goal)
             throw new Error('No project goal');
-        return save(root, { ...goal, maxAttempts: limits.maxAttempts ?? goal.maxAttempts, maxMinutes: limits.maxMinutes ?? goal.maxMinutes, tokenBudget: limits.clearTokenBudget ? undefined : limits.tokenBudget ?? goal.tokenBudget });
+        return save(root, { ...goal, maxAttempts: limits.maxAttempts ?? goal.maxAttempts, maxMinutes: limits.maxMinutes ?? goal.maxMinutes, maxWallMinutes: limits.maxWallMinutes ?? goal.maxWallMinutes, tokenBudget: limits.clearTokenBudget ? undefined : limits.tokenBudget ?? goal.tokenBudget });
     }
     finally {
         releaseLock(root, lock.ownerToken);
@@ -101,6 +136,8 @@ export function goalHandoff(root) {
 async function executeAgent(input) {
     const handle = startProviderProcess(input.provider, buildProviderInvocation(input.provider, input.prompt, input.root, 'safe', input.selection), { signal: input.signal, idleTimeoutMs: 20 * 60_000 });
     const result = await handle.completion;
+    if (handle.recordPath && existsSync(handle.recordPath))
+        throw Object.assign(new Error('Provider process cleanup could not be confirmed'), { cleanupUnconfirmed: true });
     return { success: result.kind === 'succeeded', summary: result.kind === 'succeeded' ? 'Agent finished; independently checked below' : `${result.kind}: ${result.stderr.slice(-3000)}`, ...result.telemetry.tokens, tokens: result.telemetry.tokens };
 }
 export async function runProjectGoal(root, options = {}) {
@@ -108,10 +145,62 @@ export async function runProjectGoal(root, options = {}) {
     if (!lock.acquired)
         throw new Error('Project is busy; goal and story loops share one lock');
     let goal = null;
+    let runStarted;
+    let wallAtStart = 0;
+    let wallTimer;
+    let pauseTimer;
+    let cleanupUnconfirmed = false;
+    let resolvedSelection;
+    let nativeEnabled = false;
+    const controller = new AbortController();
+    const tokensUsed = () => goal.attempts.reduce((sum, a) => sum + (a.inputTokens ?? 0) + (a.outputTokens ?? 0), 0);
+    const finish = async (status, reason, report) => {
+        if (status === 'paused' && existsSync(statePath(root, 'goal.pause')))
+            unlinkSync(statePath(root, 'goal.pause'));
+        if (goal.nativeBinding && nativeEnabled) {
+            const nativeStatus = status === 'complete' ? 'complete' : status === 'paused' ? 'paused' : /token/i.test(reason) ? 'budgetLimited' : 'blocked';
+            try {
+                const lease = await acquireSharedWorker({ targetDir: root, storyId: goal.id, provider: 'codex', role: 'integration', signal: AbortSignal.timeout(30_000) });
+                let retain = false;
+                try {
+                    await synchronizeNativeGoal({ root, binding: goal.nativeBinding, objective: goal.objective, status: nativeStatus, bare: resolvedSelection?.bare, signal: status === 'complete' ? AbortSignal.any([controller.signal, AbortSignal.timeout(30_000)]) : AbortSignal.timeout(30_000) });
+                }
+                catch (error) {
+                    const cleanup = error;
+                    retain = cleanup.cleanupUnconfirmed === true;
+                    if (retain)
+                        void cleanup.cleanupConfirmed?.then(() => lease.release()).catch(() => undefined);
+                    throw error;
+                }
+                finally {
+                    if (!retain)
+                        await lease.release();
+                }
+            }
+            catch (error) {
+                status = 'blocked';
+                reason += `; native state synchronization failed: ${error.message}`;
+            }
+        }
+        if (status === 'complete' && controller.signal.aborted) {
+            status = existsSync(statePath(root, 'goal.pause')) ? 'paused' : 'blocked';
+            reason = `${String(controller.signal.reason)}; verified work retained`;
+        }
+        if (status === 'paused' && existsSync(statePath(root, 'goal.pause')))
+            unlinkSync(statePath(root, 'goal.pause'));
+        goal = save(root, { ...goal, status, reason, lastCheck: report?.id ?? goal.lastCheck });
+        return goal;
+    };
     try {
         goal = readProjectGoal(root);
         if (!goal)
             throw new Error('Set a goal first');
+        if (options.expectedGoalId && goal.id !== options.expectedGoalId) {
+            goal = null;
+            throw new Error('Saved goal identity changed before resume');
+        }
+        if (goal.pendingRunStartedAt)
+            goal = save(root, { ...goal, wallDurationMs: goal.wallDurationMs + Math.max(0, Date.now() - Date.parse(goal.pendingRunStartedAt)), pendingRunStartedAt: undefined });
         // Exclusive project lock held. Reconcile only this project's recorded trees;
         // unknown ownership stays blocked rather than racing an orphaned worker.
         reapProviderProcesses(root, isPidAlive, isProviderTreeAlive, killProcessTreeForCleanup);
@@ -126,6 +215,10 @@ export async function runProjectGoal(root, options = {}) {
         const manifest = loadAcceptance(root);
         if (!manifest?.criteria.length || manifest.criteria.some(c => c.commands.length === 0) || !manifest.protected.length)
             return save(root, { ...goal, status: 'blocked', reason: 'Map every acceptance criterion to an executable command and explicitly protect its test infrastructure before running a goal' });
+        if (!goal.acceptanceBinding)
+            return save(root, { ...goal, status: 'blocked', reason: 'Bind this objective explicitly with goal bind --criteria=id1,id2 before running it' });
+        if (goal.acceptanceBinding.manifestDigest !== digest(manifest) || goal.acceptanceBinding.objectiveDigest !== digest(goal.objective))
+            return save(root, { ...goal, status: 'blocked', reason: 'Acceptance binding changed; review the objective and acceptance criteria before rebinding' });
         try {
             protectAcceptance(root);
         }
@@ -133,85 +226,193 @@ export async function runProjectGoal(root, options = {}) {
             if (error.code !== 'EEXIST')
                 throw error;
         }
-        const provider = options.provider ?? 'codex';
-        const rawExecute = options.execute ?? executeAgent;
         const config = loadConfig(root);
+        const provider = options.provider ?? config?.runner?.agent ?? 'codex';
+        const configured = config?.runner;
+        const selection = { provider: configured?.provider, model: configured?.model, reasoningEffort: configured?.reasoningEffort, variant: configured?.variant, bare: configured?.bare, ...Object.fromEntries(Object.entries(options.selection ?? {}).filter(([, value]) => value !== undefined)), nativeMultiAgent: false };
+        resolvedSelection = selection;
+        const native = options.native ?? config?.goals?.nativeCodex ?? false;
+        nativeEnabled = native;
+        if (native && provider === 'codex' && selection.bare) {
+            goal = save(root, { ...goal, status: 'blocked', reason: 'Native Codex app-server does not support bare startup; use --no-native-goal to retain bare execution or explicitly disable runner.bare' });
+            return goal;
+        }
+        recordGoalRun(root, goal.id, lock.ownerToken, { provider, selection, native });
+        wallAtStart = goal.wallDurationMs;
+        runStarted = Date.now();
+        if (goal.maxWallMinutes !== undefined) {
+            const remainingWall = goal.maxWallMinutes * 60_000 - wallAtStart;
+            if (remainingWall <= 0)
+                return await finish('blocked', 'Wall-time budget exhausted; unfinished work retained');
+            wallTimer = setTimeout(() => controller.abort('Wall-time budget exhausted'), remainingWall);
+        }
+        goal = save(root, { ...goal, pendingRunStartedAt: new Date(runStarted).toISOString() });
+        pauseTimer = setInterval(() => { if (existsSync(statePath(root, 'goal.pause')))
+            controller.abort('Pause requested'); }, 100);
+        let attemptAgentMs = 0;
+        const admitted = async (input, operation) => {
+            const queued = Date.now();
+            const lease = await acquireSharedWorker({ targetDir: root, storyId: goal.id, provider: input.provider, role: 'implementation', signal: input.signal });
+            const started = Date.now();
+            const remaining = goal.maxMinutes * 60_000 - goal.attempts.reduce((sum, a) => sum + a.durationMs, 0) - attemptAgentMs;
+            const timer = setTimeout(() => controller.abort('Goal agent-time budget exceeded'), Math.max(0, remaining));
+            try {
+                appendEvent(root, { runId: goal.id, timestamp: new Date().toISOString(), type: 'phase-ended', phase: 'resource-wait-implementation', durationMs: started - queued });
+                if (remaining <= 0 || input.signal.aborted)
+                    throw new Error('Goal execution cancelled or agent-time budget exhausted');
+                return await operation();
+            }
+            catch (error) {
+                const cleanup = error;
+                cleanupUnconfirmed ||= cleanup.cleanupUnconfirmed === true;
+                if (cleanup.cleanupUnconfirmed)
+                    void cleanup.cleanupConfirmed?.then(() => lease.release()).catch(() => undefined);
+                throw error;
+            }
+            finally {
+                clearTimeout(timer);
+                attemptAgentMs += Date.now() - started;
+                if (!cleanupUnconfirmed)
+                    await lease.release();
+            }
+        };
+        const rawExecute = async (input) => {
+            return admitted(input, async () => {
+                if (options.execute)
+                    return await options.execute(input);
+                if (native && input.provider === 'codex') {
+                    let binding = goal.nativeBinding;
+                    if (binding && (binding.model !== input.selection.model || binding.modelProvider !== input.selection.provider))
+                        binding = undefined;
+                    try {
+                        const result = await executeCodexGoal({ ...input, objective: goal.objective, tokenBudget: goal.tokenBudget === undefined ? undefined : goal.tokenBudget - tokensUsed(), binding, onBinding: (nativeBinding) => { goal = save(root, { ...goal, nativeBinding }); }, onUsageUpdate: (usage) => {
+                                if (goal.tokenBudget !== undefined && usage.inputTokens !== undefined && usage.outputTokens !== undefined && tokensUsed() + usage.inputTokens + usage.outputTokens > goal.tokenBudget)
+                                    controller.abort('Token budget exceeded during native execution');
+                            } });
+                        goal = save(root, { ...goal, nativeTokensUsed: result.nativeTokensUsed });
+                        return result;
+                    }
+                    catch (error) {
+                        if (!(error instanceof NativeGoalUnavailableError))
+                            throw error;
+                        goal = save(root, { ...goal, nativeBinding: undefined, nativeTokensUsed: undefined });
+                        appendEvent(root, { runId: goal.id, timestamp: new Date().toISOString(), type: 'status', data: { nativeGoal: 'unavailable', fallback: 'codex-exec' } });
+                    }
+                }
+                return await executeAgent(input);
+            });
+        };
         const execute = async (input) => {
             if (!config?.routing?.enabled || config.routing.strategy !== "capability")
                 return rawExecute(input);
             const routed = makeAsyncAdaptiveRunner({ parent: provider, parentSelection: input.selection, projectRoot: root, workers: config.routing.workers, strategy: "capability", maxCandidates: config.routing.maxCandidates, maxAttempts: Math.min(goal.maxAttempts, config.routing.maxAttempts ?? 5),
                 planner: resolvePlanner(config, provider, input.selection), fallback: config.routing.fallback, maxTier: config.routing.maxTier,
                 captureRoute: async (agent, context, prompt, selection) => {
-                    const run = await startProviderProcess(agent, buildProviderInvocation(agent, prompt, root, "read-only", selection), { signal: input.signal, idleTimeoutMs: 20 * 60_000 }).completion;
-                    return { success: run.kind === "succeeded", summary: run.kind, output: run.stdout, tokens: run.telemetry.tokens };
+                    return admitted({ ...input, provider: agent }, async () => {
+                        const handle = startProviderProcess(agent, buildProviderInvocation(agent, prompt, root, "read-only", { ...selection, nativeMultiAgent: false }), { signal: input.signal, idleTimeoutMs: 20 * 60_000 });
+                        const run = await handle.completion;
+                        if (handle.recordPath && existsSync(handle.recordPath))
+                            throw Object.assign(new Error('Planner process cleanup could not be confirmed'), { cleanupUnconfirmed: true });
+                        return { success: run.kind === "succeeded", summary: run.kind, output: run.stdout, tokens: run.telemetry.tokens };
+                    });
                 },
                 makeWorker: (agent, selection) => async (context) => {
-                    const result = await rawExecute({ ...input, provider: agent, selection, prompt: input.prompt + "\nPlanner approach:\n" + (context.story.assessment?.approach ?? "") });
+                    const result = await rawExecute({ ...input, provider: agent, selection: { ...selection, nativeMultiAgent: false }, prompt: input.prompt + "\nPlanner approach:\n" + (context.story.assessment?.approach ?? "") });
                     return { ...result, infrastructureFailure: !result.success, tokens: result.tokens ?? (result.inputTokens !== undefined && result.outputTokens !== undefined ? { inputTokens: result.inputTokens, outputTokens: result.outputTokens, model: result.model } : undefined) };
                 }, });
             const result = await routed({ targetDir: root, story: { id: goal.id, title: goal.objective, priority: 1, passes: false, agent: provider, acceptance: manifest.criteria.map(c => c.text) } });
             const last = result.tokens?.calls?.at(-1);
             return { ...result, provider: last?.provider ?? provider, model: last?.actualModel, inputTokens: result.tokens?.measurementComplete ? result.tokens.inputTokens : undefined, outputTokens: result.tokens?.measurementComplete ? result.tokens.outputTokens : undefined };
         };
-        let report = checkProject(root);
+        let report = await checkProjectAsync(root, { signal: controller.signal });
+        if (report.cleanupUnconfirmed) {
+            goal = save(root, { ...goal, status: 'blocked', reason: 'Verification cleanup could not be confirmed; retained resource ownership requires inspection', lastCheck: report.id });
+            return goal;
+        }
         while (report.status !== 'passed') {
             const protectionProblem = acceptanceProtectionProblem(root);
             if (protectionProblem)
-                return save(root, { ...goal, status: 'blocked', reason: protectionProblem, lastCheck: report.id });
+                return await finish('blocked', protectionProblem, report);
             const pause = statePath(root, 'goal.pause');
             if (existsSync(pause)) {
                 unlinkSync(pause);
-                return save(root, { ...goal, status: 'paused', lastCheck: report.id, reason: 'Paused at a safe attempt boundary' });
+                return await finish('paused', 'Paused at a safe attempt boundary', report);
             }
+            if (controller.signal.aborted)
+                return await finish('blocked', String(controller.signal.reason), report);
             const remaining = goal.maxMinutes * 60_000 - goal.attempts.reduce((sum, a) => sum + a.durationMs, 0);
             if (remaining <= 0 || goal.attempts.length >= goal.maxAttempts)
-                return save(root, { ...goal, status: 'blocked', lastCheck: report.id, reason: 'Execution budget exhausted; unfinished work retained' });
+                return await finish('blocked', 'Execution budget exhausted; unfinished work retained', report);
             if (goal.tokenBudget !== undefined && goal.attempts.length > 0) {
                 const unknown = goal.attempts.some(a => a.inputTokens === undefined || a.outputTokens === undefined);
                 const used = goal.attempts.reduce((sum, a) => sum + (a.inputTokens ?? 0) + (a.outputTokens ?? 0), 0);
                 if (unknown || used >= goal.tokenBudget)
-                    return save(root, { ...goal, status: 'blocked', reason: unknown ? 'Token usage unknown; cannot safely start another budgeted attempt' : 'Token budget exhausted' });
+                    return await finish('blocked', unknown ? 'Token usage unknown; cannot safely start another budgeted attempt' : 'Token budget exhausted', report);
             }
             const started = Date.now();
-            goal = save(root, { ...goal, status: 'running', lastCheck: report.id, reason: undefined, pendingAttempt: { provider, model: options.selection?.model, startedAt: new Date(started).toISOString() } });
-            const controller = new AbortController();
-            const timer = setTimeout(() => controller.abort('Goal time budget exceeded'), remaining);
+            goal = save(root, { ...goal, status: 'running', lastCheck: report.id, reason: undefined, pendingAttempt: { provider, model: selection.model, startedAt: new Date(started).toISOString() } });
+            attemptAgentMs = 0;
             let result;
             try {
-                result = await execute({ root, provider, selection: options.selection ?? {}, signal: controller.signal, prompt: `${goalHandoff(root)}\nCurrent independent findings:\n${JSON.stringify(report.criteria).slice(0, 12000)}` });
+                result = await execute({ root, provider, selection, signal: controller.signal, prompt: `${goalHandoff(root)}\nCurrent independent findings:\n${JSON.stringify(report.criteria).slice(0, 12000)}` });
             }
             catch (error) {
                 result = { success: false, summary: error.message };
             }
-            finally {
-                clearTimeout(timer);
+            const agentDurationMs = attemptAgentMs;
+            if (cleanupUnconfirmed) {
+                goal.attempts.push({ provider, model: selection.model, startedAt: new Date(started).toISOString(), durationMs: agentDurationMs, success: false, summary: result.summary, checkId: report.id });
+                goal = save(root, { ...goal, pendingAttempt: undefined, status: 'blocked', reason: 'Provider cleanup could not be confirmed; process record and resource reservation retained' });
+                return goal;
             }
-            const agentDurationMs = Date.now() - started;
             const checkStarted = Date.now();
-            report = checkProject(root);
+            report = await checkProjectAsync(root, { signal: controller.signal });
             if (!result.routing?.blocked)
                 result.routing?.recordOutcome(report.status === 'passed');
             appendEvent(root, { runId: goal.id, timestamp: new Date().toISOString(), type: 'phase-ended', phase: 'verify', durationMs: Date.now() - checkStarted, outcome: report.status });
-            goal.attempts.push({ provider: result.provider ?? provider, model: result.model ?? options.selection?.model, startedAt: new Date(started).toISOString(), durationMs: agentDurationMs, success: result.success, summary: result.summary.slice(0, 8000), checkId: report.id, inputTokens: result.inputTokens, outputTokens: result.outputTokens });
+            goal.attempts.push({ provider: result.provider ?? provider, model: result.model ?? selection.model, startedAt: new Date(started).toISOString(), durationMs: agentDurationMs, success: result.success, summary: result.summary.slice(0, 8000), checkId: report.id, inputTokens: result.inputTokens, outputTokens: result.outputTokens });
             const usageAvailable = result.inputTokens !== undefined && result.outputTokens !== undefined;
             appendEvent(root, { runId: goal.id, timestamp: new Date().toISOString(), type: 'tokens', attemptId: `${goal.id}:${goal.attempts.length}`, durationMs: agentDurationMs, data: { ...result.tokens, provider: result.provider ?? provider, role: 'parent', model: result.model, inputTokens: result.inputTokens, outputTokens: result.outputTokens, usageAvailable } });
             appendEvent(root, { runId: goal.id, timestamp: new Date().toISOString(), type: 'attempt-ended', attemptId: `${goal.id}:${goal.attempts.length}`, durationMs: Date.now() - started, outcome: report.status, data: { provider, model: result.model, usageAvailable } });
             if (report.status === 'passed')
                 appendEvent(root, { runId: goal.id, timestamp: new Date().toISOString(), type: 'accepted', attemptId: `${goal.id}:${goal.attempts.length}` });
             goal = save(root, { ...goal, lastCheck: report.id, pendingAttempt: undefined });
+            if (report.cleanupUnconfirmed) {
+                goal = save(root, { ...goal, status: 'blocked', reason: 'Verification cleanup could not be confirmed; process record and resource reservation retained' });
+                return goal;
+            }
             if (result.routing?.blocked)
-                return save(root, { ...goal, status: "blocked", reason: result.summary });
+                return await finish('blocked', result.summary, report);
             if (controller.signal.aborted)
-                return save(root, { ...goal, status: 'blocked', reason: 'Time budget exceeded; work retained' });
+                return await finish(existsSync(statePath(root, 'goal.pause')) ? 'paused' : 'blocked', `${String(controller.signal.reason)}; work retained`, report);
+            if (goal.tokenBudget !== undefined && (goal.attempts.some(a => a.inputTokens === undefined || a.outputTokens === undefined) || tokensUsed() > goal.tokenBudget))
+                return await finish('blocked', 'Token budget exhausted or usage unknown; work retained', report);
         }
-        return save(root, { ...goal, status: 'complete', lastCheck: report.id, reason: 'All executable acceptance checks passed on the current workspace' });
+        if (controller.signal.aborted)
+            return await finish(existsSync(statePath(root, 'goal.pause')) ? 'paused' : 'blocked', String(controller.signal.reason), report);
+        if (goal.tokenBudget !== undefined && goal.attempts.length && (goal.attempts.some(a => a.inputTokens === undefined || a.outputTokens === undefined) || tokensUsed() > goal.tokenBudget))
+            return await finish('blocked', 'Token budget exhausted or usage unknown; work retained', report);
+        return await finish('complete', 'All bound acceptance criteria and regression checks passed on the current workspace', report);
     }
     catch (error) {
         if (goal)
-            save(root, { ...goal, status: 'blocked', reason: error.message });
+            goal = save(root, { ...goal, status: 'blocked', reason: error.message });
         throw error;
     }
     finally {
-        releaseLock(root, lock.ownerToken);
+        if (wallTimer)
+            clearTimeout(wallTimer);
+        if (pauseTimer)
+            clearInterval(pauseTimer);
+        try {
+            if (goal && runStarted !== undefined) {
+                goal.wallDurationMs = wallAtStart + Math.max(0, Date.now() - runStarted);
+                goal.pendingRunStartedAt = undefined;
+                save(root, goal);
+            }
+        }
+        finally {
+            releaseLock(root, lock.ownerToken);
+        }
     }
 }

package/dist/loop/cleanup.js

@@ -7,6 +7,7 @@ import { acquireTakeoverLease, acquireTakeoverRecoveryLease, lockPath, takeoverL
 import { killProcessForCleanup, killProcessTreeForCleanup } from './watchdog.js';
 import { cleanupClaims } from './claims.js';
 import { clearStatus } from './reporter.js';
+import { discardParallelRecoveryRecords } from './recovery.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,
@@ -217,8 +218,16 @@ export function runLoopCleanup(targetDir, opts = {}) {
         }
         if (killed > 0)
             console.log(`Killed ${killed} orphaned process tree(s) from project-scoped Yoke records.`);
-        if (opts.removeWorktrees && failed === 0)
+        if (opts.removeWorktrees && failed === 0) {
             cleanupClaims(targetDir);
+            try {
+                discardParallelRecoveryRecords(targetDir);
+            }
+            catch (error) {
+                console.error(`Failed to discard parallel recovery records: ${error.message}`);
+                failed++;
+            }
+        }
         const lockFile = lockPath(targetDir);
         if (existsSync(lockFile)) {
             rmSync(lockFile, { force: true });

package/dist/loop/dispatcher.js

@@ -34,18 +34,32 @@ async function gateResult(gates, path, worker) {
     if (criteria.length > 0 && !gates.verifyCriterion)
         return { passed: false, summary: 'criterion verifier is not configured' };
     for (const criterion of criteria) {
-        const result = gates.verifyCriterion?.(path, story, criterion);
+        const result = withStoryContext(story.id, () => gates.verifyCriterion?.(path, story, criterion));
         if (!result?.passed)
             return { passed: false, summary: result?.summary ?? 'criterion verification failed' };
     }
     for (const gate of [gates.verify, gates.design, gates.perf, gates.audit]) {
         if (!gate)
             continue;
-        const result = gate(path, story);
+        const result = withStoryContext(story.id, () => gate(path, story));
         if (!result.passed)
             return result;
     }
-    return gates.qualityReview?.(path, story, worker) ?? { passed: true, summary: 'integrated gates passed' };
+    return withStoryContext(story.id, () => gates.qualityReview?.(path, story, worker)) ?? { passed: true, summary: 'integrated gates passed' };
+}
+// All gate APIs are synchronous: never leave ambient story context set across an await.
+function withStoryContext(storyId, gate) {
+    const previous = process.env.YOKE_STORY;
+    process.env.YOKE_STORY = storyId;
+    try {
+        return gate();
+    }
+    finally {
+        if (previous === undefined)
+            delete process.env.YOKE_STORY;
+        else
+            process.env.YOKE_STORY = previous;
+    }
 }
 export function createDispatcher(options) {
     const dispatcherId = options.dispatcherId ?? randomUUID();
@@ -125,6 +139,11 @@ export function createDispatcher(options) {
         if (claims.release(input) === false)
             throw new Error('claim release failed');
     };
+    const cleanupRetained = createWorkerCleanup({
+        cleanupProcess: options.worktrees.cleanupProcess,
+        removeWorktree: () => undefined,
+        releaseClaim: releaseCandidateClaim,
+    });
     const persistPass = (input) => {
         if (!options.prdPath)
             return;
@@ -135,6 +154,8 @@ export function createDispatcher(options) {
     };
     const enqueue = (input, result) => {
         let reason = 'integrated verification failed';
+        let retained = false;
+        let recoveryBaseCommit = input.worktree.baseCommit;
         const integrationQueuedAt = Date.now();
         let integrationStartedAt;
         const integrationController = new AbortController();
@@ -160,6 +181,7 @@ export function createDispatcher(options) {
                     reason = rebase.reason;
                     throw new Error(reason);
                 }
+                recoveryBaseCommit = rebase.expectedHead;
                 return rebase.expectedHead;
             },
             verify: async () => {
@@ -169,7 +191,9 @@ export function createDispatcher(options) {
                 }
                 const gate = await gateResult(options.gates, input.worktree.path, input);
                 reason = gate.summary;
-                return gate.passed;
+                if (!gate.passed)
+                    throw new Error(gate.summary);
+                return true;
             },
             integrate: async (expectedHead) => {
                 if (cancellationReason)
@@ -200,6 +224,15 @@ export function createDispatcher(options) {
                     return;
                 case 'reopened':
                     reopened.push(input.story.id);
+                    reason = merge.reason;
+                    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);
+                        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);
                     return;
                 default: {
@@ -217,7 +250,10 @@ export function createDispatcher(options) {
                 options.onIntegrationMetrics?.(input, Date.now() - integrationQueuedAt, integrationStartedAt === undefined ? undefined : Date.now() - integrationStartedAt);
             }
             finally {
-                cleanup(input);
+                if (retained)
+                    cleanupRetained(input);
+                else
+                    cleanup(input);
                 reportProgress();
             }
         });
@@ -227,12 +263,22 @@ export function createDispatcher(options) {
     const launch = (story) => {
         const provider = providerFor(story);
         const ownerToken = ids();
-        const worktree = options.worktrees.create({ story, dispatcherId, ownerToken, provider });
+        let worktree;
+        try {
+            worktree = options.worktrees.create({ story, dispatcherId, ownerToken, provider });
+        }
+        catch (error) {
+            failed.push(story.id);
+            failureReasons.set(story.id, `worktree setup failed: ${error instanceof Error ? error.message : String(error)}`);
+            reportProgress();
+            return;
+        }
         const controller = new AbortController();
         const candidateRace = Boolean(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)) {
-            options.worktrees.remove(input);
+            if (!worktree.recovered)
+                options.worktrees.remove(input);
             return;
         }
         iterations += 1;
@@ -241,6 +287,19 @@ export function createDispatcher(options) {
             areas.add(story.area);
         const candidateDispatch = candidateRace;
         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);
+        try {
+            reportProgress();
+        }
+        catch (error) {
+            active.delete(story.id);
+            if (worktree.recovered)
+                cleanupRetained(input);
+            else
+                cleanup(input);
+            throw error;
+        }
         const task = Promise.resolve().then(async () => {
             const workerLease = options.acquireResource
                 ? await options.acquireResource({ story, provider, role: 'implementation', units: candidateRace ? options.candidateCount : 1, signal: controller.signal })
@@ -248,6 +307,13 @@ export function createDispatcher(options) {
             activeWorker.phase = 'implementing';
             reportProgress();
             try {
+                if (worktree.recovered)
+                    options.worktrees.cleanupProcess?.(input);
+                if (worktree.recovered)
+                    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' },
+                        } };
                 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 })));
@@ -312,7 +378,10 @@ export function createDispatcher(options) {
             if (cancellationReason || paused || options.pause?.()) {
                 paused = true;
                 result.routing.recordOutcome?.(false);
-                cleanup(input);
+                if (input.worktree.recovered)
+                    cleanupRetained(input);
+                else
+                    cleanup(input);
                 reportProgress();
                 return;
             }
@@ -322,7 +391,10 @@ export function createDispatcher(options) {
             failed.push(story.id);
             failureReasons.set(story.id, error instanceof Error ? error.message : String(error));
             try {
-                cleanup(input);
+                if (input.worktree.recovered)
+                    cleanupRetained(input);
+                else
+                    cleanup(input);
             }
             catch (cleanupError) {
                 reportProgress();
@@ -387,7 +459,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: `worker ${storyId} failed: ${detail}` } : {}), iterations, integrated, reopened, failed };
+                return { status: 'blocked', ...(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/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/artifacts', '.yoke/events', '.yoke/history', '.yoke/routing', '.yoke/checks', '.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/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'];
 // Directory pathspecs include descendants and also exclude the directory entry.
 export const RUNTIME_EXCLUDES = RUNTIME_PATHS.map(path => `:(exclude)${path}`);
 export function stageImplementation(dir) {