@shenlee/devcrew 0.1.3 → 0.1.5

package/packages/adapters/src/index.ts

@@ -1,3 +1,6 @@
+import { accessSync, constants, realpathSync } from "node:fs";
+import { delimiter, join, sep } from "node:path";
+
 import { DEVCREW_NPM_PACKAGE, ROLE_SECTIONS } from "../../core/src/index.js";
 import type {
   ArtifactName,
@@ -6,6 +9,7 @@ import type {
   ExecutionPolicy,
   Host,
   Phase,
+  StructuredRoleData,
   RoleResult,
   RunState,
   WorkflowMode,
@@ -18,7 +22,7 @@ export interface BackendResolutionInput {
 
 export interface RoleRunInput {
   backend: BackendName;
-  role: RoleResult["role"];
+  role: Exclude<RoleResult["role"], "conductor">;
   phase: Phase;
   request: string;
   mode: WorkflowMode;
@@ -101,6 +105,156 @@ export function extractArchitectureReviewDecision(markdown: string): "approved"
   return match?.[1] as "approved" | "changes_required" | undefined;
 }
 
+const STRUCTURED_RESULT_MARKER = "<!-- devcrew-role-result -->";
+const STRUCTURED_RESULT_BLOCK = /<!--\s*devcrew-role-result\s*-->\s*```json\s*\r?\n([\s\S]*?)\r?\n```/g;
+
+function structuredOutputError(role: RoleResult["role"], reason: string): RoleOutputValidationError {
+  return new RoleOutputValidationError(role, [`marked structured role result: ${reason}`]);
+}
+
+function asRecord(value: unknown, role: RoleResult["role"], field: string): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw structuredOutputError(role, `${field} must be an object`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function asNonEmptyString(value: unknown, role: RoleResult["role"], field: string): string {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw structuredOutputError(role, `${field} must be a non-empty string`);
+  }
+  return value.trim();
+}
+
+function asStringArray(value: unknown, role: RoleResult["role"], field: string): string[] {
+  if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string" || entry.trim().length === 0)) {
+    throw structuredOutputError(role, `${field} must be an array of non-empty strings`);
+  }
+  return value.map((entry) => (entry as string).trim());
+}
+
+function asEvidence(value: unknown, role: RoleResult["role"]): StructuredRoleData["evidence"] {
+  if (!Array.isArray(value)) {
+    throw structuredOutputError(role, "evidence must be an array");
+  }
+  return value.map((entry, index) => {
+    const evidence = asRecord(entry, role, `evidence[${index}]`);
+    const command = asNonEmptyString(evidence.command, role, `evidence[${index}].command`);
+    if (!Number.isInteger(evidence.exitCode)) {
+      throw structuredOutputError(role, `evidence[${index}].exitCode must be an integer`);
+    }
+    if (evidence.output !== undefined && typeof evidence.output !== "string") {
+      throw structuredOutputError(role, `evidence[${index}].output must be a string`);
+    }
+    return { command, exitCode: evidence.exitCode as number, output: evidence.output as string | undefined };
+  });
+}
+
+function asQuestions(value: unknown, role: RoleResult["role"]): NonNullable<StructuredRoleData["questions"]> {
+  if (!Array.isArray(value)) {
+    throw structuredOutputError(role, "questions must be an array");
+  }
+  const ids = new Set<string>();
+  return value.map((entry, index) => {
+    const question = asRecord(entry, role, `questions[${index}]`);
+    const id = asNonEmptyString(question.id, role, `questions[${index}].id`);
+    if (ids.has(id)) {
+      throw structuredOutputError(role, `questions[${index}].id must be unique`);
+    }
+    ids.add(id);
+    const prompt = asNonEmptyString(question.prompt, role, `questions[${index}].prompt`);
+    if (question.context !== undefined && typeof question.context !== "string") {
+      throw structuredOutputError(role, `questions[${index}].context must be a string`);
+    }
+    return { id, prompt, context: question.context as string | undefined };
+  });
+}
+
+function parseStructuredRoleData(
+  role: Exclude<RoleResult["role"], "conductor">,
+  phase: Phase,
+  raw: unknown,
+): StructuredRoleData {
+  const value = asRecord(raw, role, "result");
+  if (value.schemaVersion !== 1) {
+    throw structuredOutputError(role, "schemaVersion must be 1");
+  }
+  if (value.role !== role) {
+    throw structuredOutputError(role, `role must be ${role}`);
+  }
+  const data: StructuredRoleData = {
+    schemaVersion: 1,
+    role,
+    summary: asNonEmptyString(value.summary, role, "summary"),
+    risks: asStringArray(value.risks, role, "risks"),
+    evidence: asEvidence(value.evidence, role),
+  };
+  if (role === "pm") {
+    data.questions = asQuestions(value.questions, role);
+  } else if (role === "architect") {
+    data.decisions = asStringArray(value.decisions, role, "decisions");
+    if (phase === "review") {
+      if (value.reviewDecision !== "approved" && value.reviewDecision !== "changes_required") {
+        throw structuredOutputError(role, "reviewDecision must be approved or changes_required");
+      }
+      data.reviewDecision = value.reviewDecision;
+    }
+  } else if (role === "implementer") {
+    data.changedFiles = asStringArray(value.changedFiles, role, "changedFiles");
+  } else {
+    if (!Array.isArray(value.testCases)) {
+      throw structuredOutputError(role, "testCases must be an array");
+    }
+    data.testCases = value.testCases.map((entry, index) => {
+      const testCase = asRecord(entry, role, `testCases[${index}]`);
+      const type = testCase.type;
+      if (type !== "happy" && type !== "edge" && type !== "failure" && type !== "regression") {
+        throw structuredOutputError(role, `testCases[${index}].type is invalid`);
+      }
+      return {
+        id: asNonEmptyString(testCase.id, role, `testCases[${index}].id`),
+        scenario: asNonEmptyString(testCase.scenario, role, `testCases[${index}].scenario`),
+        type,
+        expected: asNonEmptyString(testCase.expected, role, `testCases[${index}].expected`),
+      };
+    });
+  }
+  return data;
+}
+
+export function parseRoleResultOutput(
+  role: Exclude<RoleResult["role"], "conductor">,
+  phase: Phase,
+  output: string,
+): Pick<RoleResult, "format" | "markdown" | "structured" | "questions" | "reviewDecision"> {
+  if (!output.includes(STRUCTURED_RESULT_MARKER)) {
+    return {
+      format: "legacy",
+      markdown: output,
+      questions: role === "pm" ? extractOpenQuestions(output) : undefined,
+      reviewDecision: phase === "review" ? extractArchitectureReviewDecision(output) : undefined,
+    };
+  }
+  const blocks = [...output.matchAll(STRUCTURED_RESULT_BLOCK)];
+  if (blocks.length !== 1) {
+    throw structuredOutputError(role, blocks.length === 0 ? "must use a JSON fenced block" : "must appear exactly once");
+  }
+  let raw: unknown;
+  try {
+    raw = JSON.parse(blocks[0]?.[1] ?? "");
+  } catch {
+    throw structuredOutputError(role, "contains invalid JSON");
+  }
+  const structured = parseStructuredRoleData(role, phase, raw);
+  return {
+    format: "structured",
+    markdown: output.slice(0, blocks[0]?.index).concat(output.slice((blocks[0]?.index ?? 0) + (blocks[0]?.[0].length ?? 0))).trim(),
+    structured,
+    questions: structured.questions?.map((question) => question.prompt),
+    reviewDecision: structured.reviewDecision,
+  };
+}
+
 export function renderRolePrompt(input: Omit<RoleRunInput, "backend" | "cwd">): string {
   const executionMode = input.executionMode ?? "plan";
   const answers = input.answers ?? [];
@@ -148,6 +302,13 @@ export function renderRolePrompt(input: Omit<RoleRunInput, "backend" | "cwd">):
     "Keep scope aligned with the approved gates and the selected DevCrew execution policy.",
     permissionInstruction,
     "",
+    "Return this protocol block first:",
+    STRUCTURED_RESULT_MARKER,
+    "```json",
+    `{\"schemaVersion\":1,\"role\":\"${input.role}\",\"summary\":\"...\",\"risks\":[],\"evidence\":[]}`,
+    "```",
+    "Then return the required Markdown H2 sections. Do not include a second marked result block.",
+    "",
     "Required Sections:",
     ...roleGuidance(input.role),
   );
@@ -180,7 +341,7 @@ function titleForPhase(phase: Phase): string {
 // --- Host SDK contracts -----------------------------------------------------
 // These types pin the published surface of the optional host SDKs so the
 // adapter logic is type-checked even though the packages are not installed.
-// Verified against @openai/codex-sdk 0.136.0 (sdk/typescript/src/threadOptions.ts
+// Verified against @openai/codex-sdk 0.144.5 (sdk/typescript/src/threadOptions.ts
 // and thread.ts) and @anthropic-ai/claude-agent-sdk (Agent SDK TypeScript
 // reference). Update these when the upstream contracts change.
 
@@ -210,7 +371,11 @@ interface CodexClient {
   startThread: (options?: CodexThreadOptions) => CodexThread;
 }
 
-type CodexConstructor = new () => CodexClient;
+interface CodexClientOptions {
+  codexPathOverride?: string;
+}
+
+type CodexConstructor = new (options?: CodexClientOptions) => CodexClient;
 
 export type ClaudePermissionMode = "default" | "acceptEdits" | "bypassPermissions" | "dontAsk" | "plan";
 
@@ -377,10 +542,52 @@ function claudeOptionsForRole(input: RoleRunInput): ClaudeQueryOptions {
   return buildClaudeOptions(input.cwd, "dontAsk", allowedTools);
 }
 
+function resolveHostCodexExecutable(): string | undefined {
+  const explicitPath = process.env.DEVCREW_CODEX_PATH?.trim();
+  if (explicitPath) {
+    return explicitPath;
+  }
+
+  const pathValue = process.env.PATH ?? Object.entries(process.env)
+    .find(([key]) => key.toLowerCase() === "path")?.[1];
+  if (!pathValue) {
+    return undefined;
+  }
+
+  const executableNames = process.platform === "win32"
+    ? ["codex.exe", "codex.cmd", "codex.bat", "codex"]
+    : ["codex"];
+  for (const entry of pathValue.split(delimiter)) {
+    const directory = entry.trim().replace(/^"|"$/g, "");
+    if (!directory) {
+      continue;
+    }
+    for (const executableName of executableNames) {
+      const candidate = join(directory, executableName);
+      try {
+        accessSync(candidate, process.platform === "win32" ? constants.F_OK : constants.X_OK);
+        const normalizedCandidate = candidate.split(sep).join("/");
+        const normalizedRealPath = realpathSync(candidate).split(sep).join("/");
+        if (
+          normalizedCandidate.includes("/node_modules/.bin/")
+          || normalizedRealPath.includes("/node_modules/@openai/codex/")
+        ) {
+          continue;
+        }
+        return candidate;
+      } catch {
+        // Keep searching PATH; the SDK's packaged runtime remains the fallback.
+      }
+    }
+  }
+  return undefined;
+}
+
 async function runWithCodex(input: RoleRunInput, prompt: string, loadModule: ModuleLoader): Promise<string> {
   const mod = await loadModule(HOST_SDK_PACKAGES.codex);
   const CodexClass = mod.Codex as CodexConstructor;
-  const codex = new CodexClass();
+  const codexPathOverride = resolveHostCodexExecutable();
+  const codex = new CodexClass(codexPathOverride ? { codexPathOverride } : undefined);
   const thread = codex.startThread(codexOptionsForRole(input));
   const turn = await thread.run(prompt);
   return extractCodexText(turn);
@@ -410,6 +617,7 @@ function fallbackResult(
     summary,
     markdown: `# ${title}\n\n${summary}\n`,
     usedFallback: true,
+    format: "legacy",
   };
 }
 
@@ -443,18 +651,21 @@ export async function runRole(input: RoleRunInput, deps: RunRoleDeps = {}): Prom
       input.backend === "codex"
         ? await runWithCodex(input, prompt, loadModule)
         : await runWithClaude(input, prompt, loadModule);
-    assertRoleSections(input.role, markdown);
-    const reviewDecision = input.phase === "review" ? extractArchitectureReviewDecision(markdown) : undefined;
+    const parsed = parseRoleResultOutput(input.role, input.phase, markdown);
+    assertRoleSections(input.role, parsed.markdown);
+    const reviewDecision = parsed.reviewDecision;
     if (input.phase === "review" && !reviewDecision) {
       throw new RoleOutputValidationError(input.role, ["Review Decision"]);
     }
     return {
       role: input.role,
       backend: input.backend,
-      summary: `${input.role} produced ${title} using the ${input.backend} SDK.`,
-      markdown,
+      summary: parsed.structured?.summary ?? `${input.role} produced ${title} using the ${input.backend} SDK.`,
+      markdown: parsed.markdown,
       usedFallback: false,
-      questions: input.role === "pm" ? extractOpenQuestions(markdown) : undefined,
+      format: parsed.format,
+      structured: parsed.structured,
+      questions: parsed.questions,
       reviewDecision,
     };
   } catch (error) {

package/packages/core/src/active-run.ts

@@ -1,4 +1,4 @@
-import { readFile, writeFile } from "node:fs/promises";
+import { readFile, unlink, writeFile } from "node:fs/promises";
 
 import { activeRunPath, ensureProjectDirectories } from "./paths.js";
 
@@ -29,3 +29,15 @@ export async function getActiveRunId(cwd: string): Promise<string> {
   }
   throw new Error("No active DevCrew run. Pass runId or start a workflow first.");
 }
+
+export async function clearActiveRunIfMatches(cwd: string, runId: string): Promise<boolean> {
+  try {
+    if ((await getActiveRunId(cwd)) !== runId) {
+      return false;
+    }
+    await unlink(activeRunPath(cwd));
+    return true;
+  } catch {
+    return false;
+  }
+}

package/packages/core/src/config.ts

@@ -1,7 +1,8 @@
 import { access, readFile, writeFile } from "node:fs/promises";
+import { isAbsolute, relative, resolve, sep } from "node:path";
 
 import { configPath, ensureProjectDirectories } from "./paths.js";
-import type { DevCrewConfig } from "./types.js";
+import { BACKENDS, EXECUTION_MODES, GATES, type BackendName, type DevCrewConfig, type ExecutionMode, type GateName } from "./types.js";
 
 export const DEFAULT_CONFIG: DevCrewConfig = {
   version: 1,
@@ -25,6 +26,99 @@ async function exists(path: string): Promise<boolean> {
   }
 }
 
+type JsonRecord = Record<string, unknown>;
+
+function asRecord(value: unknown, field: string): JsonRecord {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`Invalid .devcrew/config.json: ${field} must be an object`);
+  }
+  return value as JsonRecord;
+}
+
+function assertKnownKeys(value: JsonRecord, field: string, allowed: readonly string[]): void {
+  for (const key of Object.keys(value)) {
+    if (!allowed.includes(key)) {
+      throw new Error(`Invalid .devcrew/config.json: ${field} has unknown key ${key}`);
+    }
+  }
+}
+
+function requiredString(value: unknown, field: string): string {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`Invalid .devcrew/config.json: ${field} must be a non-empty string`);
+  }
+  return value.trim();
+}
+
+function parseCommandList(value: unknown, field: string): string[] {
+  if (value === undefined) {
+    return [];
+  }
+  if (!Array.isArray(value)) {
+    throw new Error(`Invalid .devcrew/config.json: ${field} must be an array`);
+  }
+  return value.map((entry, index) => requiredString(entry, `${field}[${index}]`));
+}
+
+function parseGates(value: unknown): GateName[] {
+  if (!Array.isArray(value)) {
+    throw new Error("Invalid .devcrew/config.json: workflow.gates must be an array");
+  }
+  const gates: GateName[] = [];
+  for (const [index, entry] of value.entries()) {
+    if (typeof entry !== "string" || !GATES.includes(entry as GateName)) {
+      throw new Error(`Invalid .devcrew/config.json: workflow.gates[${index}] must be a known gate, received ${String(entry)}`);
+    }
+    if (gates.includes(entry as GateName)) {
+      throw new Error(`Invalid .devcrew/config.json: workflow.gates contains duplicate ${entry}`);
+    }
+    gates.push(entry as GateName);
+  }
+  return gates;
+}
+
+function parseArtifactDirectory(cwd: string, value: unknown): string {
+  const artifactDirectory = requiredString(value, "workflow.artifactDirectory");
+  if (isAbsolute(artifactDirectory)) {
+    throw new Error("Invalid .devcrew/config.json: workflow.artifactDirectory must be relative to the repository");
+  }
+  const projectRoot = resolve(cwd);
+  const target = resolve(projectRoot, artifactDirectory);
+  const fromProject = relative(projectRoot, target);
+  if (fromProject === ".." || fromProject.startsWith(`..${sep}`) || isAbsolute(fromProject)) {
+    throw new Error("Invalid .devcrew/config.json: workflow.artifactDirectory must resolve inside the repository");
+  }
+  return artifactDirectory;
+}
+
+function parseConfig(cwd: string, value: unknown): DevCrewConfig {
+  const parsed = asRecord(value, "root");
+  assertKnownKeys(parsed, "root", ["version", "defaultBackend", "executionMode", "verifyCommands", "lintCommands", "coverageCommands", "workflow"]);
+  if (parsed.version !== 1) {
+    throw new Error("Unsupported .devcrew/config.json version");
+  }
+  if (typeof parsed.defaultBackend !== "string" || (parsed.defaultBackend !== "host-preferred" && !BACKENDS.includes(parsed.defaultBackend as BackendName))) {
+    throw new Error("Invalid .devcrew/config.json: defaultBackend must be host-preferred, codex, claude, or local");
+  }
+  if (typeof parsed.executionMode !== "string" || !EXECUTION_MODES.includes(parsed.executionMode as ExecutionMode)) {
+    throw new Error("Invalid .devcrew/config.json: executionMode must be plan or apply");
+  }
+  const workflow = asRecord(parsed.workflow, "workflow");
+  assertKnownKeys(workflow, "workflow", ["gates", "artifactDirectory"]);
+  return {
+    version: 1,
+    defaultBackend: parsed.defaultBackend as DevCrewConfig["defaultBackend"],
+    executionMode: parsed.executionMode as ExecutionMode,
+    verifyCommands: parseCommandList(parsed.verifyCommands, "verifyCommands"),
+    lintCommands: parseCommandList(parsed.lintCommands, "lintCommands"),
+    coverageCommands: parseCommandList(parsed.coverageCommands, "coverageCommands"),
+    workflow: {
+      gates: parseGates(workflow.gates),
+      artifactDirectory: parseArtifactDirectory(cwd, workflow.artifactDirectory),
+    },
+  };
+}
+
 export async function ensureConfig(cwd: string): Promise<DevCrewConfig> {
   await ensureProjectDirectories(cwd);
   const path = configPath(cwd);
@@ -37,20 +131,5 @@ export async function ensureConfig(cwd: string): Promise<DevCrewConfig> {
 
 export async function readConfig(cwd: string): Promise<DevCrewConfig> {
   const raw = await readFile(configPath(cwd), "utf8");
-  const parsed = JSON.parse(raw) as DevCrewConfig;
-  if (parsed.version !== 1) {
-    throw new Error("Unsupported .devcrew/config.json version");
-  }
-  return {
-    ...DEFAULT_CONFIG,
-    ...parsed,
-    executionMode: parsed.executionMode ?? "plan",
-    verifyCommands: Array.isArray(parsed.verifyCommands) ? parsed.verifyCommands : [],
-    lintCommands: Array.isArray(parsed.lintCommands) ? parsed.lintCommands : [],
-    coverageCommands: Array.isArray(parsed.coverageCommands) ? parsed.coverageCommands : [],
-    workflow: {
-      ...DEFAULT_CONFIG.workflow,
-      ...parsed.workflow,
-    },
-  };
+  return parseConfig(cwd, JSON.parse(raw) as unknown);
 }

package/packages/core/src/index.ts

@@ -1,6 +1,7 @@
 export * from "./active-run.js";
 export * from "./artifacts.js";
 export * from "./config.js";
+export * from "./lock.js";
 export * from "./paths.js";
 export * from "./standards.js";
 export * from "./store.js";

package/packages/core/src/lock.ts

@@ -0,0 +1,104 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+
+import { devcrewDir, repositoryLockPath } from "./paths.js";
+
+interface RepositoryLockMetadata {
+  ownerId: string;
+  pid: number;
+  createdAt: string;
+}
+
+function metadataPath(cwd: string): string {
+  return `${repositoryLockPath(cwd)}/lock.json`;
+}
+
+async function readMetadata(cwd: string): Promise<RepositoryLockMetadata | undefined> {
+  try {
+    const parsed = JSON.parse(await readFile(metadataPath(cwd), "utf8")) as Partial<RepositoryLockMetadata>;
+    const pid = parsed.pid;
+    if (
+      typeof parsed.ownerId !== "string" ||
+      typeof pid !== "number" ||
+      !Number.isInteger(pid) ||
+      typeof parsed.createdAt !== "string"
+    ) {
+      return undefined;
+    }
+    return {
+      ownerId: parsed.ownerId,
+      pid,
+      createdAt: parsed.createdAt,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+function processIsLive(pid: number): boolean {
+  if (pid <= 0) {
+    return false;
+  }
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+async function releaseRepositoryLock(cwd: string, ownerId: string): Promise<void> {
+  const metadata = await readMetadata(cwd);
+  if (metadata?.ownerId === ownerId) {
+    await rm(repositoryLockPath(cwd), { recursive: true, force: true });
+  }
+}
+
+export async function withRepositoryLock<T>(cwd: string, action: () => Promise<T>): Promise<T> {
+  await mkdir(devcrewDir(cwd), { recursive: true });
+  const ownerId = randomUUID();
+  try {
+    await mkdir(repositoryLockPath(cwd));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
+      throw error;
+    }
+    const metadata = await readMetadata(cwd);
+    if (metadata && processIsLive(metadata.pid)) {
+      throw new Error("A DevCrew operation is already in progress for this repository");
+    }
+    throw new Error("A stale DevCrew repository lock exists; use devcrew_recover for explicit recovery");
+  }
+
+  await writeFile(
+    metadataPath(cwd),
+    `${JSON.stringify({ ownerId, pid: process.pid, createdAt: new Date().toISOString() } satisfies RepositoryLockMetadata, null, 2)}\n`,
+    "utf8",
+  );
+  try {
+    return await action();
+  } finally {
+    await releaseRepositoryLock(cwd, ownerId);
+  }
+}
+
+export async function recoverRepositoryLock(cwd: string): Promise<boolean> {
+  const lockPath = repositoryLockPath(cwd);
+  const metadata = await readMetadata(cwd);
+  if (!metadata) {
+    try {
+      await rm(lockPath, { recursive: true, force: false });
+      return true;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+        return false;
+      }
+      throw error;
+    }
+  }
+  if (processIsLive(metadata.pid)) {
+    throw new Error("Cannot recover a DevCrew repository lock held by a live process");
+  }
+  await rm(lockPath, { recursive: true, force: true });
+  return true;
+}

package/packages/core/src/paths.ts

@@ -31,6 +31,10 @@ export function activeRunPath(cwd: string): string {
   return join(devcrewDir(cwd), "active-run.json");
 }
 
+export function repositoryLockPath(cwd: string): string {
+  return join(devcrewDir(cwd), "lock");
+}
+
 export function standardsPath(cwd: string): string {
   return join(devcrewDir(cwd), "standards.md");
 }

package/packages/core/src/store.ts

@@ -2,7 +2,7 @@ import { readFile, rename, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 
 import { ensureRunDirectories, statePath } from "./paths.js";
-import { GATES, type GateName, type RunState } from "./types.js";
+import { GATES, type GateName, type RoleResult, type RunState } from "./types.js";
 
 function enabledGatesFromState(value: unknown): GateName[] {
   const configured = Array.isArray(value)
@@ -11,6 +11,16 @@ function enabledGatesFromState(value: unknown): GateName[] {
   return [...new Set<GateName>([...configured, "implementation-review", "testing"])];
 }
 
+function roleResultsFromState(value: unknown): RoleResult[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.filter((role): role is RoleResult => typeof role === "object" && role !== null).map((role) => ({
+    ...role,
+    format: role.format === "structured" ? "structured" : "legacy",
+  }));
+}
+
 export async function saveState(state: RunState): Promise<RunState> {
   state.updatedAt = new Date().toISOString();
   await ensureRunDirectories(state.cwd, state.runId);
@@ -31,6 +41,7 @@ export async function loadState(cwd: string, runId: string): Promise<RunState> {
     ...parsed,
     executionMode: parsed.executionMode ?? "plan",
     executionPolicy: parsed.executionPolicy ?? "interactive-host",
+    roles: roleResultsFromState(parsed.roles),
     enabledGates: enabledGatesFromState(parsed.enabledGates),
     artifactDirectory: typeof parsed.artifactDirectory === "string" && parsed.artifactDirectory.trim().length > 0
       ? parsed.artifactDirectory