intentdna 1.8.6 → 1.8.7

package/dist/hooks/enforce.js

@@ -33,7 +33,7 @@ export function enforcePreToolUse(ir, input, state, roles) {
     if (input.agent_type && ir.roles_scope_map && ir.roles_scope_map.length > 0) {
         const relaxed = isStepScopeRelaxed(ir, state);
         if (!relaxed) {
-            const result = enforceRoleScope(ir.roles_scope_map, input, getStepAdditionalPaths(ir, state));
+            const result = enforceRoleScope(ir.roles_scope_map, input, getStepAdditionalPaths(ir, state), state?.workflowState?.strict_boundary === true);
             if (result)
                 return { output: result, trace: { matched_rule: "scope", role: input.agent_type } };
         }
@@ -46,7 +46,7 @@ export function enforcePreToolUse(ir, input, state, roles) {
     }
     // Layer 4: Pre-execution gates
     if (ir.pre_execution_gates.length > 0) {
-        const result = enforceGates(ir.pre_execution_gates, input);
+        const result = enforceGates(ir.pre_execution_gates, input, state?.workflowState?.strict_boundary === true);
         if (result)
             return { output: result, trace: { matched_rule: "gate" } };
     }
@@ -56,11 +56,19 @@ export function enforcePreToolUse(ir, input, state, roles) {
         if (result)
             return { output: result, trace: { matched_rule: "output_schema" } };
     }
-    // Layer 6: Handoff — check consumed artifacts are available
-    if (state?.workflowState && ir.workflows_ir) {
+    if (state?.workflowState
+        && !state.workflowState.strict_boundary
+        && ir.workflows_ir) {
         const result = enforceHandoffConsumes(ir, state.workflowState, state.artifactFacts ?? []);
-        if (result)
-            return { output: result, trace: { matched_rule: "handoff", step_id: state.workflowState.current_step } };
+        if (result) {
+            return {
+                output: result,
+                trace: {
+                    matched_rule: "handoff",
+                    step_id: state.workflowState.current_step,
+                },
+            };
+        }
     }
     return null;
 }
@@ -352,27 +360,26 @@ function getStepAdditionalPaths(ir, state) {
     return rule?.additional_write_paths ?? [];
 }
 // ── Internal: Layer Enforcement ────────────────────────────
-/**
- * Enforce handoff consumes — verify that the current step's consumed
- * artifacts have been produced by a preceding step.
- * Returns block output if a required artifact is missing, null if all satisfied.
- */
 function enforceHandoffConsumes(ir, wfState, artifactFacts) {
-    const activeWf = ir.workflows_ir?.find(w => w.workflow_name === wfState.workflow);
-    if (!activeWf || (activeWf.handoff_chain?.length ?? 0) === 0)
+    const activeWorkflow = ir.workflows_ir?.find((workflow) => workflow.workflow_name === wfState.workflow);
+    if (!activeWorkflow || (activeWorkflow.handoff_chain?.length ?? 0) === 0) {
         return null;
-    const currentEntry = activeWf.handoff_chain.find(h => h.step_id === wfState.current_step);
+    }
+    const currentEntry = activeWorkflow.handoff_chain.find((entry) => entry.step_id === wfState.current_step);
     if (!currentEntry?.consumes || currentEntry.consumes.length === 0)
         return null;
     for (const consumed of currentEntry.consumes) {
         if (consumed.required === false)
             continue;
-        const producerStep = consumed.from ?? findProducerStep(activeWf.handoff_chain, consumed) ?? "external";
-        const fact = artifactFacts.find(a => artifactMatches(a, consumed, producerStep, wfState.workflow));
+        const producerStep = consumed.from
+            ?? findProducerStep(activeWorkflow.handoff_chain, consumed)
+            ?? "external";
+        const fact = artifactFacts.find((entry) => artifactMatches(entry, consumed, producerStep, wfState.workflow));
         if (!fact) {
             return blockOutput(`[Intent DNA] Step '${wfState.current_step}' requires artifact '${consumed.description}' from '${producerStep}', but no verified manifest was resolved.`);
         }
-        if (consumed.type === "git_commit" && typeof fact.metadata?.commit !== "string") {
+        if (consumed.type === "git_commit"
+            && typeof fact.metadata?.commit !== "string") {
             return blockOutput(`[Intent DNA] Step '${wfState.current_step}' requires git_commit artifact from '${producerStep}', but no commit identity was recorded.`);
         }
     }
@@ -411,9 +418,14 @@ export function enforceHandoffProduces(ir, wfState) {
     return null;
 }
 function findProducerStep(handoffChain, consumed) {
-    const producer = handoffChain.find(h => h.produces?.some(p => p.type === consumed.type && ((p.path && consumed.path && p.path === consumed.path) ||
-        (p.name && consumed.name && p.name === consumed.name) ||
-        (p.artifact_id && consumed.artifact_id && p.artifact_id === consumed.artifact_id))));
+    const producer = handoffChain.find((entry) => entry.produces?.some((produced) => produced.type === consumed.type
+        && ((produced.path && consumed.path && produced.path === consumed.path)
+            || (produced.name
+                && consumed.name
+                && produced.name === consumed.name)
+            || (produced.artifact_id
+                && consumed.artifact_id
+                && produced.artifact_id === consumed.artifact_id))));
     return producer?.step_id ?? null;
 }
 function artifactMatches(fact, artifact, producerStep, workflow) {
@@ -431,7 +443,7 @@ function artifactMatches(fact, artifact, producerStep, workflow) {
         return false;
     return true;
 }
-function enforceRoleScope(rolesScopeMap, input, additionalWritePaths = []) {
+function enforceRoleScope(rolesScopeMap, input, additionalWritePaths = [], strictBoundary = false) {
     if (!input.agent_type)
         return null;
     // Standard write tools: check single file path
@@ -450,7 +462,7 @@ function enforceRoleScope(rolesScopeMap, input, additionalWritePaths = []) {
         if (writePaths.length === 0)
             return null;
         for (const p of writePaths) {
-            const result = checkPathAgainstScope(rolesScopeMap, input, p, additionalWritePaths, false);
+            const result = checkPathAgainstScope(rolesScopeMap, input, p, additionalWritePaths, strictBoundary, strictBoundary);
             if (result)
                 return result;
         }
@@ -459,7 +471,7 @@ function enforceRoleScope(rolesScopeMap, input, additionalWritePaths = []) {
     return null;
 }
 /** Check a single file path against role scope. Shared by Write tools and Bash. */
-function checkPathAgainstScope(rolesScopeMap, input, filePath, additionalWritePaths = [], blockViolation = true) {
+function checkPathAgainstScope(rolesScopeMap, input, filePath, additionalWritePaths = [], blockViolation = true, blockUnknownRole = false) {
     const cwd = input.cwd;
     let relativePath = cwd && filePath.startsWith("/") ? relative(cwd, filePath) : filePath;
     // Normalize to resolve traversal (e.g., "src/../../test/x.ts" → "../test/x.ts")
@@ -487,7 +499,9 @@ function checkPathAgainstScope(rolesScopeMap, input, filePath, additionalWritePa
         }
         return null; // Role matched, write allowed
     }
-    return null; // No matching role — allow
+    return blockUnknownRole
+        ? blockOutput("[Intent DNA] role_mismatch: worker role has no configured role scope.")
+        : null;
 }
 /**
  * Verify a list of paths against role scope. Returns violation messages.
@@ -495,10 +509,12 @@ function checkPathAgainstScope(rolesScopeMap, input, filePath, additionalWritePa
  */
 function verifyPathsAgainstScope(rolesScopeMap, agentType, paths, cwd) {
     const violations = [];
+    let matchedRole = false;
     for (const entry of rolesScopeMap) {
         const agentTypeName = `dna-${toKebabCase(entry.role_name)}`;
         if (agentType !== agentTypeName)
             continue;
+        matchedRole = true;
         const writeGlobs = entry.scope.write ?? [];
         for (const p of paths) {
             const relativePath = cwd && p.startsWith("/") ? relative(cwd, p) : p;
@@ -508,6 +524,9 @@ function verifyPathsAgainstScope(rolesScopeMap, agentType, paths, cwd) {
         }
         break; // Found the role, done
     }
+    if (!matchedRole) {
+        violations.push(`agent_type '${agentType}' has no configured role scope`);
+    }
     return violations;
 }
 function enforceToolFilters(filters, input) {
@@ -529,11 +548,21 @@ function enforceToolFilters(filters, input) {
     }
     return null;
 }
-function enforceGates(gates, input) {
+function enforceGates(gates, input, strictBoundary = false) {
     for (const gate of gates) {
         const matches = evaluateGateCondition(gate.condition, input);
-        if (matches === null)
-            continue; // Condition too complex — skip
+        if (matches === null) {
+            if (!strictBoundary)
+                continue;
+            const detail = `Gate condition '${gate.condition}' could not be evaluated.`;
+            if (gate.action === "block") {
+                return blockOutput(`[Intent DNA] gate_evaluation: ${detail}`);
+            }
+            if (gate.action === "escalate") {
+                return escalateOutput(`[Intent DNA] gate_evaluation: ${detail}`);
+            }
+            return allowOutput(`WARN [Intent DNA] gate_evaluation: ${detail}`);
+        }
         if (!matches)
             continue; // Condition not triggered
         if (gate.action === "block") {

package/dist/hooks/enforcement-boundary.d.ts

@@ -0,0 +1,13 @@
+import type { HookEvent } from "./event-registry.js";
+import { type HookOutput } from "./protocol.js";
+export type HookFailureKind = "malformed_input" | "missing_ir" | "role_mismatch" | "gate_evaluation" | "bash_write_scope";
+export type HookFailureDisposition = "advisory" | "blocking";
+/**
+ * Foundation Hook failure policy.
+ *
+ * Pre-execution and terminal-boundary events block when enforcement cannot be
+ * evaluated safely. Observation-only and post-execution events remain advisory.
+ * Bash scope is blocking before execution and advisory after the write occurred.
+ */
+export declare function hookFailureDisposition(event: HookEvent, kind: HookFailureKind): HookFailureDisposition;
+export declare function hookFailureOutput(event: HookEvent, kind: HookFailureKind, detail: string): HookOutput;

package/dist/hooks/enforcement-boundary.js

@@ -0,0 +1,33 @@
+import { allowOutput, blockOutput } from "./protocol.js";
+const BLOCKING_EVENTS = new Set([
+    "PreToolUse",
+    "SubagentStop",
+    "Stop",
+]);
+/**
+ * Foundation Hook failure policy.
+ *
+ * Pre-execution and terminal-boundary events block when enforcement cannot be
+ * evaluated safely. Observation-only and post-execution events remain advisory.
+ * Bash scope is blocking before execution and advisory after the write occurred.
+ */
+export function hookFailureDisposition(event, kind) {
+    if (kind === "gate_evaluation") {
+        return BLOCKING_EVENTS.has(event) ? "blocking" : "advisory";
+    }
+    if (kind === "bash_write_scope") {
+        return event === "PreToolUse" ? "blocking" : "advisory";
+    }
+    if (kind === "role_mismatch") {
+        return event === "PreToolUse" || event === "SubagentStop"
+            ? "blocking"
+            : "advisory";
+    }
+    return BLOCKING_EVENTS.has(event) ? "blocking" : "advisory";
+}
+export function hookFailureOutput(event, kind, detail) {
+    const message = `[Intent DNA] ${kind}: ${detail}`;
+    return hookFailureDisposition(event, kind) === "blocking"
+        ? blockOutput(message)
+        : allowOutput(`WARN ${message}`, event);
+}

package/dist/hooks/index.d.ts

@@ -4,7 +4,8 @@
  * Public exports for the hook enforcement engine.
  * Used by the `dna-hook` CLI and importable for programmatic use.
  */
-export { type HookEvent, type HookInput, type HookOutput, type HookInputBase, type PreToolUseInput, type PostToolUseInput, type UserPromptSubmitInput, type SubagentStopInput, type PreCompactInput, type NotificationInput, type StopInput, type SessionStartInput as SessionStartHookInput, readStdin, writeOutput, allowOutput, blockOutput, escalateOutput, silentOutput, } from "./protocol.js";
+export { type HookEvent, type HookInput, type HookOutput, type HookInputBase, type PreToolUseInput, type PostToolUseInput, type UserPromptSubmitInput, type SubagentStopInput, type PreCompactInput, type NotificationInput, type StopInput, type SessionStartInput as SessionStartHookInput, type StdinReadResult, readStdin, readStdinResult, writeOutput, allowOutput, blockOutput, escalateOutput, silentOutput, } from "./protocol.js";
+export { type HookFailureDisposition, type HookFailureKind, hookFailureDisposition, hookFailureOutput, } from "./enforcement-boundary.js";
 export { type EnforceState, type SessionStartInput, type StopEnforceInput, type StopWorkflowContext, enforcePreToolUse, enforcePostToolUse, enforceUserPromptSubmit, enforceSubagentStop, enforcePreCompact, enforceNotification, enforceSessionStart, enforceStop, checkWriteAllowed, globToPrefix, evaluateGateCondition, resolveToolTarget, } from "./enforce.js";
-export { type DNAWorkflowState, type AuditEntry, resolveStateDir, readWorkflowState, writeWorkflowState, clearWorkflowState, appendAudit, } from "./state.js";
+export { type DNAWorkflowState, type AuditEntry, resolveStateDir, readWorkflowState, writeWorkflowState, clearWorkflowState, cleanupWorkerHookState, appendAudit, } from "./state.js";
 export { type SessionSummary, computeSummary, formatSummary, } from "./cli.js";

package/dist/hooks/index.js

@@ -5,10 +5,11 @@
  * Used by the `dna-hook` CLI and importable for programmatic use.
  */
 // Protocol types and I/O
-export { readStdin, writeOutput, allowOutput, blockOutput, escalateOutput, silentOutput, } from "./protocol.js";
+export { readStdin, readStdinResult, writeOutput, allowOutput, blockOutput, escalateOutput, silentOutput, } from "./protocol.js";
+export { hookFailureDisposition, hookFailureOutput, } from "./enforcement-boundary.js";
 // Enforcement engine
 export { enforcePreToolUse, enforcePostToolUse, enforceUserPromptSubmit, enforceSubagentStop, enforcePreCompact, enforceNotification, enforceSessionStart, enforceStop, checkWriteAllowed, globToPrefix, evaluateGateCondition, resolveToolTarget, } from "./enforce.js";
 // State management
-export { resolveStateDir, readWorkflowState, writeWorkflowState, clearWorkflowState, appendAudit, } from "./state.js";
+export { resolveStateDir, readWorkflowState, writeWorkflowState, clearWorkflowState, cleanupWorkerHookState, appendAudit, } from "./state.js";
 // Session summary
 export { computeSummary, formatSummary, } from "./cli.js";

package/dist/hooks/protocol.d.ts

@@ -11,6 +11,10 @@ export type { HookEvent } from "./event-registry.js";
 export interface HookInputBase {
     cwd?: string;
     sessionId?: string;
+    worker_session_id?: string;
+    run_id?: string;
+    step_id?: string;
+    attempt_id?: string;
 }
 export interface PreToolUseInput extends HookInputBase {
     tool_name: string;
@@ -76,10 +80,14 @@ export declare function escalateOutput(reason: string): HookOutput;
 export declare function stopOutput(systemMessage?: string): HookOutput;
 /** Create a silent allow output (no visible output to user). */
 export declare function silentOutput(): HookOutput;
-/**
- * Read JSON from stdin with timeout protection.
- * Returns parsed object on success, empty object on failure (fail-open).
- */
+export interface StdinReadResult {
+    ok: boolean;
+    data: Record<string, unknown>;
+    error?: "timeout" | "empty" | "malformed" | "read_error";
+}
+/** Read JSON from stdin without erasing malformed-input evidence. */
+export declare function readStdinResult(timeoutMs?: number): Promise<StdinReadResult>;
+/** Compatibility reader for non-enforcement call sites. */
 export declare function readStdin(timeoutMs?: number): Promise<Record<string, unknown>>;
 /**
  * Write hook output to stdout as JSON.

package/dist/hooks/protocol.js

@@ -46,16 +46,12 @@ export function stopOutput(systemMessage) {
 export function silentOutput() {
     return { continue: true, suppressOutput: true };
 }
-// ── Stdin/Stdout I/O ───────────────────────────────────────
-/**
- * Read JSON from stdin with timeout protection.
- * Returns parsed object on success, empty object on failure (fail-open).
- */
-export function readStdin(timeoutMs = 5000) {
+/** Read JSON from stdin without erasing malformed-input evidence. */
+export function readStdinResult(timeoutMs = 5000) {
     return new Promise((resolve) => {
         const chunks = [];
         let settled = false;
-        const finish = (data) => {
+        const finish = (result) => {
             if (settled)
                 return;
             settled = true;
@@ -63,9 +59,9 @@ export function readStdin(timeoutMs = 5000) {
             process.stdin.removeAllListeners("data");
             process.stdin.removeAllListeners("end");
             process.stdin.removeAllListeners("error");
-            resolve(data);
+            resolve(result);
         };
-        const timer = setTimeout(() => finish({}), timeoutMs);
+        const timer = setTimeout(() => finish({ ok: false, data: {}, error: "timeout" }), timeoutMs);
         process.stdin.on("data", (chunk) => {
             chunks.push(chunk);
         });
@@ -73,23 +69,33 @@ export function readStdin(timeoutMs = 5000) {
             try {
                 const raw = Buffer.concat(chunks).toString("utf-8").trim();
                 if (!raw) {
-                    finish({});
+                    finish({ ok: false, data: {}, error: "empty" });
                     return;
                 }
                 const parsed = JSON.parse(raw);
-                finish(typeof parsed === "object" && parsed !== null ? parsed : {});
+                if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+                    finish({ ok: false, data: {}, error: "malformed" });
+                    return;
+                }
+                finish({ ok: true, data: parsed });
             }
             catch {
-                finish({});
+                finish({ ok: false, data: {}, error: "malformed" });
             }
         });
-        process.stdin.on("error", () => finish({}));
+        process.stdin.on("error", () => {
+            finish({ ok: false, data: {}, error: "read_error" });
+        });
         // If stdin is already ended (piped and closed)
         if (process.stdin.readableEnded) {
-            finish({});
+            finish({ ok: false, data: {}, error: "empty" });
         }
     });
 }
+/** Compatibility reader for non-enforcement call sites. */
+export async function readStdin(timeoutMs = 5000) {
+    return (await readStdinResult(timeoutMs)).data;
+}
 /**
  * Write hook output to stdout as JSON.
  */

package/dist/hooks/schema.d.ts

@@ -1,7 +1,7 @@
 /**
  * Hook input validation — CC protocol boundary.
  * Zero external dependencies. Hand-written validators.
- * Fail-open: invalid input → log warning + return { valid: false, ... }
+ * Classification of invalid input belongs to the event boundary.
  */
 export interface ValidationResult {
     valid: boolean;
@@ -15,6 +15,7 @@ export interface ValidationResult {
 export declare function validateHookInput(event: string, raw: unknown): ValidationResult;
 /**
  * Normalize session_id field from various formats:
+ * - worker_session_id (disposable Controller worker identity)
  * - session_id (snake_case from CC)
  * - sessionId (camelCase internal)
  * - CLAUDE_SESSION_ID (env var fallback)

package/dist/hooks/schema.js

@@ -1,7 +1,7 @@
 /**
  * Hook input validation — CC protocol boundary.
  * Zero external dependencies. Hand-written validators.
- * Fail-open: invalid input → log warning + return { valid: false, ... }
+ * Classification of invalid input belongs to the event boundary.
  */
 import { isHookEventSupportedBySurface } from "./event-registry.js";
 /**
@@ -15,7 +15,7 @@ export function validateHookInput(event, raw) {
     const input = raw;
     const errors = [];
     const normalized = { ...input };
-    // Normalize session_id to sessionId
+    // The Controller's disposable worker session is the Hook context key.
     const sessionId = normalizeSessionId(input);
     if (sessionId !== undefined) {
         normalized.sessionId = sessionId;
@@ -72,11 +72,15 @@ export function validateHookInput(event, raw) {
 }
 /**
  * Normalize session_id field from various formats:
+ * - worker_session_id (disposable Controller worker identity)
  * - session_id (snake_case from CC)
  * - sessionId (camelCase internal)
  * - CLAUDE_SESSION_ID (env var fallback)
  */
 export function normalizeSessionId(input) {
+    if (typeof input.worker_session_id === "string") {
+        return input.worker_session_id;
+    }
     if (typeof input.sessionId === "string") {
         return input.sessionId;
     }

package/dist/hooks/state-manager.d.ts

@@ -2,7 +2,7 @@
  * Intent DNA — DNAStateManager
  *
  * Class-based facade over state.ts module functions. Bundles projectDir +
- * sessionId into a single object so call sites don't repeat those args.
+ * disposable workerSessionId into a single object so call sites don't repeat it.
  * Adds experience chain persistence (markdown + structured JSON) and
  * lifecycle operations (init / cleanup / isStale) that state.ts lacks.
  *
@@ -22,8 +22,8 @@ export interface ExperienceEntry {
 }
 export declare class DNAStateManager {
     private readonly projectDir;
-    private readonly sessionId?;
-    constructor(projectDir: string, sessionId?: string | undefined);
+    private readonly workerSessionId?;
+    constructor(projectDir: string, workerSessionId?: string | undefined);
     readWorkflowState(stalenessMs?: number): Promise<DNAWorkflowState | null>;
     writeWorkflowState(state: DNAWorkflowState): Promise<void>;
     clearWorkflowState(): Promise<void>;
@@ -38,8 +38,8 @@ export declare class DNAStateManager {
     /** Ensure session directory structure exists. */
     init(): Promise<void>;
     /**
-     * Remove this manager's state files.
-     * Callers that need trace rotation should invoke rotateTraces() from state.ts separately.
+     * Remove only this disposable worker's Hook directory.
+     * Durable Controller run/task/result/handoff records are outside this boundary.
      */
     cleanup(): Promise<void>;
     /** True when workflow.json started_at exceeds the staleness threshold. */

package/dist/hooks/state-manager.js

@@ -2,7 +2,7 @@
  * Intent DNA — DNAStateManager
  *
  * Class-based facade over state.ts module functions. Bundles projectDir +
- * sessionId into a single object so call sites don't repeat those args.
+ * disposable workerSessionId into a single object so call sites don't repeat it.
  * Adds experience chain persistence (markdown + structured JSON) and
  * lifecycle operations (init / cleanup / isStale) that state.ts lacks.
  *
@@ -10,29 +10,31 @@
  * class delegates to them. Prefer this class in new code; state.ts exports
  * are @deprecated for direct use.
  */
-import { readFile, mkdir, unlink, stat } from "node:fs/promises";
+import { readFile, mkdir, stat } from "node:fs/promises";
 import { join } from "node:path";
-import { resolveStateDir, readWorkflowState as rwState, writeWorkflowState as wwState, clearWorkflowState as cwState, appendAudit as aAudit, readSurgeonAttempts as rSurg, writeSurgeonAttempts as wSurg, readSessionReads as rReads, appendSessionRead as aRead, atomicWrite, } from "./state.js";
+import { resolveStateDir, readWorkflowState as rwState, writeWorkflowState as wwState, clearWorkflowState as cwState, appendAudit as aAudit, readSurgeonAttempts as rSurg, writeSurgeonAttempts as wSurg, readSessionReads as rReads, appendSessionRead as aRead, atomicWrite, atomicUpdateJson, cleanupWorkerHookState, } from "./state.js";
 const EXPERIENCE_JSON = "workflow/experience.json";
 const EXPERIENCE_MD = "workflow/experience.md";
 const DEFAULT_STALENESS_MS = 2 * 60 * 60 * 1000; // 2h — matches state.ts
 // ── Manager ────────────────────────────────────────────────
 export class DNAStateManager {
     projectDir;
-    sessionId;
-    constructor(projectDir, sessionId) {
+    workerSessionId;
+    constructor(projectDir, workerSessionId) {
         this.projectDir = projectDir;
-        this.sessionId = sessionId;
+        this.workerSessionId = workerSessionId;
     }
     // ── Workflow state ──
     readWorkflowState(stalenessMs = DEFAULT_STALENESS_MS) {
-        return rwState(this.projectDir, this.sessionId, stalenessMs);
+        return rwState(this.projectDir, this.workerSessionId, stalenessMs);
     }
     writeWorkflowState(state) {
-        return wwState(this.projectDir, state, this.sessionId);
+        return wwState(this.projectDir, state, this.workerSessionId);
     }
     clearWorkflowState() {
-        return cwState(this.projectDir, this.sessionId);
+        return this.workerSessionId
+            ? cleanupWorkerHookState(this.projectDir, this.workerSessionId)
+            : cwState(this.projectDir);
     }
     // ── Audit log ──
     appendAudit(entry) {
@@ -40,17 +42,17 @@ export class DNAStateManager {
     }
     // ── Surgeon attempts ──
     readSurgeonAttempts() {
-        return rSurg(this.projectDir, this.sessionId);
+        return rSurg(this.projectDir, this.workerSessionId);
     }
     writeSurgeonAttempts(state) {
-        return wSurg(this.projectDir, state, this.sessionId);
+        return wSurg(this.projectDir, state, this.workerSessionId);
     }
     // ── Session reads ──
     readSessionReads() {
-        return rReads(this.projectDir, this.sessionId);
+        return rReads(this.projectDir, this.workerSessionId);
     }
     appendSessionRead(filePath) {
-        return aRead(this.projectDir, filePath, this.sessionId);
+        return aRead(this.projectDir, filePath, this.workerSessionId);
     }
     // ── Experience chain (new) ──
     async readExperienceChain() {
@@ -69,28 +71,28 @@ export class DNAStateManager {
         await atomicWrite(this.path(EXPERIENCE_MD), renderExperienceMarkdown(chain));
     }
     async appendExperience(entry) {
-        const chain = await this.readExperienceChain();
-        chain.push(entry);
-        await this.writeExperienceChain(chain);
+        const chain = await atomicUpdateJson(this.path(EXPERIENCE_JSON), [], (current) => [...current, entry]);
+        await atomicWrite(this.path(EXPERIENCE_MD), renderExperienceMarkdown(chain));
     }
     // ── Lifecycle ──
     /** Ensure session directory structure exists. */
     async init() {
-        await mkdir(resolveStateDir(this.projectDir, this.sessionId), { recursive: true });
+        await mkdir(resolveStateDir(this.projectDir, this.workerSessionId), { recursive: true });
     }
     /**
-     * Remove this manager's state files.
-     * Callers that need trace rotation should invoke rotateTraces() from state.ts separately.
+     * Remove only this disposable worker's Hook directory.
+     * Durable Controller run/task/result/handoff records are outside this boundary.
      */
     async cleanup() {
-        const dir = resolveStateDir(this.projectDir, this.sessionId);
-        for (const rel of ["workflow.json", EXPERIENCE_JSON, EXPERIENCE_MD, "workflow/surgeon-attempts.json", "workflow/session-reads.json"]) {
-            await unlink(join(dir, rel)).catch(() => { });
+        if (this.workerSessionId) {
+            await cleanupWorkerHookState(this.projectDir, this.workerSessionId);
+            return;
         }
+        await cwState(this.projectDir);
     }
     /** True when workflow.json started_at exceeds the staleness threshold. */
     async isStale(stalenessMs = DEFAULT_STALENESS_MS) {
-        const wfPath = join(resolveStateDir(this.projectDir, this.sessionId), "workflow.json");
+        const wfPath = join(resolveStateDir(this.projectDir, this.workerSessionId), "workflow.json");
         try {
             const raw = await readFile(wfPath, "utf-8");
             const state = JSON.parse(raw);
@@ -110,7 +112,7 @@ export class DNAStateManager {
         }
     }
     path(rel) {
-        return join(resolveStateDir(this.projectDir, this.sessionId), rel);
+        return join(resolveStateDir(this.projectDir, this.workerSessionId), rel);
     }
 }
 // ── Markdown rendering ────────────────────────────────────

package/dist/hooks/state.d.ts

@@ -21,6 +21,12 @@ export interface DNAWorkflowState {
     current_role: string;
     iteration: number;
     session_id: string;
+    /** Disposable Controller worker identity used as the Hook state key. */
+    worker_session_id?: string;
+    /** Durable correlation only; Hook state is never authoritative for these IDs. */
+    run_id?: string;
+    step_id?: string;
+    attempt_id?: string;
     started_at: string;
     inputs?: Record<string, string>;
     resolved_variables?: Record<string, string>;
@@ -145,8 +151,10 @@ export declare function appendCompletedArtifact(projectDir: string, stepId: stri
     artifact_id?: string;
     metadata?: Record<string, unknown>;
 }, sessionId?: string): Promise<void>;
-/** Atomic write: write to temp file then rename. */
+/** Atomic owner-checked temp/fsync/rename write adapted from the approved store primitive. */
 export declare function atomicWrite(filePath: string, data: string): Promise<void>;
+export declare function atomicAppend(filePath: string, data: string): Promise<void>;
+export declare function atomicUpdateJson<T>(filePath: string, fallback: T, update: (current: T) => T | undefined): Promise<T>;
 /**
  * Read surgeon attempt state. Returns default state if not found.
  * @deprecated Prefer `DNAStateManager.readSurgeonAttempts()`.
@@ -157,6 +165,7 @@ export declare function readSurgeonAttempts(projectDir: string, sessionId?: stri
  * @deprecated Prefer `DNAStateManager.writeSurgeonAttempts()`.
  */
 export declare function writeSurgeonAttempts(projectDir: string, state: SurgeonAttemptState, sessionId?: string): Promise<void>;
+export declare function updateSurgeonAttempts(projectDir: string, sessionId: string, update: (current: SurgeonAttemptState) => SurgeonAttemptState): Promise<SurgeonAttemptState>;
 /** Tracks which files a session has Read — for context gate enforcement */
 export interface SessionReadsState {
     session_id: string;
@@ -238,9 +247,16 @@ export declare function listSessions(projectDir: string): Promise<string[]>;
  */
 export declare function rotateTraces(projectDir: string): Promise<number>;
 /**
- * Clean up stale state from `.dna/state/sessions/` and root state.
- * Removes workflow.json files older than DEFAULT_STALENESS_MS (2h).
+ * Clean up stale worker state from `.dna/state/sessions/`.
+ * Removes worker directories older than DEFAULT_STALENESS_MS (2h).
  * Called on SessionStart to prevent state accumulation.
  * Fail-open: never throws.
  */
 export declare function cleanStaleState(projectDir: string): Promise<number>;
+/**
+ * Delete exactly one disposable worker's Hook context.
+ *
+ * Controller ledgers live outside `.dna/state/sessions` and are never inspected
+ * or removed by this operation.
+ */
+export declare function cleanupWorkerHookState(projectDir: string, workerSessionId: string): Promise<void>;