@deksden-com/dd-flow-cli 0.9.0-beta.8 → 0.9.0-beta.81

package/dist/services/code-checks.js

@@ -2,14 +2,25 @@ import crypto from "node:crypto";
 import { spawn, spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
+import { parse } from "shell-quote";
+import { assertRunMutationAllowed } from "./run-recovery.js";
 import { AppError } from "../shared/errors.js";
-import { confirmManagedProcess, finishManagedProcess, heartbeatManagedProcess, managedProcessStatus, processIsAlive, registerManagedProcess, reservePorts } from "./managed-processes.js";
+import { confirmManagedProcess, finishManagedProcess, heartbeatManagedProcess, managedProcessStatus, managedProcessRuntimeHome, managedOwnerIsAlive, processTreeIsAlive, registerManagedProcess, reservePorts } from "./managed-processes.js";
+import { admitRuntimeCheck, runtimeBudgetForRun } from "./runtime-budget.js";
 const profileRelativePath = path.join(".memory-bank", "spec", "engineering", "code-check-profile.json");
 // Receipt reservation precedes child spawn so an interrupted CLI leaves an
 // auditable attempt. A second caller must not mistake that small handoff window
 // for a dead check and overwrite its outcome.
 const receiptStartingGraceMs = 30_000;
-export function codeExecutionEnvironment(workspaceRoot) { const suffix = crypto.createHash("sha256").update(path.resolve(workspaceRoot)).digest("hex").slice(0, 12); return { ...process.env, DD_FLOW_LOCAL_DATABASE_SUFFIX: suffix }; }
+export function codeExecutionEnvironment(workspaceRoot) {
+    const suffix = crypto.createHash("sha256").update(path.resolve(workspaceRoot)).digest("hex").slice(0, 12);
+    // Managed checks retain the launcher's executable resolution. A login shell
+    // or NODE_PATH can silently replace it, including with another architecture.
+    const environment = { ...process.env, DD_FLOW_LOCAL_DATABASE_SUFFIX: suffix };
+    delete environment.NODE_PATH;
+    return environment;
+}
+export function workspaceOperationId(workspaceRoot) { return `workspace:${crypto.createHash("sha256").update(path.resolve(workspaceRoot)).digest("hex")}`; }
 export function readCodeCheckProfile(workspaceRoot) {
     const file = path.join(workspaceRoot, profileRelativePath);
     if (!fs.existsSync(file))
@@ -18,8 +29,8 @@ export function readCodeCheckProfile(workspaceRoot) {
     const value = JSON.parse(bytes.toString("utf8"));
     if (value.schema_id !== "dd-flow/code-check-profile@6")
         throw new AppError("invalid_code_check_profile", "CODE check profile has an unsupported schema", 2, { file, schema_id: value.schema_id ?? null, required: "dd-flow/code-check-profile@6" });
-    if (!isStringRecord(value.aliases) || !isStringRecord(value.require_alias_for) || !isGateRecord(value.mandatory_by_gate) || !isPortAliasRecord(value.ports_by_alias))
-        throw new AppError("invalid_code_check_profile", "CODE check profile aliases, require_alias_for, mandatory_by_gate or ports_by_alias are invalid", 2, { file });
+    if (!isStringRecord(value.aliases) || !isStringRecord(value.require_alias_for) || !isGateRecord(value.mandatory_by_gate) || !isPortAliasRecord(value.ports_by_alias) || !isInputAliasRecord(workspaceRoot, value.inputs_by_alias))
+        throw new AppError("invalid_code_check_profile", "CODE check profile aliases, require_alias_for, mandatory_by_gate, ports_by_alias or inputs_by_alias are invalid", 2, { file });
     for (const [gate, aliases] of Object.entries(value.mandatory_by_gate))
         for (const alias of aliases ?? [])
             if (!value.aliases[alias])
@@ -27,19 +38,24 @@ export function readCodeCheckProfile(workspaceRoot) {
     for (const alias of Object.keys(value.ports_by_alias ?? {}))
         if (!value.aliases[alias])
             throw new AppError("invalid_code_check_profile", "A port declaration references an unknown alias", 2, { file, alias });
+    for (const alias of Object.keys(value.inputs_by_alias ?? {}))
+        if (!value.aliases[alias])
+            throw new AppError("invalid_code_check_profile", "An input declaration references an unknown alias", 2, { file, alias });
     return { profile: value, hash: crypto.createHash("sha256").update(bytes).digest("hex"), file };
 }
 export function validateCodeCheckCommands(workspaceRoot, commands) {
     const { profile, file } = readCodeCheckProfile(workspaceRoot);
-    if (!profile)
-        return [...commands];
-    return commands.map((command) => { if (command.startsWith("@check/")) {
-        if (!profile.aliases[command]?.trim())
-            throw new AppError("unknown_code_check_alias", "CODE check alias is not defined by the project profile", 2, { alias: command, file });
+    return commands.map((command) => {
+        if (command.startsWith("@check/")) {
+            if (!profile?.aliases[command]?.trim())
+                throw new AppError("unknown_code_check_alias", "CODE check alias is not defined by the project profile", 2, { alias: command, file });
+            return command;
+        }
+        for (const [prefix, alias] of Object.entries(profile?.require_alias_for ?? {}))
+            if (command === prefix || command.startsWith(`${prefix} `))
+                throw new AppError("raw_code_check_forbidden", "CODE check must use the project alias instead of a raw guarded command", 2, { command, required_alias: alias, file });
         return command;
-    } for (const [prefix, alias] of Object.entries(profile.require_alias_for))
-        if (command === prefix || command.startsWith(`${prefix} `))
-            throw new AppError("raw_code_check_forbidden", "CODE check must use the project alias instead of a raw guarded command", 2, { command, required_alias: alias, file }); return command; });
+    });
 }
 export function resolveCodeCheckCommands(workspaceRoot, runId, commands) {
     const validated = validateCodeCheckCommands(workspaceRoot, commands);
@@ -50,7 +66,7 @@ export function resolveCodeCheckCommands(workspaceRoot, runId, commands) {
 }
 export function projectPolicyCheckDeclarations(workspaceRoot, gate) {
     const { profile } = readCodeCheckProfile(workspaceRoot);
-    return (profile?.mandatory_by_gate[gate] ?? []).map((alias) => { const ref = `POLICY/${gate}/${alias.slice(7).replace(/[^a-z0-9]+/gi, "-").replace(/^-|-$/g, "").toLowerCase()}`; return { id: ref, canonical_ref: ref, source: "project_policy", command: alias, purpose: `Mandatory project ${gate} gate.`, run_at: gate, availability: "available", ...(profile?.ports_by_alias?.[alias] ? { ports: profile.ports_by_alias[alias] } : {}) }; });
+    return (profile?.mandatory_by_gate[gate] ?? []).map((alias) => { const ref = `POLICY/${gate}/${alias.slice(7).replace(/[^a-z0-9]+/gi, "-").replace(/^-|-$/g, "").toLowerCase()}`; return { id: ref, canonical_ref: ref, source: "project_policy", command: alias, purpose: `Mandatory project ${gate} gate.`, run_at: gate, availability: "available", ...(profile?.ports_by_alias?.[alias] ? { ports: profile.ports_by_alias[alias] } : {}), ...(profile?.inputs_by_alias?.[alias] ? { inputs: profile.inputs_by_alias[alias] } : {}) }; });
 }
 export function effectiveCheckDeclarations(workspaceRoot, declared, gates) { return gates.flatMap((gate) => [...declared.filter((check) => check.run_at === gate), ...projectPolicyCheckDeclarations(workspaceRoot, gate)]); }
 export function aggregateCheckDeclarations(workspaceRoot) { return projectPolicyCheckDeclarations(workspaceRoot, "code"); }
@@ -60,12 +76,15 @@ export function validateCheckPlacement(workspaceRoot, checks) { const { profile
     if (check.run_at === "work" && aggregateCommands.has(check.command))
         throw new AppError("aggregate_check_requires_code_gate", "A project aggregate check must run at CODE or readiness, not inside one scoped Work", 2, { check_id: check.id, command: check.command, run_at: check.run_at }); }
 export function validateCheckDeclaration(workspaceRoot, check) {
-    if (check.run_at === "external")
-        return;
+    if (!["work", "code", "readiness", "merge", "release"].includes(check.run_at))
+        throw new AppError("unsupported_check_gate", "Check requires an autonomous executable gate; replan the incompatible declaration", 2, { check_id: check.id, run_at: check.run_at });
     const { profile } = readCodeCheckProfile(workspaceRoot);
     if (check.availability === "planned" && check.command.startsWith("@check/") && !profile?.aliases[check.command])
         throw new AppError("planned_check_not_materialized", "A planned check alias was not materialized by its provider Work", 2, { check_id: check.id, command: check.command, provider: check.provided_by ?? null });
     validateCodeCheckCommands(workspaceRoot, [check.command]);
+    if (check.availability === "available" && !check.command.startsWith("@check/"))
+        assertDirectCheckExecutable(workspaceRoot, check.command, check.id);
+    validateCheckInputs(workspaceRoot, check.inputs ?? []);
     if (check.command.startsWith("@check/") && check.definition && profile?.aliases[check.command] !== check.definition)
         throw new AppError("check_definition_drift", "The accepted check alias definition differs from the current project profile", 2, { check_id: check.id, alias: check.command, expected: check.definition, actual: profile?.aliases[check.command] ?? null });
     if (check.availability !== "planned")
@@ -77,50 +96,133 @@ export function validateCheckDeclaration(workspaceRoot, check) {
     if (!profile?.aliases[check.command])
         throw new AppError("planned_check_not_materialized", "A planned check alias was not materialized by its provider Work", 2, { check_id: check.id, command: check.command, provider: check.provided_by ?? null });
 }
+/** Reject a plan-time typo or a fictitious "manual" command before it becomes
+ * a late shell exit. Compound shell programs remain valid: only a simple,
+ * directly named executable is preflighted here. */
+function assertDirectCheckExecutable(workspaceRoot, command, checkId) {
+    const trimmed = command.trim();
+    // A shell operator or expansion makes the launch path dynamic. Do not
+    // guess there; this preflight is deliberately limited to a direct program
+    // with ordinary arguments and optional literal environment assignments.
+    if (/[|&;<>()`$\n\r~]/.test(trimmed))
+        return;
+    const parsed = parse(trimmed);
+    if (parsed.some(word => typeof word !== "string"))
+        return;
+    const words = parsed;
+    let index = 0;
+    const env = codeExecutionEnvironment(workspaceRoot);
+    while (/^[A-Za-z_][A-Za-z0-9_]*=/.test(words[index] ?? "")) {
+        const assignment = words[index++];
+        const equals = assignment.indexOf("=");
+        env[assignment.slice(0, equals)] = assignment.slice(equals + 1);
+    }
+    const program = words[index];
+    if (!program)
+        return;
+    const probe = spawnSync("/bin/sh", ["-c", "command -v -- \"$1\" >/dev/null", "dd-flow-check", program], { cwd: workspaceRoot, env, encoding: "utf8", timeout: 5000 });
+    if (probe.status !== 0)
+        throw new AppError("check_command_unavailable", "Available CODE check names an executable that is unavailable in this environment", 2, { check_id: checkId, command, executable: program });
+}
 export async function runCodeChecks(context, input) {
     reconcileUnfinishedChecks(context, input);
+    reconcileWorkspaceOwnership(context, input.workspaceRoot);
+    const gate = acquireWorkspaceGate(context, input);
+    try {
+        return await runCodeChecksOwned(context, input, gate.id);
+    }
+    finally {
+        finishManagedProcess(context, { id: gate.id, leaseToken: gate.lease_token, state: "stopped", reason: "workspace_gate_settled" });
+    }
+}
+async function runCodeChecksOwned(context, input, workspaceGateId) {
+    const generation = assertRunMutationAllowed(context, input.projectId, input.runId);
     for (const check of input.checks)
         validateCheckDeclaration(input.workspaceRoot, check);
     const { hash: profileHash, profile } = readCodeCheckProfile(input.workspaceRoot);
-    const checks = input.checks.map((check) => { const ports = profile?.ports_by_alias?.[check.command]; return check.ports || !ports ? check : { ...check, ports }; });
+    if (input.expectedProfileHash !== undefined && input.expectedProfileHash !== profileHash)
+        throw new AppError("check_profile_drift", "The frozen check profile differs from the workspace profile", 1, { expected_profile_hash: input.expectedProfileHash, actual_profile_hash: profileHash });
+    const checks = input.checks.map((check) => { const ports = profile?.ports_by_alias?.[check.command]; const inputs = profile?.inputs_by_alias?.[check.command]; return { ...check, ...(check.ports || !ports ? {} : { ports }), ...(check.inputs || !inputs ? {} : { inputs }) }; });
     const resolved = resolveCodeCheckCommands(input.workspaceRoot, input.runId, checks.map((check) => check.command));
-    const groups = deduplicate(checks, resolved);
-    const receipts = [];
+    assertConsistentDeclarations(checks, resolved);
+    const groups = deduplicate(checks, resolved), receipts = [];
+    const retryIds = [...new Set([...(input.retryReceiptId ? [input.retryReceiptId] : []), ...(input.retryReceiptIds ?? [])])];
+    const retries = new Map();
+    for (const receiptId of retryIds) {
+        const predecessor = validateFailedCheckRetry(context, { projectId: input.projectId, runId: input.runId, receiptId, declarations: checks, reason: input.retryReason });
+        const snapshot = workspaceState(input.workspaceRoot, [input.runHome]);
+        const group = groups.find(candidate => candidate.declarations.some(check => check.run_at === predecessor.gate)
+            && checkInputHash(input.workspaceRoot, { ...candidate, gate: predecessor.gate }, profileHash, workspaceInputFingerprint(input.workspaceRoot, snapshot.files, candidate.inputs, [input.runHome])) === predecessor.input_hash);
+        if (!group || retries.has(group))
+            throw new AppError("retry_check_invalid", "Retry must match exactly one current execution contract", 2, { check_receipt_id: receiptId });
+        // Preserve the identity of a pre-deduplication failed execution when an
+        // upgraded RUN retries it; the new receipt still proves every grouped ref.
+        group.gate = predecessor.gate;
+        retries.set(group, receiptId);
+    }
     for (let index = 0; index < groups.length; index += 1) {
         const group = groups[index];
         const before = workspaceState(input.workspaceRoot, [input.runHome]);
         const startedAt = context.now();
-        const inputHash = crypto.createHash("sha256").update(JSON.stringify({ gate: group.gate, command: group.command, environment: String(codeExecutionEnvironment(input.workspaceRoot).DD_FLOW_LOCAL_DATABASE_SUFFIX), required_artifacts: group.requiredArtifacts, ports: [...group.ports].sort() })).digest("hex");
+        const inputFingerprint = workspaceInputFingerprint(input.workspaceRoot, before.files, group.inputs, [input.runHome]);
+        const inputHash = checkInputHash(input.workspaceRoot, group, profileHash, inputFingerprint);
         const epoch = crypto.createHash("sha256").update(`${group.gate}\0${before.fingerprint}`).digest("hex");
-        const reserved = reserveReceipt(context, { ...input, group, before, profileHash, inputHash, epoch, startedAt });
+        const reservationInput = { ...input, retryReceiptIds: retries.has(group) ? [retries.get(group)] : [], generation, group, before, profileHash, inputHash, epoch, startedAt };
+        delete reservationInput.retryReceiptId;
+        const decision = reserveOrReuseReceipt(context, reservationInput);
+        if (decision.receipt) {
+            receipts.push(bindReceipt(decision.receipt, group));
+            input.progress?.(`check ${index + 1}/${groups.length} ${decision.receipt.status === "passed" ? "reused" : "requires repair"}: ${group.command}`);
+            continue;
+        }
+        const reserved = decision.reserved;
         const { id, evidenceDir, stdoutPath, stderrPath, receiptPath, completionPath } = reserved;
         let resources = {};
         let result = { exitCode: null, error: "check did not start", aborted: true };
         try {
             fs.mkdirSync(evidenceDir, { recursive: true });
             writeReceipt(receiptPath, receiptFor({ ...reserved, resources, result, status: "running", after: before, mutationPaths: [], artifacts: [] }));
-            const managed = registerManagedProcess(context, { kind: "check", ownerId: `check:${id}`, projectId: input.projectId, runId: input.runId, workId: input.workId ?? null, checkId: id, stdoutPath, stderrPath, metadata: { command: group.command } });
+            const budget = runtimeBudgetForRun(context, input.projectId, input.runId);
+            const managed = registerManagedProcess(context, { kind: "check", ownerPid: process.pid, ownerId: `check:${id}`, operationId: workspaceOperationId(input.workspaceRoot), projectId: input.projectId, runId: input.runId, workId: input.workId ?? null, checkId: id, stdoutPath, stderrPath, metadata: { command: group.command, role: "check", workspace_root: input.workspaceRoot, workspace_gate_id: workspaceGateId, budget } });
             const allocation = await reservePorts(context, { ownerId: managed.owner_id, processId: managed.id, names: group.ports });
             resources = allocation.ports;
-            input.progress?.(`check ${index + 1}/${groups.length} started: ${group.command}`);
+            try {
+                input.progress?.(`check ${index + 1}/${groups.length} preparing: ${group.command}`);
+                assertRunMutationAllowed(context, input.projectId, input.runId, generation);
+            }
+            catch (error) {
+                allocation.release();
+                finishManagedProcess(context, { id: managed.id, leaseToken: managed.lease_token, state: "failed", reason: "dispatch_fenced_before_spawn" });
+                throw error;
+            }
             const stdout = fs.openSync(stdoutPath, "a");
             const stderr = fs.openSync(stderrPath, "a");
             try {
-                result = await runCheck(group.command, input.workspaceRoot, { ...codeExecutionEnvironment(input.workspaceRoot), DD_FLOW_EVIDENCE_DIR: evidenceDir, DD_FLOW_CHECK_COMPLETION_FILE: completionPath, ...portEnvironment(resources) }, stdout, stderr, (elapsed) => input.progress?.(`check ${index + 1}/${groups.length} still running (${elapsed}s): ${group.command}`), (pid) => confirmManagedProcess(context, { id: managed.id, leaseToken: managed.lease_token, pid, processGroupId: process.platform === "win32" ? null : pid }), () => heartbeatManagedProcess(context, { id: managed.id, leaseToken: managed.lease_token }));
+                result = await runCheck(group.command, input.workspaceRoot, { ...codeExecutionEnvironment(input.workspaceRoot), DD_FLOW_EVIDENCE_DIR: evidenceDir, DD_FLOW_CHECK_COMPLETION_FILE: completionPath, ...portEnvironment(resources) }, stdout, stderr, (elapsed) => input.progress?.(`check ${index + 1}/${groups.length} still running (${elapsed}s): ${group.command}`), (pid) => {
+                    confirmManagedProcess(context, { id: managed.id, leaseToken: managed.lease_token, pid, processGroupId: process.platform === "win32" ? null : pid });
+                    assertRunMutationAllowed(context, input.projectId, input.runId, generation);
+                    if (budget)
+                        admitRuntimeCheck(context, managed.id, managed.lease_token);
+                }, () => heartbeatManagedProcess(context, { id: managed.id, leaseToken: managed.lease_token }));
             }
             finally {
-                allocation.release();
                 fs.closeSync(stdout);
                 fs.closeSync(stderr);
-                finishManagedProcess(context, { id: managed.id, leaseToken: managed.lease_token, state: result.aborted || result.exitCode !== 0 || Boolean(result.error) ? "failed" : "stopped", reason: result.error });
             }
+            const current = managedProcessStatus(context).find(item => item.id === managed.id);
+            if (processTreeIsAlive(current))
+                throw new AppError("check_in_progress", "The check shell exited but its process tree is still live; retain this receipt and its resources until settlement", 2, { process_id: managed.id, check_receipt_id: id });
+            allocation.release();
+            finishManagedProcess(context, { id: managed.id, leaseToken: managed.lease_token, state: result.aborted || result.exitCode !== 0 || Boolean(result.error) ? "failed" : "stopped", reason: result.error });
         }
         catch (error) {
+            if (error instanceof AppError && error.code === "check_in_progress")
+                throw error;
             result = { exitCode: null, error: error instanceof Error ? error.message : String(error), aborted: true };
         }
         const after = workspaceState(input.workspaceRoot, [input.runHome]);
         const mutationPaths = changedPaths(before.files, after.files);
-        const artifacts = collectRequiredArtifacts(evidenceDir, group.requiredArtifacts);
+        const artifacts = collectCheckArtifacts(evidenceDir, group.requiredArtifacts);
         if (fs.existsSync(stderrPath)) {
             if (!artifacts.complete)
                 fs.appendFileSync(stderrPath, `\nmissing required evidence artifacts: ${artifacts.missing.join(", ")}\n`);
@@ -136,6 +238,16 @@ export async function runCodeChecks(context, input) {
         receipts.push(receipt);
         input.progress?.(`check ${index + 1}/${groups.length} ${status}: ${group.command}`);
     }
+    if (receipts.every(receipt => receipt.status === "passed")) {
+        const current = workspaceState(input.workspaceRoot, [input.runHome]), { hash: currentProfileHash } = readCodeCheckProfile(input.workspaceRoot);
+        for (const receipt of receipts) {
+            const group = groups.find(candidate => candidate.declarations.some(check => receipt.check_refs.includes(checkRef(check))));
+            const currentHash = group ? checkInputHash(input.workspaceRoot, group, currentProfileHash, workspaceInputFingerprint(input.workspaceRoot, current.files, group.inputs, [input.runHome])) : null;
+            if (!group || !checkReceiptEvidenceValid(receipt) || receipt.input_hash !== currentHash)
+                throw new AppError("check_evidence_stale", "Check evidence changed before the gate could be accepted", 1, { check_receipt_id: receipt.id });
+        }
+        assertRunMutationAllowed(context, input.projectId, input.runId, generation);
+    }
     return receipts;
 }
 /**
@@ -144,25 +256,36 @@ export async function runCodeChecks(context, input) {
  * a dead/terminal process becomes an explicit aborted receipt that can retry.
  */
 export function reconcileUnfinishedChecks(context, input) {
-    const where = input.workId ? "project_id = ? AND run_id = ? AND work_id = ? AND status = 'running'" : "project_id = ? AND run_id = ? AND status = 'running'";
+    let where = input.workId ? "project_id = ? AND run_id = ? AND work_id = ? AND status = 'running'" : "project_id = ? AND run_id = ? AND status = 'running'";
     const params = input.workId ? [input.projectId, input.runId, input.workId] : [input.projectId, input.runId];
+    if (input.receiptId) {
+        where += " AND id = ?";
+        params.push(input.receiptId);
+    }
     const pending = context.db.all(`SELECT id, receipt_path, started_at FROM check_receipts WHERE ${where}`, params);
     if (pending.length === 0)
         return [];
     const processes = managedProcessStatus(context);
     const reconciled = [];
     for (const pendingReceipt of pending) {
-        const process = processes.filter((item) => item.check_id === pendingReceipt.id).at(-1);
+        const process = processes.filter((item) => item.check_id === pendingReceipt.id && item.project_id === input.projectId && item.run_id === input.runId).at(-1);
         const receipt = readReceipt(pendingReceipt.receipt_path);
         const completion = receipt ? readCompletion(receipt.completion_path || path.join(path.dirname(pendingReceipt.receipt_path), "completion.json")) : null;
-        if (process && ["starting", "running", "stopping"].includes(process.state) && processLeaseIsCurrent(process) && (process.state === "starting" || processIsAlive(process))) {
+        // A stale lease after host sleep is not permission to duplicate a living
+        // check.  Its durable completion marker or explicit reconciliation decides
+        // the outcome before another invocation may start.
+        // A confirmed PID plus its birth time is sufficient to prove that this
+        // exact check writer is gone. Do not retain a dead receipt merely because
+        // older registrations lack the optional parent-owner identity.
+        const processProvenDead = Boolean(process?.pid && process.pid_started_at && !processTreeIsAlive(process));
+        if (process && !processProvenDead && (processTreeIsAlive(process) || (["starting", "running", "stopping", "orphaned"].includes(process.state) && managedOwnerIsAlive(process) !== false))) {
             throw new AppError("check_in_progress", "A previous check invocation is still running", 1, { check_receipt_id: pendingReceipt.id, process_id: process.id, pid: process.pid });
         }
         if (!process && !completion && Date.now() - Date.parse(pendingReceipt.started_at) < receiptStartingGraceMs) {
             throw new AppError("check_in_progress", "A previous check invocation is still initializing", 1, { check_receipt_id: pendingReceipt.id, initializing: true });
         }
         const after = workspaceState(input.workspaceRoot, input.runHome ? [input.runHome] : []);
-        const artifacts = receipt ? collectRequiredArtifacts(path.join(path.dirname(receipt.completion_path || pendingReceipt.receipt_path), "artifacts"), receipt.required_artifacts ?? []) : { complete: false, missing: [], items: [] };
+        const artifacts = receipt ? collectCheckArtifacts(path.join(path.dirname(receipt.completion_path || pendingReceipt.receipt_path), "artifacts"), receipt.required_artifacts ?? []) : { complete: false, missing: [], items: [] };
         const workspaceUnchanged = receipt?.before_fingerprint === after.fingerprint;
         const status = completion === null ? "aborted" : completion.exit_code === 0 && workspaceUnchanged && artifacts.complete ? "passed" : "failed";
         const exitCode = completion?.exit_code ?? null;
@@ -178,25 +301,64 @@ export function reconcileUnfinishedChecks(context, input) {
     }
     return reconciled;
 }
-function reserveReceipt(context, input) {
-    context.db.exec("BEGIN IMMEDIATE");
+function reserveOrReuseReceipt(context, input) {
+    context.db.beginWriteTransaction();
     try {
-        const rows = context.db.all("SELECT id FROM check_receipts WHERE work_id IS ? AND run_id = ?", [input.workId ?? null, input.runId]);
-        const ordinal = rows.reduce((max, row) => Math.max(max, Number(/\/RCP-(\d+)$/.exec(row.id)?.[1] ?? 0)), 0) + 1;
-        const localId = `RCP-${String(ordinal).padStart(3, "0")}`;
-        const id = `${input.workId ?? input.runId}/${localId}`;
+        assertRunMutationAllowed(context, input.projectId, input.runId, input.generation);
+        const prior = latestApplicableReceipt(context, input);
+        if (prior?.status === "running")
+            throw new AppError("check_in_progress", "A matching check invocation is still running", 1, { check_receipt_id: prior.id });
+        const retryIds = new Set([...(input.retryReceiptId ? [input.retryReceiptId] : []), ...(input.retryReceiptIds ?? [])]);
+        if (retryIds.size > 1)
+            throw new AppError("retry_check_invalid", "A check execution accepts exactly one retry predecessor", 2);
+        const retryId = [...retryIds][0];
+        if (retryId) {
+            if (!input.retryReason?.trim())
+                throw new AppError("retry_check_invalid", "A check retry requires the restored-condition reason", 2, { check_receipt_id: retryId });
+            const receipts = checkReceipts(context, { projectId: input.projectId, runId: input.runId });
+            const predecessor = receipts.find(receipt => receipt.id === retryId);
+            if (!predecessor || !["failed", "aborted"].includes(predecessor.status) || predecessor.input_hash !== input.inputHash || predecessor.profile_hash !== input.profileHash || predecessor.command !== input.group.command || predecessor.gate !== input.group.gate)
+                throw new AppError("retry_check_invalid", "Retry predecessor does not match this exact check contract", 2, { check_receipt_id: retryId });
+            const successor = receipts.find(receipt => receipt.retry_of_receipt_id === retryId && receipt.input_hash === input.inputHash && receipt.profile_hash === input.profileHash);
+            if (prior?.id !== (successor?.id ?? predecessor.id))
+                throw new AppError("retry_check_invalid", "This retry was superseded by a newer check outcome; inspect the latest receipt", 2, { check_receipt_id: retryId, latest_check_receipt_id: prior?.id ?? null, latest_status: prior?.status ?? null });
+            if (successor?.status === "running")
+                throw new AppError("check_in_progress", "The requested retry is already running", 1, { check_receipt_id: successor.id, retry_of_receipt_id: retryId });
+            if (successor) {
+                if (successor.status === "passed" && checkReceiptEvidenceValid(successor)) {
+                    context.db.exec("COMMIT");
+                    return { receipt: successor };
+                }
+                throw new AppError("retry_check_invalid", "The requested retry already has a terminal outcome; choose its failed receipt for another retry", 2, { check_receipt_id: successor.id, retry_of_receipt_id: retryId, status: successor.status });
+            }
+        }
+        // Only success is reusable evidence. A new finish attempt must execute a
+        // failed check again: repairing dependencies/services need not change any
+        // tracked input. Lifecycle invocation replay owns command idempotency;
+        // the running-receipt guard above still prevents concurrent execution.
+        if (prior?.status === "passed" && !retryIds.has(prior.id) && input.group.reusable && checkReceiptEvidenceValid(prior)) {
+            context.db.exec("COMMIT");
+            return { receipt: prior };
+        }
+        let ordinal = (context.db.get("SELECT COALESCE(MAX(reservation_sequence), 0) + 1 AS sequence FROM check_receipts WHERE project_id = ? AND run_id = ?", [input.projectId, input.runId])?.sequence ?? 1);
+        let localId = `RCP-${String(ordinal).padStart(3, "0")}`, id = `${input.workId ?? input.runId}/${localId}`;
+        while (context.db.get("SELECT 1 FROM check_receipts WHERE id = ?", [id])) {
+            ordinal += 1;
+            localId = `RCP-${String(ordinal).padStart(3, "0")}`;
+            id = `${input.workId ?? input.runId}/${localId}`;
+        }
         const directory = path.join(input.runHome, input.artifactDir ?? "05-code", "checks", localId);
-        const reserved = { id, localId, directory, evidenceDir: path.join(directory, "artifacts"), stdoutPath: path.join(directory, "stdout.log"), stderrPath: path.join(directory, "stderr.log"), receiptPath: path.join(directory, "receipt.json"), completionPath: path.join(directory, "completion.json"), group: input.group, before: input.before, profileHash: input.profileHash, inputHash: input.inputHash, epoch: input.epoch, startedAt: input.startedAt, scope: input.scope, ...(input.workId ? { workId: input.workId } : {}), projectId: input.projectId, runId: input.runId };
-        context.db.run("INSERT INTO check_receipts (id, project_id, run_id, work_id, scope, declaration_id, check_refs_json, gate, command, input_hash, verification_epoch, status, exit_code, stdout_path, stderr_path, receipt_path, workspace_fingerprint, before_fingerprint, after_fingerprint, profile_hash, mutation_paths_json, artifacts_json, started_at, finished_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'running', NULL, ?, ?, ?, ?, ?, ?, ?, '[]', '[]', ?, ?)", [id, input.projectId, input.runId, input.workId ?? null, input.scope, input.group.declarations[0].id, JSON.stringify(input.group.declarations.map(checkRef)), input.group.gate, input.group.command, input.inputHash, input.epoch, reserved.stdoutPath, reserved.stderrPath, reserved.receiptPath, input.before.fingerprint, input.before.fingerprint, input.before.fingerprint, input.profileHash, input.startedAt, input.startedAt]);
+        const reserved = { id, localId, directory, evidenceDir: path.join(directory, "artifacts"), stdoutPath: path.join(directory, "stdout.log"), stderrPath: path.join(directory, "stderr.log"), receiptPath: path.join(directory, "receipt.json"), completionPath: path.join(directory, "completion.json"), group: input.group, before: input.before, profileHash: input.profileHash, inputHash: input.inputHash, epoch: input.epoch, startedAt: input.startedAt, scope: input.scope, ...(retryId ? { retryOf: retryId, retryReason: input.retryReason } : {}), ...(input.workId ? { workId: input.workId } : {}), projectId: input.projectId, runId: input.runId };
+        context.db.run("INSERT INTO check_receipts (id, project_id, run_id, work_id, scope, declaration_id, check_refs_json, gate, command, input_hash, verification_epoch, reservation_sequence, retry_of_receipt_id, retry_reason, status, exit_code, stdout_path, stderr_path, receipt_path, workspace_fingerprint, before_fingerprint, after_fingerprint, profile_hash, mutation_paths_json, artifacts_json, started_at, finished_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'running', NULL, ?, ?, ?, ?, ?, ?, ?, '[]', '[]', ?, ?)", [id, input.projectId, input.runId, input.workId ?? null, input.scope, input.group.declarations[0].id, JSON.stringify(input.group.declarations.map(checkRef).sort()), input.group.gate, input.group.command, input.inputHash, input.epoch, ordinal, reserved.retryOf ?? null, reserved.retryReason ?? null, reserved.stdoutPath, reserved.stderrPath, reserved.receiptPath, input.before.fingerprint, input.before.fingerprint, input.before.fingerprint, input.profileHash, input.startedAt, input.startedAt]);
         context.db.exec("COMMIT");
-        return reserved;
+        return { reserved };
     }
     catch (error) {
         context.db.exec("ROLLBACK");
         throw error;
     }
 }
-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, status: input.status, 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, 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 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, 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); }
 function readReceipt(file) { try {
     return JSON.parse(fs.readFileSync(file, "utf8"));
@@ -212,31 +374,261 @@ function readCompletion(file) { try {
 catch {
     return null;
 } }
-function processLeaseIsCurrent(process) { return Date.parse(process.lease_expires_at ?? "") >= Date.now(); }
-export function unchangedFinalGateFailures(context, input) { const wanted = new Set(input.declarations.flatMap((check) => [check.id, checkRef(check)])); const current = workspaceFingerprint(input.workspaceRoot); const latest = new Map(); for (const receipt of checkReceipts(context, { projectId: input.projectId, runId: input.runId }).filter((item) => item.scope === "aggregate" && item.check_refs.some((ref) => wanted.has(ref))))
-    for (const ref of receipt.check_refs)
-        latest.set(ref, receipt); return [...new Set(latest.values())].filter((receipt) => receipt.status === "failed" && receipt.before_fingerprint === current); }
+/** Validate an explicit retry; the caller still executes a fresh real gate and retains a new receipt. */
+export function validateFailedCheckRetry(context, input) {
+    if (!input.reason?.trim())
+        throw new AppError("retry_check_invalid", "--retry-check requires --reason describing the restored environment", 2);
+    const receipt = checkReceipts(context, { projectId: input.projectId, runId: input.runId }).find((item) => item.id === input.receiptId);
+    if (!receipt || !["failed", "aborted"].includes(receipt.status))
+        throw new AppError("retry_check_invalid", "--retry-check must name a failed or aborted receipt in this RUN", 2, { check_receipt_id: input.receiptId });
+    const declared = new Set(input.declarations.flatMap((check) => [check.id, checkRef(check)]));
+    if (!receipt.check_refs.some((ref) => declared.has(ref)))
+        throw new AppError("retry_check_invalid", "--retry-check does not belong to this stage gate", 2, { check_receipt_id: input.receiptId, check_refs: receipt.check_refs });
+    return receipt;
+}
 export function checkReceipts(context, input) {
     const where = input.workId ? "project_id = ? AND run_id = ? AND work_id = ?" : "project_id = ? AND run_id = ?";
     const params = input.workId ? [input.projectId, input.runId, input.workId] : [input.projectId, input.runId];
-    return context.db.all(`SELECT id, declaration_id, check_refs_json, gate, scope, work_id, command, input_hash, verification_epoch, status, exit_code, stdout_path, stderr_path, receipt_path, workspace_fingerprint, before_fingerprint, after_fingerprint, profile_hash, mutation_paths_json, artifacts_json, started_at, finished_at FROM check_receipts WHERE ${where} ORDER BY started_at, id`, params).map((row) => ({ ...row, local_id: row.id.slice(row.id.lastIndexOf("/") + 1), check_refs: parseArray(row.check_refs_json, [row.declaration_id]), mutation_paths: parseArray(row.mutation_paths_json, []), artifacts: JSON.parse(row.artifacts_json), resources: readReceiptResources(row.receipt_path) }));
+    return context.db.all(`SELECT id, declaration_id, check_refs_json, gate, scope, work_id, command, input_hash, verification_epoch, retry_of_receipt_id, retry_reason, status, exit_code, stdout_path, stderr_path, receipt_path, workspace_fingerprint, before_fingerprint, after_fingerprint, profile_hash, mutation_paths_json, artifacts_json, started_at, finished_at FROM check_receipts WHERE ${where} ORDER BY reservation_sequence, rowid`, params).map((row) => ({ ...row, local_id: row.id.slice(row.id.lastIndexOf("/") + 1), check_refs: parseArray(row.check_refs_json, [row.declaration_id]), mutation_paths: parseArray(row.mutation_paths_json, []), resources: readReceiptResources(row.receipt_path), ...resolvedReceiptArtifacts(row.receipt_path, JSON.parse(row.artifacts_json)) }));
+}
+/** File bytes remain immutable; only the reader projects their current location. */
+function resolvedReceiptArtifacts(receiptPath, artifacts) {
+    let original = {};
+    try {
+        original = JSON.parse(fs.readFileSync(receiptPath, "utf8"));
+    }
+    catch { /* Historical missing receipts remain visibly incomplete. */ }
+    const currentRoot = path.dirname(receiptPath);
+    const oldRoot = original.receipt_path ? path.dirname(original.receipt_path) : currentRoot;
+    const relocate = (file) => {
+        const relative = path.relative(oldRoot, file);
+        return !path.isAbsolute(relative) && relative !== ".." && !relative.startsWith(`..${path.sep}`) ? path.join(currentRoot, relative) : file;
+    };
+    return { completion_path: path.join(currentRoot, "completion.json"), required_artifacts: original.required_artifacts ?? [], inputs: original.inputs ?? [], artifacts: artifacts.map((artifact) => ({ ...artifact, path: relocate(artifact.path) })) };
 }
 export function workspaceFingerprint(root) { return workspaceState(root).fingerprint; }
-export function workspaceChangedPaths(root) { const status = spawnSync("git", ["status", "--porcelain=v1", "-z", "--untracked-files=all"], { cwd: root, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 }); if (status.status !== 0)
-    return null; return status.stdout.split("\0").filter(Boolean).map((entry) => entry.slice(3)).filter(Boolean).sort(); }
-function deduplicate(checks, commands) { const groups = new Map(); checks.forEach((check, index) => { const artifacts = [...(check.required_artifacts ?? [])].sort(); const ports = [...(check.ports ?? [])].sort(); const key = JSON.stringify([check.run_at, commands[index], artifacts, ports]); const current = groups.get(key); if (current)
-    current.declarations.push(check);
-else
-    groups.set(key, { gate: check.run_at, command: commands[index], declarations: [check], requiredArtifacts: artifacts, ports }); }); return [...groups.values()]; }
-function workspaceState(root, ignoredRoots = []) { const git = spawnSync("git", ["ls-files", "-co", "--exclude-standard", "-z"], { cwd: root, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 }); const ignored = ignoredRoots.map((entry) => path.resolve(entry)); const listing = (git.status === 0 ? git.stdout.split("\0").filter(Boolean).sort() : listFiles(root)).filter((relative) => { const file = path.resolve(root, relative); return !ignored.some((ignoredRoot) => file === ignoredRoot || file.startsWith(`${ignoredRoot}${path.sep}`)); }); const files = new Map(); const hash = crypto.createHash("sha256"); for (const relative of listing) {
-    const file = path.join(root, relative);
-    const content = fs.existsSync(file) && fs.statSync(file).isFile() ? fs.readFileSync(file) : Buffer.from("<missing>");
-    const digest = crypto.createHash("sha256").update(content).digest("hex");
-    files.set(relative, digest);
-    hash.update(relative).update("\0").update(digest).update("\0");
-} return { fingerprint: hash.digest("hex"), files }; }
+/** One NUL-aware source of truth for paths differing from HEAD. Rename/copy
+ * records carry a second path; retain both because the old side is a deletion. */
+export function workspaceChangedPaths(root) {
+    const status = spawnSync("git", ["status", "--porcelain=v1", "-z", "--untracked-files=all"], { cwd: root, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+    // A workspace can be intentionally gitless. Keep the same conservative
+    // file inventory used for fingerprints instead of making result validation
+    // fail before the work contract can report its actual error.
+    if (status.status === 128 && /not a git repository|outside a repository/i.test(status.stderr ?? ""))
+        return listFiles(root);
+    if (status.status !== 0 || status.error)
+        throw new AppError("workspace_status_failed", "Could not determine changed workspace paths", 1, { workspace_root: root, stderr: status.stderr || null, cause: status.error?.message ?? null });
+    const records = status.stdout.split("\0");
+    const paths = [];
+    for (let index = 0; index < records.length; index += 1) {
+        const record = records[index];
+        if (!record)
+            continue;
+        if (record.length < 4 || record[2] !== " ")
+            throw new AppError("workspace_status_invalid", "Git returned an invalid porcelain-v1 record", 1, { workspace_root: root, record });
+        paths.push(normalizeWorkspacePath(root, record.slice(3)));
+        if (record[0] === "R" || record[0] === "C" || record[1] === "R" || record[1] === "C") {
+            const prior = records[++index];
+            if (!prior)
+                throw new AppError("workspace_status_invalid", "Git rename/copy record is missing its second path", 1, { workspace_root: root, record });
+            paths.push(normalizeWorkspacePath(root, prior));
+        }
+    }
+    return [...new Set(paths)].sort();
+}
+/** Ignored machine state cannot be reported as a product change. Tracked paths
+ * remain eligible regardless of their directory name. */
+export function ignoredWorkspacePaths(root, paths) {
+    const normalized = [...new Set(paths.map((item) => normalizeWorkspacePath(root, item)))];
+    if (!normalized.length)
+        return [];
+    const status = spawnSync("git", ["check-ignore", "-z", "--stdin"], { cwd: root, encoding: "utf8", input: `${normalized.join("\0")}\0`, maxBuffer: 64 * 1024 * 1024 });
+    // Projects may intentionally run without Git (the flow supports a local
+    // workspace identity independently from version control). In that case
+    // there is no ignore database to consult; a declared path is a product
+    // path, not an infrastructure path. Other Git failures remain fail-closed.
+    if (status.status === 128 && /not a git repository|outside a repository/i.test(status.stderr ?? ""))
+        return [];
+    if (![0, 1].includes(status.status ?? -1) || status.error)
+        throw new AppError("workspace_ignore_check_failed", "Could not classify reported workspace paths", 1, { workspace_root: root, stderr: status.stderr || null, cause: status.error?.message ?? null });
+    return [...new Set(status.stdout.split("\0").filter(Boolean).map((item) => normalizeWorkspacePath(root, item)))].sort();
+}
+export function normalizeWorkspacePath(root, value) {
+    if (typeof value !== "string" || !value || value.includes("\0") || path.isAbsolute(value))
+        throw new AppError("workspace_path_invalid", "Workspace path must be a non-empty relative path", 2, { path: value });
+    const resolvedRoot = path.resolve(root);
+    const resolved = path.resolve(resolvedRoot, value);
+    const relative = path.relative(resolvedRoot, resolved);
+    if (!relative || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative))
+        throw new AppError("workspace_path_invalid", "Workspace path escapes its root", 2, { path: value, workspace_root: root });
+    return relative.split(path.sep).join("/");
+}
+function deduplicate(checks, commands) {
+    const groups = new Map();
+    checks.forEach((check, index) => {
+        const artifacts = [...(check.required_artifacts ?? [])].sort(), ports = [...(check.ports ?? [])].sort(), inputs = normalizedInputs(check.inputs ?? []);
+        const reusable = check.reuse === "deterministic";
+        // Stage labels identify obligations, not different processes in this gate.
+        // Cross-invocation reuse still requires the explicit deterministic contract.
+        const key = JSON.stringify([commands[index], artifacts, ports, inputs, reusable]);
+        const current = groups.get(key);
+        if (current)
+            current.declarations.push(check);
+        else
+            groups.set(key, { gate: check.run_at, command: commands[index], declarations: [check], requiredArtifacts: artifacts, ports, inputs, reusable });
+    });
+    return [...groups.values()].map(group => ({ ...group, gate: [...group.declarations].map(check => check.run_at).sort()[0], declarations: [...group.declarations].sort((left, right) => checkRef(left).localeCompare(checkRef(right))) }));
+}
+function workspaceState(root, ignoredRoots = []) {
+    const git = spawnSync("git", ["ls-files", "-co", "--exclude-standard", "-z"], { cwd: root, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+    const ignored = ignoredRoots.map(entry => path.resolve(entry));
+    const listing = [...new Set(git.status === 0 ? git.stdout.split("\0").filter(Boolean) : listFiles(root))].sort();
+    const files = new Map(), hash = crypto.createHash("sha256");
+    for (const relative of listing) {
+        const file = path.resolve(root, relative);
+        if (ignored.some(ignoredRoot => file === ignoredRoot || file.startsWith(`${ignoredRoot}${path.sep}`)))
+            continue;
+        // Deleted tracked paths are absent content, both before and after commit.
+        // Do not mask other IO errors as an unchanged workspace.
+        let stat;
+        try {
+            stat = fs.lstatSync(file);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                continue;
+            throw error;
+        }
+        const content = stat.isSymbolicLink() ? Buffer.from(`symlink\0${fs.readlinkSync(file)}`) : stat.isFile() ? fs.readFileSync(file) : Buffer.from("<directory>");
+        const digest = crypto.createHash("sha256").update(content).digest("hex");
+        files.set(relative, digest);
+        hash.update(relative).update("\0").update(digest).update("\0");
+    }
+    return { fingerprint: hash.digest("hex"), files };
+}
+function workspaceInputFingerprint(root, files, inputs, ignoredRoots) {
+    const selected = new Map(inputs.length === 0 || inputs.includes(".") ? files : []);
+    for (const [file, digest] of explicitInputFiles(root, inputs.filter(input => input !== "."), ignoredRoots))
+        selected.set(file, digest);
+    const hash = crypto.createHash("sha256");
+    for (const [file, digest] of [...selected].sort(([left], [right]) => left.localeCompare(right)))
+        hash.update(file).update("\0").update(digest).update("\0");
+    return hash.digest("hex");
+}
 function changedPaths(before, after) { return [...new Set([...before.keys(), ...after.keys()])].filter((key) => before.get(key) !== after.get(key)).sort(); }
 function checkRef(check) { return check.canonical_ref ?? check.id; }
+function assertConsistentDeclarations(checks, commands) {
+    const seen = new Map();
+    for (const [index, check] of checks.entries()) {
+        const contract = JSON.stringify([check.run_at, commands[index], [...(check.required_artifacts ?? [])].sort(), [...(check.ports ?? [])].sort(), normalizedInputs(check.inputs ?? []), check.reuse ?? null]);
+        const ref = checkRef(check), prior = seen.get(ref);
+        if (prior && prior !== contract)
+            throw new AppError("check_declaration_conflict", "The same check reference has conflicting execution definitions", 2, { check_ref: ref });
+        seen.set(ref, contract);
+    }
+}
+function environmentFingerprint(workspaceRoot) {
+    const environment = codeExecutionEnvironment(workspaceRoot);
+    return crypto.createHash("sha256").update(JSON.stringify(Object.entries(environment).filter(([, value]) => value !== undefined).sort(([left], [right]) => left.localeCompare(right)))).digest("hex");
+}
+function acquireWorkspaceGate(context, input) {
+    const operationId = workspaceOperationId(input.workspaceRoot);
+    const active = managedProcessStatus(context).find(item => item.operation_id === operationId && ["starting", "running", "stopping"].includes(item.state));
+    if (active)
+        throw new AppError("check_in_progress", "The workspace is owned by another bootstrap or check; observe it before starting a new check", 1, { process_id: active.id, operation_id: operationId });
+    return registerManagedProcess(context, { kind: "workspace-gate", ownerPid: process.pid, ownerId: `workspace-gate:${crypto.randomUUID()}`, operationId, uniqueActiveOperation: true, projectId: input.projectId, runId: input.runId, metadata: { workspace_root: input.workspaceRoot, role: "check_gate" } });
+}
+export function reconcileWorkspaceOwnership(context, workspaceRoot) {
+    const operationId = workspaceOperationId(workspaceRoot);
+    const active = managedProcessStatus(context).filter(item => item.operation_id === operationId && ["starting", "running", "stopping", "orphaned"].includes(item.state));
+    if (active.some(item => processTreeIsAlive(item) || managedOwnerIsAlive(item) !== false))
+        return;
+    // Registry IDs are host-wide, whereas receipts belong to one runtime DB.
+    // An unknown/foreign home must not be settled against this client's rows.
+    if (active.some(item => managedProcessRuntimeHome(item, context) !== context.ddFlowHome))
+        return;
+    for (const child of active.filter(item => item.kind !== "workspace-gate")) {
+        if (child.kind !== "check" || !child.project_id || !child.run_id || !child.check_id)
+            return;
+        const run = context.db.get("SELECT run_root FROM runs WHERE project_id = ? AND id = ?", [child.project_id, child.run_id]);
+        if (!run?.run_root || !context.db.get("SELECT 1 FROM check_receipts WHERE id = ? AND project_id = ? AND run_id = ?", [child.check_id, child.project_id, child.run_id]))
+            return;
+        reconcileUnfinishedChecks(context, { projectId: child.project_id, runId: child.run_id, workspaceRoot, runHome: run.run_root, receiptId: child.check_id });
+        // A crash may occur after receipt settlement but before registry settlement.
+        const current = managedProcessStatus(context).find(item => item.id === child.id);
+        if (!current || current.lease_token !== child.lease_token)
+            return;
+        if (!["stopped", "failed"].includes(current.state) && !finishManagedProcess(context, { id: child.id, leaseToken: child.lease_token, state: "stopped", reason: "workspace_check_owner_reconciled" }))
+            return;
+    }
+    for (const gate of active.filter(item => item.kind === "workspace-gate"))
+        finishManagedProcess(context, { id: gate.id, leaseToken: gate.lease_token, state: "stopped", reason: "workspace_gate_owner_reconciled" });
+}
+function normalizedInputs(inputs) { for (const input of inputs)
+    validateCheckInputSyntax(input); return [...new Set(inputs.map((input) => { const normalized = path.posix.normalize(input.replaceAll("\\", "/")).replace(/^\.\/$/, ""); return normalized === "" || normalized === "." ? "." : normalized.replace(/\/$/, ""); }))].sort(); }
+function validateCheckInputs(workspaceRoot, inputs) { const root = fs.realpathSync.native(workspaceRoot); for (const input of normalizedInputs(inputs)) {
+    if (input === ".git" || input.startsWith(".git/"))
+        throw new AppError("invalid_check_input", "Check inputs cannot include Git internals", 2, { input });
+    const candidate = path.resolve(workspaceRoot, input);
+    if (candidate !== workspaceRoot && !candidate.startsWith(`${workspaceRoot}${path.sep}`))
+        throw new AppError("invalid_check_input", "Check inputs must stay within the workspace", 2, { input });
+    if (fs.existsSync(candidate))
+        validateInputTree(root, candidate, input, new Set());
+    else
+        validateMissingInputParent(root, candidate, input);
+} }
+function validateCheckInputSyntax(input) { if (typeof input !== "string" || !input.trim() || path.isAbsolute(input) || input.split(/[\\/]/).includes(".."))
+    throw new AppError("invalid_check_input", "Check inputs must be non-empty relative workspace paths", 2, { input }); }
+function validateMissingInputParent(root, candidate, input) { let parent = candidate; while (!fs.existsSync(parent))
+    parent = path.dirname(parent); const resolved = fs.realpathSync.native(parent); if (resolved !== root && !resolved.startsWith(`${root}${path.sep}`))
+    throw new AppError("invalid_check_input", "Check input parent symlink escapes the workspace", 2, { input }); }
+function validateInputTree(root, candidate, input, seen) {
+    const resolved = fs.realpathSync.native(candidate);
+    if (resolved !== root && !resolved.startsWith(`${root}${path.sep}`))
+        throw new AppError("invalid_check_input", "Check input symlink escapes the workspace", 2, { input });
+    if (seen.has(resolved))
+        throw new AppError("invalid_check_input", "Check input contains a symbolic-link cycle", 2, { input });
+    seen.add(resolved);
+    const stat = fs.statSync(candidate);
+    if (stat.isDirectory())
+        for (const entry of fs.readdirSync(candidate))
+            validateInputTree(root, path.join(candidate, entry), input, seen);
+    seen.delete(resolved);
+}
+function explicitInputFiles(root, inputs, ignoredRoots) {
+    const rootReal = fs.realpathSync.native(root), ignored = ignoredRoots.map(entry => path.resolve(entry)), result = new Map();
+    const visit = (file, relative, seen) => {
+        if (ignored.some(entry => file === entry || file.startsWith(`${entry}${path.sep}`)))
+            return;
+        if (!fs.existsSync(file)) {
+            result.set(relative, "<missing>");
+            return;
+        }
+        const resolved = fs.realpathSync.native(file);
+        if (resolved !== rootReal && !resolved.startsWith(`${rootReal}${path.sep}`))
+            throw new AppError("invalid_check_input", "Check input symlink escapes the workspace", 2, { input: relative });
+        if (seen.has(resolved))
+            throw new AppError("invalid_check_input", "Check input contains a symbolic-link cycle", 2, { input: relative });
+        const stat = fs.statSync(file);
+        if (stat.isDirectory()) {
+            seen.add(resolved);
+            for (const entry of fs.readdirSync(file).sort())
+                visit(path.join(file, entry), path.posix.join(relative, entry), seen);
+            seen.delete(resolved);
+        }
+        else if (stat.isFile())
+            result.set(relative, crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex"));
+    };
+    for (const input of inputs)
+        visit(path.resolve(root, input), input, new Set());
+    return [...result.entries()];
+}
+function checkInputHash(workspaceRoot, group, profileHash, inputFingerprint) { 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, profile_hash: profileHash, environment: environmentFingerprint(workspaceRoot), input_fingerprint: inputFingerprint })).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: group.requiredArtifacts, inputs: group.inputs }; }
+function latestApplicableReceipt(context, input) { const candidates = checkReceipts(context, { projectId: input.projectId, runId: input.runId }).filter((receipt) => receipt.input_hash === input.inputHash && receipt.profile_hash === input.profileHash); return candidates.at(-1) ?? null; }
+export function checkReceiptEvidenceValid(receipt) { if (receipt.status !== "passed" || receipt.exit_code !== 0 || receipt.before_fingerprint !== receipt.after_fingerprint || !fs.existsSync(receipt.completion_path) || readCompletion(receipt.completion_path)?.exit_code !== 0)
+    return false; const stored = readReceipt(receipt.receipt_path); if (!stored || stored.status !== "passed" || stored.input_hash !== receipt.input_hash || stored.profile_hash !== receipt.profile_hash)
+    return false; const artifacts = collectCheckArtifacts(path.join(path.dirname(receipt.receipt_path), "artifacts"), stored.required_artifacts ?? []); return artifacts.complete && JSON.stringify(artifacts.items) === JSON.stringify(stored.artifacts ?? []); }
 function parseArray(value, fallback) { try {
     const parsed = JSON.parse(value);
     return Array.isArray(parsed) && parsed.every((item) => typeof item === "string") ? parsed : fallback;
@@ -245,8 +637,14 @@ catch {
     return fallback;
 } }
 function isStringRecord(value) { return Boolean(value) && typeof value === "object" && !Array.isArray(value) && Object.values(value).every((item) => typeof item === "string" && item.trim().length > 0); }
-function isGateRecord(value) { return Boolean(value) && typeof value === "object" && !Array.isArray(value) && Object.entries(value).every(([gate, aliases]) => ["work", "code", "readiness", "merge", "release", "external"].includes(gate) && Array.isArray(aliases) && aliases.every((item) => typeof item === "string" && item.startsWith("@check/"))); }
+function isGateRecord(value) { return Boolean(value) && typeof value === "object" && !Array.isArray(value) && Object.entries(value).every(([gate, aliases]) => ["work", "code", "readiness", "merge", "release"].includes(gate) && Array.isArray(aliases) && aliases.every((item) => typeof item === "string" && item.startsWith("@check/"))); }
 function isPortAliasRecord(value) { return value === undefined || (Boolean(value) && typeof value === "object" && !Array.isArray(value) && Object.entries(value).every(([alias, ports]) => alias.startsWith("@check/") && Array.isArray(ports) && ports.length > 0 && new Set(ports).size === ports.length && ports.every((port) => typeof port === "string" && /^[A-Za-z][A-Za-z0-9_]*$/.test(port)))); }
+function isInputAliasRecord(workspaceRoot, value) { try {
+    return value === undefined || (Boolean(value) && typeof value === "object" && !Array.isArray(value) && Object.entries(value).every(([alias, inputs]) => alias.startsWith("@check/") && Array.isArray(inputs) && (validateCheckInputs(workspaceRoot, inputs), true)));
+}
+catch {
+    return false;
+} }
 function portEnvironment(ports) { return Object.fromEntries(Object.entries(ports).map(([name, value]) => [`DD_FLOW_PORT_${name.toUpperCase()}`, String(value)])); }
 function readReceiptResources(file) { try {
     const value = JSON.parse(fs.readFileSync(file, "utf8"));
@@ -255,50 +653,99 @@ function readReceiptResources(file) { try {
 catch {
     return { ports: {} };
 } }
-function collectRequiredArtifacts(root, required) { const missing = []; const items = []; for (const relative of required) {
-    if (path.isAbsolute(relative) || relative.split(/[\\/]/).includes(".."))
-        throw new AppError("invalid_evidence_path", "Required evidence paths must be relative to DD_FLOW_EVIDENCE_DIR", 2, { path: relative });
-    const file = path.join(root, relative);
-    if (!fs.existsSync(file) || !fs.statSync(file).isFile()) {
-        missing.push(relative);
-        continue;
+function collectCheckArtifacts(root, required) {
+    for (const relative of required) {
+        if (path.isAbsolute(relative) || relative.split(/[\\/]/).includes(".."))
+            throw new AppError("invalid_evidence_path", "Required evidence paths must be relative to DD_FLOW_EVIDENCE_DIR", 2, { path: relative });
     }
-    items.push({ path: relative, sha256: crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex") });
-} return { complete: missing.length === 0, missing, items }; }
+    // Required paths are minimum obligations; retain all explicit check evidence.
+    // Never follow symlinks, including a replaced evidence root.
+    const items = [];
+    const visit = (directory) => {
+        for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+            const file = path.join(directory, entry.name);
+            if (entry.isDirectory())
+                visit(file);
+            else if (entry.isFile())
+                items.push({ path: path.relative(root, file), sha256: crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex") });
+        }
+    };
+    if (fs.existsSync(root) && fs.lstatSync(root).isDirectory())
+        visit(root);
+    items.sort((a, b) => a.path.localeCompare(b.path));
+    const retained = new Set(items.map((item) => item.path));
+    const missing = required.filter((relative) => !retained.has(path.normalize(relative)));
+    return { complete: missing.length === 0, missing, items };
+}
 function listFiles(root, current = root) { return fs.readdirSync(current, { withFileTypes: true }).flatMap((entry) => { if ([".git", "node_modules"].includes(entry.name))
     return []; const absolute = path.join(current, entry.name); return entry.isDirectory() ? listFiles(root, absolute) : [path.relative(root, absolute)]; }).sort(); }
-function runCheck(command, cwd, environment, stdout, stderr, heartbeat, onSpawn, renewLease) { return new Promise((resolve) => { const started = Date.now(); const child = spawn("/bin/sh", ["-lc", checkShellScript()], { cwd, env: { ...environment, DD_FLOW_CHECK_COMMAND: command }, stdio: ["ignore", stdout, stderr], detached: process.platform !== "win32" }); if (!child.pid) {
-    resolve({ exitCode: null, error: "check process did not provide a PID", aborted: true });
-    return;
-} try {
-    onSpawn(child.pid);
-}
-catch (error) {
-    terminateProcessGroup(child.pid, "SIGTERM");
-    resolve({ exitCode: null, error: error instanceof Error ? error.message : String(error), aborted: true });
-    return;
-} const inactivityMs = 15 * 60 * 1000; let timeout; const lastOutputSize = new Map(); const armInactivityTimeout = () => { if (timeout)
-    clearTimeout(timeout); timeout = setTimeout(() => { timedOut = true; terminateProcessGroup(child.pid, "SIGTERM"); escalation = setTimeout(() => terminateProcessGroup(child.pid, "SIGKILL"), 5_000); }, inactivityMs); }; const progress = setInterval(() => { const elapsed = Math.floor((Date.now() - started) / 1000); if (!renewLease()) {
-    error = "managed process lease lost";
-    timedOut = true;
-    terminateProcessGroup(child.pid, "SIGTERM");
-    return;
-} for (const file of [stdout, stderr]) {
-    try {
-        const size = fs.fstatSync(file).size, previous = lastOutputSize.get(file) ?? 0;
-        if (size > previous) {
-            lastOutputSize.set(file, size);
-            armInactivityTimeout();
+export function runCheck(command, cwd, environment, stdout, stderr, heartbeat, onSpawn, renewLease) {
+    return new Promise((resolve) => {
+        const started = Date.now();
+        const child = spawn("/bin/sh", ["-c", checkShellScript()], { cwd, env: { ...environment, DD_FLOW_CHECK_COMMAND: command }, stdio: ["pipe", stdout, stderr], detached: process.platform !== "win32" });
+        let error = null;
+        let stopping = false;
+        let progress;
+        let escalation;
+        const stop = (cause) => {
+            if (stopping)
+                return;
+            stopping = true;
+            error = cause instanceof Error ? cause.message : String(cause);
+            if (progress) {
+                clearInterval(progress);
+                progress = undefined;
+            }
+            if (child.pid) {
+                terminateProcessGroup(child.pid, "SIGTERM");
+                escalation = setTimeout(() => terminateProcessGroup(child.pid, "SIGKILL"), 5_000);
+            }
+        };
+        // Register handlers before checking pid or calling persistence callbacks.
+        // Failure is not completion until the spawned process has actually closed.
+        child.once("error", (value) => { error = value.message; });
+        child.stdin.on("error", stop);
+        child.once("close", (exitCode, signal) => {
+            if (progress)
+                clearInterval(progress);
+            if (escalation)
+                clearTimeout(escalation);
+            if (stopping)
+                terminateProcessGroup(child.pid, "SIGKILL");
+            resolve({ exitCode, error: error ?? (signal ? `terminated by ${signal}` : null), aborted: stopping || Boolean(signal) || Boolean(error) });
+        });
+        if (!child.pid) {
+            error = "check process did not provide a PID";
+            return;
         }
-    }
-    catch { /* terminal stream */ }
-} heartbeat(elapsed); }, 15_000); let timedOut = false; let error = null; let escalation; armInactivityTimeout(); child.once("error", (value) => { error = value.message; }); child.once("close", (exitCode, signal) => { clearInterval(progress); if (timeout)
-    clearTimeout(timeout); if (escalation)
-    clearTimeout(escalation); resolve({ exitCode, error: error ?? (timedOut ? "timed out after 900 seconds without process output" : signal ? `terminated by ${signal}` : null), aborted: timedOut || Boolean(signal) || Boolean(error) }); }); }); }
+        try {
+            onSpawn(child.pid);
+        }
+        catch (cause) {
+            stop(cause);
+            return;
+        }
+        child.stdin.end("admitted\n");
+        progress = setInterval(() => {
+            try {
+                if (!renewLease()) {
+                    stop("managed process lease lost");
+                    return;
+                }
+                heartbeat(Math.floor((Date.now() - started) / 1000));
+            }
+            catch (cause) {
+                stop(cause);
+            }
+        }, 15_000);
+    });
+}
 function checkShellScript() {
     return [
+        // The actual command cannot run before PID ownership and admission persist.
+        'IFS= read -r admission && [ "$admission" = admitted ] || exit 125',
         'completion="${DD_FLOW_CHECK_COMPLETION_FILE:-}"',
-        '/bin/sh -lc "$DD_FLOW_CHECK_COMMAND"',
+        '/bin/sh -c "$DD_FLOW_CHECK_COMMAND"',
         "code=$?",
         'if [ -n "$completion" ]; then temporary="$completion.tmp.$$"; printf \'{"exit_code":%s,"finished_at":"%s"}\\n\' "$code" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" > "$temporary" && mv "$temporary" "$completion"; fi',
         'exit "$code"'