@deksden-com/dd-flow-cli 0.9.0-beta.1 → 0.9.0-beta.10

package/dist/services/code-checks.js

@@ -3,7 +3,12 @@ import { spawn, spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { AppError } from "../shared/errors.js";
+import { confirmManagedProcess, finishManagedProcess, heartbeatManagedProcess, managedProcessStatus, processIsAlive, registerManagedProcess, reservePorts } from "./managed-processes.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 readCodeCheckProfile(workspaceRoot) {
     const file = path.join(workspaceRoot, profileRelativePath);
@@ -11,14 +16,17 @@ export function readCodeCheckProfile(workspaceRoot) {
         return { profile: null, hash: null, file };
     const bytes = fs.readFileSync(file);
     const value = JSON.parse(bytes.toString("utf8"));
-    if (value.schema_id !== "dd-flow/code-check-profile@5")
-        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@5" });
-    if (!isStringRecord(value.aliases) || !isStringRecord(value.require_alias_for) || !isGateRecord(value.mandatory_by_gate))
-        throw new AppError("invalid_code_check_profile", "CODE check profile aliases, require_alias_for and mandatory_by_gate are invalid", 2, { file });
+    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 });
     for (const [gate, aliases] of Object.entries(value.mandatory_by_gate))
         for (const alias of aliases ?? [])
             if (!value.aliases[alias])
                 throw new AppError("invalid_code_check_profile", "A mandatory gate references an unknown alias", 2, { file, gate, alias });
+    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 });
     return { profile: value, hash: crypto.createHash("sha256").update(bytes).digest("hex"), file };
 }
 export function validateCodeCheckCommands(workspaceRoot, commands) {
@@ -33,14 +41,20 @@ export function validateCodeCheckCommands(workspaceRoot, commands) {
         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); const { profile } = readCodeCheckProfile(workspaceRoot); return validated.map((command) => command.startsWith("@check/") ? profile.aliases[command].replaceAll("{run_id}", runId) : command); }
+export function resolveCodeCheckCommands(workspaceRoot, runId, commands) {
+    const validated = validateCodeCheckCommands(workspaceRoot, commands);
+    const { profile } = readCodeCheckProfile(workspaceRoot);
+    // `{run_id}` is a declaration-level placeholder, not an alias feature.
+    // Plans may use it in a focused raw command as well as in project aliases.
+    return validated.map((command) => (command.startsWith("@check/") ? profile.aliases[command] : command).replaceAll("{run_id}", runId));
+}
 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" }; });
+    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] } : {}) }; });
 }
 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"); }
-export function finalCodeCheckDeclarations(workspaceRoot, declared) { return effectiveCheckDeclarations(workspaceRoot, declared, ["code", "readiness"]); }
+export function finalCodeCheckDeclarations(workspaceRoot, declared) { return effectiveCheckDeclarations(workspaceRoot, declared, ["work", "code", "readiness"]); }
 export function checksForRunAt(checks, runAt) { return checks.filter((check) => check.run_at === runAt); }
 export function validateCheckPlacement(workspaceRoot, checks) { const { profile } = readCodeCheckProfile(workspaceRoot); const aggregateCommands = new Set(projectPolicyCheckDeclarations(workspaceRoot, "code").flatMap((check) => [check.command, profile?.aliases[check.command] ?? check.command])); for (const check of checks)
     if (check.run_at === "work" && aggregateCommands.has(check.command))
@@ -64,64 +78,157 @@ export function validateCheckDeclaration(workspaceRoot, check) {
         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 });
 }
 export async function runCodeChecks(context, input) {
+    reconcileUnfinishedChecks(context, input);
     for (const check of input.checks)
         validateCheckDeclaration(input.workspaceRoot, check);
-    const { hash: profileHash } = readCodeCheckProfile(input.workspaceRoot);
-    const resolved = resolveCodeCheckCommands(input.workspaceRoot, input.runId, input.checks.map((check) => check.command));
-    const groups = deduplicate(input.checks, resolved);
+    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 }; });
+    const resolved = resolveCodeCheckCommands(input.workspaceRoot, input.runId, checks.map((check) => check.command));
+    const groups = deduplicate(checks, resolved);
     const receipts = [];
     for (let index = 0; index < groups.length; index += 1) {
         const group = groups[index];
-        const ordinal = (context.db.get("SELECT COUNT(*) AS count FROM check_receipts WHERE work_id IS ? AND run_id = ?", [input.workId ?? null, input.runId])?.count ?? 0) + 1;
-        const localId = `RCP-${String(ordinal).padStart(3, "0")}`;
-        const id = `${input.workId ?? input.runId}/${localId}`;
-        const directory = path.join(input.runHome, input.artifactDir ?? "05-code", "checks", localId);
-        const evidenceDir = path.join(directory, "artifacts");
-        fs.mkdirSync(evidenceDir, { recursive: true });
-        const stdoutPath = path.join(directory, "stdout.log");
-        const stderrPath = path.join(directory, "stderr.log");
-        const receiptPath = path.join(directory, "receipt.json");
-        const before = workspaceState(input.workspaceRoot);
-        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 })).digest("hex");
-        const epoch = crypto.createHash("sha256").update(`${group.gate}\0${before.fingerprint}`).digest("hex");
+        const before = workspaceState(input.workspaceRoot, [input.runHome]);
         const startedAt = context.now();
-        input.progress?.(`check ${index + 1}/${groups.length} started: ${group.command}`);
-        const stdout = fs.createWriteStream(stdoutPath);
-        const stderr = fs.createWriteStream(stderrPath);
-        const result = await runCheck(group.command, input.workspaceRoot, { ...codeExecutionEnvironment(input.workspaceRoot), DD_FLOW_EVIDENCE_DIR: evidenceDir }, stdout, stderr, (elapsed) => input.progress?.(`check ${index + 1}/${groups.length} still running (${elapsed}s): ${group.command}`));
-        await Promise.all([closeStream(stdout), closeStream(stderr)]);
-        const after = workspaceState(input.workspaceRoot);
+        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 epoch = crypto.createHash("sha256").update(`${group.gate}\0${before.fingerprint}`).digest("hex");
+        const reserved = reserveReceipt(context, { ...input, group, before, profileHash, inputHash, epoch, startedAt });
+        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 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}`);
+            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 }));
+            }
+            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 });
+            }
+        }
+        catch (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);
-        if (!artifacts.complete)
-            fs.appendFileSync(stderrPath, `\nmissing required evidence artifacts: ${artifacts.missing.join(", ")}\n`);
-        if (result.error)
-            fs.appendFileSync(stderrPath, `\n${result.error}\n`);
-        if (mutationPaths.length)
-            fs.appendFileSync(stderrPath, `\ncheck mutated project workspace: ${mutationPaths.join(", ")}\n`);
+        if (fs.existsSync(stderrPath)) {
+            if (!artifacts.complete)
+                fs.appendFileSync(stderrPath, `\nmissing required evidence artifacts: ${artifacts.missing.join(", ")}\n`);
+            if (result.error)
+                fs.appendFileSync(stderrPath, `\n${result.error}\n`);
+            if (mutationPaths.length)
+                fs.appendFileSync(stderrPath, `\ncheck mutated project workspace: ${mutationPaths.join(", ")}\n`);
+        }
         const status = result.aborted ? "aborted" : result.exitCode === 0 && !result.error && artifacts.complete && mutationPaths.length === 0 ? "passed" : "failed";
-        const receipt = { id, local_id: localId, declaration_id: group.declarations[0].id, check_refs: group.declarations.map(checkRef), gate: group.gate, scope: input.scope, work_id: input.workId ?? null, command: group.command, input_hash: inputHash, verification_epoch: epoch, status, exit_code: result.exitCode, stdout_path: stdoutPath, stderr_path: stderrPath, receipt_path: receiptPath, workspace_fingerprint: before.fingerprint, before_fingerprint: before.fingerprint, after_fingerprint: after.fingerprint, profile_hash: profileHash, mutation_paths: mutationPaths, artifacts: artifacts.items, started_at: startedAt, finished_at: context.now() };
-        fs.writeFileSync(receiptPath, `${JSON.stringify(receipt, null, 2)}\n`);
-        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 (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)", [id, input.projectId, input.runId, input.workId ?? null, input.scope, receipt.declaration_id, JSON.stringify(receipt.check_refs), receipt.gate, receipt.command, receipt.input_hash, receipt.verification_epoch, receipt.status, receipt.exit_code, stdoutPath, stderrPath, receiptPath, receipt.workspace_fingerprint, receipt.before_fingerprint, receipt.after_fingerprint, receipt.profile_hash, JSON.stringify(receipt.mutation_paths), JSON.stringify(receipt.artifacts), receipt.started_at, receipt.finished_at]);
+        const receipt = receiptFor({ ...reserved, resources, result, status, after, mutationPaths, artifacts: artifacts.items });
+        context.db.run("UPDATE check_receipts SET status = ?, exit_code = ?, after_fingerprint = ?, mutation_paths_json = ?, artifacts_json = ?, finished_at = ? WHERE id = ? AND project_id = ? AND status = 'running'", [receipt.status, receipt.exit_code, receipt.after_fingerprint, JSON.stringify(receipt.mutation_paths), JSON.stringify(receipt.artifacts), receipt.finished_at, id, input.projectId]);
+        writeReceipt(receiptPath, receipt);
         receipts.push(receipt);
         input.progress?.(`check ${index + 1}/${groups.length} ${status}: ${group.command}`);
     }
     return receipts;
 }
+/**
+ * A check receipt is durable even when its invoking CLI disappears.  We never
+ * guess that an orphan passed: a live process blocks a second execution, and
+ * 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'";
+    const params = input.workId ? [input.projectId, input.runId, input.workId] : [input.projectId, input.runId];
+    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 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))) {
+            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 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;
+        const finishedAt = completion?.finished_at ?? context.now();
+        context.db.run("UPDATE check_receipts SET status = ?, exit_code = ?, after_fingerprint = ?, mutation_paths_json = ?, artifacts_json = ?, finished_at = ? WHERE id = ? AND project_id = ? AND status = 'running'", [status, exitCode, after.fingerprint, JSON.stringify(workspaceUnchanged ? [] : ["<workspace changed while detached check ran>"]), JSON.stringify(artifacts.items), finishedAt, pendingReceipt.id, input.projectId]);
+        if (process)
+            finishManagedProcess(context, { id: process.id, leaseToken: process.lease_token, state: status === "passed" ? "stopped" : "failed", reason: status === "passed" ? "reconciled_completion" : completion === null ? "completion_marker_missing" : "reconciled_check_failed" });
+        if (receipt) {
+            const repaired = { ...receipt, completion_path: receipt.completion_path || path.join(path.dirname(pendingReceipt.receipt_path), "completion.json"), required_artifacts: receipt.required_artifacts ?? [], status, exit_code: exitCode, after_fingerprint: after.fingerprint, mutation_paths: workspaceUnchanged ? [] : ["<workspace changed while detached check ran>"], artifacts: artifacts.items, finished_at: finishedAt };
+            writeReceipt(pendingReceipt.receipt_path, repaired);
+            reconciled.push(repaired);
+        }
+    }
+    return reconciled;
+}
+function reserveReceipt(context, input) {
+    context.db.exec("BEGIN IMMEDIATE");
+    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}`;
+        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]);
+        context.db.exec("COMMIT");
+        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 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"));
+}
+catch {
+    return null;
+} }
+function readCompletion(file) { try {
+    const value = JSON.parse(fs.readFileSync(file, "utf8"));
+    const done = value;
+    return value && typeof value === "object" && Number.isInteger(done.exit_code) ? { exit_code: Number(done.exit_code), finished_at: typeof done.finished_at === "string" && Number.isFinite(Date.parse(done.finished_at)) ? done.finished_at : null } : null;
+}
+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); }
 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) }));
+    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) }));
 }
 export function workspaceFingerprint(root) { return workspaceState(root).fingerprint; }
-function deduplicate(checks, commands) { const groups = new Map(); checks.forEach((check, index) => { const artifacts = [...(check.required_artifacts ?? [])].sort(); const key = JSON.stringify([check.run_at, commands[index], artifacts]); const current = groups.get(key); if (current)
+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 }); }); return [...groups.values()]; }
-function workspaceState(root) { const git = spawnSync("git", ["ls-files", "-co", "--exclude-standard", "-z"], { cwd: root, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 }); const listing = git.status === 0 ? git.stdout.split("\0").filter(Boolean).sort() : listFiles(root); const files = new Map(); const hash = crypto.createHash("sha256"); for (const relative of listing) {
+    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");
@@ -139,6 +246,15 @@ catch {
 } }
 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 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 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"));
+    return { ports: value.resources?.ports ?? {} };
+}
+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 });
@@ -151,11 +267,45 @@ function collectRequiredArtifacts(root, required) { const missing = []; const it
 } 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) { return new Promise((resolve) => { const started = Date.now(); const child = spawn("/bin/sh", ["-lc", command], { cwd, env: environment, stdio: ["ignore", "pipe", "pipe"], detached: process.platform !== "win32" }); child.stdout.pipe(stdout, { end: false }); child.stderr.pipe(stderr, { end: false }); const progress = setInterval(() => heartbeat(Math.floor((Date.now() - started) / 1000)), 15_000); let timedOut = false; let error = null; let escalation; const timeout = setTimeout(() => { timedOut = true; terminateProcessGroup(child.pid, "SIGTERM"); escalation = setTimeout(() => terminateProcessGroup(child.pid, "SIGKILL"), 5_000); }, 15 * 60 * 1000); child.once("error", (value) => { error = value.message; }); child.once("close", (exitCode, signal) => { clearInterval(progress); clearTimeout(timeout); if (escalation)
-    clearTimeout(escalation); resolve({ exitCode, error: error ?? (timedOut ? "timed out after 900 seconds" : signal ? `terminated by ${signal}` : null), aborted: timedOut || Boolean(signal) || Boolean(error) }); }); }); }
+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();
+        }
+    }
+    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) }); }); }); }
+function checkShellScript() {
+    return [
+        'completion="${DD_FLOW_CHECK_COMPLETION_FILE:-}"',
+        '/bin/sh -lc "$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"'
+    ].join("\n");
+}
 function terminateProcessGroup(pid, signal) { if (!pid)
     return; try {
     process.kill(process.platform === "win32" ? pid : -pid, signal);
 }
 catch { /* already exited */ } }
-function closeStream(stream) { return new Promise((resolve, reject) => stream.end((error) => error ? reject(error) : resolve())); }

package/dist/services/engines.js

@@ -12,7 +12,7 @@ import { requireProtocol } from "./protocols.js";
 import { resolveCanonRootBeforeContext } from "./canon.js";
 import { appendAudit } from "./audit.js";
 import { findProjectByRoot } from "./projects.js";
-import { allRunEngineBindings, findRunHome, readRunEngineBinding, runEngineBindingSchemaId, writeRunEngineBinding } from "./run-engine-bindings.js";
+import { allRunEngineBindings, locateRunRoot, readRunEngineBinding, runEngineBindingSchemaId, writeRunEngineBinding } from "./run-engine-bindings.js";
 export const engineManifestSchemaId = "dd-flow/engine-manifest@1";
 const routerNativeFamilies = new Set(["engine", "version", "schema"]);
 const sourceFile = fileURLToPath(import.meta.url);
@@ -182,7 +182,7 @@ export function routeArgsThroughEngine(context, args, io, stdin, env, resolvedPr
 }
 export function bindRunEngine(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
-    const located = findRunHome(context.ddFlowHome, projectRoot, input.runId);
+    const located = locateRunRoot(context.db, projectRoot, input.runId);
     if (!located)
         throw new AppError("not_found", `RUN is not registered in router storage: ${input.runId}`, 1, { run_id: input.runId, project_root: projectRoot });
     const existing = readRunEngineBinding(located.binding_path, { allowMissing: true });
@@ -250,13 +250,13 @@ export function bindCurrentEngineToRun(context, input) {
         engine: engineIdentity(manifest),
         probe: { status: "not_required", command: null }
     };
-    return writeRunEngineBinding(path.join(input.runHome, "engine-binding.json"), binding).binding;
+    return writeRunEngineBinding(path.join(input.runRoot, "engine-binding.json"), binding).binding;
 }
 function boundRunEngineForArgs(context, args, projectRoot) {
     const runId = runIdForArgs(args);
     if (!runId || !projectRoot)
         return null;
-    const located = findRunHome(context.ddFlowHome, projectRoot, runId);
+    const located = locateRunRoot(context.db, projectRoot, runId);
     if (!located)
         return null;
     const binding = readRunEngineBinding(located.binding_path, { allowMissing: true });

package/dist/services/eval-snapshots.js

@@ -80,7 +80,10 @@ export function createEvalRunSnapshot(context, input) {
     fs.cpSync(context.ddFlowHome, path.join(output, "runtime"), {
         recursive: true,
         verbatimSymlinks: true,
-        filter: (source) => path.basename(source) !== "engines"
+        // Managed checkouts are restored from their Git bundle and workspace
+        // payload. Copying their .git indirection into runtime makes the snapshot
+        // dependent on the source machine's worktree metadata.
+        filter: (source) => !["engines", "checkouts"].includes(path.basename(source))
     });
     fs.cpSync(projectRoot, path.join(output, "project"), {
         recursive: true,
@@ -135,20 +138,22 @@ export function restoreEvalRunSnapshot(context, input) {
     clearProjectTree(projectRoot, false);
     restoreProjectGit(snapshot, manifest.project_git, projectRoot);
     replaceProjectTree(projectRoot, sourceProject);
-    const workspaceRoot = restoreWorkspace(snapshot, manifest, projectRoot, context.ddFlowHome);
     context.db.close?.();
     fs.rmSync(context.ddFlowHome, { recursive: true, force: true });
     fs.cpSync(sourceRuntime, context.ddFlowHome, { recursive: true, verbatimSymlinks: true });
+    const workspaceRoot = restoreWorkspace(snapshot, manifest, projectRoot, context.ddFlowHome);
     // The dispatch context was intentionally closed before replacing db.sqlite.
     // A fresh process owns all subsequent normal commands.
     const restored = createContext({ ...context.env, DD_FLOW_HOME: context.ddFlowHome });
     try {
         rebaseRuntime(restored, manifest.project_root, projectRoot, sourceWorkspaceRoot(manifest), workspaceRoot, manifest.dd_flow_home, context.ddFlowHome);
         registerProject(restored, { root: projectRoot });
-        const project = requireProjectByRoot(restored, projectRoot);
+        requireProjectByRoot(restored, projectRoot);
         const status = getFlowRunStatus(restored, { projectRoot, runId: manifest.run_id });
         assertStageEntry(status.index.stage_runs ?? [], manifest.stage_entry);
-        const runHome = status.run.run_home_path ?? path.join(context.ddFlowHome, "projects", project.id, "runs", manifest.run_id);
+        if (!status.run.run_root)
+            throw new AppError("runtime_missing", "Restored RUN has no artifact root", 1, { run_id: manifest.run_id });
+        const runHome = status.run.run_root;
         return {
             ok: true,
             schema_id: "dd-flow/eval-run-restore@1",
@@ -179,7 +184,7 @@ export function prepareVnextSpecifyRun(context, input) {
         slug: input.slug,
         nextAction: "start_specify"
     });
-    return { ok: true, run_id: started.run.id, run_home: started.run.run_home_path, target_stage: "specify" };
+    return { ok: true, run_id: started.run.id, run_root: started.run.run_root, target_stage: "specify" };
 }
 function assertDedicatedHome(context, projectId, runId) {
     const projects = context.db.get("SELECT COUNT(*) AS count FROM projects")?.count ?? 0;

package/dist/services/harness-config.js

@@ -0,0 +1,66 @@
+import fs from "node:fs";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+export function harnessConfigPath(ddFlowHome) {
+    return path.join(ddFlowHome, "harnesses.json");
+}
+export function harnessKey(value) {
+    const keys = {
+        codex: "codex-desktop", "codex-desktop": "codex-desktop",
+        zcode: "zcode-acp", "zcode-acp": "zcode-acp",
+        grok: "grok-acp", "grok-acp": "grok-acp",
+        agy: "antigravity-cli", "antigravity-cli": "antigravity-cli",
+        opencode: "opencode-server", "opencode-server": "opencode-server"
+    };
+    const resolved = keys[value];
+    if (!resolved)
+        throw new AppError("harness_config_invalid", `Unsupported harness: ${value}`, 2, { harness: value });
+    return resolved;
+}
+export function loadHarnessConfig(ddFlowHome) {
+    const file = harnessConfigPath(ddFlowHome);
+    let value;
+    try {
+        value = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch (cause) {
+        throw new AppError("harness_config_missing", "Harness configuration is missing or invalid", 1, { path: file, cause: String(cause) });
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new AppError("harness_config_invalid", "Harness configuration must be an object", 2, { path: file });
+    const config = value;
+    if (config.schema_id !== "dd-flow/harness-config@1" || !config.harnesses || typeof config.harnesses !== "object" || Array.isArray(config.harnesses))
+        throw new AppError("harness_config_invalid", "Harness configuration has an unsupported schema", 2, { path: file });
+    for (const [name, entry] of Object.entries(config.harnesses)) {
+        harnessKey(name);
+        if (!entry || typeof entry !== "object" || Array.isArray(entry) || typeof entry.adapter_command !== "string" || typeof entry.runtime_command !== "string")
+            throw new AppError("harness_config_invalid", "Each harness requires adapter_command and runtime_command", 2, { path: file, harness: name });
+    }
+    return config;
+}
+export function resolveHarnessCommand(ddFlowHome, harness, command) {
+    const key = harnessKey(harness);
+    const entry = loadHarnessConfig(ddFlowHome).harnesses[key];
+    if (!entry)
+        throw new AppError("harness_config_missing", "Selected harness is not configured", 1, { path: harnessConfigPath(ddFlowHome), harness: key });
+    const value = command === "adapter" ? entry.adapter_command : entry.runtime_command;
+    if (!path.isAbsolute(value))
+        throw new AppError("harness_config_invalid", "Harness commands must be absolute paths", 2, { harness: key, command, value });
+    if (!fs.existsSync(value))
+        throw new AppError("harness_command_missing", "Configured harness command does not exist", 1, { harness: key, command, value });
+    return value;
+}
+/** The adapter interface is intentionally small; native binary flag names stay here,
+ * rather than leaking through MERGE orchestration or agent prompts. */
+export function harnessRuntimeArguments(ddFlowHome, harness) {
+    const key = harnessKey(harness);
+    const runtime = resolveHarnessCommand(ddFlowHome, key, "runtime");
+    const option = {
+        "codex-desktop": "--codex-bin",
+        "zcode-acp": "--zcode-acp-bin",
+        "grok-acp": "--grok-bin",
+        "antigravity-cli": "--agy-bin",
+        "opencode-server": "--opencode-bin"
+    };
+    return [option[key], runtime];
+}