@deksden-com/dd-flow-cli 0.9.0-beta.140 → 0.9.0-beta.142

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

@@ -1,13 +1,27 @@
 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;
@@ -20,6 +34,10 @@ export function runnerFailureValid(value) {
         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;
 }
@@ -44,12 +62,14 @@ function candidateFailure(failure, evidence, root, capturedFiles) {
     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)) + 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. */
@@ -72,35 +92,90 @@ export function runnerContractForArgv(profile, command, args) {
         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. Logs, repeated cursors and foreign records
- * are diagnostic bytes, not runner progress. Partial final lines await append. */
+/** 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 stat = fs.lstatSync(file);
-        if (!stat.isFile() || stat.size > 1024 * 1024)
-            return [];
+        const text = readBoundedProofFile(file, 4 * 1024 * 1024).toString("utf8");
         const accepted = [];
-        for (const line of fs.readFileSync(file, "utf8").split("\n").slice(0, -1)) {
-            let value;
-            try {
-                value = JSON.parse(line);
-            }
-            catch {
+        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 <= lastSequence || typeof value.at !== "string" || !Number.isFinite(Date.parse(value.at)) || Date.parse(value.at) > now
+                || !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 {
-        return [];
+    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)
@@ -124,16 +199,23 @@ export function readRunnerEvidence(root, contract, binding) {
             if (fs.lstatSync(current).isSymbolicLink())
                 return null;
         }
-        const stat = fs.statSync(current);
-        if (!stat.isFile() || stat.size > 1024 * 1024)
-            return null;
-        const evidence = JSON.parse(fs.readFileSync(current, "utf8"));
+        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 {

package/dist/services/code-checks.js

@@ -1,5 +1,5 @@
 import crypto from "node:crypto";
-import { candidateFailureFiles, checkRepairDisposition, readRunnerEvidence, readRunnerProgress, runnerContractsValid, runnerEvidencePass, runnerObservationDurations } from "./check-runner-evidence.js";
+import { candidateFailureFiles, checkRepairDisposition, readRunnerEvidence, readRunnerProgress, runnerContractsValid, runnerEvidencePass, runnerObservationDurations, runnerProofArtifacts } from "./check-runner-evidence.js";
 export { assertSourceRepairEligible, checkRepairDisposition } from "./check-runner-evidence.js";
 import { isGitlessWorkspace, ownedWorkspaceHookPath, projectServicePathFilter, workspaceGitFiles } from "./workspace-files.js";
 import { spawn, spawnSync } from "node:child_process";
@@ -622,10 +622,12 @@ async function runCodeChecksOwned(context, input, workspaceGateId, generation) {
         }
         const runnerEvidence = group.runnerEvidence ? readRunnerEvidence(evidenceDir, group.runnerEvidence, { invocation_id: id, check_id: id, command: group.command, input_hash: inputHash, verification_epoch: epoch }) : undefined;
         const physicalFailures = executionFailures({ exitCode: result.exitCode, launcherError: result.error ?? undefined, cleanupUnconfirmed: result.cleanupUnconfirmed, missing: artifacts.missing, mutations: mutationPaths, invalidRunner: Boolean(group.runnerEvidence && !runnerEvidence) });
+        if (result.failure)
+            physicalFailures.push(result.failure);
         const candidateFiles = candidateFailureFiles(runnerEvidence, input.workspaceRoot);
         if (group.runnerEvidence)
             retainExecutionOutcome(evidenceDir, { id, command: group.command, input_hash: inputHash, verification_epoch: epoch }, input.workspaceRoot, physicalFailures, candidateFiles);
-        const requiredArtifacts = [...new Set([...group.requiredArtifacts, ...(group.runnerEvidence ? ["engine-outcome.json"] : [])])];
+        const requiredArtifacts = [...new Set([...group.requiredArtifacts, ...runnerProofArtifacts(runnerEvidence), ...(group.runnerEvidence ? ["engine-outcome.json"] : [])])];
         artifacts = collectCheckArtifacts(evidenceDir, requiredArtifacts);
         const status = result.aborted ? "aborted" : result.exitCode === 0 && !result.error && artifacts.complete && mutationPaths.length === 0 && (!group.runnerEvidence || runnerEvidencePass(runnerEvidence)) ? "passed" : "failed";
         const receipt = receiptFor({ ...reserved, resources, result, status, after, mutationPaths, artifacts: artifacts.items });
@@ -714,7 +716,7 @@ export function reconcileUnfinishedChecks(context, input) {
                 }
             }
             retainExecutionOutcome(evidenceDir, receipt, input.workspaceRoot, physicalFailures, candidateFiles);
-            receipt.required_artifacts = [...new Set([...(receipt.required_artifacts ?? []), "engine-outcome.json"])];
+            receipt.required_artifacts = [...new Set([...(receipt.required_artifacts ?? []), ...runnerProofArtifacts(runnerEvidence), "engine-outcome.json"])];
             artifacts = collectCheckArtifacts(evidenceDir, receipt.required_artifacts);
         }
         const status = completion === null ? "aborted" : completion.exit_code === 0 && workspaceUnchanged && artifacts.complete && physicalFailures.length === 0 && (!receipt?.runner_evidence_required || runnerEvidencePass(runnerEvidence)) ? "passed" : "failed";
@@ -796,7 +798,7 @@ function reserveOrReuseReceipt(context, input) {
 }
 function sourceRepairContractMatches(receipt, group, profileHash) {
     return checkRepairDisposition(receipt) === "source_repair" && group.command === receipt.command && profileHash === receipt.profile_hash && isDeepStrictEqual(group.inputs, receipt.inputs)
-        && isDeepStrictEqual([...group.requiredArtifacts].sort(), receipt.required_artifacts.filter(file => file !== "engine-outcome.json").sort()) && isDeepStrictEqual([...group.ports].sort(), Object.keys(receipt.resources.ports).sort());
+        && isDeepStrictEqual(derivedReceiptArtifacts(group, receipt).sort(), [...receipt.required_artifacts].sort()) && isDeepStrictEqual([...group.ports].sort(), Object.keys(receipt.resources.ports).sort());
 }
 function receiptFor(input) { return { id: input.id, local_id: input.localId, declaration_id: input.group.declarations[0].id, check_refs: input.group.declarations.map(checkRef), gate: input.group.gate, scope: input.scope, work_id: input.workId ?? null, command: input.group.command, input_hash: input.inputHash, verification_epoch: input.epoch, retry_of_receipt_id: input.retryOf ?? null, retry_reason: input.retryReason ?? null, status: input.status, ...(input.status === "aborted" ? { abort_reason: input.result.error } : {}), exit_code: input.status === "running" ? null : input.result.exitCode, stdout_path: input.stdoutPath, stderr_path: input.stderrPath, receipt_path: input.receiptPath, completion_path: input.completionPath, required_artifacts: input.group.requiredArtifacts, inputs: input.group.inputs, workspace_fingerprint: input.before.fingerprint, before_fingerprint: input.before.fingerprint, after_fingerprint: input.after.fingerprint, profile_hash: input.profileHash, mutation_paths: input.mutationPaths, artifacts: input.artifacts, resources: { ports: input.resources }, started_at: input.startedAt, finished_at: input.status === "running" ? input.startedAt : new Date().toISOString() }; }
 function writeReceipt(file, receipt) { const temporary = `${file}.tmp-${process.pid}-${crypto.randomUUID()}`; fs.writeFileSync(temporary, `${JSON.stringify(receipt, null, 2)}\n`); fs.renameSync(temporary, file); }
@@ -1136,7 +1138,8 @@ function explicitInputFiles(root, inputs, ignoredRoots) {
     return [...result.entries()];
 }
 function checkInputHash(workspaceRoot, group, profileHash, inputFingerprint, evidenceContext, checkEnvironment) { return crypto.createHash("sha256").update(JSON.stringify({ workspace_root: path.resolve(workspaceRoot), gate: group.reusable ? null : group.gate, command: group.command, required_artifacts: group.requiredArtifacts, ports: group.ports, inputs: group.inputs, ...(group.runnerEvidence ? { runner_evidence: group.runnerEvidence } : {}), profile_hash: profileHash, environment: environmentFingerprint(workspaceRoot, group.environmentInputs, checkEnvironment), input_fingerprint: inputFingerprint, ...(group.environmentInputs === undefined ? {} : { environment_inputs: group.environmentInputs }), ...(evidenceContext === undefined ? {} : { evidence_context: evidenceContext }) })).digest("hex"); }
-function bindReceipt(receipt, group) { return { ...receipt, gate: group.gate, declaration_id: group.declarations[0].id, check_refs: group.declarations.map(checkRef), required_artifacts: [...new Set([...group.requiredArtifacts, ...(receipt.required_artifacts.includes("engine-outcome.json") ? ["engine-outcome.json"] : [])])], inputs: group.inputs }; }
+function derivedReceiptArtifacts(group, receipt) { return [...new Set([...group.requiredArtifacts, ...runnerProofArtifacts(receipt.runner_evidence), ...(receipt.required_artifacts.includes("engine-outcome.json") ? ["engine-outcome.json"] : [])])]; }
+function bindReceipt(receipt, group) { return { ...receipt, gate: group.gate, declaration_id: group.declarations[0].id, check_refs: group.declarations.map(checkRef), required_artifacts: derivedReceiptArtifacts(group, receipt), inputs: group.inputs }; }
 export function checkReceiptEvidenceValid(receipt) { return checkReceiptEvidenceValidForMode(receipt); }
 function checkReceiptEvidenceValidForMode(receipt, mode) {
     try {
@@ -1239,8 +1242,10 @@ export function runCheck(command, cwd, environment, stdout, stderr, heartbeat, o
         const started = Date.now();
         const child = spawn("/bin/sh", ["-c", checkShellScript()], { cwd, env: { ...environment, DD_FLOW_CHECK_COMMAND: command }, stdio: ["pipe", "pipe", "pipe"], detached: process.platform !== "win32" });
         let error = null;
+        let failure;
         let stopping = false;
         let closed = false;
+        let admitted = false;
         let progress;
         let cleanup;
         let cleanupUnconfirmed = false;
@@ -1259,6 +1264,8 @@ export function runCheck(command, cwd, environment, stdout, stderr, heartbeat, o
                 return;
             stopping = true;
             error = cause instanceof Error ? cause.message : String(cause);
+            if (cause instanceof AppError)
+                failure = { code: cause.code, message: cause.message };
             if (progress) {
                 clearInterval(progress);
                 progress = undefined;
@@ -1270,22 +1277,28 @@ export function runCheck(command, cwd, environment, stdout, stderr, heartbeat, o
             cleanup = stopProcessGroup(child, 5_000).catch(cause => {
                 cleanupUnconfirmed = true;
                 error = `${error}; cleanup: ${JSON.stringify(errorRecord(cause))}`;
-                resolve({ exitCode: null, error, aborted: true, cleanupUnconfirmed });
+                resolve({ exitCode: null, error, aborted: true, cleanupUnconfirmed, ...(failure ? { failure } : {}) });
             });
         };
         const observationTimer = setInterval(() => {
-            if (stopping || closed || observation.phase?.() === "serving")
+            if (stopping || closed || !admitted || observation.phase?.() === "serving")
                 return;
             if (runnerClock && runnerProgress) {
-                for (const event of readRunnerProgress(runnerProgress, environment.DD_FLOW_CHECK_INVOCATION_ID ?? "", runnerSequence)) {
-                    runnerSequence = event.sequence;
-                    runnerPhase = event.phase;
-                    runnerClock.sample(runnerSequence, Date.parse(event.at));
+                try {
+                    for (const event of readRunnerProgress(runnerProgress, environment.DD_FLOW_CHECK_INVOCATION_ID ?? "", runnerSequence)) {
+                        runnerSequence = event.sequence;
+                        if (runnerPhase !== "execution")
+                            runnerPhase = event.phase;
+                        runnerClock.sample(runnerSequence, Date.parse(event.at));
+                    }
+                    // The outer guard includes the runner's bounded cleanup tail.
+                    runnerClock.timeoutMs = runnerPhase === "execution" ? runnerExecutionMs : runnerStartupMs;
+                    if (runnerClock.sample(runnerSequence))
+                        stop(new AppError("operation_observation_lost", "Structured test runner stopped making progress", 1, { phase: runnerPhase, sequence: runnerSequence }));
+                }
+                catch (cause) {
+                    stop(cause);
                 }
-                // The outer guard includes the runner's bounded cleanup tail.
-                runnerClock.timeoutMs = runnerPhase === "execution" ? runnerExecutionMs : runnerStartupMs;
-                if (runnerClock.sample(runnerSequence))
-                    stop(new AppError("operation_observation_lost", "Structured test runner stopped making progress", 1, { phase: runnerPhase, sequence: runnerSequence }));
                 return;
             }
             if (clock.sample(outputCursor))
@@ -1313,28 +1326,12 @@ export function runCheck(command, cwd, environment, stdout, stderr, heartbeat, o
                 clearInterval(observationTimer);
             await cleanup;
             await Promise.all(flushed);
-            resolve({ exitCode, error: error ?? (signal ? `terminated by ${signal}` : null), aborted: stopping || Boolean(signal) || Boolean(error), ...(cleanupUnconfirmed ? { cleanupUnconfirmed } : {}) });
+            resolve({ exitCode, error: error ?? (signal ? `terminated by ${signal}` : null), aborted: stopping || Boolean(signal) || Boolean(error), ...(cleanupUnconfirmed ? { cleanupUnconfirmed } : {}), ...(failure ? { failure } : {}) });
         });
         if (!child.pid) {
             error = "check process did not provide a PID";
             return;
         }
-        try {
-            onSpawn(child.pid);
-        }
-        catch (cause) {
-            stop(cause);
-            return;
-        }
-        if (observation.leaseExpiresAt) {
-            const expiry = observation.leaseExpiresAt();
-            if (!expiry || !renewalConfirmed(renewal, performance.now(), expiry)) {
-                stop("check confirmation has no current authority");
-                return;
-            }
-        }
-        child.stdin.end("admitted\n");
-        clock.sample(outputCursor);
         const renew = () => {
             if (stopping || closed)
                 return;
@@ -1382,7 +1379,46 @@ export function runCheck(command, cwd, environment, stdout, stderr, heartbeat, o
                 stop(cause);
             }
         };
-        progress = setInterval(renew, 15_000);
+        // The shell is held on stdin: a no-effect identity read may be retried,
+        // but never the command or an admission callback with unknown effects.
+        const confirmation = createRenewalState();
+        confirmation.uncertainSince = performance.now();
+        let confirmationError;
+        const admit = () => {
+            renewalTimer = undefined;
+            if (stopping || closed)
+                return;
+            if (confirmationError && !renewalRemaining(confirmation)) {
+                stop(confirmationError);
+                return;
+            }
+            try {
+                onSpawn(child.pid);
+            }
+            catch (cause) {
+                if (cause instanceof AppError && cause.code === "process_ownership_unknown"
+                    && cause.details.reason === "physical_identity_unavailable" && maintenanceRetryable(cause)
+                    && renewalFailure(confirmation)) {
+                    confirmationError = cause;
+                    renewalTimer = setTimeout(admit, Math.min(renewalDelay(confirmation), renewalRemaining(confirmation)));
+                    return;
+                }
+                stop(cause);
+                return;
+            }
+            if (observation.leaseExpiresAt) {
+                const expiry = observation.leaseExpiresAt();
+                if (!expiry || !renewalConfirmed(renewal, performance.now(), expiry)) {
+                    stop("check confirmation has no current authority");
+                    return;
+                }
+            }
+            admitted = true;
+            child.stdin.end("admitted\n");
+            clock.sample(++outputCursor);
+            progress = setInterval(renew, 15_000);
+        };
+        admit();
     });
 }
 function checkShellScript() {

package/dist/services/runtime-budget.js

@@ -199,6 +199,22 @@ export function admitRuntimeCheck(context, id, leaseToken) {
     }
 }
 /** Scope selection uses retained registration, never a current profile or PID search. */
+export function prepareRuntimeScopeStatus(scopeId, scopeIdsJson) {
+    if (Boolean(scopeId) === Boolean(scopeIdsJson))
+        throw new AppError("usage", "Use exactly one of --scope-id or --scope-ids-json", 2);
+    let ids;
+    try {
+        ids = scopeId ? [scopeId] : JSON.parse(scopeIdsJson);
+    }
+    catch {
+        throw new AppError("usage", "Scope inventory requires JSON IDs", 2);
+    }
+    if (!Array.isArray(ids) || !ids.length || ids.length > 16 || ids.some(id => typeof id !== "string") || new Set(ids).size !== ids.length)
+        throw new AppError("usage", "Scope inventory requires 1..16 unique scope IDs", 2);
+    for (const id of ids)
+        parseRuntimeBudget(JSON.stringify({ schema_id: "dd-flow/runtime-budget@1", scope_id: id, per_harness: {} }));
+    return ids;
+}
 export function runtimeBudgetStatus(context, scopeId) {
     parseRuntimeBudget(JSON.stringify({ schema_id: "dd-flow/runtime-budget@1", scope_id: scopeId, per_harness: {} }));
     return withResourceReadSnapshot(resourceHome(context), db => {

package/dist/services/stage-lifecycle.js

@@ -13,7 +13,7 @@ import { reconcileSessionCoverage, registerFlowSession } from "./sessions.js";
 import { usageForRun } from "./usage.js";
 import { boundCanonicalPlan, prepareCanonicalPlan } from "./plan-runtime.js";
 import { prepareJsonFile, prepareJsonSchema, prepareOutputDirectory, prepareOutputFile, prepareTextFile } from "../cli/input-preparation.js";
-import { AppError } from "../shared/errors.js";
+import { AppError, errorRecord, processEvidence, diagnosticJson } from "../shared/errors.js";
 import { planJsonPath, projectHome, resolveProjectRoot } from "../storage/paths.js";
 import { resolveCanonRoot } from "./canon.js";
 import { preflightMemoryPermissions } from "./memory-permissions.js";
@@ -295,7 +295,7 @@ export async function finishStage(context, input, prepared = prepareStageFinish(
         if (coverage.jobs.missing?.length) {
             throw new AppError("worker_jobs_incomplete", "Stage finish requires all declared worker jobs", 1, { coverage });
         }
-        const lint = await runTargetedMemoryBankLint(projectRoot);
+        const lint = await runTargetedMemoryBankLint(projectRoot, undefined, path.join(stageRoot, "diagnostics"));
         if (planFinish)
             boundCanonicalPlan(context, { projectId: view.run.project_id, protocolId: view.run.subject.id, planPath: planFinish.plan_path }, planFinish.canonical);
         const report = buildStageReport(context, view, input.stage, status, semantic, stageRoot, lint, planFinish);
@@ -836,7 +836,7 @@ function workerCoverage(context, projectId, runId) {
         jobs: { expected: jobs.map((job) => job.job_id), missing: missingJobs }
     };
 }
-export async function runTargetedMemoryBankLint(projectRoot, selectedFiles) {
+export async function runTargetedMemoryBankLint(projectRoot, selectedFiles, diagnosticRoot) {
     const files = [...new Set((selectedFiles ?? gitChangedFiles(projectRoot)).filter((file) => file.startsWith(".memory-bank/") && file.toLowerCase().endsWith(".md") && !file.split(/[\\/]/u).some((part) => part === ".." || part.startsWith(".env"))))];
     for (const file of files)
         ensureWithin(projectRoot, path.resolve(projectRoot, file), "lint target");
@@ -844,27 +844,71 @@ export async function runTargetedMemoryBankLint(projectRoot, selectedFiles) {
         return { ok: true, status: "not_applicable_no_changed_docs", files, finding_count: 0 };
     }
     const binary = process.env.MB_LINT_BIN ?? "mb-lint";
+    const fail = (code, message, details) => {
+        const error = new AppError(code, message, 1, { binary, files, ...details });
+        if (diagnosticRoot) {
+            try {
+                fs.mkdirSync(diagnosticRoot, { recursive: true });
+                const file = path.join(diagnosticRoot, `lint-${crypto.randomUUID()}.json`);
+                if (details.report) {
+                    const reportFile = file.replace(/\.json$/, ".report.json"), report = diagnosticJson(details.report);
+                    const reportBytes = Buffer.from(report);
+                    fs.writeFileSync(reportFile, reportBytes.length <= 1024 * 1024 ? report : JSON.stringify({ truncated: true, bytes: reportBytes.length, excerpt: reportBytes.subarray(0, 128 * 1024).toString("utf8") }), { flag: "wx", mode: 0o600 });
+                    error.details.report_path = reportFile;
+                }
+                delete error.details.report;
+                fs.writeFileSync(file, diagnosticJson(errorRecord(error)), { flag: "wx", mode: 0o600 });
+                error.details.diagnostic_path = file;
+            }
+            catch (capture) {
+                delete error.details.report;
+                error.details.capture_error = errorRecord(capture);
+            }
+        }
+        delete error.details.report;
+        throw error;
+    };
     let result;
     try {
         result = await commandResult(binary, ["--root", projectRoot, "--files", ...files, "--format", "json"], { cwd: projectRoot, startupMs: SETUP_STARTUP_MS });
     }
     catch (cause) {
-        const error = cause;
-        throw new AppError("lint_gate_unavailable", "Selected-file mb-lint is unavailable", 1, { binary, files, cause: error.code, ...error.details });
+        const recorded = errorRecord(cause), unavailable = ["ENOENT", "EACCES", "ENOEXEC"].includes(recorded.code);
+        fail(unavailable ? "lint_gate_unavailable" : "lint_gate_tool_failed", "Selected-file mb-lint could not execute", { cause: recorded });
     }
-    let parsed = {};
+    const evidence = processEvidence(result);
+    if (result.signal || result.exit_code !== 0 && result.exit_code !== 1)
+        fail("lint_gate_tool_failed", "Selected-file mb-lint did not complete normally", { process: evidence });
+    let parsed;
     try {
-        parsed = result.stdout ? JSON.parse(result.stdout) : {};
+        parsed = JSON.parse(result.stdout);
     }
     catch {
-        throw new AppError("lint_gate_invalid_output", "Selected-file mb-lint did not return JSON", 1, { binary, files });
+        fail(result.exit_code === 0 ? "lint_gate_invalid_output" : "lint_gate_tool_failed", "Selected-file mb-lint did not return a report", { process: evidence });
     }
-    if (result.exit_code !== 0) {
-        throw new AppError("lint_gate_failed", "Selected-file mb-lint reported blocking findings", 1, { binary, files, result: parsed });
+    const report = parsed;
+    const severities = { error: "errors", warning: "warnings", info: "info", suggestion: "suggestions" };
+    const matchingRoot = () => { try {
+        return typeof report?.root === "string" && fs.realpathSync(path.resolve(projectRoot, report.root)) === fs.realpathSync(projectRoot);
     }
-    const findingCount = parsed && typeof parsed === "object" && Array.isArray(parsed.findings)
-        ? parsed.findings.length
-        : 0;
+    catch {
+        return false;
+    } };
+    const valid = report && report.tool === "mb-lint" && typeof report.version === "string" && report.version.trim()
+        && matchingRoot()
+        && report.memoryBank === ".memory-bank" && report.summary && Array.isArray(report.findings)
+        && report.findings.every(finding => finding && typeof finding === "object" && typeof finding.severity === "string" && Object.hasOwn(severities, finding.severity)
+            && [finding.ruleId, finding.file, finding.message].every(value => typeof value === "string" && value.trim()))
+        && Object.entries(severities).every(([severity, key]) => Number.isSafeInteger(report.summary[key]) && Number(report.summary[key]) >= 0
+            && report.summary[key] === report.findings.filter(finding => finding.severity === severity).length);
+    if (!valid)
+        fail(result.exit_code === 0 ? "lint_gate_invalid_output" : "lint_gate_tool_failed", "Selected-file mb-lint returned an invalid report", { process: evidence });
+    const errors = Number(report.summary.errors);
+    if ((errors > 0 ? 1 : 0) !== result.exit_code)
+        fail("lint_gate_invalid_output", "Selected-file mb-lint report contradicts its exit status", { process: evidence });
+    if (errors > 0)
+        fail("lint_gate_failed", "Selected-file mb-lint reported blocking findings", { process: evidence, report: parsed, summary: report.summary, finding_count: report.findings.length });
+    const findingCount = report.findings.length;
     return { ok: true, status: "passed", binary, files, finding_count: findingCount, result: parsed };
 }
 function renderMarkdown(report) {

package/dist/services/tooling.js

@@ -4,7 +4,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { commandResult, commandText } from '../harness-runtime/lib/process-json.mjs';
 import { publishSetup, SETUP_STARTUP_MS } from '../harness-runtime/lib/setup-progress.mjs';
-import { AppError } from "../shared/errors.js";
+import { AppError, processEvidence } from "../shared/errors.js";
 import { ensureDir } from "../storage/paths.js";
 const manifestRelativePath = path.join("tools", "worktrunk-manifest.json");
 const managedToolRootName = "wt";
@@ -206,24 +206,26 @@ function verifyCachedWorktrunk(context, manifest, platform) {
         binary_sha256: actualBinaryChecksum
     };
 }
-async function extractArchive(archive, destination, format) {
+export async function extractArchive(archive, destination, format) {
     if (format === "tar.xz") {
         const listing = await commandResult("tar", ["-tJf", archive], { startupMs: SETUP_STARTUP_MS });
-        if (listing.exit_code !== 0 || listing.stdout.split("\n").some(unsafeArchivePath)) {
-            throw new AppError("tool_integrity_failed", "Pinned Worktrunk archive has an unsafe or unreadable file list", 1);
-        }
+        if (listing.exit_code !== 0 || listing.signal)
+            throw new AppError("tool_integrity_failed", "Pinned Worktrunk archive listing failed", 1, { process: processEvidence(listing) });
+        if (listing.stdout.split("\n").some(unsafeArchivePath))
+            throw new AppError("tool_integrity_failed", "Pinned Worktrunk archive has an unsafe file list", 1, { phase: "archive_path_validation" });
         const extracted = await commandResult("tar", ["-xJvf", archive, "-C", destination], { startupMs: SETUP_STARTUP_MS });
-        if (extracted.exit_code !== 0)
-            throw new AppError("tool_integrity_failed", "Pinned Worktrunk archive extraction failed", 1, { stderr: sanitize(extracted.stderr) });
+        if (extracted.exit_code !== 0 || extracted.signal)
+            throw new AppError("tool_integrity_failed", "Pinned Worktrunk archive extraction failed", 1, { process: processEvidence(extracted) });
         return;
     }
     const listing = await commandResult("unzip", ["-Z1", archive], { startupMs: SETUP_STARTUP_MS });
-    if (listing.exit_code !== 0 || listing.stdout.split("\n").some(unsafeArchivePath)) {
-        throw new AppError("tool_integrity_failed", "Pinned Worktrunk archive has an unsafe or unreadable file list", 1);
-    }
+    if (listing.exit_code !== 0 || listing.signal)
+        throw new AppError("tool_integrity_failed", "Pinned Worktrunk archive listing failed", 1, { process: processEvidence(listing) });
+    if (listing.stdout.split("\n").some(unsafeArchivePath))
+        throw new AppError("tool_integrity_failed", "Pinned Worktrunk archive has an unsafe file list", 1, { phase: "archive_path_validation" });
     const extracted = await commandResult("unzip", [archive, "-d", destination], { startupMs: SETUP_STARTUP_MS });
-    if (extracted.exit_code !== 0)
-        throw new AppError("tool_integrity_failed", "Pinned Worktrunk archive extraction failed", 1, { stderr: sanitize(extracted.stderr) });
+    if (extracted.exit_code !== 0 || extracted.signal)
+        throw new AppError("tool_integrity_failed", "Pinned Worktrunk archive extraction failed", 1, { process: processEvidence(extracted) });
 }
 function findBinary(root) {
     const expected = process.platform === "win32" ? "wt.exe" : "wt";

package/dist/services/verification-matrix.js

@@ -52,9 +52,10 @@ export function renderVerificationMatrix(matrix) {
     return [`# Verification matrix`, "", `RUN: ${escape(h.run_id)}; stage: ${escape(h.stage)} / ${escape(h.stage_attempt)}; role: ${h.role}; completeness: ${h.completeness}.`, "", "This generated view is not semantic acceptance. A retained passed check proves only its declared contour and proof limits.", "", "## Requirements", "", "| Protocol | Requirement | Statement | PLAN items / checks |", "| --- | --- | --- | --- |", ...matrix.requirements.map(row => `| ${escape(row.protocol_id)} | ${escape(row.id)} | ${escape(row.statement)} | ${escape(row.plan_items.map(item => `${item.id}: ${item.check_refs.join(", ")}`).join("; "))} |`), "", "## Acceptance criteria", "", "| Protocol | Criterion | Gate | Checks / native results | Proof limits |", "| --- | --- | --- | --- | --- |", ...matrix.criteria.map(row => `| ${escape(row.protocol_id)} | ${escape(row.criterion_id)} | ${escape(row.gate ?? "not declared")} | ${escape(row.checks.map(check => `${check.canonical_ref}: ${status(check)}`).join("; "))} | ${escape(JSON.stringify(row.declaration?.proof_limits ?? []))} |`), "", "## Policy checks", "", ...matrix.policy_checks.map(check => `- ${escape(check.canonical_ref)}: ${escape(status(check))}`), "", "## Sources", "", ...matrix.sources.map(source => `- ${escape(source.role)}: ${escape(`${source.root}:${source.path}`)} (${source.sha256})`), ""].join("\n");
 }
 export function verificationMatrixInstruction(metadata, runHome, task) {
+    const contract = `<verification_evidence_contract>\nCheck prerequisites must be executable in the check command or supported project policy; purpose prose and list order do not prepare an environment. A readiness gate is final verification, not implicit setup before the first CODE Work. PLAN and PLAN-REVIEW must compare claimed prerequisites with the actual launch path: a description saying migrate-before-check cannot repair a command that checks before migration. Prefer the existing self-contained project verification alias.\nBrowser checks must prove the expected surface exists and the measured set is nonempty before asserting layout geometry. An empty DOM is not evidence of no overlap. Derive navigation from the actual UI and accepted specification. Review whether the test can fail for the intended defect; a green named contour does not prove complete product semantics. Keep native test outcome separate from observation/cleanup: passed assertions with unknown cleanup are neither PASS nor a product assertion failure. Use retained native diagnostics and proof limits; generic timeouts or infrastructure errors do not authorize source repair. Do not patch the candidate product outside the assigned flow Work.\n</verification_evidence_contract>\n`;
     if (!metadata)
-        return "";
-    return `<verification_matrix>\nRuntime generated the technical verification matrix: ${safePath(runHome, metadata.markdown.path, false)}; structured data: ${safePath(runHome, metadata.json.path, false)}. Source fingerprint: ${metadata.source_fingerprint}; completeness: ${metadata.completeness}. Read it before ${task}. This is a derived view of the named accepted requirements, PLAN and receipts, not semantic acceptance. Do not edit these generated files or manually duplicate receipt IDs/hashes/results. Record insufficient proof or violated criteria in the ordinary Stage/Work result with evidence references; modify only your assigned source/test/result documents. Review inputs remain read-only. A passed check proves only its named contour and limits, not all business semantics or production readiness.\n</verification_matrix>\n`;
+        return contract;
+    return `${contract}<verification_matrix>\nRuntime generated the technical verification matrix: ${safePath(runHome, metadata.markdown.path, false)}; structured data: ${safePath(runHome, metadata.json.path, false)}. Source fingerprint: ${metadata.source_fingerprint}; completeness: ${metadata.completeness}. Read it before ${task}. This is a derived view of the named accepted requirements, PLAN and receipts, not semantic acceptance. Do not edit these generated files or manually duplicate receipt IDs/hashes/results. Record insufficient proof or violated criteria in the ordinary Stage/Work result with evidence references; modify only your assigned source/test/result documents. Review inputs remain read-only. A passed check proves only its named contour and limits, not all business semantics or production readiness.\n</verification_matrix>\n`;
 }
 /** Attachment and packet authority share a short transaction, then both files
  * must be visible before the prompt claims they are ready. */

package/dist/services/vnext-plan.js

@@ -120,8 +120,7 @@ export function startVnextPlan(context, input, prepared = prepareVnextPlanStart(
         : `PLAN-REVIEW mode is ${planReviewMode}: include review groups only for genuinely applicable aspects; an empty set is allowed.`;
     fs.writeFileSync(promptPath, `${prompt}\n<review_mode_rule>${reviewModeRule}</review_mode_rule>\n<verification_rule>Every flow check must be an autonomous executable command. Do not declare external/manual proof or a human review as a check, evidence substitute, DEF, or gate. The only user interaction supported by this flow is an explicit stage pause for a material unanswered question.</verification_rule>\n${stageLifecycleInstruction}\n`);
     const externalContext = applyExternalStageContext({ context, stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
-    if (prepared.matrix)
-        fs.appendFileSync(promptPath, verificationMatrixInstruction(prepared.matrix.metadata, home, "designing the source PLAN and its tests"));
+    fs.appendFileSync(promptPath, verificationMatrixInstruction(prepared.matrix?.metadata ?? null, home, "designing the source PLAN and its tests"));
     fs.writeFileSync(path.join(root, "work-context.json"), JSON.stringify({ schema_id: "dd-flow/work-context@1", system: { run_id: run.id, work_id: planWorkId, stage: "plan" }, workspace: { project_root: projectRoot, workspace_root: run.workspace_root, stage_root: root }, artifacts: artifactMaterialization, input: { protocols, owned_obligations: Object.fromEntries(owned) } }, null, 2));
     const binding = bindStageCoordinatorWork(context, { workId: planWorkId, hookEventId: input.hookEventId, stage: "plan", promptPath, resultPath: path.join(root, "stage-report.json"), ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
     const attachmentInput = { projectRoot, runId: run.id, stage: "plan", dir: "03-plan", status: "running", dataSchemaId: "dd-flow/protocol-plan@6" };