@deksden-com/dd-flow-cli 0.9.0-beta.14 → 0.9.0-beta.141

package/dist/services/branch-context.js

@@ -166,11 +166,11 @@ function gitFacts(workspacePath) {
     if (!fs.existsSync(workspacePath)) {
         return { status: "missing_workspace", actual_branch: null, dirty: null, path: workspacePath };
     }
-    const branch = spawnSync("git", ["-C", workspacePath, "rev-parse", "--abbrev-ref", "HEAD"], { encoding: "utf8" });
+    const branch = spawnSync("git", ["-C", workspacePath, "rev-parse", "--abbrev-ref", "HEAD"], { encoding: "utf8", timeout: 5000 });
     if (branch.status !== 0) {
-        return { status: "not_git_checkout", actual_branch: null, dirty: null, path: workspacePath };
+        return { status: branch.error || branch.signal ? "observation_unavailable" : "not_git_checkout", actual_branch: null, dirty: null, path: workspacePath };
     }
-    const status = spawnSync("git", ["-C", workspacePath, "status", "--porcelain"], { encoding: "utf8" });
+    const status = spawnSync("git", ["-C", workspacePath, "status", "--porcelain"], { encoding: "utf8", timeout: 5000 });
     return {
         status: "ok",
         actual_branch: branch.stdout.trim() || null,

package/dist/services/canon.js

@@ -1,27 +1,30 @@
 import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
+import { AppError } from "../shared/errors.js";
+import { prepareError } from "../cli/input-preparation.js";
 const canonRootKey = "canon.root";
-export function registerCanonRoot(context, input) {
+export function prepareCanonRegistration(context, input) {
+    if (typeof input.root !== "string" || !input.root.trim())
+        return prepareError(new AppError("validation", "Canon root must be a non-empty path", 2));
     const resolution = resolveCanonRoot(context, { explicitRoot: input.root, allowRegistered: false });
     if (!resolution.ok || !resolution.canon) {
-        return {
-            ...resolution,
-            action: "register",
-            exit_code: 1
-        };
+        return prepareError(new AppError("validation", "Canon root cannot be registered", 2, { root: input.root, blockers: resolution.blockers, candidates: resolution.candidates, bootstrap: resolution.bootstrap }));
     }
+    return resolution.canon;
+}
+export function registerCanonRoot(context, input, canon = prepareCanonRegistration(context, input)) {
     const now = context.now();
     context.db.run(`INSERT INTO runtime_config (key, value_json, created_at, updated_at)
      VALUES (?, ?, ?, ?)
      ON CONFLICT(key) DO UPDATE SET
        value_json = excluded.value_json,
-       updated_at = excluded.updated_at`, [canonRootKey, JSON.stringify({ root: resolution.canon.root }), now, now]);
+       updated_at = excluded.updated_at`, [canonRootKey, JSON.stringify({ root: canon.root }), now, now]);
     return {
         ok: true,
         action: "register",
         canon: {
-            ...resolution.canon,
+            ...canon,
             source: "registered"
         },
         db_path: context.db.path

package/dist/services/check-runner-evidence.js

@@ -0,0 +1,250 @@
+import fs from "node:fs";
+import crypto from "node:crypto";
+import { stripVTControlCharacters } from "node:util";
+import path from "node:path";
+import { parse } from "shell-quote";
+import { AppError } from "../shared/errors.js";
+import { validateObservationDuration } from "../harness-runtime/lib/observation-clock.mjs";
+function object(value) { return Boolean(value) && typeof value === "object" && !Array.isArray(value); }
+function boundedString(value, bytes) { return typeof value === "string" && Buffer.byteLength(value) <= bytes; }
+const validatedBrowserProofs = new WeakSet();
+function relativeProofPath(value) { return typeof value === "string" && value.length > 0 && Buffer.byteLength(value) <= 4096 && !path.isAbsolute(value) && !value.includes("\\") && value.split("/").every(part => part !== "" && part !== "." && part !== ".."); }
+function proofArtifact(value) { return object(value) && relativeProofPath(value.relative_path) && typeof value.sha256 === "string" && /^[a-f0-9]{64}$/.test(value.sha256); }
+function browserProofShape(proof) {
+    const attempt = proof.attempt, step = proof.step;
+    return proof.native_code === "PLAYWRIGHT_ACTION_INACTIVITY" && object(attempt) && boundedString(attempt.invocation_id, 4096) && boundedString(attempt.test_id, 4096) && Boolean(attempt.test_id)
+        && [attempt.retry, attempt.repeat_each_index, attempt.worker_index].every(value => Number.isSafeInteger(value) && value >= 0)
+        && object(step) && boundedString(step.id, 4096) && Boolean(step.id) && ["pw:api", "expect"].includes(String(step.category)) && step.file === proof.file && Number.isSafeInteger(step.line) && step.line > 0
+        && proofArtifact(proof.worker_snapshot) && proofArtifact(proof.native_result);
+}
+export function runnerFailureValid(value) {
+    if (!object(value) || typeof value.category !== "string" || !["assertion", "tooling", "unclassified"].includes(value.category))
+        return false;
+    if (value.diagnostic_artifact !== undefined && !proofArtifact(value.diagnostic_artifact))
+        return false;
+    for (const key of ["code", "message", "file", "test_id", "native_code", "classification_reason"])
+        if (value[key] !== undefined && !boundedString(value[key], 4096))
+            return false;
+    if (value.stack !== undefined && !boundedString(value.stack, 16384) || value.origin !== undefined && (typeof value.origin !== "string" || !["candidate", "tooling", "unknown"].includes(value.origin)) || value.phase !== undefined && (typeof value.phase !== "string" || !["test", "setup", "teardown", "collection", "runner"].includes(value.phase)))
+        return false;
+    if (value.repair_evidence !== undefined) {
+        const proof = value.repair_evidence;
+        if (!object(proof) || !boundedString(proof.rule, 128) || !boundedString(proof.native_code, 128) || !boundedString(proof.file, 4096) || !object(proof.world))
+            return false;
+        const world = proof.world;
+        if (world.schema_id !== "dd-tasks/test-world-ready@1" || !boundedString(world.invocation_id, 4096) || typeof world.world_id !== "string" || !/^[a-f0-9]{32}$/.test(world.world_id) || typeof world.migrations_sha256 !== "string" || !/^[a-f0-9]{64}$/.test(world.migrations_sha256) || world.ready !== true || world.setup_completed !== true || !boundedString(world.role, 128) || !world.role)
+            return false;
+        if (proof.rule === "candidate_browser_action_inactivity" && !browserProofShape(proof))
+            return false;
+        if (!["candidate_sql_integrity", "candidate_browser_action_inactivity"].includes(String(proof.rule)))
+            return false;
+    }
+    return true;
+}
+function candidateFile(root, file) {
+    if (!root || !path.isAbsolute(file))
+        return false;
+    try {
+        const relative = path.relative(fs.realpathSync(root), fs.realpathSync(file));
+        return relative !== "" && relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative) && fs.statSync(file).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+export function candidateFailureFiles(evidence, root) {
+    return [...new Set((evidence?.failures ?? []).flatMap(failure => failure.file && candidateFile(root, failure.file) ? [failure.file] : []))];
+}
+function candidateFailure(failure, evidence, root, capturedFiles) {
+    const owned = (file) => capturedFiles === undefined ? candidateFile(root, file) : capturedFiles.includes(file);
+    if (failure.origin === "tooling" || failure.origin === "unknown")
+        return false;
+    if (failure.category === "assertion")
+        return failure.origin === undefined || failure.origin === "candidate" && failure.file !== undefined && owned(failure.file);
+    const proof = failure.repair_evidence;
+    if (proof?.rule === "candidate_browser_action_inactivity")
+        return validatedBrowserProofs.has(proof) && failure.category === "unclassified" && failure.phase === "test" && failure.origin === "candidate" && failure.native_code === proof.native_code && failure.file === proof.file && failure.test_id === proof.attempt.test_id && proof.attempt.invocation_id === evidence.binding.invocation_id && owned(proof.file);
+    return failure.category === "unclassified" && failure.origin === "candidate" && ["test", "setup"].includes(failure.phase ?? "") && proof?.rule === "candidate_sql_integrity" && ["23502", "23503", "23505", "23514"].includes(proof.native_code) && failure.native_code === proof.native_code && failure.file === proof.file && proof.world.invocation_id === evidence.binding.invocation_id && owned(proof.file);
+}
+export function runnerObservationDurations(environment) {
+    // Both observers leave the launcher its bounded physical cleanup tail.
+    return { startupMs: validateObservationDuration(validateObservationDuration(Number(environment.DD_FLOW_TEST_STARTUP_SILENCE_MS ?? 120_000)) + 10_000),
+        executionMs: validateObservationDuration(validateObservationDuration(Number(environment.DD_FLOW_TEST_EXECUTION_SILENCE_MS ?? 600_000)) + 15_000) };
+}
+/** Baseline uses argv rather than a shell alias. Recognize only a literal,
+ * unique execution contract; never guess shell expansion or compound syntax. */
+export function runnerContractForArgv(profile, command, args) {
+    if (profile.schema_id !== "dd-flow/code-check-profile@7" || !profile.runner_evidence_by_alias)
+        return null;
+    if (!runnerContractsValid(profile.runner_evidence_by_alias))
+        throw new AppError("invalid_code_check_profile", "Invalid baseline runner evidence contract", 2);
+    const matches = [];
+    for (const [alias, contract] of Object.entries(profile.runner_evidence_by_alias)) {
+        const source = profile.aliases?.[alias];
+        if (typeof source !== "string")
+            throw new AppError("invalid_code_check_profile", "Baseline runner evidence references an unknown alias", 2, { alias });
+        let expansion = false;
+        const tokens = parse(source, () => { expansion = true; return ""; });
+        if (!expansion && tokens.every(token => typeof token === "string") && JSON.stringify(tokens) === JSON.stringify([command, ...args]))
+            matches.push({ alias, command: source, contract });
+    }
+    if (matches.some(match => JSON.stringify(match.contract) !== JSON.stringify(matches[0].contract)))
+        throw new AppError("runner_evidence_ambiguous", "Baseline argv matches conflicting runner evidence contracts", 2, { aliases: matches.map(match => match.alias) });
+    return matches[0] ?? null;
+}
+/** Shared by CODE and EVAL baseline. The sole publisher owns this structured
+ * journal; logs belong on stdout/stderr. Partial final lines await append. */
+export function readRunnerProgress(file, invocationId, lastSequence = 0, now = Date.now()) {
+    try {
+        const text = readBoundedProofFile(file, 4 * 1024 * 1024).toString("utf8");
+        const accepted = [];
+        for (const line of text.split("\n").slice(0, -1)) {
+            if (Buffer.byteLength(line) > 16 * 1024)
+                throw new Error("Progress record exceeds 16 KiB");
+            const value = JSON.parse(line);
+            if (value && typeof value === "object" && !Array.isArray(value) && typeof value.invocation_id === "string" && value.invocation_id !== invocationId)
+                continue;
+            if (!value || typeof value !== "object" || Array.isArray(value) || value.schema_id !== "dd-flow/check-runner-progress@1" || value.invocation_id !== invocationId
+                || !Number.isSafeInteger(value.sequence) || value.sequence <= 0 || typeof value.at !== "string" || !Number.isFinite(Date.parse(value.at))
+                || !["startup", "execution"].includes(value.phase)
+                || !["setup_step_completed", "run_started", "module_collected", "test_started", "test_completed", "step_completed", "run_completed"].includes(value.event))
+                throw new Error("Malformed official progress record");
+            if (value.sequence <= lastSequence || Date.parse(value.at) > now)
+                continue;
+            accepted.push(value);
+            lastSequence = value.sequence;
+        }
+        return accepted;
+    }
+    catch (cause) {
+        if (cause.code === "ENOENT")
+            return [];
+        throw new AppError("runner_progress_invalid", "Runner progress cannot be safely observed", 1, { cause: cause.code ?? cause.message });
+    }
+}
+function readBoundedProofFile(file, limit) {
+    const fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+    try {
+        const stat = fs.fstatSync(fd);
+        if (!stat.isFile() || stat.size > limit)
+            throw new Error("Evidence is not a bounded regular file");
+        const buffer = Buffer.alloc(Math.min(limit + 1, stat.size + 1));
+        let length = 0;
+        while (length < buffer.length) {
+            const read = fs.readSync(fd, buffer, length, buffer.length - length, null);
+            if (!read)
+                break;
+            length += read;
+        }
+        if (length > limit || length > stat.size)
+            throw new Error("Evidence grew during observation");
+        return buffer.subarray(0, length);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function readProofArtifact(root, ref, limit = 256 * 1024) {
+    let current = root;
+    if (fs.lstatSync(current).isSymbolicLink())
+        throw new Error("Symlink evidence root");
+    for (const part of ref.relative_path.split("/")) {
+        current = path.join(current, part);
+        if (fs.lstatSync(current).isSymbolicLink())
+            throw new Error("Symlink proof artifact");
+    }
+    const bytes = readBoundedProofFile(current, limit);
+    if (crypto.createHash("sha256").update(bytes).digest("hex") !== ref.sha256)
+        throw new Error("Browser proof hash differs");
+    const value = JSON.parse(bytes.toString("utf8"));
+    if (!object(value))
+        throw new Error("Invalid proof object");
+    return value;
+}
+function matches(actual, expected) { return object(actual) && Object.entries(expected).every(([key, value]) => actual[key] === value); }
+function validateBrowserArtifacts(root, proof, binding) {
+    const snapshot = readProofArtifact(root, proof.worker_snapshot), native = readProofArtifact(root, proof.native_result);
+    if (!Array.isArray(native.errors) || native.errors.length < 1 || native.errors.length > 64 || native.errors.some(error => !boundedString(error, 4096) || !/^(?:Error: )?(?:[A-Za-z][\w.]*: )?Test timeout of [1-9]\d*ms exceeded\.(?:\nCall log:[\s\S]*)?$/.test(stripVTControlCharacters(String(error)))))
+        return false;
+    if (!matches(snapshot.binding, binding) || !matches(native.binding, binding) || !matches(snapshot.attempt, proof.attempt) || !matches(native.attempt, proof.attempt)
+        || !matches(snapshot.step, proof.step) || !matches(native.step, proof.step) || !matches(snapshot.world, proof.world) || proof.world.invocation_id !== binding.invocation_id
+        || native.status !== "timedOut" || native.phase !== "test" || native.file !== proof.file || snapshot.phase !== "body" || snapshot.observation_gap !== false || !matches(snapshot.browser, { connected: true, page_closed: false, crashed: false })
+        || !matches(snapshot.world_health, { api: true, web: true, db: true }))
+        return false;
+    const quiet = snapshot.quiet_ms, last = Date.parse(String(snapshot.last_progress_at)), deadline = Date.parse(String(snapshot.deadline_at)), observed = Date.parse(String(snapshot.observed_at)), health = Date.parse(String(snapshot.health_observed_at)), ended = Date.parse(String(native.ended_at));
+    return Number.isSafeInteger(quiet) && quiet > 0 && [last, deadline, observed, health, ended].every(Number.isFinite) && Math.abs(deadline - last - quiet) <= 2 && observed >= last && observed <= deadline && health <= observed && health >= last && deadline - health <= Math.min(1000, quiet / 4) && ended >= deadline && ended <= Date.now() && ended - deadline <= 5000;
+}
+export function runnerProofArtifacts(evidence) {
+    return [...new Set((evidence?.failures ?? []).flatMap(failure => { const proof = failure.repair_evidence; return [...(failure.diagnostic_artifact ? [failure.diagnostic_artifact.relative_path] : []), ...(proof?.rule === "candidate_browser_action_inactivity" ? [proof.worker_snapshot.relative_path, proof.native_result.relative_path] : [])]; }))];
+}
+export function runnerContractsValid(value) {
+    if (value === undefined)
+        return true;
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    return Object.entries(value).every(([alias, raw]) => {
+        if (!raw || typeof raw !== "object" || Array.isArray(raw))
+            return false;
+        const contract = raw;
+        return alias.startsWith("@check/") && contract.schema_id === "dd-flow/check-runner-evidence@1" && typeof contract.path === "string" && contract.path.length > 0 && contract.path.split("/")[0] !== "engine-outcome.json" && !contract.path.includes("\\") && !path.isAbsolute(contract.path) && !contract.path.split("/").some(part => part === ".." || part === "" || part === ".");
+    });
+}
+export function readRunnerEvidence(root, contract, binding) {
+    try {
+        let current = root;
+        if (!fs.lstatSync(current).isDirectory())
+            return null;
+        for (const part of contract.path.split(/[\\/]/)) {
+            current = path.join(current, part);
+            if (fs.lstatSync(current).isSymbolicLink())
+                return null;
+        }
+        const evidence = JSON.parse(readBoundedProofFile(current, 1024 * 1024).toString("utf8"));
+        if (evidence.schema_id !== contract.schema_id || !evidence.binding || Object.entries(binding).some(([key, value]) => evidence.binding[key] !== value)
+            || typeof evidence.runner?.name !== "string" || !evidence.runner.name || typeof evidence.runner.version !== "string" || !evidence.runner.version || typeof evidence.completed !== "boolean" || !evidence.counts
+            || ![evidence.counts.passed, evidence.counts.failed, evidence.counts.skipped].every(n => Number.isSafeInteger(n) && n >= 0)
+            || !Array.isArray(evidence.failures) || evidence.failures.length > 64 || evidence.failures.some(f => !runnerFailureValid(f))
+            || evidence.counts.failed > evidence.failures.length || evidence.observation_unknown !== undefined && typeof evidence.observation_unknown !== "boolean")
+            return null;
+        for (const failure of evidence.failures) {
+            if (failure.diagnostic_artifact && !matches(readProofArtifact(root, failure.diagnostic_artifact, 2 * 1024 * 1024).binding, binding))
+                return null;
+            const proof = failure.repair_evidence;
+            if (proof?.rule === "candidate_browser_action_inactivity") {
+                if (!validateBrowserArtifacts(root, proof, binding))
+                    return null;
+                validatedBrowserProofs.add(proof);
+            }
+        }
+        return evidence;
+    }
+    catch {
+        return null;
+    }
+}
+export function runnerEvidencePass(evidence) { return Boolean(evidence?.completed && !evidence.observation_unknown && evidence.counts.failed === 0 && evidence.failures.length === 0); }
+export function checkRepairDisposition(receipt) {
+    if (receipt.status === "running" || receipt.status === "aborted" || receipt.runner_evidence?.observation_unknown)
+        return "settlement_required";
+    if (receipt.status === "passed")
+        return "passed";
+    if (receipt.execution_failures?.length || receipt.mutation_paths?.length || receipt.before_fingerprint !== receipt.after_fingerprint || receipt.diagnostic_evidence_valid === false)
+        return "tooling_blocker";
+    if (!Number.isSafeInteger(receipt.exit_code) || receipt.exit_code === 0)
+        return "unclassified";
+    const evidence = receipt.runner_evidence;
+    if (!evidence || !Array.isArray(evidence.failures) || !evidence.failures.length || receipt.exit_code === 0 || evidence.failures.some(f => !f || !["assertion", "tooling", "unclassified"].includes(f.category)))
+        return "unclassified";
+    if (evidence.failures.some(f => f.category === "tooling"))
+        return "tooling_blocker";
+    if (!evidence.completed)
+        return "unclassified";
+    if (evidence.failures.some(f => !runnerFailureValid(f) || !candidateFailure(f, evidence, receipt.candidate_root, receipt.candidate_files)))
+        return "unclassified";
+    return "source_repair";
+}
+export function assertSourceRepairEligible(receipts) {
+    const blockers = receipts.filter(receipt => checkRepairDisposition(receipt) !== "source_repair");
+    if (!receipts.length || blockers.length)
+        throw new AppError("check_gate_blocked", "Checks require tooling diagnosis or settlement before product repair; retained nonzero is not a candidate-source verdict", 2, { failures: receipts, dispositions: receipts.map(receipt => ({ check_receipt_id: receipt.id, disposition: checkRepairDisposition(receipt) })), outcome: "blocked", recoverable: false, instruction: "Inspect retained runner evidence. Do not change product code to repair tooling, unknown observation or unclassified failure. Retry only after establishing and correcting the cause." });
+}

package/dist/services/cleanup.js

@@ -2,13 +2,13 @@ import fs from "node:fs";
 import { spawnSync } from "node:child_process";
 import path from "node:path";
 import { AppError } from "../shared/errors.js";
-import { parseJsonObject } from "../shared/json.js";
-import { ensureReadableFile } from "../storage/database.js";
-import { projectCheckoutRoot, resolveProjectRoot } from "../storage/paths.js";
+import { prepareJsonFile } from "../cli/input-preparation.js";
+import { projectCheckoutRoot, resolveProjectRoot, runtimeStateJsonPath } from "../storage/paths.js";
 import { appendAudit } from "./audit.js";
 import { requireProjectByRoot } from "./projects.js";
-import { protocolRunDiagnostics, readProtocolRuntimeState, requireProtocol } from "./protocols.js";
+import { persistProtocolState, prepareProtocolRuntimeRepair, protocolRunDiagnostics, readProtocolRuntimeState, requireProtocol } from "./protocols.js";
 import { publicSessionIdentity } from "./session-identity.js";
+import { publishRunProjections } from "./runs.js";
 const actionKinds = new Set([
     "repair_protocol_state",
     "cancel_queue_job",
@@ -25,7 +25,8 @@ export function cleanupScan(context, input) {
     const protocols = context.db.all("SELECT id, status, stage, state_path FROM protocols WHERE project_id = ? ORDER BY id ASC", [project.id]);
     for (const protocol of protocols) {
         const terminal = ["closed", "cancelled"].includes(protocol.status) || ["closed", "cancelled"].includes(protocol.stage);
-        if (!fs.existsSync(protocol.state_path)) {
+        const requiresMigration = protocol.state_path !== runtimeStateJsonPath(context.ddFlowHome, project.id, protocol.id);
+        if (!fs.existsSync(protocol.state_path) || requiresMigration) {
             pushFinding(findings, actions, "missing_protocol_runtime_state", "warning", {
                 protocol_id: protocol.id,
                 path: protocol.state_path,
@@ -43,6 +44,8 @@ export function cleanupScan(context, input) {
             }
         }
         const fullProtocol = requireProtocol(context, protocol.id, project.id);
+        if (requiresMigration)
+            continue;
         const state = readProtocolRuntimeState(context, fullProtocol).state;
         const diagnostics = protocolRunDiagnostics(context, fullProtocol, state).diagnostics;
         for (const diagnostic of diagnostics.filter((entry) => entry.code === "protocol_run_stage_mismatch")) {
@@ -170,36 +173,55 @@ export function cleanupScan(context, input) {
         plan: { project_root: project.root, project_id: project.id, actions }
     };
 }
-export function cleanupApply(context, input) {
-    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+export function prepareCleanupApply(context, input) {
     const reason = input.reason.trim();
     if (!reason) {
         throw new AppError("validation", "cleanup apply requires --reason", 2);
     }
-    ensureReadableFile(input.planFile);
-    const plan = validateCleanupPlan(parseJsonObject(fs.readFileSync(input.planFile, "utf8"), input.planFile), project);
+    const value = prepareJsonFile(input.planFile, "cleanup plan").value;
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new AppError("validation", "cleanup plan must be an object", 2);
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const plan = validateCleanupPlan(value, project);
     validateNoDestructiveSurprises(context, plan, input.force);
+    return { project, reason, plan };
+}
+export function cleanupApply(context, input) {
+    const { project, reason, plan } = input.prepared ?? prepareCleanupApply(context, input);
+    // A supplied plan can outlive its initial inspection. Refresh external
+    // workspace evidence before reserving the writer, then recheck SQL below.
+    if (input.prepared)
+        validateNoDestructiveSurprises(context, plan, input.force);
+    const prepared = prepareCleanupEffects(context, plan);
     const now = context.now();
     const results = [];
-    context.db.exec("BEGIN IMMEDIATE");
+    let executing = false, committed = false;
     try {
-        for (const action of plan.actions) {
-            results.push(applyAction(context, action, reason, input.force, now));
-        }
-        const changed = results.filter((result) => result.changed).length;
-        if (changed > 0) {
-            appendAudit(context, {
-                projectId: project.id,
-                eventType: "cleanup.applied",
-                reason,
-                forced: input.force,
-                payload: { project_id: project.id, action_count: plan.actions.length, changed, results }
-            });
-        }
-        context.db.exec("COMMIT");
+        context.db.writeTransaction(() => {
+            context.db.afterCommit(() => { committed = true; });
+            validateNoDestructiveSurprises(context, plan, input.force, false);
+            prepared.assertUnchanged();
+            for (const action of plan.actions) {
+                executing = true;
+                results.push(applyAction(context, action, reason, input.force, now, prepared));
+            }
+            const changed = results.filter((result) => result.changed).length;
+            if (changed > 0) {
+                appendAudit(context, {
+                    projectId: project.id,
+                    eventType: "cleanup.applied",
+                    reason,
+                    forced: input.force,
+                    payload: { project_id: project.id, action_count: plan.actions.length, changed, results }
+                });
+            }
+        });
     }
     catch (error) {
-        context.db.exec("ROLLBACK");
+        if (committed || error instanceof AppError && error.details.effect === "committed")
+            throw new AppError(error instanceof AppError ? error.code : "cleanup_publication_failed", error instanceof Error ? error.message : "Committed cleanup publication failed", error instanceof AppError ? error.exitCode : 1, { ...(error instanceof AppError ? error.details : {}), effect: "committed", publication_pending: true, attempted_results: results, cause: String(error) });
+        if (executing)
+            throw new AppError("cleanup_apply_failed", "Cleanup failed after execution began; inspect retained artifacts before retrying", 1, { effect: "unknown", database_rolled_back: true, attempted_results: results, cause: error instanceof Error ? error.message : String(error), ...(error instanceof AppError ? { cause_code: error.code } : {}) });
         throw error;
     }
     return {
@@ -248,18 +270,36 @@ function validateCleanupPlan(value, project) {
                 throw new AppError("validation", "close_flow_session requires a native session identity", 2);
             }
         }
+        const requiredField = action.kind === "discard_stale_run" ? "run_id"
+            : ["repair_protocol_state", "cancel_queue_job", "close_worktree_record"].includes(String(action.kind)) ? "protocol_id" : undefined;
+        if (requiredField && (typeof action[requiredField] !== "string" || !action[requiredField].trim()))
+            throw new AppError("validation", `cleanup ${String(action.kind)} requires ${requiredField}`, 2);
+        const numericField = action.kind === "expire_lane_lock" ? "lock_id" : action.kind === "expire_lane_waiter" ? "waiter_id" : undefined;
+        if (numericField && (!Number.isSafeInteger(action[numericField]) || action[numericField] < 1))
+            throw new AppError("validation", `cleanup ${String(action.kind)} requires a positive integer ${numericField}`, 2);
+        if (action.worktree_path !== undefined && (typeof action.worktree_path !== "string" || !path.isAbsolute(action.worktree_path)))
+            throw new AppError("validation", "cleanup worktree_path must be an absolute path", 2);
         return action;
     });
     return { project_root: project.root, project_id: project.id, actions };
 }
-function validateNoDestructiveSurprises(context, plan, force) {
-    const destructive = plan.actions.find((action) => action.kind === "close_worktree_record" && action.worktree_path && dirtyGit(action.worktree_path));
+function validateNoDestructiveSurprises(context, plan, force, inspectFiles = true) {
+    for (const action of plan.actions) {
+        if (action.kind === "repair_protocol_state")
+            requireProtocol(context, action.protocol_id, action.project_id);
+        if (action.kind === "discard_stale_run") {
+            const run = context.db.get("SELECT index_json, status FROM runs WHERE project_id = ? AND id = ?", [action.project_id, action.run_id]);
+            if (run && ["running", "discarded"].includes(run.status))
+                cleanupRunIndex(run.index_json);
+        }
+    }
+    const destructive = inspectFiles && plan.actions.find((action) => action.kind === "close_worktree_record" && action.worktree_path && dirtyGit(action.worktree_path));
     if (destructive && !force) {
         throw new AppError("worktree_dirty", "cleanup apply refuses dirty worktree actions without --force --reason", 1, {
             path: destructive.worktree_path
         });
     }
-    const unsafeWorktree = plan.actions.find((action) => action.kind === "close_worktree_record" && action.worktree_path && !safeCleanupWorktreePath(context, action.project_id, action.worktree_path));
+    const unsafeWorktree = inspectFiles && plan.actions.find((action) => action.kind === "close_worktree_record" && action.worktree_path && !safeCleanupWorktreePath(context, action.project_id, action.worktree_path));
     if (unsafeWorktree) {
         throw new AppError("worktree_cleanup_unsafe", "cleanup apply refuses unsafe worktree path", 1, {
             path: unsafeWorktree.worktree_path
@@ -278,12 +318,53 @@ function validateNoDestructiveSurprises(context, plan, force) {
         });
     }
 }
-function applyAction(context, action, reason, force, now) {
+function prepareCleanupEffects(context, plan) {
+    const checks = [], files = new Map();
+    const repairs = new Map();
+    const read = (sql, params) => {
+        const value = context.db.get(sql, params), encoded = JSON.stringify(value);
+        checks.push(() => { if (JSON.stringify(context.db.get(sql, params)) !== encoded)
+            throw new AppError("cleanup_plan_changed", "Cleanup target changed during preparation", 1, { effect: "no_effect" }); });
+        return value;
+    };
+    const remember = (file) => { if (file !== undefined)
+        files.set(file, fs.existsSync(file)); };
+    for (const action of plan.actions) {
+        if (action.kind === "repair_protocol_state") {
+            read("SELECT * FROM protocols WHERE project_id = ? AND id = ?", [action.project_id, action.protocol_id]);
+            const protocol = requireProtocol(context, action.protocol_id, action.project_id);
+            remember(protocol.state_path);
+            repairs.set(action, prepareProtocolRuntimeRepair(context, protocol));
+        }
+        if (action.kind === "discard_stale_run") {
+            const run = read("SELECT * FROM runs WHERE project_id = ? AND id = ?", [action.project_id, action.run_id]);
+            if (run) {
+                remember(run.runtime_path);
+                remember(run.run_dir);
+                remember(run.workspace_root);
+            }
+        }
+        if (action.kind === "close_worktree_record") {
+            const record = read("SELECT * FROM worktree_records WHERE project_id = ? AND protocol_id = ?", [action.project_id, action.protocol_id]);
+            remember(action.worktree_path ?? record?.worktree_path);
+        }
+    }
+    return { repairs, assertUnchanged: () => { for (const check of checks)
+            check(); }, exists: (file) => {
+            if (!files.has(file))
+                throw new AppError("cleanup_plan_changed", "Cleanup target has no prepared filesystem observation", 1, { path: file, effect: "no_effect" });
+            return files.get(file);
+        } };
+}
+function applyAction(context, action, reason, force, now, prepared) {
     if (action.kind === "repair_protocol_state" && action.protocol_id) {
         const protocol = requireProtocol(context, action.protocol_id, action.project_id);
         const beforePath = protocol.state_path;
-        const existed = fs.existsSync(beforePath);
-        readProtocolRuntimeState(context, protocol);
+        const existed = prepared.exists(beforePath), repair = prepared.repairs.get(action);
+        context.db.run("UPDATE protocols SET state_path = ?, plan_path = ? WHERE project_id = ? AND id = ?", [repair.statePath, repair.planPath, action.project_id, action.protocol_id]);
+        persistProtocolState(context, { ...protocol, state_path: repair.statePath, plan_path: repair.planPath }, repair.state);
+        protocol.state_path = repair.statePath;
+        appendAudit(context, { protocolId: protocol.id, projectId: protocol.project_id, eventType: "protocol.runtime_state_repaired", payload: { protocol_id: protocol.id, path: repair.statePath, repaired_from: repair.previousStatePath, source: "sqlite" } });
         return {
             kind: action.kind,
             changed: !existed || beforePath !== protocol.state_path,
@@ -338,21 +419,19 @@ function applyAction(context, action, reason, force, now) {
         if (run.status === "discarded") {
             const index = discardedRunIndex(run.index_json, reason, now);
             context.db.run("UPDATE runs SET verdict = 'discarded', next_action = ?, index_json = ?, updated_at = ?, completed_at = COALESCE(completed_at, ?) WHERE project_id = ? AND id = ?", [reason, JSON.stringify(index), now, now, action.project_id, action.run_id]);
-            if (fs.existsSync(run.runtime_path))
-                fs.writeFileSync(run.runtime_path, `${JSON.stringify(index, null, 2)}\n`);
+            context.db.afterCommit(() => publishRunProjections(context, action.project_id, action.run_id));
             return { kind: action.kind, changed: true, run_id: action.run_id };
         }
         if (run.status !== "running") {
             return { kind: action.kind, changed: false, skipped: true, reason: `already_${run.status}`, run_id: action.run_id };
         }
-        if (fs.existsSync(run.runtime_path) || fs.existsSync(run.run_dir) || fs.existsSync(run.workspace_root)) {
+        if (prepared.exists(run.runtime_path) || prepared.exists(run.run_dir) || prepared.exists(run.workspace_root)) {
             return { kind: action.kind, changed: false, skipped: true, reason: "runtime_or_workspace_reappeared", run_id: action.run_id };
         }
         const index = discardedRunIndex(run.index_json, reason, now);
         context.db.run(`UPDATE runs SET status = 'discarded', verdict = 'discarded', next_action = ?, index_json = ?, updated_at = ?, completed_at = ?
        WHERE project_id = ? AND id = ? AND status = 'running'`, [reason, JSON.stringify(index), now, now, action.project_id, action.run_id]);
-        fs.mkdirSync(run.run_dir, { recursive: true });
-        fs.writeFileSync(run.runtime_path, `${JSON.stringify(index, null, 2)}\n`);
+        context.db.afterCommit(() => publishRunProjections(context, action.project_id, action.run_id));
         context.db.run(`UPDATE sessions SET status = 'stopped', stop_reason = ?, updated_at = ?, stopped_at = ?
        WHERE project_id = ? AND run_id = ? AND status IN ('pending', 'active', 'waiting_user', 'blocked', 'stopping')`, [reason, now, now, action.project_id, action.run_id]);
         context.db.run("UPDATE flow_session_segments SET ended_at = ? WHERE project_id = ? AND run_id = ? AND ended_at IS NULL", [now, action.project_id, action.run_id]);
@@ -394,7 +473,7 @@ function applyAction(context, action, reason, force, now) {
     }
     if (action.kind === "close_worktree_record" && action.protocol_id) {
         const worktreePath = action.worktree_path ?? context.db.get("SELECT worktree_path FROM worktree_records WHERE project_id = ? AND protocol_id = ?", [action.project_id, action.protocol_id])?.worktree_path;
-        const status = worktreePath && fs.existsSync(worktreePath) ? "kept" : "removed";
+        const status = worktreePath && prepared.exists(worktreePath) ? "kept" : "removed";
         const result = context.db.run(`UPDATE worktree_records SET status = ?, updated_at = ?, closed_at = ?
        WHERE project_id = ? AND protocol_id = ? AND status = 'active'`, [status, now, now, action.project_id, action.protocol_id]);
         return {
@@ -407,22 +486,36 @@ function applyAction(context, action, reason, force, now) {
     return { kind: action.kind, changed: false, skipped: true, reason: "invalid_action" };
 }
 function discardedRunIndex(indexJson, reason, now) {
-    const index = JSON.parse(indexJson);
+    const index = cleanupRunIndex(indexJson);
     index.schema_id = "dd-flow/flow-run@3";
     index.status = "discarded";
     index.verdict = "discarded";
     index.next_action = reason;
     index.updated_at = now;
+    index.runtime_revision = (typeof index.runtime_revision === "number" ? index.runtime_revision : 0) + 1;
     index.completed_at ??= now;
     index.finished_at ??= now;
     return index;
 }
+function cleanupRunIndex(indexJson) {
+    try {
+        const index = JSON.parse(indexJson);
+        if (!index || typeof index !== "object" || Array.isArray(index))
+            throw new Error("RUN index must be an object");
+        return index;
+    }
+    catch (error) {
+        throw new AppError("runtime_state_invalid", "Cleanup cannot read retained RUN state", 1, { cause: String(error) });
+    }
+}
 function dirtyGit(worktreePath) {
     if (!fs.existsSync(worktreePath)) {
         return false;
     }
-    const result = spawnSync("git", ["-C", worktreePath, "status", "--porcelain"], { encoding: "utf8" });
-    return result.status === 0 && result.stdout.trim().length > 0;
+    const result = spawnSync("git", ["-C", worktreePath, "status", "--porcelain"], { encoding: "utf8", timeout: 5000 });
+    if (result.error || result.status !== 0)
+        throw new AppError("workspace_status_failed", "Cannot establish worktree status before cleanup", 1, { path: worktreePath, cause: result.error?.message ?? result.stderr });
+    return result.stdout.trim().length > 0;
 }
 function safeCleanupWorktreePath(context, projectId, worktreePath) {
     if (!fs.existsSync(worktreePath)) {