@deksden-com/dd-flow-cli 0.9.0-beta.123 → 0.9.0-beta.127

package/dist/harness-runtime/lib/operation-progress.mjs

@@ -0,0 +1,112 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { createHash } from 'node:crypto';
+import { open, readFile } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import path from 'node:path';
+import { writeJsonAtomic } from './runner-events.mjs';
+
+export const OPERATION_PROGRESS_CONTRACT = 'dd-flow/operation-progress@1';
+const context = new AsyncLocalStorage(), flights = new Map();
+const fields = ['operation_id', 'daemon_id', 'operation', 'params_sha256', 'owner_id', 'generation'];
+const phases = new Set(['accepted','ownership_confirmed','admission_confirmed','native_dispatched','native_progress','native_outcome_retained','settlement_started','settlement_completed','settlement_pending']);
+export function operationDirectory(root,id) {
+  if (typeof root!=='string' || !path.isAbsolute(root) || typeof id!=='string' || !id || id.length>1_024) throw Object.assign(new Error('invalid operation observation binding'),{code:'operation_progress_invalid'});
+  return path.join(root, 'operations', createHash('sha256').update(id).digest('hex'));
+}
+export async function readOperationRecord(root, id, name) {
+  try {
+    const handle = await open(path.join(operationDirectory(root, id), name), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+      const stat = await handle.stat();
+      if (!stat.isFile() || name === 'progress.json' && stat.size > 16_384) throw Object.assign(new Error('invalid operation record file'), {code:'operation_progress_invalid'});
+      const bytes = name === 'progress.json'
+        ? await handle.read({buffer:Buffer.alloc(16_385),position:0}).then(({buffer,bytesRead})=>buffer.subarray(0,bytesRead))
+        : await handle.readFile();
+      if (name === 'progress.json' && bytes.length > 16_384) throw Object.assign(new Error('invalid operation record file'), {code:'operation_progress_invalid'});
+      try {
+        const value = JSON.parse(bytes.toString('utf8'));
+        if (name === 'progress.json' && (!value || typeof value !== 'object' || Array.isArray(value))) throw new Error('operation progress must be an object');
+        return value;
+      }
+      catch (cause) { if (name !== 'progress.json') throw cause; throw Object.assign(new Error('invalid operation progress JSON'), {code:'operation_progress_invalid',cause}); }
+    } finally { await handle.close(); }
+  } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+export async function readOperationProgress(root, id, expected = {}) {
+  const requested = await readOperationRecord(root, id, 'requested.json');
+  const progress = await readOperationRecord(root, id, 'progress.json');
+  if (!progress) return null;
+  const invalid = () => Object.assign(new Error('operation progress binding is invalid'), { code: 'operation_progress_invalid', details: { operation_id: id } });
+  if (!requested || progress.schema_id !== OPERATION_PROGRESS_CONTRACT || progress.operation_id !== id
+    || typeof progress.operation!=='string' || !progress.operation || progress.operation.length>128
+    || !/^[a-f0-9]{64}$/.test(progress.params_sha256 ?? '')
+    || ['daemon_id','owner_id'].some(field=>progress[field]!==null && (typeof progress[field]!=='string' || !progress[field] || progress[field].length>1_024))
+    || progress.generation!==null && (!Number.isSafeInteger(progress.generation) || progress.generation<0)
+    || !Number.isSafeInteger(progress.sequence) || progress.sequence < 1 || !phases.has(progress.phase)
+    || !Number.isFinite(Date.parse(requested.requested_at))
+    || !Number.isFinite(Date.parse(progress.observed_at)) || Date.parse(progress.observed_at) > Date.now()
+    || Date.parse(progress.observed_at) < Date.parse(requested.requested_at)
+    || fields.some(field => (progress[field] ?? null) !== (requested[field] ?? null))) throw invalid();
+  assertExpectedBinding(requested, expected, id);
+  return progress;
+}
+function assertExpectedBinding(requested, expected, id) {
+  if (fields.some(field => Object.hasOwn(expected, field) && (expected[field] ?? null) !== (requested[field] ?? null))) {
+    throw Object.assign(new Error('retained operation differs from dispatched request'), {code:'operation_conflict',details:{operation_id:id}});
+  }
+}
+export function publishOperationProgress(root, id, phase, metadata = {}) {
+  if (!phases.has(phase)) return Promise.reject(Object.assign(new Error('unknown operation progress phase'), {code:'operation_progress_invalid'}));
+  const key = `${root}\0${id}`;
+  const next = (flights.get(key) ?? Promise.resolve()).catch(() => {}).then(async () => {
+    const requested = await readOperationRecord(root, id, 'requested.json');
+    if (!requested) return null;
+    const prior = await readOperationProgress(root, id);
+    const observedAt = metadata.observed_at ?? new Date().toISOString();
+    if (prior && Date.parse(observedAt)<Date.parse(prior.observed_at)) return prior;
+    if (prior && phase === prior.phase && phase !== 'native_progress') return prior;
+    if (prior && phase === 'native_progress' && Date.parse(observedAt) - Date.parse(prior.observed_at) < 1_000) return prior;
+    const value = { schema_id: OPERATION_PROGRESS_CONTRACT,
+      ...Object.fromEntries(fields.map(field => [field, requested[field] ?? null])),
+      sequence: (prior?.sequence ?? 0) + 1, phase, observed_at: observedAt,
+      ...Object.fromEntries(['native_request_id', 'session_id'].filter(field => typeof metadata[field] === 'string').map(field => [field, metadata[field].slice(0, 256)])) };
+    if (!Number.isFinite(Date.parse(observedAt)) || Date.parse(observedAt) > Date.now() || Date.parse(observedAt) < Date.parse(requested.requested_at)) throw Object.assign(new Error('invalid progress event timestamp'), { code: 'operation_progress_invalid' });
+    await writeJsonAtomic(path.join(operationDirectory(root, id), 'progress.json'), value);
+    return value;
+  });
+  flights.set(key, next);
+  void next.finally(() => { if (flights.get(key) === next) flights.delete(key); }).catch(() => {});
+  return next;
+}
+export const withOperationProgress = (root, id, action) => context.run({ root, id }, action);
+export function operationProgressReporter() {
+  const binding = context.getStore();
+  return (phase, metadata) => binding ? publishOperationProgress(binding.root, binding.id, phase, metadata) : Promise.resolve(null);
+}
+export const noteOperationProgress = (phase, metadata) => operationProgressReporter()(phase, metadata);
+
+/** Confirmed admission waiting is ownership evidence, not native activity. */
+export async function publishOperationWaiting(root,id,receipt) {
+  const requested = await readOperationRecord(root,id,'requested.json');
+  if (!requested) return;
+  const prior = await readOperationRecord(root,id,'admission-wait.json');
+  if (prior?.state === (receipt.admitted ? 'admitted' : 'provider_capacity') && Date.now()-Date.parse(prior.observed_at)<1_000) return;
+  const value = { schema_id:'dd-flow/operation-waiting@1', ...Object.fromEntries(fields.map(field=>[field,requested[field] ?? null])), observed_at:new Date().toISOString(), lease_expires_at:receipt.lease_expires_at, process_id:receipt.process_id, state:receipt.admitted ? 'admitted' : 'provider_capacity' };
+  await writeJsonAtomic(path.join(operationDirectory(root,id),'admission-wait.json'),value);
+}
+export async function readOperationWaiting(root,id,expected={}) {
+  const requested = await readOperationRecord(root,id,'requested.json'), waiting = await readOperationRecord(root,id,'admission-wait.json');
+  if (!waiting || waiting.state!=='provider_capacity') return false;
+  if (!requested || waiting.schema_id!=='dd-flow/operation-waiting@1' || fields.some(field=>(waiting[field] ?? null)!==(requested[field] ?? null))) throw Object.assign(new Error('admission waiting binding differs'),{code:'operation_progress_invalid'});
+  assertExpectedBinding(requested, expected, id);
+  if (!Number.isFinite(Date.parse(waiting.observed_at)) || Date.parse(waiting.observed_at)>Date.now() || Date.parse(waiting.observed_at)<Date.parse(requested.requested_at) || typeof waiting.process_id!=='string' || !waiting.process_id) throw Object.assign(new Error('invalid admission observation'),{code:'operation_progress_invalid'});
+  if (Date.now()-Date.parse(waiting.observed_at)>30_000) return false;
+  if (!Number.isFinite(Date.parse(waiting.lease_expires_at)) || Date.parse(waiting.lease_expires_at)<=Date.now()) return false;
+  const daemon = JSON.parse(await readFile(path.join(root,'daemon.json'),'utf8'));
+  if ((daemon.daemon_id ?? daemon.config?.daemonId)!==waiting.daemon_id || daemon.config?.runtime_owner?.owner_id!==waiting.owner_id || ['stopping','clean','unclean','cleanup_failed','failed'].includes(daemon.shutdown_state)) return false;
+  if (waiting.process_id !== daemon.resource_process?.id) return false;
+  try { const fence = JSON.parse(await readFile(path.join(root,'operation-fence.json'),'utf8')); if (fence.daemon_id===waiting.daemon_id && fence.generation>waiting.generation) return false; } catch(error) { if(error.code!=='ENOENT') throw error; }
+  try { process.kill(daemon.pid,0); } catch { return false; }
+  return true;
+}
+export function suspendOperationClock(clock) { clock.lastWall = clock.wall(); clock.lastMono = clock.monotonic(); }

package/dist/harness-runtime/lib/process-json.mjs

@@ -1,21 +1,32 @@
 import { spawn } from "node:child_process";
-import { reportedError } from "./operation-errors.mjs";
+import { errorRecord, reportedError } from "./operation-errors.mjs";
+import { ObservationClock, validateObservationDuration } from "./observation-clock.mjs";
+import { terminateCommandTree } from "./native-hook-command.mjs";
 
 function failure(message, code) {
   return Object.assign(new Error(message), { code });
 }
 
-export function reportedFailure(stdout, stderr, fallback, fallbackCode = "flow_reconciliation_failed") {
+export function reportedFailure(stdout, stderr, fallback, fallbackCode = "flow_reconciliation_failed", retainedError = null) {
   for (const text of [stdout, stderr]) {
-    for (const line of [text.trim(), ...text.trim().split(/\n/).reverse()]) {
+    // Bounded CLI transport may prepend JSONL phase records to the usual
+    // pretty-printed error envelope. Remove only our diagnostics, not arbitrary
+    // text or a substring that might masquerade as an authoritative receipt.
+    const envelope = text.split(/\n/).filter(line => {
+      try { return !["native_hook_phase", "process_maintenance_phase"].includes(JSON.parse(line)?.kind); }
+      catch { return true; }
+    }).join("\n").trim();
+    for (const line of [text.trim(), envelope, ...text.trim().split(/\n/).reverse()]) {
       try {
         const value = JSON.parse(line);
+        if (["native_hook_phase", "process_maintenance_phase"].includes(value?.kind)) continue;
         const error = value?.error;
         if (typeof error?.code === "string" && error.code) return reportedError(error, fallback);
         if (typeof value?.code === "string" && value.code) return reportedError({ ...value, message: typeof error === "string" ? error : value.message }, fallback);
       } catch { /* Not a structured CLI error line. */ }
     }
   }
+  if (retainedError) return reportedError(retainedError, fallback);
   return failure(stderr.trim() || stdout.trim() || fallback, fallbackCode);
 }
 
@@ -23,49 +34,136 @@ function processTarget(executable, args) {
   return /\.[cm]?js$/.test(executable) ? { command: process.execPath, args: [executable, ...args] } : { command: executable, args };
 }
 
-export async function commandJson(bin, args, { cwd, env = {}, input = null, onProgress = null } = {}) {
+// These are utility/transport children, never a second productive-work owner.
+async function command(bin, args, json, { cwd, env = {}, input = null, onProgress = null,
+  timeoutMs = 30_000, phase = "utility", signal = null, onDiagnostic = null } = {}) {
+  if (timeoutMs !== null) validateObservationDuration(timeoutMs);
+  if (timeoutMs === null && phase !== "native-work") throw new RangeError("only native-work may omit the utility quiet timeout");
+  if (signal?.aborted) throw signal.reason ?? failure("command aborted", "command_aborted");
+  const executable = bin === "dd-flow" && typeof env.DD_FLOW_BIN === "string" ? env.DD_FLOW_BIN : bin;
+  const target = processTarget(executable, json ? [...args, "--json"] : args);
   return await new Promise((resolve, reject) => {
-    // A canonical runtime may intentionally shadow the ambient `dd-flow`
-    // executable with its captured engine.  Keep that choice in the supplied
-    // environment rather than letting a host-global shim leak into a run.
-    const executable = bin === "dd-flow" && typeof env.DD_FLOW_BIN === "string" ? env.DD_FLOW_BIN : bin;
-    const target = processTarget(executable, [...args, "--json"]);
-    const child = spawn(target.command, target.args, { cwd, env: { ...process.env, ...env }, stdio: [input === null ? "ignore" : "pipe", "pipe", "pipe"] });
-    let stdout = ""; let stderr = ""; let pendingStderr = ""; let settled = false; let progressError = null;
-    const finish = (error, value) => { if (settled) return; settled = true; error ? reject(error) : resolve(value); };
-    const deliverProgress = (line) => {
-      let value; try { value = JSON.parse(line); } catch { return; }
-      if (typeof onProgress !== "function" || progressError) return;
-      try { const returned = onProgress(value); if (returned && typeof returned.then === "function") { Promise.resolve(returned).catch(() => {}); throw failure("commandJson onProgress must be synchronous", "progress_callback_async"); } }
-      catch (error) { progressError = error; child.kill("SIGKILL"); }
+    const child = spawn(target.command, target.args, { cwd, env: { ...process.env, ...env },
+      detached: process.platform !== "win32", stdio: [input === null ? "ignore" : "pipe", "pipe", "pipe"] });
+    const maxOutput = 8 * 1024 * 1024, maxTail = 64 * 1024, maxLine = 1024 * 1024;
+    let stdout = "", stderr = "", pendingStderr = "", settled = false, primary = null, cursor = 0, droppingStructured = false;
+    let outputBytes = 0, cleanupTimer = null, inputError = null, termination = null, retainedError = null, prettyError = "";
+    const phases = new Set();
+    const clock = timeoutMs === null ? null : new ObservationClock({ timeoutMs });
+    const productive = () => { cursor++; clock?.sample(cursor, Date.now()); };
+    const finish = (error, value) => {
+      if (settled) return; settled = true;
+      clearInterval(timer); clearTimeout(cleanupTimer); signal?.removeEventListener("abort", abort);
+      error ? reject(error) : resolve(value);
     };
-    child.stdout.setEncoding("utf8").on("data", (data) => { stdout += data; });
-    child.stderr.setEncoding("utf8").on("data", (data) => {
-      stderr += data; pendingStderr += data;
+    const stop = error => {
+      if (primary || settled) return;
+      primary = error;
+      termination = terminateCommandTree(child).catch(cause => { if (cause.code !== "ESRCH") primary.cleanup_error = cause; });
+      // A missing close after owned SIGKILL is cleanup uncertainty, not success.
+      cleanupTimer = setTimeout(() => {
+        primary.cleanup_error ??= failure("owned utility child did not close", "command_cleanup_unconfirmed");
+        finish(primary);
+      }, 5_000);
+    };
+    const abort = () => stop(signal.reason ?? failure("command aborted", "command_aborted"));
+    const deliverProgress = line => {
+      let value;
+      // Parse a bounded whole pretty envelope before its diagnostic bytes leave
+      // the tail. An oversized envelope cannot become plain-text keepalive.
+      if (prettyError === null) { if (line.trimEnd() === "}") prettyError = ""; return; }
+      const candidate = prettyError ? `${prettyError}\n${line}` : line;
+      if (prettyError && candidate.length > maxTail) { prettyError = null; return; }
+      try { value = JSON.parse(candidate); prettyError = ""; }
+      catch {
+        if (!prettyError && !line.trimStart().startsWith("{")) { productive(); return; }
+        prettyError = candidate.length > maxTail ? null : candidate; return;
+      }
+      const kind = value?.kind;
+      const passive = ["heartbeat", "poll", "status", "elapsed", "wait", "waiting"].some(marker => [kind, value?.phase, value?.action].includes(marker));
+      if (!["native_hook_phase", "process_maintenance_phase"].includes(kind)) {
+        const error = typeof value?.error?.code === "string" && value.error.code ? value.error
+          : typeof value?.code === "string" && value.code ? { ...value, message: typeof value.error === "string" ? value.error : value.message } : null;
+        // Retain one bounded typed summary independently of the diagnostic tail.
+        // It is consulted only on failed exit, after authoritative stdout.
+        if (error) retainedError = errorRecord(error);
+      }
+      if (["native_hook_phase", "process_maintenance_phase"].includes(kind)) {
+        const marker = JSON.stringify([kind, value.phase, value.operation_id ?? value.process_id]);
+        if (typeof value.phase === "string" && !passive && !phases.has(marker)) { phases.add(marker); productive(); }
+      } else if (!passive) productive();
+      if (typeof onProgress !== "function" || primary) return;
+      try {
+        const returned = onProgress(value);
+        if (returned && typeof returned.then === "function") {
+          Promise.resolve(returned).catch(() => {});
+          throw failure("command onProgress must be synchronous", "progress_callback_async");
+        }
+      } catch (error) { stop(error); }
+    };
+    const diagnostic = (data, stream) => {
+      try {
+        const returned = onDiagnostic?.(data, stream);
+        if (returned && typeof returned.then === "function") {
+          Promise.resolve(returned).catch(() => {});
+          throw failure("command onDiagnostic must be synchronous", "progress_callback_async");
+        }
+      } catch (error) { stop(error); }
+    };
+    const timer = clock ? setInterval(() => {
+      if (clock.sample(cursor)) stop(Object.assign(failure("command observation became quiet", "command_observation_lost"),
+        { details: { phase, timeout_ms: timeoutMs, observation_lost: clock.observationLost } }));
+    }, Math.max(1, Math.min(1_000, timeoutMs / 4))) : null;
+    clock?.sample(cursor);
+    signal?.addEventListener("abort", abort, { once: true });
+    child.stdout.setEncoding("utf8").on("data", data => {
+      productive();
+      diagnostic(data, "stdout"); outputBytes += Buffer.byteLength(data);
+      if (outputBytes > maxOutput) stop(failure("command final output exceeds 8 MiB", "command_output_limit"));
+      else stdout += data;
+    });
+    child.stderr.setEncoding("utf8").on("data", data => {
+      diagnostic(data, "stderr"); stderr = (stderr + data).slice(-maxTail);
+      if (droppingStructured) {
+        const end = data.indexOf("\n");
+        if (end < 0) return;
+        data = data.slice(end + 1); droppingStructured = false;
+      }
+      pendingStderr += data;
       for (;;) {
         const end = pendingStderr.indexOf("\n"); if (end < 0) break;
         const line = pendingStderr.slice(0, end); pendingStderr = pendingStderr.slice(end + 1);
-        deliverProgress(line);
+        if (line.length <= maxLine) deliverProgress(line);
+      }
+      if (pendingStderr && prettyError === "" && !pendingStderr.trimStart().startsWith("{")) productive();
+      // Plain streaming diagnostics are not the final reply and cannot kill a
+      // productive operation merely because their cumulative size is large.
+      if (pendingStderr.length > maxLine) {
+        droppingStructured = prettyError !== "" || pendingStderr.trimStart().startsWith("{");
+        pendingStderr = droppingStructured ? "" : pendingStderr.slice(-maxTail);
       }
     });
-    child.once("error", (error) => finish(progressError ?? error));
-    if (input !== null) child.stdin.end(input);
-    child.on("close", (status) => {
+    child.once("error", error => { if (!child.pid) finish(primary ?? error); else stop(error); });
+    if (input !== null) {
+      child.stdin.on("error", error => { inputError = error; if (error.code !== "EPIPE") stop(error); });
+      child.stdin.end(input);
+    }
+    child.once("close", status => {
       if (pendingStderr) deliverProgress(pendingStderr);
-      if (progressError) return finish(progressError);
-      if (status !== 0) return finish(reportedFailure(stdout, stderr, `${executable} exited ${status}`));
-      try { const value = JSON.parse(stdout.trim()); if (value?.ok === false) { const error = value.error && typeof value.error === "object" ? value.error : value; if (typeof error.code === "string") return finish(reportedError(error, `${bin} returned an error envelope`)); } finish(null, value); }
-      catch (error) { finish(failure(`${bin} returned invalid JSON: ${error.message}`, "flow_reconciliation_failed")); }
+      if (primary) { void (termination ?? Promise.resolve()).then(() => finish(primary)); return; }
+      if (status !== 0) return finish(reportedFailure(stdout, stderr, `${executable} exited ${status}`, json ? "flow_reconciliation_failed" : "command_failed", retainedError));
+      if (!json) return finish(inputError, stdout.trim());
+      try {
+        const value = JSON.parse(stdout.trim());
+        if (value?.ok === false) {
+          const error = value.error && typeof value.error === "object" ? value.error : value;
+          return finish(reportedError(error, `${bin} returned an error envelope`));
+        }
+        if (inputError) return finish(inputError);
+        finish(null, value);
+      } catch (error) { finish(failure(`${bin} returned invalid JSON: ${error.message}`, "flow_reconciliation_failed")); }
     });
   });
 }
-
-export async function commandText(bin, args, { cwd, env = {} } = {}) {
-  return await new Promise((resolve, reject) => {
-    const executable = bin === "dd-flow" && typeof env.DD_FLOW_BIN === "string" ? env.DD_FLOW_BIN : bin;
-    const target = processTarget(executable, args);
-    const child = spawn(target.command, target.args, { cwd, env: { ...process.env, ...env }, stdio: ["ignore", "pipe", "pipe"] }); let stdout = ""; let stderr = "";
-    child.stdout.setEncoding("utf8").on("data", (data) => { stdout += data; }); child.stderr.setEncoding("utf8").on("data", (data) => { stderr += data; }); child.on("error", reject);
-    child.on("close", (status) => status === 0 ? resolve(stdout.trim()) : reject(failure(stderr.trim() || stdout.trim() || `${executable} exited ${status}`, "command_failed")));
-  });
-}
+export async function commandJson(bin, args, options = {}) { return await command(bin, args, true, options); }
+export async function commandText(bin, args, options = {}) { return await command(bin, args, false, options); }

package/dist/harness-runtime/lib/tool-observations.d.mts

@@ -6,6 +6,7 @@ export interface ToolEvent {
   reason?: string;
   [key: string]: unknown;
 }
+export function classifyCodexItem(type: unknown): "tool" | "non_tool" | "unknown";
 export class ToolObservations {
   calls: Map<string, ToolEvent>;
   turns: Map<string, { session: { harness_id: string; session_id: string }; turn_id: string; started: boolean; completed: boolean }>;

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

@@ -128,11 +128,14 @@ function structuredFailure(value) {
 
 const codexTools = new Set(["commandExecution", "fileChange", "mcpToolCall", "dynamicToolCall", "collabAgentToolCall", "webSearch", "imageView", "imageGeneration", "sleep"]);
 const codexNonTools = new Set(["userMessage", "hookPrompt", "agentMessage", "functionCallOutput", "plan", "reasoning", "subAgentActivity", "enteredReviewMode", "exitedReviewMode", "contextCompaction"]);
+export function classifyCodexItem(type) {
+  return codexTools.has(type) ? "tool" : codexNonTools.has(type) ? "non_tool" : "unknown";
+}
 export function codexAppServerObservation(message) {
   if (!["item/started", "item/completed"].includes(message?.method)) return null;
   const { threadId, turnId, item } = message.params ?? {};
-  if (!item || codexNonTools.has(item.type)) return null;
-  if (!codexTools.has(item.type)) return { reason: "codex_item_type_unsupported" };
+  if (!item || classifyCodexItem(item.type) === "non_tool") return null;
+  if (classifyCodexItem(item.type) === "unknown") return { reason: "codex_item_type_unsupported" };
   if (!threadId || !item.id) return { reason: "tool_identity_missing" };
   const native = item.status;
   const failed = ["failed", "declined", "interrupted"].includes(native) || item.type === "commandExecution" && typeof item.exitCode === "number" && item.exitCode !== 0;

package/dist/harness-runtime/lib/zcode-usage.mjs

@@ -26,8 +26,9 @@ export function normalizeZcodeUsage(usage, read) {
     totals.requestOutputTokens += tokens.output;
     for (const [key, value] of [["requestReasoningTokens", tokens.reasoning],
       ["requestCacheCreationTokens", tokens.cache?.write], ["requestCacheReadTokens", tokens.cache?.read]]) {
-      if (value !== undefined && !valid(value)) incomplete = true;
-      else totals[key] += value ?? 0;
+      if (value == null) totals[key] = null;
+      else if (!valid(value)) incomplete = true;
+      else if (totals[key] !== null) totals[key] += value;
     }
     totals.requestCount++;
   }

package/dist/runtime/context.js

@@ -1,18 +1,22 @@
 import { getDatabase } from "../storage/database.js";
 import { resolveDdFlowHome } from "../storage/paths.js";
-export function createRouterContext(env) {
+import { assertImportAdmission } from "../storage/import-guard.js";
+export function createRouterContext(env, deadlineAt) {
     const ddFlowHome = resolveDdFlowHome(env);
     return {
         ddFlowHome,
-        db: getDatabase(ddFlowHome, "read_existing"),
+        db: getDatabase(ddFlowHome, "read_existing", undefined, deadlineAt),
         now: () => new Date().toISOString()
     };
 }
-export function createContext(env, mode = "initialize", importPermitId) {
+export function createContext(env, mode = "initialize", importPermitId, options = {}) {
     const ddFlowHome = resolveDdFlowHome(env);
+    if (options.resourceDatabaseMode === "prepared_existing" || options.resourceDatabaseMode === "initialize")
+        assertImportAdmission(ddFlowHome, importPermitId);
     return {
         ddFlowHome,
-        db: getDatabase(ddFlowHome, mode, importPermitId, mode === "hook" && env.DD_FLOW_HOOK_DEADLINE_AT ? Number(env.DD_FLOW_HOOK_DEADLINE_AT) : undefined),
+        db: getDatabase(ddFlowHome, mode, importPermitId, options.databaseDeadlineAt ?? (mode === "hook" && env.DD_FLOW_HOOK_DEADLINE_AT ? Number(env.DD_FLOW_HOOK_DEADLINE_AT) : undefined)),
+        ...options,
         env,
         now: () => new Date().toISOString()
     };

package/dist/schemas/flow-run.schema.json

@@ -13,6 +13,7 @@
     "subject": {"$ref": "#/definitions/identity"},
     "flow_kind": {"type": "string", "minLength": 1},
     "verification_matrix_contract": {"const": "dd-flow/verification-matrix@1"},
+    "final_check_coverage_contract": {"const": "dd-flow/final-check-coverage@1"},
     "status": {"enum": ["created", "running", "paused", "waiting_for_user", "done", "failed", "blocked", "cancelled", "discarded"]},
     "verdict": {"type": ["string", "null"]},
     "started_at": {"type": "string", "format": "date-time"},

package/dist/schemas/plan-review-decision.schema.json

@@ -1,14 +1,14 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "dd-flow/plan-review-decision@3",
+  "$id": "dd-flow/plan-review-decision@4",
   "type": "object",
   "additionalProperties": false,
   "required": ["schema_id", "outcome", "summary", "finding_decisions", "correction"],
   "properties": {
-    "schema_id": {"const": "dd-flow/plan-review-decision@3"},
+    "schema_id": {"const": "dd-flow/plan-review-decision@4"},
     "outcome": {"enum": ["accepted", "failed", "cancelled"]},
     "summary": {"type": "string", "minLength": 1},
-    "finding_decisions": {"type": "array", "items": {"type": "object", "additionalProperties": false, "required": ["finding_ref", "decision", "reason"], "properties": {"finding_ref": {"type": "string", "pattern": "^WRK-[^/]+/FIND-[0-9]{3}$"}, "decision": {"enum": ["accepted_fix", "rejected", "deferred_as_DEF", "requires_user", "duplicate"]}, "reason": {"type": "string", "minLength": 1}}}},
+    "finding_decisions": {"type": "array", "items": {"type": "object", "additionalProperties": false, "required": ["finding_ref", "decision", "reason"], "properties": {"finding_ref": {"type": "string", "pattern": "^WRK-[^/]+/FIND-[0-9]{3}$"}, "decision": {"enum": ["accepted_fix", "rejected", "deferred_as_DEF", "requires_user", "duplicate"]}, "reason": {"type": "string", "minLength": 1}, "duplicate_of": {"type": "string", "pattern": "^WRK-[^/]+/FIND-[0-9]{3}$"}, "def_id": {"type": "string", "pattern": "^DEF-[A-Za-z0-9][A-Za-z0-9_-]*$"}}}},
     "correction": {"type": "object", "additionalProperties": false, "required": ["status", "previous_plan_revision", "changed_paths", "summary"], "properties": {"status": {"enum": ["applied", "not_required"]}, "previous_plan_revision": {"type": "integer", "minimum": 1}, "changed_paths": {"type": "array", "items": {"type": "string", "minLength": 1}}, "summary": {"type": "string", "minLength": 1}}}
   }
 }

package/dist/schemas/run-control-receipt.schema.json

@@ -49,6 +49,25 @@
     "reused": { "type": "boolean" },
     "next_cursor": { "type": "integer", "minimum": 0 },
     "run_status": { "type": "string" },
+    "finalization": {
+      "type": ["object", "null"], "additionalProperties": false,
+      "required": ["schema_id", "issuer", "phase", "project_root", "run_id", "controller_id", "generation", "controller_status", "run_status", "status", "owner", "capture", "error"],
+      "properties": {
+        "schema_id": { "const": "dd-flow/terminal-finalization@1" },
+        "issuer": { "const": "dd-flow" },
+        "phase": { "const": "terminal_finalization" },
+        "project_root": { "type": "string", "minLength": 1 },
+        "run_id": { "type": "string", "minLength": 1 },
+        "controller_id": { "type": "string", "minLength": 1 },
+        "generation": { "type": "integer", "minimum": 0 },
+        "controller_status": { "enum": ["recovery_required", "capture_failed"] },
+        "run_status": { "enum": ["done", "failed", "cancelled"] },
+        "status": { "enum": ["pending", "blocked"] },
+        "owner": { "enum": ["live", "absent", "unknown"] },
+        "capture": { "enum": ["recorded", "missing"] },
+        "error": { "type": "object" }
+      }
+    },
     "control": { "type": ["object", "null"] },
     "operations": { "type": "array", "items": { "type": "object" } },
     "worker": { "type": ["object", "null"] },