@weppy/ralph 0.1.0

package/dist/cli.js

@@ -0,0 +1,2248 @@
+#!/usr/bin/env node
+
+// src/planning/index.ts
+import { stat } from "node:fs/promises";
+import { resolve } from "node:path";
+async function createInitialPlan(input) {
+  const normalizedInputDocuments = await Promise.all(
+    input.inputDocuments.map(async (documentPath) => {
+      const resolvedPath = resolve(input.cwd ?? process.cwd(), documentPath);
+      const fileStat = await stat(resolvedPath);
+      return {
+        path: resolvedPath,
+        kind: detectInputDocumentKind(resolvedPath, fileStat.isDirectory())
+      };
+    })
+  );
+  const planModel = createDefaultPlanningModel({
+    title: input.title,
+    workspacePath: input.workspacePath,
+    inputDocuments: normalizedInputDocuments
+  });
+  return {
+    normalizedInputDocuments,
+    specMarkdown: buildSpecMarkdown(input.title, input.workspacePath, normalizedInputDocuments),
+    planMarkdown: buildPlanMarkdown(input.title, planModel, normalizedInputDocuments),
+    tasks: {
+      phases: planModel.phases,
+      tasks: planModel.tasks,
+      dependencies: planModel.dependencies,
+      retryCounts: Object.fromEntries(planModel.tasks.map((task) => [task.id, 0])),
+      evidenceLinks: Object.fromEntries(planModel.tasks.map((task) => [task.id, []])),
+      phaseGateStatus: Object.fromEntries(planModel.phases.map((phase) => [phase.id, "pending"]))
+    },
+    runtime: {
+      currentPhaseId: planModel.phases[0]?.id ?? null,
+      currentTaskId: planModel.tasks[0]?.id ?? null,
+      remainingTaskCount: planModel.tasks.length,
+      lastRunId: null,
+      nextAction: "resume",
+      blockedReason: null,
+      lastValidationStatus: "pending"
+    }
+  };
+}
+function buildSpecMarkdown(title, workspacePath, inputDocuments) {
+  const sections = ["# Job Spec", "", `Title: ${title}`, "", `Workspace: ${workspacePath}`, ""];
+  if (inputDocuments.length === 0) {
+    sections.push("No input documents were provided.");
+    sections.push("");
+  } else {
+    sections.push("Referenced inputs:", "");
+    sections.push(
+      ...inputDocuments.map((document) => `- [${document.kind}] ${document.path}`),
+      "",
+      "Ralph passes these paths to the agent as references.",
+      "The agent must inspect the files directly instead of relying on copied content.",
+      ""
+    );
+  }
+  return `${sections.join("\n").trimEnd()}
+`;
+}
+function buildPlanMarkdown(title, planModel, inputDocuments) {
+  const lines = [
+    "# Plan",
+    "",
+    `Job title: ${title}`,
+    ""
+  ];
+  for (const phase of planModel.phases) {
+    lines.push(`## ${phase.id} ${phase.title}`, "");
+    const phaseTasks = planModel.tasks.filter((task) => task.phaseId === phase.id);
+    if (phaseTasks.length === 0) {
+      lines.push("No tasks.", "");
+      continue;
+    }
+    for (const task of phaseTasks) {
+      const dependencies = planModel.dependencies[task.id] ?? [];
+      lines.push(`- ${task.id}: ${task.title}`);
+      lines.push(`  - ${task.description}`);
+      lines.push(
+        dependencies.length === 0 ? "  - Dependencies: none" : `  - Dependencies: ${dependencies.join(", ")}`
+      );
+    }
+    lines.push("");
+  }
+  if (inputDocuments.length > 0) {
+    lines.push(
+      "",
+      "## Inputs",
+      "",
+      ...inputDocuments.map((value) => `- [${value.kind}] ${value.path}`)
+    );
+  }
+  return `${lines.join("\n")}
+`;
+}
+function createDefaultPlanningModel(input) {
+  const phaseId = "PHASE-001";
+  const taskId = "TASK-001";
+  const inputSummary = input.inputDocuments.length === 0 ? "Use the workspace state as the primary source of truth." : `Inspect ${input.inputDocuments.length} referenced input path(s) before making changes.`;
+  return {
+    phases: [
+      {
+        id: phaseId,
+        title: "Requested Work"
+      }
+    ],
+    tasks: [
+      {
+        id: taskId,
+        phaseId,
+        title: input.title,
+        description: `${input.title}. ${inputSummary}`,
+        status: "pending"
+      }
+    ],
+    dependencies: {
+      [taskId]: []
+    }
+  };
+}
+function detectInputDocumentKind(documentPath, isDirectory) {
+  if (isDirectory) {
+    return "directory";
+  }
+  const normalizedPath = documentPath.toLowerCase();
+  if ([".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp", ".svg"].some(
+    (extension) => normalizedPath.endsWith(extension)
+  )) {
+    return "image";
+  }
+  if (normalizedPath.includes(".")) {
+    return "file";
+  }
+  return "unknown";
+}
+
+// src/state/index.ts
+import { mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
+import { dirname, join, resolve as resolve2 } from "node:path";
+var stateFeature = {
+  rootDirectoryName: ".ralph-cache",
+  defaultLocationBase: "workspacePath",
+  cliOverrideFlag: "--state-dir"
+};
+function resolveWorkspacePath(workspacePath, cwd = process.cwd()) {
+  if (workspacePath.trim().length === 0) {
+    throw new Error("`workspacePath` must not be empty.");
+  }
+  return resolve2(cwd, workspacePath);
+}
+function resolveStateDirectoryPath({
+  workspacePath,
+  stateDirectoryPath,
+  cwd = process.cwd()
+}) {
+  if (stateDirectoryPath !== void 0) {
+    return resolve2(cwd, stateDirectoryPath);
+  }
+  if (workspacePath === void 0) {
+    throw new Error("`workspacePath` is required when `stateDirectoryPath` is not provided.");
+  }
+  const resolvedWorkspacePath = resolveWorkspacePath(workspacePath, cwd);
+  return join(resolvedWorkspacePath, stateFeature.rootDirectoryName);
+}
+function getJobPaths(jobId, rootDirectoryPath) {
+  const jobDirectoryPath = join(rootDirectoryPath, "jobs", jobId);
+  return {
+    rootDirectoryPath,
+    jobsDirectoryPath: join(rootDirectoryPath, "jobs"),
+    currentJobPath: join(rootDirectoryPath, "current-job.txt"),
+    jobDirectoryPath,
+    jobJsonPath: join(jobDirectoryPath, "job.json"),
+    inputsJsonPath: join(jobDirectoryPath, "inputs.json"),
+    specMarkdownPath: join(jobDirectoryPath, "spec.md"),
+    planMarkdownPath: join(jobDirectoryPath, "plan.md"),
+    tasksJsonPath: join(jobDirectoryPath, "tasks.json"),
+    runtimeJsonPath: join(jobDirectoryPath, "runtime.json"),
+    finalSummaryPath: join(jobDirectoryPath, "final-summary.md"),
+    userChecksPath: join(jobDirectoryPath, "user-checks.md"),
+    validationsDirectoryPath: join(jobDirectoryPath, "validations"),
+    runsDirectoryPath: join(jobDirectoryPath, "runs"),
+    artifactsDirectoryPath: join(jobDirectoryPath, "artifacts")
+  };
+}
+async function ensureStateRoot(rootDirectoryPath) {
+  await mkdir(join(rootDirectoryPath, "jobs"), { recursive: true });
+}
+async function ensureJobDirectories(jobPaths) {
+  await ensureStateRoot(jobPaths.rootDirectoryPath);
+  await mkdir(jobPaths.jobDirectoryPath, { recursive: true });
+  await mkdir(jobPaths.validationsDirectoryPath, { recursive: true });
+  await mkdir(jobPaths.runsDirectoryPath, { recursive: true });
+  await mkdir(jobPaths.artifactsDirectoryPath, { recursive: true });
+}
+async function ensureRunDirectory(runDirectoryPath) {
+  await mkdir(runDirectoryPath, { recursive: true });
+}
+async function atomicWriteFile(filePath, content) {
+  await mkdir(dirname(filePath), { recursive: true });
+  const temporaryPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  await writeFile(temporaryPath, content, "utf8");
+  await rename(temporaryPath, filePath);
+}
+async function atomicWriteJson(filePath, value) {
+  await atomicWriteFile(filePath, `${JSON.stringify(value, null, 2)}
+`);
+}
+async function readTextFile(filePath) {
+  try {
+    return await readFile(filePath, "utf8");
+  } catch (error) {
+    if (isMissingFileError(error)) {
+      return void 0;
+    }
+    throw error;
+  }
+}
+async function readJsonFile(filePath) {
+  const content = await readTextFile(filePath);
+  if (content === void 0) {
+    return void 0;
+  }
+  return JSON.parse(content);
+}
+function getNextRunId(lastRunId) {
+  const previousNumber = lastRunId === null ? 0 : Number.parseInt(lastRunId.replace("run-", ""), 10);
+  const nextNumber = Number.isFinite(previousNumber) ? previousNumber + 1 : 1;
+  return `run-${String(nextNumber).padStart(3, "0")}`;
+}
+function getRunPaths(runsDirectoryPath, runId) {
+  const runDirectoryPath = join(runsDirectoryPath, runId);
+  const resultPath = join(runDirectoryPath, "result.json");
+  return {
+    runDirectoryPath,
+    promptPath: join(runDirectoryPath, "prompt.md"),
+    resultPath,
+    runRecordPath: join(runDirectoryPath, "run-record.json"),
+    stdoutLogPath: join(runDirectoryPath, "stdout.log"),
+    stderrLogPath: join(runDirectoryPath, "stderr.log"),
+    outputPath: resultPath
+  };
+}
+function getValidationPath(validationsDirectoryPath, validationIndex) {
+  return join(
+    validationsDirectoryPath,
+    `validation-${String(validationIndex).padStart(3, "0")}.json`
+  );
+}
+async function listDirectoryEntries(directoryPath) {
+  try {
+    return await readdir(directoryPath);
+  } catch (error) {
+    if (isMissingFileError(error)) {
+      return [];
+    }
+    throw error;
+  }
+}
+function isMissingFileError(error) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+
+// src/shared/utils/format.ts
+function slugify(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40) || "job";
+}
+function toIsoTimestamp(date = /* @__PURE__ */ new Date()) {
+  return date.toISOString();
+}
+
+// src/job/rules.ts
+function isTaskCompleted(status) {
+  return status === "completed";
+}
+function isTaskTerminal(status) {
+  return ["completed", "blocked", "failed", "cancelled"].includes(status);
+}
+function isTaskRemaining(status) {
+  return ["pending", "running", "partial"].includes(status);
+}
+function isJobTerminal(status) {
+  return ["completed", "failed", "cancelled"].includes(status);
+}
+function derivePhaseGateStatus(phases, tasks) {
+  return Object.fromEntries(
+    phases.map((phase) => {
+      const phaseTasks = tasks.filter((task) => task.phaseId === phase.id);
+      if (phaseTasks.some((task) => ["failed", "blocked"].includes(task.status))) {
+        return [phase.id, "failed"];
+      }
+      if (phaseTasks.length > 0 && phaseTasks.every((task) => isTaskCompleted(task.status))) {
+        return [phase.id, "passed"];
+      }
+      return [phase.id, "pending"];
+    })
+  );
+}
+function selectRunnableTask(snapshot) {
+  const activePhaseId = getActivePhaseId(snapshot.tasks.phases, snapshot.tasks.tasks);
+  if (activePhaseId === null) {
+    return void 0;
+  }
+  return snapshot.tasks.tasks.find((task) => {
+    if (task.phaseId !== activePhaseId || task.status !== "pending") {
+      return false;
+    }
+    return areTaskDependenciesSatisfied(task, snapshot.tasks.tasks, snapshot.tasks.dependencies);
+  });
+}
+function nextPendingTaskId(phases, tasks, dependencies) {
+  const activePhaseId = getActivePhaseId(phases, tasks);
+  if (activePhaseId === null) {
+    return null;
+  }
+  return tasks.find((task) => {
+    if (task.phaseId !== activePhaseId || task.status !== "pending") {
+      return false;
+    }
+    return areTaskDependenciesSatisfied(task, tasks, dependencies);
+  })?.id ?? null;
+}
+function countRemainingTasks(tasks) {
+  return tasks.filter((task) => isTaskRemaining(task.status)).length;
+}
+function buildNoRunnableTaskReason(snapshot) {
+  const phaseGateStatus = derivePhaseGateStatus(snapshot.tasks.phases, snapshot.tasks.tasks);
+  const activePhaseId = getActivePhaseId(snapshot.tasks.phases, snapshot.tasks.tasks);
+  if (activePhaseId === null) {
+    return "No runnable task is available.";
+  }
+  if (phaseGateStatus[activePhaseId] === "failed") {
+    return `No runnable task is available because ${activePhaseId} has failed.`;
+  }
+  const pendingTasks = snapshot.tasks.tasks.filter(
+    (task) => task.phaseId === activePhaseId && task.status === "pending"
+  );
+  const blockedDependencies = pendingTasks.map((task) => {
+    const unmetDependencies = (snapshot.tasks.dependencies[task.id] ?? []).filter((dependencyId) => {
+      const dependency = snapshot.tasks.tasks.find((entry) => entry.id === dependencyId);
+      return dependency === void 0 || !isTaskCompleted(dependency.status);
+    });
+    return unmetDependencies.length > 0 ? `${task.id} waits for ${unmetDependencies.join(", ")}` : null;
+  }).filter((value) => value !== null);
+  if (blockedDependencies.length > 0) {
+    return `No runnable task is available because dependencies are incomplete: ${blockedDependencies.join("; ")}.`;
+  }
+  return `No runnable task is available in ${activePhaseId}.`;
+}
+function buildBlockedRuntime(snapshot, reason) {
+  return {
+    ...snapshot.runtime,
+    currentTaskId: null,
+    currentPhaseId: getActivePhaseId(snapshot.tasks.phases, snapshot.tasks.tasks),
+    remainingTaskCount: countRemainingTasks(snapshot.tasks.tasks),
+    nextAction: "blocked",
+    blockedReason: reason
+  };
+}
+function getActivePhaseId(phases, tasks) {
+  const phaseGateStatus = derivePhaseGateStatus(phases, tasks);
+  for (const phase of phases) {
+    if (phaseGateStatus[phase.id] === "passed") {
+      continue;
+    }
+    return phase.id;
+  }
+  return null;
+}
+function areTaskDependenciesSatisfied(task, tasks, dependencies) {
+  const taskDependencies = dependencies[task.id] ?? [];
+  return taskDependencies.every((dependencyId) => {
+    const dependency = tasks.find((entry) => entry.id === dependencyId);
+    return dependency !== void 0 && isTaskCompleted(dependency.status);
+  });
+}
+
+// src/job/index.ts
+async function createJob(options) {
+  const cwd = options.cwd ?? process.cwd();
+  const workspacePath = resolveWorkspacePath(options.workspacePath, cwd);
+  const stateDirectoryPath = resolveStateDirectoryPath({
+    workspacePath,
+    stateDirectoryPath: options.stateDirectoryPath,
+    cwd
+  });
+  const jobId = buildJobId(options.title);
+  const paths = getJobPaths(jobId, stateDirectoryPath);
+  const planningResult = await createInitialPlan({
+    title: options.title,
+    workspacePath,
+    inputDocuments: options.inputDocuments,
+    cwd
+  });
+  const timestamp = toIsoTimestamp();
+  const job = {
+    id: jobId,
+    title: options.title,
+    requestedAgent: options.agent,
+    status: "planned",
+    workspacePath,
+    stateDirectoryPath,
+    inputDocuments: planningResult.normalizedInputDocuments,
+    validationProfile: {
+      name: options.validateCommands !== void 0 && options.validateCommands.length > 0 ? "commands" : "default",
+      commands: options.validateCommands ?? []
+    },
+    retryPolicy: {
+      maxRetriesPerTask: options.maxRetriesPerTask ?? 1
+    },
+    createdAt: timestamp,
+    updatedAt: timestamp
+  };
+  await ensureJobDirectories(paths);
+  await Promise.all([
+    atomicWriteJson(paths.jobJsonPath, job),
+    atomicWriteJson(paths.inputsJsonPath, planningResult.normalizedInputDocuments),
+    atomicWriteJson(paths.tasksJsonPath, planningResult.tasks),
+    atomicWriteJson(paths.runtimeJsonPath, planningResult.runtime),
+    atomicWriteFile(paths.specMarkdownPath, planningResult.specMarkdown),
+    atomicWriteFile(paths.planMarkdownPath, planningResult.planMarkdown),
+    atomicWriteFile(paths.userChecksPath, "# User Checks\n\n"),
+    atomicWriteFile(paths.finalSummaryPath, "# Final Summary\n\nPending.\n"),
+    atomicWriteFile(paths.currentJobPath, `${jobId}
+`)
+  ]);
+  return {
+    snapshot: {
+      job,
+      tasks: planningResult.tasks,
+      runtime: planningResult.runtime
+    },
+    paths
+  };
+}
+async function loadJob(options) {
+  const cwd = options.cwd ?? process.cwd();
+  const stateDirectoryPath = resolveStateDirectoryPath({
+    workspacePath: options.workspacePath,
+    stateDirectoryPath: options.stateDirectoryPath,
+    cwd
+  });
+  const currentJobId = options.jobId ?? await loadCurrentJobId(stateDirectoryPath);
+  if (currentJobId === void 0) {
+    throw new Error(
+      `No job id was provided and no current job exists under ${stateDirectoryPath}.`
+    );
+  }
+  const paths = getJobPaths(currentJobId, stateDirectoryPath);
+  const [job, tasks, runtime] = await Promise.all([
+    readJsonFile(paths.jobJsonPath),
+    readJsonFile(paths.tasksJsonPath),
+    readJsonFile(paths.runtimeJsonPath)
+  ]);
+  if (job === void 0 || tasks === void 0 || runtime === void 0) {
+    throw new Error(`Job ${currentJobId} was not found under ${stateDirectoryPath}.`);
+  }
+  return { job, tasks, runtime };
+}
+async function saveJobSnapshot(snapshot) {
+  const paths = getJobPaths(snapshot.job.id, snapshot.job.stateDirectoryPath);
+  await Promise.all([
+    atomicWriteJson(paths.jobJsonPath, snapshot.job),
+    atomicWriteJson(paths.tasksJsonPath, snapshot.tasks),
+    atomicWriteJson(paths.runtimeJsonPath, snapshot.runtime)
+  ]);
+}
+async function cancelJob(options) {
+  const snapshot = await loadJob(options);
+  const updatedTasks = snapshot.tasks.tasks.map(
+    (task) => isTerminalTaskStatus(task.status) ? task : {
+      ...task,
+      status: "cancelled"
+    }
+  );
+  const nextSnapshot = {
+    job: {
+      ...snapshot.job,
+      status: "cancelled",
+      updatedAt: toIsoTimestamp()
+    },
+    tasks: {
+      ...snapshot.tasks,
+      tasks: updatedTasks,
+      phaseGateStatus: derivePhaseGateStatus(snapshot.tasks.phases, updatedTasks)
+    },
+    runtime: {
+      ...snapshot.runtime,
+      currentTaskId: null,
+      remainingTaskCount: 0,
+      nextAction: "none",
+      blockedReason: "Cancelled by user.",
+      lastValidationStatus: snapshot.runtime.lastValidationStatus
+    }
+  };
+  await saveJobSnapshot(nextSnapshot);
+  return nextSnapshot;
+}
+async function loadJobDetails(options) {
+  const snapshot = await loadJob(options);
+  const paths = getJobPaths(snapshot.job.id, snapshot.job.stateDirectoryPath);
+  const finalSummary = await readTextFile(paths.finalSummaryPath) ?? null;
+  const userChecks = await readTextFile(paths.userChecksPath) ?? null;
+  if (snapshot.runtime.lastRunId === null) {
+    return {
+      snapshot,
+      finalSummary,
+      userChecks,
+      latestAgentResult: null,
+      latestRunRecord: null,
+      latestValidation: null
+    };
+  }
+  const runPaths = getRunPaths(paths.runsDirectoryPath, snapshot.runtime.lastRunId);
+  const validationIndex = Number.parseInt(snapshot.runtime.lastRunId.replace("run-", ""), 10);
+  const validationPath = getValidationPath(paths.validationsDirectoryPath, validationIndex);
+  const [latestAgentResult, latestRunRecord, latestValidation] = await Promise.all([
+    readJsonFile(runPaths.resultPath),
+    readJsonFile(runPaths.runRecordPath),
+    readJsonFile(validationPath)
+  ]);
+  return {
+    snapshot,
+    finalSummary,
+    userChecks,
+    latestAgentResult: latestAgentResult ?? null,
+    latestRunRecord: latestRunRecord ?? null,
+    latestValidation: latestValidation ?? null
+  };
+}
+async function getJobOverview(options) {
+  const snapshot = await loadJob(options);
+  const paths = getJobPaths(snapshot.job.id, snapshot.job.stateDirectoryPath);
+  const runIds = (await listDirectoryEntries(paths.runsDirectoryPath)).sort();
+  return { snapshot, runIds };
+}
+async function loadCurrentJobId(stateDirectoryPath) {
+  const content = await readTextFile(getJobPaths("placeholder", stateDirectoryPath).currentJobPath);
+  return content?.trim() || void 0;
+}
+function buildJobId(title) {
+  const datePart = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10).replace(/-/g, "");
+  const randomPart = Math.random().toString(36).slice(2, 8);
+  return `job-${datePart}-${slugify(title)}-${randomPart}`;
+}
+function isTerminalTaskStatus(status) {
+  return isTaskTerminal(status);
+}
+
+// src/shared/utils/cli.ts
+function parseCliArgs(argv) {
+  const flags = /* @__PURE__ */ new Map();
+  const positionals = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith("--")) {
+      positionals.push(token);
+      continue;
+    }
+    const [name, inlineValue] = token.split("=", 2);
+    if (inlineValue !== void 0) {
+      appendFlagValue(flags, name, inlineValue);
+      continue;
+    }
+    const nextToken = argv[index + 1];
+    if (nextToken !== void 0 && !nextToken.startsWith("--")) {
+      appendFlagValue(flags, name, nextToken);
+      index += 1;
+      continue;
+    }
+    appendFlagValue(flags, name, "true");
+  }
+  return { flags, positionals };
+}
+function getSingleFlag(parsedArgs, flagName) {
+  return parsedArgs.flags.get(flagName)?.at(-1);
+}
+function getMultiFlag(parsedArgs, flagName) {
+  return parsedArgs.flags.get(flagName) ?? [];
+}
+function hasFlag(parsedArgs, flagName) {
+  return parsedArgs.flags.has(flagName);
+}
+function appendFlagValue(flags, flagName, value) {
+  const currentValues = flags.get(flagName) ?? [];
+  currentValues.push(value);
+  flags.set(flagName, currentValues);
+}
+
+// src/shared/utils/output.ts
+function printLine(message) {
+  process.stdout.write(`${message}
+`);
+}
+function printError(message) {
+  process.stderr.write(`${message}
+`);
+}
+function printJson(value) {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}
+`);
+}
+
+// src/cli/cancel/index.ts
+async function runCancelCommand(argv) {
+  const parsedArgs = parseCliArgs(argv);
+  const jobId = getSingleFlag(parsedArgs, "--job");
+  const workspacePath = getSingleFlag(parsedArgs, "--workspace");
+  const stateDirectoryPath = getSingleFlag(parsedArgs, "--state-dir");
+  const jsonMode = hasFlag(parsedArgs, "--json");
+  if (workspacePath === void 0 && stateDirectoryPath === void 0) {
+    printError("Either --workspace or --state-dir is required.");
+    return 1;
+  }
+  try {
+    const snapshot = await cancelJob({
+      jobId,
+      workspacePath,
+      stateDirectoryPath
+    });
+    if (jsonMode) {
+      printJson({
+        job_id: snapshot.job.id,
+        status: snapshot.job.status,
+        next_action: snapshot.runtime.nextAction
+      });
+      return 0;
+    }
+    printLine(`Cancelled job ${snapshot.job.id}`);
+    printLine(`Status: ${snapshot.job.status}`);
+    return 0;
+  } catch (error) {
+    printError(error instanceof Error ? error.message : "Failed to cancel job.");
+    return 1;
+  }
+}
+
+// src/cli/result/index.ts
+async function runResultCommand(argv) {
+  const parsedArgs = parseCliArgs(argv);
+  const jobId = getSingleFlag(parsedArgs, "--job");
+  const workspacePath = getSingleFlag(parsedArgs, "--workspace");
+  const stateDirectoryPath = getSingleFlag(parsedArgs, "--state-dir");
+  const jsonMode = hasFlag(parsedArgs, "--json");
+  if (workspacePath === void 0 && stateDirectoryPath === void 0) {
+    printError("Either --workspace or --state-dir is required.");
+    return 1;
+  }
+  try {
+    const details = await loadJobDetails({
+      jobId,
+      workspacePath,
+      stateDirectoryPath
+    });
+    if (jsonMode) {
+      printJson({
+        job_id: details.snapshot.job.id,
+        status: details.snapshot.job.status,
+        final_summary: details.finalSummary,
+        user_checks: details.userChecks,
+        latest_run_record: details.latestRunRecord,
+        latest_agent_result: details.latestAgentResult,
+        latest_validation: details.latestValidation
+      });
+      return 0;
+    }
+    printLine(`Job: ${details.snapshot.job.id}`);
+    printLine(`Status: ${details.snapshot.job.status}`);
+    printLine("");
+    printLine("Final Summary:");
+    printLine(details.finalSummary ?? "No final summary available.");
+    printLine("User Checks:");
+    printLine(details.userChecks ?? "No user checks available.");
+    if (details.latestRunRecord !== null) {
+      printLine("Latest Run:");
+      printLine(`Run: ${details.latestRunRecord.runId}`);
+      printLine(`Status: ${details.latestRunRecord.status}`);
+      printLine(`Summary: ${details.latestRunRecord.summary}`);
+    }
+    return 0;
+  } catch (error) {
+    printError(error instanceof Error ? error.message : "Failed to load job result.");
+    return 1;
+  }
+}
+
+// src/adapters/run.ts
+import { spawn } from "node:child_process";
+
+// src/adapters/prompts.ts
+function buildExecutionPrompt(context) {
+  const lines = [
+    "You are executing a single Ralph task in a fresh context.",
+    "Return only a JSON object that matches the required schema.",
+    "Do not wrap the JSON in markdown fences.",
+    "",
+    `Workspace: ${context.workspacePath}`,
+    `Task ID: ${context.taskId}`,
+    `Task Title: ${context.taskTitle}`,
+    "",
+    "Task Description:",
+    context.taskDescription,
+    "",
+    "Execution Requirements:",
+    "- Work only inside the provided workspace.",
+    "- Read referenced files directly from their paths before acting.",
+    "- Do not assume Ralph copied file or image contents into this prompt.",
+    "- If no changes are needed, explain why in the summary.",
+    "- `changed_files`, `artifacts`, `follow_up_tasks`, `user_checks`, `validation_hints`, and `blockers` must always be arrays.",
+    "- Use `blocked` only when progress cannot continue without an external unblocker.",
+    "- Use `partial` when you made progress but more work remains.",
+    "",
+    "Ralph Reference Files:",
+    `- Plan: ${context.planPath}`,
+    `- Job spec: ${context.specPath}`,
+    `- Input manifest: ${context.inputManifestPath}`,
+    "",
+    "Referenced Input Paths:",
+    ...context.inputDocuments.length === 0 ? ["- None."] : context.inputDocuments.map((document) => `- [${document.kind}] ${document.path}`),
+    "",
+    "Open the referenced files as needed and execute the task."
+  ];
+  return `${lines.join("\n")}
+`;
+}
+function buildResultJsonSchema() {
+  return {
+    type: "object",
+    additionalProperties: false,
+    required: [
+      "status",
+      "task_id",
+      "summary",
+      "changed_files",
+      "artifacts",
+      "follow_up_tasks",
+      "user_checks",
+      "validation_hints",
+      "blockers"
+    ],
+    properties: {
+      status: {
+        type: "string",
+        enum: ["completed", "partial", "blocked", "failed"]
+      },
+      task_id: {
+        type: "string"
+      },
+      summary: {
+        type: "string"
+      },
+      changed_files: {
+        type: "array",
+        items: { type: "string" }
+      },
+      artifacts: {
+        type: "array",
+        items: { type: "string" }
+      },
+      follow_up_tasks: {
+        type: "array",
+        items: { type: "string" }
+      },
+      user_checks: {
+        type: "array",
+        items: { type: "string" }
+      },
+      validation_hints: {
+        type: "array",
+        items: { type: "string" }
+      },
+      blockers: {
+        type: "array",
+        items: { type: "string" }
+      }
+    }
+  };
+}
+function buildOutputFileArgs(context) {
+  return ["-o", context.outputPath];
+}
+
+// src/adapters/run.ts
+var defaultAgentTimeoutMs = 15 * 60 * 1e3;
+var authRequiredPattern = /(auth(entication)? (required|failed)|not logged in|login required|please log in|please login|unauthorized|invalid api key|missing api key|expired token|sign in)/i;
+async function runAdapter(context) {
+  const adapter = getAdapterDefinition(context.agent);
+  try {
+    return await adapter.execute(context);
+  } catch (error) {
+    throw adapter.normalizeError(error);
+  }
+}
+function getAdapterDefinition(agent) {
+  switch (agent) {
+    case "codex":
+      return {
+        preparePrompt: buildExecutionPrompt,
+        execute: async (runContext) => executeAdapterProcess(
+          runContext,
+          createProcessSpec(
+            "codex",
+            [
+              "exec",
+              "--skip-git-repo-check",
+              "--dangerously-bypass-approvals-and-sandbox",
+              "-C",
+              runContext.workspacePath,
+              "--output-schema",
+              `${runContext.runDirectoryPath}/result.schema.json`,
+              ...buildOutputFileArgs(runContext),
+              runContext.promptText
+            ],
+            "file"
+          )
+        ),
+        normalizeError: normalizeAdapterError
+      };
+    case "claude-code":
+      return {
+        preparePrompt: buildExecutionPrompt,
+        execute: async (runContext) => executeAdapterProcess(
+          runContext,
+          createProcessSpec(
+            "claude",
+            [
+              "-p",
+              "--dangerously-skip-permissions",
+              "--output-format",
+              "json",
+              "--json-schema",
+              JSON.stringify(buildResultJsonSchema()),
+              runContext.promptText
+            ],
+            "stdout"
+          )
+        ),
+        normalizeError: normalizeAdapterError
+      };
+    case "custom-command":
+      return {
+        preparePrompt: buildExecutionPrompt,
+        execute: async (runContext) => {
+          const customCommand = process.env.RALPH_CUSTOM_AGENT_COMMAND;
+          if (customCommand === void 0 || customCommand.trim().length === 0) {
+            throw createAdapterFailure(
+              "execution_failed",
+              "custom-command adapter requires RALPH_CUSTOM_AGENT_COMMAND."
+            );
+          }
+          return executeAdapterProcess(
+            runContext,
+            createProcessSpec("sh", ["-lc", customCommand], "file")
+          );
+        },
+        normalizeError: normalizeAdapterError
+      };
+  }
+}
+function parseAgentResult(rawResultText) {
+  if (rawResultText === null || rawResultText.trim().length === 0) {
+    throw createAdapterFailure("malformed_result", "Agent did not return a result payload.");
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(rawResultText);
+  } catch {
+    throw createAdapterFailure("malformed_result", "Agent returned invalid JSON.");
+  }
+  if (isClaudeWrappedResult(parsed)) {
+    return parsed.structured_output;
+  }
+  if (!isAgentResult(parsed)) {
+    throw createAdapterFailure("malformed_result", "Agent result did not match the expected contract.");
+  }
+  return parsed;
+}
+async function persistRunLogs(context, result) {
+  await Promise.all([
+    atomicWriteFile(`${context.runDirectoryPath}/stdout.log`, `${result.stdout}`),
+    atomicWriteFile(`${context.runDirectoryPath}/stderr.log`, `${result.stderr}`)
+  ]);
+}
+function createAdapterFailure(code, message, options) {
+  return {
+    code,
+    message,
+    stdout: options?.stdout ?? "",
+    stderr: options?.stderr ?? "",
+    exitCode: options?.exitCode ?? null,
+    signal: options?.signal ?? null
+  };
+}
+async function executeAdapterProcess(context, processSpec) {
+  await atomicWriteJson(`${context.runDirectoryPath}/result.schema.json`, buildResultJsonSchema());
+  return new Promise((resolve3, reject) => {
+    const child = spawn(processSpec.command, processSpec.args, {
+      cwd: context.workspacePath,
+      env: {
+        ...process.env,
+        RALPH_WORKSPACE_PATH: context.workspacePath,
+        RALPH_PROMPT_PATH: context.promptPath,
+        RALPH_OUTPUT_PATH: context.outputPath,
+        RALPH_RUN_DIRECTORY_PATH: context.runDirectoryPath
+      }
+    });
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    let timeoutId;
+    const finishReject = (error) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      if (timeoutId !== void 0) {
+        clearTimeout(timeoutId);
+      }
+      reject(error);
+    };
+    const finishResolve = async (exitCode, signal) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      if (timeoutId !== void 0) {
+        clearTimeout(timeoutId);
+      }
+      const rawResultText = processSpec.outputMode === "stdout" ? stdout.trim() || null : await readRawResult(context.outputPath);
+      resolve3({
+        stdout,
+        stderr,
+        exitCode,
+        signal,
+        rawResultText
+      });
+    };
+    child.stdout?.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on("error", (error) => {
+      const spawnError = error;
+      finishReject({
+        kind: "spawn",
+        message: spawnError.message,
+        stdout,
+        stderr,
+        exitCode: null,
+        signal: null,
+        code: spawnError.code === "ENOENT" ? "cli_missing" : "execution_failed"
+      });
+    });
+    child.on("close", (exitCode, signal) => {
+      if (exitCode !== 0) {
+        finishReject({
+          kind: "process_exit",
+          message: "Agent process exited with a non-zero status.",
+          stdout,
+          stderr,
+          exitCode,
+          signal
+        });
+        return;
+      }
+      void finishResolve(exitCode, signal).catch((error) => finishReject(error));
+    });
+    timeoutId = setTimeout(() => {
+      child.kill("SIGTERM");
+      finishReject({
+        kind: "timeout",
+        message: `Agent process timed out after ${String(processSpec.timeoutMs)}ms.`,
+        stdout,
+        stderr,
+        exitCode: null,
+        signal: "SIGTERM"
+      });
+    }, processSpec.timeoutMs);
+  });
+}
+function createProcessSpec(command, args, outputMode) {
+  return {
+    command,
+    args,
+    outputMode,
+    timeoutMs: getAgentTimeoutMs()
+  };
+}
+function normalizeAdapterError(error) {
+  if (isAdapterExecutionFailure(error)) {
+    return error;
+  }
+  if (isAdapterProcessFailure(error)) {
+    if (error.kind === "timeout") {
+      return createAdapterFailure("timeout", error.message ?? "Agent process timed out.", error);
+    }
+    if (error.kind === "spawn" && error.code === "cli_missing") {
+      return createAdapterFailure("cli_missing", error.message ?? "Agent CLI is missing.", error);
+    }
+    if (looksLikeAuthRequired(error.stdout ?? "", error.stderr ?? "", error.message ?? "")) {
+      return createAdapterFailure(
+        "auth_required",
+        error.message ?? "Agent requires authentication before it can run.",
+        error
+      );
+    }
+    return createAdapterFailure(
+      error.code === "cli_missing" ? "cli_missing" : "execution_failed",
+      error.message ?? "Agent execution failed.",
+      error
+    );
+  }
+  if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT") {
+    return createAdapterFailure("cli_missing", error.message);
+  }
+  return createAdapterFailure(
+    "execution_failed",
+    error instanceof Error ? error.message : "Execution failed."
+  );
+}
+function isAgentResult(value) {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const candidate = value;
+  const status = candidate.status;
+  return typeof candidate.task_id === "string" && typeof candidate.summary === "string" && typeof status === "string" && ["completed", "partial", "blocked", "failed"].includes(status) && (status !== "blocked" || isStringArray(candidate.blockers) && candidate.blockers.length > 0) && isStringArray(candidate.changed_files) && isStringArray(candidate.artifacts) && isStringArray(candidate.follow_up_tasks) && isStringArray(candidate.user_checks) && isStringArray(candidate.validation_hints) && isStringArray(candidate.blockers);
+}
+function isClaudeWrappedResult(value) {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const candidate = value;
+  return isAgentResult(candidate.structured_output);
+}
+function isStringArray(value) {
+  return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+function isAdapterExecutionFailure(error) {
+  return typeof error === "object" && error !== null && "code" in error && "message" in error && "stdout" in error && "stderr" in error;
+}
+function isAdapterProcessFailure(error) {
+  return typeof error === "object" && error !== null && "kind" in error;
+}
+function looksLikeAuthRequired(stdout, stderr, message) {
+  return authRequiredPattern.test(`${stdout}
+${stderr}
+${message}`);
+}
+function getAgentTimeoutMs() {
+  const raw = process.env.RALPH_AGENT_TIMEOUT_MS;
+  if (raw === void 0) {
+    return defaultAgentTimeoutMs;
+  }
+  const parsed = Number.parseInt(raw, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : defaultAgentTimeoutMs;
+}
+async function readRawResult(outputPath) {
+  try {
+    const { readFile: readFile2 } = await import("node:fs/promises");
+    return await readFile2(outputPath, "utf8");
+  } catch (error) {
+    if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+}
+
+// src/adapters/index.ts
+var adapterFeature = {
+  supported: ["codex", "claude-code", "custom-command"]
+};
+function isSupportedAgent(value) {
+  return adapterFeature.supported.includes(value);
+}
+
+// src/reporting/index.ts
+async function updateUserChecksReport(userChecksPath, userChecks) {
+  const existingContent = await readTextFile(userChecksPath) ?? "# User Checks\n\n";
+  const existingChecks = existingContent.split("\n").map((line) => line.trim()).filter((line) => line.startsWith("- ")).map((line) => line.slice(2));
+  const mergedChecks = Array.from(/* @__PURE__ */ new Set([...existingChecks, ...userChecks]));
+  const lines = ["# User Checks", ""];
+  if (mergedChecks.length === 0) {
+    lines.push("None.");
+  } else {
+    lines.push(...mergedChecks.map((entry) => `- ${entry}`));
+  }
+  lines.push("");
+  await atomicWriteFile(userChecksPath, `${lines.join("\n")}`);
+}
+async function updateFinalSummaryReport(options) {
+  const runIds = (await listDirectoryEntries(options.runsDirectoryPath)).sort();
+  const runRecords = (await Promise.all(
+    runIds.map(
+      async (runId) => readJsonFile(`${options.runsDirectoryPath}/${runId}/run-record.json`)
+    )
+  )).filter((record) => record !== void 0);
+  if (runRecords.length === 0) {
+    await atomicWriteFile(
+      options.finalSummaryPath,
+      `# Final Summary
+
+Title: ${options.title}
+
+Status: ${options.jobStatus}
+
+Pending.
+`
+    );
+    return;
+  }
+  const latestRun = runRecords.at(-1);
+  const lines = [
+    "# Final Summary",
+    "",
+    `Title: ${options.title}`,
+    "",
+    `Status: ${options.jobStatus}`,
+    `Latest run: ${latestRun.runId}`,
+    `Latest run status: ${latestRun.status}`,
+    "",
+    "Run history:",
+    ""
+  ];
+  for (const runRecord of runRecords) {
+    lines.push(`## ${runRecord.runId} ${runRecord.taskId}`, "");
+    lines.push(`- Status: ${runRecord.status}`);
+    lines.push(`- Summary: ${runRecord.summary}`);
+    if (runRecord.changedFiles.length > 0) {
+      lines.push("- Changed files:");
+      lines.push(...runRecord.changedFiles.map((value) => `  - ${value}`));
+    }
+    if (runRecord.followUpTasks.length > 0) {
+      lines.push("- Follow-up tasks:");
+      lines.push(...runRecord.followUpTasks.map((value) => `  - ${value}`));
+    }
+    if (runRecord.blockers.length > 0) {
+      lines.push("- Blockers:");
+      lines.push(...runRecord.blockers.map((value) => `  - ${value}`));
+    }
+    lines.push("");
+  }
+  await atomicWriteFile(options.finalSummaryPath, `${lines.join("\n")}
+`);
+}
+
+// src/validation/index.ts
+import { spawn as spawn2 } from "node:child_process";
+function applyValidationOutcome(agentResult, validationRecord) {
+  if (validationRecord.status !== "failed") {
+    return agentResult;
+  }
+  return {
+    ...agentResult,
+    status: "failed",
+    blockers: [...agentResult.blockers, validationRecord.summary]
+  };
+}
+async function runValidation(options) {
+  const commandResults = await Promise.all(
+    options.commands.map((command) => executeValidationCommand(command, options.workspacePath))
+  );
+  const hasFailedCommand = commandResults.some((commandResult) => commandResult.status === "failed");
+  const record = {
+    id: `validation-${String(options.validationIndex).padStart(3, "0")}`,
+    status: hasFailedCommand ? "failed" : "passed",
+    hints: options.validationHints,
+    checkedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    summary: commandResults.length === 0 ? options.validationHints.length > 0 ? "Validation hints recorded. No executable validations configured yet." : "No executable validations configured. Passing by default." : hasFailedCommand ? "One or more validation commands failed." : "All validation commands passed.",
+    commandResults
+  };
+  await atomicWriteJson(getValidationPath(options.validationsDirectoryPath, options.validationIndex), record);
+  return record;
+}
+async function executeValidationCommand(command, workspacePath) {
+  return new Promise((resolve3, reject) => {
+    const child = spawn2("sh", ["-lc", command], {
+      cwd: workspacePath,
+      env: process.env
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on("error", (error) => {
+      reject(error);
+    });
+    child.on("close", (exitCode, signal) => {
+      resolve3({
+        command,
+        exitCode,
+        signal,
+        stdout,
+        stderr,
+        status: exitCode === 0 ? "passed" : "failed"
+      });
+    });
+  });
+}
+
+// src/execution/index.ts
+async function resumeJob(options) {
+  const maxIterations = options.maxIterations ?? Number.POSITIVE_INFINITY;
+  let snapshot = await loadJob(options);
+  const runRecords = [];
+  let lastRunDirectoryPath = "";
+  if (isTerminalJobStatus(snapshot.job.status)) {
+    throw new Error(`Job ${snapshot.job.id} is already ${snapshot.job.status}.`);
+  }
+  while (runRecords.length < maxIterations) {
+    const runnableTask = selectRunnableTask(snapshot);
+    if (runnableTask === void 0) {
+      snapshot = await blockJobOnNoRunnableTask(snapshot);
+      break;
+    }
+    const iterationResult = await executeIteration(snapshot, runnableTask);
+    snapshot = iterationResult.snapshot;
+    runRecords.push(iterationResult.runRecord);
+    lastRunDirectoryPath = iterationResult.runDirectoryPath;
+    if (snapshot.runtime.nextAction !== "resume") {
+      break;
+    }
+  }
+  if (runRecords.length === 0 && snapshot.job.status !== "blocked") {
+    throw new Error(`Job ${snapshot.job.id} has no runnable task.`);
+  }
+  return {
+    snapshot,
+    runRecord: runRecords.at(-1) ?? null,
+    runRecords,
+    runDirectoryPath: lastRunDirectoryPath || null,
+    iterations: runRecords.length
+  };
+}
+async function executeIteration(snapshot, runnableTask) {
+  const paths = getJobPaths(snapshot.job.id, snapshot.job.stateDirectoryPath);
+  const runId = getNextRunId(snapshot.runtime.lastRunId);
+  const runPaths = getRunPaths(paths.runsDirectoryPath, runId);
+  const adapter = getAdapterDefinition(snapshot.job.requestedAgent);
+  const promptText = adapter.preparePrompt({
+    title: snapshot.job.title,
+    taskId: runnableTask.id,
+    taskTitle: runnableTask.title,
+    taskDescription: runnableTask.description,
+    workspacePath: snapshot.job.workspacePath,
+    specPath: paths.specMarkdownPath,
+    planPath: paths.planMarkdownPath,
+    inputManifestPath: paths.inputsJsonPath,
+    inputDocuments: snapshot.job.inputDocuments
+  });
+  await ensureRunDirectory(runPaths.runDirectoryPath);
+  const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const runningSnapshot = buildRunningSnapshot(snapshot, runnableTask, runId);
+  const runningRunRecord = buildRunningRunRecord({
+    runId,
+    taskId: runnableTask.id,
+    agent: snapshot.job.requestedAgent,
+    startedAt
+  });
+  await Promise.all([
+    atomicWriteFile(runPaths.promptPath, promptText),
+    atomicWriteFile(runPaths.stdoutLogPath, ""),
+    atomicWriteFile(runPaths.stderrLogPath, ""),
+    atomicWriteJson(runPaths.runRecordPath, runningRunRecord),
+    saveJobSnapshot(runningSnapshot)
+  ]);
+  try {
+    const adapterResult = await runAdapter({
+      agent: runningSnapshot.job.requestedAgent,
+      workspacePath: runningSnapshot.job.workspacePath,
+      promptPath: runPaths.promptPath,
+      promptText,
+      outputPath: runPaths.outputPath,
+      runDirectoryPath: runPaths.runDirectoryPath
+    });
+    await persistRunLogs(buildRunContext(runningSnapshot, runPaths, promptText), adapterResult);
+    const agentResult = parseAgentResult(adapterResult.rawResultText);
+    if (agentResult.task_id !== runnableTask.id) {
+      throw {
+        code: "malformed_result",
+        message: `Agent returned task_id ${agentResult.task_id}, expected ${runnableTask.id}.`,
+        stdout: adapterResult.stdout,
+        stderr: adapterResult.stderr,
+        exitCode: adapterResult.exitCode,
+        signal: adapterResult.signal
+      };
+    }
+    const validationRecord = await runValidation({
+      jobId: runningSnapshot.job.id,
+      taskId: runnableTask.id,
+      validationHints: agentResult.validation_hints,
+      workspacePath: runningSnapshot.job.workspacePath,
+      commands: runningSnapshot.job.validationProfile.commands,
+      validationsDirectoryPath: paths.validationsDirectoryPath,
+      validationIndex: toRunNumber(runId)
+    });
+    const normalizedResult = applyValidationOutcome(agentResult, validationRecord);
+    const runRecord = buildRunRecord({
+      runId,
+      taskId: runnableTask.id,
+      agent: runningSnapshot.job.requestedAgent,
+      startedAt,
+      finishedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      result: normalizedResult,
+      exitCode: adapterResult.exitCode,
+      signal: adapterResult.signal
+    });
+    await Promise.all([
+      atomicWriteJson(runPaths.resultPath, normalizedResult),
+      atomicWriteJson(runPaths.runRecordPath, runRecord)
+    ]);
+    const nextSnapshot = applyTaskOutcome({
+      snapshot: runningSnapshot,
+      task: runnableTask,
+      runId,
+      runRecord,
+      result: normalizedResult,
+      validationStatus: validationRecord.status
+    });
+    await saveJobSnapshot(nextSnapshot);
+    await Promise.all([
+      updateUserChecksReport(paths.userChecksPath, collectUserChecks(nextSnapshot, runRecord)),
+      updateFinalSummaryReport({
+        finalSummaryPath: paths.finalSummaryPath,
+        title: runningSnapshot.job.title,
+        jobStatus: nextSnapshot.job.status,
+        runsDirectoryPath: paths.runsDirectoryPath
+      })
+    ]);
+    return {
+      snapshot: nextSnapshot,
+      runRecord,
+      runDirectoryPath: runPaths.runDirectoryPath
+    };
+  } catch (error) {
+    const failure = normalizeExecutionFailure(error);
+    await persistRunLogs(buildRunContext(runningSnapshot, runPaths, promptText), failure);
+    const failedResult = {
+      status: "failed",
+      task_id: runnableTask.id,
+      summary: failure.message,
+      changed_files: [],
+      artifacts: [],
+      follow_up_tasks: [],
+      user_checks: [],
+      validation_hints: [],
+      blockers: failure.code === "cli_missing" ? [failure.message] : []
+    };
+    const runRecord = buildRunRecord({
+      runId,
+      taskId: runnableTask.id,
+      agent: runningSnapshot.job.requestedAgent,
+      startedAt,
+      finishedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      result: failedResult,
+      exitCode: failure.exitCode,
+      signal: failure.signal,
+      errorCode: failure.code
+    });
+    await Promise.all([
+      atomicWriteJson(runPaths.resultPath, failedResult),
+      atomicWriteJson(runPaths.runRecordPath, runRecord)
+    ]);
+    const nextSnapshot = applyTaskOutcome({
+      snapshot: runningSnapshot,
+      task: runnableTask,
+      runId,
+      runRecord,
+      result: failedResult,
+      validationStatus: "failed",
+      failureCode: failure.code
+    });
+    await saveJobSnapshot(nextSnapshot);
+    await updateFinalSummaryReport({
+      finalSummaryPath: paths.finalSummaryPath,
+      title: runningSnapshot.job.title,
+      jobStatus: nextSnapshot.job.status,
+      runsDirectoryPath: paths.runsDirectoryPath
+    });
+    return {
+      snapshot: nextSnapshot,
+      runRecord,
+      runDirectoryPath: runPaths.runDirectoryPath
+    };
+  }
+}
+function buildRunContext(snapshot, runPaths, promptText) {
+  return {
+    agent: snapshot.job.requestedAgent,
+    workspacePath: snapshot.job.workspacePath,
+    promptPath: runPaths.promptPath,
+    promptText,
+    outputPath: runPaths.outputPath,
+    runDirectoryPath: runPaths.runDirectoryPath
+  };
+}
+function applyTaskOutcome(options) {
+  const { snapshot, task, runId, runRecord, result } = options;
+  const nextRetryCounts = {
+    ...snapshot.tasks.retryCounts
+  };
+  const nextEvidenceLinks = {
+    ...snapshot.tasks.evidenceLinks,
+    [task.id]: [...snapshot.tasks.evidenceLinks[task.id] ?? [], runId]
+  };
+  const nextDependencies = Object.fromEntries(
+    Object.entries(snapshot.tasks.dependencies).map(([key, value]) => [key, [...value]])
+  );
+  const nextTasks = snapshot.tasks.tasks.map(
+    (entry) => entry.id === task.id ? { ...entry } : entry
+  );
+  const targetTask = nextTasks.find((entry) => entry.id === task.id);
+  const canRetry = nextRetryCounts[task.id] < snapshot.job.retryPolicy.maxRetriesPerTask;
+  if (result.status === "completed") {
+    targetTask.status = "completed";
+  } else if (result.status === "partial") {
+    if (result.follow_up_tasks.length > 0) {
+      targetTask.status = "completed";
+      appendFollowUpTasks({
+        dependencies: nextDependencies,
+        nextTasks,
+        nextRetryCounts,
+        nextEvidenceLinks,
+        sourceTask: task,
+        followUpTasks: result.follow_up_tasks
+      });
+    } else if (canRetry) {
+      targetTask.status = "pending";
+      nextRetryCounts[task.id] += 1;
+    } else {
+      targetTask.status = "blocked";
+      result.blockers = [
+        ...result.blockers,
+        "Partial result exhausted retry budget without follow-up tasks."
+      ];
+    }
+  } else if (result.status === "failed") {
+    if (canRetry) {
+      targetTask.status = "pending";
+      nextRetryCounts[task.id] += 1;
+    } else {
+      targetTask.status = options.failureCode === "malformed_result" ? "blocked" : "failed";
+    }
+  } else if (result.status === "blocked") {
+    targetTask.status = "blocked";
+  }
+  if (result.status === "completed" && result.follow_up_tasks.length > 0) {
+    appendFollowUpTasks({
+      dependencies: nextDependencies,
+      nextTasks,
+      nextRetryCounts,
+      nextEvidenceLinks,
+      sourceTask: task,
+      followUpTasks: result.follow_up_tasks
+    });
+  }
+  const phaseGateStatus = derivePhaseGateStatus(snapshot.tasks.phases, nextTasks);
+  const remainingTaskCount = countRemainingTasks(nextTasks);
+  const blockedReason = nextTasks.some((entry) => entry.status === "blocked") ? result.blockers.join("; ") || runRecord.summary : null;
+  const hasFailedTask = nextTasks.some((entry) => entry.status === "failed");
+  const allRequiredWorkCompleted = nextTasks.length > 0 && nextTasks.every((entry) => entry.status === "completed");
+  const allPhaseGatesPassed = Object.values(phaseGateStatus).length > 0 && Object.values(phaseGateStatus).every((status) => status === "passed");
+  const nextAction = blockedReason !== null ? "blocked" : remainingTaskCount > 0 ? "resume" : "none";
+  const nextJobStatus = blockedReason !== null ? "blocked" : hasFailedTask ? "failed" : remainingTaskCount === 0 && allRequiredWorkCompleted && allPhaseGatesPassed ? "completed" : "running";
+  const currentTaskId = nextPendingTaskId(snapshot.tasks.phases, nextTasks, nextDependencies);
+  const currentPhaseId = currentTaskId === null ? snapshot.tasks.phases.find((phase) => phaseGateStatus[phase.id] !== "passed")?.id ?? null : nextTasks.find((entry) => entry.id === currentTaskId)?.phaseId ?? snapshot.runtime.currentPhaseId;
+  return {
+    job: {
+      ...snapshot.job,
+      status: nextJobStatus,
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    },
+    tasks: {
+      ...snapshot.tasks,
+      tasks: nextTasks,
+      dependencies: nextDependencies,
+      retryCounts: nextRetryCounts,
+      evidenceLinks: nextEvidenceLinks,
+      phaseGateStatus
+    },
+    runtime: {
+      ...snapshot.runtime,
+      currentPhaseId,
+      currentTaskId,
+      remainingTaskCount,
+      lastRunId: runId,
+      nextAction,
+      blockedReason,
+      lastValidationStatus: options.validationStatus
+    }
+  };
+}
+function appendFollowUpTasks(options) {
+  const nextTaskNumber = options.nextTasks.length + 1;
+  options.followUpTasks.forEach((followUpTask, index) => {
+    const taskId = `TASK-${String(nextTaskNumber + index).padStart(3, "0")}`;
+    options.nextTasks.push({
+      id: taskId,
+      phaseId: options.sourceTask.phaseId,
+      title: followUpTask,
+      description: followUpTask,
+      status: "pending",
+      sourceTaskId: options.sourceTask.id
+    });
+    options.dependencies[taskId] = [options.sourceTask.id];
+    options.nextRetryCounts[taskId] = 0;
+    options.nextEvidenceLinks[taskId] = [];
+  });
+}
+function buildRunRecord(options) {
+  return {
+    runId: options.runId,
+    taskId: options.taskId,
+    agent: options.agent,
+    startedAt: options.startedAt,
+    finishedAt: options.finishedAt,
+    status: options.result.status,
+    summary: options.result.summary,
+    changedFiles: options.result.changed_files,
+    blockers: options.result.blockers,
+    userChecks: options.result.user_checks,
+    validationHints: options.result.validation_hints,
+    artifacts: options.result.artifacts,
+    followUpTasks: options.result.follow_up_tasks,
+    exitCode: options.exitCode,
+    signal: options.signal,
+    errorCode: options.errorCode
+  };
+}
+function buildRunningRunRecord(options) {
+  return {
+    runId: options.runId,
+    taskId: options.taskId,
+    agent: options.agent,
+    startedAt: options.startedAt,
+    finishedAt: null,
+    status: "running",
+    summary: `Started ${options.taskId}.`,
+    changedFiles: [],
+    blockers: [],
+    userChecks: [],
+    validationHints: [],
+    artifacts: [],
+    followUpTasks: [],
+    exitCode: null,
+    signal: null
+  };
+}
+function isTerminalJobStatus(status) {
+  return isJobTerminal(status);
+}
+function buildRunningSnapshot(snapshot, task, runId) {
+  const nextTasks = snapshot.tasks.tasks.map(
+    (entry) => entry.id === task.id ? {
+      ...entry,
+      status: "running"
+    } : entry
+  );
+  return {
+    job: {
+      ...snapshot.job,
+      status: "running",
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    },
+    tasks: {
+      ...snapshot.tasks,
+      tasks: nextTasks
+    },
+    runtime: {
+      ...snapshot.runtime,
+      currentPhaseId: task.phaseId,
+      currentTaskId: task.id,
+      remainingTaskCount: countRemainingTasks(nextTasks),
+      lastRunId: runId,
+      nextAction: "resume",
+      blockedReason: null,
+      lastValidationStatus: "pending"
+    }
+  };
+}
+function collectUserChecks(snapshot, runRecord) {
+  return runRecord.userChecks;
+}
+function toRunNumber(runId) {
+  return Number.parseInt(runId.replace("run-", ""), 10);
+}
+function normalizeExecutionFailure(error) {
+  if (typeof error === "object" && error !== null && "code" in error && "message" in error && "stdout" in error && "stderr" in error) {
+    return error;
+  }
+  return {
+    code: "execution_failed",
+    message: error instanceof Error ? error.message : "Execution failed.",
+    stdout: "",
+    stderr: "",
+    exitCode: null,
+    signal: null
+  };
+}
+async function blockJobOnNoRunnableTask(snapshot) {
+  const reason = buildNoRunnableTaskReason(snapshot);
+  const paths = getJobPaths(snapshot.job.id, snapshot.job.stateDirectoryPath);
+  const nextSnapshot = {
+    job: {
+      ...snapshot.job,
+      status: "blocked",
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    },
+    tasks: {
+      ...snapshot.tasks,
+      phaseGateStatus: derivePhaseGateStatus(snapshot.tasks.phases, snapshot.tasks.tasks)
+    },
+    runtime: {
+      ...buildBlockedRuntime(snapshot, reason),
+      lastValidationStatus: snapshot.runtime.lastValidationStatus
+    }
+  };
+  await saveJobSnapshot(nextSnapshot);
+  await updateFinalSummaryReport({
+    finalSummaryPath: paths.finalSummaryPath,
+    title: snapshot.job.title,
+    jobStatus: nextSnapshot.job.status,
+    runsDirectoryPath: paths.runsDirectoryPath
+  });
+  return nextSnapshot;
+}
+
+// src/cli/resume/index.ts
+async function runResumeCommand(argv) {
+  const parsedArgs = parseCliArgs(argv);
+  const jobId = getSingleFlag(parsedArgs, "--job");
+  const workspacePath = getSingleFlag(parsedArgs, "--workspace");
+  const stateDirectoryPath = getSingleFlag(parsedArgs, "--state-dir");
+  const maxIterationsRaw = getSingleFlag(parsedArgs, "--max-iterations");
+  const jsonMode = hasFlag(parsedArgs, "--json");
+  if (workspacePath === void 0 && stateDirectoryPath === void 0) {
+    printError("Either --workspace or --state-dir is required.");
+    return 1;
+  }
+  try {
+    const parsedMaxIterations = maxIterationsRaw === void 0 ? void 0 : Number.parseInt(maxIterationsRaw, 10);
+    const invalidMaxIterations = parsedMaxIterations === void 0 || !Number.isFinite(parsedMaxIterations) || parsedMaxIterations <= 0;
+    if (maxIterationsRaw !== void 0 && invalidMaxIterations) {
+      printError("`--max-iterations` must be a positive integer.");
+      return 1;
+    }
+    const result = await resumeJob({
+      jobId,
+      workspacePath,
+      stateDirectoryPath,
+      maxIterations: parsedMaxIterations
+    });
+    if (jsonMode) {
+      printJson({
+        job_id: result.snapshot.job.id,
+        job_status: result.snapshot.job.status,
+        run_id: result.runRecord?.runId ?? null,
+        run_status: result.runRecord?.status ?? null,
+        summary: result.runRecord?.summary ?? result.snapshot.runtime.blockedReason,
+        run_directory_path: result.runDirectoryPath,
+        iterations: result.iterations,
+        next_action: result.snapshot.runtime.nextAction,
+        blocked_reason: result.snapshot.runtime.blockedReason
+      });
+      return 0;
+    }
+    printLine(`Job: ${result.snapshot.job.id}`);
+    printLine(`Run: ${result.runRecord?.runId ?? "-"}`);
+    printLine(`Run status: ${result.runRecord?.status ?? "-"}`);
+    printLine(`Job status: ${result.snapshot.job.status}`);
+    printLine(`Summary: ${result.runRecord?.summary ?? result.snapshot.runtime.blockedReason ?? "-"}`);
+    printLine(`Run dir: ${result.runDirectoryPath ?? "-"}`);
+    printLine(`Iterations: ${String(result.iterations)}`);
+    printLine(`Next action: ${result.snapshot.runtime.nextAction}`);
+    return 0;
+  } catch (error) {
+    printError(error instanceof Error ? error.message : "Failed to resume job.");
+    return 1;
+  }
+}
+
+// src/cli/start/index.ts
+async function runStartCommand(argv) {
+  const parsedArgs = parseCliArgs(argv);
+  const title = getSingleFlag(parsedArgs, "--title");
+  const agent = getSingleFlag(parsedArgs, "--agent");
+  const workspacePath = getSingleFlag(parsedArgs, "--workspace");
+  const stateDirectoryPath = getSingleFlag(parsedArgs, "--state-dir");
+  const inputDocuments = getMultiFlag(parsedArgs, "--input");
+  const validateCommands = getMultiFlag(parsedArgs, "--validate-cmd");
+  const maxRetriesPerTaskRaw = getSingleFlag(parsedArgs, "--max-retries");
+  const jsonMode = hasFlag(parsedArgs, "--json");
+  if (title === void 0) {
+    printError("Missing required option: --title");
+    return 1;
+  }
+  if (agent === void 0) {
+    printError("Missing required option: --agent");
+    return 1;
+  }
+  if (workspacePath === void 0) {
+    printError("Missing required option: --workspace");
+    return 1;
+  }
+  if (!isSupportedAgent(agent)) {
+    printError(
+      `Unsupported agent: ${agent}. Supported agents: ${adapterFeature.supported.join(", ")}`
+    );
+    return 1;
+  }
+  try {
+    const parsedMaxRetriesPerTask = maxRetriesPerTaskRaw === void 0 ? void 0 : Number.parseInt(maxRetriesPerTaskRaw, 10);
+    const invalidMaxRetries = parsedMaxRetriesPerTask === void 0 || !Number.isFinite(parsedMaxRetriesPerTask) || parsedMaxRetriesPerTask < 0;
+    if (maxRetriesPerTaskRaw !== void 0 && invalidMaxRetries) {
+      printError("`--max-retries` must be a non-negative integer.");
+      return 1;
+    }
+    const { snapshot, paths } = await createJob({
+      title,
+      agent,
+      workspacePath,
+      stateDirectoryPath,
+      inputDocuments,
+      validateCommands,
+      maxRetriesPerTask: parsedMaxRetriesPerTask
+    });
+    if (jsonMode) {
+      printJson({
+        job_id: snapshot.job.id,
+        status: snapshot.job.status,
+        workspace_path: snapshot.job.workspacePath,
+        state_directory_path: snapshot.job.stateDirectoryPath,
+        validation_commands: snapshot.job.validationProfile.commands,
+        max_retries_per_task: snapshot.job.retryPolicy.maxRetriesPerTask,
+        next_action: snapshot.runtime.nextAction,
+        current_task_id: snapshot.runtime.currentTaskId
+      });
+      return 0;
+    }
+    printLine(`Started job ${snapshot.job.id}`);
+    printLine(`Status: ${snapshot.job.status}`);
+    printLine(`Workspace: ${snapshot.job.workspacePath}`);
+    printLine(`State dir: ${snapshot.job.stateDirectoryPath}`);
+    printLine(`Job dir: ${paths.jobDirectoryPath}`);
+    if (snapshot.job.inputDocuments.length > 0) {
+      printLine(`Inputs: ${snapshot.job.inputDocuments.map((entry) => entry.path).join(", ")}`);
+    }
+    if (snapshot.job.validationProfile.commands.length > 0) {
+      printLine(`Validation commands: ${snapshot.job.validationProfile.commands.join(" | ")}`);
+    }
+    printLine(`Max retries per task: ${String(snapshot.job.retryPolicy.maxRetriesPerTask)}`);
+    printLine("Next: `ralph status` or `ralph resume`");
+    return 0;
+  } catch (error) {
+    printError(error instanceof Error ? error.message : "Failed to start job.");
+    return 1;
+  }
+}
+
+// src/cli/status/index.ts
+async function runStatusCommand(argv) {
+  const parsedArgs = parseCliArgs(argv);
+  const jobId = getSingleFlag(parsedArgs, "--job");
+  const workspacePath = getSingleFlag(parsedArgs, "--workspace");
+  const stateDirectoryPath = getSingleFlag(parsedArgs, "--state-dir");
+  const jsonMode = hasFlag(parsedArgs, "--json");
+  if (workspacePath === void 0 && stateDirectoryPath === void 0) {
+    printError("Either --workspace or --state-dir is required.");
+    return 1;
+  }
+  try {
+    const { snapshot, runIds } = await getJobOverview({
+      jobId,
+      workspacePath,
+      stateDirectoryPath
+    });
+    if (jsonMode) {
+      printJson({
+        job_id: snapshot.job.id,
+        title: snapshot.job.title,
+        status: snapshot.job.status,
+        agent: snapshot.job.requestedAgent,
+        workspace_path: snapshot.job.workspacePath,
+        state_directory_path: snapshot.job.stateDirectoryPath,
+        current_phase_id: snapshot.runtime.currentPhaseId,
+        current_task_id: snapshot.runtime.currentTaskId,
+        remaining_task_count: snapshot.runtime.remainingTaskCount,
+        next_action: snapshot.runtime.nextAction,
+        blocked_reason: snapshot.runtime.blockedReason,
+        last_validation_status: snapshot.runtime.lastValidationStatus,
+        max_retries_per_task: snapshot.job.retryPolicy.maxRetriesPerTask,
+        retry_counts: snapshot.tasks.retryCounts,
+        last_run_id: snapshot.runtime.lastRunId,
+        run_ids: runIds
+      });
+      return 0;
+    }
+    printLine(`Job: ${snapshot.job.id}`);
+    printLine(`Title: ${snapshot.job.title}`);
+    printLine(`Status: ${snapshot.job.status}`);
+    printLine(`Agent: ${snapshot.job.requestedAgent}`);
+    printLine(`Workspace: ${snapshot.job.workspacePath}`);
+    printLine(`State dir: ${snapshot.job.stateDirectoryPath}`);
+    printLine(`Current phase: ${snapshot.runtime.currentPhaseId ?? "-"}`);
+    printLine(`Current task: ${snapshot.runtime.currentTaskId ?? "-"}`);
+    printLine(`Remaining tasks: ${String(snapshot.runtime.remainingTaskCount)}`);
+    printLine(`Next action: ${snapshot.runtime.nextAction}`);
+    printLine(`Blocked reason: ${snapshot.runtime.blockedReason ?? "-"}`);
+    printLine(`Validation: ${snapshot.runtime.lastValidationStatus}`);
+    printLine(`Last run: ${snapshot.runtime.lastRunId ?? "-"}`);
+    printLine(`Max retries per task: ${String(snapshot.job.retryPolicy.maxRetriesPerTask)}`);
+    return 0;
+  } catch (error) {
+    printError(error instanceof Error ? error.message : "Failed to load job status.");
+    return 1;
+  }
+}
+
+// src/shared/constants/index.ts
+var packageName = "@weppy/ralph";
+var version = "0.1.0";
+
+// src/mcp/tools/index.ts
+var mcpToolDefinitions = [
+  {
+    name: "start_job",
+    description: "Create a Ralph job in the target workspace.",
+    inputSchema: {
+      type: "object",
+      required: ["title", "agent", "workspace_path"],
+      properties: {
+        title: { type: "string" },
+        agent: { type: "string", enum: ["codex", "claude-code", "custom-command"] },
+        workspace_path: { type: "string" },
+        state_dir: { type: "string" },
+        input_documents: {
+          type: "array",
+          items: { type: "string" }
+        },
+        validation_commands: {
+          type: "array",
+          items: { type: "string" }
+        },
+        max_retries_per_task: { type: "integer", minimum: 0 }
+      }
+    }
+  },
+  {
+    name: "get_status",
+    description: "Read the current Ralph job status.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        job_id: { type: "string" },
+        workspace_path: { type: "string" },
+        state_dir: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "get_result",
+    description: "Read the latest Ralph job result and reports.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        job_id: { type: "string" },
+        workspace_path: { type: "string" },
+        state_dir: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "resume_job",
+    description: "Resume a Ralph job until it reaches a non-resumable state or the iteration limit.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        job_id: { type: "string" },
+        workspace_path: { type: "string" },
+        state_dir: { type: "string" },
+        max_iterations: { type: "integer", minimum: 1 }
+      }
+    }
+  },
+  {
+    name: "cancel_job",
+    description: "Cancel a Ralph job and mark pending work as cancelled.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        job_id: { type: "string" },
+        workspace_path: { type: "string" },
+        state_dir: { type: "string" }
+      }
+    }
+  }
+];
+
+// src/mcp/index.ts
+async function startMcpServer() {
+  let buffer = Buffer.alloc(0);
+  let expectedBodyLength = null;
+  process.stdin.on("data", (chunk) => {
+    buffer = Buffer.concat([buffer, chunk]);
+    void processIncomingBuffer();
+  });
+  process.stdin.resume();
+  return await new Promise((resolve3) => {
+    process.stdin.on("end", () => resolve3(0));
+  });
+  async function processIncomingBuffer() {
+    while (true) {
+      if (expectedBodyLength === null) {
+        const headerEndIndex = buffer.indexOf("\r\n\r\n");
+        if (headerEndIndex === -1) {
+          return;
+        }
+        const headerText = buffer.subarray(0, headerEndIndex).toString("utf8");
+        const contentLengthHeader = headerText.split("\r\n").find((line) => line.toLowerCase().startsWith("content-length:"));
+        if (contentLengthHeader === void 0) {
+          writeJsonRpcResponse({
+            jsonrpc: "2.0",
+            id: null,
+            error: {
+              code: -32600,
+              message: "Missing Content-Length header."
+            }
+          });
+          buffer = Buffer.alloc(0);
+          return;
+        }
+        expectedBodyLength = Number.parseInt(contentLengthHeader.split(":")[1].trim(), 10);
+        buffer = buffer.subarray(headerEndIndex + 4);
+      }
+      if (expectedBodyLength === null || buffer.length < expectedBodyLength) {
+        return;
+      }
+      const body = buffer.subarray(0, expectedBodyLength).toString("utf8");
+      buffer = buffer.subarray(expectedBodyLength);
+      expectedBodyLength = null;
+      let request;
+      try {
+        request = JSON.parse(body);
+      } catch {
+        writeJsonRpcResponse({
+          jsonrpc: "2.0",
+          id: null,
+          error: {
+            code: -32700,
+            message: "Invalid JSON payload."
+          }
+        });
+        continue;
+      }
+      const response = await handleRequest(request);
+      if (response !== null) {
+        writeJsonRpcResponse(response);
+      }
+    }
+  }
+}
+async function handleRequest(request) {
+  if (request.method === "notifications/initialized") {
+    return null;
+  }
+  try {
+    switch (request.method) {
+      case "initialize":
+        return {
+          jsonrpc: "2.0",
+          id: request.id ?? null,
+          result: {
+            protocolVersion: "2024-11-05",
+            serverInfo: {
+              name: "@weppy/ralph",
+              version
+            },
+            capabilities: {
+              tools: {}
+            }
+          }
+        };
+      case "ping":
+        return {
+          jsonrpc: "2.0",
+          id: request.id ?? null,
+          result: {}
+        };
+      case "tools/list":
+        return {
+          jsonrpc: "2.0",
+          id: request.id ?? null,
+          result: {
+            tools: mcpToolDefinitions
+          }
+        };
+      case "tools/call":
+        return {
+          jsonrpc: "2.0",
+          id: request.id ?? null,
+          result: await callTool(request.params ?? {})
+        };
+      default:
+        return {
+          jsonrpc: "2.0",
+          id: request.id ?? null,
+          error: {
+            code: -32601,
+            message: `Unknown method: ${request.method}`
+          }
+        };
+    }
+  } catch (error) {
+    return {
+      jsonrpc: "2.0",
+      id: request.id ?? null,
+      error: {
+        code: -32e3,
+        message: error instanceof Error ? error.message : "Unhandled MCP error."
+      }
+    };
+  }
+}
+async function callTool(params) {
+  const toolName = asString(params.name);
+  const args = isRecord(params.arguments) ? params.arguments : {};
+  let payload;
+  switch (toolName) {
+    case "start_job": {
+      const result = await createJob({
+        title: requireString(args.title, "title"),
+        agent: requireAgent(args.agent),
+        workspacePath: requireString(args.workspace_path, "workspace_path"),
+        stateDirectoryPath: asOptionalString(args.state_dir),
+        inputDocuments: asStringArray(args.input_documents),
+        validateCommands: asStringArray(args.validation_commands),
+        maxRetriesPerTask: requireOptionalInteger(args.max_retries_per_task, "max_retries_per_task", 0)
+      });
+      payload = {
+        job_id: result.snapshot.job.id,
+        status: result.snapshot.job.status,
+        workspace_path: result.snapshot.job.workspacePath,
+        state_directory_path: result.snapshot.job.stateDirectoryPath,
+        next_action: result.snapshot.runtime.nextAction
+      };
+      break;
+    }
+    case "get_status": {
+      requireOneOf(args, "workspace_path", "state_dir");
+      const result = await getJobOverview({
+        jobId: asOptionalString(args.job_id),
+        workspacePath: asOptionalString(args.workspace_path),
+        stateDirectoryPath: asOptionalString(args.state_dir)
+      });
+      payload = {
+        job: result.snapshot.job,
+        runtime: result.snapshot.runtime,
+        tasks: result.snapshot.tasks,
+        run_ids: result.runIds
+      };
+      break;
+    }
+    case "get_result": {
+      requireOneOf(args, "workspace_path", "state_dir");
+      const result = await loadJobDetails({
+        jobId: asOptionalString(args.job_id),
+        workspacePath: asOptionalString(args.workspace_path),
+        stateDirectoryPath: asOptionalString(args.state_dir)
+      });
+      payload = result;
+      break;
+    }
+    case "resume_job": {
+      requireOneOf(args, "workspace_path", "state_dir");
+      const result = await resumeJob({
+        jobId: asOptionalString(args.job_id),
+        workspacePath: asOptionalString(args.workspace_path),
+        stateDirectoryPath: asOptionalString(args.state_dir),
+        maxIterations: requireOptionalInteger(args.max_iterations, "max_iterations", 1)
+      });
+      payload = result;
+      break;
+    }
+    case "cancel_job": {
+      requireOneOf(args, "workspace_path", "state_dir");
+      const result = await cancelJob({
+        jobId: asOptionalString(args.job_id),
+        workspacePath: asOptionalString(args.workspace_path),
+        stateDirectoryPath: asOptionalString(args.state_dir)
+      });
+      payload = result;
+      break;
+    }
+    default:
+      throw new Error(`Unknown tool: ${toolName}`);
+  }
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(payload, null, 2)
+      }
+    ],
+    structuredContent: payload
+  };
+}
+function writeJsonRpcResponse(response) {
+  const body = JSON.stringify(response);
+  process.stdout.write(`Content-Length: ${Buffer.byteLength(body, "utf8")}\r
+\r
+${body}`);
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function asString(value) {
+  if (typeof value !== "string") {
+    throw new Error("Expected a string.");
+  }
+  return value;
+}
+function requireString(value, fieldName) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`Missing required string field: ${fieldName}`);
+  }
+  return value;
+}
+function asOptionalString(value) {
+  return typeof value === "string" ? value : void 0;
+}
+function asOptionalNumber(value) {
+  return typeof value === "number" ? value : void 0;
+}
+function requireOptionalInteger(value, fieldName, minimum) {
+  const parsed = asOptionalNumber(value);
+  if (parsed === void 0) {
+    return void 0;
+  }
+  if (!Number.isInteger(parsed) || parsed < minimum) {
+    throw new Error(`\`${fieldName}\` must be an integer greater than or equal to ${String(minimum)}.`);
+  }
+  return parsed;
+}
+function asStringArray(value) {
+  return Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
+}
+function requireOneOf(args, ...fields) {
+  const hasAny = fields.some(
+    (field) => typeof args[field] === "string" && args[field].trim().length > 0
+  );
+  if (!hasAny) {
+    throw new Error(`At least one of ${fields.join(", ")} is required.`);
+  }
+}
+function requireAgent(value) {
+  if (value === "codex" || value === "claude-code" || value === "custom-command") {
+    return value;
+  }
+  throw new Error("`agent` must be one of: codex, claude-code, custom-command.");
+}
+
+// src/cli/index.ts
+function printHelp() {
+  const helpText = [
+    `${packageName} v${version}`,
+    "",
+    "Usage:",
+    "  ralph <command> [options]",
+    "",
+    "Commands:",
+    "  start    Create a new job",
+    "  status   Show current job status",
+    "  resume   Resume job execution",
+    "  cancel   Cancel a running job",
+    "  result   Show job result and reports",
+    "  mcp      Start MCP server (stdin/stdout)",
+    "",
+    "Common options:",
+    "  --workspace <path>   Working directory for agent execution",
+    "  --state-dir <path>   State storage root override",
+    "  --json               Output in JSON format",
+    "",
+    "Start options:",
+    "  --title <text>       Job title (required)",
+    "  --agent <name>       Agent adapter: codex, claude-code, custom-command (required)",
+    "  --input <path>       Input file/image/directory reference (repeatable)",
+    "  --validate-cmd <cmd> Validation command (repeatable)",
+    "  --max-retries <n>    Max retries per task",
+    "",
+    "Resume options:",
+    "  --max-iterations <n> Max iterations per resume call",
+    "",
+    "Status/Cancel/Result options:",
+    "  --job <id>           Job ID (defaults to current job)",
+    "",
+    "Flags:",
+    "  --help, -h           Show this help",
+    "  --version, -v        Show version"
+  ];
+  process.stdout.write(`${helpText.join("\n")}
+`);
+}
+async function main(argv) {
+  const [command] = argv;
+  const commandArgs = argv.slice(1);
+  switch (command) {
+    case void 0:
+    case "help":
+    case "--help":
+    case "-h":
+      printHelp();
+      return 0;
+    case "version":
+    case "--version":
+    case "-v":
+      process.stdout.write(`${version}
+`);
+      return 0;
+    case "start":
+      return runStartCommand(commandArgs);
+    case "status":
+      return runStatusCommand(commandArgs);
+    case "resume":
+      return runResumeCommand(commandArgs);
+    case "cancel":
+      return runCancelCommand(commandArgs);
+    case "result":
+      return runResultCommand(commandArgs);
+    case "mcp":
+      return startMcpServer();
+    default:
+      process.stderr.write(`Unknown command: ${command}
+`);
+      printHelp();
+      return 1;
+  }
+}
+void main(process.argv.slice(2)).then((exitCode) => {
+  process.exitCode = exitCode;
+});