intentdna 1.9.0 → 1.9.3

package/dist/compiler/input-resolver.d.ts

@@ -18,6 +18,8 @@ export interface ExpandDNAInputOptions {
 }
 export interface ExpandedDNAInput {
     files: string[];
+    dnas: IntentDNA[];
+    snapshot_bytes: Uint8Array[];
     provenance: DNASourceProvenance[];
     diagnostics: Diagnostic[];
 }

package/dist/compiler/input-resolver.js

@@ -3,6 +3,7 @@ import { homedir } from "node:os";
 import { readdir, readFile, stat } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { TextDecoder } from "node:util";
 import { validateDNA } from "../schema/validate.js";
 import { parseYAML } from "../schema/yaml-parser.js";
 import { DNADiagnosticsError, hasDiagnosticErrors } from "./diagnostics.js";
@@ -59,8 +60,8 @@ export async function detectDNAConfigs(projectDir = process.cwd()) {
     }
     return [];
 }
-function fingerprint(raw) {
-    return `sha256:${createHash("sha256").update(raw, "utf-8").digest("hex")}`;
+function fingerprint(snapshotBytes) {
+    return `sha256:${createHash("sha256").update(snapshotBytes).digest("hex")}`;
 }
 function enterprisePolicyCandidates(name, cwd, options) {
     const configuredDirs = [
@@ -103,8 +104,13 @@ function sourceTrustForInput(file, ref, cwd) {
     return "input";
 }
 async function readDNAWithRaw(path) {
-    const raw = await readFile(path, "utf-8");
-    return { raw, dna: parseDNAContent(path, raw) };
+    const snapshotBytes = await readFile(path);
+    const raw = new TextDecoder("utf-8", { fatal: true }).decode(snapshotBytes);
+    return {
+        raw,
+        dna: parseDNAContent(path, raw),
+        snapshot_bytes: Uint8Array.from(snapshotBytes),
+    };
 }
 export async function expandDNAInputs(files, options) {
     const cwd = options?.cwd ?? process.cwd();
@@ -112,6 +118,8 @@ export async function expandDNAInputs(files, options) {
     const seen = new Set();
     const diagnostics = [];
     const provenance = new Map();
+    const snapshots = new Map();
+    const snapshotBytes = new Map();
     const stack = [];
     const visit = async (file, ref, inheritedBy, trust) => {
         const abs = resolve(cwd, file);
@@ -169,11 +177,13 @@ export async function expandDNAInputs(files, options) {
         stack.pop();
         seen.add(abs);
         ordered.push(abs);
+        snapshots.set(abs, loaded.dna);
+        snapshotBytes.set(abs, loaded.snapshot_bytes);
         provenance.set(abs, {
             source_id: loaded.dna.id,
             source_ref: ref,
             resolved_path: abs,
-            fingerprint: fingerprint(loaded.raw),
+            fingerprint: fingerprint(loaded.snapshot_bytes),
             type: loaded.dna.type,
             cascade_priority: loaded.dna.cascade.priority,
             version: loaded.dna.version,
@@ -188,7 +198,13 @@ export async function expandDNAInputs(files, options) {
     if (hasDiagnosticErrors(diagnostics)) {
         throw new DNADiagnosticsError("DNA inheritance resolution failed", diagnostics);
     }
-    return { files: ordered, provenance: ordered.map((file) => provenance.get(file)).filter(Boolean), diagnostics };
+    return {
+        files: ordered,
+        dnas: ordered.map((file) => snapshots.get(file)).filter(Boolean),
+        snapshot_bytes: ordered.map((file) => snapshotBytes.get(file)).filter(Boolean),
+        provenance: ordered.map((file) => provenance.get(file)).filter(Boolean),
+        diagnostics,
+    };
 }
 export async function expandDNAInputFiles(files, options) {
     return (await expandDNAInputs(files, options)).files;

package/dist/hooks/cli.d.ts

@@ -18,11 +18,18 @@ import type { ArtifactFact, ConstraintIR, RoleDef, VerifierSpec } from "../schem
 import type { HookEvent, HookOutput } from "./protocol.js";
 import { blockOutput } from "./protocol.js";
 import { readWorkflowState } from "./state.js";
+import type { DNAWorkflowState } from "./state.js";
 import type { VerifierResultEntry } from "./state.js";
+import type { HeartbeatRequest } from "../runtime/canonical-run-service.js";
 interface HookRuntimePaths {
     projectDir: string;
     irPath: string;
 }
+interface HookRuntimeIdentity {
+    readonly host_session_id: string | undefined;
+    readonly worker_session_id: string | undefined;
+}
+declare function resolveHookRuntimeIdentity(event: HookEvent, input: Record<string, unknown>, rawInput: Record<string, unknown>): HookRuntimeIdentity;
 declare function resolveHookRuntimePaths(cwd: string, irPath?: string, explicitIRPath?: boolean): Promise<HookRuntimePaths>;
 export interface SessionSummary {
     total: number;
@@ -57,6 +64,40 @@ export declare function runHookEvent(options: RunHookEventOptions): Promise<Hook
 export declare function codexHookEventForInput(rawInput: Record<string, unknown>, args: string[]): unknown;
 declare function inferWorkflowAssetFromIr(ir: ConstraintIR, workflowId?: string): string | undefined;
 declare function runCodexHookWithLoadedIr(rawInput: Record<string, unknown>, projectDir: string, args: string[], ir: ConstraintIR): Promise<import("../runtime/codex-adapter.js").CodexHookRunnerResult>;
+interface HookIRLoadOptions {
+    readonly projectDir: string;
+    readonly projectIRPath: string;
+    readonly sessionId?: string;
+    readonly trustedWorkerIdentity?: string;
+}
+interface HookIRLoadResult {
+    readonly ir: ConstraintIR | null;
+    readonly error?: string;
+    readonly source: "session" | "project" | "none";
+}
+interface CanonicalHeartbeatPort {
+    heartbeat(request: HeartbeatRequest): Promise<unknown>;
+}
+type CanonicalHeartbeatOutcome = {
+    readonly kind: "renewed";
+} | {
+    readonly kind: "not_canonical";
+} | {
+    readonly kind: "no_projection";
+} | {
+    readonly kind: "projection_unreadable";
+    readonly message: string;
+} | {
+    readonly kind: "mismatched_projection";
+} | {
+    readonly kind: "legacy_projection";
+} | {
+    readonly kind: "service_rejected";
+    readonly message: string;
+};
+declare function heartbeatCanonicalAttempt(projectDir: string, state: DNAWorkflowState | null, service?: CanonicalHeartbeatPort): Promise<CanonicalHeartbeatOutcome>;
+declare function recordCanonicalHeartbeatOutcome(projectDir: string, outcome: CanonicalHeartbeatOutcome, event: string, state: DNAWorkflowState | null, sessionId?: string): Promise<void>;
+declare function loadHookIR(options: HookIRLoadOptions): Promise<HookIRLoadResult>;
 declare function recordProducedArtifacts(projectDir: string, ir: ConstraintIR, wfState: {
     workflow: string;
     current_step: string;
@@ -97,6 +138,10 @@ export declare const resolveWorkflowArtifactFactsForTest: typeof resolveWorkflow
 export declare const readWorkflowStateForHookTest: typeof readWorkflowStateForHook;
 export declare const runCodexHookWithLoadedIrForTest: typeof runCodexHookWithLoadedIr;
 export declare const resolveHookRuntimePathsForTest: typeof resolveHookRuntimePaths;
+export declare const resolveHookRuntimeIdentityForTest: typeof resolveHookRuntimeIdentity;
+export declare const loadHookIRForTest: typeof loadHookIR;
+export declare const heartbeatCanonicalAttemptForTest: typeof heartbeatCanonicalAttempt;
+export declare const recordCanonicalHeartbeatOutcomeForTest: typeof recordCanonicalHeartbeatOutcome;
 export declare const inferWorkflowAssetFromIrForTest: typeof inferWorkflowAssetFromIr;
 export declare const resolveWorkflowArtifactFactsForHookTest: typeof resolveWorkflowArtifactFactsForHook;
 export declare const finalizeAndResolveArtifactsForHookTest: typeof finalizeAndResolveArtifactsForHook;

package/dist/hooks/cli.js

@@ -21,18 +21,52 @@ import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { createHash, randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import { readStdinResult, writeOutput, silentOutput, allowOutput, blockOutput, stopOutput } from "./protocol.js";
-import { validateHookInput } from "./schema.js";
+import { isCurrentClaudeSubagentStopInput, validateHookInput } from "./schema.js";
 import { hookFailureOutput } from "./enforcement-boundary.js";
 import { enforcePreToolUse, enforcePostToolUse, enforceUserPromptSubmit, enforceSubagentStop, enforcePreCompact, enforceNotification, enforceSessionStart, enforceStop, extractBashWritePaths, checkReflectionLimit, checkContextReadiness, checkWorkflowBoundary, } from "./enforce.js";
-import { appendAudit, readWorkflowState, appendTrace, appendRuntimeDecisionEvent, appendEvidenceCaptureEvent, rotateTraces, readTraces, cleanStaleState, readSurgeonAttempts, updateSurgeonAttempts, appendSessionRead, readSessionReads, appendVerifierResult, readVerifierResults, appendCompletedArtifact, artifactIdentity, buildArtifactKey, readArtifactManifest, resolveArtifactTemplate, safePathComponent, workflowTemplateVariables, writeArtifactManifest, EVIDENCE_CAPTURE_SCHEMA_VERSION } from "./state.js";
+import { appendAudit, readWorkflowState, appendTrace, appendRuntimeDecisionEvent, appendEvidenceCaptureEvent, rotateTraces, readTraces, cleanStaleState, readSurgeonAttempts, updateSurgeonAttempts, appendSessionRead, readSessionReads, appendVerifierResult, readVerifierResults, appendCompletedArtifact, artifactIdentity, buildArtifactKey, readArtifactManifest, resolveArtifactTemplate, resolveSessionCompiledIRPath, safePathComponent, workflowTemplateVariables, writeArtifactManifest, EVIDENCE_CAPTURE_SCHEMA_VERSION } from "./state.js";
 import { hookEventsForSurface } from "./event-registry.js";
 import { writeAuditEvent } from "../audit/index.js";
 import { RUNTIME_DECISION_EVENT_SCHEMA_VERSION, trustedEvidenceCaptureAttribution } from "../governance/index.js";
 import { runCodexHook } from "../runtime/codex-adapter.js";
+import { createCanonicalRuntimeComposition } from "../runtime/canonical-runtime-composition.js";
+import { buildClaudeSubagentStopHostEvent, encodeClaudeHostEventForStderr, } from "./host-event.js";
 import { runCheckpointVerifier as runSharedCheckpointVerifier, runCompletionVerifier, toProjectRelativePath, } from "../runtime/verifier.js";
 // ── Constants ──────────────────────────────────────────────
 const DEFAULT_IR_PATH = ".dna/compiled/ir.json";
 const VALID_EVENTS = new Set(hookEventsForSurface("cli"));
+function resolveHookRuntimeIdentity(event, input, rawInput) {
+    const hostSessionId = typeof rawInput.session_id === "string"
+        ? rawInput.session_id
+        : typeof rawInput.sessionId === "string"
+            ? rawInput.sessionId
+            : typeof input.sessionId === "string"
+                ? input.sessionId
+                : undefined;
+    const agentId = typeof input.agent_id === "string" && input.agent_id.trim().length > 0
+        ? input.agent_id
+        : undefined;
+    const suppliedWorkerIdentity = typeof rawInput.worker_session_id === "string"
+        && rawInput.worker_session_id.trim().length > 0
+        ? rawInput.worker_session_id
+        : undefined;
+    const useHostAgentIdentity = event === "SubagentStop"
+        && agentId !== undefined
+        && isCurrentClaudeSubagentStopInput(rawInput);
+    return {
+        host_session_id: hostSessionId,
+        worker_session_id: useHostAgentIdentity
+            ? agentId
+            : suppliedWorkerIdentity ?? (typeof input.sessionId === "string" ? input.sessionId : hostSessionId),
+    };
+}
+function isCanonicalWorkflowState(state) {
+    return Boolean(state?.active
+        && state.worker_session_id
+        && state.run_id
+        && state.step_id
+        && state.attempt_id);
+}
 function workflowRuntimeRevisionMismatch(ir, state) {
     if (!state?.active || state.resolved_variables_source !== "compiled_manifest")
         return null;
@@ -391,15 +425,34 @@ async function main() {
     const cwd = typeof rawInput.cwd === "string" ? rawInput.cwd : process.cwd();
     const runtimePaths = await resolveHookRuntimePaths(cwd, irPath, explicitIRPath);
     const { projectDir } = runtimePaths;
-    const sessionId = typeof rawInput.sessionId === "string" ? rawInput.sessionId : undefined;
-    // Load compiled IR
+    const identity = resolveHookRuntimeIdentity(event, rawInput, rawStdin);
+    // Canonical attempts are pinned to an attempt-local projection. Legacy hooks
+    // keep the project-level compiled IR compatibility path.
     const resolvedIRPath = runtimePaths.irPath;
-    const ir = await loadIR(resolvedIRPath);
-    if (!ir) {
-        writeOutput(hookFailureOutput(event, "missing_ir", `Compiled IR is missing, unreadable, invalid, or version-incompatible at ${resolvedIRPath}.`));
+    const hookStateIdentity = identity.worker_session_id;
+    const loaded = await loadHookIR({
+        projectDir,
+        projectIRPath: resolvedIRPath,
+        sessionId: hookStateIdentity,
+        trustedWorkerIdentity: hookStateIdentity,
+    });
+    if (!loaded.ir) {
+        writeOutput(hookFailureOutput(event, "missing_ir", loaded.error ?? `Compiled IR is missing, unreadable, invalid, or version-incompatible at ${resolvedIRPath}.`));
         return;
     }
-    const output = await runHookEvent({ event, ir, rawInput, projectDir, sessionId });
+    const output = await runHookEvent({
+        event,
+        ir: loaded.ir,
+        rawInput,
+        projectDir,
+        sessionId: hookStateIdentity,
+    });
+    if (event === "SubagentStop" && output.continue !== false && hookStateIdentity) {
+        const state = await readWorkflowState(projectDir, hookStateIdentity);
+        const hostEvent = buildClaudeSubagentStopHostEvent(rawStdin, state);
+        if (hostEvent)
+            process.stderr.write(encodeClaudeHostEventForStderr(hostEvent));
+    }
     writeOutput(output);
 }
 export function normalizeHookOutputForEvent(output, event) {
@@ -485,6 +538,10 @@ export async function runHookEvent(options) {
                     && wfStateRaw.attempt_id),
             };
         }
+        if (event === "PreToolUse" || event === "PostToolUse") {
+            const heartbeatOutcome = await heartbeatCanonicalAttempt(projectDir, wfStateRaw);
+            await recordCanonicalHeartbeatOutcome(projectDir, heartbeatOutcome, event, wfStateRaw, sessionId);
+        }
     }
     if (event === "PreToolUse" && wfStateRaw?.active) {
         try {
@@ -824,10 +881,11 @@ function inferWorkflowAssetFromIr(ir, workflowId) {
 function agentTypeForWorkflowRole(role) {
     if (!role)
         return undefined;
-    return `dna-${role.replace(/([a-z])([A-Z])/g, "$1-$2").replace(/[_\s]+/g, "-").toLowerCase()}`;
+    return `dna-${toKebabCase(role)}`;
 }
 function subagentMatchesWorkflowRole(rawInput, wfState) {
-    return typeof rawInput.agent_type === "string" && rawInput.agent_type === agentTypeForWorkflowRole(wfState.current_role);
+    return typeof rawInput.agent_type === "string"
+        && rawInput.agent_type === agentTypeForWorkflowRole(wfState.current_role);
 }
 async function runCodexHookWithLoadedIr(rawInput, projectDir, args, ir) {
     const sessionId = typeof rawInput.worker_session_id === "string"
@@ -838,8 +896,13 @@ async function runCodexHookWithLoadedIr(rawInput, projectDir, args, ir) {
                 ? rawInput.sessionId
                 : undefined;
     const workflowState = await readWorkerWorkflowState(projectDir, sessionId, typeof rawInput.worker_session_id !== "string");
+    const hookEvent = codexHookEventForInput(rawInput, args);
+    if (hookEvent === "PreToolUse" || hookEvent === "PostToolUse") {
+        const heartbeatOutcome = await heartbeatCanonicalAttempt(projectDir, workflowState);
+        await recordCanonicalHeartbeatOutcome(projectDir, heartbeatOutcome, typeof hookEvent === "string" ? hookEvent : "CodexHook", workflowState, sessionId);
+    }
     const workflowAsset = inferWorkflowAssetFromIr(ir, workflowState?.workflow);
-    return runCodexHook({ ...rawInput, event: codexHookEventForInput(rawInput, args) }, {
+    return runCodexHook({ ...rawInput, event: hookEvent }, {
         ir,
         projectDir,
         hookInstallMode: codexInstallMode(argValue(args, "--codex-install-mode")),
@@ -868,12 +931,23 @@ async function runCodexHookCli(args) {
         const explicitIRPath = argValue(args, "--ir");
         const runtimePaths = await resolveHookRuntimePaths(cwd, explicitIRPath ?? DEFAULT_IR_PATH, explicitIRPath !== undefined);
         const { projectDir, irPath } = runtimePaths;
-        const ir = await loadIR(irPath);
-        if (!ir) {
-            writeOutput(hookFailureOutput(policyEvent, "missing_ir", `Compiled IR is missing, unreadable, invalid, or version-incompatible at ${irPath}.`));
+        const workerSessionId = typeof rawInput.worker_session_id === "string"
+            ? rawInput.worker_session_id
+            : undefined;
+        const claimedSessionId = workerSessionId
+            ?? (typeof rawInput.session_id === "string" ? rawInput.session_id : undefined)
+            ?? (typeof rawInput.sessionId === "string" ? rawInput.sessionId : undefined);
+        const loaded = await loadHookIR({
+            projectDir,
+            projectIRPath: irPath,
+            sessionId: claimedSessionId,
+            trustedWorkerIdentity: workerSessionId,
+        });
+        if (!loaded.ir) {
+            writeOutput(hookFailureOutput(policyEvent, "missing_ir", loaded.error ?? `Compiled IR is missing, unreadable, invalid, or version-incompatible at ${irPath}.`));
             return;
         }
-        const result = await runCodexHookWithLoadedIr(rawInput, projectDir, args, ir);
+        const result = await runCodexHookWithLoadedIr(rawInput, projectDir, args, loaded.ir);
         writeOutput(result.output);
     }
     catch (err) {
@@ -885,26 +959,180 @@ async function runCodexHookCli(args) {
 // ── IR Loading ─────────────────────────────────────────────
 /** Expected IR schema version — must match plugin-adapter.ts */
 const EXPECTED_IR_VERSION = 1;
-async function loadIR(irPath) {
+function canonicalProjectionMismatch(projection, state) {
+    if (projection.schema_version !== "intentdna.canonical_hook_projection.v1"
+        && projection.schema_version !== "intentdna.canonical_hook_projection.v2") {
+        return "Canonical session IR has an unsupported schema version.";
+    }
+    for (const [label, actual, expected] of [
+        ["run", projection.run_id, state.run_id],
+        ["step", projection.step_id, state.step_id],
+        ["attempt", projection.attempt_id, state.attempt_id],
+        ["worker session", projection.worker_session_id, state.worker_session_id],
+    ]) {
+        if (actual !== expected)
+            return `Canonical session IR ${label} identity does not match workflow state.`;
+    }
+    const compiled = projection.compiled_ir;
+    if (!projection.compiled_ir_hash
+        || compiled?.compiled_ir_hash !== projection.compiled_ir_hash
+        || compiled?.ir?.compiled_ir_hash !== projection.compiled_ir_hash
+        || compiled?.workflow_runtime?.compiled_ir_hash !== projection.compiled_ir_hash) {
+        return "Canonical session IR hash does not match its compiled projection.";
+    }
+    if (state.workflow_runtime_compiled_ir_hash !== projection.compiled_ir_hash) {
+        return "Canonical session IR hash does not match workflow state.";
+    }
+    return null;
+}
+function canonicalHeartbeatService(projectDir) {
+    return createCanonicalRuntimeComposition({
+        project_directory: projectDir,
+    }).service;
+}
+async function heartbeatCanonicalAttempt(projectDir, state, service) {
+    if (!isCanonicalWorkflowState(state))
+        return { kind: "not_canonical" };
+    let projection;
     try {
-        const raw = await readFile(irPath, "utf-8");
-        const data = JSON.parse(raw);
-        // Support both raw IR and wrapped CompiledIRFile format
-        if (data.ir_version && data.ir) {
-            if (data.ir_version !== EXPECTED_IR_VERSION) {
-                process.stderr.write(`\n  Intent DNA: IR version mismatch (v${data.ir_version} on disk, v${EXPECTED_IR_VERSION} expected)\n` +
-                    `  Fix: run \`dna sync\` to recompile\n\n`);
-                return null;
-            }
-            return data.ir;
+        const projectionPath = resolveSessionCompiledIRPath(projectDir, state.worker_session_id);
+        projection = JSON.parse(await readFile(projectionPath, "utf-8"));
+    }
+    catch (error) {
+        const code = error instanceof Error && "code" in error
+            ? error.code
+            : undefined;
+        if (code === "ENOENT")
+            return { kind: "no_projection" };
+        return {
+            kind: "projection_unreadable",
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+    if (canonicalProjectionMismatch(projection, state))
+        return { kind: "mismatched_projection" };
+    if (projection.schema_version !== "intentdna.canonical_hook_projection.v2") {
+        return { kind: "legacy_projection" };
+    }
+    try {
+        await (service ?? canonicalHeartbeatService(projectDir)).heartbeat({
+            lease_token: projection.lease_token,
+            owner_id: projection.owner_id,
+        });
+        return { kind: "renewed" };
+    }
+    catch (error) {
+        return {
+            kind: "service_rejected",
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+async function recordCanonicalHeartbeatOutcome(projectDir, outcome, event, state, sessionId) {
+    if (outcome.kind === "renewed" || outcome.kind === "not_canonical")
+        return;
+    const detail = outcome.kind === "service_rejected" || outcome.kind === "projection_unreadable"
+        ? `: ${outcome.message}`
+        : "";
+    await appendTrace(projectDir, {
+        trace_id: randomUUID(),
+        event,
+        workflow: state?.workflow,
+        step: state?.current_step,
+        decision: "warn",
+        reason: `canonical heartbeat ${outcome.kind}${detail}`,
+        duration_ms: 0,
+        timestamp: new Date().toISOString(),
+    }, sessionId);
+}
+async function loadHookIR(options) {
+    let projectionRaw = null;
+    let projectionPath = null;
+    if (options.sessionId) {
+        try {
+            projectionPath = resolveSessionCompiledIRPath(options.projectDir, options.sessionId);
+            projectionRaw = await readFile(projectionPath, "utf-8");
         }
-        // Direct ConstraintIR
-        if (data.compiled_at && data.source_dna_ids) {
-            return data;
+        catch (error) {
+            const code = error instanceof Error && "code" in error
+                ? error.code
+                : undefined;
+            if (code !== "ENOENT") {
+                return {
+                    ir: null,
+                    source: "none",
+                    error: `Canonical session IR is unreadable at ${projectionPath ?? "unknown"}: ${error instanceof Error ? error.message : String(error)}`,
+                };
+            }
         }
-        process.stderr.write(`\n  Intent DNA: unrecognized IR format at ${irPath}\n` +
-            `  Fix: run \`dna sync\` to regenerate\n\n`);
+    }
+    let state = null;
+    try {
+        state = options.sessionId
+            ? await readWorkflowState(options.projectDir, options.sessionId)
+            : null;
+    }
+    catch (error) {
+        return { ir: null, source: "none", error: `Hook session identity is invalid: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    if (!isCanonicalWorkflowState(state) && projectionRaw === null) {
+        return { ir: await loadIR(options.projectIRPath), source: "project" };
+    }
+    if (!isCanonicalWorkflowState(state)) {
+        return {
+            ir: null,
+            source: "none",
+            error: "Canonical Hook workflow state is missing, unreadable, or incomplete; project/root IR fallback is forbidden.",
+        };
+    }
+    if (!options.trustedWorkerIdentity || options.trustedWorkerIdentity !== state.worker_session_id) {
+        return {
+            ir: null,
+            source: "none",
+            error: "Canonical Hook execution requires a trusted worker_session_id; project/root IR fallback is forbidden.",
+        };
+    }
+    projectionPath ??= resolveSessionCompiledIRPath(options.projectDir, state.worker_session_id);
+    try {
+        const projection = JSON.parse(projectionRaw ?? await readFile(projectionPath, "utf-8"));
+        const mismatch = canonicalProjectionMismatch(projection, state);
+        if (mismatch)
+            return { ir: null, source: "none", error: mismatch };
+        const ir = await parseIR(projection.compiled_ir, projectionPath);
+        return ir
+            ? { ir, source: "session" }
+            : { ir: null, source: "none", error: `Canonical session IR is invalid at ${projectionPath}.` };
+    }
+    catch (error) {
+        return {
+            ir: null,
+            source: "none",
+            error: `Canonical session IR is missing, unreadable, or malformed at ${projectionPath}: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+async function parseIR(data, irPath) {
+    if (!data || typeof data !== "object")
         return null;
+    const record = data;
+    if (record.ir_version && record.ir) {
+        if (record.ir_version !== EXPECTED_IR_VERSION) {
+            process.stderr.write(`\n  Intent DNA: IR version mismatch (v${record.ir_version} on disk, v${EXPECTED_IR_VERSION} expected)\n` +
+                `  Fix: run \`dna sync\` to recompile\n\n`);
+            return null;
+        }
+        return record.ir;
+    }
+    if (record.compiled_at && record.source_dna_ids)
+        return record;
+    process.stderr.write(`\n  Intent DNA: unrecognized IR format at ${irPath}\n` +
+        `  Fix: run \`dna sync\` to regenerate\n\n`);
+    return null;
+}
+async function loadIR(irPath) {
+    try {
+        const raw = await readFile(irPath, "utf-8");
+        return parseIR(JSON.parse(raw), irPath);
     }
     catch (err) {
         // U3: Human-readable error instead of silent failure
@@ -1122,6 +1350,10 @@ export const resolveWorkflowArtifactFactsForTest = resolveWorkflowArtifactFacts;
 export const readWorkflowStateForHookTest = readWorkflowStateForHook;
 export const runCodexHookWithLoadedIrForTest = runCodexHookWithLoadedIr;
 export const resolveHookRuntimePathsForTest = resolveHookRuntimePaths;
+export const resolveHookRuntimeIdentityForTest = resolveHookRuntimeIdentity;
+export const loadHookIRForTest = loadHookIR;
+export const heartbeatCanonicalAttemptForTest = heartbeatCanonicalAttempt;
+export const recordCanonicalHeartbeatOutcomeForTest = recordCanonicalHeartbeatOutcome;
 export const inferWorkflowAssetFromIrForTest = inferWorkflowAssetFromIr;
 export const resolveWorkflowArtifactFactsForHookTest = resolveWorkflowArtifactFactsForHook;
 export const finalizeAndResolveArtifactsForHookTest = finalizeAndResolveArtifactsForHook;

package/dist/hooks/host-event.d.ts

@@ -0,0 +1,57 @@
+import type { DNAWorkflowState } from "./state.js";
+export declare const CLAUDE_HOST_EVENT_SCHEMA_VERSION: "intentdna.claude_host_event.v1";
+export declare const CLAUDE_HOST_EVENT_STDERR_PREFIX = "INTENTDNA_CLAUDE_HOST_EVENT_V1 ";
+export interface ClaudeSubagentStopHostEvent {
+    readonly schema_version: typeof CLAUDE_HOST_EVENT_SCHEMA_VERSION;
+    readonly hook_event_name: "SubagentStop";
+    readonly session_id: string;
+    readonly transcript_path: string;
+    readonly agent_id: string;
+    readonly agent_type: string;
+    readonly agent_transcript_path: string;
+    readonly last_assistant_message_digest: `sha256:${string}`;
+    readonly run_id: string;
+    readonly step_id: string;
+    readonly attempt_id: string;
+    readonly worker_session_id: string;
+}
+export interface ClaudeHookResponseFrame {
+    readonly type: "system";
+    readonly subtype: "hook_response";
+    readonly hook_id: string;
+    readonly hook_event: "SubagentStop";
+    readonly session_id: string;
+    readonly uuid: string;
+    readonly outcome: "success";
+    readonly exit_code: 0;
+    readonly stderr: string;
+}
+export interface VerifiedClaudeSubagentStopHostEvent {
+    readonly hook_id: string;
+    readonly frame_uuid: string;
+    readonly event: ClaudeSubagentStopHostEvent;
+}
+export interface ClaudeSubagentStopHostEventExpectation {
+    readonly hook_id: string;
+    readonly session_id: string;
+    readonly run_id: string;
+    readonly step_id: string;
+    readonly attempt_id: string;
+    readonly worker_session_id: string;
+}
+export interface ClaudeHostEventConsumptionKey {
+    readonly session_id: string;
+    readonly frame_uuid: string;
+    readonly hook_id: string;
+}
+export interface ClaudeHostEventConsumptionStore {
+    consume(key: ClaudeHostEventConsumptionKey): Promise<boolean>;
+}
+export type ClaudeHostEventErrorCode = "invalid_frame" | "missing_envelope" | "duplicate_envelope" | "malformed_envelope" | "identity_mismatch" | "context_mismatch" | "replayed_frame";
+export declare class ClaudeHostEventError extends Error {
+    readonly code: ClaudeHostEventErrorCode;
+    constructor(code: ClaudeHostEventErrorCode, message: string);
+}
+export declare function buildClaudeSubagentStopHostEvent(input: Record<string, unknown>, state: DNAWorkflowState | null): ClaudeSubagentStopHostEvent | null;
+export declare function encodeClaudeHostEventForStderr(event: ClaudeSubagentStopHostEvent): string;
+export declare function parseClaudeSubagentStopHookResponse(frame: unknown, expected: ClaudeSubagentStopHostEventExpectation, consumptionStore: ClaudeHostEventConsumptionStore): Promise<VerifiedClaudeSubagentStopHostEvent>;