@danielblomma/cortex-mcp 2.0.5 → 2.0.6

package/bin/cortex.mjs

@@ -89,6 +89,13 @@ function printHelp() {
   console.log(helpRow("hooks [install|uninstall|status] [--project]", "Claude Code hooks"));
   console.log(helpRow("telemetry test", "Smoke-test the push pipeline"));
 
+  console.log(helpSection("HARNESS"));
+  console.log(helpRow("stage start --task-id <id> --description \"...\"", "Start a workflow run for a task"));
+  console.log(helpRow("stage status --task-id <id>", "Print run state JSON"));
+  console.log(helpRow("stage envelope --task-id <id> [--stage <name>]", "Compose stage prompt envelope"));
+  console.log(helpRow("stage advance --task-id <id> --stage <name> --body-file <path>", "Write artifact, advance run"));
+  console.log(helpRow("stage run --task-id <id> -- <command>", "Exec a command with CORTEX_ACTIVE_TASK_ID set"));
+
   console.log(helpSection("MISC"));
   console.log(helpRow("mcp", "Run the MCP stdio server for the current project"));
   console.log(helpRow("version", "Print CLI version"));
@@ -1005,6 +1012,10 @@ async function run() {
     return runRunCommand(rest);
   }
 
+  if (command === "stage") {
+    return runStageCommandShim(rest);
+  }
+
   const passthrough = new Set([
     "bootstrap",
     "update",
@@ -1527,6 +1538,19 @@ async function runRunCommand(args) {
   process.exit(exitCode);
 }
 
+async function runStageCommandShim(args) {
+  const target = process.env.CORTEX_PROJECT_ROOT?.trim() || process.cwd();
+  process.env.CORTEX_PROJECT_ROOT = path.resolve(target);
+  const entry = resolveCliEntry("stage");
+  if (!fs.existsSync(entry)) {
+    throw new Error(
+      `Build the project's MCP first (missing ${entry}). Run 'cortex bootstrap' in the project root.`,
+    );
+  }
+  const mod = await import(pathToFileURL(entry).href);
+  await mod.runStageCommand(args);
+}
+
 async function runTelemetryCommand(args) {
   const sub = args[0] || "help";
   if (sub === "test") {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@danielblomma/cortex-mcp",
   "mcpName": "io.github.DanielBlomma/cortex",
-  "version": "2.0.5",
+  "version": "2.0.6",
   "description": "Local, repo-scoped context platform for coding assistants. Semantic search, graph relationships, and architectural rule context.",
   "type": "module",
   "author": "Daniel Blomma",

package/scaffold/mcp/package-lock.json

@@ -10,6 +10,9 @@
       "dependencies": {
         "@huggingface/transformers": "^4.1.0",
         "@modelcontextprotocol/sdk": "^1.27.1",
+        "@types/js-yaml": "^4.0.9",
+        "js-yaml": "^4.1.1",
+        "minimatch": "^10.2.5",
         "ryugraph": "^25.9.1",
         "zod": "^3.24.1"
       },
@@ -842,12 +845,17 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/@types/js-yaml": {
+      "version": "4.0.9",
+      "resolved": "https://registry.npmjs.org/@types/js-yaml/-/js-yaml-4.0.9.tgz",
+      "integrity": "sha512-k4MGaQl5TGo/iipqb2UDG2UwjXziSWkh0uysQelTlJpX1qGlpUZYm8PnO4DxG1qBomtJUdYJ6qR6xdIah10JLg==",
+      "license": "MIT"
+    },
     "node_modules/@types/node": {
       "version": "22.19.13",
       "resolved": "https://registry.npmjs.org/@types/node/-/node-22.19.13.tgz",
       "integrity": "sha512-akNQMv0wW5uyRpD2v2IEyRSZiR+BeGuoB6L310EgGObO44HSMNT8z1xzio28V8qOrgYaopIDNA18YgdXd+qTiw==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "undici-types": "~6.21.0"
       }
@@ -989,6 +997,21 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/argparse": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz",
+      "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==",
+      "license": "Python-2.0"
+    },
+    "node_modules/balanced-match": {
+      "version": "4.0.4",
+      "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-4.0.4.tgz",
+      "integrity": "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==",
+      "license": "MIT",
+      "engines": {
+        "node": "18 || 20 || >=22"
+      }
+    },
     "node_modules/body-parser": {
       "version": "2.2.2",
       "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-2.2.2.tgz",
@@ -1020,6 +1043,18 @@
       "deprecated": "Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.",
       "license": "MIT"
     },
+    "node_modules/brace-expansion": {
+      "version": "5.0.5",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.5.tgz",
+      "integrity": "sha512-VZznLgtwhn+Mact9tfiwx64fA9erHH/MCXEUfB/0bX/6Fz6ny5EGTXYltMocqg4xFAQZtnO3DHWWXi8RiuN7cQ==",
+      "license": "MIT",
+      "dependencies": {
+        "balanced-match": "^4.0.2"
+      },
+      "engines": {
+        "node": "18 || 20 || >=22"
+      }
+    },
     "node_modules/bytes": {
       "version": "3.1.2",
       "resolved": "https://registry.npmjs.org/bytes/-/bytes-3.1.2.tgz",
@@ -1760,7 +1795,6 @@
       "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.14.tgz",
       "integrity": "sha512-am5zfg3yu6sqn5yjKBNqhnTX7Cv+m00ox+7jbaKkrLMRJ4rAdldd1xPd/JzbBWspqaQv6RSTrgFN95EsfhC+7w==",
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=16.9.0"
       }
@@ -1861,6 +1895,18 @@
         "url": "https://github.com/sponsors/panva"
       }
     },
+    "node_modules/js-yaml": {
+      "version": "4.1.1",
+      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.1.tgz",
+      "integrity": "sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA==",
+      "license": "MIT",
+      "dependencies": {
+        "argparse": "^2.0.1"
+      },
+      "bin": {
+        "js-yaml": "bin/js-yaml.js"
+      }
+    },
     "node_modules/json-schema-traverse": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz",
@@ -1940,6 +1986,21 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/minimatch": {
+      "version": "10.2.5",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-10.2.5.tgz",
+      "integrity": "sha512-MULkVLfKGYDFYejP07QOurDLLQpcjk7Fw+7jXS2R2czRQzR56yHRveU5NDJEOviH+hETZKSkIk5c+T23GjFUMg==",
+      "license": "BlueOak-1.0.0",
+      "dependencies": {
+        "brace-expansion": "^5.0.5"
+      },
+      "engines": {
+        "node": "18 || 20 || >=22"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
     "node_modules/minimist": {
       "version": "1.2.8",
       "resolved": "https://registry.npmjs.org/minimist/-/minimist-1.2.8.tgz",
@@ -2611,7 +2672,6 @@
       "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
       "dev": true,
       "license": "Apache-2.0",
-      "peer": true,
       "bin": {
         "tsc": "bin/tsc",
         "tsserver": "bin/tsserver"
@@ -2764,7 +2824,6 @@
       "resolved": "https://registry.npmjs.org/zod/-/zod-3.25.76.tgz",
       "integrity": "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==",
       "license": "MIT",
-      "peer": true,
       "funding": {
         "url": "https://github.com/sponsors/colinhacks"
       }

package/scaffold/mcp/package.json

@@ -12,8 +12,11 @@
     "test": "npm run build --silent && node --test tests/*.test.mjs"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.27.1",
     "@huggingface/transformers": "^4.1.0",
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@types/js-yaml": "^4.0.9",
+    "js-yaml": "^4.1.1",
+    "minimatch": "^10.2.5",
     "ryugraph": "^25.9.1",
     "zod": "^3.24.1"
   },

package/scaffold/mcp/src/cli/stage.ts

@@ -0,0 +1,325 @@
+import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import {
+  composeStageEnvelope,
+  createRun,
+  advanceStage,
+  getRunState,
+  type StageStatus,
+  type WorkflowDefinition,
+} from "../core/workflow/index.js";
+import { DEFAULT_WORKFLOWS } from "../core/workflow/default-workflows.js";
+
+/**
+ * `cortex stage` CLI surface. Each subcommand is a thin shell wrapper
+ * around the workflow primitives, mirroring the cortex.workflow.* MCP
+ * tools so shell scripts and CI can drive the harness without an MCP
+ * client.
+ *
+ * Subcommands:
+ *   start --task-id <id> --description "..." [--workflow <id>]
+ *   status --task-id <id>
+ *   envelope --task-id <id> [--stage <name>]
+ *   advance --task-id <id> --stage <name> --body-file <path>
+ *           [--frontmatter-file <path>] [--status <complete|blocked|failed>]
+ *   run --task-id <id> -- <command> [args...]
+ *     Sets CORTEX_ACTIVE_TASK_ID and execs the command. Use this to
+ *     spawn an agent that runs under the harness's pre-tool-use gate.
+ *
+ * All commands resolve cwd from CORTEX_PROJECT_ROOT (preferred) or
+ * process.cwd() so they work both inside an MCP server context and as
+ * standalone shell calls.
+ */
+
+export async function runStageCommand(args: string[]): Promise<void> {
+  const sub = args[0] ?? "help";
+  const rest = args.slice(1);
+
+  switch (sub) {
+    case "start":
+      return runStart(rest);
+    case "status":
+      return runStatus(rest);
+    case "envelope":
+      return runEnvelope(rest);
+    case "advance":
+      return runAdvance(rest);
+    case "run":
+      return runRun(rest);
+    case "help":
+    case "--help":
+    case "-h":
+      printHelp();
+      return;
+    default:
+      printHelp();
+      throw new Error(`Unknown stage subcommand: ${sub}`);
+  }
+}
+
+function printHelp(): void {
+  const lines = [
+    "Usage:",
+    "  cortex stage start    --task-id <id> --description \"...\" [--workflow <id>]",
+    "  cortex stage status   --task-id <id>",
+    "  cortex stage envelope --task-id <id> [--stage <name>]",
+    "  cortex stage advance  --task-id <id> --stage <name> --body-file <path>",
+    "                        [--frontmatter-file <path>] [--status <s>] [--outcome-file <path>]",
+    "  cortex stage run      --task-id <id> -- <command> [args...]",
+    "",
+    "Status values: complete (default) | blocked | failed",
+    "All commands operate on .agents/<task-id>/ in the current project root.",
+  ];
+  process.stdout.write(lines.join("\n") + "\n");
+}
+
+function projectRoot(): string {
+  return process.env.CORTEX_PROJECT_ROOT?.trim() || process.cwd();
+}
+
+function resolveWorkflow(workflowId: string): WorkflowDefinition {
+  const wf = DEFAULT_WORKFLOWS[workflowId];
+  if (!wf) {
+    throw new Error(
+      `Unknown workflow_id: ${workflowId}. Available: ${
+        Object.keys(DEFAULT_WORKFLOWS).join(", ") || "<none>"
+      }`,
+    );
+  }
+  return wf;
+}
+
+type Flags = Record<string, string | boolean>;
+
+function parseFlags(args: string[]): { flags: Flags; rest: string[] } {
+  const flags: Flags = {};
+  const rest: string[] = [];
+  let i = 0;
+  while (i < args.length) {
+    const arg = args[i];
+    if (arg === "--") {
+      rest.push(...args.slice(i + 1));
+      break;
+    }
+    if (arg.startsWith("--")) {
+      const next = args[i + 1];
+      if (next === undefined || next.startsWith("--")) {
+        flags[arg.slice(2)] = true;
+        i += 1;
+      } else {
+        flags[arg.slice(2)] = next;
+        i += 2;
+      }
+      continue;
+    }
+    rest.push(arg);
+    i += 1;
+  }
+  return { flags, rest };
+}
+
+function requireFlag(flags: Flags, name: string): string {
+  const value = flags[name];
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`Missing required flag: --${name}`);
+  }
+  return value;
+}
+
+function emitJson(data: unknown): void {
+  process.stdout.write(JSON.stringify(data, null, 2) + "\n");
+}
+
+async function runStart(args: string[]): Promise<void> {
+  const { flags } = parseFlags(args);
+  const taskId = requireFlag(flags, "task-id");
+  const description = requireFlag(flags, "description");
+  const workflowId =
+    typeof flags.workflow === "string" ? flags.workflow : "secure-build";
+
+  const workflow = resolveWorkflow(workflowId);
+  const state = createRun({
+    cwd: projectRoot(),
+    taskId,
+    workflow,
+    taskDescription: description,
+  });
+  const envelope = composeStageEnvelope({
+    cwd: projectRoot(),
+    taskId,
+    workflow,
+  });
+  emitJson({ state, envelope });
+}
+
+async function runStatus(args: string[]): Promise<void> {
+  const { flags } = parseFlags(args);
+  const taskId = requireFlag(flags, "task-id");
+  const state = getRunState(projectRoot(), taskId);
+  emitJson({ state });
+}
+
+async function runEnvelope(args: string[]): Promise<void> {
+  const { flags } = parseFlags(args);
+  const taskId = requireFlag(flags, "task-id");
+  const stageName = typeof flags.stage === "string" ? flags.stage : undefined;
+
+  const state = getRunState(projectRoot(), taskId);
+  if (!state) {
+    throw new Error(
+      `No run state for task ${taskId}. Start one with 'cortex stage start'.`,
+    );
+  }
+  const workflow = resolveWorkflow(state.workflow_id);
+  const envelope = composeStageEnvelope({
+    cwd: projectRoot(),
+    taskId,
+    workflow,
+    stageName,
+  });
+  emitJson({ envelope });
+}
+
+async function runAdvance(args: string[]): Promise<void> {
+  const { flags } = parseFlags(args);
+  const taskId = requireFlag(flags, "task-id");
+  const stageName = requireFlag(flags, "stage");
+  const bodyPath = requireFlag(flags, "body-file");
+  const frontmatterPath =
+    typeof flags["frontmatter-file"] === "string"
+      ? flags["frontmatter-file"]
+      : null;
+  const outcomePath =
+    typeof flags["outcome-file"] === "string" ? flags["outcome-file"] : null;
+  const statusFlag =
+    typeof flags.status === "string" ? (flags.status as StageStatus) : undefined;
+
+  const body = readFileSync(bodyPath, "utf8");
+  const frontmatter: Record<string, unknown> = frontmatterPath
+    ? parseJsonObject(frontmatterPath)
+    : {};
+  const outcome = outcomePath ? parseJsonObject(outcomePath) : undefined;
+
+  const state = getRunState(projectRoot(), taskId);
+  if (!state) {
+    throw new Error(
+      `No run state for task ${taskId}. Start one with 'cortex stage start'.`,
+    );
+  }
+  const workflow = resolveWorkflow(state.workflow_id);
+  const stage = workflow.stages.find((s) => s.name === stageName);
+  if (!stage) {
+    throw new Error(
+      `Stage ${stageName} is not defined in workflow ${workflow.id}`,
+    );
+  }
+
+  const finalStatus: StageStatus = statusFlag ?? "complete";
+  const next = advanceStage({
+    cwd: projectRoot(),
+    taskId,
+    workflow,
+    stageName,
+    artifactName: stage.artifact,
+    frontmatter: {
+      ...frontmatter,
+      stage: stageName,
+      status: finalStatus,
+      references:
+        (Array.isArray((frontmatter as Record<string, unknown>).references)
+          ? ((frontmatter as Record<string, unknown>).references as unknown[])
+              .filter((v): v is string => typeof v === "string")
+          : null) ?? deriveReferencesFromReads(stage.reads, workflow),
+    },
+    body,
+    status: finalStatus,
+    outcome,
+  });
+
+  let nextEnvelope = null;
+  if (next.outcome === "in_progress" && next.current_stage) {
+    nextEnvelope = composeStageEnvelope({
+      cwd: projectRoot(),
+      taskId,
+      workflow,
+    });
+  }
+  emitJson({ state: next, next_envelope: nextEnvelope });
+}
+
+function parseJsonObject(filePath: string): Record<string, unknown> {
+  const raw = readFileSync(filePath, "utf8");
+  let value: unknown;
+  try {
+    value = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(
+      `Failed to parse JSON in ${filePath}: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error(`Expected JSON object in ${filePath}, got ${typeof value}`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function deriveReferencesFromReads(
+  reads: string[],
+  workflow: WorkflowDefinition,
+): string[] {
+  const refs: string[] = [];
+  for (const readName of reads) {
+    const stage = workflow.stages.find((s) => s.name === readName);
+    if (stage) refs.push(stage.artifact);
+  }
+  return refs;
+}
+
+async function runRun(args: string[]): Promise<void> {
+  const { flags, rest } = parseFlags(args);
+  const taskId = requireFlag(flags, "task-id");
+  if (rest.length === 0) {
+    throw new Error(
+      "cortex stage run requires a command after --, e.g. 'cortex stage run --task-id task-1 -- claude'",
+    );
+  }
+
+  const state = getRunState(projectRoot(), taskId);
+  if (!state) {
+    throw new Error(
+      `No run state for task ${taskId}. Start one with 'cortex stage start'.`,
+    );
+  }
+  if (state.outcome !== "in_progress" || !state.current_stage) {
+    throw new Error(
+      `Run ${taskId} is not in progress (outcome=${state.outcome}). Cannot spawn agent.`,
+    );
+  }
+
+  const [command, ...commandArgs] = rest;
+
+  const child = spawn(command, commandArgs, {
+    stdio: "inherit",
+    env: {
+      ...process.env,
+      CORTEX_ACTIVE_TASK_ID: taskId,
+    },
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    child.on("error", reject);
+    child.on("exit", (code, signal) => {
+      if (signal) {
+        reject(new Error(`spawned process terminated by signal ${signal}`));
+        return;
+      }
+      if (code !== 0) {
+        reject(new Error(`spawned process exited with code ${code}`));
+        return;
+      }
+      resolve();
+    });
+  });
+}

package/scaffold/mcp/src/core/workflow/artifact-io.ts

@@ -0,0 +1,156 @@
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import * as yaml from "js-yaml";
+import {
+  runStateSchema,
+  stageArtifactFrontmatterSchema,
+  type RunState,
+  type StageArtifactFrontmatter,
+} from "./schemas.js";
+
+/**
+ * Filesystem layout for one workflow run:
+ *
+ *   <cwd>/.agents/<task-id>/
+ *     plan.md
+ *     review.md
+ *     ...
+ *     state.json
+ *
+ * All paths in this module are relative to the project's <cwd>. The caller
+ * is responsible for choosing cwd; we never assume process.cwd() here so
+ * tests can target a tmp directory.
+ */
+
+export const AGENTS_DIR = ".agents";
+export const STATE_FILENAME = "state.json";
+
+export function runDir(cwd: string, taskId: string): string {
+  return join(cwd, AGENTS_DIR, taskId);
+}
+
+export function stateFilePath(cwd: string, taskId: string): string {
+  return join(runDir(cwd, taskId), STATE_FILENAME);
+}
+
+export function artifactPath(
+  cwd: string,
+  taskId: string,
+  artifactName: string,
+): string {
+  return join(runDir(cwd, taskId), artifactName);
+}
+
+const FRONTMATTER_OPEN = /^---\s*\r?\n/;
+const FRONTMATTER_CLOSE = /\r?\n---\s*\r?\n/;
+
+export type ParsedArtifact = {
+  frontmatter: StageArtifactFrontmatter;
+  body: string;
+};
+
+export function parseStageArtifact(text: string): ParsedArtifact {
+  if (!FRONTMATTER_OPEN.test(text)) {
+    throw new Error("Stage artifact is missing YAML frontmatter (--- ... ---)");
+  }
+  const afterOpen = text.replace(FRONTMATTER_OPEN, "");
+  const closeMatch = afterOpen.match(FRONTMATTER_CLOSE);
+  if (!closeMatch || closeMatch.index === undefined) {
+    throw new Error("Stage artifact frontmatter is not terminated (--- ... ---)");
+  }
+  const yamlText = afterOpen.slice(0, closeMatch.index);
+  const body = afterOpen
+    .slice(closeMatch.index + closeMatch[0].length)
+    .replace(/^\s+/, "")
+    .replace(/\s+$/, "");
+
+  let raw: unknown;
+  try {
+    raw = yaml.load(yamlText);
+  } catch (err) {
+    throw new Error(
+      `Failed to parse stage artifact frontmatter as YAML: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+  }
+
+  const parsed = stageArtifactFrontmatterSchema.safeParse(raw);
+  if (!parsed.success) {
+    throw new Error(
+      `Stage artifact frontmatter does not match schema: ${parsed.error.message}`,
+    );
+  }
+  return { frontmatter: parsed.data, body };
+}
+
+export function readStageArtifact(
+  cwd: string,
+  taskId: string,
+  artifactName: string,
+): ParsedArtifact {
+  const path = artifactPath(cwd, taskId, artifactName);
+  const text = readFileSync(path, "utf8");
+  return parseStageArtifact(text);
+}
+
+export function renderStageArtifact(
+  frontmatter: StageArtifactFrontmatter,
+  body: string,
+): string {
+  const yamlText = yaml.dump(frontmatter, {
+    lineWidth: 100,
+    noRefs: true,
+    sortKeys: false,
+  });
+  const trimmedBody = body.trim();
+  return `---\n${yamlText}---\n\n${trimmedBody}\n`;
+}
+
+export function writeStageArtifact(
+  cwd: string,
+  taskId: string,
+  artifactName: string,
+  frontmatter: StageArtifactFrontmatter,
+  body: string,
+): string {
+  const dir = runDir(cwd, taskId);
+  mkdirSync(dir, { recursive: true });
+  const path = artifactPath(cwd, taskId, artifactName);
+  writeFileSync(path, renderStageArtifact(frontmatter, body), "utf8");
+  return path;
+}
+
+export function readRunState(cwd: string, taskId: string): RunState | null {
+  const path = stateFilePath(cwd, taskId);
+  if (!existsSync(path)) return null;
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(path, "utf8"));
+  } catch (err) {
+    throw new Error(
+      `Failed to parse run state at ${path}: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+  }
+  const parsed = runStateSchema.safeParse(raw);
+  if (!parsed.success) {
+    throw new Error(`Run state at ${path} does not match schema: ${parsed.error.message}`);
+  }
+  return parsed.data;
+}
+
+export function writeRunState(cwd: string, state: RunState): string {
+  const validated = runStateSchema.parse(state);
+  const dir = runDir(cwd, validated.task_id);
+  mkdirSync(dir, { recursive: true });
+  const path = stateFilePath(cwd, validated.task_id);
+  writeFileSync(path, JSON.stringify(validated, null, 2) + "\n", "utf8");
+  return path;
+}