intentdna 1.9.0 → 1.9.3

package/dist/cli/commands/run-lifecycle.js

@@ -1,3 +1,4 @@
+import { LEGACY_RUN_STORE_SCHEMA_VERSION, RunStoreError, } from "../../runtime/run-store.js";
 class LifecycleUsageError extends Error {
     constructor(message) {
         super(message);
@@ -15,31 +16,44 @@ const TASK_STATES = [
     "skipped",
     "cancelled",
 ];
+const ACTIVATION_STATES = [
+    "dormant",
+    "dependency_blocked",
+    "ready",
+    "claimed",
+    "running",
+    "waiting_for_human",
+    "succeeded",
+    "failed",
+    "skipped",
+    "cancelled",
+];
 function requireText(value, label) {
-    if (!value.trim()) {
+    if (!value.trim())
         throw new LifecycleUsageError(`${label} is required`);
-    }
 }
 function requireRunId(runId) {
     requireText(runId, "run_id");
 }
+function validateReason(reason) {
+    if (reason !== null && !reason.trim()) {
+        throw new LifecycleUsageError("reason must not be empty");
+    }
+}
 function validateStartRun(run) {
     requireRunId(run.run_id);
     requireText(run.workflow_id, "workflow_id");
     requireText(run.plan_digest, "plan_digest");
     requireText(run.created_at, "created_at");
     requireText(run.updated_at, "updated_at");
-    if (run.status !== "active"
-        || run.cancellation !== null
-        || run.terminal !== null) {
+    if (run.status !== "active" || run.cancellation !== null || run.terminal !== null) {
         throw new LifecycleUsageError("start requires an active run without cancellation or terminal state");
     }
 }
-function statusProjection(snapshot) {
+function legacyStatusProjection(snapshot) {
     const taskCounts = Object.fromEntries(TASK_STATES.map((state) => [state, 0]));
-    for (const task of snapshot.tasks) {
+    for (const task of snapshot.tasks)
         taskCounts[task.state] += 1;
-    }
     return {
         schema_version: "intentdna.run_status.v1",
         run_id: snapshot.run.run_id,
@@ -56,14 +70,36 @@ function statusProjection(snapshot) {
         updated_at: snapshot.run.updated_at,
     };
 }
+export function canonicalViewStatusProjection(view) {
+    const activationCounts = Object.fromEntries(ACTIVATION_STATES.map((state) => [state, 0]));
+    for (const activation of view.activations) {
+        activationCounts[activation.state] += 1;
+    }
+    return {
+        schema_version: "intentdna.run_status.v2",
+        ledger_schema_version: 2,
+        run_id: view.run.run_id,
+        target: view.run.target,
+        plan_id: view.run.plan_id,
+        binding_id: view.run.run_binding.binding_id,
+        status: view.run.status,
+        record_version: view.record_version,
+        activation_counts: activationCounts,
+        attempt_count: view.attempts.length,
+        result_count: view.results.length,
+        cancellation: view.run.cancellation,
+        terminal: view.run.terminal,
+        created_at: view.run.created_at,
+        updated_at: view.run.updated_at,
+    };
+}
 function durableHandoffs(snapshot) {
     return snapshot.events.flatMap((event) => {
         if (event.type !== "handoff_resolved"
             || event.step_id === null
             || event.attempt_id === null
-            || event.worker_session_id === null) {
+            || event.worker_session_id === null)
             return [];
-        }
         return [{
                 event_id: event.event_id,
                 sequence: event.sequence,
@@ -77,7 +113,7 @@ function durableHandoffs(snapshot) {
             }];
     });
 }
-function inspectionProjection(snapshot) {
+function legacyInspectionProjection(snapshot) {
     return {
         schema_version: "intentdna.run_inspection.v1",
         record_version: snapshot.record_version,
@@ -92,13 +128,31 @@ function inspectionProjection(snapshot) {
         ledger_updated_at: snapshot.updated_at,
     };
 }
+function canonicalInspectionProjection(view) {
+    return {
+        schema_version: "intentdna.run_inspection.v2",
+        ledger_schema_version: 2,
+        record_version: view.record_version,
+        run: view.run,
+        activations: view.activations,
+        attempts: view.attempts,
+        claims: view.claims.map((claim) => {
+            const { claim_token: _claimToken, ...publicClaim } = claim;
+            return publicClaim;
+        }),
+        events: view.events,
+        result_refs: view.results,
+        ledger_created_at: view.ledger.created_at,
+        ledger_updated_at: view.ledger.updated_at,
+    };
+}
 function writeJson(value) {
     process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
 }
-function nonZeroTaskCounts(counts) {
-    const summary = TASK_STATES
-        .filter((state) => counts[state] > 0)
-        .map((state) => `${state}=${counts[state]}`)
+function nonZeroCounts(counts) {
+    const summary = Object.entries(counts)
+        .filter(([, count]) => count > 0)
+        .map(([state, count]) => `${state}=${count}`)
         .join(", ");
     return summary || "none";
 }
@@ -106,10 +160,16 @@ function writeHumanStatus(status, action) {
     if (action)
         process.stdout.write(`Action: ${action}\n`);
     process.stdout.write(`Run: ${status.run_id}\n`);
-    process.stdout.write(`Workflow: ${status.workflow_id}\n`);
+    if (status.schema_version === "intentdna.run_status.v1") {
+        process.stdout.write(`Workflow: ${status.workflow_id}\n`);
+        process.stdout.write(`Tasks: ${nonZeroCounts(status.task_counts)}\n`);
+    }
+    else {
+        process.stdout.write(`Target: ${status.target.kind}:${status.target.key}\n`);
+        process.stdout.write(`Activations: ${nonZeroCounts(status.activation_counts)}\n`);
+    }
     process.stdout.write(`Status: ${status.status}\n`);
     process.stdout.write(`Ledger version: ${status.record_version}\n`);
-    process.stdout.write(`Tasks: ${nonZeroTaskCounts(status.task_counts)}\n`);
     process.stdout.write(`Attempts: ${status.attempt_count}; results: ${status.result_count}\n`);
     if (status.cancellation) {
         process.stdout.write(`Cancellation: ${status.cancellation.requested_at}`
@@ -121,52 +181,93 @@ function writeHumanStatus(status, action) {
     }
 }
 function writeInspection(snapshot, json) {
-    const projection = inspectionProjection(snapshot);
+    const projection = legacyInspectionProjection(snapshot);
     if (json) {
         writeJson(projection);
         return;
     }
-    writeHumanStatus(statusProjection(snapshot));
+    writeHumanStatus(legacyStatusProjection(snapshot));
+    const attempts = projection.attempts;
     process.stdout.write("\nAttempts:\n");
-    if (projection.attempts.length === 0) {
+    if (attempts.length === 0)
         process.stdout.write("  (none)\n");
-    }
-    for (const attempt of projection.attempts) {
+    for (const attempt of attempts) {
         process.stdout.write(`  ${attempt.attempt_id} step=${attempt.step_id}`
             + ` worker=${attempt.worker_session_id} phase=${attempt.phase}`
             + ` pid=${attempt.process_id ?? "-"}`
             + ` outcome=${attempt.terminal_outcome?.kind ?? "none"}\n`);
     }
     process.stdout.write("\nResolved handoffs:\n");
-    if (projection.handoffs.length === 0) {
+    if (projection.handoffs.length === 0)
         process.stdout.write("  (none)\n");
-    }
     for (const handoff of projection.handoffs) {
         process.stdout.write(`  attempt=${handoff.attempt_id} worker=${handoff.worker_session_id}`
             + ` binding=${JSON.stringify(handoff.binding)}\n`);
     }
     process.stdout.write("\nCommitted results:\n");
-    if (projection.results.length === 0) {
+    if (projection.results.length === 0)
         process.stdout.write("  (none)\n");
-    }
     for (const result of projection.results) {
         process.stdout.write(`  ${result.result_id} attempt=${result.attempt_id}`
             + ` worker=${result.worker_session_id}`
             + ` outputs=${JSON.stringify(result.outputs)}\n`);
     }
     process.stdout.write("\nEvents:\n");
-    if (projection.events.length === 0) {
+    if (projection.events.length === 0)
         process.stdout.write("  (none)\n");
+    for (const event of projection.events) {
+        process.stdout.write(`  ${event.sequence} ${event.type}`
+            + ` step=${event.step_id ?? "-"} attempt=${event.attempt_id ?? "-"}`
+            + ` payload=${JSON.stringify(event.payload)}\n`);
+    }
+}
+function writeCanonicalInspection(view, json) {
+    const projection = canonicalInspectionProjection(view);
+    if (json) {
+        writeJson(projection);
+        return;
     }
+    writeHumanStatus(canonicalViewStatusProjection(view));
+    process.stdout.write("\nAttempts:\n");
+    if (projection.attempts.length === 0)
+        process.stdout.write("  (none)\n");
+    for (const attempt of projection.attempts) {
+        const executor = attempt.executor?.kind ?? "unattached";
+        process.stdout.write(`  ${attempt.attempt_id} step=${attempt.step_id}`
+            + ` activation=${attempt.activation_id}`
+            + ` executor=${executor} phase=${attempt.phase}`
+            + ` outcome=${attempt.terminal_outcome?.kind ?? "none"}\n`);
+    }
+    process.stdout.write("\nResult references:\n");
+    if (projection.result_refs.length === 0)
+        process.stdout.write("  (none)\n");
+    for (const result of projection.result_refs) {
+        process.stdout.write(`  ${result.result_id} activation=${result.activation_id}`
+            + ` attempt=${result.attempt_id} digest=${result.result_digest}\n`);
+    }
+    process.stdout.write("\nEvents:\n");
+    if (projection.events.length === 0)
+        process.stdout.write("  (none)\n");
     for (const event of projection.events) {
         process.stdout.write(`  ${event.sequence} ${event.type}`
             + ` step=${event.step_id ?? "-"} attempt=${event.attempt_id ?? "-"}`
-            + ` worker=${event.worker_session_id ?? "-"}`
             + ` payload=${JSON.stringify(event.payload)}\n`);
     }
 }
-function writeOperation(action, snapshot, json) {
-    const status = statusProjection(snapshot);
+function writeLegacyOperation(action, snapshot, json) {
+    const status = legacyStatusProjection(snapshot);
+    if (json) {
+        writeJson({
+            schema_version: "intentdna.run_lifecycle_operation.v1",
+            action,
+            status,
+        });
+        return;
+    }
+    writeHumanStatus(status, action);
+}
+export function writeCanonicalOperation(action, view, json) {
+    const status = canonicalViewStatusProjection(view);
     if (json) {
         writeJson({
             schema_version: "intentdna.run_lifecycle_operation.v1",
@@ -180,6 +281,15 @@ function writeOperation(action, snapshot, json) {
 function operationExitCode(snapshot) {
     return snapshot.run.status === "failed" ? 1 : 0;
 }
+function canonicalOperationExitCode(view) {
+    return view.run.status === "failed" ? 1 : 0;
+}
+async function requireCanonicalService(options) {
+    const service = options.service ?? await options.service_factory?.();
+    if (!service)
+        throw new LifecycleUsageError("canonical run operation requires a service");
+    return service;
+}
 async function handle(operation) {
     try {
         return await operation();
@@ -190,20 +300,13 @@ async function handle(operation) {
         return error instanceof LifecycleUsageError ? 2 : 1;
     }
 }
-export async function runLifecycleStart(options) {
-    return handle(async () => {
-        validateStartRun(options.run);
-        await options.controller.createRun({ run: options.run });
-        const snapshot = await options.controller.runUntilTerminal(options.run.run_id);
-        writeOperation("start", snapshot, options.json === true);
-        return operationExitCode(snapshot);
-    });
-}
 export async function runLifecycleStatus(options) {
     return handle(async () => {
         requireRunId(options.run_id);
-        const snapshot = await options.run_store.requireRun(options.run_id);
-        const projection = statusProjection(snapshot);
+        const stored = await options.run_store.requireAnyRun(options.run_id);
+        const projection = stored.schema_version === LEGACY_RUN_STORE_SCHEMA_VERSION
+            ? legacyStatusProjection(stored)
+            : canonicalViewStatusProjection(await (await requireCanonicalService(options)).inspect(options.run_id));
         if (options.json === true)
             writeJson(projection);
         else
@@ -214,28 +317,59 @@ export async function runLifecycleStatus(options) {
 export async function runLifecycleInspect(options) {
     return handle(async () => {
         requireRunId(options.run_id);
-        const snapshot = await options.run_store.requireRun(options.run_id);
-        writeInspection(snapshot, options.json === true);
+        const stored = await options.run_store.requireAnyRun(options.run_id);
+        if (stored.schema_version === LEGACY_RUN_STORE_SCHEMA_VERSION) {
+            writeInspection(stored, options.json === true);
+        }
+        else {
+            const audit = await (await requireCanonicalService(options)).inspectAudit(options.run_id);
+            writeCanonicalInspection(audit, options.json === true);
+        }
         return 0;
     });
 }
 export async function runLifecycleResume(options) {
     return handle(async () => {
         requireRunId(options.run_id);
-        const snapshot = await options.controller.runUntilTerminal(options.run_id);
-        writeOperation("resume", snapshot, options.json === true);
-        return operationExitCode(snapshot);
+        const stored = await options.run_store.requireAnyRun(options.run_id);
+        if (stored.schema_version === LEGACY_RUN_STORE_SCHEMA_VERSION) {
+            throw new RunStoreError("unsupported_legacy_run", `unsupported_legacy_run: legacy run ${options.run_id} cannot resume through the canonical scheduler`);
+        }
+        const service = await requireCanonicalService(options);
+        const view = options.drive
+            ? await options.drive(service, options.run_id)
+            : await service.resume(options.run_id);
+        writeCanonicalOperation("resume", view, options.json === true);
+        return canonicalOperationExitCode(view);
     });
 }
 export async function runLifecycleCancel(options) {
     return handle(async () => {
         requireRunId(options.run_id);
         const reason = options.reason ?? null;
-        if (reason !== null && !reason.trim()) {
-            throw new LifecycleUsageError("reason must not be empty");
+        validateReason(reason);
+        const stored = await options.run_store.requireAnyRun(options.run_id);
+        if (stored.schema_version === LEGACY_RUN_STORE_SCHEMA_VERSION) {
+            const snapshot = await options.run_store.cancelLegacyRun(options.run_id, reason);
+            writeLegacyOperation("cancel", snapshot, options.json === true);
+            return 0;
+        }
+        const view = await (await requireCanonicalService(options)).cancel(options.run_id, reason);
+        writeCanonicalOperation("cancel", view, options.json === true);
+        return 0;
+    });
+}
+export async function runLifecycleClose(options) {
+    return handle(async () => {
+        requireRunId(options.run_id);
+        const reason = options.reason ?? null;
+        validateReason(reason);
+        const stored = await options.run_store.requireAnyRun(options.run_id);
+        if (stored.schema_version !== LEGACY_RUN_STORE_SCHEMA_VERSION) {
+            throw new Error(`unsupported: canonical run ${options.run_id} does not support close`);
         }
-        const snapshot = await options.controller.requestCancellation(options.run_id, reason);
-        writeOperation("cancel", snapshot, options.json === true);
+        const snapshot = await options.run_store.closeLegacyRun(options.run_id, reason);
+        writeLegacyOperation("close", snapshot, options.json === true);
         return 0;
     });
 }

package/dist/cli/commands/run-observer.d.ts

@@ -0,0 +1,15 @@
+import type { RunView } from "../../runtime/canonical-run-service.js";
+import type { CanonicalRuntimeProjection, CanonicalTarget } from "../../runtime/canonical-target-compiler.js";
+import { type CompiledIRFile } from "../../runtime/plugin-adapter.js";
+import type { PushDriverAttemptContext, PushDriverAttemptLifecycleHooks } from "../../runtime/push-driver.js";
+export interface ObservedCanonicalRunMetadata {
+    readonly project_directory: string;
+    readonly target: CanonicalTarget;
+    readonly task_id: string;
+    readonly workflow_asset: string | null;
+    readonly runtime_projection: CompiledIRFile;
+}
+export declare function durableRuntimeProjection(projection: CanonicalRuntimeProjection): CompiledIRFile;
+export declare function syncRuntimeProjection(projectDirectory: string, agentsDirectory: string, projection: CanonicalRuntimeProjection, compiled: CompiledIRFile): Promise<void>;
+export declare function createRunAttemptObservers(readMetadata: (context: PushDriverAttemptContext) => ObservedCanonicalRunMetadata): PushDriverAttemptLifecycleHooks;
+export declare function writeTerminalDriverFailure(view: RunView): void;

package/dist/cli/commands/run-observer.js

@@ -0,0 +1,210 @@
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { DNAStateManager } from "../../hooks/state-manager.js";
+import { appendEvidenceCaptureEvent, EVIDENCE_CAPTURE_SCHEMA_VERSION, writeCanonicalHookRuntimeProjection, } from "../../hooks/state.js";
+import { compileAllRolesToAgentMD, writeAgentMDFiles } from "../../runtime/agent-md.js";
+import { durableCanonicalRuntimeProjection } from "../../runtime/canonical-runtime-projection.js";
+import { writeCompiledIR, } from "../../runtime/plugin-adapter.js";
+import { WORKFLOW_RUNTIME_INPUT_VARIABLE_NAMES } from "../../runtime/workflow-runtime-manifest.js";
+function logicalWorkflowStep(stepId) {
+    const separator = stepId.lastIndexOf("/");
+    const component = separator === -1 ? null : stepId.slice(0, separator);
+    const localStepId = separator === -1 ? stepId : stepId.slice(separator + 1);
+    const prefix = "worker:";
+    if (!localStepId.startsWith(prefix) || localStepId.length === prefix.length) {
+        throw new Error(`canonical worker step id is invalid: ${stepId}`);
+    }
+    return { component, step_id: localStepId.slice(prefix.length) };
+}
+function workflowBindingForStep(metadata, stepId) {
+    const manifest = metadata.runtime_projection.workflow_runtime;
+    if (!manifest)
+        throw new Error("Missing canonical workflow runtime manifest");
+    const logical = logicalWorkflowStep(stepId);
+    const workflowName = metadata.target.kind === "workflow"
+        ? metadata.target.key
+        : Object.keys(manifest.workflows).filter((name) => (name === logical.component || name.endsWith(`_${logical.component}`)))[0];
+    if (!workflowName || !manifest.workflows[workflowName]) {
+        throw new Error(`Missing runtime binding for canonical step ${stepId}`);
+    }
+    return {
+        manifest,
+        binding: manifest.workflows[workflowName],
+        workflow_name: workflowName,
+        logical_step_id: logical.step_id,
+    };
+}
+export function durableRuntimeProjection(projection) {
+    return durableCanonicalRuntimeProjection(projection);
+}
+export async function syncRuntimeProjection(projectDirectory, agentsDirectory, projection, compiled) {
+    await writeAgentMDFiles(compileAllRolesToAgentMD(projection.roles, projection.constraint_ir), agentsDirectory);
+    await writeCompiledIR(projectDirectory, compiled);
+}
+async function writeAttemptState(context, metadata) {
+    const compiled = metadata.runtime_projection;
+    const { manifest, binding, workflow_name: workflowName, logical_step_id: logicalStepId } = workflowBindingForStep(metadata, context.packet.step_id);
+    if (context.packet.workspace.isolation === "worktree") {
+        await writeAgentMDFiles(compileAllRolesToAgentMD(compiled.roles ?? {}, compiled.ir), join(context.packet.workspace.working_directory, ".claude", "agents"));
+        await writeCompiledIR(context.packet.workspace.working_directory, compiled);
+    }
+    const state = new DNAStateManager(context.packet.workspace.working_directory, context.worker_session_id);
+    const compiledIRHash = compiled.compiled_ir_hash ?? compiled.ir.compiled_ir_hash;
+    if (!compiledIRHash || manifest.compiled_ir_hash !== compiledIRHash) {
+        throw new Error("Canonical Hook projection is missing its pinned compiled IR hash");
+    }
+    await writeCanonicalHookRuntimeProjection(context.packet.workspace.working_directory, {
+        schema_version: "intentdna.canonical_hook_projection.v2",
+        run_id: context.packet.run_id,
+        step_id: context.packet.step_id,
+        attempt_id: context.packet.attempt_id,
+        worker_session_id: context.worker_session_id,
+        compiled_ir_hash: compiledIRHash,
+        compiled_ir: compiled,
+        lease_token: context.lease.claim_token,
+        owner_id: context.lease.owner_id,
+    });
+    const inputs = {};
+    for (const name of binding.runtime_input_refs) {
+        const value = WORKFLOW_RUNTIME_INPUT_VARIABLE_NAMES.has(name)
+            ? metadata.task_id
+            : context.binding.validated_inputs[name];
+        if (typeof value === "string")
+            inputs[name] = value;
+    }
+    await state.writeWorkflowState({
+        active: true,
+        workflow_asset: binding.workflow_asset,
+        workflow: workflowName,
+        current_step: logicalStepId,
+        current_role: context.packet.role,
+        iteration: context.packet.workflow_round,
+        session_id: context.worker_session_id,
+        worker_session_id: context.worker_session_id,
+        run_id: context.packet.run_id,
+        step_id: context.packet.step_id,
+        attempt_id: context.packet.attempt_id,
+        started_at: context.packet.created_at,
+        inputs,
+        resolved_variables: binding.resolved_variables,
+        resolved_variables_source: "compiled_manifest",
+        workflow_runtime_manifest_hash: manifest.manifest_hash,
+        workflow_runtime_compiled_ir_hash: manifest.compiled_ir_hash,
+        workflow_inputs_pinned: true,
+    });
+    return state;
+}
+async function recordEvidence(context, response, metadata) {
+    const { binding, workflow_name: workflowName, logical_step_id: logicalStepId } = workflowBindingForStep(metadata, context.packet.step_id);
+    const result = response.result;
+    const status = result.terminal_outcome.kind === "worker_process"
+        ? result.terminal_outcome.status
+        : result.terminal_outcome.kind;
+    const processOutcome = result.terminal_outcome.kind === "worker_process"
+        ? result.terminal_outcome.process
+        : null;
+    const startedAt = Date.parse(result.started_at);
+    const completedAt = Date.parse(result.completed_at);
+    const persisted = await appendEvidenceCaptureEvent(metadata.project_directory, {
+        schema_version: EVIDENCE_CAPTURE_SCHEMA_VERSION,
+        event_id: `c5:${randomUUID()}`,
+        captured_at: result.committed_at,
+        project_root: metadata.project_directory,
+        source: "dna_cli",
+        workflow_asset: metadata.workflow_asset ?? "unknown",
+        workflow_id: workflowName,
+        run_id: context.packet.run_id,
+        step_id: logicalStepId,
+        fact: "result",
+        summary: `dna run recorded ${status === "succeeded" ? "success" : "failure"} for workflow step ${logicalStepId}`,
+        result: status === "succeeded" ? "success" : "failure",
+        exit_code: processOutcome !== null && "exit_code" in processOutcome
+            ? processOutcome.exit_code ?? undefined
+            : undefined,
+        duration_ms: Number.isFinite(startedAt) && Number.isFinite(completedAt)
+            ? Math.max(0, completedAt - startedAt)
+            : undefined,
+    });
+    if (!persisted)
+        throw new Error("evidence capture event was not persisted");
+}
+function writeObservationFailure(kind, error) {
+    process.stderr.write(`Warning: post-submit ${kind} observation failed: `
+        + `${error instanceof Error ? error.message : String(error)}\n`);
+}
+function writeVerificationDiagnostics(context, response) {
+    const outcome = response.result.terminal_outcome;
+    if (outcome.kind === "worker_process"
+        && outcome.status === "failed"
+        && outcome.reason_code !== null
+        && [
+            "unsupported_output_contract",
+            "invalid_provider_output",
+            "driver_postprocess_failed",
+        ].includes(outcome.reason_code)) {
+        process.stderr.write(`Error: ${outcome.reason_code}: ${outcome.message ?? "provider output post-processing failed"}\n`);
+    }
+    const verifierById = new Map(context.run.plan.plan.verifier_plan.map((verifier) => [verifier.verifier_id, verifier]));
+    const logicalStepId = logicalWorkflowStep(context.packet.step_id).step_id;
+    for (const result of response.result.verification_results) {
+        if (result.passed)
+            continue;
+        const verifier = verifierById.get(result.verifier_id);
+        if (!verifier) {
+            process.stderr.write(`Verification failed: ${result.verifier_id}`
+                + ` reason=${result.reason_code} (step: ${logicalStepId})\n`);
+        }
+        else if (verifier.kind === "checkpoint") {
+            process.stderr.write(`Checkpoint failed: ${verifier.assertion}`
+                + `${verifier.message ? ` - ${verifier.message}` : ""}`
+                + ` (step: ${logicalStepId})\n`);
+        }
+        else {
+            process.stderr.write(`Completion failed: ${result.reason_code} (step: ${logicalStepId})\n`);
+        }
+    }
+}
+export function createRunAttemptObservers(readMetadata) {
+    const states = new Map();
+    return {
+        before_execute: async (context) => {
+            states.set(context.lease.attempt_id, await writeAttemptState(context, readMetadata(context)));
+        },
+        after_submit: async (context, _execution, response) => {
+            try {
+                await recordEvidence(context, response, readMetadata(context));
+            }
+            catch (error) {
+                writeObservationFailure("evidence", error);
+            }
+            try {
+                writeVerificationDiagnostics(context, response);
+            }
+            catch (error) {
+                writeObservationFailure("verification diagnostic", error);
+            }
+            finally {
+                await states.get(context.lease.attempt_id)?.cleanup().catch(() => undefined);
+                states.delete(context.lease.attempt_id);
+            }
+        },
+        on_attempt_error: async (context) => {
+            if (!context)
+                return;
+            await states.get(context.lease.attempt_id)?.cleanup().catch(() => undefined);
+            states.delete(context.lease.attempt_id);
+        },
+    };
+}
+export function writeTerminalDriverFailure(view) {
+    if (view.run.status !== "failed")
+        return;
+    const failure = [...view.attempts].reverse().find((attempt) => (attempt.phase === "terminal"
+        && attempt.terminal_outcome?.kind === "worker_process"
+        && attempt.terminal_outcome.status === "failed"
+        && attempt.terminal_outcome.reason_code === "driver_prelaunch_failed"));
+    if (failure?.terminal_outcome?.kind !== "worker_process")
+        return;
+    process.stderr.write(`Error: ${failure.terminal_outcome.reason_code}: `
+        + `${failure.terminal_outcome.message ?? "provider launch preparation failed"}\n`);
+}

package/dist/cli/commands/run.d.ts

@@ -1,11 +1,6 @@
-/**
- * Intent DNA - canonical dna run command.
- *
- * 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 type { TransitionRule } from "../../schema/types.js";
+/** Intent DNA - canonical dna run CLI transport. */
+import type { AttemptExecutionAuthorityPort, ExecutionRecoveryProbeRequest } from "../../runtime/execution-authority.js";
+import { type LocalExecutionAuthorityBinding, type LocalExecutionBindRequest, type LocalExecutionPreparationRequest, type LocalExecutionRecoveryBinding, type LocalPreparedExecutionHandle } from "../../runtime/local-execution-authority.js";
 import { type RunLifecycleAction } from "./run-lifecycle.js";
 export type RunProviderKind = "claude" | "codex";
 export interface RunOptions {
@@ -13,6 +8,7 @@ export interface RunOptions {
     runId?: string;
     dnaFiles: string[];
     workflowName?: string;
+    controllerName?: string;
     taskId?: string;
     context?: string;
     vars?: Record<string, string>;
@@ -31,17 +27,17 @@ export interface RunOptions {
     reason?: string | null;
     json?: boolean;
 }
-/**
- * Retained as a source-compatible result shape for callers that only use the
- * pure legacy routing helper below. Canonical execution truth is RunStoreSnapshot.
- */
-export interface StepResult {
-    stepId: string;
-    status: "pass" | "fail" | "skipped";
-    durationMs: number;
-    resultFile?: string;
+export interface RunExecutionAuthority extends AttemptExecutionAuthorityPort {
+    readonly authority_instance_id: string;
+    assertExecutionSupported(): void;
+    prepareExecution(request: LocalExecutionPreparationRequest): LocalPreparedExecutionHandle;
+    abandonPreparedExecution(handle: LocalPreparedExecutionHandle): void;
+    recoverPreparedExecution(request: LocalExecutionPreparationRequest): LocalPreparedExecutionHandle | null;
+    bindExecution(handle: LocalPreparedExecutionHandle, request: LocalExecutionBindRequest): LocalExecutionAuthorityBinding;
+    recoverExecution(request: ExecutionRecoveryProbeRequest): LocalExecutionRecoveryBinding;
+}
+export interface RunCompositionOptions {
+    readonly execution_authority_factory?: (rootDirectory: string) => RunExecutionAuthority;
 }
 export declare function substituteTemplate(template: string, vars: Record<string, string>): string;
-export declare function evaluateRunIf(condition: string | null, round: number): boolean;
-export declare function checkRetryNeeded(stepResults: Map<string, StepResult>, transitions: TransitionRule[]): boolean;
-export declare function runRun(opts: RunOptions): Promise<number>;
+export declare function runRun(opts: RunOptions, composition?: RunCompositionOptions): Promise<number>;