intentdna 1.8.6 → 1.8.7

package/dist/hooks/state.js

@@ -9,8 +9,8 @@
  * All read operations are fail-safe (return null on error, never throw).
  * All write operations use atomic temp+rename pattern.
  */
-import { readFile, writeFile, rename, mkdir, appendFile, unlink, readdir, stat } from "node:fs/promises";
-import { createHash } from "node:crypto";
+import { readFile, rename, mkdir, unlink, readdir, stat, open, rm, utimes } from "node:fs/promises";
+import { createHash, randomUUID } from "node:crypto";
 import { join, dirname } from "node:path";
 import { CASCADE_LAYER_NAMES, RUNTIME_DECISION_EVENT_SCHEMA_VERSION } from "../governance/index.js";
 // ── Types ──────────────────────────────────────────────────
@@ -145,6 +145,11 @@ export async function readWorkflowState(projectDir, sessionId, stalenessMs = DEF
     try {
         const raw = await readFile(filePath, "utf-8");
         const state = JSON.parse(raw);
+        if (sessionId) {
+            const storedWorkerSessionId = state.worker_session_id ?? state.session_id;
+            if (storedWorkerSessionId !== sessionId)
+                return null;
+        }
         // Staleness check based on started_at
         if (stalenessMs > 0 && state.started_at) {
             const age = Date.now() - new Date(state.started_at).getTime();
@@ -165,7 +170,16 @@ export async function writeWorkflowState(projectDir, state, sessionId) {
     const stateDir = resolveStateDir(projectDir, sessionId);
     await mkdir(stateDir, { recursive: true });
     const workflowPath = join(stateDir, WORKFLOW_FILE);
-    await atomicWrite(workflowPath, JSON.stringify(state, null, 2));
+    const workerState = sessionId
+        ? {
+            ...state,
+            session_id: sessionId,
+            ...(state.worker_session_id === undefined
+                ? {}
+                : { worker_session_id: sessionId }),
+        }
+        : state;
+    await atomicWrite(workflowPath, JSON.stringify(workerState, null, 2));
 }
 /**
  * Clear workflow state (workflow complete).
@@ -193,25 +207,25 @@ export async function appendAudit(projectDir, entry) {
     await mkdir(auditDir, { recursive: true });
     const date = entry.timestamp.slice(0, 10); // YYYY-MM-DD
     const logPath = join(auditDir, `violations-${date}.log`);
-    // Dedup: check if identical entry (same event+tool+second) already exists
-    const dedupKey = `${entry.event}|${entry.tool_name ?? ""}|${entry.timestamp.slice(0, 19)}`;
-    try {
-        const existing = await readFile(logPath, "utf-8");
-        const lines = existing.trimEnd().split("\n");
-        // Check last 10 lines for dedup (avoid scanning entire file)
-        const recentLines = lines.slice(-10);
-        for (const line of recentLines) {
-            try {
-                const prev = JSON.parse(line);
-                const prevKey = `${prev.event}|${prev.tool_name ?? ""}|${prev.timestamp.slice(0, 19)}`;
-                if (prevKey === dedupKey)
-                    return; // Already logged
+    await withStateFileLock(logPath, async (lock) => {
+        const dedupKey = `${entry.event}|${entry.tool_name ?? ""}|${entry.timestamp.slice(0, 19)}`;
+        try {
+            const existing = await readFile(logPath, "utf-8");
+            const recentLines = existing.trimEnd().split("\n").slice(-10);
+            for (const line of recentLines) {
+                try {
+                    const prev = JSON.parse(line);
+                    const prevKey = `${prev.event}|${prev.tool_name ?? ""}|${prev.timestamp.slice(0, 19)}`;
+                    if (prevKey === dedupKey)
+                        return;
+                }
+                catch { /* skip malformed historical lines */ }
             }
-            catch { /* skip malformed lines */ }
         }
-    }
-    catch { /* file doesn't exist yet */ }
-    await appendFile(logPath, JSON.stringify(entry) + "\n", "utf-8");
+        catch { /* file doesn't exist yet */ }
+        await lock.assertOwned();
+        await atomicAppendUnlocked(logPath, JSON.stringify(entry) + "\n");
+    });
 }
 // ── Completed Artifacts ───────────────────────────────────
 /**
@@ -219,44 +233,264 @@ export async function appendAudit(projectDir, entry) {
  * Reads current workflow state, appends the artifact, writes back atomically.
  */
 export async function appendCompletedArtifact(projectDir, stepId, artifact, sessionId) {
-    const state = await readWorkflowState(projectDir, sessionId, 0);
-    if (!state)
-        return;
-    const artifacts = state.completed_artifacts ?? [];
-    let stepEntry = artifacts.find(a => a.step_id === stepId);
-    if (!stepEntry) {
-        stepEntry = { step_id: stepId, artifacts: [] };
-        artifacts.push(stepEntry);
-    }
-    const verifiedAt = new Date().toISOString();
-    const existing = stepEntry.artifacts.find(a => a.type === artifact.type && a.path === artifact.path);
-    if (existing) {
-        existing.verified_at = verifiedAt;
-        if (artifact.artifact_id)
-            existing.artifact_id = artifact.artifact_id;
-        if (artifact.metadata)
-            existing.metadata = artifact.metadata;
-        state.completed_artifacts = artifacts;
-        await writeWorkflowState(projectDir, state, sessionId);
-        return;
-    }
-    stepEntry.artifacts.push({
-        type: artifact.type,
-        path: artifact.path,
-        verified_at: verifiedAt,
-        ...(artifact.artifact_id ? { artifact_id: artifact.artifact_id } : {}),
-        ...(artifact.metadata ? { metadata: artifact.metadata } : {}),
+    const workflowPath = join(resolveStateDir(projectDir, sessionId), WORKFLOW_FILE);
+    await atomicUpdateJson(workflowPath, null, (state) => {
+        if (!state)
+            return undefined;
+        const artifacts = state.completed_artifacts ?? [];
+        let stepEntry = artifacts.find(a => a.step_id === stepId);
+        if (!stepEntry) {
+            stepEntry = { step_id: stepId, artifacts: [] };
+            artifacts.push(stepEntry);
+        }
+        const verifiedAt = new Date().toISOString();
+        const existing = stepEntry.artifacts.find(a => a.type === artifact.type && a.path === artifact.path);
+        if (existing) {
+            existing.verified_at = verifiedAt;
+            if (artifact.artifact_id)
+                existing.artifact_id = artifact.artifact_id;
+            if (artifact.metadata)
+                existing.metadata = artifact.metadata;
+        }
+        else {
+            stepEntry.artifacts.push({
+                type: artifact.type,
+                path: artifact.path,
+                verified_at: verifiedAt,
+                ...(artifact.artifact_id ? { artifact_id: artifact.artifact_id } : {}),
+                ...(artifact.metadata ? { metadata: artifact.metadata } : {}),
+            });
+        }
+        return { ...state, completed_artifacts: artifacts };
     });
-    state.completed_artifacts = artifacts;
-    await writeWorkflowState(projectDir, state, sessionId);
 }
 // ── Internal ───────────────────────────────────────────────
-/** Atomic write: write to temp file then rename. */
+const STATE_LOCK_WAIT_MS = 5_000;
+const STATE_LOCK_RETRY_MS = 25;
+const STATE_LOCK_STALE_MS = 5 * 60_000;
+const STATE_LOCK_HEARTBEAT_MS = 100_000;
+const DIRECTORY_MODE = 0o700;
+const FILE_MODE = 0o600;
+function isErrno(error, code) {
+    return error instanceof Error
+        && "code" in error
+        && error.code === code;
+}
+function isUnsupportedDirectorySync(error) {
+    if (!(error instanceof Error) || !("code" in error))
+        return false;
+    const code = error.code;
+    return code === "EINVAL"
+        || code === "ENOTSUP"
+        || code === "EISDIR"
+        || (code === "EPERM" && process.platform === "win32");
+}
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+async function syncParentDirectory(filePath) {
+    let handle;
+    try {
+        handle = await open(dirname(filePath), "r");
+    }
+    catch (error) {
+        if (isUnsupportedDirectorySync(error))
+            return;
+        throw error;
+    }
+    try {
+        await handle.sync();
+    }
+    catch (error) {
+        if (!isUnsupportedDirectorySync(error))
+            throw error;
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function atomicWriteUnlocked(filePath, data) {
+    const tmpPath = `${filePath}.tmp.${process.pid}.${randomUUID()}`;
+    await mkdir(dirname(filePath), { recursive: true, mode: DIRECTORY_MODE });
+    let handle;
+    try {
+        handle = await open(tmpPath, "wx", FILE_MODE);
+        await handle.writeFile(data, "utf-8");
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await rename(tmpPath, filePath);
+        await syncParentDirectory(filePath);
+    }
+    catch (error) {
+        await handle?.close().catch(() => undefined);
+        await rm(tmpPath, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+async function atomicAppendUnlocked(filePath, data) {
+    await mkdir(dirname(filePath), { recursive: true, mode: DIRECTORY_MODE });
+    const handle = await open(filePath, "a", FILE_MODE);
+    try {
+        await handle.writeFile(data, "utf-8");
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function readLockOwner(ownerPath) {
+    try {
+        return (await readFile(ownerPath, "utf-8")).trim();
+    }
+    catch (error) {
+        if (isErrno(error, "ENOENT"))
+            return null;
+        throw error;
+    }
+}
+async function lockIsStale(lockDirectory) {
+    try {
+        const lease = await stat(join(lockDirectory, "lease"));
+        return Date.now() - lease.mtimeMs > STATE_LOCK_STALE_MS;
+    }
+    catch (error) {
+        if (!isErrno(error, "ENOENT"))
+            return false;
+    }
+    try {
+        const lock = await stat(lockDirectory);
+        return Date.now() - lock.mtimeMs > STATE_LOCK_STALE_MS;
+    }
+    catch {
+        return false;
+    }
+}
+async function recoverStaleLock(lockDirectory) {
+    if (!(await lockIsStale(lockDirectory)))
+        return false;
+    const quarantine = `${lockDirectory}.reclaimed.${randomUUID()}`;
+    try {
+        await rename(lockDirectory, quarantine);
+    }
+    catch (error) {
+        if (isErrno(error, "ENOENT"))
+            return true;
+        throw error;
+    }
+    await rm(quarantine, { recursive: true, force: true });
+    return true;
+}
+async function withStateFileLock(filePath, operation) {
+    const lockDirectory = `${filePath}.lock`;
+    const owner = `${process.pid}.${Date.now()}.${randomUUID()}`;
+    const ownerPath = join(lockDirectory, "owner");
+    const leasePath = join(lockDirectory, "lease");
+    const deadline = Date.now() + STATE_LOCK_WAIT_MS;
+    await mkdir(dirname(filePath), { recursive: true, mode: DIRECTORY_MODE });
+    while (true) {
+        try {
+            await mkdir(lockDirectory, { mode: DIRECTORY_MODE });
+            try {
+                const ownerHandle = await open(ownerPath, "wx", FILE_MODE);
+                await ownerHandle.writeFile(owner, "utf-8");
+                await ownerHandle.sync();
+                await ownerHandle.close();
+                const leaseHandle = await open(leasePath, "wx", FILE_MODE);
+                await leaseHandle.writeFile(owner, "utf-8");
+                await leaseHandle.sync();
+                await leaseHandle.close();
+            }
+            catch (error) {
+                await rm(lockDirectory, { recursive: true, force: true });
+                throw error;
+            }
+            break;
+        }
+        catch (error) {
+            if (!isErrno(error, "EEXIST"))
+                throw error;
+            if (await recoverStaleLock(lockDirectory))
+                continue;
+            if (Date.now() >= deadline) {
+                throw new Error(`Timed out acquiring Hook state lock for ${filePath}`);
+            }
+            await sleep(STATE_LOCK_RETRY_MS);
+        }
+    }
+    let heartbeatRunning = false;
+    let lostOwnership = false;
+    const refresh = async () => {
+        if (heartbeatRunning || lostOwnership)
+            return;
+        heartbeatRunning = true;
+        try {
+            if ((await readLockOwner(ownerPath)) !== owner) {
+                lostOwnership = true;
+                return;
+            }
+            const now = new Date();
+            await utimes(leasePath, now, now);
+        }
+        catch {
+            lostOwnership = true;
+        }
+        finally {
+            heartbeatRunning = false;
+        }
+    };
+    const timer = setInterval(() => void refresh(), STATE_LOCK_HEARTBEAT_MS);
+    timer.unref();
+    const lock = {
+        async assertOwned() {
+            if (lostOwnership || (await readLockOwner(ownerPath)) !== owner) {
+                lostOwnership = true;
+                throw new Error(`Hook state lock ownership was lost for ${filePath}`);
+            }
+        },
+    };
+    try {
+        return await operation(lock);
+    }
+    finally {
+        clearInterval(timer);
+        while (heartbeatRunning)
+            await sleep(1);
+        if ((await readLockOwner(ownerPath).catch(() => null)) === owner) {
+            await rm(lockDirectory, { recursive: true, force: true });
+        }
+    }
+}
+/** Atomic owner-checked temp/fsync/rename write adapted from the approved store primitive. */
 export async function atomicWrite(filePath, data) {
-    const tmpPath = filePath + ".tmp." + process.pid;
-    await mkdir(dirname(filePath), { recursive: true });
-    await writeFile(tmpPath, data, "utf-8");
-    await rename(tmpPath, filePath);
+    await withStateFileLock(filePath, async (lock) => {
+        await lock.assertOwned();
+        await atomicWriteUnlocked(filePath, data);
+    });
+}
+export async function atomicAppend(filePath, data) {
+    await withStateFileLock(filePath, async (lock) => {
+        await lock.assertOwned();
+        await atomicAppendUnlocked(filePath, data);
+    });
+}
+export async function atomicUpdateJson(filePath, fallback, update) {
+    return withStateFileLock(filePath, async (lock) => {
+        let current = fallback;
+        try {
+            current = JSON.parse(await readFile(filePath, "utf-8"));
+        }
+        catch (error) {
+            if (!isErrno(error, "ENOENT"))
+                throw error;
+        }
+        const next = update(current);
+        if (next === undefined)
+            return current;
+        await lock.assertOwned();
+        await atomicWriteUnlocked(filePath, JSON.stringify(next, null, 2));
+        return next;
+    });
 }
 // ── Surgeon Attempt State ────────────────────────────────
 const SURGEON_ATTEMPTS_FILE = "workflow/surgeon-attempts.json";
@@ -297,6 +531,10 @@ export async function writeSurgeonAttempts(projectDir, state, sessionId) {
     const filePath = join(stateDir, SURGEON_ATTEMPTS_FILE);
     await atomicWrite(filePath, JSON.stringify(state, null, 2));
 }
+export async function updateSurgeonAttempts(projectDir, sessionId, update) {
+    const filePath = join(resolveStateDir(projectDir, sessionId), SURGEON_ATTEMPTS_FILE);
+    return atomicUpdateJson(filePath, defaultSurgeonState(), update);
+}
 const SESSION_READS_FILE = "workflow/session-reads.json";
 /**
  * Read session reads state. Returns empty reads if not found.
@@ -326,11 +564,10 @@ export async function writeSessionReads(projectDir, state, sessionId) {
  * @deprecated Prefer `DNAStateManager.appendSessionRead()`.
  */
 export async function appendSessionRead(projectDir, filePath, sessionId) {
-    const state = await readSessionReads(projectDir, sessionId);
-    if (!state.read_files.includes(filePath)) {
-        state.read_files.push(filePath);
-        await writeSessionReads(projectDir, state, sessionId);
-    }
+    const statePath = join(resolveStateDir(projectDir, sessionId), SESSION_READS_FILE);
+    await atomicUpdateJson(statePath, { session_id: sessionId ?? "", read_files: [] }, (state) => state.read_files.includes(filePath)
+        ? undefined
+        : { ...state, read_files: [...state.read_files, filePath] });
 }
 const VERIFIER_RESULTS_FILE = "workflow/verifier-results.json";
 export function verifierResultId(result) {
@@ -408,9 +645,8 @@ export async function writeVerifierResults(projectDir, results, sessionId) {
     await atomicWrite(filePath, JSON.stringify(results, null, 2));
 }
 export async function appendVerifierResult(projectDir, result, sessionId) {
-    const results = await readVerifierResultsFile(projectDir, sessionId);
-    results.push(normalizeVerifierResult(result));
-    await writeVerifierResults(projectDir, results, sessionId);
+    const statePath = join(resolveStateDir(projectDir, sessionId), VERIFIER_RESULTS_FILE);
+    await atomicUpdateJson(statePath, [], (results) => [...results, normalizeVerifierResult(result)]);
 }
 const TRACE_DIR = "trace";
 const RUNTIME_DECISION_DIR = "runtime-decisions";
@@ -447,7 +683,7 @@ export async function appendTrace(projectDir, entry, sessionId) {
                 return;
         }
         catch { /* file doesn't exist yet */ }
-        await appendFile(globalPath, line, "utf-8");
+        await atomicAppend(globalPath, line);
         // 2. Session-local trace (if session isolated)
         if (sessionId) {
             const sessionDir = resolveStateDir(projectDir, sessionId);
@@ -459,7 +695,7 @@ export async function appendTrace(projectDir, entry, sessionId) {
                     return;
             }
             catch { /* file doesn't exist yet */ }
-            await appendFile(sessionTracePath, line, "utf-8");
+            await atomicAppend(sessionTracePath, line);
         }
     }
     catch {
@@ -595,7 +831,7 @@ export async function appendEvidenceCaptureEvent(projectDir, event) {
         const date = dateFromIso(sanitized.captured_at);
         const captureDir = join(projectDir, ".dna", EVIDENCE_CAPTURE_DIR);
         await mkdir(captureDir, { recursive: true });
-        await appendFile(join(captureDir, evidenceCaptureFileName(date)), line, "utf-8");
+        await atomicAppend(join(captureDir, evidenceCaptureFileName(date)), line);
     }
     catch {
         // Fail-open: evidence capture write failure never affects hook execution
@@ -608,11 +844,11 @@ export async function appendRuntimeDecisionEvent(projectDir, event, sessionId) {
         const date = new Date().toISOString().slice(0, 10);
         const globalDir = join(projectDir, ".dna", "state", RUNTIME_DECISION_DIR);
         await mkdir(globalDir, { recursive: true });
-        await appendFile(join(globalDir, decisionFileName(date)), line, "utf-8");
+        await atomicAppend(join(globalDir, decisionFileName(date)), line);
         if (sessionId) {
             const sessionDir = resolveStateDir(projectDir, projectedSessionDirName(sessionId));
             await mkdir(sessionDir, { recursive: true });
-            await appendFile(join(sessionDir, "runtime-decisions.jsonl"), line, "utf-8");
+            await atomicAppend(join(sessionDir, "runtime-decisions.jsonl"), line);
         }
     }
     catch {
@@ -865,8 +1101,8 @@ export async function rotateTraces(projectDir) {
 }
 // ── Stale State Cleanup ──────────────────────────────────
 /**
- * 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.
  */
@@ -910,21 +1146,32 @@ export async function cleanStaleState(projectDir) {
     catch {
         // No sessions dir — nothing to clean
     }
-    // Also clean root-level stale workflow state
-    const rootWfPath = join(projectDir, ".dna", "state", WORKFLOW_FILE);
+    const rootWorkflowPath = join(projectDir, ".dna", "state", WORKFLOW_FILE);
     try {
-        const raw = await readFile(rootWfPath, "utf-8");
-        const state = JSON.parse(raw);
-        if (state.started_at) {
-            const age = Date.now() - new Date(state.started_at).getTime();
-            if (age > DEFAULT_STALENESS_MS) {
-                await unlink(rootWfPath).catch(() => { });
-                removed++;
-            }
+        const state = JSON.parse(await readFile(rootWorkflowPath, "utf-8"));
+        if (state.started_at
+            && Date.now() - new Date(state.started_at).getTime()
+                > DEFAULT_STALENESS_MS) {
+            await unlink(rootWorkflowPath).catch(() => { });
+            removed += 1;
         }
     }
     catch {
-        // No root workflow state
+        // No valid root workflow state.
     }
     return removed;
 }
+/**
+ * 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 async function cleanupWorkerHookState(projectDir, workerSessionId) {
+    const workerDir = resolveStateDir(projectDir, safePathComponent(workerSessionId, "worker_session_id"));
+    const sessionsDir = join(projectDir, ".dna", "state", "sessions");
+    if (dirname(workerDir) !== sessionsDir) {
+        throw new Error("Refusing to clean non-worker Hook state");
+    }
+    await rm(workerDir, { recursive: true, force: true });
+}

package/dist/runtime/diagnosis-contract-verifier.d.ts

@@ -0,0 +1,11 @@
+export type DiagnosisContractVerifyMode = "analyze" | "review";
+export interface DiagnosisContractVerifyOptions {
+    projectDir: string;
+    moduleName: string;
+    mode: DiagnosisContractVerifyMode;
+}
+export interface DiagnosisContractVerifyResult {
+    passed: boolean;
+    reason?: string;
+    evidence?: string;
+}