intentdna 1.8.6 → 1.8.7

package/dist/cli/commands/run.js

@@ -1,481 +1,763 @@
 /**
- * Intent DNA — dna run command
+ * Intent DNA - canonical dna run command.
  *
- * TypeScript runtime execution of workflows.
- * Loads DNA → compiles → auto-syncs agents/hooks → executes steps
- * via `claude -p --agent` child processes.
+ * The CLI compiles one workflow into Controller definitions, persists one
+ * durable run ledger, and launches one disposable provider session per Step
+ * attempt. Cross-Step inputs come only from committed results.
  */
-import { spawn } from "node:child_process";
-import { mkdir, writeFile } from "node:fs/promises";
-import { join, resolve } from "node:path";
-import { randomUUID } from "node:crypto";
-import { loadDNA, compileFromFiles, expandDNAInputFiles } from "../../compiler/index.js";
+import { createHash, randomUUID } from "node:crypto";
+import { isAbsolute, join, relative, resolve, sep, } from "node:path";
 import { cascadeDNA } from "../../compiler/cascade.js";
+import { compileFromFiles, expandDNAInputFiles, loadDNA, } from "../../compiler/index.js";
 import { compileWorkflow } from "../../compiler/workflow.js";
-import { compileAllRolesToAgentMD, writeAgentMDFiles, toKebabCase, } from "../../runtime/agent-md.js";
-import { createCompiledIR, writeCompiledIR } from "../../runtime/plugin-adapter.js";
 import { trustedEvidenceCaptureAttribution } from "../../governance/index.js";
 import { DNAStateManager } from "../../hooks/state-manager.js";
 import { appendEvidenceCaptureEvent, EVIDENCE_CAPTURE_SCHEMA_VERSION, } from "../../hooks/state.js";
-import { runCompletionVerifier, runCheckpointVerifier, } from "../../runtime/verifier.js";
-// ── Template & Condition Helpers ───────────────────────────
-/**
- * Replace {{var}} placeholders in a template string.
- * Unmatched placeholders are preserved as-is.
- */
+import { compileAllRolesToAgentMD, toKebabCase, writeAgentMDFiles, } from "../../runtime/agent-md.js";
+import { HandoffResolver } from "../../runtime/handoff-resolver.js";
+import { createCompiledIR, writeCompiledIR } from "../../runtime/plugin-adapter.js";
+import { ImmutableResultStore } from "../../runtime/result-store.js";
+import { RunController, } from "../../runtime/run-controller.js";
+import { DurableRunStore, RunStoreError, } from "../../runtime/run-store.js";
+import { createClaudeExecutionProvider } from "../../runtime/providers/claude.js";
+import { createCodexExecutionProvider } from "../../runtime/providers/codex.js";
+import { runCheckpointVerifier, runCompletionVerifier, } from "../../runtime/verifier.js";
+import { adaptWorkflowPlan, } from "../../runtime/workflow-plan-adapter.js";
+import { executeWorkerAttempt, } from "../../runtime/worker-executor.js";
+import { allocateAttemptWorkspace, applyWorkspaceLifecycleDecision, planAttemptWorkspace, } from "../../runtime/workspace-isolation.js";
+import { runLifecycleCancel, runLifecycleInspect, runLifecycleResume, runLifecycleStart, runLifecycleStatus, } from "./run-lifecycle.js";
+class RunUsageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RunUsageError";
+    }
+}
+// ── Compatibility-only pure helpers ───────────────────────
 export function substituteTemplate(template, vars) {
-    return template.replace(/\{\{(\w+)\}\}/g, (match, key) => {
-        return key in vars ? vars[key] : match;
-    });
+    return template.replace(/\{\{(\w+)\}\}/g, (match, key) => (key in vars ? vars[key] : match));
 }
-/**
- * Evaluate a run_if condition against the current round.
- * Returns true if the step should execute.
- */
 export function evaluateRunIf(condition, round) {
     if (condition === null)
         return true;
-    // "round == N"
     const eqMatch = condition.match(/^round\s*==\s*(\d+)$/);
     if (eqMatch)
         return round === parseInt(eqMatch[1], 10);
-    // "round > N"
     const gtMatch = condition.match(/^round\s*>\s*(\d+)$/);
     if (gtMatch)
         return round > parseInt(gtMatch[1], 10);
-    // "round >= N"
     const geMatch = condition.match(/^round\s*>=\s*(\d+)$/);
     if (geMatch)
         return round >= parseInt(geMatch[1], 10);
-    // "retry" = round > 1
     if (condition === "retry")
         return round > 1;
-    // "always" or unknown → run
     return true;
 }
-/**
- * Run checkpoint assertions for a completed step.
- * Returns true if all checkpoints pass, false if any fail.
- */
-async function runCompletions(step, vars, opts) {
-    if (!step.completion)
-        return true;
-    for (const completion of step.completion) {
-        const result = await runCompletionVerifier(completion, opts.ir, {
-            projectDir: opts.projectDir,
-            variables: vars,
-        });
-        if (!result.passed) {
-            logVerifierFailure("Completion failed", step.id, result);
-            return false;
+export function checkRetryNeeded(stepResults, transitions) {
+    for (const transition of transitions) {
+        if (transition.condition === "fail"
+            && stepResults.get(transition.from)?.status === "fail") {
+            return true;
         }
     }
-    return true;
+    return false;
 }
-async function runCheckpoints(step, vars, opts) {
-    if (!step.checkpoints)
-        return true;
-    for (const cp of step.checkpoints) {
-        const action = cp.action ?? "block";
-        const result = await runCheckpointVerifier(cp, opts.ir, {
-            projectDir: opts.projectDir,
-            variables: vars,
+// ── Validation and durable metadata ───────────────────────
+function requireText(value, label) {
+    const trimmed = value?.trim();
+    if (!trimmed)
+        throw new RunUsageError(`${label} is required`);
+    return trimmed;
+}
+function requirePositiveNumber(value, label) {
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new RunUsageError(`${label} must be a positive number`);
+    }
+    return value;
+}
+function requirePositiveInteger(value, label) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new RunUsageError(`${label} must be a positive integer`);
+    }
+    return value;
+}
+function requireNonNegativeInteger(value, label) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new RunUsageError(`${label} must be a non-negative integer`);
+    }
+    return value;
+}
+function asRunId(value) {
+    return requireText(value, "run_id");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readStringRecord(value, label) {
+    if (!isRecord(value))
+        throw new Error(`${label} must be an object`);
+    const result = {};
+    for (const [key, entry] of Object.entries(value)) {
+        if (typeof entry !== "string") {
+            throw new Error(`${label}.${key} must be a string`);
+        }
+        result[key] = entry;
+    }
+    return result;
+}
+function readCanonicalMetadata(value) {
+    if (!isRecord(value) || value.schema_version !== "intentdna.canonical_run.v1") {
+        throw new Error("run metadata is not intentdna.canonical_run.v1");
+    }
+    const dnaFiles = value.dna_files;
+    const context = value.context;
+    const provider = value.provider;
+    const timeoutMs = value.timeout_ms;
+    const workflowAsset = value.workflow_asset;
+    if (typeof value.project_directory !== "string"
+        || !Array.isArray(dnaFiles)
+        || !dnaFiles.every((entry) => typeof entry === "string")
+        || typeof value.workflow_name !== "string"
+        || typeof value.task_id !== "string"
+        || (context !== null && typeof context !== "string")
+        || typeof value.agents_directory !== "string"
+        || !isRecord(provider)
+        || !["claude", "codex"].includes(String(provider.kind))
+        || (provider.executable !== null && typeof provider.executable !== "string")
+        || typeof provider.max_budget_usd !== "number"
+        || typeof provider.permission_mode !== "string"
+        || typeof value.max_concurrency !== "number"
+        || (timeoutMs !== null && typeof timeoutMs !== "number")
+        || typeof value.cancellation_grace_ms !== "number"
+        || (workflowAsset !== null && typeof workflowAsset !== "string")) {
+        throw new Error("run metadata is malformed");
+    }
+    const metadata = {
+        schema_version: "intentdna.canonical_run.v1",
+        project_directory: value.project_directory,
+        dna_files: dnaFiles,
+        workflow_name: value.workflow_name,
+        task_id: value.task_id,
+        context,
+        variables: readStringRecord(value.variables, "run metadata variables"),
+        agents_directory: value.agents_directory,
+        provider: {
+            kind: provider.kind,
+            executable: provider.executable === null
+                ? null
+                : requireText(provider.executable, "run metadata provider.executable"),
+            max_budget_usd: requirePositiveNumber(provider.max_budget_usd, "run metadata provider.max_budget_usd"),
+            permission_mode: requireText(provider.permission_mode, "run metadata provider.permission_mode"),
+        },
+        max_concurrency: requirePositiveInteger(value.max_concurrency, "run metadata max_concurrency"),
+        timeout_ms: timeoutMs === null
+            ? null
+            : requireNonNegativeInteger(timeoutMs, "run metadata timeout_ms"),
+        cancellation_grace_ms: requireNonNegativeInteger(value.cancellation_grace_ms, "run metadata cancellation_grace_ms"),
+        workflow_asset: workflowAsset,
+    };
+    requireText(metadata.project_directory, "run metadata project_directory");
+    requireText(metadata.workflow_name, "run metadata workflow_name");
+    requireText(metadata.task_id, "run metadata task_id");
+    requireText(metadata.agents_directory, "run metadata agents_directory");
+    if (metadata.dna_files.length === 0) {
+        throw new Error("run metadata dna_files must not be empty");
+    }
+    return metadata;
+}
+function stableJson(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map(stableJson).join(",")}]`;
+    }
+    if (value !== null && typeof value === "object") {
+        const entries = Object.entries(value)
+            .filter(([, entry]) => entry !== undefined)
+            .sort(([left], [right]) => left.localeCompare(right));
+        return `{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${stableJson(entry)}`).join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+}
+function planDigest(plan, roles) {
+    const stablePlan = { ...plan, compiled_at: null };
+    return createHash("sha256")
+        .update(stableJson({ plan: stablePlan, roles }), "utf-8")
+        .digest("hex");
+}
+function runtimeRoot(projectDirectory) {
+    return join(projectDirectory, ".dna", "runtime");
+}
+// ── Compilation and provider construction ─────────────────
+async function compileRunAssets(metadata) {
+    const dnas = [];
+    for (const file of metadata.dna_files)
+        dnas.push(await loadDNA(file));
+    const cascaded = cascadeDNA(dnas);
+    const ir = await compileFromFiles([...metadata.dna_files], {
+        context: metadata.context ?? undefined,
+    });
+    const definition = cascaded.workflows[metadata.workflow_name];
+    if (!definition) {
+        throw new Error(`workflow '${metadata.workflow_name}' not found; available: `
+            + `${Object.keys(cascaded.workflows).join(", ") || "(none)"}`);
+    }
+    const result = compileWorkflow(definition, {
+        workflow_key: metadata.workflow_name,
+    });
+    if (!result.ok || !result.plan) {
+        throw new Error("workflow compilation failed:\n"
+            + result.errors.map((error) => `  ${error.path}: ${error.message}`).join("\n"));
+    }
+    const plan = result.plan;
+    const attribution = trustedEvidenceCaptureAttribution(ir, {
+        workflowId: metadata.workflow_name,
+    });
+    const workflowAsset = attribution.workflowAsset === "unknown"
+        ? null
+        : attribution.workflowAsset;
+    if (metadata.workflow_asset !== null
+        && workflowAsset !== metadata.workflow_asset) {
+        throw new Error(`workflow asset changed from '${metadata.workflow_asset}' to '${workflowAsset ?? "unknown"}'`);
+    }
+    return {
+        plan,
+        roles: cascaded.roles,
+        ir,
+        plan_digest: planDigest(plan, cascaded.roles),
+        workflow_asset: workflowAsset,
+    };
+}
+async function compileCanonicalRun(metadata) {
+    const assets = await compileRunAssets(metadata);
+    const adapterOptions = {
+        roles: assets.roles,
+        variables: metadata.variables,
+        working_directory: metadata.project_directory,
+        timeout_ms: metadata.timeout_ms,
+        cancellation_grace_ms: metadata.cancellation_grace_ms,
+    };
+    return {
+        ...assets,
+        definitions: adaptWorkflowPlan(assets.plan, adapterOptions),
+    };
+}
+async function syncRuntimeArtifacts(compiled, metadata) {
+    const agents = compileAllRolesToAgentMD(compiled.roles, compiled.ir);
+    await writeAgentMDFiles(agents, metadata.agents_directory);
+    await writeCompiledIR(metadata.project_directory, createCompiledIR(compiled.ir, compiled.roles));
+}
+function projectPathInWorkspace(metadata, workspaceDirectory, projectPath) {
+    const projectRelative = relative(metadata.project_directory, projectPath);
+    const outsideProject = (projectRelative === ".."
+        || projectRelative.startsWith(`..${sep}`)
+        || isAbsolute(projectRelative));
+    return outsideProject
+        ? projectPath
+        : resolve(workspaceDirectory, projectRelative);
+}
+async function syncAttemptRuntimeArtifacts(compiled, metadata, workspace) {
+    if (workspace.isolation !== "worktree")
+        return;
+    const agentsDirectory = projectPathInWorkspace(metadata, workspace.working_directory, metadata.agents_directory);
+    if (agentsDirectory !== metadata.agents_directory) {
+        const agents = compileAllRolesToAgentMD(compiled.roles, compiled.ir);
+        await writeAgentMDFiles(agents, agentsDirectory);
+    }
+    await writeCompiledIR(workspace.working_directory, createCompiledIR(compiled.ir, compiled.roles));
+}
+function createProvider(metadata) {
+    if (metadata.provider.kind === "codex") {
+        return createCodexExecutionProvider({
+            executable: metadata.provider.executable ?? undefined,
         });
-        if (!result.passed) {
-            logVerifierFailure(`Checkpoint failed: ${cp.assert}`, step.id, result);
-            if (action === "block")
-                return false;
+    }
+    return createClaudeExecutionProvider({
+        executable: metadata.provider.executable ?? undefined,
+        agentName: (packet) => `dna-${toKebabCase(packet.role)}`,
+        extraArgs: [
+            "--max-budget-usd",
+            String(metadata.provider.max_budget_usd),
+            "--permission-mode",
+            metadata.provider.permission_mode,
+        ],
+    });
+}
+function preservationReason(packet) {
+    return packet.workspace.isolation === "worktree"
+        ? "integration_pending"
+        : "controller_policy";
+}
+function preserveWorkspace(workspace, reason, detail) {
+    const result = applyWorkspaceLifecycleDecision(workspace, {
+        action: "preserve",
+        reason,
+        detail,
+    });
+    if (result.status === "preserved") {
+        log(`Preserved worktree ${result.working_directory}: `
+            + `${result.reason}${result.detail ? ` (${result.detail})` : ""}`);
+    }
+}
+async function recordAttemptProcess(runStore, packet, processId) {
+    if (!Number.isSafeInteger(processId) || processId <= 0) {
+        throw new Error(`provider returned invalid process id ${processId}`);
+    }
+    while (true) {
+        const snapshot = await runStore.requireRun(packet.run_id);
+        const attempt = snapshot.attempts.find((entry) => entry.attempt_id === packet.attempt_id);
+        if (!attempt
+            || attempt.step_id !== packet.step_id
+            || attempt.worker_session_id !== packet.worker_session_id) {
+            throw new Error(`attempt ${packet.attempt_id} disappeared before process registration`);
+        }
+        const recordedProcessId = attempt.process_id ?? null;
+        if (recordedProcessId === processId || attempt.phase === "terminal")
+            return;
+        if (recordedProcessId !== null) {
+            throw new Error(`attempt ${packet.attempt_id} already owns process ${recordedProcessId}`);
+        }
+        try {
+            await runStore.updateRun({
+                run_id: packet.run_id,
+                expected_record_version: snapshot.record_version,
+                attempts: [{ ...attempt, process_id: processId }],
+            });
+            return;
+        }
+        catch (error) {
+            if (error instanceof RunStoreError && error.code === "version_conflict") {
+                continue;
+            }
+            throw error;
         }
     }
-    return true;
 }
-function logVerifierFailure(prefix, stepId, result) {
-    const exitCode = result.exit_code === undefined ? "" : ` exit_code=${result.exit_code}`;
+const reconcileLocalProcess = async (attempt) => {
+    const processId = attempt.process_id ?? null;
+    if (processId === null
+        || !Number.isSafeInteger(processId)
+        || processId <= 0) {
+        return "unknown";
+    }
+    try {
+        process.kill(processId, 0);
+        return "live";
+    }
+    catch (error) {
+        const code = error instanceof Error
+            ? error.code
+            : undefined;
+        if (code === "EPERM")
+            return "live";
+        if (code === "ESRCH")
+            return "dead";
+        return "unknown";
+    }
+};
+function verifierFailureMessage(prefix, stepId, result) {
+    const exitCode = result.exit_code === undefined
+        ? ""
+        : ` exit_code=${result.exit_code}`;
     const target = result.target ? ` target=${result.target}` : "";
-    const message = result.message ? ` — ${result.message}` : "";
-    log(`${prefix}${target}${exitCode}${message} (step: ${stepId})`);
+    const message = result.message ? ` - ${result.message}` : "";
+    const detail = `${prefix}${target}${exitCode}${message}`;
+    log(`${detail} (step: ${stepId})`);
+    return detail;
+}
+async function applyStepValidation(metadata, compiled, packet, execution) {
+    if (execution.result.outcome.kind !== "success")
+        return execution;
+    const step = compiled.plan.steps.find((entry) => entry.id === packet.step_id);
+    if (!step) {
+        throw new Error(`compiled Step ${packet.step_id} disappeared before validation`);
+    }
+    const variables = {
+        ...metadata.variables,
+        round: String(packet.attempt_number),
+    };
+    let failure = null;
+    for (const completion of step.completion ?? []) {
+        const result = await runCompletionVerifier(completion, compiled.ir, {
+            projectDir: packet.workspace.working_directory,
+            variables,
+        });
+        if (!result.passed) {
+            failure = verifierFailureMessage("Completion failed", step.id, result);
+            break;
+        }
+    }
+    if (!failure) {
+        for (const checkpoint of step.checkpoints ?? []) {
+            const result = await runCheckpointVerifier(checkpoint, compiled.ir, {
+                projectDir: packet.workspace.working_directory,
+                variables,
+            });
+            if (result.passed)
+                continue;
+            const detail = verifierFailureMessage(`Checkpoint failed: ${checkpoint.assert}`, step.id, result);
+            if ((checkpoint.action ?? "block") === "block") {
+                failure = detail;
+                break;
+            }
+        }
+    }
+    if (!failure)
+        return execution;
+    return {
+        ...execution,
+        result: {
+            ...execution.result,
+            outputs: [],
+            outcome: {
+                kind: "malformed_result",
+                exit_code: 0,
+                signal: null,
+                error: failure,
+            },
+        },
+    };
 }
-// ── Step Execution ─────────────────────────────────────────
-async function recordStepResultEvidence(step, opts, sessionId, status, durationMs) {
-    const result = status === "pass" ? "success" : "failure";
-    await appendEvidenceCaptureEvent(opts.projectDir, {
+async function recordStepResultEvidence(metadata, packet, execution) {
+    const outcome = execution.result.outcome;
+    const succeeded = outcome.kind === "success";
+    const startedAt = Date.parse(execution.result.started_at);
+    const completedAt = Date.parse(execution.result.completed_at);
+    await appendEvidenceCaptureEvent(metadata.project_directory, {
         schema_version: EVIDENCE_CAPTURE_SCHEMA_VERSION,
         event_id: `c5:${randomUUID()}`,
-        captured_at: new Date().toISOString(),
-        project_root: opts.projectDir,
+        captured_at: execution.result.completed_at,
+        project_root: metadata.project_directory,
         source: "dna_cli",
-        workflow_asset: opts.workflowAsset ?? "unknown",
-        workflow_id: opts.workflowName,
-        run_id: sessionId,
-        step_id: step.id,
+        workflow_asset: metadata.workflow_asset ?? "unknown",
+        workflow_id: metadata.workflow_name,
+        run_id: packet.run_id,
+        step_id: packet.step_id,
         fact: "result",
-        summary: `dna run recorded ${result} for workflow step ${step.id}`,
-        result,
-        duration_ms: durationMs,
+        summary: `dna run recorded ${succeeded ? "success" : "failure"} for workflow step ${packet.step_id}`,
+        result: succeeded ? "success" : "failure",
+        exit_code: "exit_code" in outcome
+            ? outcome.exit_code ?? undefined
+            : undefined,
+        duration_ms: Number.isFinite(startedAt) && Number.isFinite(completedAt)
+            ? Math.max(0, completedAt - startedAt)
+            : undefined,
     });
 }
-/**
- * Execute a single workflow step via `claude -p --agent`.
- * Returns StepResult with pass/fail status.
- */
-export async function executeStep(step, vars, opts, iteration = 1) {
-    const start = Date.now();
-    const prompt = substituteTemplate(step.prompt ?? step.description, vars);
-    const agentName = `${opts.agentPrefix}${toKebabCase(step.role)}`;
-    const sessionId = randomUUID();
-    const resultFile = join(opts.logDir, `${step.id}-result.json`);
-    const stateManager = new DNAStateManager(opts.projectDir, sessionId);
-    let stateWritten = false;
-    const args = [
-        "-p",
-        "--agent",
-        agentName,
-        "--output-format",
-        "json",
-        "--max-budget-usd",
-        String(opts.maxBudget),
-        "--permission-mode",
-        opts.permissionMode,
-        "--session-id",
-        sessionId,
-        "--no-session-persistence",
-    ];
-    log(`Running step: ${step.id} (agent: ${agentName})`);
-    try {
+function createWorkspaceAwareExecutor(metadata, compiled, runStore) {
+    return async (packet, provider, options) => {
+        const workspace = allocateAttemptWorkspace(planAttemptWorkspace({
+            isolation: packet.workspace.isolation,
+            repository_directory: metadata.project_directory,
+            run_id: packet.run_id,
+            step_id: packet.step_id,
+            attempt_id: packet.attempt_id,
+        }));
+        const workerPacket = {
+            ...packet,
+            workspace: {
+                isolation: workspace.isolation,
+                working_directory: workspace.working_directory,
+            },
+        };
+        const state = new DNAStateManager(workspace.working_directory, packet.worker_session_id);
+        let lifecycleRecorded = false;
         try {
-            await stateManager.writeWorkflowState({
-                active: true,
-                workflow_asset: opts.workflowAsset,
-                workflow: opts.workflowName,
-                current_step: step.id,
-                current_role: step.role,
-                iteration,
-                session_id: sessionId,
-                started_at: new Date(start).toISOString(),
-                inputs: opts.inputs,
-                resolved_variables: vars,
+            await syncAttemptRuntimeArtifacts(compiled, metadata, workspace);
+            try {
+                await state.writeWorkflowState({
+                    active: true,
+                    workflow_asset: metadata.workflow_asset ?? undefined,
+                    workflow: metadata.workflow_name,
+                    current_step: packet.step_id,
+                    current_role: packet.role,
+                    iteration: packet.attempt_number,
+                    session_id: packet.worker_session_id,
+                    worker_session_id: packet.worker_session_id,
+                    run_id: packet.run_id,
+                    step_id: packet.step_id,
+                    attempt_id: packet.attempt_id,
+                    started_at: packet.created_at,
+                    inputs: { ...metadata.variables },
+                    resolved_variables: {
+                        ...metadata.variables,
+                        round: String(packet.attempt_number),
+                    },
+                });
+            }
+            catch (error) {
+                log(`Workflow evidence state unavailable for ${packet.step_id}; `
+                    + `continuing fail-open: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            const inheritedProcessObserver = options?.onProcessStart;
+            let execution = await executeWorkerAttempt(workerPacket, provider, {
+                ...options,
+                onProcessStart: async (processId) => {
+                    await recordAttemptProcess(runStore, workerPacket, processId);
+                    await inheritedProcessObserver?.(processId);
+                },
             });
-            stateWritten = true;
+            execution = await applyStepValidation(metadata, compiled, workerPacket, execution);
+            await recordStepResultEvidence(metadata, workerPacket, execution);
+            const reason = execution.result.outcome.kind === "cancelled"
+                ? "attempt_cancelled"
+                : execution.result.outcome.kind === "success"
+                    ? preservationReason(workerPacket)
+                    : "attempt_failed";
+            preserveWorkspace(workspace, reason, `attempt outcome: ${execution.result.outcome.kind}`);
+            lifecycleRecorded = true;
+            return execution;
         }
         catch (error) {
-            log(`Workflow evidence state unavailable for ${step.id}; continuing fail-open: ${error instanceof Error ? error.message : String(error)}`);
-        }
-        const output = await spawnAsync("claude", args, prompt, opts.projectDir);
-        await writeFile(resultFile, output, "utf-8");
-        // Check for error in JSON output
-        let isError = false;
-        try {
-            const parsed = JSON.parse(output);
-            isError = parsed.is_error === true;
-        }
-        catch {
-            // Non-JSON output → treat as success
-        }
-        const status = isError ? "fail" : "pass";
-        if (status === "pass" && step.completion && step.completion.length > 0) {
-            const completionsPassed = await runCompletions(step, vars, opts);
-            if (!completionsPassed) {
-                const durationMs = Date.now() - start;
-                await recordStepResultEvidence(step, opts, sessionId, "fail", durationMs);
-                log(`Step ${step.id} COMPLETION_FAIL (${durationMs}ms)`);
-                return { stepId: step.id, status: "fail", durationMs, resultFile };
-            }
-        }
-        if (status === "pass" && step.checkpoints && step.checkpoints.length > 0) {
-            const checkpointsPassed = await runCheckpoints(step, vars, opts);
-            if (!checkpointsPassed) {
-                const durationMs = Date.now() - start;
-                await recordStepResultEvidence(step, opts, sessionId, "fail", durationMs);
-                log(`Step ${step.id} CHECKPOINT_FAIL (${durationMs}ms)`);
-                return { stepId: step.id, status: "fail", durationMs, resultFile };
+            if (!lifecycleRecorded) {
+                preserveWorkspace(workspace, "controller_policy", `attempt launch failed: ${error instanceof Error ? error.message : String(error)}`);
             }
+            throw error;
         }
-        const durationMs = Date.now() - start;
-        await recordStepResultEvidence(step, opts, sessionId, status, durationMs);
-        log(`Step ${step.id} ${status.toUpperCase()} (${durationMs}ms)`);
-        return { stepId: step.id, status, durationMs, resultFile };
-    }
-    catch {
-        const durationMs = Date.now() - start;
-        await recordStepResultEvidence(step, opts, sessionId, "fail", durationMs);
-        log(`Step ${step.id} FAIL (process error, ${durationMs}ms)`);
-        return { stepId: step.id, status: "fail", durationMs };
-    }
-    finally {
-        if (stateWritten) {
+        finally {
             try {
-                await stateManager.clearWorkflowState();
+                await state.cleanup();
             }
             catch (error) {
-                log(`Workflow evidence state cleanup failed for ${step.id}; continuing fail-open: ${error instanceof Error ? error.message : String(error)}`);
-            }
-        }
-    }
-}
-/**
- * Execute a parallel group of steps.
- */
-export async function executeGroup(group, allSteps, round, vars, opts) {
-    const steps = group.step_ids
-        .map((id) => allSteps.find((s) => s.id === id))
-        .filter(Boolean);
-    const results = [];
-    for (const step of steps) {
-        // Evaluate run_if condition
-        if (!evaluateRunIf(step.run_if, round)) {
-            log(`Skipping step: ${step.id} (run_if: ${step.run_if}, round: ${round})`);
-            results.push({ stepId: step.id, status: "skipped", durationMs: 0 });
-            continue;
-        }
-        // Collect for execution
-        results.push(step); // placeholder, replaced below
-    }
-    // Filter executable steps
-    const executable = steps.filter((s) => evaluateRunIf(s.run_if, round));
-    if (executable.length === 0)
-        return results.filter((r) => r.status === "skipped");
-    // Single step: sequential
-    if (executable.length === 1) {
-        const result = await executeStep(executable[0], vars, opts, round);
-        const skipped = results.filter((r) => r.status === "skipped");
-        return [...skipped, result];
-    }
-    // Multiple steps: parallel
-    log(`Running ${executable.length} steps in parallel`);
-    const parallelResults = await Promise.all(executable.map((step) => executeStep(step, vars, opts, round)));
-    const skipped = results.filter((r) => r.status === "skipped");
-    return [...skipped, ...parallelResults];
-}
-/**
- * Check if any transition requires retry.
- */
-export function checkRetryNeeded(stepResults, transitions) {
-    for (const t of transitions) {
-        if (t.condition === "fail") {
-            const result = stepResults.get(t.from);
-            if (result && result.status === "fail") {
-                return true;
+                log(`Worker Hook state cleanup failed for ${packet.worker_session_id}: `
+                    + `${error instanceof Error ? error.message : String(error)}`);
             }
         }
-    }
-    return false;
+    };
 }
-// ── Spawn Helper ───────────────────────────────────────────
-function spawnAsync(command, args, stdinData, cwd) {
-    return new Promise((resolve, reject) => {
-        const child = spawn(command, args, {
-            stdio: ["pipe", "pipe", "pipe"],
-            cwd,
-        });
-        let stdout = "";
-        let stderr = "";
-        child.stdout.on("data", (data) => {
-            stdout += data.toString();
-        });
-        child.stderr.on("data", (data) => {
-            stderr += data.toString();
-            // Stream stderr in real-time
-            process.stderr.write(data);
-        });
-        child.on("error", reject);
-        child.on("close", (code) => {
-            if (code !== 0 && stdout === "") {
-                reject(new Error(`claude exited with code ${code}: ${stderr}`));
-            }
-            else {
-                resolve(stdout);
-            }
-        });
-        child.stdin.write(stdinData);
-        child.stdin.end();
+function buildRuntime(metadata, compiled) {
+    const runStore = new DurableRunStore({
+        root_directory: runtimeRoot(metadata.project_directory),
+    });
+    const resultStore = new ImmutableResultStore(runStore);
+    const resolver = new HandoffResolver(resultStore);
+    const provider = createProvider(metadata);
+    const controller = new RunController({
+        run_store: runStore,
+        handoff_resolver: resolver,
+        steps: compiled.definitions,
+        provider_for_step: () => provider,
+        reconcile_attempt: reconcileLocalProcess,
+        execute_attempt: createWorkspaceAwareExecutor(metadata, compiled, runStore),
+        max_concurrency: metadata.max_concurrency,
+        lease_duration_ms: 15_000,
+        lease_heartbeat_ms: 3_000,
+        scheduler_poll_ms: 50,
     });
+    return { run_store: runStore, controller };
 }
-// ── Logging ────────────────────────────────────────────────
-function log(msg) {
-    const ts = new Date().toLocaleTimeString("en-US", { hour12: false });
-    process.stderr.write(`[${ts}] ${msg}\n`);
+function buildCancellationController(runStore) {
+    return new RunController({
+        run_store: runStore,
+        steps: [],
+        provider_for_step: () => {
+            throw new Error("cancellation-only Controller cannot launch a Step");
+        },
+        reconcile_attempt: reconcileLocalProcess,
+        max_concurrency: 1,
+        lease_duration_ms: 15_000,
+        lease_heartbeat_ms: 3_000,
+        scheduler_poll_ms: 50,
+    });
 }
-// ── Main Entry ─────────────────────────────────────────────
-export async function runRun(opts) {
-    // Validate required inputs
+async function startMetadata(opts, projectDirectory) {
     if (opts.dnaFiles.length === 0) {
-        process.stderr.write("Error: --dna requires at least one DNA file\n");
-        return 2;
+        throw new RunUsageError("--dna requires at least one DNA file");
     }
-    if (!opts.workflowName) {
-        process.stderr.write("Error: --workflow is required\n");
-        return 2;
+    const workflowName = requireText(opts.workflowName, "--workflow");
+    const taskId = requireText(opts.taskId, "--task");
+    const expanded = await expandDNAInputFiles(opts.dnaFiles, {
+        cwd: projectDirectory,
+    });
+    if (expanded.length === 0) {
+        throw new RunUsageError("--dna did not resolve any DNA files");
+    }
+    const variables = {
+        ...(opts.vars ?? {}),
+        task_id: taskId,
+        ARGUMENTS: taskId,
+        workflow: workflowName,
+    };
+    const maxBudget = requirePositiveNumber(opts.maxBudget ?? 5, "--max-budget");
+    const maxConcurrency = requirePositiveInteger(opts.maxConcurrency ?? 1, "--max-concurrency");
+    const timeoutMs = opts.timeoutMs === null || opts.timeoutMs === undefined
+        ? null
+        : requireNonNegativeInteger(opts.timeoutMs, "--timeout-ms");
+    const cancellationGraceMs = requireNonNegativeInteger(opts.cancellationGraceMs ?? 5_000, "--cancellation-grace-ms");
+    const permissionMode = requireText(opts.permissionMode ?? "default", "--permission-mode");
+    return {
+        schema_version: "intentdna.canonical_run.v1",
+        project_directory: projectDirectory,
+        dna_files: expanded.map((file) => resolve(projectDirectory, file)),
+        workflow_name: workflowName,
+        task_id: taskId,
+        context: opts.context ?? null,
+        variables,
+        agents_directory: opts.agentsDir
+            ? resolve(projectDirectory, opts.agentsDir)
+            : join(projectDirectory, ".claude", "agents"),
+        provider: {
+            kind: opts.provider ?? "claude",
+            executable: opts.providerExecutable === undefined
+                ? null
+                : requireText(opts.providerExecutable, "--provider-executable"),
+            max_budget_usd: maxBudget,
+            permission_mode: permissionMode,
+        },
+        max_concurrency: maxConcurrency,
+        timeout_ms: timeoutMs,
+        cancellation_grace_ms: cancellationGraceMs,
+        workflow_asset: null,
+    };
+}
+async function runtimeForExistingRun(runStore, runId, projectDirectory) {
+    const snapshot = await runStore.requireRun(runId);
+    const metadata = readCanonicalMetadata(snapshot.run.metadata);
+    if (resolve(metadata.project_directory) !== projectDirectory) {
+        throw new Error(`run ${runId} belongs to project ${metadata.project_directory}, not ${projectDirectory}`);
     }
-    if (!opts.taskId) {
-        process.stderr.write("Error: --task is required\n");
-        return 2;
+    const compiled = await compileCanonicalRun(metadata);
+    if (compiled.plan_digest !== snapshot.run.plan_digest) {
+        throw new Error(`run ${runId} plan digest changed; resume requires the original DNA and role definitions`);
     }
-    const maxBudget = opts.maxBudget ?? 5;
-    const permissionMode = opts.permissionMode ?? "default";
-    const projectDir = resolve(opts.projectDir ?? process.cwd());
-    const agentsDir = opts.agentsDir ? resolve(projectDir, opts.agentsDir) : join(projectDir, ".claude", "agents");
+    await syncRuntimeArtifacts(compiled, metadata);
+    return buildRuntime(metadata, compiled);
+}
+// ── CLI entry ──────────────────────────────────────────────
+export async function runRun(opts) {
+    const action = opts.action ?? "start";
+    const projectDirectory = resolve(opts.projectDir ?? process.cwd());
+    const runStore = new DurableRunStore({
+        root_directory: runtimeRoot(projectDirectory),
+    });
     try {
-        // ── Step 1: Load & compile DNA ───────────────────────
-        log("Loading DNA files...");
-        const expandedDNAFiles = await expandDNAInputFiles(opts.dnaFiles, { cwd: projectDir });
-        const dnas = await Promise.all(expandedDNAFiles.map(loadDNA));
-        const cascaded = cascadeDNA(dnas);
-        const ir = await compileFromFiles(expandedDNAFiles, {
-            context: opts.context,
-        });
-        // ── Step 2: Find & compile workflow ──────────────────
-        const wfDef = cascaded.workflows[opts.workflowName];
-        if (!wfDef) {
-            process.stderr.write(`Error: Workflow '${opts.workflowName}' not found. Available: ${Object.keys(cascaded.workflows).join(", ") || "(none)"}\n`);
-            return 1;
+        if (action !== "start"
+            && action !== "status"
+            && action !== "inspect"
+            && action !== "resume"
+            && action !== "cancel") {
+            throw new RunUsageError(`unsupported run action '${String(action)}'`);
         }
-        const wfResult = compileWorkflow(wfDef, { workflow_key: opts.workflowName });
-        if (!wfResult.ok) {
-            process.stderr.write(`Error: Workflow compilation failed:\n`);
-            for (const err of wfResult.errors) {
-                process.stderr.write(`  ${err.path}: ${err.message}\n`);
-            }
-            return 1;
+        if (action === "status") {
+            return runLifecycleStatus({
+                run_store: runStore,
+                run_id: asRunId(requireText(opts.runId, "run_id")),
+                json: opts.json,
+            });
         }
-        const plan = wfResult.plan;
-        log(`Compiled workflow: ${plan.name} (${plan.steps.length} steps, ${plan.parallel_groups.length} groups)`);
-        // ── Step 3: Build template variables ─────────────────
-        const vars = {
-            ...(opts.vars ?? {}),
-            task_id: opts.taskId,
-            ARGUMENTS: opts.taskId,
-            workflow: opts.workflowName,
-        };
-        // ── Dry-run mode ─────────────────────────────────────
+        if (action === "inspect") {
+            return runLifecycleInspect({
+                run_store: runStore,
+                run_id: asRunId(requireText(opts.runId, "run_id")),
+                json: opts.json,
+            });
+        }
+        if (action === "resume") {
+            const runId = asRunId(requireText(opts.runId, "run_id"));
+            const runtime = await runtimeForExistingRun(runStore, runId, projectDirectory);
+            return runLifecycleResume({
+                controller: runtime.controller,
+                run_id: runId,
+                json: opts.json,
+            });
+        }
+        if (action === "cancel") {
+            const runId = asRunId(requireText(opts.runId, "run_id"));
+            return runLifecycleCancel({
+                controller: buildCancellationController(runStore),
+                run_id: runId,
+                reason: opts.reason,
+                json: opts.json,
+            });
+        }
+        const initialMetadata = await startMetadata(opts, projectDirectory);
         if (opts.dryRun) {
-            return printDryRun(plan, vars);
+            const firstPreview = await compileRunAssets(initialMetadata);
+            const previewMetadata = {
+                ...initialMetadata,
+                workflow_asset: firstPreview.workflow_asset,
+            };
+            const preview = previewMetadata.workflow_asset
+                === initialMetadata.workflow_asset
+                ? firstPreview
+                : await compileRunAssets(previewMetadata);
+            return printDryRun(preview.plan, previewMetadata, preview.plan_digest);
         }
-        // ── Step 4: Auto-sync agents & hooks ─────────────────
-        log("Syncing agents and hooks...");
-        const agentResults = compileAllRolesToAgentMD(cascaded.roles, ir);
-        await writeAgentMDFiles(agentResults, agentsDir);
-        log(`Generated ${agentResults.length} agent file(s) in ${agentsDir}`);
-        const hookScripts = createCompiledIR(ir, cascaded.roles);
-        await writeCompiledIR(projectDir, hookScripts);
-        log("Synced compiled IR for dna-hook enforcement");
-        // ── Step 5: Prepare log directory ────────────────────
-        const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
-        const logDir = opts.logDir
-            ? resolve(projectDir, opts.logDir)
-            : join(projectDir, ".intentdna", "runs", `${opts.workflowName}-${timestamp}`);
-        await mkdir(logDir, { recursive: true });
-        const attribution = trustedEvidenceCaptureAttribution(ir, { workflowId: opts.workflowName });
-        const execOpts = {
-            agentPrefix: "dna-",
-            maxBudget,
-            permissionMode,
-            logDir,
-            projectDir,
-            workflowName: opts.workflowName,
-            workflowAsset: attribution.workflowAsset === "unknown" ? undefined : attribution.workflowAsset,
-            inputs: {
-                ...(opts.vars ?? {}),
-                task_id: opts.taskId,
-                ARGUMENTS: opts.taskId,
-                workflow: opts.workflowName,
-            },
-            ir,
+        const firstCompilation = await compileCanonicalRun(initialMetadata);
+        const metadata = {
+            ...initialMetadata,
+            workflow_asset: firstCompilation.workflow_asset,
         };
-        // ── Step 6: Execute workflow ──────────────────────────
-        const maxRetries = plan.retry.max_retries;
-        const allTransitions = [...plan.transitions, ...plan.default_transitions];
-        const stepResults = new Map();
-        let round = 1;
-        while (round <= maxRetries + 1) {
-            log(`\n=== Round ${round}/${maxRetries + 1} ===`);
-            // Update round variable for templates
-            const roundVars = { ...vars, round: String(round) };
-            for (const group of plan.parallel_groups) {
-                const groupResults = await executeGroup(group, plan.steps, round, roundVars, execOpts);
-                // Store results
-                for (const result of groupResults) {
-                    stepResults.set(result.stepId, result);
-                }
-                // Check for non-optional step failure (abort group execution)
-                for (const result of groupResults) {
-                    if (result.status === "fail") {
-                        const step = plan.steps.find((s) => s.id === result.stepId);
-                        if (step && !step.optional) {
-                            // Check if there's a fail transition for this step
-                            const hasFailTransition = allTransitions.some((t) => t.from === result.stepId && t.condition === "fail");
-                            if (!hasFailTransition) {
-                                log(`Non-optional step '${result.stepId}' failed with no fail transition — aborting`);
-                                return printSummary(stepResults, round, logDir, 1);
-                            }
-                        }
-                    }
-                }
-            }
-            // Check if retry needed
-            if (checkRetryNeeded(stepResults, allTransitions)) {
-                if (round >= maxRetries + 1) {
-                    log(`Max retries (${maxRetries}) exhausted`);
-                    return printSummary(stepResults, round, logDir, 1);
-                }
-                log("Retry triggered by fail transition");
-                round++;
-                continue;
-            }
-            // All passed
-            break;
-        }
-        return printSummary(stepResults, round, logDir, 0);
+        const compiled = metadata.workflow_asset === initialMetadata.workflow_asset
+            ? firstCompilation
+            : await compileCanonicalRun(metadata);
+        await syncRuntimeArtifacts(compiled, metadata);
+        const runtime = buildRuntime(metadata, compiled);
+        const now = new Date().toISOString();
+        const runId = opts.runId?.trim()
+            ? asRunId(opts.runId)
+            : `run_${randomUUID()}`;
+        const run = {
+            run_id: runId,
+            workflow_id: metadata.workflow_name,
+            workflow_version: null,
+            plan_digest: compiled.plan_digest,
+            status: "active",
+            cancellation: null,
+            terminal: null,
+            metadata: metadata,
+            created_at: now,
+            updated_at: now,
+        };
+        return runLifecycleStart({
+            controller: runtime.controller,
+            run,
+            json: opts.json,
+        });
     }
-    catch (err) {
-        process.stderr.write(`Fatal: ${err instanceof Error ? err.message : String(err)}\n`);
-        return 1;
+    catch (error) {
+        const usage = error instanceof RunUsageError;
+        process.stderr.write(`${usage ? "Usage error" : "Error"}: `
+            + `${error instanceof Error ? error.message : String(error)}\n`);
+        return usage ? 2 : 1;
     }
 }
-// ── Output Helpers ─────────────────────────────────────────
-function printDryRun(plan, vars) {
-    process.stderr.write("\n=== DRY RUN — Execution Plan ===\n\n");
+function printDryRun(plan, metadata, digest) {
+    process.stderr.write("\n=== DRY RUN - Canonical Controller Plan ===\n\n");
     process.stderr.write(`Workflow: ${plan.name}\n`);
-    process.stderr.write(`Steps: ${plan.steps.length}\n`);
+    process.stderr.write(`Plan digest: ${digest}\n`);
+    process.stderr.write(`Provider: ${metadata.provider.kind}\n`);
+    process.stderr.write(`Max concurrency: ${metadata.max_concurrency}\n`);
+    process.stderr.write(`Durable root: ${runtimeRoot(metadata.project_directory)}\n`);
+    process.stderr.write(`Steps: ${plan.steps.length}\n\n`);
     process.stderr.write(`Groups: ${plan.parallel_groups.length}\n`);
     process.stderr.write(`Max retries: ${plan.retry.max_retries}\n`);
     if (plan.retry.retry_from) {
         process.stderr.write(`Retry from: ${plan.retry.retry_from}\n`);
     }
-    process.stderr.write(`Variables: ${JSON.stringify(vars)}\n`);
-    process.stderr.write("\nExecution order:\n");
+    process.stderr.write(`Variables: ${JSON.stringify(metadata.variables)}\n\n`);
     for (const group of plan.parallel_groups) {
-        const parallel = group.step_ids.length > 1 ? " (parallel)" : "";
-        process.stderr.write(`\n  Group ${group.group_index + 1}${parallel}:\n`);
+        process.stderr.write(`Group ${group.group_index + 1} (${group.isolation}):\n`);
         for (const stepId of group.step_ids) {
-            const step = plan.steps.find((s) => s.id === stepId);
-            const prompt = substituteTemplate(step.prompt ?? step.description, vars);
+            const step = plan.steps.find((entry) => entry.id === stepId);
+            if (!step)
+                continue;
+            const prompt = substituteTemplate(step.prompt ?? step.description, metadata.variables);
             const runIf = step.run_if ? ` [run_if: ${step.run_if}]` : "";
             const optional = step.optional ? " (optional)" : "";
-            process.stderr.write(`    - ${step.id} → agent: dna-${toKebabCase(step.role)}${runIf}${optional}\n`);
-            process.stderr.write(`      prompt: ${prompt.slice(0, 120)}${prompt.length > 120 ? "..." : ""}\n`);
+            process.stderr.write(`  - ${step.id} -> agent: dna-${toKebabCase(step.role)}`
+                + `${runIf}${optional}; independent session\n`);
+            process.stderr.write(`    prompt: ${prompt.slice(0, 120)}${prompt.length > 120 ? "..." : ""}\n`);
         }
     }
     if (plan.transitions.length > 0) {
         process.stderr.write("\nTransitions:\n");
-        for (const t of plan.transitions) {
-            process.stderr.write(`    ${t.from} → ${t.to} (on ${t.condition})\n`);
+        for (const transition of plan.transitions) {
+            process.stderr.write(`  ${transition.from} -> ${transition.to} `
+                + `(on ${transition.condition})\n`);
         }
     }
     process.stderr.write("\n");
     return 0;
 }
-function printSummary(results, rounds, logDir, exitCode) {
-    process.stderr.write("\n=== Workflow Summary ===\n");
-    process.stderr.write(`Rounds executed: ${rounds}\n`);
-    process.stderr.write(`Log directory: ${logDir}\n\n`);
-    for (const [stepId, result] of results) {
-        const icon = result.status === "pass" ? "PASS" : result.status === "fail" ? "FAIL" : "SKIP";
-        const duration = result.durationMs > 0 ? ` (${(result.durationMs / 1000).toFixed(1)}s)` : "";
-        process.stderr.write(`  [${icon}] ${stepId}${duration}\n`);
-    }
-    const passed = [...results.values()].filter((r) => r.status === "pass").length;
-    const failed = [...results.values()].filter((r) => r.status === "fail").length;
-    const skipped = [...results.values()].filter((r) => r.status === "skipped").length;
-    process.stderr.write(`\nTotal: ${passed} passed, ${failed} failed, ${skipped} skipped\n`);
-    return exitCode;
+function log(message) {
+    const timestamp = new Date().toLocaleTimeString("en-US", { hour12: false });
+    process.stderr.write(`[${timestamp}] ${message}\n`);
 }