@mndrk/agx 1.4.20 → 1.4.22

package/lib/cli/cloud/aggregate.js

@@ -0,0 +1,162 @@
+/* eslint-disable no-console */
+'use strict';
+
+function createCloudAggregateHelpers(env) {
+  const {
+    SWARM_TIMEOUT_MS,
+    SWARM_RETRIES,
+    pRetryFn,
+    logExecutionFlow,
+    runAgxCommand,
+    resolveStageObjective,
+    buildStageRequirementPrompt,
+    enforceStageRequirement,
+    ensureExplanation,
+    ensureNextPrompt,
+    extractFileRefsFromText,
+    extractJson,
+    signalTemporalTask,
+    buildAggregatorPrompt,
+    resolveAggregatorModel,
+    abortIfCancelled,
+  } = env || {};
+
+  async function runSingleAgentAggregate({ task, taskId, prompt, output, iteration, logger, provider, model, artifacts, cancellationWatcher }) {
+    logExecutionFlow('runSingleAgentAggregate', 'input', `taskId=${taskId}, iteration=${iteration}`);
+    logExecutionFlow('runSingleAgentAggregate', 'processing', 'running aggregator');
+    const stageKey = task?.stage || 'unknown';
+    const stagePrompt = resolveStageObjective(task, stageKey, '');
+    const stageRequirement = buildStageRequirementPrompt({ stage: stageKey, stagePrompt });
+    const aggregatorProvider = String(provider || task?.provider || task?.engine || 'claude').toLowerCase();
+    const aggregatorModel = typeof model === 'string' && model.trim() ? model.trim() : null;
+    const fileRefs = extractFileRefsFromText(output, { max: 20 });
+
+    const aggregatePrompt = buildAggregatorPrompt({
+      role: 'single-agent',
+      taskId,
+      task,
+      stagePrompt,
+      stageRequirement,
+      runPath: artifacts?.runPath || null,
+      fileRefs,
+    });
+    artifacts?.recordPrompt(`Aggregator Prompt (${aggregatorProvider}${aggregatorModel ? `/${aggregatorModel}` : ''})`, aggregatePrompt);
+
+    const aggregateArgs = [aggregatorProvider, '--prompt', aggregatePrompt, '--print'];
+    if (aggregatorModel) {
+      aggregateArgs.push('--model', aggregatorModel);
+    }
+
+    await abortIfCancelled(cancellationWatcher);
+    const res = await pRetryFn(
+      () => runAgxCommand(aggregateArgs, SWARM_TIMEOUT_MS, `agx ${aggregatorProvider} aggregate`, {
+        onStdout: (data) => logger?.log('checkpoint', data),
+        onStderr: (data) => logger?.log('error', data),
+        onTrace: (event) => {
+          void artifacts?.recordEngineTrace?.({ provider: aggregatorProvider, model: aggregatorModel || null, role: 'single-aggregate' }, event);
+        },
+        cancellationWatcher,
+      }),
+      { retries: SWARM_RETRIES }
+    );
+
+    const decision = extractJson(res.stdout) || extractJson(res.stderr);
+    logExecutionFlow('runSingleAgentAggregate', 'output', `decision=${JSON.stringify(decision || {})}`);
+    if (!decision) {
+      logger?.log('error', '[single] Aggregator returned invalid JSON\n');
+      return { done: true, decision: 'failed', explanation: 'Aggregator response was not valid JSON.', final_result: 'Aggregator response was not valid JSON.', next_prompt: '', summary: 'Aggregator response was not valid JSON.' };
+    }
+
+    logger?.log('checkpoint', `[single] decision ${JSON.stringify(decision)}\n`);
+
+    return ensureExplanation(enforceStageRequirement({
+      done: Boolean(decision.done),
+      decision: typeof decision.decision === 'string' ? decision.decision : '',
+      explanation: typeof decision.explanation === 'string' ? decision.explanation : '',
+      final_result: typeof decision.final_result === 'string' ? decision.final_result : '',
+      next_prompt: typeof decision.next_prompt === 'string' ? decision.next_prompt : '',
+      summary: typeof decision.summary === 'string' ? decision.summary : ''
+    }, { stage: stageKey, stagePrompt }));
+  }
+
+  async function runSwarmAggregate({ task, taskId, prompt, results, iteration, logger, artifacts }) {
+    const providerList = results.map((r) => r.provider).join(',');
+    logExecutionFlow('runSwarmAggregate', 'input', `taskId=${taskId}, iteration=${iteration}, providers=${providerList}`);
+    const stageKey = task?.stage || 'unknown';
+    const stagePrompt = resolveStageObjective(task, stageKey, '');
+    const stageRequirement = buildStageRequirementPrompt({ stage: stageKey, stagePrompt });
+    const aggregatorProvider = String(task?.engine || task?.provider || 'claude').toLowerCase();
+    const aggregatorModel = resolveAggregatorModel(task);
+    const fileRefs = extractFileRefsFromText(
+      results.map((r) => r?.output || '').filter(Boolean).join('\n\n'),
+      { max: 20 }
+    );
+
+    const aggregatePrompt = buildAggregatorPrompt({
+      role: 'swarm',
+      taskId,
+      task,
+      stagePrompt,
+      stageRequirement,
+      runPath: artifacts?.runPath || null,
+      fileRefs,
+    });
+    artifacts?.recordPrompt(`Swarm Aggregator Prompt (${aggregatorProvider}${aggregatorModel ? `/${aggregatorModel}` : ''})`, aggregatePrompt);
+
+    const aggregateArgs = [aggregatorProvider, '--prompt', aggregatePrompt, '--print'];
+    if (aggregatorModel) {
+      aggregateArgs.push('--model', aggregatorModel);
+    }
+
+    logExecutionFlow('runSwarmAggregate', 'processing', 'running aggregator');
+    const res = await pRetryFn(
+      () => runAgxCommand(aggregateArgs, SWARM_TIMEOUT_MS, `agx ${aggregatorProvider} aggregate`, {
+        onStdout: (data) => logger?.log('checkpoint', data),
+        onStderr: (data) => logger?.log('error', data),
+        onTrace: (event) => {
+          void artifacts?.recordEngineTrace?.({ provider: aggregatorProvider, model: aggregatorModel || null, role: 'swarm-aggregate' }, event);
+          void signalTemporalTask(taskId, 'daemonStep', {
+            kind: 'runAgxCommand',
+            task_id: taskId,
+            provider: aggregatorProvider,
+            model: aggregatorModel || null,
+            role: 'swarm-aggregate',
+            iteration,
+            providers: results.map((r) => r.provider),
+            ...event,
+          });
+        },
+      }),
+      { retries: SWARM_RETRIES }
+    );
+
+    const decision = extractJson(res.stdout) || extractJson(res.stderr);
+    logExecutionFlow('runSwarmAggregate', 'output', `decision=${JSON.stringify(decision || {})}`);
+    if (!decision) {
+      logger?.log('error', '[swarm] Aggregator returned invalid JSON\n');
+      return {
+        done: true,
+        decision: 'failed',
+        explanation: 'Aggregator response was not valid JSON.',
+        final_result: 'Aggregator response was not valid JSON.',
+        next_prompt: '',
+        summary: 'Aggregator response was not valid JSON.'
+      };
+    }
+
+    logger?.log('checkpoint', `[swarm] decision ${JSON.stringify(decision)}\n`);
+
+    return enforceStageRequirement({
+      done: Boolean(decision.done),
+      decision: typeof decision.decision === 'string' ? decision.decision : '',
+      explanation: typeof decision.explanation === 'string' ? decision.explanation : '',
+      final_result: typeof decision.final_result === 'string' ? decision.final_result : '',
+      next_prompt: typeof decision.next_prompt === 'string' ? decision.next_prompt : '',
+      summary: typeof decision.summary === 'string' ? decision.summary : ''
+    }, { stage: stageKey, stagePrompt });
+  }
+
+  return { runSingleAgentAggregate, runSwarmAggregate };
+}
+
+module.exports = { createCloudAggregateHelpers };

package/lib/cli/cloud/command.js

@@ -0,0 +1,230 @@
+/* eslint-disable no-console */
+'use strict';
+
+function createCloudCommandHelpers(env) {
+  const {
+    loadCloudConfigFile,
+    fetch,
+    sanitizeCliArgs,
+    logExecutionFlow,
+    spawnCloudTaskProcess,
+    randomId,
+    appendTail,
+    truncateForTemporalTrace,
+    extractCancellationReason,
+    CancellationRequestedError,
+    CANCELLED_ERROR_CODE,
+  } = env || {};
+
+  async function updateCloudTask(taskId, updates) {
+    const cloudConfig = loadCloudConfigFile();
+    if (!cloudConfig?.apiUrl) return;
+    if (!taskId) return;
+
+    try {
+      const headers = {
+        'Content-Type': 'application/json',
+        'x-user-id': cloudConfig.userId || '',
+      };
+      if (cloudConfig?.token) {
+        headers.Authorization = `Bearer ${cloudConfig.token}`;
+      }
+      // Assume standard API route is /api/tasks/:id
+      await fetch(`${cloudConfig.apiUrl}/api/tasks/${encodeURIComponent(taskId)}`, {
+        method: 'PATCH',
+        headers,
+        body: JSON.stringify(updates),
+      });
+    } catch (err) {
+      // Silent fail or log debug
+      // console.debug('Failed to update cloud task', err);
+    }
+  }
+
+  function runAgxCommand(args, timeoutMs, label, handlers = {}) {
+    return new Promise((resolve, reject) => {
+      let stdout = '';
+      let stderr = '';
+      let stdoutTail = '';
+      let stderrTail = '';
+      let settled = false;
+
+      const childArgs = sanitizeCliArgs([process.argv[1], ...args]);
+      logExecutionFlow('runAgxCommand', 'input', `label=${label}, args=${childArgs.join(' ')}, timeout=${timeoutMs}`);
+      const cancellationWatcher = handlers.cancellationWatcher || null;
+      const child = spawnCloudTaskProcess(childArgs);
+      logExecutionFlow('runAgxCommand', 'processing', `spawning child process (pid: ${child.pid})`);
+
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), timeoutMs);
+      const traceId = randomId();
+      const startedAt = Date.now();
+      const startedAtIso = new Date(startedAt).toISOString();
+      const emitTrace = (event) => {
+        if (!handlers || typeof handlers.onTrace !== 'function') return;
+        try {
+          handlers.onTrace(event);
+        } catch { }
+      };
+
+      emitTrace({
+        id: traceId,
+        phase: 'start',
+        label,
+        args: childArgs,
+        pid: child?.pid || null,
+        timeout_ms: timeoutMs,
+        started_at: startedAtIso,
+      });
+
+      if (cancellationWatcher?.start) {
+        try {
+          cancellationWatcher.start();
+        } catch { }
+      }
+
+      let cancelUnsubscribe = null;
+      const cleanupCancellation = () => {
+        if (cancelUnsubscribe) {
+          cancelUnsubscribe();
+          cancelUnsubscribe = null;
+        }
+      };
+
+      const handleCancellation = (payload) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timeout);
+        if (child && typeof child.kill === 'function') {
+          child.kill('SIGTERM');
+          setTimeout(() => {
+            child.kill('SIGKILL');
+          }, 500);
+        }
+        const reason = extractCancellationReason(payload) || 'Cancelled by operator';
+        const err = new CancellationRequestedError(reason);
+        err.code = CANCELLED_ERROR_CODE;
+        err.payload = payload;
+        err.stdout = stdout;
+        err.stderr = stderr;
+        emitTrace({
+          id: traceId,
+          phase: 'cancel',
+          label,
+          args: childArgs,
+          pid: child?.pid || null,
+          timeout_ms: timeoutMs,
+          started_at: startedAtIso,
+          finished_at: new Date().toISOString(),
+          duration_ms: Date.now() - startedAt,
+          stdout_tail: truncateForTemporalTrace(stdoutTail),
+          stderr_tail: truncateForTemporalTrace(stderrTail),
+          error: err.message,
+        });
+        cleanupCancellation();
+        reject(err);
+      };
+
+      if (cancellationWatcher?.onCancel) {
+        cancelUnsubscribe = cancellationWatcher.onCancel(handleCancellation);
+      }
+
+      controller.signal.addEventListener('abort', () => {
+        if (settled) return;
+        settled = true;
+        child.kill('SIGKILL');
+        const err = new Error(`${label || 'command'} timed out`);
+        err.code = 'ETIMEDOUT';
+        clearTimeout(timeout);
+        emitTrace({
+          id: traceId,
+          phase: 'timeout',
+          label,
+          args: childArgs,
+          pid: child?.pid || null,
+          timeout_ms: timeoutMs,
+          started_at: startedAtIso,
+          finished_at: new Date().toISOString(),
+          duration_ms: Date.now() - startedAt,
+          stdout_tail: truncateForTemporalTrace(stdoutTail),
+          stderr_tail: truncateForTemporalTrace(stderrTail),
+          error: err.message,
+        });
+        cleanupCancellation();
+        reject(err);
+      });
+
+      child.stdout.on('data', (data) => {
+        const chunk = data.toString();
+        stdout += chunk;
+        stdoutTail = appendTail(stdoutTail, chunk);
+        if (handlers.onStdout) handlers.onStdout(data);
+      });
+      child.stderr.on('data', (data) => {
+        const chunk = data.toString();
+        stderr += chunk;
+        stderrTail = appendTail(stderrTail, chunk);
+        if (handlers.onStderr) handlers.onStderr(data);
+      });
+
+      child.on('error', (err) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timeout);
+        logExecutionFlow('runAgxCommand', 'output', `error ${err?.message || err}`);
+        emitTrace({
+          id: traceId,
+          phase: 'error',
+          label,
+          args: childArgs,
+          pid: child?.pid || null,
+          timeout_ms: timeoutMs,
+          started_at: startedAtIso,
+          finished_at: new Date().toISOString(),
+          duration_ms: Date.now() - startedAt,
+          stdout_tail: truncateForTemporalTrace(stdoutTail),
+          stderr_tail: truncateForTemporalTrace(stderrTail),
+          error: err?.message || String(err),
+        });
+        cleanupCancellation();
+        reject(err);
+      });
+
+      child.on('close', (code) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timeout);
+        logExecutionFlow('runAgxCommand', 'output', `pid=${child.pid}, exit code=${code}`);
+        emitTrace({
+          id: traceId,
+          phase: 'exit',
+          label,
+          args: childArgs,
+          pid: child?.pid || null,
+          timeout_ms: timeoutMs,
+          started_at: startedAtIso,
+          finished_at: new Date().toISOString(),
+          duration_ms: Date.now() - startedAt,
+          exit_code: code,
+          stdout_tail: truncateForTemporalTrace(stdoutTail),
+          stderr_tail: truncateForTemporalTrace(stderrTail),
+        });
+        cleanupCancellation();
+        if (code === 0) {
+          resolve({ stdout, stderr, code });
+        } else {
+          const err = new Error(`${label || 'command'} exited with code ${code}`);
+          err.code = code;
+          err.stdout = stdout;
+          err.stderr = stderr;
+          reject(err);
+        }
+      });
+    });
+  }
+
+  return { updateCloudTask, runAgxCommand };
+}
+
+module.exports = { createCloudCommandHelpers };
+

package/lib/cli/cloud/executeVerifySingle.js

@@ -0,0 +1,293 @@
+/* eslint-disable no-console */
+'use strict';
+
+function createCloudExecuteVerifySingle(env) {
+  const {
+    path,
+    fs,
+    SWARM_RETRIES,
+    SINGLE_MAX_ITERS,
+    VERIFY_TIMEOUT_MS,
+    pRetryFn,
+    logExecutionFlow,
+    resolveStageObjective,
+    buildStageRequirementPrompt,
+    enforceStageRequirement,
+    detectVerifyCommands,
+    runVerifyCommands,
+    getGitSummary,
+    createDaemonArtifactsRecorder,
+    runAgxCommand,
+    runSingleAgentIteration,
+    buildExecuteIterationPrompt,
+    buildVerifyPrompt,
+    persistIterationArtifacts,
+    finalizeRunSafe,
+    buildLocalRunIndexEntry,
+    postTaskComment,
+    extractJsonLast,
+    ensureExplanation,
+    ensureNextPrompt,
+    abortIfCancelled,
+    CancellationRequestedError,
+    buildNextPromptWithDecisionContext,
+  } = env || {};
+
+  async function runSingleAgentExecuteVerifyLoop({ taskId, task, provider, model, logger, storage, projectSlug, taskSlug, stageLocal, initialPromptContext, cancellationWatcher }) {
+    logExecutionFlow('runSingleAgentExecuteVerifyLoop', 'input', `taskId=${taskId}, provider=${provider}, model=${model}`);
+    const stageKey = task?.stage || 'unknown';
+    const stagePrompt = resolveStageObjective(task, stageKey, '');
+    const stageRequirement = buildStageRequirementPrompt({ stage: stageKey, stagePrompt });
+
+    let iteration = 1;
+    let nextPrompt = '';
+    let lastDecision = null;
+    let lastRun = null;
+    let lastRunEntry = null;
+
+    while (iteration <= SINGLE_MAX_ITERS) {
+      logger?.log('system', `[single] execute/verify iteration ${iteration} start\n`);
+      logExecutionFlow('runSingleAgentExecuteVerifyLoop', 'processing', `iteration ${iteration} start`);
+      await abortIfCancelled(cancellationWatcher);
+
+      const executeRun = await storage.createRun({
+        projectSlug,
+        taskSlug,
+        stage: stageLocal,
+        engine: provider,
+        model: model || undefined,
+      });
+      lastRun = executeRun;
+      const runContainerPath = executeRun?.paths?.root ? path.dirname(executeRun.paths.root) : null;
+
+      const executeArtifacts = createDaemonArtifactsRecorder({ storage, run: executeRun, taskId });
+      if (iteration === 1 && initialPromptContext) {
+        executeArtifacts.recordPrompt('Initial Task Context', initialPromptContext);
+      }
+
+      // Tee spawned agx output into files under execute artifacts.
+      const execStdoutPath = executeRun?.paths?.artifacts ? path.join(executeRun.paths.artifacts, 'spawned.stdout.log') : null;
+      const execStderrPath = executeRun?.paths?.artifacts ? path.join(executeRun.paths.artifacts, 'spawned.stderr.log') : null;
+      const execStdoutStream = execStdoutPath ? fs.createWriteStream(execStdoutPath, { flags: 'a' }) : null;
+      const execStderrStream = execStderrPath ? fs.createWriteStream(execStderrPath, { flags: 'a' }) : null;
+
+      // EXECUTE
+      const executePrompt = buildExecuteIterationPrompt(nextPrompt, iteration);
+      let output = '';
+      try {
+        output = await runSingleAgentIteration({
+          taskId,
+          task,
+          provider,
+          model,
+          prompt: executePrompt,
+          logger,
+          onStdout: (chunk) => {
+            try { execStdoutStream?.write(chunk.toString()); } catch { }
+          },
+          onStderr: (chunk) => {
+            try { execStderrStream?.write(chunk.toString()); } catch { }
+          },
+          artifacts: executeArtifacts,
+          cancellationWatcher,
+        });
+      } catch (err) {
+        const message = err?.stdout || err?.stderr || err?.message || 'Single-agent execute phase failed.';
+        executeArtifacts.recordOutput('Execute Error', String(message));
+        await executeArtifacts.flush();
+        try { execStdoutStream?.end(); } catch { }
+        try { execStderrStream?.end(); } catch { }
+        await storage.failRun(executeRun, { error: err?.message || 'execute failed', code: 'EXECUTE_FAILED' });
+        lastDecision = {
+          done: false,
+          decision: 'failed',
+          explanation: err?.message || 'Single-agent execute phase failed.',
+          final_result: message,
+          next_prompt: '',
+          summary: err?.message || 'Single-agent execute phase failed.',
+        };
+        return { code: 1, decision: lastDecision, lastRun, runIndexEntry: lastRunEntry };
+      }
+      try { execStdoutStream?.end(); } catch { }
+      try { execStderrStream?.end(); } catch { }
+      executeArtifacts.recordOutput(`Agent Output (${provider}${model ? `/${model}` : ''}, iter ${iteration})`, output);
+      await executeArtifacts.flush();
+
+      // VERIFY (local commands)
+      const verifyCommands = detectVerifyCommands({ cwd: process.cwd() });
+      const gitSummary = getGitSummary({ cwd: process.cwd() });
+      const verifyResults = await runVerifyCommands(verifyCommands, { cwd: process.cwd(), max_output_chars: 20000 });
+
+      const verifyRun = await storage.createRun({
+        projectSlug,
+        taskSlug,
+        stage: 'verify',
+        runId: executeRun.run_id,
+        engine: provider,
+        model: model || undefined,
+      });
+      lastRun = verifyRun;
+
+      // Tee verifier stdout/stderr to files under verify artifacts.
+      const verifyStdoutPath = verifyRun?.paths?.artifacts ? path.join(verifyRun.paths.artifacts, 'spawned.stdout.log') : null;
+      const verifyStderrPath = verifyRun?.paths?.artifacts ? path.join(verifyRun.paths.artifacts, 'spawned.stderr.log') : null;
+      const verifyStdoutStream = verifyStdoutPath ? fs.createWriteStream(verifyStdoutPath, { flags: 'a' }) : null;
+      const verifyStderrStream = verifyStderrPath ? fs.createWriteStream(verifyStderrPath, { flags: 'a' }) : null;
+
+      // VERIFY (LLM)
+      const verifyPrompt = buildVerifyPrompt({
+        taskId,
+        task,
+        stagePrompt,
+        stageRequirement,
+        gitSummary,
+        verifyResults,
+        iteration,
+        lastRunPath: runContainerPath || verifyRun?.paths?.root || null,
+      });
+      const verifyArtifacts = createDaemonArtifactsRecorder({ storage, run: verifyRun, taskId });
+      verifyArtifacts.recordPrompt(`Verification Prompt (${provider}${model ? `/${model}` : ''}, iter ${iteration})`, verifyPrompt);
+
+      const verifyArgs = [provider, '--prompt', verifyPrompt, '--print'];
+      if (model) verifyArgs.push('--model', model);
+
+      await abortIfCancelled(cancellationWatcher);
+
+      let verifyRes;
+      try {
+        verifyRes = await pRetryFn(
+          () => runAgxCommand(verifyArgs, VERIFY_TIMEOUT_MS, `agx ${provider} verify`, {
+            onStdout: (data) => {
+              try { verifyStdoutStream?.write(data.toString()); } catch { }
+              logger?.log('checkpoint', data);
+            },
+            onStderr: (data) => {
+              try { verifyStderrStream?.write(data.toString()); } catch { }
+              logger?.log('error', data);
+            },
+            onTrace: (event) => {
+              void verifyArtifacts?.recordEngineTrace?.({ provider, model: model || null, role: 'single-verify' }, event);
+            },
+            cancellationWatcher,
+          }),
+          { retries: SWARM_RETRIES }
+        );
+      } catch (err) {
+        try { verifyStdoutStream?.end(); } catch { }
+        try { verifyStderrStream?.end(); } catch { }
+        if (err instanceof CancellationRequestedError) {
+          throw err;
+        }
+        verifyArtifacts.recordOutput('Verifier Error', String(err?.message || err));
+        await persistIterationArtifacts(storage, { runContainerPath, executeRun, verifyRun, decision: {}, verifyCommands, verifyResults, gitSummary });
+        await verifyArtifacts.flush();
+        await storage.failRun(verifyRun, { error: err?.message || 'verify failed', code: 'VERIFY_FAILED' });
+        await finalizeRunSafe(storage, executeRun, { status: 'failed', reason: `Verification failed: ${err?.message || 'verify failed'}` });
+        lastDecision = {
+          done: false,
+          decision: 'failed',
+          explanation: err?.message || 'Verifier failed.',
+          final_result: err?.message || 'Verifier failed.',
+          next_prompt: '',
+          summary: err?.message || 'Verifier failed.',
+        };
+        return { code: 1, decision: lastDecision, lastRun, runIndexEntry: lastRunEntry };
+      }
+      try { verifyStdoutStream?.end(); } catch { }
+      try { verifyStderrStream?.end(); } catch { }
+
+      const verifierText = verifyRes?.stdout || verifyRes?.stderr || '';
+      verifyArtifacts.recordOutput(`Verifier Output (${provider}${model ? `/${model}` : ''}, iter ${iteration})`, verifierText);
+
+      let decision = extractJsonLast(verifierText);
+      if (!decision) decision = extractJsonLast(verifyRes?.stderr || '');
+      if (!decision) {
+        decision = {
+          done: false,
+          decision: 'failed',
+          explanation: 'Verifier returned invalid JSON.',
+          final_result: 'Verifier returned invalid JSON.',
+          next_prompt: '',
+          summary: 'Verifier returned invalid JSON.',
+        };
+      }
+
+      decision = ensureExplanation(ensureNextPrompt(enforceStageRequirement({
+        done: Boolean(decision.done),
+        decision: typeof decision.decision === 'string' ? decision.decision : '',
+        explanation: typeof decision.explanation === 'string' ? decision.explanation : '',
+        final_result: typeof decision.final_result === 'string' ? decision.final_result : '',
+        next_prompt: typeof decision.next_prompt === 'string' ? decision.next_prompt : '',
+        summary: typeof decision.summary === 'string' ? decision.summary : '',
+        plan_md: typeof decision.plan_md === 'string' ? decision.plan_md : '',
+        implementation_summary_md: typeof decision.implementation_summary_md === 'string' ? decision.implementation_summary_md : '',
+        verification_md: typeof decision.verification_md === 'string' ? decision.verification_md : '',
+      }, { stage: stageKey, stagePrompt })));
+
+      lastDecision = decision;
+
+      await persistIterationArtifacts(storage, { runContainerPath, executeRun, verifyRun, decision, verifyCommands, verifyResults, gitSummary });
+
+      // Finalize this iteration (verify) run.
+      verifyArtifacts.recordOutput('Daemon Decision', JSON.stringify(decision || {}, null, 2));
+      await verifyArtifacts.flush();
+
+      const statusMap = {
+        done: 'done',
+        blocked: 'blocked',
+        not_done: 'continue',
+        failed: 'failed',
+      };
+      const localDecisionStatus = statusMap[String(decision?.decision || 'failed')] || 'failed';
+      await finalizeRunSafe(storage, executeRun, {
+        status: localDecisionStatus,
+        reason: 'Execute phase completed; see verify stage for decision.',
+      });
+      await storage.finalizeRun(verifyRun, {
+        status: localDecisionStatus,
+        reason: decision?.explanation || decision?.summary || '',
+      });
+
+      lastRunEntry = await buildLocalRunIndexEntry(storage, verifyRun, localDecisionStatus);
+
+      // Update local task status.
+      const localTaskStatusMap = {
+        done: 'done',
+        blocked: 'blocked',
+        not_done: 'running',
+        failed: 'failed',
+      };
+      const nextLocalStatus = localTaskStatusMap[String(decision?.decision || 'failed')] || 'failed';
+      await storage.updateTaskState(projectSlug, taskSlug, { status: nextLocalStatus });
+
+      await postTaskComment(taskId, decision.summary || decision.explanation || '');
+
+      if (['done', 'blocked', 'failed'].includes(String(decision?.decision || ''))) {
+        const code = decision?.decision === 'done' ? 0 : 1;
+        return { code, decision: lastDecision, lastRun, runIndexEntry: lastRunEntry };
+      }
+
+      nextPrompt = (typeof buildNextPromptWithDecisionContext === 'function'
+        ? buildNextPromptWithDecisionContext(decision)
+        : (decision?.next_prompt || ''));
+      iteration += 1;
+    }
+
+    if (!lastDecision) {
+      lastDecision = {
+        done: false,
+        decision: 'not_done',
+        explanation: `Single-agent run reached max iterations (${SINGLE_MAX_ITERS}).`,
+        final_result: `Single-agent run reached max iterations (${SINGLE_MAX_ITERS}).`,
+        next_prompt: '',
+        summary: `Single-agent run reached max iterations (${SINGLE_MAX_ITERS}).`,
+      };
+    }
+
+    return { code: 1, decision: lastDecision, lastRun, runIndexEntry: lastRunEntry };
+  }
+
+  return { runSingleAgentExecuteVerifyLoop };
+}
+
+module.exports = { createCloudExecuteVerifySingle };