@deksden-com/dd-flow-cli 0.9.0-beta.124 → 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/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"] },

package/dist/services/code-checks.js

@@ -1,6 +1,7 @@
 import crypto from "node:crypto";
 import { isGitlessWorkspace, ownedWorkspaceHookPath, projectServicePathFilter, workspaceGitFiles } from "./workspace-files.js";
 import { spawn, spawnSync } from "node:child_process";
+import { ObservationClock, validateObservationDuration } from "../harness-runtime/lib/observation-clock.mjs";
 import fs from "node:fs";
 import path from "node:path";
 import { isDeepStrictEqual } from "node:util";
@@ -8,7 +9,8 @@ import { parse } from "shell-quote";
 import { assertRunMutationAllowed } from "./run-recovery.js";
 import { AppError, errorRecord } from "../shared/errors.js";
 import { stopProcessGroup } from "../harness-runtime/lib/managed-daemon.mjs";
-import { confirmManagedProcess, finishManagedProcess, heartbeatManagedProcess, managedProcessStatus, managedProcessRuntimeHome, managedOwnerIsAlive, processTreeIsAlive, registerManagedProcess, reservePorts } from "./managed-processes.js";
+import { createRenewalState, maintenanceRetryable, renewalConfirmed, renewalDelay, renewalFailure, renewalRemaining, RENEWAL_POLICY } from "../harness-runtime/lib/lease-renewal.mjs";
+import { confirmManagedProcess, finishManagedProcess, renewManagedProcess, managedProcessStatus, managedProcessRuntimeHome, managedOwnerIsAlive, processTreeIsAlive, registerManagedProcess, reservePorts } from "./managed-processes.js";
 import { admitRuntimeCheck, runtimeBudgetForRun } from "./runtime-budget.js";
 import { getResourceDatabase } from "../storage/database.js";
 const profileRelativePath = path.join(".memory-bank", "spec", "engineering", "code-check-profile.json");
@@ -234,6 +236,8 @@ function assertDirectCheckExecutable(workspaceRoot, command, checkId) {
     if (!program)
         return;
     const probe = spawnSync("/bin/sh", ["-c", "command -v -- \"$1\" >/dev/null", "dd-flow-check", program], { cwd: workspaceRoot, env, encoding: "utf8", timeout: 5000 });
+    if (probe.error || probe.signal)
+        throw new AppError("check_command_probe_unavailable", "Executable probe could not be observed; availability is unknown", 2, { check_id: checkId, executable: program, cause: probe.error?.message, signal: probe.signal });
     if (probe.status !== 0)
         throw new AppError("check_command_unavailable", "Available CODE check names an executable that is unavailable in this environment", 2, { check_id: checkId, command, executable: program });
 }
@@ -331,7 +335,7 @@ async function runCodeChecksOwned(context, input, workspaceGateId, generation) {
                     assertRunMutationAllowed(context, input.projectId, input.runId, generation);
                     if (budget)
                         admitRuntimeCheck(context, managed.id, managed.lease_token);
-                }, () => heartbeatManagedProcess(context, { id: managed.id, leaseToken: managed.lease_token }));
+                }, attemptMs => renewManagedProcess({ ...context, resourceDatabaseMode: "prepared_existing", databaseDeadlineAt: Date.now() + attemptMs }, { id: managed.id, leaseToken: managed.lease_token }));
             }
             finally {
                 fs.closeSync(stdout);
@@ -423,7 +427,7 @@ export function reconcileUnfinishedChecks(context, input) {
         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 };
+            const repaired = { ...receipt, completion_path: receipt.completion_path || path.join(path.dirname(pendingReceipt.receipt_path), "completion.json"), required_artifacts: receipt.required_artifacts ?? [], ...(status === "aborted" ? { abort_reason: "completion_marker_missing" } : {}), 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);
         }
@@ -487,7 +491,7 @@ function reserveOrReuseReceipt(context, input) {
         return { reserved };
     }, "checks.reserveOrReuseReceipt");
 }
-function receiptFor(input) { return { id: input.id, local_id: input.localId, declaration_id: input.group.declarations[0].id, check_refs: input.group.declarations.map(checkRef), gate: input.group.gate, scope: input.scope, work_id: input.workId ?? null, command: input.group.command, input_hash: input.inputHash, verification_epoch: input.epoch, retry_of_receipt_id: input.retryOf ?? null, retry_reason: input.retryReason ?? null, status: input.status, exit_code: input.status === "running" ? null : input.result.exitCode, stdout_path: input.stdoutPath, stderr_path: input.stderrPath, receipt_path: input.receiptPath, completion_path: input.completionPath, required_artifacts: input.group.requiredArtifacts, inputs: input.group.inputs, workspace_fingerprint: input.before.fingerprint, before_fingerprint: input.before.fingerprint, after_fingerprint: input.after.fingerprint, profile_hash: input.profileHash, mutation_paths: input.mutationPaths, artifacts: input.artifacts, resources: { ports: input.resources }, started_at: input.startedAt, finished_at: input.status === "running" ? input.startedAt : new Date().toISOString() }; }
+function receiptFor(input) { return { id: input.id, local_id: input.localId, declaration_id: input.group.declarations[0].id, check_refs: input.group.declarations.map(checkRef), gate: input.group.gate, scope: input.scope, work_id: input.workId ?? null, command: input.group.command, input_hash: input.inputHash, verification_epoch: input.epoch, retry_of_receipt_id: input.retryOf ?? null, retry_reason: input.retryReason ?? null, status: input.status, ...(input.status === "aborted" ? { abort_reason: input.result.error } : {}), exit_code: input.status === "running" ? null : input.result.exitCode, stdout_path: input.stdoutPath, stderr_path: input.stderrPath, receipt_path: input.receiptPath, completion_path: input.completionPath, required_artifacts: input.group.requiredArtifacts, inputs: input.group.inputs, workspace_fingerprint: input.before.fingerprint, before_fingerprint: input.before.fingerprint, after_fingerprint: input.after.fingerprint, profile_hash: input.profileHash, mutation_paths: input.mutationPaths, artifacts: input.artifacts, resources: { ports: input.resources }, started_at: input.startedAt, finished_at: input.status === "running" ? input.startedAt : new Date().toISOString() }; }
 function writeReceipt(file, receipt) { const temporary = `${file}.tmp-${process.pid}-${crypto.randomUUID()}`; fs.writeFileSync(temporary, `${JSON.stringify(receipt, null, 2)}\n`); fs.renameSync(temporary, file); }
 function readReceipt(file) { try {
     return JSON.parse(fs.readFileSync(file, "utf8"));
@@ -820,15 +824,23 @@ function listFiles(root) {
     });
     return visit(root).filter(file => file.split(path.sep).join("/") !== ownedHook).sort();
 }
-export function runCheck(command, cwd, environment, stdout, stderr, heartbeat, onSpawn, renewLease) {
+export function runCheck(command, cwd, environment, stdout, stderr, heartbeat, onSpawn, renewLease, observation = {}) {
+    const inactivityTimeoutMs = validateObservationDuration(observation.inactivityTimeoutMs ?? 30 * 60_000);
     return new Promise((resolve) => {
         const started = Date.now();
-        const child = spawn("/bin/sh", ["-c", checkShellScript()], { cwd, env: { ...environment, DD_FLOW_CHECK_COMMAND: command }, stdio: ["pipe", stdout, stderr], detached: process.platform !== "win32" });
+        const child = spawn("/bin/sh", ["-c", checkShellScript()], { cwd, env: { ...environment, DD_FLOW_CHECK_COMMAND: command }, stdio: ["pipe", "pipe", "pipe"], detached: process.platform !== "win32" });
         let error = null;
         let stopping = false;
+        let closed = false;
         let progress;
         let cleanup;
         let cleanupUnconfirmed = false;
+        const renewal = createRenewalState();
+        let renewalTimer;
+        const clock = new ObservationClock({ timeoutMs: inactivityTimeoutMs });
+        let outputCursor = 0;
+        const outputs = [fs.createWriteStream("", { fd: stdout, autoClose: false }), fs.createWriteStream("", { fd: stderr, autoClose: false })];
+        const flushed = outputs.map(output => new Promise(resolve => { output.once("finish", resolve); output.once("error", () => resolve()); }));
         const stop = (cause) => {
             if (stopping)
                 return;
@@ -838,20 +850,41 @@ export function runCheck(command, cwd, environment, stdout, stderr, heartbeat, o
                 clearInterval(progress);
                 progress = undefined;
             }
+            if (renewalTimer)
+                clearTimeout(renewalTimer);
+            if (observationTimer)
+                clearInterval(observationTimer);
             cleanup = stopProcessGroup(child, 5_000).catch(cause => {
                 cleanupUnconfirmed = true;
                 error = `${error}; cleanup: ${JSON.stringify(errorRecord(cause))}`;
                 resolve({ exitCode: null, error, aborted: true, cleanupUnconfirmed });
             });
         };
+        const observationTimer = setInterval(() => {
+            if (stopping || closed || observation.phase?.() === "serving")
+                return;
+            if (clock.sample(outputCursor))
+                stop(new AppError("operation_observation_lost", "Owned command has no confirmed progress within its inactivity window", 1, { phase: observation.phase?.() ?? "finite", inactivity_timeout_ms: inactivityTimeoutMs }));
+        }, Math.min(1000, inactivityTimeoutMs));
         // Register handlers before checking pid or calling persistence callbacks.
         // Failure is not completion until the spawned process has actually closed.
         child.once("error", (value) => { error = value.message; });
+        for (const [index, stream] of [child.stdout, child.stderr].entries()) {
+            outputs[index].once("error", stop);
+            stream.on("data", () => { outputCursor++; clock.sample(outputCursor); });
+            stream.pipe(outputs[index]);
+        }
         child.stdin.on("error", stop);
         child.once("close", async (exitCode, signal) => {
+            closed = true;
             if (progress)
                 clearInterval(progress);
+            if (renewalTimer)
+                clearTimeout(renewalTimer);
+            if (observationTimer)
+                clearInterval(observationTimer);
             await cleanup;
+            await Promise.all(flushed);
             resolve({ exitCode, error: error ?? (signal ? `terminated by ${signal}` : null), aborted: stopping || Boolean(signal) || Boolean(error), ...(cleanupUnconfirmed ? { cleanupUnconfirmed } : {}) });
         });
         if (!child.pid) {
@@ -866,18 +899,55 @@ export function runCheck(command, cwd, environment, stdout, stderr, heartbeat, o
             return;
         }
         child.stdin.end("admitted\n");
-        progress = setInterval(() => {
+        clock.sample(outputCursor);
+        const renew = () => {
+            if (stopping || closed)
+                return;
+            if (renewalTimer) {
+                clearTimeout(renewalTimer);
+                renewalTimer = undefined;
+            }
             try {
-                if (!renewLease()) {
+                renewal.uncertainSince ??= performance.now();
+                const remaining = renewalRemaining(renewal);
+                if (!remaining) {
+                    stop("managed process renewal budget exhausted");
+                    return;
+                }
+                const receipt = renewLease(Math.min(RENEWAL_POLICY.attemptMs, remaining));
+                if (receipt === false || typeof receipt === "object" && !receipt.owned) {
                     stop("managed process lease lost");
                     return;
                 }
+                if (typeof receipt === "object" && receipt.owned) {
+                    const expiry = Date.parse(receipt.lease_expires_at);
+                    if (!Number.isFinite(expiry))
+                        throw new AppError("managed_lease_receipt_invalid", "Check renewal returned invalid expiry", 1);
+                    if (expiry <= Date.now())
+                        throw Object.assign(new Error("Check renewal receipt expired before acknowledgement"), { code: "process_maintenance_timeout" });
+                }
+                if (!renewalRemaining(renewal) || !renewalConfirmed(renewal)) {
+                    stop("managed process renewal budget exhausted");
+                    return;
+                }
+            }
+            catch (cause) {
+                if (!maintenanceRetryable(cause) || !renewalFailure(renewal)) {
+                    stop(cause);
+                    return;
+                }
+                renewalTimer = setTimeout(renew, Math.min(renewalDelay(renewal), renewalRemaining(renewal)));
+                return;
+            }
+            // A progress callback error is not a retryable renewal failure.
+            try {
                 heartbeat(Math.floor((Date.now() - started) / 1000));
             }
             catch (cause) {
                 stop(cause);
             }
-        }, 15_000);
+        };
+        progress = setInterval(renew, 15_000);
     });
 }
 function checkShellScript() {