@deksden-com/dd-flow-cli 0.9.0-beta.0 → 0.9.0-beta.7

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/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,10 +138,10 @@ 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 });

package/dist/services/hooks.js

@@ -7,6 +7,7 @@ import { AppError } from "../shared/errors.js";
 import { parseJsonObject } from "../shared/json.js";
 import { ensureDir, resolveProjectRoot } from "../storage/paths.js";
 import { appendAudit } from "./audit.js";
+import { nativeSessionIdentity, storageSessionId } from "./session-identity.js";
 import { commandHasOption, commandOption, commandPosition, parseLifecycleCommand, unwrapShellCommand } from "./lifecycle-command.js";
 import { registerProject, requireProjectByRoot } from "./projects.js";
 import { activeFlowSessionsForProject, bindObservedFlowSession, flowSessionPayloadFromRegisterCommand, recordFlowSessionObservation } from "./sessions.js";
@@ -278,7 +279,7 @@ export function handleCodexHook(context, input) {
         return { ok: true, observed: false, reason: "event_not_participating", event: eventName };
     // Resume legitimately receives an answer through stdin. It is matched by
     // immutable lifecycle arguments below; never reject or rewrite that pipe.
-    if (lifecycle.analysis.kind === "compound" && !lifecycle.stageResume) {
+    if (lifecycle.analysis.kind === "compound") {
         return {
             ok: false,
             observed: false,
@@ -303,10 +304,11 @@ export function handleCodexHook(context, input) {
     if (!project)
         return { ok: true, observed: false, reason: "unrelated_cwd" };
     const binding = sessionId ? upsertSessionBindingFromPayload(context, project, sessionId, payload) : undefined;
+    const storageId = sessionId ? storageSessionId(nativeSessionIdentity("codex-desktop", sessionId)) : null;
     const observedSession = flowPayload
-        ? bindObservedFlowSession(context, project, flowPayload, sessionId ?? flowPayload.session_id ?? undefined)
+        ? bindObservedFlowSession(context, project, { ...flowPayload, harness: "codex-desktop", provider_session_id: sessionId ?? flowPayload.provider_session_id ?? null }, storageId ?? undefined)
         : undefined;
-    const effectiveSessionId = observedSession?.session_id ?? sessionId ?? null;
+    const effectiveSessionId = observedSession?.session_id ?? storageId;
     const protocolId = observedSession?.protocol_id ?? binding?.protocol_id ?? null;
     const eventKey = hookEventKey(payload, eventName, toolName, command);
     const inserted = recordHookEvent(context, {
@@ -343,7 +345,7 @@ export function handleCodexHook(context, input) {
         observed: inserted,
         duplicate: !inserted,
         event_key: eventKey,
-        session_id: effectiveSessionId,
+        session: sessionId ? nativeSessionIdentity("codex-desktop", sessionId) : null,
         protocol_id: protocolId,
         ...(sessionId && (flowPayload || stageStart || stageResume || workStart)
             ? {
@@ -377,7 +379,7 @@ export function handleZcodeEvent(context, input) {
     const lifecycle = lifecycleFacts(command);
     if (!lifecycle)
         return { ok: true, observed: false, reason: "event_not_participating" };
-    if (lifecycle.analysis.kind === "compound" && !lifecycle.stageResume) {
+    if (lifecycle.analysis.kind === "compound") {
         throw new AppError("compound_lifecycle_command", "dd-flow lifecycle commands must be a standalone ZCode Bash tool call", 1, {
             standalone_command: lifecycle.invocation.command
         });
@@ -403,8 +405,8 @@ export function handleZcodeEvent(context, input) {
         throw new AppError("zcode_identity_missing", "ZCode ACP event has no root provider Session ID", 1);
     const childProviderSessionId = stringValue(runtime.childSessionId);
     const providerSessionId = childProviderSessionId ?? rootProviderSessionId;
-    const sessionId = `zcode-acp:${providerSessionId}`;
-    const parentSessionId = childProviderSessionId ? `zcode-acp:${rootProviderSessionId}` : null;
+    const sessionId = storageSessionId(nativeSessionIdentity("zcode-acp", providerSessionId));
+    const parentSessionId = childProviderSessionId ? storageSessionId(nativeSessionIdentity("zcode-acp", rootProviderSessionId)) : null;
     const agentId = stringValue(runtime.agentId);
     const observedSession = flowPayload ? bindObservedFlowSession(context, project, {
         ...flowPayload,
@@ -463,9 +465,8 @@ export function handleZcodeEvent(context, input) {
         duplicate: !inserted,
         event_key: eventKey,
         harness: "zcode-acp",
-        session_id: sessionId,
-        provider_session_id: providerSessionId,
-        parent_session_id: parentSessionId,
+        session: nativeSessionIdentity("zcode-acp", providerSessionId),
+        ...(childProviderSessionId ? { parent_session: nativeSessionIdentity("zcode-acp", rootProviderSessionId) } : {}),
         daemon_id: daemonId ?? null
     };
 }
@@ -485,7 +486,7 @@ export function handleGrokEvent(context, input) {
     const lifecycle = lifecycleFacts(command);
     if (!lifecycle)
         return { ok: true, observed: false, reason: "event_not_participating" };
-    if (lifecycle.analysis.kind === "compound" && !lifecycle.stageResume) {
+    if (lifecycle.analysis.kind === "compound") {
         throw new AppError("compound_lifecycle_command", "dd-flow lifecycle commands must be a standalone Grok Build tool call", 1, {
             standalone_command: lifecycle.invocation.command
         });
@@ -509,8 +510,8 @@ export function handleGrokEvent(context, input) {
     if (!rootProviderSessionId || !providerSessionId)
         throw new AppError("grok_identity_missing", "Grok Build hook has no trusted Session ID", 1);
     const isChild = providerSessionId !== rootProviderSessionId;
-    const sessionId = `grok-acp:${providerSessionId}`;
-    const parentSessionId = isChild ? `grok-acp:${stringValue(ddGrok.parentProviderSessionId) ?? rootProviderSessionId}` : null;
+    const sessionId = storageSessionId(nativeSessionIdentity("grok-acp", providerSessionId));
+    const parentSessionId = isChild ? storageSessionId(nativeSessionIdentity("grok-acp", stringValue(ddGrok.parentProviderSessionId) ?? rootProviderSessionId)) : null;
     const daemonId = stringValue(ddGrok.daemonId);
     const agentId = stringValue(hook.agent_id) ?? stringValue(hook.agentId);
     const observedSession = flowPayload ? bindObservedFlowSession(context, project, {
@@ -532,8 +533,8 @@ export function handleGrokEvent(context, input) {
         projectId: project.id, sessionId, runId: observedSession?.run_id ?? null, protocolId: observedSession?.protocol_id ?? null,
         cwd: expectedRoot, toolName: toolName ?? "Bash", eventKey
     });
-    const result = { ok: true, observed: inserted, duplicate: !inserted, event_key: eventKey, harness: "grok-acp", session_id: sessionId,
-        provider_session_id: providerSessionId, parent_session_id: parentSessionId, daemon_id: daemonId ?? null };
+    const result = { ok: true, observed: inserted, duplicate: !inserted, event_key: eventKey, session: nativeSessionIdentity("grok-acp", providerSessionId),
+        ...(isChild ? { parent_session: nativeSessionIdentity("grok-acp", stringValue(ddGrok.parentProviderSessionId) ?? rootProviderSessionId) } : {}), daemon_id: daemonId ?? null };
     return (flowPayload || stageStart || stageResume || workStart)
         ? { ...result, hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "allow", updatedInput: { ...(rawInput ?? {}), command: commandWithHookEvent(command, eventKey) } } }
         : result;
@@ -565,8 +566,8 @@ export function handleOpenCodeEvent(context, input) {
     if (resolveProjectRoot(directory) !== expectedRoot) {
         throw new AppError(agy ? "agy_directory_mismatch" : "opencode_directory_mismatch", `${agy ? "Antigravity" : "OpenCode"} Session directory does not match the controlled workspace`, 1, { expected: expectedRoot, actual: directory });
     }
-    const sessionId = `${harness}:${providerSessionId}`;
-    const parentSessionId = nativeParentId ? `${harness}:${nativeParentId}` : null;
+    const sessionId = storageSessionId(nativeSessionIdentity(harness, providerSessionId));
+    const parentSessionId = nativeParentId ? storageSessionId(nativeSessionIdentity(harness, nativeParentId)) : null;
     const command = stringValue(rawInput.command) ?? stringValue(rawInput.cmd) ?? stringValue(rawInput.CommandLine);
     const baseKey = `${eventId}:${phase}`;
     if (phase === "after") {
@@ -577,7 +578,7 @@ export function handleOpenCodeEvent(context, input) {
             eventName: "PostToolUse", toolName, status: "observed", payload: { session_id: providerSessionId, cwd: expectedRoot, tool_name: toolName, status: objectRecord(event.outcome).status },
             eventKey: baseKey, matchKey: null, transcriptPath: null, cwd: expectedRoot
         });
-        return { ok: true, observed: inserted, duplicate: !inserted, event_key: baseKey, phase, harness, session_id: sessionId };
+        return { ok: true, observed: inserted, duplicate: !inserted, event_key: baseKey, phase, harness, session: nativeSessionIdentity(harness, providerSessionId), ...(nativeParentId ? { parent_session: nativeSessionIdentity(harness, nativeParentId) } : {}) };
     }
     if (!command || !["bash", "Bash", "run_command", "run_terminal_command", "RunTerminalCommand"].includes(toolName)) {
         return { ok: true, observed: false, reason: command ? "non_bash_tool" : "event_not_participating" };
@@ -585,7 +586,7 @@ export function handleOpenCodeEvent(context, input) {
     const lifecycle = lifecycleFacts(command);
     if (!lifecycle)
         return { ok: true, observed: false, reason: "event_not_participating" };
-    if (lifecycle.analysis.kind === "compound" && !lifecycle.stageResume) {
+    if (lifecycle.analysis.kind === "compound") {
         throw new AppError("compound_lifecycle_command", `dd-flow lifecycle commands must be a standalone ${agy ? "Antigravity" : "OpenCode"} shell tool call`, 1, { standalone_command: lifecycle.invocation.command });
     }
     const { flowPayload, bootstrapStageStart, commandProjectRoot } = lifecycle;
@@ -614,7 +615,7 @@ export function handleOpenCodeEvent(context, input) {
         status: "observed", payload, eventKey: baseKey, matchKey, transcriptPath: null, cwd: expectedRoot
     });
     recordFlowSessionObservation(context, { projectId: project.id, sessionId, runId: observedSession?.run_id ?? null, protocolId: observedSession?.protocol_id ?? null, cwd: expectedRoot, toolName, eventKey: baseKey });
-    const result = { ok: true, observed: inserted, duplicate: !inserted, event_key: baseKey, phase, harness, session_id: sessionId, provider_session_id: providerSessionId, parent_session_id: parentSessionId, daemon_id: daemonId };
+    const result = { ok: true, observed: inserted, duplicate: !inserted, event_key: baseKey, phase, harness, session: nativeSessionIdentity(harness, providerSessionId), ...(nativeParentId ? { parent_session: nativeSessionIdentity(harness, nativeParentId) } : {}), daemon_id: daemonId };
     return agy ? result : { ...result, hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "allow", updatedInput: { ...rawInput, command: commandWithHookEvent(command, baseKey) } } };
 }
 /** Convert an Antigravity CLI tool hook into the shared lifecycle receipt. */
@@ -736,7 +737,7 @@ export function sessionIdForHookEvent(context, projectId, eventKey) {
 /** Reads immutable identity facts already captured by PreToolUse. */
 export function hookSessionIdentity(context, projectId, eventKey) {
     const event = context.db.get(`SELECT he.id, he.harness, he.provider_session_id, he.parent_session_id, he.daemon_id, he.session_id, he.agent_id, he.turn_id, he.transcript_path, he.provider, he.model, he.reasoning, he.mode, he.agent_type, COALESCE(he.cwd, csb.cwd) AS cwd
-     FROM hook_events he LEFT JOIN codex_session_bindings csb ON csb.project_id = he.project_id AND csb.session_id = he.session_id
+     FROM hook_events he LEFT JOIN codex_session_bindings csb ON csb.project_id = he.project_id AND csb.session_id = COALESCE(he.provider_session_id, he.session_id)
      WHERE he.project_id = ? AND he.event_key = ?`, [projectId, eventKey]);
     if (!event?.session_id)
         throw new AppError("hook_event_not_found", "stage start requires a trusted PreToolUse hook event", 1, { event_key: eventKey });
@@ -747,7 +748,9 @@ export function hookSessionIdentity(context, projectId, eventKey) {
         parentSessionId: event.parent_session_id,
         daemonId: event.daemon_id,
         agentId: event.agent_id,
-        sessionId: event.harness === "codex-desktop" ? event.agent_id ?? event.session_id : event.session_id,
+        // agent_id is an auxiliary provider fact, never a replacement Session ID.
+        sessionId: event.session_id,
+        nativeSessionId: event.provider_session_id ?? event.session_id,
         turnId: event.turn_id,
         transcriptPath: event.transcript_path,
         provider: event.provider,

package/dist/services/lanes.js

@@ -288,6 +288,7 @@ export async function waitAcquireLaneLock(context, input) {
                 timeoutSeconds
             });
         }
+        input.progress?.(`lane ${lane} is waiting at queue position ${String(result.payload.position ?? "unknown")}; next update in ${pollIntervalSeconds} seconds`);
         await delay(pollIntervalSeconds * 1000);
     }
 }