@hecer/yoke 1.18.0 → 1.20.0

package/dist/loop/parallel-adapters.js

@@ -1,11 +1,14 @@
 import { execFileSync, spawnSync } from 'node:child_process';
-import { mkdirSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, unlinkSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
 import { isProviderTreeAlive, reapProviderProcesses } from './cleanup.js';
 import { realGitOps, stageImplementation } from './git.js';
 import { isPidAlive } from './lock.js';
 import { storyPathSegment } from './prd.js';
 import { killProcessTreeForCleanup } from './watchdog.js';
+import { parallelAcceptanceDigest, recoverParallelWorktree, retainParallelWorktree } from './recovery.js';
+import { statePath } from '../workspace/state.js';
 export function makeParallelAdapters(targetDir, identity, injectedGit) {
     return injectedGit
         ? injectedAdapters(targetDir, identity, injectedGit)
@@ -37,18 +40,40 @@ function injectedAdapters(targetDir, identity, git) {
 function productionAdapters(targetDir, identity) {
     const owned = new Set();
     const removed = new Set();
+    const acceptanceDigests = new Map();
+    const ownershipTokens = new Map();
     return {
         worktrees: {
             create: input => {
+                acceptanceDigests.set(input.story.id, parallelAcceptanceDigest(targetDir));
                 const path = worktreePath(targetDir, input);
+                const recovered = recoverParallelWorktree(targetDir, recoveryPath(targetDir, input.story.id), input.story.id);
+                if (recovered) {
+                    owned.add(recovered.path);
+                    ownershipTokens.set(recovered.path, recovered.ownerToken);
+                    return recovered;
+                }
                 const baseCommit = gitText(targetDir, ['rev-parse', 'HEAD']);
+                preflightWorktreePath(targetDir, path);
                 mkdirSync(dirname(path), { recursive: true });
                 realGitOps.addWorktree(targetDir, path);
                 owned.add(path);
+                ownershipTokens.set(path, input.ownerToken);
                 return { path, baseCommit };
             },
             cleanupProcess: cleanupProviderProcesses,
-            remove: input => removeOwnedWorktree(targetDir, input, owned, removed, realGitOps),
+            retain: (input, reason) => {
+                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 });
+            },
+            remove: input => {
+                removeOwnedWorktree(targetDir, input, owned, removed, realGitOps);
+                const file = recoveryPath(targetDir, input.story.id);
+                if (input.worktree.recovered && existsSync(file))
+                    unlinkSync(file);
+            },
         },
         git: {
             isClean: dir => realGitOps.isClean(dir),
@@ -56,23 +81,27 @@ 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),
+        candidates: primary => makeCandidateLifecycle(targetDir, primary, owned, removed, realGitOps, ownershipTokens),
     };
 }
 function cleanupProviderProcesses(input) {
     reapProviderProcesses(input.worktree.path, isPidAlive, isProviderTreeAlive, killProcessTreeForCleanup);
 }
-function makeCandidateLifecycle(targetDir, primary, owned, removed, git) {
+function makeCandidateLifecycle(targetDir, primary, owned, removed, git, ownershipTokens) {
     return {
         reserve: input => {
             const worktree = input.candidateId === 'candidate-1'
                 ? primary.worktree
                 : { path: candidateWorktreePath(targetDir, input), baseCommit: primary.worktree.baseCommit };
+            if (input.candidateId !== 'candidate-1')
+                ownershipTokens?.set(worktree.path, input.ownerToken);
             writeCandidateStatus(targetDir, input, worktree.path, 'reserved');
             return worktree;
         },
         materialize: ownership => {
             if (ownership.worktree.path !== primary.worktree.path) {
+                if (git === realGitOps)
+                    preflightWorktreePath(targetDir, ownership.worktree.path);
                 mkdirSync(dirname(ownership.worktree.path), { recursive: true });
                 git.addWorktree(targetDir, ownership.worktree.path);
                 owned.add(ownership.worktree.path);
@@ -92,7 +121,7 @@ function makeCandidateLifecycle(targetDir, primary, owned, removed, git) {
     };
 }
 function worktreePath(targetDir, input) {
-    return join(targetDir, '.yoke', 'worktrees', `${storyPathSegment(input.story.id)}-${input.ownerToken}`);
+    return shortWorktreePath(targetDir, input.story.id, input.ownerToken);
 }
 function removeOwnedWorktree(targetDir, input, owned, removed, git) {
     if (removed.has(input.worktree.path))
@@ -105,7 +134,24 @@ function removeOwnedWorktree(targetDir, input, owned, removed, git) {
     removed.add(input.worktree.path);
 }
 function candidateWorktreePath(targetDir, input) {
-    return join(targetDir, '.yoke', 'worktrees', `${storyPathSegment(input.storyId)}-${input.ownerToken}`);
+    return shortWorktreePath(targetDir, input.storyId, input.ownerToken);
+}
+function shortWorktreePath(targetDir, storyId, ownerToken) {
+    // 96 bits derived from the complete ownership identity; Git refuses an existing path.
+    const name = createHash('sha256').update(JSON.stringify([storyId, ownerToken])).digest('hex').slice(0, 24);
+    return join(targetDir, '.yoke', 'worktrees', name);
+}
+function recoveryPath(targetDir, storyId) {
+    return statePath(targetDir, 'integration-recovery', `${storyPathSegment(storyId)}.json`);
+}
+function preflightWorktreePath(targetDir, path) {
+    if (process.platform !== 'win32')
+        return;
+    const common = resolve(targetDir, gitText(targetDir, ['rev-parse', '--git-common-dir']));
+    const administrativePath = join(common, 'worktrees', basename(path));
+    if ([resolve(path, '.git'), administrativePath].some(value => value.length >= 240)) {
+        throw new Error(`Parallel worktree path exceeds the Windows Git path budget: ${path}. Move the project to a shorter root and retry; implementation has not started.`);
+    }
 }
 function writeCandidateStatus(targetDir, input, worktree, state, reason) {
     const file = join(targetDir, '.yoke', 'proof', storyPathSegment(input.storyId), 'candidates', input.candidateId, 'status.json');

package/dist/loop/parallel-command.js

@@ -50,7 +50,13 @@ export async function runParallelLoopCommand(input) {
                 units: request.units,
                 signal: request.signal,
             });
-            input.reporter.resourceWait?.({ id: request.story.id, title: request.story.title }, request.role, request.units, Date.now() - started, request.provider.provider);
+            try {
+                input.reporter.resourceWait?.({ id: request.story.id, title: request.story.title }, request.role, request.units, Date.now() - started, request.provider.provider);
+            }
+            catch (error) {
+                await lease.release();
+                throw error;
+            }
             return lease;
         },
         resourceStatus: () => sharedPoolStatus(),
@@ -71,6 +77,7 @@ export async function runParallelLoopCommand(input) {
         pause,
         onProgress: status => input.reporter.parallel?.(status),
         onAccepted: story => input.reporter.accepted?.(story),
+        onReopened: (story, evidence) => input.reporter.reopened?.(story, evidence),
         gates: {
             verify: input.verify,
             design: input.design,

package/dist/loop/recovery.js

@@ -1,8 +1,11 @@
 import { execFileSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { existsSync, mkdirSync, readFileSync, realpathSync as filesystemRealpathSync, writeFileSync } from 'node:fs';
-import { dirname, join, relative, resolve, isAbsolute } from 'node:path';
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync as filesystemRealpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, relative, resolve, isAbsolute } from 'node:path';
+import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
+import { statePath } from '../workspace/state.js';
+import { loadPrd } from './prd.js';
 const Recovery = z.object({ version: z.literal(1), root: z.string(), worktree: z.string(), base: z.string(), prdHash: z.string() }).strict();
 const digest = (file) => createHash('sha256').update(readFileSync(file)).digest('hex');
 const pathIdentity = (path) => process.platform === 'win32' ? path.toLowerCase() : path;
@@ -49,3 +52,79 @@ export function prepareIsolatedWorktree(directory, worktree, resume) {
     // Record is outside the worker checkout and binds reuse to its source state.
     writeFileSync(record, JSON.stringify({ version: 1, root, worktree: wt, base, prdHash }), { mode: 0o600 });
 }
+const ParallelRecovery = z.object({
+    version: z.literal(1), root: z.string().max(4096), storyId: z.string().max(1024), worktree: z.string().max(4096), baseCommit: z.string().max(128),
+    prdHash: z.string().length(64), ownerToken: z.string().min(1).max(256), reason: z.string().max(16384), state: z.literal('retained'), recordedAt: z.string().datetime(),
+}).strict();
+export function parallelAcceptanceDigest(directory) {
+    // Accepted sibling stories change only passes. Their acceptance contracts remain protected.
+    const contract = loadPrd(join(directory, '.yoke', 'prd.yaml')).map(({ passes: _passes, ...story }) => story);
+    return createHash('sha256').update(JSON.stringify(contract)).digest('hex');
+}
+function parallelRecordPath(directory, file) {
+    const safe = statePath(directory, 'integration-recovery', basename(file));
+    if (pathIdentity(resolve(file)) !== pathIdentity(resolve(safe)))
+        throw new Error('Invalid parallel recovery record path');
+    return safe;
+}
+export function discardParallelRecoveryRecords(directory) {
+    const parent = statePath(directory, 'integration-recovery');
+    if (!existsSync(parent))
+        return;
+    for (const name of readdirSync(parent)) {
+        if (!name.endsWith('.json') && !name.endsWith('.tmp'))
+            continue;
+        const file = statePath(directory, 'integration-recovery', name);
+        if (!lstatSync(file).isFile())
+            throw new Error('Parallel recovery record is not a file');
+        rmSync(file);
+    }
+}
+/** Records are outside the candidate and bind reuse to unchanged target acceptance. */
+export function retainParallelWorktree(directory, file, input) {
+    const root = realpathSync(directory);
+    const worktree = realpathSync(input.worktree);
+    const record = ParallelRecovery.parse({ version: 1, root, ...input, reason: input.reason.slice(0, 16384), worktree, state: 'retained', recordedAt: new Date().toISOString() });
+    const safe = parallelRecordPath(directory, file);
+    mkdirSync(dirname(safe), { recursive: true });
+    const temp = statePath(directory, 'integration-recovery', `${randomUUID()}.tmp`);
+    try {
+        writeFileSync(temp, JSON.stringify(record), { flag: 'wx', mode: 0o600 });
+        parallelRecordPath(directory, file);
+        renameSync(temp, safe);
+    }
+    finally {
+        rmSync(temp, { force: true });
+    }
+}
+export function recoverParallelWorktree(directory, file, storyId) {
+    const safe = parallelRecordPath(directory, file);
+    if (!existsSync(safe))
+        return undefined;
+    const stat = lstatSync(safe);
+    if (!stat.isFile())
+        throw new Error('Parallel recovery record is not a file');
+    if (stat.size > 65536)
+        throw new Error('Parallel recovery record is too large');
+    const saved = ParallelRecovery.parse(JSON.parse(readFileSync(safe, 'utf8')));
+    if (!existsSync(saved.worktree))
+        throw new Error(`Retained candidate is missing: ${saved.worktree}; resolve its recovery record before retrying`);
+    const root = realpathSync(directory);
+    const actual = realpathSync(saved.worktree);
+    const parent = realpathSync(join(root, '.yoke', 'worktrees'));
+    const rel = relative(parent, actual);
+    const expectedName = createHash('sha256').update(JSON.stringify([storyId, saved.ownerToken])).digest('hex').slice(0, 24);
+    if (saved.storyId !== storyId || pathIdentity(saved.root) !== pathIdentity(root) || pathIdentity(actual) !== pathIdentity(saved.worktree) || isAbsolute(rel) || rel !== expectedName)
+        throw new Error('Retained candidate ownership or path binding is invalid');
+    const git = (args, cwd = root) => execFileSync('git', args, { cwd, encoding: 'utf8', stdio: 'pipe' }).trim();
+    if (saved.baseCommit !== git(['rev-parse', 'HEAD']) || saved.prdHash !== parallelAcceptanceDigest(root))
+        throw new Error(`Retained candidate is stale against target or PRD: ${actual}; reconcile it before retrying`);
+    const common = realpathSync(resolve(root, git(['rev-parse', '--git-common-dir'])));
+    if (pathIdentity(realpathSync(resolve(actual, git(['rev-parse', '--git-common-dir'], actual)))) !== pathIdentity(common))
+        throw new Error('Retained candidate belongs to another repository');
+    const registered = git(['worktree', 'list', '--porcelain']).split(/\r?\n/u).filter(line => line.startsWith('worktree ')).map(line => realpathSync(resolve(line.slice(9))));
+    if (!registered.some(path => pathIdentity(path) === pathIdentity(actual)))
+        throw new Error('Retained candidate is not a registered worktree');
+    git(['merge-base', '--is-ancestor', saved.baseCommit, 'HEAD'], actual);
+    return { path: actual, baseCommit: saved.baseCommit, recovered: true, ownerToken: saved.ownerToken };
+}

package/dist/loop/reporter.js

@@ -303,6 +303,9 @@ export function makeReporter(dir, opts = {}, now = () => new Date()) {
         integrationDuration(story, durationMs, provider) {
             appendEvent(dir, { runId, timestamp: now().toISOString(), type: 'phase-ended', storyId: story.id, phase: 'integration', provider, durationMs: Math.max(0, durationMs) });
         },
+        reopened(story, evidence) {
+            appendEvent(dir, { runId, timestamp: now().toISOString(), type: 'status', storyId: story.id, data: { status: 'reopened', ...evidence } });
+        },
         parallelWorker(status) {
             const base = current;
             const parallel = base?.parallel;

package/dist/loop/resource-pool.js

@@ -51,12 +51,12 @@ export function globalWorkerLimit(environment = process.env) {
         cachedGlobalLimit = value;
     return value;
 }
-function poolDir() {
+function poolDir(resource) {
     const base = process.env.LOCALAPPDATA || process.env.XDG_STATE_HOME || join(homedir(), '.yoke');
-    return join(resolve(base), 'Yoke', 'parallel-pool');
+    return join(resolve(base), 'Yoke', resource === 'check' ? 'check-pool' : 'parallel-pool');
 }
-function ensurePoolDir() {
-    const dir = poolDir();
+function ensurePoolDir(resource) {
+    const dir = poolDir(resource);
     mkdirSync(dir, { recursive: true });
     const stat = lstatSync(dir);
     if (!stat.isDirectory() || stat.isSymbolicLink())
@@ -119,8 +119,8 @@ function staleDead(record, now) {
     const created = Date.parse(record.createdAt);
     return !Number.isFinite(created) || now - created > STALE_OWNER_MS;
 }
-function withPoolLock(operation) {
-    const dir = ensurePoolDir();
+function withPoolLock(operation, resource) {
+    const dir = ensurePoolDir(resource);
     const lockFile = join(dir, 'pool');
     return withClaimOperations(lockFile, { now: new Date(), staleMs: STALE_OWNER_MS, isAlive: isPidAlive }, () => readRecords(dir), () => [], records => {
         const now = Date.now();
@@ -184,7 +184,7 @@ function writeRecord(dir, record) {
 }
 export async function acquireSharedWorker(request) {
     const units = request.units ?? 1;
-    const limit = globalWorkerLimit();
+    const limit = request.resource === 'check' ? globalCheckLimit() : globalWorkerLimit();
     if (!Number.isInteger(units) || units < 1 || units > MAX_PROJECT_WORKERS)
         throw new Error(`Worker reservation units must be an integer from 1 to ${MAX_PROJECT_WORKERS}`);
     if (units > limit)
@@ -213,7 +213,7 @@ export async function acquireSharedWorker(request) {
     while (!published) {
         if (request.signal?.aborted)
             throw new Error(abortReason(request.signal));
-        const result = withPoolLock((_records, dir) => { writeRecord(dir, waiting); return true; });
+        const result = withPoolLock((_records, dir) => { writeRecord(dir, waiting); return true; }, request.resource);
         if (result === true)
             published = true;
         else
@@ -237,7 +237,7 @@ export async function acquireSharedWorker(request) {
                     replaceRecord(dir, { ...head, overtakes: head.overtakes + 1 });
                 replaceRecord(dir, { ...own, state: 'active' });
                 return true;
-            });
+            }, request.resource);
             if (granted === true) {
                 const acquiredAt = new Date().toISOString();
                 let released = false;
@@ -254,7 +254,7 @@ export async function acquireSharedWorker(request) {
                                     return false;
                                 rmSync(recordPath(dir, id), { force: true });
                                 return true;
-                            });
+                            }, request.resource);
                             if (result !== null) {
                                 released = true;
                                 return result;
@@ -274,7 +274,7 @@ export async function acquireSharedWorker(request) {
                 if (own)
                     rmSync(recordPath(dir, id), { force: true });
                 return true;
-            });
+            }, request.resource);
             if (removed !== null)
                 break;
             await waitForCapacity();
@@ -347,10 +347,10 @@ export function withSharedWorkerSync(request, operation) {
         }
     }
 }
-export function sharedPoolStatus() {
-    const limit = globalWorkerLimit();
-    const snapshot = withPoolLock(records => records.map(record => ({ ...record })));
-    const records = snapshot ?? readRecords(ensurePoolDir()).filter(record => !staleDead(record, Date.now()));
+export function sharedPoolStatus(resource) {
+    const limit = resource === 'check' ? globalCheckLimit() : globalWorkerLimit();
+    const snapshot = withPoolLock(records => records.map(record => ({ ...record })), resource);
+    const records = snapshot ?? readRecords(ensurePoolDir(resource)).filter(record => !staleDead(record, Date.now()));
     const sharedLimit = effectiveLimit(records, limit);
     const active = records.filter(record => record.state === 'active');
     const waiting = records.filter(record => record.state === 'waiting');
@@ -367,3 +367,9 @@ export function sharedPoolStatus() {
         oldestWaitMs: Number.isFinite(oldest) ? Math.max(0, Date.now() - oldest) : 0,
     };
 }
+export function globalCheckLimit(environment = process.env) {
+    const raw = environment.YOKE_MAX_PARALLEL_CHECKS ?? '1';
+    if (!/^[1-8]$/u.test(raw))
+        throw new Error('YOKE_MAX_PARALLEL_CHECKS must be an integer from 1 to 8');
+    return Number(raw);
+}

package/dist/loop/run-command.js

@@ -2,13 +2,15 @@ import { roleSelection } from "../routing/capability.js";
 import { join } from 'node:path';
 import { existsSync, unlinkSync } from 'node:fs';
 import { loadConfig, saveConfig, defaultConfig, resolveOutputPolicy, resolveVerifyCommand } from '../retrofit/config.js';
-import { allPass, loadPrd, progress, selectNextStory } from './prd.js';
+import { allPass, loadPrd, progress, selectNextStory, storyPathSegment } from './prd.js';
 import { pauseFilePath, requestLoopPause, runLoop } from './loop.js';
 import { commitPaths, realGitOps } from './git.js';
 import { makeRunner, makeReviewRunner, isAgentAvailable } from './runner.js';
 import { commandVerifier, commandsVerifier, retryingVerifier } from './verify.js';
 import { readStatus, makeReporter, fmtDuration } from './reporter.js';
-import { acquireLock, releaseLock } from './lock.js';
+import { acquireLock, releaseLock, readLock } from './lock.js';
+import { statePath } from '../workspace/state.js';
+import { accountRunIterations, createLoopRun, readRunState, writeRunState } from './run-state.js';
 import { maybeAutoUpgrade } from '../update/upgrade.js';
 import { resolveCommitIdentity } from './identity.js';
 import { runAudit } from '../audit/command.js';
@@ -232,7 +234,7 @@ async function runContinuousExploration(targetDir, options) {
         console.error('--explore-limit must be a positive, supported duration');
         return 2;
     }
-    const limitDeadline = options.exploreLimitMs === undefined ? undefined : Date.now() + options.exploreLimitMs;
+    const limitDeadline = options.savedRun?.exploreDeadline ?? (options.exploreLimitMs === undefined ? undefined : Date.now() + options.exploreLimitMs);
     const reporter = options.reporter ?? makeReporter(targetDir, { json: options.json, quiet: true });
     let config;
     try {
@@ -242,11 +244,11 @@ async function runContinuousExploration(targetDir, options) {
         config = null;
     }
     const defaultImplementationAgent = options.agent ?? resolveRunnerAgent(config, undefined, detectHostAgent());
-    const defaultExplorer = options.agent ?? config?.planning?.agent ?? defaultImplementationAgent;
+    const defaultExplorer = options.explorationPlanner?.agent ?? options.agent ?? config?.planning?.agent ?? defaultImplementationAgent;
     const available = options.isAvailable ?? isAgentAvailable;
     const reviewRequested = !options.reviewRunner && Boolean(options.review || options.reviewer);
     const innerOptions = { ...options, isolate: true, explore: true, explorationSupervisor: true, reporter, quiet: true };
-    let usedIterations = 0;
+    let usedIterations = options.savedRun?.consumedIterations ?? 0;
     let retryCount = 0;
     let explorationFailures = 0;
     let noActionScans = 0;
@@ -284,6 +286,8 @@ async function runContinuousExploration(targetDir, options) {
             return 'limit';
         const explorer = retryProviders(targetDir, explorationAgent, available);
         const result = runPrdExplore(targetDir, {
+            ownedLockToken: options.ownedLockToken,
+            ...(explorationAgent === options.explorationPlanner?.agent ? { selection: options.explorationPlanner.selection } : {}),
             runner: explorationAgent,
             timeoutMinutes: options.timeoutMinutes,
             isAvailable: options.isAvailable ?? isAgentAvailable,
@@ -370,7 +374,9 @@ async function runContinuousExploration(targetDir, options) {
         }
         const afterStatus = readStatus(targetDir);
         const changedStatus = afterStatus?.updatedAt !== beforeStatus?.updatedAt;
-        if (changedStatus && priorProgress.passed < priorProgress.total)
+        if (options.savedRun)
+            usedIterations = options.savedRun.consumedIterations ?? usedIterations;
+        else if (changedStatus && priorProgress.passed < priorProgress.total)
             usedIterations += Math.max(0, afterStatus?.iteration ?? 0);
         if (unexpectedFailure) {
             retryCount++;
@@ -468,7 +474,7 @@ async function runContinuousExploration(targetDir, options) {
         }
         retryCount++;
         advanceRecoveryProviders();
-        retryWorktree = true;
+        retryWorktree = (afterStatus?.parallel?.reopened ?? 0) === 0;
         const wait = retryDelay(retryCount);
         reporter.phase('waiting-recovery', `story ${afterStatus?.story ?? 'unknown'} remains incomplete: ${afterStatus?.reason ?? 'no passing completion status'}; retrying with ${implementationAgent ?? 'the configured runner'} in ${Math.ceil(wait / 1_000)} seconds`, currentProgress(targetDir));
         say(`The current task remains unfinished; its isolated work is retained. Next: retry with ${implementationAgent ?? 'the configured runner'} in ${Math.ceil(wait / 1_000)} seconds.`);
@@ -480,7 +486,7 @@ async function runContinuousExploration(targetDir, options) {
 }
 export function runLoopCommand(targetDir, opts) {
     if (opts.explore && !opts.explorationSupervisor)
-        return runContinuousExploration(targetDir, opts);
+        return startContinuousExploration(targetDir, opts);
     let parallel = opts.parallel ?? 1;
     const candidates = opts.candidates ?? 1;
     if (opts.resumeWorktree && (opts.isolate === false || parallel !== 1 || candidates !== 1)) {
@@ -554,7 +560,8 @@ export function runLoopCommand(targetDir, opts) {
         return 2;
     }
     const isolate = opts.isolate ?? config.loop.isolate ?? true;
-    const useParallelDispatcher = parallel > 1 || candidates > 1;
+    const retainedParallel = opts.explorationSupervisor && loadPrd(path).some(story => !story.passes && existsSync(statePath(targetDir, 'integration-recovery', `${storyPathSegment(story.id)}.json`)));
+    const useParallelDispatcher = parallel > 1 || candidates > 1 || retainedParallel === true;
     if (opts.resumeWorktree && (!isolate || parallel !== 1)) {
         console.error('--resume-worktree requires isolation and one worker');
         return 2;
@@ -668,11 +675,13 @@ export function runLoopCommand(targetDir, opts) {
     const routingRequested = opts.routing ?? config.routing?.enabled ?? true;
     const routingEnabled = routingRequested && Boolean(config.routing && (config.routing.workers.length || config.routing.fallback === 'block' || config.routing.maxTier || config.routing.assessmentPolicy === 'prepared'));
     const runnerSelection = {
-        provider: config.runner?.provider,
-        model: config.runner?.model,
-        reasoningEffort: config.runner?.reasoningEffort,
-        variant: config.runner?.variant,
-        bare: config.runner?.bare,
+        ...(opts.selection ?? {
+            provider: config.runner?.provider,
+            model: config.runner?.model,
+            reasoningEffort: config.runner?.reasoningEffort,
+            variant: config.runner?.variant,
+            bare: config.runner?.bare,
+        }),
         nativeMultiAgent: false,
     };
     const parallelProviders = [{
@@ -735,13 +744,7 @@ export function runLoopCommand(targetDir, opts) {
         timeoutMs: idleMs,
         isAvailable: available,
         permissions,
-        selection: {
-            provider: config.runner?.provider,
-            model: config.runner?.model,
-            reasoningEffort: config.runner?.reasoningEffort,
-            variant: config.runner?.variant,
-            bare: config.runner?.bare,
-        },
+        selection: runnerSelection,
         commit: (_path, request) => commitPaths(targetDir, ['.yoke/prd.yaml'], `yoke: plan change ${request.id}`, commitIdentity),
     }));
     let runner = opts.runner;
@@ -854,7 +857,14 @@ export function runLoopCommand(targetDir, opts) {
     }
     let lock;
     try {
-        lock = acquireLock(targetDir);
+        statePath(targetDir, 'loop.lock');
+        if (opts.ownedLockToken) {
+            if (readLock(targetDir)?.ownerToken !== opts.ownedLockToken)
+                throw new Error('Invalid borrowed loop lock');
+            lock = { acquired: true, ownerToken: opts.ownedLockToken };
+        }
+        else
+            lock = acquireLock(targetDir);
     }
     catch (error) {
         console.error(`Cannot acquire the Yoke loop lock: ${error.message}`);
@@ -867,8 +877,22 @@ export function runLoopCommand(targetDir, opts) {
     if (lock.stalePid !== undefined) {
         console.warn(`Took over a stale loop lock (pid ${lock.stalePid} is gone).`);
     }
-    const reporter = opts.reporter ?? makeReporter(targetDir, { json: opts.json, quiet: opts.quiet });
+    let reporter = opts.reporter ?? makeReporter(targetDir, { json: opts.json, quiet: opts.quiet });
     executionReporter = reporter;
+    try {
+        const saved = opts.savedRun ?? createLoopRun({ ...opts, agent: runnerAgent, selection: runnerSelection, parallel, isolate, routing: routingEnabled, timeoutMinutes: opts.timeoutMinutes ?? config.loop.timeoutMinutes });
+        if (opts.savedRun && readRunState(targetDir)?.runId !== opts.savedRun.runId)
+            throw new Error('Saved run changed before resume');
+        writeRunState(targetDir, saved, lock.ownerToken);
+        reporter = accountRunIterations(targetDir, saved, lock.ownerToken, reporter);
+        executionReporter = reporter;
+    }
+    catch (error) {
+        if (!opts.ownedLockToken)
+            releaseLock(targetDir, lock.ownerToken);
+        reporter.blocked(`could not persist loop run: ${error.message}`);
+        return 1;
+    }
     const buildResume = (storyId, requestId) => buildTrustedDecisionResumeState({
         storyId,
         requestId,
@@ -938,7 +962,8 @@ export function runLoopCommand(targetDir, opts) {
             completion,
             quality,
             onCriticalDecision: decision => writeDecisionResume(targetDir, buildResume(decision.storyId, decisionRequestId(decision))),
-        }).then(code => reconcileDecisionResume() ?? code).finally(() => releaseLock(targetDir, lock.ownerToken));
+        }).then(code => reconcileDecisionResume() ?? code).finally(() => { if (!opts.ownedLockToken)
+            releaseLock(targetDir, lock.ownerToken); });
     }
     try {
         const maxIterations = opts.maxIterations ?? Number.POSITIVE_INFINITY;
@@ -984,6 +1009,47 @@ export function runLoopCommand(targetDir, opts) {
         return 1;
     }
     finally {
-        releaseLock(targetDir, lock.ownerToken);
+        if (!opts.ownedLockToken)
+            releaseLock(targetDir, lock.ownerToken);
     }
 }
+async function startContinuousExploration(targetDir, options) {
+    let lock;
+    try {
+        if (options.isolate === false)
+            throw new Error('--explore requires isolated story worktrees');
+        if (options.exploreLimitMs !== undefined && (!Number.isSafeInteger(options.exploreLimitMs) || options.exploreLimitMs <= 0 || Date.now() + options.exploreLimitMs > 8_640_000_000_000_000))
+            throw new Error('--explore-limit must be a positive, supported duration');
+        statePath(targetDir, 'loop.lock');
+        lock = acquireLock(targetDir);
+        if (!lock.acquired) {
+            console.error('Another loop is already running here');
+            return 2;
+        }
+        const config = loadConfig(targetDir);
+        const implementationAgent = options.agent ?? resolveRunnerAgent(config, undefined, detectHostAgent());
+        const implementationSelection = options.selection ?? config?.runner ?? {};
+        const explorationPlanner = options.explorationPlanner ?? resolvePlanner(config, implementationAgent, implementationSelection, options.agent);
+        const run = options.savedRun ?? createLoopRun({ ...options, agent: implementationAgent, selection: implementationSelection, explorationPlanner, timeoutMinutes: options.timeoutMinutes ?? config?.loop.timeoutMinutes, ...(options.parallel === undefined && !options.parallelAuto ? typeof config?.loop.parallel === 'number' ? { parallel: config.loop.parallel } : { parallelAuto: true } : {}) });
+        if (options.savedRun && readRunState(targetDir)?.runId !== run.runId)
+            throw new Error('Saved run changed before resume');
+        writeRunState(targetDir, run, lock.ownerToken);
+        return await runContinuousExploration(targetDir, { ...options, selection: run.options.selection, explorationPlanner: run.options.explorationPlanner ?? explorationPlanner, savedRun: run, ownedLockToken: lock.ownerToken });
+    }
+    catch (error) {
+        console.error(`Cannot start exploration: ${error.message}`);
+        return 2;
+    }
+    finally {
+        if (lock?.acquired)
+            releaseLock(targetDir, lock.ownerToken);
+    }
+}
+/** Resume the saved execution identity without extending its exploration deadline. */
+export function resumeLoopCommand(targetDir) {
+    const run = readRunState(targetDir);
+    if (!run || run.mode === 'goal')
+        throw new Error('No saved loop run to resume');
+    const { native: _native, ...options } = run.options;
+    return runLoopCommand(targetDir, { ...options, ...(run.mode === 'loop' && options.maxIterations !== undefined ? { maxIterations: Math.max(0, options.maxIterations - (run.consumedIterations ?? 0)) } : {}), explore: run.mode === 'explore', savedRun: run, permissions: 'safe' });
+}