superlab 0.1.12 → 0.1.13

package/lib/auto.cjs

@@ -1,975 +1,17 @@
-const fs = require("node:fs");
-const path = require("node:path");
-const crypto = require("node:crypto");
-const { spawn } = require("node:child_process");
-const { refreshContext } = require("./context.cjs");
-
-const ALLOWED_AUTO_STAGES = new Set(["run", "iterate", "review", "report", "write"]);
-const LOOP_AUTO_STAGES = new Set(["run", "iterate", "review"]);
-const FINAL_AUTO_STAGES = new Set(["report", "write"]);
-const PLACEHOLDER_VALUES = new Set(["", "tbd", "none", "待补充", "无"]);
-const FROZEN_CORE_ALIASES = {
-  mission: [path.join(".lab", "context", "mission.md")],
-  framing: [
-    path.join(".lab", "context", "terminology-lock.md"),
-    path.join(".lab", "writing", "framing.md"),
-  ],
-  claims: [path.join(".lab", "context", "terminology-lock.md")],
-  "terminology-lock": [path.join(".lab", "context", "terminology-lock.md")],
-};
-const REVIEW_CONTEXT_FILES = [
-  path.join(".lab", "context", "decisions.md"),
-  path.join(".lab", "context", "state.md"),
-  path.join(".lab", "context", "open-questions.md"),
-  path.join(".lab", "context", "evidence-index.md"),
-];
-const PROMOTION_CANONICAL_FILES = [
-  path.join(".lab", "context", "data-decisions.md"),
-  path.join(".lab", "context", "decisions.md"),
-  path.join(".lab", "context", "state.md"),
-  path.join(".lab", "context", "session-brief.md"),
-];
-
-function contextFile(targetDir, name) {
-  return path.join(targetDir, ".lab", "context", name);
-}
-
-function readFileIfExists(filePath) {
-  if (!fs.existsSync(filePath)) {
-    return "";
-  }
-  return fs.readFileSync(filePath, "utf8");
-}
-
-function extractValue(text, labels) {
-  for (const label of labels) {
-    const escaped = label.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    const regex = new RegExp(`^\\s*-\\s*${escaped}:[ \\t]*([^\\n\\r]+?)[ \\t]*$`, "im");
-    const match = text.match(regex);
-    if (match && match[1]) {
-      return match[1].trim();
-    }
-  }
-  return "";
-}
-
-function isMeaningful(value) {
-  return !PLACEHOLDER_VALUES.has((value || "").trim().toLowerCase());
-}
-
-function normalizeAllowedStages(rawValue) {
-  return (rawValue || "")
-    .split(",")
-    .map((value) => value.trim().toLowerCase())
-    .filter(Boolean);
-}
-
-function parseAutoMode(targetDir) {
-  const text = readFileIfExists(contextFile(targetDir, "auto-mode.md"));
-  const allowedStages = normalizeAllowedStages(extractValue(text, ["Allowed stages", "允许阶段"]));
-  return {
-    path: contextFile(targetDir, "auto-mode.md"),
-    text,
-    objective: extractValue(text, ["Objective", "目标"]),
-    allowedStages,
-    successCriteria: extractValue(text, ["Success criteria", "成功标准"]),
-    maxIterations: extractValue(text, ["Max iterations", "最大迭代轮次"]),
-    maxWallClockTime: extractValue(text, ["Max wall-clock time", "最大运行时长"]),
-    maxFailures: extractValue(text, ["Max failures", "最大失败次数"]),
-    pollInterval: extractValue(text, ["Poll interval", "轮询间隔"]),
-    stageCommands: {
-      run: extractValue(text, ["Run command", "运行命令"]),
-      iterate: extractValue(text, ["Iterate command", "迭代命令"]),
-      review: extractValue(text, ["Review command", "审查命令"]),
-      report: extractValue(text, ["Report command", "报告命令"]),
-      write: extractValue(text, ["Write command", "写作命令"]),
-    },
-    successCheckCommand: extractValue(text, ["Success check command", "成功检查命令"]),
-    stopCheckCommand: extractValue(text, ["Stop check command", "停止检查命令"]),
-    promotionCheckCommand: extractValue(text, ["Promotion check command", "升格检查命令"]),
-    promotionCommand: extractValue(text, ["Promotion command", "升格命令"]),
-    promotionPolicy: extractValue(text, ["Promotion policy", "升格策略"]),
-    frozenCore: extractValue(text, ["Frozen core", "冻结核心"]),
-    explorationEnvelope: extractValue(text, ["Exploration envelope", "探索边界"]),
-    stopConditions: extractValue(text, ["Stop conditions", "停止条件"]),
-    escalationConditions: extractValue(text, ["Escalation conditions", "升级条件"]),
-  };
-}
-
-function parseInteger(value, fallback = null) {
-  const normalized = (value || "").trim();
-  if (!normalized) {
-    return fallback;
-  }
-  const parsed = Number.parseInt(normalized, 10);
-  return Number.isFinite(parsed) ? parsed : fallback;
-}
-
-function parseDurationMs(value, fallbackMs) {
-  const normalized = (value || "").trim().toLowerCase();
-  if (!normalized) {
-    return fallbackMs;
-  }
-  const match = normalized.match(/^(\d+(?:\.\d+)?)(ms|s|m|h)?$/);
-  if (!match) {
-    return fallbackMs;
-  }
-  const amount = Number.parseFloat(match[1]);
-  const unit = match[2] || "s";
-  const multipliers = {
-    ms: 1,
-    s: 1000,
-    m: 60_000,
-    h: 3_600_000,
-  };
-  return Math.max(1, Math.round(amount * multipliers[unit]));
-}
-
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-function normalizeList(rawValue) {
-  return (rawValue || "")
-    .split(",")
-    .map((value) => value.trim())
-    .filter(Boolean);
-}
-
-function resolveFrozenCoreEntries(rawValue) {
-  const normalized = normalizeList(rawValue);
-  const paths = new Set();
-  const invalidEntries = [];
-
-  for (const entry of normalized) {
-    const key = entry.trim().toLowerCase();
-    if (FROZEN_CORE_ALIASES[key]) {
-      for (const aliasedPath of FROZEN_CORE_ALIASES[key]) {
-        paths.add(aliasedPath);
-      }
-      continue;
-    }
-
-    if (entry.includes("/") || entry.includes(path.sep) || entry.endsWith(".md")) {
-      paths.add(entry);
-      continue;
-    }
-
-    invalidEntries.push(entry);
-  }
-
-  return {
-    entries: normalized,
-    relativePaths: Array.from(paths),
-    invalidEntries,
-  };
-}
-
-function hashPathState(filePath) {
-  if (!fs.existsSync(filePath)) {
-    return "__missing__";
-  }
-
-  const stat = fs.statSync(filePath);
-  if (stat.isDirectory()) {
-    const entries = fs
-      .readdirSync(filePath)
-      .sort((left, right) => left.localeCompare(right))
-      .map((entry) => {
-        const childPath = path.join(filePath, entry);
-        return `${entry}:${hashPathState(childPath)}`;
-      })
-      .join("|");
-    return crypto.createHash("sha256").update(entries).digest("hex");
-  }
-
-  return crypto.createHash("sha256").update(fs.readFileSync(filePath)).digest("hex");
-}
-
-function snapshotFrozenCore(targetDir, rawValue) {
-  const { relativePaths } = resolveFrozenCoreEntries(rawValue);
-  const snapshot = new Map();
-
-  for (const relativePath of relativePaths) {
-    const absolutePath = path.resolve(targetDir, relativePath);
-    snapshot.set(absolutePath, hashPathState(absolutePath));
-  }
-
-  return snapshot;
-}
-
-function detectFrozenCoreChanges(snapshot) {
-  const changedPaths = [];
-  for (const [absolutePath, initialHash] of snapshot.entries()) {
-    const currentHash = hashPathState(absolutePath);
-    if (currentHash !== initialHash) {
-      changedPaths.push(absolutePath);
-    }
-  }
-  return changedPaths;
-}
-
-function parseAutoStatus(targetDir) {
-  const text = readFileIfExists(contextFile(targetDir, "auto-status.md"));
-  return {
-    path: contextFile(targetDir, "auto-status.md"),
-    text,
-    status: extractValue(text, ["Status", "状态"]),
-    currentStage: extractValue(text, ["Current stage", "当前阶段"]),
-    currentCommand: extractValue(text, ["Current command", "当前命令"]),
-    activeRunId: extractValue(text, ["Active run id", "当前活跃 run id"]),
-    iterationCount: extractValue(text, ["Iteration count", "迭代计数"]),
-    startedAt: extractValue(text, ["Started at", "开始时间"]),
-    lastHeartbeat: extractValue(text, ["Last heartbeat", "最近心跳"]),
-    lastCheckpoint: extractValue(text, ["Last checkpoint", "最近 checkpoint"]),
-    lastSummary: extractValue(text, ["Last summary", "最近 summary"]),
-    decision: extractValue(text, ["Current decision", "当前决策"]),
-  };
-}
-
-function validateAutoMode(mode, status = null) {
-  const issues = [];
-  const activated =
-    isMeaningful(mode.objective) ||
-    (status && ["running", "stopped", "failed", "completed"].includes((status.status || "").toLowerCase()));
-
-  if (!activated) {
-    return issues;
-  }
-
-  const requiredFields = [
-    ["objective", mode.objective],
-    ["allowed stages", mode.allowedStages.join(", ")],
-    ["success criteria", mode.successCriteria],
-    ["max iterations", mode.maxIterations],
-    ["max wall-clock time", mode.maxWallClockTime],
-    ["max failures", mode.maxFailures],
-    ["poll interval", mode.pollInterval],
-    ["success check command", mode.successCheckCommand],
-    ["stop check command", mode.stopCheckCommand],
-    ["promotion policy", mode.promotionPolicy],
-    ["promotion check command", mode.promotionCheckCommand],
-    ["promotion command", mode.promotionCommand],
-    ["frozen core", mode.frozenCore],
-    ["exploration envelope", mode.explorationEnvelope],
-    ["stop conditions", mode.stopConditions],
-  ];
-
-  const missing = requiredFields
-    .filter(([, value]) => !isMeaningful(value))
-    .map(([name]) => name);
-  if (missing.length > 0) {
-    issues.push(`missing auto mode fields: ${missing.join(", ")}`);
-  }
-
-  const invalidStages = mode.allowedStages.filter((stage) => !ALLOWED_AUTO_STAGES.has(stage));
-  if (invalidStages.length > 0) {
-    issues.push(`unsupported auto stages: ${invalidStages.join(", ")}`);
-  }
-
-  const missingCommands = mode.allowedStages.filter((stage) => !isMeaningful(mode.stageCommands?.[stage]));
-  if (missingCommands.length > 0) {
-    issues.push(`missing auto commands for stages: ${missingCommands.join(", ")}`);
-  }
-
-  const invalidFrozenCoreEntries = resolveFrozenCoreEntries(mode.frozenCore).invalidEntries;
-  if (invalidFrozenCoreEntries.length > 0) {
-    issues.push(`unsupported frozen core entries: ${invalidFrozenCoreEntries.join(", ")}`);
-  }
-
-  return issues;
-}
-
-function validateAutoStatus(status, mode = null) {
-  const issues = [];
-  const normalizedStatus = (status.status || "").trim().toLowerCase();
-  if (!normalizedStatus || normalizedStatus === "idle") {
-    return issues;
-  }
-
-  if (!["running", "stopped", "failed", "completed"].includes(normalizedStatus)) {
-    issues.push(`invalid auto status: ${status.status}`);
-    return issues;
-  }
-
-  if (normalizedStatus === "running") {
-    if (!isMeaningful(status.currentStage)) {
-      issues.push("auto status is missing current stage");
-    }
-    if (!isMeaningful(status.startedAt)) {
-      issues.push("auto status is missing started at");
-    }
-    if (!isMeaningful(status.lastHeartbeat)) {
-      issues.push("auto status is missing last heartbeat");
-    }
-  }
-
-  if (mode && mode.allowedStages.length > 0 && isMeaningful(status.currentStage)) {
-    const currentStage = status.currentStage.trim().toLowerCase();
-    if (!mode.allowedStages.includes(currentStage)) {
-      issues.push(`auto status stage is outside allowed stages: ${status.currentStage}`);
-    }
-  }
-
-  return issues;
-}
-
-function renderAutoStatus(status, { lang = "en" } = {}) {
-  if (lang === "zh") {
-    return `# 自动模式状态
-
-## 运行状态
-
-- 状态: ${status.status || "idle"}
-- 当前阶段: ${status.currentStage || ""}
-- 当前命令: ${status.currentCommand || ""}
-- 当前活跃 run id: ${status.activeRunId || ""}
-- 迭代计数: ${status.iterationCount || "0"}
-
-## 时间
-
-- 开始时间: ${status.startedAt || ""}
-- 最近心跳: ${status.lastHeartbeat || ""}
-
-## 工件
-
-- 最近 checkpoint: ${status.lastCheckpoint || ""}
-- 最近 summary: ${status.lastSummary || ""}
-
-## 决策
-
-- 当前决策: ${status.decision || ""}
-`;
-  }
-
-  return `# Auto Mode Status
-
-## Runtime State
-
-- Status: ${status.status || "idle"}
-- Current stage: ${status.currentStage || ""}
-- Current command: ${status.currentCommand || ""}
-- Active run id: ${status.activeRunId || ""}
-- Iteration count: ${status.iterationCount || "0"}
-
-## Timing
-
-- Started at: ${status.startedAt || ""}
-- Last heartbeat: ${status.lastHeartbeat || ""}
-
-## Artifacts
-
-- Last checkpoint: ${status.lastCheckpoint || ""}
-- Last summary: ${status.lastSummary || ""}
-
-## Decision
-
-- Current decision: ${status.decision || ""}
-`;
-}
-
-function writeAutoStatus(targetDir, status, { lang = "en" } = {}) {
-  const filePath = contextFile(targetDir, "auto-status.md");
-  fs.mkdirSync(path.dirname(filePath), { recursive: true });
-  fs.writeFileSync(filePath, renderAutoStatus(status, { lang }).trimEnd() + "\n");
-}
-
-function readWorkflowLanguage(targetDir) {
-  const configPath = path.join(targetDir, ".lab", "config", "workflow.json");
-  if (!fs.existsSync(configPath)) {
-    return "en";
-  }
-  try {
-    const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
-    return config.workflow_language === "zh" ? "zh" : "en";
-  } catch {
-    return "en";
-  }
-}
-
-function readWorkflowConfig(targetDir) {
-  const configPath = path.join(targetDir, ".lab", "config", "workflow.json");
-  try {
-    return JSON.parse(fs.readFileSync(configPath, "utf8"));
-  } catch {
-    return {};
-  }
-}
-
-function resolveProjectPath(targetDir, configuredPath, fallbackRelativePath) {
-  if (typeof configuredPath !== "string" || configuredPath.trim() === "") {
-    return path.join(targetDir, fallbackRelativePath);
-  }
-  return path.isAbsolute(configuredPath)
-    ? configuredPath
-    : path.resolve(targetDir, configuredPath);
-}
-
-function snapshotPaths(targetDir, relativePaths) {
-  const snapshot = new Map();
-  for (const relativePath of relativePaths) {
-    const absolutePath = path.resolve(targetDir, relativePath);
-    snapshot.set(absolutePath, hashPathState(absolutePath));
-  }
-  return snapshot;
-}
-
-function changedSnapshotPaths(snapshot) {
-  const changed = [];
-  for (const [absolutePath, previousHash] of snapshot.entries()) {
-    if (hashPathState(absolutePath) !== previousHash) {
-      changed.push(absolutePath);
-    }
-  }
-  return changed;
-}
-
-function stageContractSnapshot(targetDir, stage) {
-  const workflowConfig = readWorkflowConfig(targetDir);
-  const resultsRoot = resolveProjectPath(targetDir, workflowConfig.results_root, "results");
-  const deliverablesRoot = resolveProjectPath(targetDir, workflowConfig.deliverables_root, path.join("docs", "research"));
-  const trackedPathsByStage = {
-    run: [resultsRoot],
-    iterate: [resultsRoot],
-    review: REVIEW_CONTEXT_FILES.map((relativePath) => path.resolve(targetDir, relativePath)),
-    report: [path.join(deliverablesRoot, "report.md")],
-    write: [
-      path.join(deliverablesRoot, "paper", "main.tex"),
-      path.join(deliverablesRoot, "paper", "sections"),
-    ],
-  };
-
-  const absolutePaths = trackedPathsByStage[stage] || [];
-  const snapshot = new Map();
-  for (const absolutePath of absolutePaths) {
-    snapshot.set(absolutePath, hashPathState(absolutePath));
-  }
-  return {
-    stage,
-    absolutePaths,
-    snapshot,
-  };
-}
-
-function verifyStageContract({ stage, snapshot }) {
-  const changedPaths = [];
-  for (const [absolutePath, previousHash] of snapshot.entries()) {
-    if (hashPathState(absolutePath) !== previousHash) {
-      changedPaths.push(absolutePath);
-    }
-  }
-
-  if (stage === "review") {
-    if (changedPaths.length === 0) {
-      throw new Error(
-        "review stage did not update canonical review context (.lab/context/decisions.md, state.md, open-questions.md, or evidence-index.md)"
-      );
-    }
-    return;
-  }
-
-  if (stage === "report") {
-    if (changedPaths.length === 0) {
-      throw new Error("report stage did not produce the deliverable report.md under deliverables_root");
-    }
-    return;
-  }
-
-  if (stage === "write") {
-    if (changedPaths.length === 0) {
-      throw new Error("write stage did not produce LaTeX output under deliverables_root/paper");
-    }
-    return;
-  }
-
-  if ((stage === "run" || stage === "iterate") && changedPaths.length === 0) {
-    throw new Error(`${stage} stage did not produce persistent outputs under results_root`);
-  }
-}
-
-function verifyPromotionWriteback(targetDir, snapshot) {
-  const changedPaths = changedSnapshotPaths(snapshot);
-  if (changedPaths.length !== PROMOTION_CANONICAL_FILES.length) {
-    throw new Error(
-      `promotion did not update canonical context: ${PROMOTION_CANONICAL_FILES.filter(
-        (relativePath) => !changedPaths.includes(path.resolve(targetDir, relativePath))
-      ).join(", ")}`
-    );
-  }
-}
-
-async function runCommandWithPolling({ targetDir, stage, command, pollIntervalMs, deadlineMs, startedAt, status, lang }) {
-  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,
-        startedAt,
-        lastHeartbeat: new Date().toISOString(),
-        decision: `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()}` : ""
-          }`
-        )
-      );
-    });
-  });
-}
-
-function splitAutoStages(allowedStages) {
-  const loopStages = allowedStages.filter((stage) => LOOP_AUTO_STAGES.has(stage));
-  const finalStages = allowedStages.filter((stage) => FINAL_AUTO_STAGES.has(stage));
-  return { loopStages, finalStages };
-}
-
-async function startAutoMode({ targetDir, now = new Date() }) {
-  const mode = parseAutoMode(targetDir);
-  const issues = validateAutoMode(mode);
-  if (issues.length > 0) {
-    throw new Error(issues.join(" | "));
-  }
-
-  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 frozenCoreSnapshot = snapshotFrozenCore(targetDir, mode.frozenCore);
-  const { loopStages, finalStages } = splitAutoStages(mode.allowedStages);
-  const executedStages = [];
-  let failureCount = 0;
-  let currentStatus = { ...status };
-  let successReached = false;
-  let stopMatched = false;
-  let promotionApplied = false;
-  let stopReason = "";
-
-  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 });
-    throw new Error(message);
-  };
-
-  const stageExecutors = {
-    run: async () => {
-      const contract = stageContractSnapshot(targetDir, "run");
-      await runCommandWithPolling({
-        targetDir,
-        stage: "run",
-        command: mode.stageCommands.run,
-        pollIntervalMs,
-        deadlineMs,
-        startedAt,
-        status: currentStatus,
-        lang,
-      });
-      verifyStageContract({ stage: "run", snapshot: contract.snapshot });
-    },
-    iterate: async () => {
-      const contract = stageContractSnapshot(targetDir, "iterate");
-      await runCommandWithPolling({
-        targetDir,
-        stage: "iterate",
-        command: mode.stageCommands.iterate,
-        pollIntervalMs,
-        deadlineMs,
-        startedAt,
-        status: currentStatus,
-        lang,
-      });
-      verifyStageContract({ stage: "iterate", snapshot: contract.snapshot });
-    },
-    review: async () => {
-      const contract = stageContractSnapshot(targetDir, "review");
-      await runCommandWithPolling({
-        targetDir,
-        stage: "review",
-        command: mode.stageCommands.review,
-        pollIntervalMs,
-        deadlineMs,
-        startedAt,
-        status: currentStatus,
-        lang,
-      });
-      verifyStageContract({ stage: "review", snapshot: contract.snapshot });
-    },
-    report: async () => {
-      const contract = stageContractSnapshot(targetDir, "report");
-      await runCommandWithPolling({
-        targetDir,
-        stage: "report",
-        command: mode.stageCommands.report,
-        pollIntervalMs,
-        deadlineMs,
-        startedAt,
-        status: currentStatus,
-        lang,
-      });
-      verifyStageContract({ stage: "report", snapshot: contract.snapshot });
-    },
-    write: async () => {
-      const contract = stageContractSnapshot(targetDir, "write");
-      await runCommandWithPolling({
-        targetDir,
-        stage: "write",
-        command: mode.stageCommands.write,
-        pollIntervalMs,
-        deadlineMs,
-        startedAt,
-        status: currentStatus,
-        lang,
-      });
-      verifyStageContract({ stage: "write", snapshot: contract.snapshot });
-    },
-  };
-
-  const executeStage = async (stage) => {
-    const command = mode.stageCommands[stage];
-    if (!isMeaningful(command)) {
-      return;
-    }
-
-    let stageCompleted = false;
-    while (!stageCompleted) {
-      try {
-        const executor = stageExecutors[stage];
-        if (!executor) {
-          throw new Error(`unsupported auto stage executor: ${stage}`);
-        }
-        await executor();
-        executedStages.push(stage);
-        writeRunningStatus({
-          currentStage: stage,
-          currentCommand: command,
-          decision: `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 ${stage}`,
-          command: mode.stopCheckCommand,
-          deadlineMs,
-        });
-        if (stopCheck.matched) {
-          stopMatched = true;
-          stopReason = stopCheck.stdout || stopCheck.stderr || `stop condition matched after ${stage}`;
-          stageCompleted = true;
-          return;
-        }
-
-        stageCompleted = true;
-      } catch (error) {
-        failureCount += 1;
-        if (failureCount > maxFailures) {
-          failAutoMode(error.message);
-        }
-        writeRunningStatus({
-          currentStage: stage,
-          currentCommand: command,
-          decision: `retrying stage ${stage} after failure ${failureCount}`,
-        });
-      }
-    }
-  };
-
-  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 executeStage(stage);
-      if (stopMatched || successReached) {
-        break;
-      }
-    }
-
-    if (stopMatched || successReached) {
-      break;
-    }
-
-    if (!promotionApplied && isMeaningful(mode.promotionCheckCommand)) {
-      const promotionCheck = await runCheckCommand({
-        targetDir,
-        label: `promotion check after iteration ${iteration}`,
-        command: mode.promotionCheckCommand,
-        deadlineMs,
-      });
-      if (promotionCheck.matched) {
-        const promotionSnapshot = snapshotPaths(targetDir, PROMOTION_CANONICAL_FILES);
-        await runCommandWithPolling({
-          targetDir,
-          stage: "promotion",
-          command: mode.promotionCommand,
-          pollIntervalMs,
-          deadlineMs,
-          startedAt,
-          status: currentStatus,
-          lang,
-        });
-        writeRunningStatus({
-          currentStage: stagesPerIteration.at(-1) || currentStatus.currentStage,
-          currentCommand: mode.promotionCommand,
-          decision: `promotion policy matched after iteration ${iteration}`,
-        });
-        promotionApplied = true;
-        refreshContext({ targetDir });
-        verifyPromotionWriteback(targetDir, promotionSnapshot);
-        const frozenCoreChangesAfterPromotion = detectFrozenCoreChanges(frozenCoreSnapshot);
-        if (frozenCoreChangesAfterPromotion.length > 0) {
-          failAutoMode(`frozen core changed: ${frozenCoreChangesAfterPromotion.join(", ")}`);
-        }
-      }
-    }
-
-    const successCheck = await runCheckCommand({
-      targetDir,
-      label: `success check after iteration ${iteration}`,
-      command: mode.successCheckCommand,
-      deadlineMs,
-    });
-    if (successCheck.matched) {
-      successReached = true;
-      break;
-    }
-
-  }
-
-  if (stopMatched) {
-    currentStatus = {
-      ...currentStatus,
-      status: "stopped",
-      currentStage: executedStages.at(-1) || currentStatus.currentStage,
-      currentCommand: mode.stageCommands[executedStages.at(-1)] || currentStatus.currentCommand,
-      lastHeartbeat: new Date().toISOString(),
-      decision: stopReason || "stopped by stop condition",
-    };
-    writeAutoStatus(targetDir, currentStatus, { lang });
-    return {
-      mode,
-      status: currentStatus,
-      executedStages,
-    };
-  }
-
-  if (!successReached && loopStages.length > 0) {
-    failAutoMode(`max iterations exhausted without meeting success criteria: ${maxIterations}`);
-  }
-
-  for (const stage of finalStages) {
-    await executeStage(stage);
-    if (stopMatched) {
-      currentStatus = {
-        ...currentStatus,
-        status: "stopped",
-        currentStage: executedStages.at(-1) || currentStatus.currentStage,
-        currentCommand: mode.stageCommands[executedStages.at(-1)] || currentStatus.currentCommand,
-        lastHeartbeat: new Date().toISOString(),
-        decision: stopReason || "stopped by stop condition",
-      };
-      writeAutoStatus(targetDir, currentStatus, { lang });
-      return {
-        mode,
-        status: currentStatus,
-        executedStages,
-      };
-    }
-  }
-
-  currentStatus = {
-    ...currentStatus,
-    status: "completed",
-    currentStage: executedStages.at(-1) || currentStatus.currentStage,
-    currentCommand: mode.stageCommands[executedStages.at(-1)] || currentStatus.currentCommand,
-    lastHeartbeat: new Date().toISOString(),
-    decision: successReached ? "completed bounded auto orchestration" : "completed configured stages",
-  };
-  writeAutoStatus(targetDir, currentStatus, { lang });
-  return {
-    mode,
-    status: currentStatus,
-    executedStages,
-  };
-}
-
-function stopAutoMode({ targetDir, now = new Date() }) {
-  const existing = parseAutoStatus(targetDir);
-  const lang = readWorkflowLanguage(targetDir);
-  const status = {
-    ...existing,
-    status: "stopped",
-    lastHeartbeat: now.toISOString(),
-    decision: "stopped by operator",
-  };
-  writeAutoStatus(targetDir, status, { lang });
-  return status;
-}
-
-function getAutoStatus({ targetDir }) {
-  const mode = parseAutoMode(targetDir);
-  const status = parseAutoStatus(targetDir);
-  return {
-    mode,
-    status,
-    issues: validateAutoMode(mode, status).concat(validateAutoStatus(status, mode)),
-  };
-}
+const {
+  ALLOWED_AUTO_STAGES,
+  validateAutoMode,
+  validateAutoStatus,
+} = require("./auto_contracts.cjs");
+const {
+  parseAutoMode,
+  parseAutoStatus,
+} = require("./auto_state.cjs");
+const {
+  getAutoStatus,
+  startAutoMode,
+  stopAutoMode,
+} = require("./auto_runner.cjs");
 
 module.exports = {
   ALLOWED_AUTO_STAGES,