superlab 0.1.12 → 0.1.13

package/lib/auto_runner.cjs

@@ -0,0 +1,830 @@
+const fs = require("node:fs");
+const { spawn } = require("node:child_process");
+const { refreshContext } = require("./context.cjs");
+const { parseEvalProtocol, validateEvalProtocol } = require("./eval_protocol.cjs");
+const {
+  isMeaningful,
+  parseDurationMs,
+  parseInteger,
+  sleep,
+} = require("./auto_common.cjs");
+const {
+  detectFrozenCoreChanges,
+  resolveStageCommand,
+  snapshotFrozenCore,
+  snapshotPaths,
+  splitAutoStages,
+  stageContractSnapshot,
+  validateAutoMode,
+  validateAutoStatus,
+  verifyPromotionWriteback,
+  verifyStageContract,
+} = require("./auto_contracts.cjs");
+const {
+  parseAutoMode,
+  parseAutoStatus,
+  readWorkflowLanguage,
+  resolveRequiredArtifact,
+  writeAutoOutcome,
+  writeAutoStatus,
+} = require("./auto_state.cjs");
+
+function normalizeTransition(value) {
+  return (value || "").trim();
+}
+
+function isSuccessTransition(value) {
+  return ["success", "terminal-success", "campaign-success"].includes((value || "").trim().toLowerCase());
+}
+
+function isStopTransition(value) {
+  return ["stop", "campaign-stop", "terminal-stop"].includes((value || "").trim().toLowerCase());
+}
+
+async function runCommandWithPolling({
+  targetDir,
+  stage,
+  command,
+  pollIntervalMs,
+  deadlineMs,
+  startedAt,
+  status,
+  lang,
+  rungId = "",
+  watchTarget = "",
+  nextRung = "",
+}) {
+  const child = spawn(command, {
+    cwd: targetDir,
+    shell: true,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+
+  let stdout = "";
+  let stderr = "";
+  let exitCode = null;
+  let signalCode = null;
+
+  child.stdout.on("data", (chunk) => {
+    if (stdout.length < 4000) {
+      stdout += chunk.toString("utf8");
+    }
+  });
+  child.stderr.on("data", (chunk) => {
+    if (stderr.length < 4000) {
+      stderr += chunk.toString("utf8");
+    }
+  });
+  child.on("exit", (code, signal) => {
+    exitCode = code;
+    signalCode = signal;
+  });
+
+  while (exitCode === null && signalCode === null) {
+    if (Date.now() > deadlineMs) {
+      child.kill("SIGTERM");
+      await sleep(50);
+      if (child.exitCode === null && child.signalCode === null) {
+        child.kill("SIGKILL");
+      }
+      throw new Error(`auto stage timed out: ${stage}`);
+    }
+
+    writeAutoStatus(
+      targetDir,
+      {
+        ...status,
+        status: "running",
+        currentStage: stage,
+        currentCommand: command,
+        currentRung: rungId,
+        watchTarget,
+        nextRung,
+        startedAt,
+        lastHeartbeat: new Date().toISOString(),
+        decision: rungId ? `running rung ${rungId}` : `running stage ${stage}`,
+      },
+      { lang }
+    );
+    await sleep(pollIntervalMs);
+  }
+
+  if ((exitCode ?? 1) !== 0) {
+    throw new Error(`auto stage failed: ${stage}${stderr ? ` | ${stderr.trim()}` : stdout ? ` | ${stdout.trim()}` : ""}`);
+  }
+
+  return {
+    stdout: stdout.trim(),
+    stderr: stderr.trim(),
+  };
+}
+
+function runCheckCommand({ targetDir, label, command, deadlineMs }) {
+  const remainingMs = Math.max(1000, deadlineMs - Date.now());
+  const result = spawn(command, {
+    cwd: targetDir,
+    shell: true,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+
+  return new Promise((resolve, reject) => {
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    const timeout = setTimeout(() => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      result.kill("SIGTERM");
+      reject(new Error(`${label} timed out`));
+    }, remainingMs);
+
+    result.stdout.on("data", (chunk) => {
+      if (stdout.length < 4000) {
+        stdout += chunk.toString("utf8");
+      }
+    });
+    result.stderr.on("data", (chunk) => {
+      if (stderr.length < 4000) {
+        stderr += chunk.toString("utf8");
+      }
+    });
+    result.on("error", (error) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timeout);
+      reject(error);
+    });
+    result.on("exit", (code, signal) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timeout);
+      if (signal) {
+        reject(new Error(`${label} exited with signal ${signal}`));
+        return;
+      }
+      if (code === 0) {
+        resolve({ matched: true, stdout: stdout.trim(), stderr: stderr.trim() });
+        return;
+      }
+      if (code === 1) {
+        resolve({ matched: false, stdout: stdout.trim(), stderr: stderr.trim() });
+        return;
+      }
+      reject(
+        new Error(
+          `${label} failed with exit code ${code}${
+            stderr ? ` | ${stderr.trim()}` : stdout ? ` | ${stdout.trim()}` : ""
+          }`
+        )
+      );
+    });
+  });
+}
+
+async function evaluateTerminalGoal({ mode, iteration, targetDir, deadlineMs }) {
+  if (mode.terminalGoalType === "rounds") {
+    const roundsTarget = parseInteger(mode.terminalGoalTarget, 1);
+    return {
+      matched: iteration >= roundsTarget,
+      reason: `round target ${roundsTarget} reached`,
+    };
+  }
+
+  if (mode.terminalGoalType === "task-completion") {
+    return {
+      matched: iteration >= 1,
+      reason: "task-completion terminal goal reached",
+    };
+  }
+
+  const successCheck = await runCheckCommand({
+    targetDir,
+    label: `success check after iteration ${iteration}`,
+    command: mode.successCheckCommand,
+    deadlineMs,
+  });
+  return {
+    matched: successCheck.matched,
+    reason: successCheck.stdout || successCheck.stderr || `metric threshold matched after iteration ${iteration}`,
+  };
+}
+
+async function startAutoMode({ targetDir, now = new Date() }) {
+  const mode = parseAutoMode(targetDir);
+  const evalProtocol = parseEvalProtocol(targetDir);
+  const issues = validateAutoMode(mode, null, evalProtocol);
+  if (issues.length > 0) {
+    throw new Error(issues.join(" | "));
+  }
+  const evalProtocolIssues = validateEvalProtocol(targetDir);
+  if (evalProtocolIssues.length > 0) {
+    throw new Error(evalProtocolIssues.join(" | "));
+  }
+  if (mode.approvalStatus !== "approved") {
+    throw new Error(`approval status must be approved before auto mode can start (current: ${mode.approvalStatus || "missing"})`);
+  }
+
+  const lang = readWorkflowLanguage(targetDir);
+  const timestamp = now.toISOString();
+  const status = {
+    status: "running",
+    currentStage: mode.allowedStages[0] || "run",
+    currentCommand: "",
+    activeRunId: "",
+    iterationCount: "0",
+    startedAt: timestamp,
+    lastHeartbeat: timestamp,
+    lastCheckpoint: "",
+    lastSummary: "",
+    decision: "armed for bounded auto orchestration",
+  };
+  writeAutoStatus(targetDir, status, { lang });
+
+  const startedAt = status.startedAt;
+  const pollIntervalMs = parseDurationMs(mode.pollInterval, 1000);
+  const maxWallClockMs = parseDurationMs(mode.maxWallClockTime, 60 * 60 * 1000);
+  const deadlineMs = Date.now() + maxWallClockMs;
+  const maxFailures = parseInteger(mode.maxFailures, 0);
+  const maxIterations = parseInteger(mode.maxIterations, 1);
+  const requiredArtifact = resolveRequiredArtifact(targetDir, mode.requiredTerminalArtifact);
+  const frozenCoreSnapshot = snapshotFrozenCore(targetDir, mode.frozenCore);
+  const { loopStages, finalStages } = splitAutoStages(mode.allowedStages);
+  const executedStages = [];
+  let failureCount = 0;
+  let iterationsCompleted = 0;
+  let currentStatus = { ...status };
+  let successReached = false;
+  let stopMatched = false;
+  let promotionApplied = false;
+  let stopReason = "";
+  let finalRung = "";
+
+  const writeRunningStatus = (overrides = {}) => {
+    currentStatus = {
+      ...currentStatus,
+      status: "running",
+      lastHeartbeat: new Date().toISOString(),
+      ...overrides,
+    };
+    writeAutoStatus(targetDir, currentStatus, { lang });
+  };
+
+  const failAutoMode = (message) => {
+    currentStatus = {
+      ...currentStatus,
+      status: "failed",
+      lastHeartbeat: new Date().toISOString(),
+      decision: message,
+    };
+    writeAutoStatus(targetDir, currentStatus, { lang });
+    writeAutoOutcome(
+      targetDir,
+      {
+        objective: mode.objective,
+        experimentLadder: evalProtocol.experimentLadder,
+        metricGlossary: evalProtocol.metricGlossary,
+        metricSourcePapers: evalProtocol.metricSourcePapers,
+        metricImplementationSource: evalProtocol.metricImplementationSource,
+        comparisonSourcePapers: evalProtocol.comparisonSourcePapers,
+        comparisonImplementationSource: evalProtocol.comparisonImplementationSource,
+        deviationFromOriginalImplementation: evalProtocol.deviationFromOriginalImplementation,
+        terminalGoalType: mode.terminalGoalType,
+        terminalGoalTarget: mode.terminalGoalTarget,
+        requiredTerminalArtifact: mode.requiredTerminalArtifact,
+        status: "failed",
+        goalReached: false,
+        stopReason: message,
+        promotionApplied,
+        finalArtifact: "",
+        finalRung,
+        executedStages: executedStages.join(", "),
+        iterationsCompleted: String(iterationsCompleted),
+        startedAt,
+        finishedAt: new Date().toISOString(),
+      },
+      { lang }
+    );
+    refreshContext({ targetDir });
+    throw new Error(message);
+  };
+
+  const runStage = async ({
+    stage,
+    commandOverride = "",
+    rungId = "",
+    watchTarget = "",
+    nextRung = "",
+  }) => {
+    const command = resolveStageCommand(mode, stage, commandOverride);
+    if (!isMeaningful(command)) {
+      throw new Error(`missing auto command for stage: ${stage}`);
+    }
+
+    let stageCompleted = false;
+    while (!stageCompleted) {
+      try {
+        const contract = stageContractSnapshot(targetDir, stage);
+        await runCommandWithPolling({
+          targetDir,
+          stage,
+          command,
+          pollIntervalMs,
+          deadlineMs,
+          startedAt,
+          status: currentStatus,
+          lang,
+          rungId,
+          watchTarget,
+          nextRung,
+        });
+        verifyStageContract({ stage, snapshot: contract.snapshot });
+        executedStages.push(stage);
+        finalRung = rungId || finalRung;
+        writeRunningStatus({
+          currentStage: stage,
+          currentCommand: command,
+          currentRung: rungId || currentStatus.currentRung,
+          watchTarget,
+          nextRung,
+          decision: rungId ? `completed rung ${rungId}` : `completed stage ${stage}`,
+        });
+        refreshContext({ targetDir });
+
+        const frozenCoreChanges = detectFrozenCoreChanges(frozenCoreSnapshot);
+        if (frozenCoreChanges.length > 0) {
+          failAutoMode(`frozen core changed: ${frozenCoreChanges.join(", ")}`);
+        }
+
+        const stopCheck = await runCheckCommand({
+          targetDir,
+          label: `stop check after ${rungId || stage}`,
+          command: mode.stopCheckCommand,
+          deadlineMs,
+        });
+        if (stopCheck.matched) {
+          stopMatched = true;
+          stopReason =
+            stopCheck.stdout || stopCheck.stderr || `stop condition matched after ${rungId || stage}`;
+        }
+
+        stageCompleted = true;
+      } catch (error) {
+        failureCount += 1;
+        if (failureCount > maxFailures) {
+          failAutoMode(error.message);
+        }
+        writeRunningStatus({
+          currentStage: stage,
+          currentCommand: command,
+          currentRung: rungId || currentStatus.currentRung,
+          watchTarget,
+          nextRung,
+          decision: `retrying ${rungId || stage} after failure ${failureCount}`,
+        });
+      }
+    }
+  };
+
+  const maybeApplyPromotion = async (label) => {
+    if (promotionApplied || !isMeaningful(mode.promotionCheckCommand)) {
+      return;
+    }
+    const promotionCheck = await runCheckCommand({
+      targetDir,
+      label: `promotion check after ${label}`,
+      command: mode.promotionCheckCommand,
+      deadlineMs,
+    });
+    if (!promotionCheck.matched) {
+      return;
+    }
+    const promotionSnapshot = snapshotPaths(targetDir, [
+      ".lab/context/data-decisions.md",
+      ".lab/context/decisions.md",
+      ".lab/context/state.md",
+      ".lab/context/session-brief.md",
+    ]);
+    await runCommandWithPolling({
+      targetDir,
+      stage: "promotion",
+      command: mode.promotionCommand,
+      pollIntervalMs,
+      deadlineMs,
+      startedAt,
+      status: currentStatus,
+      lang,
+      rungId: currentStatus.currentRung || "",
+      watchTarget: currentStatus.watchTarget || "",
+      nextRung: currentStatus.nextRung || "",
+    });
+    writeRunningStatus({
+      currentCommand: mode.promotionCommand,
+      decision: `promotion policy matched after ${label}`,
+    });
+    promotionApplied = true;
+    refreshContext({ targetDir });
+    verifyPromotionWriteback(targetDir, promotionSnapshot);
+    const frozenCoreChangesAfterPromotion = detectFrozenCoreChanges(frozenCoreSnapshot);
+    if (frozenCoreChangesAfterPromotion.length > 0) {
+      failAutoMode(`frozen core changed: ${frozenCoreChangesAfterPromotion.join(", ")}`);
+    }
+  };
+
+  if (evalProtocol.experimentRungs.length > 0) {
+    const rungMap = new Map(evalProtocol.experimentRungs.map((rung) => [rung.id, rung]));
+    let currentRung = evalProtocol.experimentRungs[0];
+
+    while (currentRung && iterationsCompleted < Math.max(1, maxIterations)) {
+      if (!mode.allowedStages.includes(currentRung.stage)) {
+        failAutoMode(`experiment ladder rung ${currentRung.id} uses stage outside allowed stages: ${currentRung.stage}`);
+      }
+      iterationsCompleted += 1;
+      const command = resolveStageCommand(mode, currentRung.stage, currentRung.command);
+      writeRunningStatus({
+        currentStage: currentRung.stage,
+        currentCommand: command,
+        iterationCount: String(iterationsCompleted),
+        currentRung: currentRung.id,
+        watchTarget: currentRung.watch,
+        nextRung: "",
+        decision: `starting rung ${currentRung.id}`,
+      });
+
+      await runStage({
+        stage: currentRung.stage,
+        commandOverride: currentRung.command,
+        rungId: currentRung.id,
+        watchTarget: currentRung.watch,
+      });
+
+      if (stopMatched) {
+        const stopTransition = normalizeTransition(currentRung.onStop);
+        if (isMeaningful(stopTransition) && !isStopTransition(stopTransition)) {
+          if (!rungMap.has(stopTransition)) {
+            failAutoMode(`experiment ladder references unknown stop rung: ${stopTransition}`);
+          }
+          currentRung = rungMap.get(stopTransition);
+          stopMatched = false;
+          stopReason = "";
+          continue;
+        }
+        stopReason = stopReason || `stop condition matched during rung ${currentRung.id}`;
+        break;
+      }
+
+      const gateResult = await runCheckCommand({
+        targetDir,
+        label: `gate for rung ${currentRung.id}`,
+        command: currentRung.gate,
+        deadlineMs,
+      });
+      const transition = normalizeTransition(gateResult.matched ? currentRung.onPass : currentRung.onFail);
+      if (!isMeaningful(transition)) {
+        failAutoMode(`experiment ladder rung ${currentRung.id} has no ${gateResult.matched ? "pass" : "fail"} transition`);
+      }
+
+      writeRunningStatus({
+        currentStage: currentRung.stage,
+        currentCommand: command,
+        currentRung: currentRung.id,
+        watchTarget: currentRung.watch,
+        nextRung: transition,
+        decision: gateResult.matched
+          ? `rung ${currentRung.id} passed gate`
+          : `rung ${currentRung.id} failed gate`,
+      });
+
+      await maybeApplyPromotion(`rung ${currentRung.id}`);
+
+      if (isSuccessTransition(transition)) {
+        if (mode.terminalGoalType === "task-completion") {
+          successReached = true;
+          stopReason = `success terminal rung reached: ${currentRung.id}`;
+          break;
+        }
+        const goalEvaluation = await evaluateTerminalGoal({
+          mode,
+          iteration: iterationsCompleted,
+          targetDir,
+          deadlineMs,
+        });
+        if (!goalEvaluation.matched) {
+          failAutoMode(
+            `experiment ladder reached success terminal at ${currentRung.id} before terminal goal matched`
+          );
+        }
+        successReached = true;
+        stopReason = goalEvaluation.reason || `success terminal rung reached: ${currentRung.id}`;
+        break;
+      }
+
+      if (isStopTransition(transition)) {
+        stopMatched = true;
+        stopReason = `stop terminal rung reached: ${currentRung.id}`;
+        break;
+      }
+
+      if (!rungMap.has(transition)) {
+        failAutoMode(`experiment ladder references unknown next rung: ${transition}`);
+      }
+      currentRung = rungMap.get(transition);
+    }
+
+    if (!successReached && !stopMatched && iterationsCompleted >= Math.max(1, maxIterations)) {
+      failAutoMode(`max iterations exhausted before completing experiment ladder: ${maxIterations}`);
+    }
+  } else {
+    const stagesPerIteration = loopStages.length > 0 ? loopStages : mode.allowedStages;
+
+    for (let iteration = 1; iteration <= Math.max(1, maxIterations); iteration += 1) {
+      writeRunningStatus({
+        currentStage: stagesPerIteration[0] || currentStatus.currentStage,
+        currentCommand: mode.stageCommands[stagesPerIteration[0]] || "",
+        iterationCount: String(iteration),
+        decision: `starting iteration ${iteration}`,
+      });
+
+      for (const stage of stagesPerIteration) {
+        await runStage({ stage });
+        if (stopMatched || successReached) {
+          break;
+        }
+      }
+
+      iterationsCompleted = iteration;
+
+      if (stopMatched || successReached) {
+        break;
+      }
+
+      await maybeApplyPromotion(`iteration ${iteration}`);
+
+      const goalEvaluation = await evaluateTerminalGoal({
+        mode,
+        iteration,
+        targetDir,
+        deadlineMs,
+      });
+      if (goalEvaluation.matched) {
+        successReached = true;
+        stopReason = goalEvaluation.reason || "completed configured auto goal";
+        break;
+      }
+    }
+
+    if (!successReached && loopStages.length > 0 && iterationsCompleted >= Math.max(1, maxIterations)) {
+      failAutoMode(`max iterations exhausted without meeting success criteria: ${maxIterations}`);
+    }
+  }
+
+  if (stopMatched) {
+    currentStatus = {
+      ...currentStatus,
+      status: "stopped",
+      currentStage: executedStages.at(-1) || currentStatus.currentStage,
+      currentCommand: currentStatus.currentCommand,
+      lastHeartbeat: new Date().toISOString(),
+      decision: stopReason || "stopped by stop condition",
+    };
+    writeAutoStatus(targetDir, currentStatus, { lang });
+    writeAutoOutcome(
+      targetDir,
+      {
+        objective: mode.objective,
+        experimentLadder: evalProtocol.experimentLadder,
+        metricGlossary: evalProtocol.metricGlossary,
+        terminalGoalType: mode.terminalGoalType,
+        terminalGoalTarget: mode.terminalGoalTarget,
+        requiredTerminalArtifact: mode.requiredTerminalArtifact,
+        status: "stopped",
+        goalReached: false,
+        stopReason: stopReason || "stopped by stop condition",
+        promotionApplied,
+        finalArtifact: requiredArtifact.relativePath,
+        finalRung,
+        executedStages: executedStages.join(", "),
+        iterationsCompleted: String(iterationsCompleted),
+        startedAt,
+        finishedAt: new Date().toISOString(),
+      },
+      { lang }
+    );
+    refreshContext({ targetDir });
+    return {
+      mode,
+      status: currentStatus,
+      executedStages,
+      outcome: {
+        experimentLadder: evalProtocol.experimentLadder,
+        metricGlossary: evalProtocol.metricGlossary,
+        metricSourcePapers: evalProtocol.metricSourcePapers,
+        metricImplementationSource: evalProtocol.metricImplementationSource,
+        comparisonSourcePapers: evalProtocol.comparisonSourcePapers,
+        comparisonImplementationSource: evalProtocol.comparisonImplementationSource,
+        deviationFromOriginalImplementation: evalProtocol.deviationFromOriginalImplementation,
+        goalType: mode.terminalGoalType,
+        goalTarget: mode.terminalGoalTarget,
+        goalReached: false,
+        stopReason: stopReason || "stopped by stop condition",
+        promotionApplied,
+        finalArtifact: requiredArtifact.relativePath,
+        finalRung,
+      },
+    };
+  }
+
+  if (evalProtocol.experimentRungs.length === 0) {
+    for (const stage of finalStages) {
+      await runStage({ stage });
+      if (stopMatched) {
+        currentStatus = {
+          ...currentStatus,
+          status: "stopped",
+          currentStage: executedStages.at(-1) || currentStatus.currentStage,
+          currentCommand: currentStatus.currentCommand,
+          lastHeartbeat: new Date().toISOString(),
+          decision: stopReason || "stopped by stop condition",
+        };
+        writeAutoStatus(targetDir, currentStatus, { lang });
+        writeAutoOutcome(
+          targetDir,
+          {
+            objective: mode.objective,
+            experimentLadder: evalProtocol.experimentLadder,
+            metricGlossary: evalProtocol.metricGlossary,
+            metricSourcePapers: evalProtocol.metricSourcePapers,
+            metricImplementationSource: evalProtocol.metricImplementationSource,
+            comparisonSourcePapers: evalProtocol.comparisonSourcePapers,
+            comparisonImplementationSource: evalProtocol.comparisonImplementationSource,
+            deviationFromOriginalImplementation: evalProtocol.deviationFromOriginalImplementation,
+            terminalGoalType: mode.terminalGoalType,
+            terminalGoalTarget: mode.terminalGoalTarget,
+            requiredTerminalArtifact: mode.requiredTerminalArtifact,
+            status: "stopped",
+            goalReached: false,
+            stopReason: stopReason || "stopped by stop condition",
+            promotionApplied,
+            finalArtifact: requiredArtifact.relativePath,
+            finalRung,
+            executedStages: executedStages.join(", "),
+            iterationsCompleted: String(iterationsCompleted),
+            startedAt,
+            finishedAt: new Date().toISOString(),
+          },
+          { lang }
+        );
+        refreshContext({ targetDir });
+        return {
+          mode,
+          status: currentStatus,
+          executedStages,
+          outcome: {
+            experimentLadder: evalProtocol.experimentLadder,
+            metricGlossary: evalProtocol.metricGlossary,
+            metricSourcePapers: evalProtocol.metricSourcePapers,
+            metricImplementationSource: evalProtocol.metricImplementationSource,
+            comparisonSourcePapers: evalProtocol.comparisonSourcePapers,
+            comparisonImplementationSource: evalProtocol.comparisonImplementationSource,
+            deviationFromOriginalImplementation: evalProtocol.deviationFromOriginalImplementation,
+            goalType: mode.terminalGoalType,
+            goalTarget: mode.terminalGoalTarget,
+            goalReached: false,
+            stopReason: stopReason || "stopped by stop condition",
+            promotionApplied,
+            finalArtifact: requiredArtifact.relativePath,
+            finalRung,
+          },
+        };
+      }
+    }
+  }
+
+  if (!fs.existsSync(requiredArtifact.absolutePath)) {
+    failAutoMode(`required terminal artifact missing: ${mode.requiredTerminalArtifact}`);
+  }
+
+  currentStatus = {
+    ...currentStatus,
+    status: "completed",
+    currentStage: executedStages.at(-1) || currentStatus.currentStage,
+    currentCommand: currentStatus.currentCommand,
+    lastHeartbeat: new Date().toISOString(),
+    decision: successReached ? "completed configured auto goal" : "completed configured stages",
+  };
+  writeAutoStatus(targetDir, currentStatus, { lang });
+  writeAutoOutcome(
+    targetDir,
+    {
+      objective: mode.objective,
+      experimentLadder: evalProtocol.experimentLadder,
+      metricGlossary: evalProtocol.metricGlossary,
+      metricSourcePapers: evalProtocol.metricSourcePapers,
+      metricImplementationSource: evalProtocol.metricImplementationSource,
+      comparisonSourcePapers: evalProtocol.comparisonSourcePapers,
+      comparisonImplementationSource: evalProtocol.comparisonImplementationSource,
+      deviationFromOriginalImplementation: evalProtocol.deviationFromOriginalImplementation,
+      terminalGoalType: mode.terminalGoalType,
+      terminalGoalTarget: mode.terminalGoalTarget,
+      requiredTerminalArtifact: mode.requiredTerminalArtifact,
+      status: "completed",
+      goalReached: successReached,
+      stopReason: stopReason || "completed configured auto goal",
+      promotionApplied,
+      finalArtifact: requiredArtifact.relativePath,
+      finalRung,
+      executedStages: executedStages.join(", "),
+      iterationsCompleted: String(iterationsCompleted),
+      startedAt,
+      finishedAt: new Date().toISOString(),
+    },
+    { lang }
+  );
+  refreshContext({ targetDir });
+  return {
+    mode,
+    status: currentStatus,
+    executedStages,
+    outcome: {
+      experimentLadder: evalProtocol.experimentLadder,
+      metricGlossary: evalProtocol.metricGlossary,
+      metricSourcePapers: evalProtocol.metricSourcePapers,
+      metricImplementationSource: evalProtocol.metricImplementationSource,
+      comparisonSourcePapers: evalProtocol.comparisonSourcePapers,
+      comparisonImplementationSource: evalProtocol.comparisonImplementationSource,
+      deviationFromOriginalImplementation: evalProtocol.deviationFromOriginalImplementation,
+      goalType: mode.terminalGoalType,
+      goalTarget: mode.terminalGoalTarget,
+      goalReached: successReached,
+      stopReason: stopReason || "completed configured auto goal",
+      promotionApplied,
+      finalArtifact: requiredArtifact.relativePath,
+      finalRung,
+    },
+  };
+}
+
+function stopAutoMode({ targetDir, now = new Date() }) {
+  const existing = parseAutoStatus(targetDir);
+  const mode = parseAutoMode(targetDir);
+  const evalProtocol = parseEvalProtocol(targetDir);
+  const lang = readWorkflowLanguage(targetDir);
+  const status = {
+    ...existing,
+    status: "stopped",
+    lastHeartbeat: now.toISOString(),
+    decision: "stopped by operator",
+  };
+  writeAutoStatus(targetDir, status, { lang });
+  writeAutoOutcome(
+    targetDir,
+    {
+      objective: mode.objective,
+      experimentLadder: evalProtocol.experimentLadder,
+      metricGlossary: evalProtocol.metricGlossary,
+      metricSourcePapers: evalProtocol.metricSourcePapers,
+      metricImplementationSource: evalProtocol.metricImplementationSource,
+      comparisonSourcePapers: evalProtocol.comparisonSourcePapers,
+      comparisonImplementationSource: evalProtocol.comparisonImplementationSource,
+      deviationFromOriginalImplementation: evalProtocol.deviationFromOriginalImplementation,
+      terminalGoalType: mode.terminalGoalType,
+      terminalGoalTarget: mode.terminalGoalTarget,
+      requiredTerminalArtifact: mode.requiredTerminalArtifact,
+      status: "stopped",
+      goalReached: false,
+      stopReason: "stopped by operator",
+      promotionApplied: false,
+      finalArtifact: mode.requiredTerminalArtifact || "",
+      finalRung: existing.currentRung || "",
+      executedStages: "",
+      iterationsCompleted: existing.iterationCount || "0",
+      startedAt: existing.startedAt || now.toISOString(),
+      finishedAt: now.toISOString(),
+    },
+    { lang }
+  );
+  refreshContext({ targetDir });
+  return status;
+}
+
+function getAutoStatus({ targetDir }) {
+  const mode = parseAutoMode(targetDir);
+  const status = parseAutoStatus(targetDir);
+  const evalProtocol = parseEvalProtocol(targetDir);
+  return {
+    mode,
+    status,
+    issues: validateAutoMode(mode, status, evalProtocol).concat(validateAutoStatus(status, mode)),
+  };
+}
+
+module.exports = {
+  getAutoStatus,
+  startAutoMode,
+  stopAutoMode,
+};