@deksden-com/dd-flow-cli 0.9.0-beta.64 → 0.9.0-beta.74

package/dist/harness-runtime/lib/tool-observations.mjs

@@ -0,0 +1,153 @@
+import fs from "node:fs";
+
+/** Canonical physical-session tool accounting. Native decoding lives below;
+ * consumers never have to inspect provider envelopes or aggregate tokens. */
+export class ToolObservations {
+  constructor() { this.calls = new Map(); this.gaps = new Set(); }
+  add(event) {
+    if (!event) return;
+    if (event.reason) { this.gaps.add(event.reason); return; }
+    const { harness_id, session_id } = event.session ?? {};
+    if (!harness_id || !session_id || !event.call_id) { this.gaps.add("tool_identity_missing"); return; }
+    const key = JSON.stringify([harness_id, session_id, event.epoch ?? "", event.call_id]);
+    const old = this.calls.get(key);
+    // Replay and late starts cannot undo a terminal outcome. Conflicting
+    // terminal facts remain visible rather than silently choosing success.
+    const terminal = value => ["completed", "failed"].includes(value);
+    if (old && terminal(old.status) && terminal(event.status) && old.status !== event.status) this.gaps.add("conflicting_tool_outcomes");
+    this.calls.set(key, { ...old, ...event, name: event.name ?? old?.name ?? "unknown",
+      status: old?.status === "failed" || event.status === "failed" ? "failed" : terminal(old?.status) ? old.status : event.status ?? old?.status ?? "unknown" });
+  }
+  summary(sessionId, cursor) {
+    const by_tool = {}, sessions = new Map(), reasons = new Set(this.gaps); let total = 0, failures = 0, pending = 0;
+    for (const [key, value] of this.calls) {
+      if (sessionId !== undefined && value.session.session_id !== sessionId || cursor?.has(key)) continue;
+      const id = JSON.stringify(value.session);
+      if (value.name === "unknown") reasons.add("tool_start_missing");
+      const session = sessions.get(id) ?? { session: value.session, parent_session: value.parent_session ?? null, total: 0, failures: 0, pending: 0, by_tool: {} };
+      total++; session.total++; by_tool[value.name] = (by_tool[value.name] ?? 0) + 1; session.by_tool[value.name] = (session.by_tool[value.name] ?? 0) + 1;
+      if (value.status === "failed") { failures++; session.failures++; }
+      if (!["completed", "failed"].includes(value.status)) { pending++; session.pending++; }
+      sessions.set(id, session);
+    }
+    return { schema_id: "dd-flow/tool-summary@1", scope: "physical_sessions", measurement: "observed_invocations", origin: "native_tool_events", aggregation: cursor ? "delta" : "cumulative", total, failures, pending, by_tool,
+      sessions: [...sessions.values()], completeness: reasons.size ? "partial" : "complete", outcome_completeness: pending ? "partial" : "complete", reasons: [...reasons] };
+  }
+  cursor() { return new Set(this.calls.keys()); }
+}
+
+/** For adapters whose raw transcript is not portable, retain only normalized
+ * tool facts in the existing owned journal. Repeated snapshots are idempotent. */
+export function journalToolObservations(file, events, previous) {
+  const batch = new ToolObservations();
+  for (const event of events) batch.add(event);
+  const records = [...batch.calls.values(), ...[...batch.gaps].map(reason => ({ reason }))];
+  for (const event of records) {
+    const key = JSON.stringify([event.session, event.epoch, event.call_id, event.reason]);
+    const encoded = JSON.stringify(event);
+    if (previous.get(key) === encoded) continue;
+    fs.appendFileSync(file, `${JSON.stringify({ kind: "tool_observation", schema_id: "dd-flow/tool-observation@1", observed_at: new Date().toISOString(), event })}\n`, { mode: 0o600 });
+    previous.set(key, encoded);
+  }
+}
+
+const identity = (harness_id, session_id) => ({ harness_id, session_id });
+const status = value => ["error", "failed", "ERROR"].includes(value) ? "failed" : ["completed", "success", "DONE"].includes(value) ? "completed" : "running";
+export function zcodePhysicalSession(update, rootSessionId) {
+  const native = update?._meta?.zcodeRuntime ?? {};
+  if (native.source === "subagent" && !native.childSessionId) return null;
+  return native.childSessionId ?? rootSessionId;
+}
+
+export function acpToolObservation(message, { harness = "zcode-acp", rootSessionId, adapterSessionId } = {}) {
+  if (!["session/update", "_x.ai/session_notification"].includes(message?.method)) return null;
+  const update = message.params?.update;
+  if (!["tool_call", "tool_call_update"].includes(update?.sessionUpdate)) return null;
+  const transport = message.params?.sessionId;
+  if (adapterSessionId && transport !== adapterSessionId) return null;
+  const root = rootSessionId ?? transport;
+  const session = harness === "zcode-acp" ? zcodePhysicalSession(update, root) : root;
+  if (!session || !update.toolCallId) return { reason: "tool_identity_missing" };
+  return { session: identity(harness, session), parent_session: session !== root ? identity(harness, root) : null,
+    transport_session_id: transport, call_id: update.toolCallId, name: update._meta?.["x.ai/tool"]?.name ?? update._meta?.claudeCode?.toolName ?? update.title?.split(":", 1)[0], status: status(update.status) };
+}
+
+export function droidToolObservations(record, sessionId) {
+  return (Array.isArray(record.message?.content) ? record.message.content : []).flatMap(block => {
+    if (block.type === "tool_use") return [{ session: identity("droid-cli", sessionId), call_id: block.id, name: block.name, status: "running" }];
+    if (block.type === "tool_result") return [{ session: identity("droid-cli", sessionId), call_id: block.tool_use_id, status: block.is_error ? "failed" : "completed" }];
+    return [];
+  });
+}
+
+export function codexToolObservation(record, sessionId) {
+  if (record.type !== "response_item") return null;
+  const p = record.payload ?? {};
+  if (["function_call", "custom_tool_call"].includes(p.type)) return { session: identity("codex-desktop", sessionId), call_id: p.call_id, name: p.name, status: "running" };
+  if (["function_call_output", "custom_tool_call_output"].includes(p.type)) {
+    return { session: identity("codex-desktop", sessionId), call_id: p.call_id, status: containsFailure(p) ? "failed" : "completed" };
+  }
+  return null;
+}
+
+function containsFailure(value) {
+  if (Array.isArray(value)) return value.some(containsFailure);
+  if (typeof value === "string") {
+    if (/(?:^|\n)exit=(?:[1-9]\d*)\b|Process exited with code [1-9]\d*/.test(value)) return true;
+    if (/^[{[]/.test(value.trim())) { try { return containsFailure(JSON.parse(value)); } catch {} }
+    return false;
+  }
+  if (!value || typeof value !== "object") return false;
+  if (value.ok === false || value.is_error === true || value.isError === true || value.error === true || typeof value.error === "string") return true;
+  if (typeof value.exit_code === "number" && value.exit_code !== 0) return true;
+  return Object.values(value).some(containsFailure);
+}
+
+export function openCodeToolObservation(part, sessionId, messageId) {
+  if (part.type !== "tool") return null;
+  return { session: identity("opencode-server", part.sessionID ?? sessionId), call_id: part.callID ?? part.id,
+    epoch: messageId, name: part.tool, status: status(part.state?.status) };
+}
+
+export function agyToolObservation(step, rootSessionId) {
+  if (step.step_type !== "tool") return null;
+  const sessionId = step.conversation_id ?? rootSessionId;
+  return { session: identity("antigravity-cli", sessionId), parent_session: sessionId !== rootSessionId ? identity("antigravity-cli", rootSessionId) : null,
+    call_id: step.step_id ?? step.stepId ?? step.id ?? step.tool_call_id ?? step.toolCallId ?? (Number.isInteger(step.step_index) ? String(step.step_index) : null),
+    name: step.tool_name ?? step.tool_info?.name, status: step.tool_info?.error ? "failed" : status(step.state) };
+}
+
+/** Read-only replay, shared by accounting and offline diagnosis. A journal
+ * carries physical identities; an ACP connection identity never crosses out. */
+export function replayToolJournal(file, options, reducer = new ToolObservations()) {
+  let bytes;
+  try { bytes = fs.readFileSync(file, "utf8"); } catch (error) { reducer.gaps.add(error.code === "ENOENT" ? "journal_missing" : "journal_unreadable"); return reducer; }
+  const lines = bytes.split("\n"); let session = options.rootSessionId, transport = options.adapterSessionId;
+  for (const [index, line] of lines.entries()) {
+    if (!line.trim()) continue;
+    let e; try { e = JSON.parse(line); } catch { reducer.gaps.add(index === lines.length - 1 ? "journal_partial_tail" : "journal_invalid_record"); continue; }
+    const add = event => { if (event) reducer.add({ ...event, source: { journal: file, line: index + 1 }, observed_at: e.observed_at ?? e.timestamp ?? e.at ?? e.ts ?? null }); };
+    if (e.kind === "tool_observation" && e.schema_id === "dd-flow/tool-observation@1") { add(e.event); continue; }
+    if (e.kind === "notification_failure") reducer.gaps.add("notification_failure");
+    const m = e.payload ?? e;
+    if (options.harness === "zcode-acp" || options.harness === "grok-acp") {
+      if (m.method === "zcode/session/allocated" && m.params?.provider_session_id === session) transport = m.params.adapter_session_id;
+      if (e.kind === "inbound" || m.method) add(acpToolObservation(m, { ...options, rootSessionId: session, adapterSessionId: transport }));
+    } else if (options.harness === "codex-desktop") {
+      if (e.type === "session_meta" && e.payload?.id !== session) { reducer.gaps.add("session_identity_mismatch"); break; }
+      add(codexToolObservation(e, session));
+    } else if (options.harness === "droid-cli") {
+      if (e.type === "session_start" && e.id !== session) { reducer.gaps.add("session_identity_mismatch"); break; }
+      for (const event of droidToolObservations(e, session)) add(event);
+    } else if (options.harness === "antigravity-cli") {
+      const native = m.event ?? e;
+      if (native.event === "step_update") add(agyToolObservation(native.step_update ?? {}, session));
+    } else if (options.harness === "opencode-server") {
+      // Native SSE message.part.updated, retained in the adapter journal.
+      const event = m.event ?? m;
+      const part = event.properties?.part;
+      if (part) add(openCodeToolObservation(part, session, part.messageID));
+    } else reducer.gaps.add("tool_observation_unsupported");
+  }
+  return reducer;
+}

package/dist/services/code-checks.js

@@ -12,7 +12,14 @@ const profileRelativePath = path.join(".memory-bank", "spec", "engineering", "co
 // auditable attempt. A second caller must not mistake that small handoff window
 // for a dead check and overwrite its outcome.
 const receiptStartingGraceMs = 30_000;
-export function codeExecutionEnvironment(workspaceRoot) { const suffix = crypto.createHash("sha256").update(path.resolve(workspaceRoot)).digest("hex").slice(0, 12); return { ...process.env, DD_FLOW_LOCAL_DATABASE_SUFFIX: suffix }; }
+export function codeExecutionEnvironment(workspaceRoot) {
+    const suffix = crypto.createHash("sha256").update(path.resolve(workspaceRoot)).digest("hex").slice(0, 12);
+    // Managed checks retain the launcher's executable resolution. A login shell
+    // or NODE_PATH can silently replace it, including with another architecture.
+    const environment = { ...process.env, DD_FLOW_LOCAL_DATABASE_SUFFIX: suffix };
+    delete environment.NODE_PATH;
+    return environment;
+}
 export function workspaceOperationId(workspaceRoot) { return `workspace:${crypto.createHash("sha256").update(path.resolve(workspaceRoot)).digest("hex")}`; }
 export function readCodeCheckProfile(workspaceRoot) {
     const file = path.join(workspaceRoot, profileRelativePath);
@@ -144,9 +151,13 @@ async function runCodeChecksOwned(context, input, workspaceGateId) {
     for (const receiptId of retryIds) {
         const predecessor = validateFailedCheckRetry(context, { projectId: input.projectId, runId: input.runId, receiptId, declarations: checks, reason: input.retryReason });
         const snapshot = workspaceState(input.workspaceRoot, [input.runHome]);
-        const group = groups.find(candidate => checkInputHash(input.workspaceRoot, candidate, profileHash, workspaceInputFingerprint(input.workspaceRoot, snapshot.files, candidate.inputs, [input.runHome])) === predecessor.input_hash);
+        const group = groups.find(candidate => candidate.declarations.some(check => check.run_at === predecessor.gate)
+            && checkInputHash(input.workspaceRoot, { ...candidate, gate: predecessor.gate }, profileHash, workspaceInputFingerprint(input.workspaceRoot, snapshot.files, candidate.inputs, [input.runHome])) === predecessor.input_hash);
         if (!group || retries.has(group))
             throw new AppError("retry_check_invalid", "Retry must match exactly one current execution contract", 2, { check_receipt_id: receiptId });
+        // Preserve the identity of a pre-deduplication failed execution when an
+        // upgraded RUN retries it; the new receipt still proves every grouped ref.
+        group.gate = predecessor.gate;
         retries.set(group, receiptId);
     }
     for (let index = 0; index < groups.length; index += 1) {
@@ -321,7 +332,11 @@ function reserveOrReuseReceipt(context, input) {
                 throw new AppError("retry_check_invalid", "The requested retry already has a terminal outcome; choose its failed receipt for another retry", 2, { check_receipt_id: successor.id, retry_of_receipt_id: retryId, status: successor.status });
             }
         }
-        if (prior && !retryIds.has(prior.id) && (prior.status !== "passed" || (input.group.reusable && checkReceiptEvidenceValid(prior)))) {
+        // Only success is reusable evidence. A new finish attempt must execute a
+        // failed check again: repairing dependencies/services need not change any
+        // tracked input. Lifecycle invocation replay owns command idempotency;
+        // the running-receipt guard above still prevents concurrent execution.
+        if (prior?.status === "passed" && !retryIds.has(prior.id) && input.group.reusable && checkReceiptEvidenceValid(prior)) {
             context.db.exec("COMMIT");
             return { receipt: prior };
         }
@@ -392,19 +407,105 @@ function resolvedReceiptArtifacts(receiptPath, artifacts) {
     return { completion_path: path.join(currentRoot, "completion.json"), required_artifacts: original.required_artifacts ?? [], inputs: original.inputs ?? [], artifacts: artifacts.map((artifact) => ({ ...artifact, path: relocate(artifact.path) })) };
 }
 export function workspaceFingerprint(root) { return workspaceState(root).fingerprint; }
-export function workspaceChangedPaths(root) { const status = spawnSync("git", ["status", "--porcelain=v1", "-z", "--untracked-files=all"], { cwd: root, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 }); if (status.status !== 0)
-    return null; return status.stdout.split("\0").filter(Boolean).map((entry) => entry.slice(3)).filter(Boolean).sort(); }
-function deduplicate(checks, commands) { const groups = new Map(); checks.forEach((check, index) => { const artifacts = [...(check.required_artifacts ?? [])].sort(); const ports = [...(check.ports ?? [])].sort(); const inputs = normalizedInputs(check.inputs ?? []); const reusable = check.reuse === "deterministic"; const key = JSON.stringify([check.run_at, commands[index], artifacts, ports, inputs, reusable]); const current = groups.get(key); if (current)
-    current.declarations.push(check);
-else
-    groups.set(key, { gate: check.run_at, command: commands[index], declarations: [check], requiredArtifacts: artifacts, ports, inputs, reusable }); }); return [...groups.values()].map(group => ({ ...group, declarations: [...group.declarations].sort((left, right) => checkRef(left).localeCompare(checkRef(right))) })); }
-function workspaceState(root, ignoredRoots = []) { const git = spawnSync("git", ["ls-files", "-co", "--exclude-standard", "-z"], { cwd: root, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 }); const ignored = ignoredRoots.map((entry) => path.resolve(entry)); const listing = (git.status === 0 ? git.stdout.split("\0").filter(Boolean).sort() : listFiles(root)).filter((relative) => { const file = path.resolve(root, relative); return !ignored.some((ignoredRoot) => file === ignoredRoot || file.startsWith(`${ignoredRoot}${path.sep}`)); }); const files = new Map(); const hash = crypto.createHash("sha256"); for (const relative of listing) {
-    const file = path.join(root, relative);
-    const content = fs.existsSync(file) && fs.statSync(file).isFile() ? fs.readFileSync(file) : Buffer.from("<missing>");
-    const digest = crypto.createHash("sha256").update(content).digest("hex");
-    files.set(relative, digest);
-    hash.update(relative).update("\0").update(digest).update("\0");
-} return { fingerprint: hash.digest("hex"), files }; }
+/** One NUL-aware source of truth for paths differing from HEAD. Rename/copy
+ * records carry a second path; retain both because the old side is a deletion. */
+export function workspaceChangedPaths(root) {
+    const status = spawnSync("git", ["status", "--porcelain=v1", "-z", "--untracked-files=all"], { cwd: root, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+    // A workspace can be intentionally gitless. Keep the same conservative
+    // file inventory used for fingerprints instead of making result validation
+    // fail before the work contract can report its actual error.
+    if (status.status === 128 && /not a git repository|outside a repository/i.test(status.stderr ?? ""))
+        return listFiles(root);
+    if (status.status !== 0 || status.error)
+        throw new AppError("workspace_status_failed", "Could not determine changed workspace paths", 1, { workspace_root: root, stderr: status.stderr || null, cause: status.error?.message ?? null });
+    const records = status.stdout.split("\0");
+    const paths = [];
+    for (let index = 0; index < records.length; index += 1) {
+        const record = records[index];
+        if (!record)
+            continue;
+        if (record.length < 4 || record[2] !== " ")
+            throw new AppError("workspace_status_invalid", "Git returned an invalid porcelain-v1 record", 1, { workspace_root: root, record });
+        paths.push(normalizeWorkspacePath(root, record.slice(3)));
+        if (record[0] === "R" || record[0] === "C" || record[1] === "R" || record[1] === "C") {
+            const prior = records[++index];
+            if (!prior)
+                throw new AppError("workspace_status_invalid", "Git rename/copy record is missing its second path", 1, { workspace_root: root, record });
+            paths.push(normalizeWorkspacePath(root, prior));
+        }
+    }
+    return [...new Set(paths)].sort();
+}
+/** Ignored machine state cannot be reported as a product change. Tracked paths
+ * remain eligible regardless of their directory name. */
+export function ignoredWorkspacePaths(root, paths) {
+    const normalized = [...new Set(paths.map((item) => normalizeWorkspacePath(root, item)))];
+    if (!normalized.length)
+        return [];
+    const status = spawnSync("git", ["check-ignore", "-z", "--stdin"], { cwd: root, encoding: "utf8", input: `${normalized.join("\0")}\0`, maxBuffer: 64 * 1024 * 1024 });
+    // Projects may intentionally run without Git (the flow supports a local
+    // workspace identity independently from version control). In that case
+    // there is no ignore database to consult; a declared path is a product
+    // path, not an infrastructure path. Other Git failures remain fail-closed.
+    if (status.status === 128 && /not a git repository|outside a repository/i.test(status.stderr ?? ""))
+        return [];
+    if (![0, 1].includes(status.status ?? -1) || status.error)
+        throw new AppError("workspace_ignore_check_failed", "Could not classify reported workspace paths", 1, { workspace_root: root, stderr: status.stderr || null, cause: status.error?.message ?? null });
+    return [...new Set(status.stdout.split("\0").filter(Boolean).map((item) => normalizeWorkspacePath(root, item)))].sort();
+}
+export function normalizeWorkspacePath(root, value) {
+    if (typeof value !== "string" || !value || value.includes("\0") || path.isAbsolute(value))
+        throw new AppError("workspace_path_invalid", "Workspace path must be a non-empty relative path", 2, { path: value });
+    const resolvedRoot = path.resolve(root);
+    const resolved = path.resolve(resolvedRoot, value);
+    const relative = path.relative(resolvedRoot, resolved);
+    if (!relative || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative))
+        throw new AppError("workspace_path_invalid", "Workspace path escapes its root", 2, { path: value, workspace_root: root });
+    return relative.split(path.sep).join("/");
+}
+function deduplicate(checks, commands) {
+    const groups = new Map();
+    checks.forEach((check, index) => {
+        const artifacts = [...(check.required_artifacts ?? [])].sort(), ports = [...(check.ports ?? [])].sort(), inputs = normalizedInputs(check.inputs ?? []);
+        const reusable = check.reuse === "deterministic";
+        // Stage labels identify obligations, not different processes in this gate.
+        // Cross-invocation reuse still requires the explicit deterministic contract.
+        const key = JSON.stringify([commands[index], artifacts, ports, inputs, reusable]);
+        const current = groups.get(key);
+        if (current)
+            current.declarations.push(check);
+        else
+            groups.set(key, { gate: check.run_at, command: commands[index], declarations: [check], requiredArtifacts: artifacts, ports, inputs, reusable });
+    });
+    return [...groups.values()].map(group => ({ ...group, gate: [...group.declarations].map(check => check.run_at).sort()[0], declarations: [...group.declarations].sort((left, right) => checkRef(left).localeCompare(checkRef(right))) }));
+}
+function workspaceState(root, ignoredRoots = []) {
+    const git = spawnSync("git", ["ls-files", "-co", "--exclude-standard", "-z"], { cwd: root, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+    const ignored = ignoredRoots.map(entry => path.resolve(entry));
+    const listing = [...new Set(git.status === 0 ? git.stdout.split("\0").filter(Boolean) : listFiles(root))].sort();
+    const files = new Map(), hash = crypto.createHash("sha256");
+    for (const relative of listing) {
+        const file = path.resolve(root, relative);
+        if (ignored.some(ignoredRoot => file === ignoredRoot || file.startsWith(`${ignoredRoot}${path.sep}`)))
+            continue;
+        // Deleted tracked paths are absent content, both before and after commit.
+        // Do not mask other IO errors as an unchanged workspace.
+        let stat;
+        try {
+            stat = fs.lstatSync(file);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                continue;
+            throw error;
+        }
+        const content = stat.isSymbolicLink() ? Buffer.from(`symlink\0${fs.readlinkSync(file)}`) : stat.isFile() ? fs.readFileSync(file) : Buffer.from("<directory>");
+        const digest = crypto.createHash("sha256").update(content).digest("hex");
+        files.set(relative, digest);
+        hash.update(relative).update("\0").update(digest).update("\0");
+    }
+    return { fingerprint: hash.digest("hex"), files };
+}
 function workspaceInputFingerprint(root, files, inputs, ignoredRoots) {
     const selected = new Map(inputs.length === 0 || inputs.includes(".") ? files : []);
     for (const [file, digest] of explicitInputFiles(root, inputs.filter(input => input !== "."), ignoredRoots))
@@ -522,8 +623,8 @@ function explicitInputFiles(root, inputs, ignoredRoots) {
         visit(path.resolve(root, input), input, new Set());
     return [...result.entries()];
 }
-function checkInputHash(workspaceRoot, group, profileHash, inputFingerprint) { return crypto.createHash("sha256").update(JSON.stringify({ workspace_root: path.resolve(workspaceRoot), gate: group.gate, command: group.command, required_artifacts: group.requiredArtifacts, ports: group.ports, inputs: group.inputs, profile_hash: profileHash, environment: environmentFingerprint(workspaceRoot), input_fingerprint: inputFingerprint })).digest("hex"); }
-function bindReceipt(receipt, group) { return { ...receipt, declaration_id: group.declarations[0].id, check_refs: group.declarations.map(checkRef), required_artifacts: group.requiredArtifacts, inputs: group.inputs }; }
+function checkInputHash(workspaceRoot, group, profileHash, inputFingerprint) { return crypto.createHash("sha256").update(JSON.stringify({ workspace_root: path.resolve(workspaceRoot), gate: group.reusable ? null : group.gate, command: group.command, required_artifacts: group.requiredArtifacts, ports: group.ports, inputs: group.inputs, profile_hash: profileHash, environment: environmentFingerprint(workspaceRoot), input_fingerprint: inputFingerprint })).digest("hex"); }
+function bindReceipt(receipt, group) { return { ...receipt, gate: group.gate, declaration_id: group.declarations[0].id, check_refs: group.declarations.map(checkRef), required_artifacts: group.requiredArtifacts, inputs: group.inputs }; }
 function latestApplicableReceipt(context, input) { const candidates = checkReceipts(context, { projectId: input.projectId, runId: input.runId }).filter((receipt) => receipt.input_hash === input.inputHash && receipt.profile_hash === input.profileHash); return candidates.at(-1) ?? null; }
 export function checkReceiptEvidenceValid(receipt) { if (receipt.status !== "passed" || receipt.exit_code !== 0 || receipt.before_fingerprint !== receipt.after_fingerprint || !fs.existsSync(receipt.completion_path) || readCompletion(receipt.completion_path)?.exit_code !== 0)
     return false; const stored = readReceipt(receipt.receipt_path); if (!stored || stored.status !== "passed" || stored.input_hash !== receipt.input_hash || stored.profile_hash !== receipt.profile_hash)
@@ -644,7 +745,7 @@ function checkShellScript() {
         // The actual command cannot run before PID ownership and admission persist.
         'IFS= read -r admission && [ "$admission" = admitted ] || exit 125',
         'completion="${DD_FLOW_CHECK_COMPLETION_FILE:-}"',
-        '/bin/sh -lc "$DD_FLOW_CHECK_COMMAND"',
+        '/bin/sh -c "$DD_FLOW_CHECK_COMMAND"',
         "code=$?",
         'if [ -n "$completion" ]; then temporary="$completion.tmp.$$"; printf \'{"exit_code":%s,"finished_at":"%s"}\\n\' "$code" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" > "$temporary" && mv "$temporary" "$completion"; fi',
         'exit "$code"'

package/dist/services/controller-fanout.js

@@ -3,6 +3,17 @@ import { getVnextFanoutStatus, observeVnextNativeChildren, reconcileVnextFanout,
 import { getFlowRunVariables } from "./runs.js";
 import { dispatchVnextPlanReview } from "./vnext-plan-review.js";
 import { resolveExecutionPolicy } from "./execution-policy.js";
+/** Stage entry acknowledges the packet before the controller issues child commands. */
+export function controllerStageEntryPrompt(stage, command, responseFile) {
+    return [
+        `Start the assigned ${stage} Stage now. Your first tool call must be this exact standalone command:`,
+        command,
+        `Read the complete authoritative packet saved to ${JSON.stringify(responseFile)}, including worker_prompt_markdown. If a read is truncated, continue until the entire packet has been read.`,
+        "If the returned packet has orchestration.kind = work_fanout, this Turn is only Stage entry: acknowledge the packet and end your Turn immediately. The packet describes the whole Stage, but its graph/dispatch/finish instructions belong to later controller continuations. Do not list, start, launch or finish Work, create children, change files, run checks, or finish the Stage in this entry Turn. The controller will inspect the graph and send the next assignment with exact issued commands (or dispatch external workers itself).",
+        "Otherwise perform this Stage's semantic work and stop at its boundary or a declared HITL boundary. Do not start a successor Stage.",
+        "Copy runtime-issued lifecycle commands verbatim as standalone calls. Never generate an invocation ID, substitute a shell variable for it, or borrow one from another command. If a required command is missing or rejected without a returned retry command, report the exact error and end the Turn so the controller can handle it."
+    ].join("\n\n");
+}
 /** The shared controller owns this former eval-only Work-graph decision. */
 export async function nextControllerFanout(context, input) {
     const children = input.children.filter(child => child.status !== "settled_by_root");

package/dist/services/engines.js

@@ -117,7 +117,7 @@ export function installCurrentEngine(context, input = {}) {
 }
 export function listEngines(context) {
     const root = engineStoreRoot(context.ddFlowHome);
-    const engines = readInstalledManifests(root).map(manifestSummary);
+    const engines = readInstalledManifests(root).map(manifest => manifestSummary(manifest));
     return { ok: true, schema_id: "dd-flow/engine-list@1", engine_store: root, engines };
 }
 export function engineInfo(context, input) {
@@ -138,11 +138,10 @@ export function resolveEngine(context, input = {}) {
 export function doctorEngines(context, input = {}) {
     const root = engineStoreRoot(context.ddFlowHome);
     const installed = readInstalledManifests(root);
-    const checks = installed.map((manifest) => ({
-        engine: manifestSummary(manifest),
-        status: manifestHealthy(manifest) ? "ok" : "corrupt",
-        diagnostics: manifestDiagnostics(manifest)
-    }));
+    const checks = installed.map(manifest => {
+        const diagnostics = manifestDiagnostics(manifest);
+        return { engine: manifestSummary(manifest, diagnostics), status: diagnostics.length ? "corrupt" : "ok", diagnostics };
+    });
     const classification = input.classification ?? classifyCliOperation(["engine", "doctor"], input.env ?? context.env);
     const selection = selectEngine(context, input, {}, classification);
     return {
@@ -254,6 +253,38 @@ export function bindCurrentEngineToRun(context, input) {
     };
     return writeRunEngineBinding(path.join(input.runRoot, "engine-binding.json"), binding).binding;
 }
+/** Forks are a new execution authority.  The source binding stays immutable;
+ * this replaces only the copied binding after proving the selected engine can
+ * read the copied RUN. */
+export function upgradeForkedRunEngine(context, input) {
+    const projectRoot = resolveProjectRoot(input.projectRoot);
+    const located = locateRunRoot(context.db, projectRoot, input.runId);
+    if (!located)
+        throw new AppError("not_found", `Forked RUN is not registered: ${input.runId}`, 1);
+    const manifest = requireBoundManifest(context.ddFlowHome, {
+        packageName: getCliBuildInfo().package_name,
+        packageVersion: input.engineVersion,
+        ...(input.integrityChecksum ? { integrityChecksum: input.integrityChecksum } : {})
+    });
+    const requested = engineIdentity(manifest);
+    readRunEngineBinding(located.binding_path);
+    const lineage = path.join(located.run_root, "fork-lineage.json");
+    if (!fs.existsSync(lineage))
+        throw new AppError("fork_lineage_missing", "Engine upgrade is permitted only for a derived RUN", 1, { run_id: located.run_id });
+    const probeArgs = ["run", "status", located.run_id, "--project-root", projectRoot, "--json"];
+    const probe = spawnSync(process.execPath, [resolveManifestEntrypoint(manifest), ...probeArgs], {
+        cwd: manifest.snapshot_root,
+        env: { ...process.env, ...context.env, DD_FLOW_HOME: context.ddFlowHome, DD_FLOW_ENGINE_MODE: "1", DD_FLOW_ENGINE_HOME: manifest.snapshot_root },
+        encoding: "utf8", timeout: 30_000
+    });
+    if (probe.status !== 0)
+        throw new AppError("fork_engine_probe_failed", "Selected engine cannot read the forked RUN", 1, { run_id: located.run_id, engine: manifestSummary(manifest), stderr: probe.stderr.slice(0, 2000) });
+    const binding = { schema_id: runEngineBindingSchemaId, run_id: located.run_id, project_root: projectRoot, bound_at: context.now(), source: "fork_upgrade", reason: requiredText(input.reason, "reason"), engine: requested, probe: { status: "passed", command: `dd-flow ${probeArgs.join(" ")}` } };
+    const temporary = `${located.binding_path}.fork-${process.pid}-${Date.now()}.tmp`;
+    fs.writeFileSync(temporary, `${JSON.stringify(binding, null, 2)}\n`);
+    fs.renameSync(temporary, located.binding_path);
+    return binding;
+}
 function boundRunEngineForArgs(context, args, projectRoot) {
     const runId = runIdForArgs(args);
     if (!runId || !projectRoot)
@@ -847,7 +878,7 @@ function manifestDiagnostics(manifest, options = {}) {
     }
     return diagnostics;
 }
-function manifestSummary(manifest) {
+function manifestSummary(manifest, diagnostics = manifestDiagnostics(manifest, { checkEntrypoint: false })) {
     return {
         schema_id: manifest.schema_id,
         package_name: manifest.package_name,
@@ -859,8 +890,8 @@ function manifestSummary(manifest) {
         snapshot_root: manifest.snapshot_root,
         resolved_entrypoint: safeResolveManifestEntrypoint(manifest),
         installed_at: manifest.installed_at,
-        healthy: manifestHealthy(manifest),
-        diagnostics: manifestDiagnostics(manifest)
+        healthy: diagnostics.length === 0,
+        diagnostics
     };
 }
 function resolveManifestEntrypoint(manifest) {

package/dist/services/eval-snapshots.js

@@ -11,7 +11,6 @@ import { registerProject, requireProjectByRoot } from "./projects.js";
 import { freezeRunExecutionRouting, getFlowRunStatus, importFlowRunExecutionProfile, startFlowRun } from "./runs.js";
 import { loadExecutionRoutingInput, resolveExecutionPolicy } from "./execution-policy.js";
 import { readVnextFlowDefinition } from "./vnext-specify.js";
-import { assertRunWorkResultArtifacts, runWorkResultArtifactIssues } from "./work-registry.js";
 import { captureRecoveryDatabase, readRecoveryResourceEvidence } from "./recovery-snapshot-database.js";
 import { resourceHome } from "./managed-processes.js";
 import { codexHomeSharedEntries } from "./hooks.js";
@@ -104,8 +103,6 @@ function captureEvalRunSnapshot(context, input) {
     }
     if (!recovery)
         assertDedicatedHome(context, project.id, input.runId);
-    if (!input.incomplete)
-        assertRunWorkResultArtifacts(context, project.id, input.runId);
     if (recovery) {
         const guard = context.db.get("SELECT status, recovery_id FROM run_recovery_guards WHERE project_id = ? AND run_id = ? AND recovery_id = ?", [project.id, input.runId, input.recoveryId]);
         if (!guard || guard.status !== "sealed")
@@ -181,28 +178,17 @@ function captureEvalRunSnapshot(context, input) {
     });
     const projectGit = snapshotProjectGit(projectRoot, output);
     const workspace = snapshotWorkspace(workspaceRoot, projectRoot, output);
-    // Compare the copied files with the copied SQLite receipt, not a later read
-    // of the live database. Incomplete captures retain contradictions as evidence.
-    const copiedContext = createContext({ ...context.env, DD_FLOW_HOME: path.join(output, "runtime") }, "read_existing");
-    let receiptIssues;
-    try {
-        if (recovery)
+    // Accepted Work results are captured in SQLite. Their file representations
+    // are retained evidence, not a second authority or a checkpoint gate.
+    if (recovery) {
+        const copiedContext = createContext({ ...context.env, DD_FLOW_HOME: path.join(output, "runtime") }, "read_existing");
+        try {
             captureRecoveryAuxiliary(context, copiedContext, { projectId: project.id, runId: input.runId, output });
-        receiptIssues = runWorkResultArtifactIssues(copiedContext, project.id, input.runId, file => {
-            const roots = [[context.ddFlowHome, "runtime"], [workspaceRoot, workspace.kind === "git_worktree" ? "workspace" : "project"], [projectRoot, "project"]];
-            for (const [source, payload] of roots) {
-                const relative = path.relative(source, file);
-                if (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative))
-                    return path.join(output, payload, relative);
-            }
-            throw new AppError("snapshot_receipt_path_invalid", "Work receipt is outside captured payloads", 1, { result_path: file });
-        });
-    }
-    finally {
-        copiedContext.db.close?.();
+        }
+        finally {
+            copiedContext.db.close?.();
+        }
     }
-    if (!input.incomplete && receiptIssues.length)
-        throw new AppError("snapshot_work_receipt_inconsistent", "Copied Work result does not match its authoritative receipt", 1, { issues: receiptIssues });
     const manifest = {
         schema_id: "dd-flow/eval-run-snapshot@5",
         run_id: input.runId,
@@ -213,7 +199,6 @@ function captureEvalRunSnapshot(context, input) {
         stage_entry: input.incomplete || recovery || input.candidate ? null : input.stageEntry,
         ...(input.incomplete ? { consistency: "sqlite_read_snapshot_files_copied_nonatomically", active_child_work_count: activeChildren, restorable: false } : recovery ? { recovery_id: input.recoveryId, consistency: "sealed_writer_barrier_required", active_child_work_count: activeChildren, restorable: "same-runtime-or-explicit-restore" } : {}),
         created_at: context.now(),
-        work_result_integrity: { valid: receiptIssues.length === 0, issues: receiptIssues },
         runtime_sha256: treeHash(path.join(output, "runtime")),
         project_sha256: treeHash(path.join(output, "project")),
         project_git: projectGit,
@@ -477,30 +462,21 @@ function rebaseRuntime(context, oldRoot, newRoot, oldWorkspace, newWorkspace, ol
     finally {
         context.db.exec("PRAGMA foreign_keys = ON");
     }
-    // SQLite owns operational paths. Imported packets, results and journals are
-    // historical bytes; the relocation receipt records their path mapping.
-    if (!recovery)
-        rewriteStructuredFiles(context.ddFlowHome, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome);
+    // Only operational database paths move. Imported packets, results and
+    // journals retain their historical bytes, including interrupted JSONL tails.
+    // The frozen workspace route is an operational receipt consumed by later
+    // stages, so its relocated path is the sole structured-file exception.
+    rewriteOperationalRouteReceipts(context.ddFlowHome, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome);
 }
-function rewriteStructuredFiles(root, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome) {
-    const visit = (dir) => {
-        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-            const file = path.join(dir, entry.name);
-            // This is hashed input evidence, not a mutable runtime projection.
-            if (/^execution-routing(?:\.[a-f0-9]{64})?\.input\.json$/.test(entry.name))
-                continue;
-            // DD_FLOW_HOME also contains the restored checkout and installed tools.
-            // They are project/tool bytes, not flow records; parsing every *.json
-            // there breaks on valid JSON-with-comments such as tsconfig files.
-            if (entry.isDirectory() && ![".git", "checkouts", "engines", "node_modules", "tools", "snapshot-imports"].includes(entry.name))
+function rewriteOperationalRouteReceipts(root, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome) {
+    const visit = (directory) => {
+        for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+            const file = path.join(directory, entry.name);
+            if (entry.isDirectory())
                 visit(file);
-            else if (entry.isFile() && entry.name.endsWith(".json")) {
+            else if (entry.isFile() && entry.name === "workspace-route.json") {
                 const value = JSON.parse(fs.readFileSync(file, "utf8"));
-                writeJson(file, rebaseStructuredValue(value, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome));
-            }
-            else if (entry.isFile() && entry.name.endsWith(".jsonl")) {
-                const lines = fs.readFileSync(file, "utf8").split("\n").filter(Boolean).map((line) => JSON.stringify(rebaseStructuredValue(JSON.parse(line), oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome)));
-                fs.writeFileSync(file, `${lines.join("\n")}\n`);
+                fs.writeFileSync(file, `${JSON.stringify(rebaseStructuredValue(value, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome), null, 2)}\n`);
             }
         }
     };
@@ -583,7 +559,9 @@ function restoreProjectGit(snapshot, source, projectRoot) {
 }
 const mergeStateFiles = ["MERGE_HEAD", "MERGE_MSG", "MERGE_MODE", "ORIG_HEAD", "AUTO_MERGE"];
 function indexEntries(root) {
-    const entries = gitBytes(root, ["ls-files", "--stage", "-z", "--", ".", ":(exclude)**/.env", ":(exclude)**/.env.*"]);
+    const entries = Buffer.from(gitBytes(root, ["ls-files", "--stage", "-z"])
+        .toString("utf8").split("\0").filter(entry => entry && snapshotEnvironmentAllowed(entry.slice(entry.indexOf("\t") + 1)))
+        .map(entry => `${entry}\0`).join(""));
     const merge = {};
     for (const name of mergeStateFiles) {
         const file = git(root, ["rev-parse", "--git-path", name]);
@@ -710,10 +688,15 @@ function runGit(root, args) {
         throw new AppError("snapshot_workspace_restore_failed", "Could not restore feature worktree", 1, { stderr: result.stderr.trim(), args });
 }
 function samePath(left, right) { return path.resolve(left) === path.resolve(right); }
+function snapshotEnvironmentAllowed(source) {
+    const name = path.basename(source);
+    // Public configuration template, not a local environment/credential file.
+    return name === ".env.example" || (name !== ".env" && !name.startsWith(".env."));
+}
 function snapshotPayloadAllowed(source) {
     const name = path.basename(source);
     return ![".git", "node_modules", ".cache", ".npm", ".pnpm-store"].includes(name)
-        && name !== ".env" && !name.startsWith(".env.");
+        && snapshotEnvironmentAllowed(source);
 }
 function runtimePayloadAllowed(source) {
     return snapshotPayloadAllowed(source) && !["auth.json", "auth.bk", "credentials.json", ".credentials.json", "credentials", ".credentials", "id_rsa", "id_ed25519", "engines", "checkouts"].includes(path.basename(source));