@hecer/yoke 1.17.0 → 1.19.0

package/dist/dashboard/server.js

@@ -4,6 +4,7 @@ import { lstatSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from '
 import { join } from 'node:path';
 import { parse } from 'yaml';
 import { z } from 'zod';
+import { configPath, defaultConfig, loadConfig, resolveSolPiSettings, saveConfig, SolPiSettingsSchema } from '../retrofit/config.js';
 import { listProjects } from './registry.js';
 import { dashboardPage } from './page.js';
 import { readEvents } from '../observability/events.js';
@@ -99,6 +100,28 @@ function writePauseSignal(root) {
             throw error;
     }
 }
+function assertSafeConfigTarget(root) {
+    const directory = join(root, '.yoke');
+    const file = configPath(root);
+    try {
+        const stat = lstatSync(directory);
+        if (stat.isSymbolicLink() || !stat.isDirectory())
+            throw new Error('Unsafe project settings target');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    try {
+        const stat = lstatSync(file);
+        if (stat.isSymbolicLink() || !stat.isFile())
+            throw new Error('Unsafe project settings target');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+}
 function projectIsRunning(root) {
     if (activeResumes.has(root))
         return true;
@@ -213,13 +236,51 @@ export async function startDashboard(options = {}) {
                 send(200, workspaceAnalytics(listProjects(), period, sort));
                 return;
             }
-            const match = /^\/api\/projects\/([a-f0-9]{32})(\/pause|\/resume|\/notes|\/changes|\/analytics|\/history|\/events)?$/u.exec(path);
+            const match = /^\/api\/projects\/([a-f0-9]{32})(\/pause|\/resume|\/notes|\/changes|\/settings|\/analytics|\/history|\/events)?$/u.exec(path);
             if (match) {
                 const project = listProjects().find(project => project.id === match[1]);
                 if (!project) {
                     send(404, { error: 'Unknown project' });
                     return;
                 }
+                if (req.method === 'GET' && match[2] === '/settings') {
+                    if (project.error) {
+                        send(409, { error: project.error });
+                        return;
+                    }
+                    assertSafeConfigTarget(project.root);
+                    const config = loadConfig(project.root) ?? defaultConfig('0.0.0');
+                    send(200, resolveSolPiSettings(config));
+                    return;
+                }
+                if (req.method === 'POST' && match[2] === '/settings') {
+                    let settings;
+                    try {
+                        settings = SolPiSettingsSchema.parse(await requestBody(req, {}));
+                    }
+                    catch (error) {
+                        send(error.message === 'Dashboard request body too large' ? 413 : 400, { error: error.message === 'Dashboard request body too large' ? error.message : 'Invalid project settings payload' });
+                        return;
+                    }
+                    if (project.error) {
+                        send(409, { error: project.error });
+                        return;
+                    }
+                    try {
+                        assertSafeConfigTarget(project.root);
+                        const config = loadConfig(project.root) ?? defaultConfig('0.0.0');
+                        saveConfig(project.root, { ...config, solpi: settings });
+                    }
+                    catch (error) {
+                        if (error.message === 'Unsafe project settings target') {
+                            send(409, { error: error.message });
+                            return;
+                        }
+                        throw error;
+                    }
+                    send(200, settings);
+                    return;
+                }
                 if (req.method === 'GET' && match[2] === '/analytics') {
                     if (project.error) {
                         send(409, { error: project.error });

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-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/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'];
 // Directory pathspecs include descendants and also exclude the directory entry.
 export const RUNTIME_EXCLUDES = RUNTIME_PATHS.map(path => `:(exclude)${path}`);
 export function stageImplementation(dir) {

package/dist/loop/loop.js

@@ -1,5 +1,5 @@
 import { knownInfrastructureFailure } from "../routing/capability.js";
-import { existsSync, unlinkSync, readFileSync } from 'node:fs';
+import { existsSync, unlinkSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs';
 import { acceptanceProtectionProblem } from '../check/command.js';
 import { join, relative } from 'node:path';
 import { isAcceptanceCriterion, loadPrd, savePrd, selectNextStory, allPass, progress, storyPathSegment } from './prd.js';
@@ -102,6 +102,18 @@ function runQualityReview(opts, executionDir, story, reporter) {
 export function pauseFilePath(targetDir) {
     return join(targetDir, '.yoke', 'loop.pause');
 }
+/** Request a pause at the next safe story or exploration boundary. */
+export function requestLoopPause(targetDir) {
+    const file = pauseFilePath(targetDir);
+    mkdirSync(join(targetDir, '.yoke'), { recursive: true });
+    try {
+        writeFileSync(file, `${new Date().toISOString()}\n`, { flag: 'wx' });
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+    }
+}
 function consumePause(targetDir) {
     const file = pauseFilePath(targetDir);
     if (!existsSync(file))

package/dist/loop/prd.js

@@ -11,6 +11,15 @@ export const AcceptanceCriterionSchema = z.object({
     text: z.string().min(1),
     verify: z.array(z.string().min(1)).min(1),
 });
+export const ExplorationOriginSchema = z.object({
+    version: z.literal(1),
+    rationale: z.string().min(1).max(2_000),
+    expectedBenefit: z.string().min(1).max(2_000),
+    confidence: z.number().min(0.8).max(1),
+    risk: z.enum(['low', 'medium']),
+    evidence: z.array(z.object({ path: z.string().min(1).max(500), observation: z.string().min(1).max(1_000) }).strict()).min(1).max(6),
+    discoveredAt: z.string().datetime(),
+}).strict();
 export function criterionCommandProblem(criterion) {
     const normalizedId = criterion.id.toLowerCase().replace(/[^a-z0-9]/g, '');
     for (const raw of criterion.verify) {
@@ -46,6 +55,8 @@ export const StorySchema = z.object({
     agent: AgentSchema.optional(),
     /** Inbox request that created this story. Used for idempotent append-only intake. */
     sourceChange: z.string().min(1).optional(),
+    /** Evidence retained for stories created by opt-in continuous exploration. */
+    exploration: ExplorationOriginSchema.optional(),
     quality: StoryQualityDeclarationSchema.optional(),
     assessment: AssessmentSchema.optional(),
     /** Binding to the task, upstream contracts and approved planning brief. */

package/dist/loop/reporter.js

@@ -220,10 +220,12 @@ export function makeReporter(dir, opts = {}, now = () => new Date()) {
             persist({ ...base, state: 'running', phase: undefined, story: story.id, storyTitle: story.title,
                 progress, ...(eta ? { eta } : {}), updatedAt: now().toISOString() }, 'story-done', `✓ ${story.id} done${took} — ${progress.passed}/${progress.total} (${percentOf(progress)}%)${hint}`);
         },
-        phase(phase) {
-            if (!current)
-                return;
-            persist({ ...current, phase, updatedAt: now().toISOString() }, phase, `  · ${phase}…`);
+        phase(phase, reason, progress) {
+            const status = current ?? emptyStatus(now().toISOString());
+            const base = phase === 'exploring' || phase === 'waiting-exploration' || phase === 'waiting-recovery'
+                ? (({ story: _story, storyTitle: _storyTitle, ...withoutStory }) => withoutStory)(status)
+                : status;
+            persist({ ...base, state: 'running', phase, ...(progress ? { progress } : {}), ...(reason ? { reason } : { reason: undefined }), updatedAt: now().toISOString() }, phase, `  · ${phase}…`);
         },
         blocked(reason) {
             const base = current ?? emptyStatus(now().toISOString());
@@ -237,9 +239,9 @@ export function makeReporter(dir, opts = {}, now = () => new Date()) {
             persist({ ...withoutParallel(current ?? emptyStatus(now().toISOString())), state: 'cap-reached', phase: undefined,
                 progress, updatedAt: now().toISOString() }, 'cap-reached', `◾ iteration cap reached — ${progress.passed}/${progress.total}`);
         },
-        paused(progress) {
+        paused(progress, reason) {
             persist({ ...withoutParallel(current ?? emptyStatus(now().toISOString())), state: 'paused', phase: undefined,
-                progress, updatedAt: now().toISOString() }, 'paused', `⏸ loop paused — ${progress.passed}/${progress.total}`);
+                progress, ...(reason ? { reason } : {}), updatedAt: now().toISOString() }, 'paused', `⏸ loop paused — ${progress.passed}/${progress.total}`);
         },
         quality(status) {
             const base = current ?? emptyStatus(now().toISOString());

package/dist/loop/run-command.js

@@ -1,9 +1,9 @@
 import { roleSelection } from "../routing/capability.js";
 import { join } from 'node:path';
-import { existsSync } from 'node:fs';
+import { existsSync, unlinkSync } from 'node:fs';
 import { loadConfig, saveConfig, defaultConfig, resolveOutputPolicy, resolveVerifyCommand } from '../retrofit/config.js';
-import { loadPrd, progress } from './prd.js';
-import { runLoop } from './loop.js';
+import { allPass, loadPrd, progress, selectNextStory } 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';
@@ -26,6 +26,7 @@ import { designVerifier } from '../scan/gate.js';
 import { prepareIsolatedWorktree } from './recovery.js';
 import { AGENT_LIST, SUPPORTED_AGENTS } from '../agents/catalog.js';
 import { MAX_PROJECT_WORKERS, sharedPoolStatus, withSharedWorkerSync } from './resource-pool.js';
+import { runPrdExplore } from '../prd/explore.js';
 export const DEFAULT_IDLE_MINUTES = 20;
 const STALE_MINUTES = 20; // a running status older than this likely means the loop died
 export function relativeTime(fromIso, now) {
@@ -103,8 +104,13 @@ export function loopStatus(targetDir, now = () => new Date()) {
         const candidate = worker.candidateId ? ` candidate ${worker.candidateId} · ${worker.worktree ?? 'worktree unknown'} · ${worker.lifecycle ?? 'working'}` : '';
         lines.push(`  worker ${worker.story} "${worker.storyTitle}" (${worker.provider}${worker.model ? `/${worker.model}` : ''})${candidate} · ${worker.phase ?? 'working'}${quality}`);
     }
-    const ageMs = now().getTime() - Date.parse(st.updatedAt);
-    if (st.state === 'running' && ageMs > STALE_MINUTES * 60_000) {
+    const nowMs = now().getTime();
+    const ageMs = nowMs - Date.parse(st.updatedAt);
+    const providerProgressMs = Math.max(0, ...((st.supervision ?? [])
+        .filter(process => process.liveness === 'alive' && process.lastProgressAt)
+        .map(process => Date.parse(process.lastProgressAt))
+        .filter(Number.isFinite)));
+    if (st.state === 'running' && ageMs > STALE_MINUTES * 60_000 && nowMs - providerProgressMs > STALE_MINUTES * 60_000) {
         lines.push(`  ⚠ possibly stuck — no update in ${relativeTime(st.updatedAt, now())}`);
     }
     return lines.join('\n');
@@ -113,7 +119,368 @@ export function resolveIdleMs(flagMinutes, configMinutes) {
     const minutes = flagMinutes ?? configMinutes ?? DEFAULT_IDLE_MINUTES;
     return minutes > 0 ? minutes * 60_000 : 0;
 }
+const DEFAULT_EXPLORE_INTERVAL_MINUTES = 30;
+const EXPLORE_RETRY_BASE_MS = 30_000;
+const EXPLORE_RETRY_MAX_MS = 15 * 60_000;
+function consumeExplorePause(targetDir) {
+    const path = pauseFilePath(targetDir);
+    if (!existsSync(path))
+        return false;
+    try {
+        unlinkSync(path);
+    }
+    catch { /* a pause request still wins if cleanup fails */ }
+    return true;
+}
+function currentProgress(targetDir) {
+    try {
+        return progress(loadPrd(prdPath(targetDir)));
+    }
+    catch {
+        return { passed: 0, total: 0 };
+    }
+}
+function allCurrentStoriesPass(targetDir) {
+    try {
+        return allPass(loadPrd(prdPath(targetDir)));
+    }
+    catch {
+        return false;
+    }
+}
+async function waitForExplorePause(targetDir, durationMs, heartbeat, limitDeadline) {
+    const waitDeadline = Date.now() + durationMs;
+    let nextHeartbeat = Date.now() + 5 * 60_000;
+    while (Date.now() < waitDeadline && (limitDeadline === undefined || Date.now() < limitDeadline)) {
+        if (consumeExplorePause(targetDir))
+            return true;
+        if (Date.now() >= nextHeartbeat) {
+            heartbeat?.();
+            nextHeartbeat = Date.now() + 5 * 60_000;
+        }
+        const untilWaitEnds = waitDeadline - Date.now();
+        const untilLimit = limitDeadline === undefined ? untilWaitEnds : limitDeadline - Date.now();
+        await new Promise(resolve => setTimeout(resolve, Math.max(1, Math.min(1_000, untilWaitEnds, untilLimit))));
+    }
+    return consumeExplorePause(targetDir);
+}
+function retryProviders(targetDir, preferred, available = isAgentAvailable) {
+    let config;
+    try {
+        config = loadConfig(targetDir);
+    }
+    catch {
+        config = null;
+    }
+    const primary = resolveRunnerAgent(config, preferred, detectHostAgent());
+    return [...new Set([primary, ...(config?.agents ?? [])])].filter(agent => available(agent));
+}
+function retryReviewers(preferred, implementer, available) {
+    return [...new Set([...(preferred ? [preferred] : []), ...SUPPORTED_AGENTS])].filter(agent => agent !== implementer && available(agent));
+}
+function nextProvider(providers, current) {
+    if (!providers.length)
+        return current;
+    const index = current ? providers.indexOf(current) : -1;
+    return providers[(index + 1 + providers.length) % providers.length];
+}
+function retryDelay(failures) {
+    return Math.min(EXPLORE_RETRY_MAX_MS, EXPLORE_RETRY_BASE_MS * 2 ** Math.min(10, Math.max(0, failures - 1)));
+}
+function scheduleExploreLimitPause(targetDir, deadline) {
+    if (deadline === undefined)
+        return () => { };
+    let timer;
+    const check = () => {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0) {
+            requestLoopPause(targetDir);
+            return;
+        }
+        timer = setTimeout(check, Math.min(remaining, 2_147_483_647));
+        timer.unref?.();
+    };
+    check();
+    return () => { if (timer)
+        clearTimeout(timer); };
+}
+function reportExploration(targetDir, summary, json, nextStep) {
+    const say = json ? (line) => console.error(line) : (line) => console.log(line);
+    let next = nextStep;
+    try {
+        if (!next) {
+            const story = selectNextStory(loadPrd(prdPath(targetDir)));
+            if (story)
+                next = `${story.id}: ${story.title}`;
+        }
+    }
+    catch { /* the persistent loop status keeps the parse failure visible */ }
+    say(`Exploration: ${summary}`);
+    say(`Next: ${next ?? 'scan the project again for evidenced improvements'}`);
+}
+async function runContinuousExploration(targetDir, options) {
+    if (options.isolate === false) {
+        console.error('--explore requires isolated story worktrees so failed work can be resumed safely.');
+        return 2;
+    }
+    const intervalMinutes = options.exploreIntervalMinutes ?? DEFAULT_EXPLORE_INTERVAL_MINUTES;
+    if (!Number.isInteger(intervalMinutes) || intervalMinutes < 1 || intervalMinutes > 1_440) {
+        console.error('--explore-interval must be an integer from 1 to 1440 minutes');
+        return 2;
+    }
+    if (options.exploreLimitMs !== undefined && (!Number.isSafeInteger(options.exploreLimitMs) || options.exploreLimitMs <= 0 || Date.now() + options.exploreLimitMs > 8_640_000_000_000_000)) {
+        console.error('--explore-limit must be a positive, supported duration');
+        return 2;
+    }
+    const limitDeadline = options.exploreLimitMs === undefined ? undefined : Date.now() + options.exploreLimitMs;
+    const reporter = options.reporter ?? makeReporter(targetDir, { json: options.json, quiet: true });
+    let config;
+    try {
+        config = loadConfig(targetDir);
+    }
+    catch {
+        config = null;
+    }
+    const defaultImplementationAgent = options.agent ?? resolveRunnerAgent(config, undefined, detectHostAgent());
+    const defaultExplorer = 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 retryCount = 0;
+    let explorationFailures = 0;
+    let noActionScans = 0;
+    let implementationAgent = defaultImplementationAgent;
+    let reviewerAgent = options.reviewer ?? (reviewRequested ? SUPPORTED_AGENTS.find(agent => agent !== defaultImplementationAgent && available(agent)) : undefined);
+    let explorationAgent = defaultExplorer;
+    let retryWorktree = false;
+    const safeBatchSize = () => {
+        if (retryWorktree)
+            return 1;
+        const parallelSetting = options.parallelAuto ? 'auto' : options.parallel ?? config?.loop.parallel ?? 'auto';
+        if (parallelSetting !== 'auto')
+            return Math.max(1, parallelSetting);
+        try {
+            const pending = loadPrd(prdPath(targetDir)).filter(story => !story.passes);
+            if (!config?.actions?.length && pending.length > 1 && pending.every(story => story.writes?.length)) {
+                return Math.min(sharedPoolStatus().limit, pending.length);
+            }
+        }
+        catch { /* the inner command reports the underlying configuration or PRD error */ }
+        return 1;
+    };
+    const say = options.json ? (line) => console.error(line) : (line) => console.log(line);
+    reporter.phase('exploring', 'continuous exploration supervisor started', currentProgress(targetDir));
+    const limitReached = () => limitDeadline !== undefined && Date.now() >= limitDeadline;
+    const stopForTimeLimit = () => {
+        consumeExplorePause(targetDir);
+        const reason = 'the configured exploration time limit elapsed; stopped at a safe boundary';
+        reporter.paused(currentProgress(targetDir), reason);
+        say('Exploration time limit elapsed; the loop stopped at a safe boundary. Next: yoke loop run --explore .');
+        return 3;
+    };
+    const scanForWork = async (focus) => {
+        if (limitReached())
+            return 'limit';
+        const explorer = retryProviders(targetDir, explorationAgent, available);
+        const result = runPrdExplore(targetDir, {
+            runner: explorationAgent,
+            timeoutMinutes: options.timeoutMinutes,
+            isAvailable: options.isAvailable ?? isAgentAvailable,
+            onUsage: usage => reporter.addTokens(usage),
+            pause: () => consumeExplorePause(targetDir) || limitReached(),
+            ...(focus ? { focus } : {}),
+        });
+        if (result.kind === 'paused') {
+            if (limitReached())
+                return 'limit';
+            reporter.paused(currentProgress(targetDir));
+            say('Exploration paused at a safe boundary.');
+            return 'paused';
+        }
+        if (result.kind === 'added') {
+            explorationFailures = 0;
+            noActionScans = 0;
+            explorationAgent = defaultExplorer;
+            const titles = result.tasks.map(task => `${task.id}: ${task.title}`).join('; ');
+            reporter.phase('exploring', `accepted tasks are committed; implementation is next: ${titles}`, currentProgress(targetDir));
+            reportExploration(targetDir, `added ${titles}`, options.json ?? false);
+            return 'continue';
+        }
+        if (result.kind === 'none') {
+            explorationFailures = 0;
+            noActionScans++;
+            if (noActionScans % 3 === 0)
+                explorationAgent = nextProvider(explorer, explorationAgent) ?? defaultExplorer;
+            const wait = intervalMinutes * 60_000;
+            const waitingReason = `${focus ? `${focus}; ` : ''}${result.summary}; scanning again in ${intervalMinutes} minute(s)`;
+            reporter.phase('waiting-exploration', waitingReason, currentProgress(targetDir));
+            reportExploration(targetDir, 'no new task met the evidence and quality gates', options.json ?? false, `scan again in ${intervalMinutes} minute(s)`);
+            return await waitForExplorePause(targetDir, wait, () => reporter.phase('waiting-exploration', waitingReason, currentProgress(targetDir)), limitDeadline) ? 'paused' : 'continue';
+        }
+        explorationFailures++;
+        explorationAgent = nextProvider(explorer, result.provider ?? explorationAgent) ?? defaultExplorer;
+        const wait = retryDelay(explorationFailures);
+        const waitingReason = `${focus ? `${focus}; ` : ''}${result.summary}; retrying exploration in ${Math.ceil(wait / 1_000)} seconds`;
+        reporter.phase('waiting-recovery', waitingReason, currentProgress(targetDir));
+        reportExploration(targetDir, 'the explorer could not produce an admissible task', options.json ?? false, `retry in ${Math.ceil(wait / 1_000)} seconds`);
+        return await waitForExplorePause(targetDir, wait, () => reporter.phase('waiting-recovery', waitingReason, currentProgress(targetDir)), limitDeadline) ? 'paused' : 'continue';
+    };
+    const advanceRecoveryProviders = () => {
+        implementationAgent = nextProvider(retryProviders(targetDir, implementationAgent, available), implementationAgent) ?? implementationAgent;
+        if (reviewRequested)
+            reviewerAgent = nextProvider(retryReviewers(reviewerAgent, implementationAgent, available), reviewerAgent) ?? reviewerAgent;
+    };
+    for (;;) {
+        if (consumeExplorePause(targetDir)) {
+            reporter.paused(currentProgress(targetDir));
+            say(`Exploration paused. Next: yoke loop run --explore .`);
+            return 3;
+        }
+        if (limitReached())
+            return stopForTimeLimit();
+        const beforeStatus = readStatus(targetDir);
+        const priorProgress = currentProgress(targetDir);
+        const remaining = options.maxIterations === undefined ? undefined : Math.max(0, options.maxIterations - usedIterations);
+        if (remaining === 0) {
+            reporter.capReached(currentProgress(targetDir));
+            say(`Exploration reached --max=${options.maxIterations}. Next: yoke loop run --explore .`);
+            return 1;
+        }
+        let resultCode;
+        let unexpectedFailure;
+        const batchSize = limitDeadline === undefined ? undefined : safeBatchSize();
+        const batchLimit = batchSize === undefined ? remaining : Math.min(remaining ?? batchSize, batchSize);
+        const cancelTimePause = scheduleExploreLimitPause(targetDir, limitDeadline);
+        try {
+            resultCode = await Promise.resolve(runLoopCommand(targetDir, {
+                ...innerOptions,
+                agent: implementationAgent,
+                ...(reviewRequested && reviewerAgent ? { reviewer: reviewerAgent } : {}),
+                ...(batchLimit !== undefined ? { maxIterations: batchLimit } : {}),
+                ...(retryWorktree ? { resumeWorktree: true, parallel: 1, candidates: 1 } : {}),
+            }));
+        }
+        catch (error) {
+            resultCode = 1;
+            unexpectedFailure = error instanceof Error ? error.message : String(error);
+        }
+        finally {
+            cancelTimePause();
+        }
+        const afterStatus = readStatus(targetDir);
+        const changedStatus = afterStatus?.updatedAt !== beforeStatus?.updatedAt;
+        if (changedStatus && priorProgress.passed < priorProgress.total)
+            usedIterations += Math.max(0, afterStatus?.iteration ?? 0);
+        if (unexpectedFailure) {
+            retryCount++;
+            advanceRecoveryProviders();
+            const wait = retryDelay(retryCount);
+            const reason = `the loop stopped unexpectedly: ${unexpectedFailure}; retrying with ${implementationAgent} in ${Math.ceil(wait / 1_000)} seconds`;
+            reporter.phase('waiting-recovery', reason, currentProgress(targetDir));
+            say(`The loop stopped unexpectedly. Next: retry with ${implementationAgent} in ${Math.ceil(wait / 1_000)} seconds or pause with yoke loop pause .`);
+            if (await waitForExplorePause(targetDir, wait, () => reporter.phase('waiting-recovery', reason, currentProgress(targetDir)), limitDeadline)) {
+                reporter.paused(currentProgress(targetDir));
+                return 3;
+            }
+            continue;
+        }
+        if (resultCode === 3) {
+            if (limitReached())
+                return stopForTimeLimit();
+            say('Exploration paused. Next: yoke loop run --explore .');
+            return 3;
+        }
+        if (limitReached())
+            return stopForTimeLimit();
+        if (options.maxIterations !== undefined && usedIterations >= options.maxIterations) {
+            if (resultCode === 0) {
+                reporter.complete(currentProgress(targetDir));
+                say(`Current backlog complete; --max=${options.maxIterations} stopped further exploration. Next: yoke loop run --explore .`);
+                return 0;
+            }
+            reporter.capReached(currentProgress(targetDir));
+            say(`Exploration reached --max=${options.maxIterations} with work remaining. Next: yoke loop run --explore .`);
+            return 1;
+        }
+        if (resultCode === 0) {
+            retryCount = 0;
+            retryWorktree = false;
+            const availableProviders = retryProviders(targetDir, defaultImplementationAgent, options.isAvailable ?? isAgentAvailable);
+            implementationAgent = availableProviders.includes(defaultImplementationAgent) ? defaultImplementationAgent : availableProviders[0] ?? defaultImplementationAgent;
+            reporter.phase('exploring', 'the current accepted backlog is complete; scanning for the next verified improvement', currentProgress(targetDir));
+            const scan = await scanForWork();
+            if (scan === 'paused')
+                return 3;
+            if (scan === 'limit')
+                return stopForTimeLimit();
+            continue;
+        }
+        if (afterStatus?.state === 'cap-reached') {
+            if (limitDeadline !== undefined) {
+                retryCount = 0;
+                retryWorktree = false;
+                reporter.phase('exploring', 'the current safe task batch is complete; continuing the accepted backlog', currentProgress(targetDir));
+                continue;
+            }
+            say(`The current backlog is incomplete at the requested iteration cap. Next: yoke loop run --explore .`);
+            return 1;
+        }
+        let pendingDecision = false;
+        try {
+            pendingDecision = Boolean(readPendingDecision(targetDir));
+        }
+        catch {
+            pendingDecision = true;
+        }
+        if (pendingDecision || afterStatus?.reason?.includes('ambiguous acceptance criteria')) {
+            retryWorktree = false;
+            const wait = Math.min(intervalMinutes * 60_000, 60_000);
+            reporter.phase('waiting-recovery', `story ${afterStatus?.story ?? 'unknown'} needs a human decision before it can continue`, currentProgress(targetDir));
+            say(`Story ${afterStatus?.story ?? 'unknown'} is waiting for a human decision. Next: answer it or run yoke loop pause .`);
+            if (await waitForExplorePause(targetDir, wait, undefined, limitDeadline)) {
+                reporter.paused(currentProgress(targetDir));
+                return 3;
+            }
+            continue;
+        }
+        if (afterStatus?.reason?.startsWith('integrated completion gate failed') && allCurrentStoriesPass(targetDir)) {
+            retryWorktree = false;
+            reporter.phase('exploring', `all planned tasks pass, but ${afterStatus.reason}; looking for work that can resolve the completion gate`, currentProgress(targetDir));
+            const scan = await scanForWork(`The integrated completion gate is still failing: ${afterStatus.reason}`);
+            if (scan === 'paused')
+                return 3;
+            if (scan === 'limit')
+                return stopForTimeLimit();
+            continue;
+        }
+        if (resultCode === 2) {
+            retryCount++;
+            advanceRecoveryProviders();
+            const wait = retryDelay(retryCount);
+            reporter.phase('waiting-recovery', `the loop could not start; retrying with ${implementationAgent}${reviewerAgent ? ` and reviewer ${reviewerAgent}` : ''} in ${Math.ceil(wait / 1_000)} seconds`, currentProgress(targetDir));
+            say(`The unfinished loop could not start. Next: retry with ${implementationAgent}${reviewerAgent ? ` and reviewer ${reviewerAgent}` : ''} in ${Math.ceil(wait / 1_000)} seconds or pause with yoke loop pause .`);
+            if (await waitForExplorePause(targetDir, wait, undefined, limitDeadline)) {
+                reporter.paused(currentProgress(targetDir));
+                return 3;
+            }
+            continue;
+        }
+        retryCount++;
+        advanceRecoveryProviders();
+        retryWorktree = true;
+        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.`);
+        if (await waitForExplorePause(targetDir, wait, undefined, limitDeadline)) {
+            reporter.paused(currentProgress(targetDir));
+            return 3;
+        }
+    }
+}
 export function runLoopCommand(targetDir, opts) {
+    if (opts.explore && !opts.explorationSupervisor)
+        return runContinuousExploration(targetDir, opts);
     let parallel = opts.parallel ?? 1;
     const candidates = opts.candidates ?? 1;
     if (opts.resumeWorktree && (opts.isolate === false || parallel !== 1 || candidates !== 1)) {
@@ -257,7 +624,8 @@ export function runLoopCommand(targetDir, opts) {
     }
     if (commitIdentity) {
         const announce = opts.json ? console.error : console.log;
-        announce(`Commits: ${commitIdentity.authorName} <${commitIdentity.authorEmail}> · co-authors: ${commitIdentity.allowCoAuthors ? 'allowed' : 'disabled'}`);
+        if (!opts.quiet)
+            announce(`Commits: ${commitIdentity.authorName} <${commitIdentity.authorEmail}> · co-authors: ${commitIdentity.allowCoAuthors ? 'allowed' : 'disabled'}`);
     }
     const idleMs = resolveIdleMs(opts.timeoutMinutes, config.loop.timeoutMinutes);
     const qualityOverrides = {
@@ -268,7 +636,8 @@ export function runLoopCommand(targetDir, opts) {
         ...(opts.candidates !== undefined ? { candidates: opts.candidates } : {}),
     };
     if (qualityOverrides.qualityUnbounded) {
-        console.error('WARNING: Quality repair limits are unbounded for this invocation. Mechanical gates, watchdog, isolation, and commit safety remain active.');
+        if (!opts.quiet)
+            console.error('WARNING: Quality repair limits are unbounded for this invocation. Mechanical gates, watchdog, isolation, and commit safety remain active.');
     }
     const configuredCriticAgent = config.quality?.critic?.agent ?? config.quality?.criticAgent ?? config.agents.find(agent => agent !== runnerAgent) ?? runnerAgent;
     const configuredCriticModel = config.quality?.critic?.model ?? config.quality?.criticModel ?? (configuredCriticAgent === runnerAgent ? config.runner?.model : undefined);
@@ -292,7 +661,8 @@ export function runLoopCommand(targetDir, opts) {
         const repairAgent = config.quality?.repair?.agent ?? config.quality?.repairAgent ?? runnerAgent;
         const limit = resolved.limits.unbounded ? 'unbounded' : `${resolved.limits.maxRounds ?? 3} rounds/${resolved.limits.maxMinutes ?? 60} minutes`;
         const announce = opts.json ? console.error : console.log;
-        announce(`Quality: ${resolved.policy} · critic: ${criticAgent}${configuredCriticModel ? `/${configuredCriticModel}` : '/provider-default'} · repair: ${repairAgent}${config.quality?.repair?.model ?? config.quality?.repairModel ? `/${config.quality?.repair?.model ?? config.quality?.repairModel}` : '/provider-default'} · permissions: read-only critic/safe repair · budget: ${limit}`);
+        if (!opts.quiet)
+            announce(`Quality: ${resolved.policy} · critic: ${criticAgent}${configuredCriticModel ? `/${configuredCriticModel}` : '/provider-default'} · repair: ${repairAgent}${config.quality?.repair?.model ?? config.quality?.repairModel ? `/${config.quality?.repair?.model ?? config.quality?.repairModel}` : '/provider-default'} · permissions: read-only critic/safe repair · budget: ${limit}`);
     }
     const permissions = opts.permissions ?? config.runner?.permissions ?? 'safe';
     const routingRequested = opts.routing ?? config.routing?.enabled ?? true;
@@ -417,7 +787,8 @@ export function runLoopCommand(targetDir, opts) {
             })
             : makeRunner(runnerAgent, idleMs, runnerOpts);
         const announce = opts.json ? console.error : console.log;
-        announce(`Runner: ${runnerAgent} · permissions: ${permissions} · routing: ${routingEnabled ? 'on' : routingRequested ? 'auto (parent; no worker profiles)' : 'off'} · workers: ${parallel} local / ${sharedLimit} shared maximum · isolation: ${isolate || parallel > 1 ? 'on' : 'off'} · cwd: ${targetDir}`);
+        if (!opts.quiet)
+            announce(`Runner: ${runnerAgent} · permissions: ${permissions} · routing: ${routingEnabled ? 'on' : routingRequested ? 'auto (parent; no worker profiles)' : 'off'} · workers: ${parallel} local / ${sharedLimit} shared maximum · isolation: ${isolate || parallel > 1 ? 'on' : 'off'} · cwd: ${targetDir}`);
     }
     if (config.actions?.length) {
         if (parallel > 1 || candidates > 1) {
@@ -496,7 +867,7 @@ 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 });
+    const reporter = opts.reporter ?? makeReporter(targetDir, { json: opts.json, quiet: opts.quiet });
     executionReporter = reporter;
     const buildResume = (storyId, requestId) => buildTrustedDecisionResumeState({
         storyId,
@@ -597,11 +968,13 @@ export function runLoopCommand(targetDir, opts) {
             return resumeCode;
         // In json mode stdout belongs to the NDJSON stream — route the narrative summary to stderr.
         const say = opts.json ? (line) => console.error(line) : (line) => console.log(line);
-        say(`Loop ${result.status} after ${result.iterations} iteration(s): ${result.finalProgress.passed}/${result.finalProgress.total} stories pass`);
-        if (result.reason)
-            say(`Reason: ${result.reason}`);
-        if (result.reason && /api key|please run \/login|not logged in|auth/i.test(result.reason)) {
-            say('Hint: the agent CLI has no credentials in this environment. Set ANTHROPIC_API_KEY, GEMINI_API_KEY, or OPENAI_API_KEY, or log the agent in for headless use.');
+        if (!opts.quiet) {
+            say(`Loop ${result.status} after ${result.iterations} iteration(s): ${result.finalProgress.passed}/${result.finalProgress.total} stories pass`);
+            if (result.reason)
+                say(`Reason: ${result.reason}`);
+            if (result.reason && /api key|please run \/login|not logged in|auth/i.test(result.reason)) {
+                say('Hint: the agent CLI has no credentials in this environment. Set ANTHROPIC_API_KEY, GEMINI_API_KEY, or OPENAI_API_KEY, or log the agent in for headless use.');
+            }
         }
         // Exit codes: 0 complete · 1 blocked/cap-reached · 2 config error (handled above) · 3 paused (loop.pause consumed at a story boundary)
         if (result.status === 'complete')