@mndrk/agx 1.4.20 → 1.4.22

package/lib/cli/cloud/executeVerifySwarm.js

@@ -0,0 +1,302 @@
+/* eslint-disable no-console */
+'use strict';
+
+function createCloudExecuteVerifySwarm(env) {
+  const {
+    path,
+    fs,
+    SWARM_RETRIES,
+    SWARM_MAX_ITERS,
+    VERIFY_TIMEOUT_MS,
+    pRetryFn,
+    logExecutionFlow,
+    resolveStageObjective,
+    buildStageRequirementPrompt,
+    enforceStageRequirement,
+    detectVerifyCommands,
+    runVerifyCommands,
+    getGitSummary,
+    createDaemonArtifactsRecorder,
+    runAgxCommand,
+    runSwarmIteration,
+    buildExecuteIterationPrompt,
+    buildVerifyPrompt,
+    persistIterationArtifacts,
+    finalizeRunSafe,
+    buildLocalRunIndexEntry,
+    postTaskComment,
+    extractJsonLast,
+    ensureExplanation,
+    ensureNextPrompt,
+    abortIfCancelled,
+    resolveAggregatorModel,
+    signalTemporalTask,
+    buildNextPromptWithDecisionContext,
+  } = env || {};
+
+  async function runSwarmExecuteVerifyLoop({ taskId, task, logger, storage, projectSlug, taskSlug, stageLocal, initialPromptContext, cancellationWatcher }) {
+    logExecutionFlow('runSwarmExecuteVerifyLoop', 'input', `taskId=${taskId}`);
+    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;
+
+    const verifierProvider = String(task?.engine || task?.provider || 'claude').toLowerCase();
+    const verifierModel = resolveAggregatorModel(task);
+
+    while (iteration <= SWARM_MAX_ITERS) {
+      logger?.log('system', `[swarm] execute/verify iteration ${iteration} start\n`);
+      await abortIfCancelled(cancellationWatcher);
+
+      const executeRun = await storage.createRun({
+        projectSlug,
+        taskSlug,
+        stage: stageLocal,
+        engine: verifierProvider,
+        model: verifierModel || 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 (swarm iteration)
+      let results;
+      try {
+        results = await runSwarmIteration({
+          taskId,
+          task,
+          prompt: nextPrompt ? buildExecuteIterationPrompt(nextPrompt, iteration) : buildExecuteIterationPrompt('', iteration),
+          logger,
+          artifacts: executeArtifacts,
+          cancellationWatcher,
+          onProviderStdout: (provider, chunk) => {
+            if (!execStdoutStream) return;
+            execStdoutStream.write(`[${provider}] ${chunk.toString()}`);
+          },
+          onProviderStderr: (provider, chunk) => {
+            if (!execStderrStream) return;
+            execStderrStream.write(`[${provider}] ${chunk.toString()}`);
+          },
+        });
+      } catch (err) {
+        executeArtifacts.recordOutput('Execute Error', String(err?.message || err));
+        await executeArtifacts.flush();
+        try { execStdoutStream?.end(); } catch { }
+        try { execStderrStream?.end(); } catch { }
+        await storage.failRun(executeRun, { error: err?.message || 'swarm execute failed', code: 'EXECUTE_FAILED' });
+        lastDecision = {
+          done: false,
+          decision: 'failed',
+          explanation: err?.message || 'Swarm execute phase failed.',
+          final_result: err?.message || 'Swarm execute phase failed.',
+          next_prompt: '',
+          summary: err?.message || 'Swarm execute phase failed.',
+        };
+        return { code: 1, decision: lastDecision, lastRun, runIndexEntry: lastRunEntry };
+      } finally {
+        try { execStdoutStream?.end(); } catch { }
+        try { execStderrStream?.end(); } catch { }
+      }
+
+      const combinedOutput = Array.isArray(results)
+        ? results.map((r) => `[${r.provider}]\n${r.output || ''}`).join('\n\n')
+        : '';
+      executeArtifacts.recordOutput(`Swarm Output (iter ${iteration})`, combinedOutput);
+      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: verifierProvider,
+        model: verifierModel || 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 (${verifierProvider}${verifierModel ? `/${verifierModel}` : ''}, iter ${iteration})`, verifyPrompt);
+
+      const verifyArgs = [verifierProvider, '--prompt', verifyPrompt, '--print'];
+      if (verifierModel) verifyArgs.push('--model', verifierModel);
+
+      let verifyRes;
+      try {
+        await abortIfCancelled(cancellationWatcher);
+        verifyRes = await pRetryFn(
+          () => runAgxCommand(verifyArgs, VERIFY_TIMEOUT_MS, `agx ${verifierProvider} 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: verifierProvider, model: verifierModel || null, role: 'swarm-verify' }, event);
+              void signalTemporalTask(taskId, 'daemonStep', {
+                kind: 'runAgxCommand',
+                task_id: taskId,
+                provider: verifierProvider,
+                model: verifierModel || null,
+                role: 'swarm-verify',
+                iteration,
+                ...event,
+              });
+            },
+            cancellationWatcher,
+          }),
+          { retries: SWARM_RETRIES }
+        );
+      } catch (err) {
+        verifyArtifacts.recordOutput('Verifier Error', String(err?.message || err));
+        await persistIterationArtifacts(storage, { runContainerPath, executeRun, verifyRun, decision: {}, verifyCommands, verifyResults, gitSummary });
+        await verifyArtifacts.flush();
+        try { verifyStdoutStream?.end(); } catch { }
+        try { verifyStderrStream?.end(); } catch { }
+        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 };
+      } finally {
+        try { verifyStdoutStream?.end(); } catch { }
+        try { verifyStderrStream?.end(); } catch { }
+      }
+
+      const verifierText = verifyRes?.stdout || verifyRes?.stderr || '';
+      verifyArtifacts.recordOutput(`Verifier Output (${verifierProvider}${verifierModel ? `/${verifierModel}` : ''}, 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 });
+
+      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);
+
+      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: `Swarm run reached max iterations (${SWARM_MAX_ITERS}).`,
+        final_result: `Swarm run reached max iterations (${SWARM_MAX_ITERS}).`,
+        next_prompt: '',
+        summary: `Swarm run reached max iterations (${SWARM_MAX_ITERS}).`,
+      };
+    }
+
+    return { code: 1, decision: lastDecision, lastRun, runIndexEntry: lastRunEntry };
+  }
+
+  return { runSwarmExecuteVerifyLoop };
+}
+
+module.exports = { createCloudExecuteVerifySwarm };

package/lib/cli/cloud/index.js

@@ -0,0 +1,68 @@
+/* eslint-disable no-console */
+'use strict';
+
+const { createCloudCommandHelpers } = require('./command');
+const { createCloudPromptHelpers } = require('./prompts');
+const { createCloudPersistenceHelpers } = require('./persist');
+const { createCloudIterationHelpers } = require('./iterations');
+const { createCloudAggregateHelpers } = require('./aggregate');
+const { createCloudExecuteVerifySingle } = require('./executeVerifySingle');
+const { createCloudExecuteVerifySwarm } = require('./executeVerifySwarm');
+const { createCloudSimpleLoops } = require('./simpleLoops');
+const { createCloudTaskHelpers } = require('./taskLogger');
+
+function createCloudRunner(env) {
+  const baseEnv = env || {};
+
+  const task = createCloudTaskHelpers(baseEnv);
+  baseEnv.patchTaskState = task.patchTaskState;
+  baseEnv.createTaskLogger = task.createTaskLogger;
+
+  const command = createCloudCommandHelpers(baseEnv);
+  baseEnv.updateCloudTask = command.updateCloudTask;
+  baseEnv.runAgxCommand = command.runAgxCommand;
+
+  const prompts = createCloudPromptHelpers(baseEnv);
+  baseEnv.resolveAggregatorModel = prompts.resolveAggregatorModel;
+  baseEnv.buildAggregatorPrompt = prompts.buildAggregatorPrompt;
+  baseEnv.truncateForPrompt = prompts.truncateForPrompt;
+  baseEnv.buildExecuteIterationPrompt = prompts.buildExecuteIterationPrompt;
+  baseEnv.buildVerifyPrompt = prompts.buildVerifyPrompt;
+
+  const persistence = createCloudPersistenceHelpers(baseEnv);
+  baseEnv.appendRunContainerLog = persistence.appendRunContainerLog;
+  baseEnv.finalizeRunSafe = persistence.finalizeRunSafe;
+  baseEnv.persistIterationArtifacts = persistence.persistIterationArtifacts;
+
+  const iterations = createCloudIterationHelpers(baseEnv);
+  baseEnv.runSwarmIteration = iterations.runSwarmIteration;
+  baseEnv.runSingleAgentIteration = iterations.runSingleAgentIteration;
+
+  const aggregate = createCloudAggregateHelpers(baseEnv);
+  baseEnv.runSingleAgentAggregate = aggregate.runSingleAgentAggregate;
+  baseEnv.runSwarmAggregate = aggregate.runSwarmAggregate;
+
+  const execVerifySingle = createCloudExecuteVerifySingle(baseEnv);
+  baseEnv.runSingleAgentExecuteVerifyLoop = execVerifySingle.runSingleAgentExecuteVerifyLoop;
+
+  const execVerifySwarm = createCloudExecuteVerifySwarm(baseEnv);
+  baseEnv.runSwarmExecuteVerifyLoop = execVerifySwarm.runSwarmExecuteVerifyLoop;
+
+  const simpleLoops = createCloudSimpleLoops(baseEnv);
+  baseEnv.runSingleAgentLoop = simpleLoops.runSingleAgentLoop;
+  baseEnv.runSwarmLoop = simpleLoops.runSwarmLoop;
+
+  return {
+    ...task,
+    ...command,
+    ...prompts,
+    ...persistence,
+    ...iterations,
+    ...aggregate,
+    ...execVerifySingle,
+    ...execVerifySwarm,
+    ...simpleLoops,
+  };
+}
+
+module.exports = { createCloudRunner };

package/lib/cli/cloud/iterations.js

@@ -0,0 +1,155 @@
+/* eslint-disable no-console */
+'use strict';
+
+function createCloudIterationHelpers(env) {
+  const {
+    SWARM_PROVIDERS,
+    SWARM_TIMEOUT_MS,
+    SWARM_RETRIES,
+    pMap,
+    pRetryFn,
+    commandExists,
+    logExecutionFlow,
+    runAgxCommand,
+    updateCloudTask,
+    abortIfCancelled,
+    // Note: additional helpers (comments, artifacts) are handled by higher-level loops.
+  } = env || {};
+
+  async function runSwarmIteration({ taskId, task, prompt, logger, artifacts, cancellationWatcher, onProviderStdout, onProviderStderr }) {
+    logExecutionFlow('runSwarmIteration', 'input', `taskId=${taskId}, prompt=${Boolean(prompt)}`);
+    const swarmModels = Array.isArray(task?.swarm_models)
+      ? task.swarm_models
+        .filter((entry) => entry && entry.provider && entry.model)
+        .map((entry) => ({
+          provider: String(entry.provider).toLowerCase(),
+          model: String(entry.model)
+        }))
+      : [];
+
+    const providers = (swarmModels.length ? swarmModels.map((m) => m.provider) : SWARM_PROVIDERS)
+      .map((p) => p.toLowerCase());
+
+    const missing = providers.filter((p) => !commandExists(p));
+    if (missing.length) {
+      throw new Error(`Missing providers for swarm run: ${missing.join(', ')}`);
+    }
+
+    logExecutionFlow('runSwarmIteration', 'processing', `providers=${providers.join(',')}`);
+    logger?.log('system', `[swarm] iteration start\n`);
+
+    const results = await pMap(providers, (provider, index) => {
+      const args = [provider, '--cloud-task', taskId];
+      const modelForProvider = swarmModels.length
+        ? swarmModels[index]?.model || null
+        : null;
+      if (modelForProvider) {
+        args.push('--model', modelForProvider);
+      }
+      if (prompt) {
+        // The agent already receives full task context via --cloud-task; keep the per-iteration
+        // prompt narrowly scoped to the next instruction to avoid duplicating context.
+        args.push('--prompt', String(prompt));
+      }
+
+      return pRetryFn(
+        () => runAgxCommand(args, SWARM_TIMEOUT_MS, `agx ${provider}`, {
+          onStdout: (data) => {
+            if (typeof onProviderStdout === 'function') onProviderStdout(provider, data);
+            logger?.log('output', data);
+          },
+          onStderr: (data) => {
+            if (typeof onProviderStderr === 'function') onProviderStderr(provider, data);
+            logger?.log('error', data);
+          },
+          onTrace: (event) => {
+            void artifacts?.recordEngineTrace?.({ provider, model: swarmModels.length ? (swarmModels[index]?.model || null) : null, role: 'swarm-iteration' }, event);
+
+            if (taskId) {
+              if (event.phase === 'start' && event.pid) {
+                void updateCloudTask(taskId, { pid: event.pid, started_at: event.started_at });
+              }
+              if (event.phase === 'exit') {
+                void updateCloudTask(taskId, { exit_code: event.exit_code, completed_at: event.finished_at });
+              }
+            }
+          }
+          ,
+          cancellationWatcher,
+        }),
+        {
+          retries: SWARM_RETRIES,
+        }
+      ).then((res) => ({
+        provider,
+        output: res.stdout || res.stderr || ''
+      }));
+    }, { concurrency: providers.length });
+
+    for (const result of results) {
+      logger?.log('output', `\n[${result.provider}] ${result.output}\n`);
+    }
+
+    logExecutionFlow('runSwarmIteration', 'output', `providers finished count=${results.length}`);
+    return results;
+  }
+
+  async function runSingleAgentIteration({ taskId, task, provider, model, prompt, logger, onStdout, onStderr, artifacts, cancellationWatcher }) {
+    logExecutionFlow('runSingleAgentIteration', 'input', `taskId=${taskId}, provider=${provider}, model=${model}, prompt=${Boolean(prompt) ? 'present' : 'none'}`);
+    logExecutionFlow('runSingleAgentIteration', 'processing', 'preparing runAgxCommand');
+    const args = [provider, '--cloud-task', taskId];
+    if (model) {
+      args.push('--model', model);
+    }
+
+    // Record iteration prompt for artifacts
+    // For iteration 1, prompt is empty because context comes via --cloud-task
+    // For subsequent iterations, prompt contains the next_prompt from aggregation
+    const iterationLabel = `Agent Iteration Prompt (${provider}${model ? `/${model}` : ''})`;
+    if (prompt) {
+      const iterPrompt = String(prompt);
+      artifacts?.recordPrompt(iterationLabel, iterPrompt);
+      args.push('--prompt', iterPrompt);
+    } else {
+      // First iteration uses --cloud-task context (already recorded as Initial Task Context)
+      artifacts?.recordPrompt(iterationLabel, `(First iteration: using --cloud-task ${taskId} context)`);
+    }
+
+
+    await abortIfCancelled(cancellationWatcher);
+    const res = await pRetryFn(
+      () => runAgxCommand(args, SWARM_TIMEOUT_MS, `agx ${provider}`, {
+        onStdout: (data) => {
+          if (onStdout) onStdout(data);
+          logger?.log('output', data);
+        },
+        onStderr: (data) => {
+          if (onStderr) onStderr(data);
+          logger?.log('error', data);
+        },
+        onTrace: (event) => {
+          void artifacts?.recordEngineTrace?.({ provider, model: model || null, role: 'single-iteration' }, event);
+
+          if (taskId) {
+            if (event.phase === 'start' && event.pid) {
+              void updateCloudTask(taskId, { pid: event.pid, started_at: event.started_at });
+            }
+            if (event.phase === 'exit') {
+              void updateCloudTask(taskId, { exit_code: event.exit_code, completed_at: event.finished_at });
+            }
+          }
+        },
+        cancellationWatcher,
+      }),
+      { retries: SWARM_RETRIES }
+    );
+
+    const outputSource = res.stdout || res.stderr || '';
+    logExecutionFlow('runSingleAgentIteration', 'output', `response length=${outputSource.length}`);
+    return res.stdout || res.stderr || '';
+  }
+
+  return { runSwarmIteration, runSingleAgentIteration };
+}
+
+module.exports = { createCloudIterationHelpers };

package/lib/cli/cloud/persist.js

@@ -0,0 +1,123 @@
+/* eslint-disable no-console */
+'use strict';
+
+function createCloudPersistenceHelpers(env) {
+  const { fs, path, buildLocalRunIndexEntry } = env || {};
+
+  async function appendRunContainerLog(runContainerPath, relativePath, text) {
+    if (!runContainerPath || !relativePath || !text) return;
+    const filePath = path.join(runContainerPath, relativePath);
+    try {
+      await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
+      const payload = String(text);
+      await fs.promises.appendFile(filePath, payload.endsWith('\n') ? payload : `${payload}\n`, 'utf8');
+    } catch { }
+  }
+
+  async function finalizeRunSafe(storage, run, decision) {
+    if (!storage || !run || run.finalized) return;
+    try {
+      await storage.finalizeRun(run, decision);
+    } catch { }
+  }
+
+  async function persistIterationArtifacts(storage, { runContainerPath, executeRun, verifyRun, decision, verifyCommands, verifyResults, gitSummary }) {
+    if (!storage) return;
+
+    const safeText = (v) => (typeof v === 'string' ? v : '');
+
+    // Ensure the run container has a plan folder so the layout is always:
+    //   <task_slug>/<run_id>/{plan,execute,verify}
+    if (runContainerPath) {
+      try {
+        await fs.promises.mkdir(path.join(runContainerPath, 'plan'), { recursive: true });
+      } catch { }
+    }
+
+    const planMd = safeText(decision?.plan_md) || '# Plan\n\n- (not provided)\n';
+    const implMd = safeText(decision?.implementation_summary_md) || '# Implementation Summary\n\n- (not provided)\n';
+    const verificationMd = safeText(decision?.verification_md) || '# Verification\n\nDONE: no\n\n- (not provided)\n';
+
+    // Write the plan markdown into the plan folder (not under execute/verify).
+    if (runContainerPath) {
+      try {
+        await fs.promises.writeFile(path.join(runContainerPath, 'plan', 'plan.md'), planMd.endsWith('\n') ? planMd : `${planMd}\n`, 'utf8');
+      } catch { }
+    }
+
+    // Implementation summary belongs with the execution phase.
+    if (executeRun?.paths?.artifacts) {
+      try {
+        await storage.writeArtifact(executeRun, 'implementation_summary.md', implMd.endsWith('\n') ? implMd : `${implMd}\n`);
+      } catch (err) {
+        await appendRunContainerLog(runContainerPath, 'daemon/artifact_errors.log', `[${new Date().toISOString()}] execute artifact write failed: ${err?.message || err}`);
+      }
+    }
+
+    // Verification outputs (including command logs) belong with the verify phase.
+    if (verifyRun?.paths?.artifacts) {
+      try {
+        await storage.writeArtifact(verifyRun, 'verification.md', verificationMd.endsWith('\n') ? verificationMd : `${verificationMd}\n`);
+      } catch (err) {
+        await appendRunContainerLog(runContainerPath, 'daemon/artifact_errors.log', `[${new Date().toISOString()}] verify artifact write failed (verification.md): ${err?.message || err}`);
+      }
+
+      const payload = {
+        commands: Array.isArray(verifyCommands) ? verifyCommands : [],
+        results: Array.isArray(verifyResults) ? verifyResults.map((r) => ({
+          id: r.id,
+          label: r.label,
+          cmd: r.cmd,
+          args: r.args,
+          cwd: r.cwd,
+          exit_code: r.exit_code,
+          duration_ms: r.duration_ms,
+          error: r.error,
+        })) : [],
+        git: gitSummary || null,
+      };
+
+      try {
+        await storage.writeArtifact(verifyRun, 'verify_commands.json', JSON.stringify(payload, null, 2) + '\n');
+      } catch (err) {
+        await appendRunContainerLog(runContainerPath, 'daemon/artifact_errors.log', `[${new Date().toISOString()}] verify artifact write failed (verify_commands.json): ${err?.message || err}`);
+      }
+
+      if (Array.isArray(verifyResults)) {
+        for (let i = 0; i < verifyResults.length; i += 1) {
+          const r = verifyResults[i];
+          const base = `verify_results/${String(i + 1).padStart(2, '0')}-${String(r.id || `cmd_${i + 1}`).replace(/[^a-z0-9_-]/gi, '_')}`;
+          try { await storage.writeArtifact(verifyRun, `${base}.stdout.txt`, (r.stdout || '').toString()); } catch { }
+          try { await storage.writeArtifact(verifyRun, `${base}.stderr.txt`, (r.stderr || '').toString()); } catch { }
+        }
+      }
+
+      if (gitSummary?.status_porcelain) {
+        try { await storage.writeArtifact(verifyRun, 'git_status.txt', String(gitSummary.status_porcelain)); } catch { }
+      }
+      if (gitSummary?.diff_stat) {
+        try { await storage.writeArtifact(verifyRun, 'git_diffstat.txt', String(gitSummary.diff_stat)); } catch { }
+      }
+    }
+  }
+
+  async function buildRunIndexEntrySafe(storage, verifyRun, localDecisionStatus) {
+    if (!storage || !verifyRun || !localDecisionStatus) return null;
+    if (typeof buildLocalRunIndexEntry !== 'function') return null;
+    try {
+      return await buildLocalRunIndexEntry(storage, verifyRun, localDecisionStatus);
+    } catch {
+      return null;
+    }
+  }
+
+  return {
+    appendRunContainerLog,
+    finalizeRunSafe,
+    persistIterationArtifacts,
+    buildRunIndexEntrySafe,
+  };
+}
+
+module.exports = { createCloudPersistenceHelpers };
+