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

package/dist/harness-runtime/lib/native-children.d.mts

@@ -0,0 +1,13 @@
+export const NATIVE_CHILD_CONTRACT_VERSION: "native-children@1";
+export interface NativeChild {
+  session_id: string;
+  parent_session_id: string;
+  status: "running" | "unknown" | "completed" | "failed" | "cancelled" | "settled_by_root";
+  source: string;
+  provenance?: "root_child" | "parent_mismatch";
+  terminal_turn_id?: string;
+  terminal_observed_at?: string;
+  provider_error?: unknown;
+  native_turn_items?: { observed?: boolean; possible_effects?: boolean; pending?: boolean };
+}
+export function normalizeNativeChildren(receipt: Record<string, unknown>, rootSessionId: string): NativeChild[];

package/dist/harness-runtime/lib/native-children.mjs

@@ -0,0 +1,78 @@
+export const NATIVE_CHILD_CONTRACT_VERSION = "native-children@1";
+import { errorRecord } from "./operation-errors.mjs";
+
+function nativeFailure(code, message, exitCode, details) { return Object.assign(new Error(message), { code, exitCode, details }); }
+
+
+/** Normalize provider-observed topology only; never parse assistant prose. */
+export function normalizeNativeChildren(receipt, rootSessionId) {
+  const candidates = [];
+  const object = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : {};
+  receipt = object(receipt);
+  const list = (value) => Array.isArray(value) ? value : [];
+  const text = (value, keys) => { for (const key of keys) if (typeof value[key] === "string" && value[key]) return value[key]; return null; };
+  const settledTree = new Set(
+    list(receipt.tree_observations)
+      .filter(value => object(value).settled === true)
+      .map(value => text(object(value), ["provider_session_id", "session_id"]))
+      .filter(id => id !== null)
+  );
+  const add = (raw, source, scopedParent = null, fallback = "unknown") => {
+    const value = object(raw);
+    const id = text(value, ["provider_session_id", "session_id", "sessionId", "childSessionId", "conversation_id", "conversationId", "id", "subagentId"]);
+    const parent = text(value, ["parent_provider_session_id", "parent_session_id", "parentSessionId", "parentID", "parentId"]) ?? scopedParent;
+    if (!id) return;
+    const outcomeError = object(value.outcome_error);
+    if (typeof outcomeError.code === "string") {
+      const record = errorRecord(outcomeError);
+      throw Object.assign(nativeFailure(record.code, record.message, 1, record.details), record, { details: { ...object(record.details), session_id: id, source } });
+    }
+    const state = String(value.status ?? value.state ?? fallback).toLowerCase();
+    if (state === "lost") throw nativeFailure("native_child_outcome_lost", "Native child ended without a recoverable outcome", 1, { session_id: id, parent_session_id: parent, source, native_status: state });
+    // Provider idle means no current activity, not a Work result. Only an
+    // explicit terminal result or a separately proven root settlement may be
+    // terminal here; unknown states stay unknown for reconciliation.
+    const status = ["completed", "complete", "done", "success", "succeeded"].includes(state) ? "completed" : state === "settled_by_root" ? "settled_by_root" : ["failed", "error"].includes(state) ? "failed" : ["cancelled", "canceled", "interrupted"].includes(state) ? "cancelled" : ["running", "active", "pending"].includes(state) ? "running" : fallback;
+    const rootChild = parent === rootSessionId;
+    const settled = rootChild && status === "unknown" && settledTree.has(id) ? "settled_by_root" : status;
+    candidates.push({ session_id: id, parent_session_id: parent ?? "", status: settled, source, ...(rootChild ? {} : { provenance: "parent_mismatch" }),
+      ...(text(value, ["terminal_turn_id"]) ? { terminal_turn_id: text(value, ["terminal_turn_id"]) } : {}),
+      ...(text(value, ["terminal_observed_at"]) ? { terminal_observed_at: text(value, ["terminal_observed_at"]) } : {}),
+      ...(value.provider_error !== undefined ? { provider_error: value.provider_error } : {}),
+      ...(value.native_turn_items && typeof value.native_turn_items === "object" ? { native_turn_items: value.native_turn_items } : {}) });
+  };
+  for (const value of list(receipt.descendants)) add(value, "adapter.descendants");
+  for (const value of list(receipt.children)) add(value, "opencode.session.children");
+  const subagents = object(object(receipt.evidence).subagents ?? receipt.subagents);
+  for (const value of list(subagents.running)) add(value, "zcode/session/subagents", rootSessionId, "running");
+  for (const value of list(subagents.completed)) add(value, "zcode/session/subagents", rootSessionId, "completed");
+  for (const value of list(object(subagents.ended).items)) {
+    const status = String(object(value).status ?? "unknown");
+    if (!["success", "failed", "cancelled", "lost"].includes(status)) throw nativeFailure("native_child_outcome_unavailable", "ZCode ended child has no recognized native outcome", 1, { child: value });
+    add(value, "zcode/session/subagents", rootSessionId);
+  }
+  const unique = new Map();
+  const rank = { unknown: 0, running: 1, settled_by_root: 2, completed: 3, failed: 3, cancelled: 3 };
+  for (const child of candidates) {
+    const previous = unique.get(child.session_id);
+    if (previous && previous.parent_session_id !== child.parent_session_id) {
+      // Keep the contradictory parent visible to the existing provenance gate,
+      // independently of input order or which source happened to say success.
+      const foreign = [previous, child].filter(item => item.parent_session_id !== rootSessionId).sort((a, b) => a.parent_session_id.localeCompare(b.parent_session_id))[0];
+      unique.set(child.session_id, { ...foreign, provenance: "parent_mismatch" });
+      continue;
+    }
+    if (previous && rank[previous.status] === 3 && rank[child.status] === 3 && previous.status !== child.status) throw nativeFailure("native_child_outcome_conflict", "Native child has contradictory terminal outcomes", 1, { session_id: child.session_id, observations: [previous, child] });
+    if (previous && previous.status === child.status && previous.terminal_turn_id && child.terminal_turn_id && previous.terminal_turn_id !== child.terminal_turn_id)
+      throw nativeFailure("native_child_turn_conflict", "Native child has contradictory terminal Turn identities", 1, { session_id: child.session_id, observations: [previous, child] });
+    if (previous && previous.status === child.status) {
+      unique.set(child.session_id, { ...previous, ...child,
+        ...(child.terminal_turn_id ?? previous.terminal_turn_id ? { terminal_turn_id: child.terminal_turn_id ?? previous.terminal_turn_id } : {}),
+        ...(child.provider_error ?? previous.provider_error ? { provider_error: child.provider_error ?? previous.provider_error } : {}),
+        ...(child.native_turn_items ?? previous.native_turn_items ? { native_turn_items: child.native_turn_items ?? previous.native_turn_items } : {}) });
+      continue;
+    }
+    if (!previous || rank[child.status] > rank[previous.status]) unique.set(child.session_id, child);
+  }
+  return [...unique.values()].sort((left, right) => left.session_id.localeCompare(right.session_id));
+}

package/dist/harness-runtime/lib/native-hook-command.d.mts

@@ -1,3 +1,7 @@
 export function invokeNativeHook(input: { bin: string; args: string[]; payload: unknown; home?: string | undefined; cwd?: string; env?: NodeJS.ProcessEnv; timeoutMs?: number }): Promise<Record<string, unknown> & { timing?: Record<string, number> }>;
 export function hookBudget(timeoutMs?: number, deadlineAt?: number | null): { deadlineAt: number; remaining(phase: string, maximum?: number): number; run<T>(action: () => T | Promise<T>, phase: string): Promise<T> };
 export function readNativeHookInput(stream: NodeJS.ReadStream, budget: { remaining(phase: string): number }, maxBytes?: number): Promise<string>;
+export function acceptNativeHookRequest(stateDir: string, binding: Record<string, unknown>, current?: { requests: Map<string, { binding: Record<string, unknown> }>; accepting?: Map<string, Promise<Record<string, unknown>>> } | null): Promise<Record<string, unknown>>;
+export function writeNativeHookFailure(stateDir: string, binding: Record<string, unknown> | undefined, error: unknown, budget: ReturnType<typeof hookBudget>): Promise<void>;
+export function readNativeHookFailures(stateDir: string, requests: Map<string, { current: unknown; binding: Record<string, unknown> }>, current: unknown, reject: (error: Error & { code?: string; details?: Record<string, unknown> }) => void): Promise<void>;
+export function runBoundedCommand(input: { bin: string; args: string[]; input?: string | null; cwd?: string; env?: NodeJS.ProcessEnv; timeoutMs?: number; timeoutCode?: string; inheritDeadline?: boolean; cleanupWithinBudget?: boolean; maintenanceProgress?: { action: string; processId: string | null; inactivityMs: number } | null; signal?: AbortSignal }): Promise<string>;

package/dist/harness-runtime/lib/native-hook-command.mjs

@@ -1,5 +1,65 @@
 import { spawn } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
 import { reportedFailure } from "./process-json.mjs";
+import { errorRecord, reportedError } from "./operation-errors.mjs";
+import { writeJsonAtomic } from "./runner-events.mjs";
+
+/** Retain accepted native requests in the existing operation hook ledger. */
+export async function acceptNativeHookRequest(stateDir, binding, current = null) {
+  if (["operation_id", "daemon_id", "tool_call_id", "root_provider_session_id", "provider_session_id"].some(key => typeof binding[key] !== "string" || !binding[key])
+    || !Number.isSafeInteger(binding.turn_generation) || binding.turn_generation < 0
+    || !/^[a-f0-9]{64}$/.test(binding.command_sha256 ?? "")) throw Object.assign(new Error("Native hook has no current owned operation"), { code: "native_hook_unproven" });
+  const key = JSON.stringify([binding.provider_session_id, binding.tool_call_id, binding.event]);
+  const existing = current && [...current.requests.values()].find(value => JSON.stringify([value.binding.provider_session_id, value.binding.tool_call_id, value.binding.event]) === key)?.binding;
+  const same = value => {
+    if (value.command_sha256 !== binding.command_sha256 || value.native_cwd !== binding.native_cwd) throw Object.assign(new Error("Native tool identity was reused with changed hook input"), { code: "native_hook_identity_conflict" });
+    return value;
+  };
+  if (existing) return same(existing);
+  current && (current.accepting ??= new Map());
+  if (current?.accepting.has(key)) return same(await current.accepting.get(key));
+  const accepted = (async () => {
+  const directory = path.join(stateDir, "operations", createHash("sha256").update(binding.operation_id).digest("hex"));
+  const requested = JSON.parse(await readFile(path.join(directory, "requested.json"), "utf8"));
+  if (requested.operation_id !== binding.operation_id || requested.daemon_id !== binding.daemon_id || !["session.prompt", "session.create", "session.start"].includes(requested.operation)
+    || requested.operation === "session.prompt" && requested.session_id && requested.session_id !== binding.root_provider_session_id) throw Object.assign(new Error("Native hook operation does not match its retained owner"), { code: "native_hook_unproven" });
+  const receipt = { ...binding, schema_id: "dd-flow/hook-request@1", request_id: randomUUID() };
+  await writeJsonAtomic(path.join(directory, "hooks", `${receipt.request_id}.json`), receipt);
+  return receipt;
+  })();
+  current?.accepting.set(key, accepted);
+  try { return await accepted; } finally { current?.accepting.delete(key); }
+}
+
+export async function writeNativeHookFailure(stateDir, binding, error, budget) {
+  if (!binding?.request_id || !/^[A-Za-z0-9-]{1,128}$/.test(binding.request_id)) return;
+  await budget.run(() => writeJsonAtomic(path.join(stateDir, "hook-failures", `${binding.request_id}.json`), {
+    ...errorRecord(error), request_id: binding.request_id, observed_at: new Date().toISOString(), native_hook_binding: binding,
+  }), "failure_receipt");
+}
+
+/** Read only requests accepted for this exact live operation, never scan a mailbox. */
+export async function readNativeHookFailures(stateDir, requests, current, reject) {
+  for (const [id, accepted] of requests) {
+    if (accepted.current !== current) continue;
+    let value;
+    try { value = JSON.parse(await readFile(path.join(stateDir, "hook-failures", `${id}.json`), "utf8")); }
+    catch (error) { if (error.code === "ENOENT") continue; value = { code: "native_hook_receipt_invalid", message: error.message }; }
+    if (value.request_id !== id || !value.native_hook_binding || JSON.stringify(value.native_hook_binding) !== JSON.stringify(accepted.binding) || typeof value.code !== "string" || typeof value.message !== "string") {
+      if (!accepted.diagnostic) {
+        accepted.diagnostic = { code: "native_hook_receipt_invalid", message: "Accepted hook request has an unreadable or unbound failure receipt", request_id: id, operation_id: accepted.binding.operation_id, effect: "unknown", receipt_bound: false };
+        process.stderr.write(`${JSON.stringify({ native_hook_diagnostic: accepted.diagnostic })}\n`);
+      }
+      continue;
+    }
+    requests.delete(id);
+    const error = reportedError(value, "Native hook failed");
+    error.details = { ...error.details, native_hook_binding: accepted.binding };
+    reject(error);
+  }
+}
 
 /** The caller supplies its qualified native limit; phases share that deadline. */
 export function hookBudget(timeoutMs = 25_000, deadlineAt = process.env.DD_FLOW_HOOK_DEADLINE_AT === undefined ? null : Number(process.env.DD_FLOW_HOOK_DEADLINE_AT)) {
@@ -9,7 +69,7 @@ export function hookBudget(timeoutMs = 25_000, deadlineAt = process.env.DD_FLOW_
   const remaining = (phase, maximum = duration) => {
     const value = duration - (performance.now() - started);
     if (value <= 0) throw Object.assign(new Error(`Native hook deadline exceeded during ${phase}`), { code: "native_hook_timeout", details: { phase, elapsed_ms: Math.round(performance.now() - started), effect: "unknown" } });
-    return Math.max(1, Math.min(maximum, value));
+    return Math.max(1, Math.floor(Math.min(maximum, value)));
   };
   return { deadlineAt: Math.floor(Date.now() + duration), remaining, async run(action, phase) {
     const timeoutMs = remaining(phase);
@@ -57,26 +117,35 @@ export async function terminateCommandTree(child, { platform = process.platform,
 }
 
 /** Preserve the native hook protocol across the CLI process boundary. */
-export async function runBoundedCommand({ bin, args, input = null, cwd, env = {}, timeoutMs = 15_000, timeoutCode = "native_hook_timeout" }) {
-  const inherited = env.DD_FLOW_HOOK_DEADLINE_AT ?? process.env.DD_FLOW_HOOK_DEADLINE_AT;
+export async function runBoundedCommand({ bin, args, input = null, cwd, env = {}, timeoutMs = 15_000, timeoutCode = "native_hook_timeout", inheritDeadline = true, cleanupWithinBudget = false, maintenanceProgress = null, signal }) {
+  if (signal?.aborted) throw Object.assign(new Error("Bounded CLI request cancelled before launch"), { code: "process_maintenance_cancelled", details: { effect: "no_effect" } });
+  const inherited = inheritDeadline ? env.DD_FLOW_HOOK_DEADLINE_AT ?? process.env.DD_FLOW_HOOK_DEADLINE_AT : undefined;
   if (inherited !== undefined) {
     const deadline = Number(inherited);
     if (!Number.isSafeInteger(deadline) || deadline < 0) throw Object.assign(new Error("Invalid native hook deadline"), { code: "hook_deadline_invalid", details: { effect: "no_effect" } });
     timeoutMs = Math.min(timeoutMs, deadline - Date.now());
   }
   if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) throw Object.assign(new Error("Native hook budget exhausted before subprocess launch"), { code: timeoutCode, details: { phase: "subprocess", effect: "no_effect" } });
+  if (maintenanceProgress && (!Number.isFinite(maintenanceProgress.inactivityMs) || maintenanceProgress.inactivityMs <= 0
+    || typeof maintenanceProgress.action !== "string" || !(maintenanceProgress.processId === null || typeof maintenanceProgress.processId === "string")))
+    throw Object.assign(new Error("Invalid maintenance progress budget"), { code: "process_maintenance_timeout", details: { effect: "no_effect", native_dispatch_started: false } });
   const started = performance.now();
   // Transport/physical cleanup has its own small tail inside the outer limit.
-  const deadlineAt = Math.floor(Date.now() + Math.max(0, timeoutMs - Math.min(250, timeoutMs / 10)));
+  const cleanupMs = Math.min(500, timeoutMs / 5);
+  const commandMs = cleanupWithinBudget ? Math.max(1, timeoutMs - cleanupMs) : timeoutMs;
+  const deadlineAt = Math.floor(Date.now() + Math.max(0, commandMs - Math.min(250, commandMs / 10)));
   const script = /\.[cm]?js$/.test(bin);
   const output = await new Promise((resolve, reject) => {
     const child = spawn(script ? process.execPath : bin, [...(script ? [bin] : []), ...args], {
       cwd, env: { ...process.env, ...env, DD_FLOW_HOOK_DEADLINE_AT: String(deadlineAt) }, detached: process.platform !== "win32", stdio: ["pipe", "pipe", "pipe"]
     });
     let stdout = "", stderr = "", failure, cleanupTimer, settled = false, termination;
+    let timer, phaseBuffer = "", lastProgress = started;
+    const progressPhases = new Set();
+    const commandDeadline = started + commandMs;
     const finish = (error, value) => {
       if (settled) return;
-      settled = true; clearTimeout(timer); clearTimeout(cleanupTimer);
+      settled = true; clearTimeout(timer); clearTimeout(cleanupTimer); signal?.removeEventListener("abort", abort);
       if (error) {
         const diagnostics = hookDiagnostics(stderr);
         if (diagnostics.length) error.details = { ...error.details, hook_diagnostics: diagnostics };
@@ -86,7 +155,8 @@ export async function runBoundedCommand({ bin, args, input = null, cwd, env = {}
     const stop = error => {
       if (termination || settled) return;
       failure ??= error;
-      failure.details = { ...failure.details, elapsed_ms: Math.round(performance.now() - started), effect: "unknown" };
+      clearTimeout(timer);
+      failure.details = { ...failure.details, elapsed_ms: Math.round(performance.now() - started), effect: "unknown", subprocess_pid: child.pid ?? null };
       termination = terminateCommandTree(child).catch(cleanup => {
         if (cleanup.code === "ESRCH") return;
         failure.details.cleanup_error = { code: cleanup.code, message: cleanup.message };
@@ -97,11 +167,45 @@ export async function runBoundedCommand({ bin, args, input = null, cwd, env = {}
         failure.details.cleanup_unconfirmed = true;
         child.stdin.destroy(); child.stdout.destroy(); child.stderr.destroy(); child.unref();
         finish(failure);
-      }, 500);
+      }, cleanupWithinBudget ? cleanupMs : 500);
     };
-    const timer = setTimeout(() => stop(Object.assign(new Error("Bounded CLI request timed out"), { code: timeoutCode })), timeoutMs);
+    // A useful, request-bound phase advances the silence window, not ownership
+    // authority. The child storage deadline and parent uncertainty horizon stay
+    // fixed; repeated phases, logging and polling cannot keep a writer alive.
+    const arm = () => {
+      clearTimeout(timer);
+      const now = performance.now();
+      const remaining = Math.min(commandDeadline - now, maintenanceProgress ? lastProgress + maintenanceProgress.inactivityMs - now : Infinity);
+      if (remaining <= 0) { stop(Object.assign(new Error("Bounded CLI request timed out"), { code: timeoutCode })); return; }
+      timer = setTimeout(arm, Math.ceil(remaining));
+    };
+    arm();
+    const abort = () => stop(Object.assign(new Error("Bounded CLI request cancelled"), { code: "process_maintenance_cancelled" }));
+    signal?.addEventListener("abort", abort, { once: true });
+    if (signal?.aborted) abort();
     child.stdout.setEncoding("utf8").on("data", chunk => { stdout += chunk; if (stdout.length > 1_048_576) stop(new Error("Native hook response exceeds protocol limit")); });
-    child.stderr.setEncoding("utf8").on("data", chunk => { stderr = (stderr + chunk).slice(-65_536); });
+    // Match the existing response bound: a legal bounded error tree may exceed
+    // 64KiB when pretty-printed, plus maintenance phases preceding the receipt.
+    child.stderr.setEncoding("utf8").on("data", chunk => {
+      stderr = (stderr + chunk).slice(-1_048_576);
+      if (!maintenanceProgress || termination || settled) return;
+      phaseBuffer += chunk;
+      const lines = phaseBuffer.split("\n"); phaseBuffer = lines.pop().slice(-16_384);
+      for (const line of lines) {
+        if (line.length > 16_384) continue;
+        let phase; try { phase = JSON.parse(line); } catch { continue; }
+        if (phase?.kind !== "process_maintenance_phase" || phase.action !== maintenanceProgress.action
+          || (phase.process_id ?? null) !== maintenanceProgress.processId || phase.native_dispatch_started !== false
+          || !["request", "store_open", "store_validation", "lookup", "writer_reservation", "writer_reserved", "write", "commit", "committed", "ack"].includes(phase.phase)
+          || phase.store_kind !== undefined && !["run", "resource"].includes(phase.store_kind)) continue;
+        const key = `${phase.store_kind ?? ""}:${phase.phase}`;
+        if (progressPhases.has(key)) continue;
+        // Delayed observation cannot revive an already-expired silence window.
+        const now = performance.now();
+        if (now >= commandDeadline || now - lastProgress >= maintenanceProgress.inactivityMs) { arm(); return; }
+        progressPhases.add(key); lastProgress = now; arm();
+      }
+    });
     child.stdin.on("error", error => { failure ??= error; });
     child.on("error", error => finish(failure ?? error));
     child.on("close", code => {
@@ -121,10 +225,10 @@ function hookDiagnostics(stderr) {
   return stderr.split("\n").flatMap(line => {
     try {
       const value = JSON.parse(line);
-      if (value?.kind !== "native_hook_phase") return [];
+      if (!["native_hook_phase", "process_maintenance_phase"].includes(value?.kind)) return [];
       const phase = typeof value.phase === "string" && /^[a-z_]{1,48}$/.test(value.phase) ? value.phase : null;
       if (!phase) return [];
-      return [{ phase, ...Object.fromEntries(["elapsed_ms", "remaining_ms", "sqlite_extended_code"].filter(key => Number.isFinite(value[key])).map(key => [key, value[key]])) }];
+      return [{ phase, ...Object.fromEntries(["elapsed_ms", "remaining_ms", "sqlite_extended_code"].filter(key => Number.isFinite(value[key])).map(key => [key, value[key]])), ...(value.kind === "process_maintenance_phase" ? { ...Object.fromEntries(["action", "process_id", "operation_id", "lease_expires_at", "store_kind", "maintenance_effect", "attempt_kind", "role"].filter(key => typeof value[key] === "string" && /^[A-Za-z0-9:._-]{1,128}$/.test(value[key])).map(key => [key, value[key]])), ...(typeof value.native_dispatch_started === "boolean" ? { native_dispatch_started: value.native_dispatch_started } : {}) } : {}) }];
     } catch { return []; }
   }).slice(-16);
 }

package/dist/harness-runtime/lib/native-streams.mjs

@@ -0,0 +1,45 @@
+// Async iteration backpressures the native pipe while its existing evidence
+// sink drains. Bound one JSON reply, never lifetime diagnostics.
+export const MAX_NATIVE_LINE_BYTES = 8 * 1024 * 1024;
+export async function readNativeLines(stream, onLine, onError) {
+  let buffer = "";
+  stream.setEncoding("utf8");
+  try {
+    for await (const chunk of stream.iterator({ destroyOnReturn: false })) {
+      buffer += chunk;
+      let at;
+      while ((at = buffer.indexOf("\n")) >= 0) {
+        const line = buffer.slice(0, at); buffer = buffer.slice(at + 1);
+        assertLine(line);
+        if (line.trim()) await onLine(line);
+      }
+      assertLine(buffer);
+    }
+    if (buffer.trim()) { assertLine(buffer); await onLine(buffer); }
+  } catch (cause) { stream.pause(); await observationFailure(cause, onError); }
+}
+export function assertNativeLine(line, phase = "reply") {
+  if (Buffer.byteLength(line) > MAX_NATIVE_LINE_BYTES) throw Object.assign(new Error(`Native JSON ${phase} exceeds the bounded capture limit`), { code: phase === "request" ? "native_request_limit" : "operation_observation_lost", details: { reason: `native_${phase}_limit`, limit_bytes: MAX_NATIVE_LINE_BYTES, ...(phase === "request" ? { effect: "no_effect" } : { native_outcome: "unknown" }) } });
+}
+const assertLine = assertNativeLine;
+export function admitNativeRequestBuffer(buffer, socket, schema) {
+  try { assertNativeLine(buffer, "request"); return true; }
+  catch (error) { socket.pause(); socket.end(`${JSON.stringify({ schema_id: schema, id: null, ok: false, error: { code: error.code, message: error.message, details: error.details } })}\n`, () => socket.destroy()); return false; }
+}
+export function retainNativeReplyBuffer(buffer, finish) {
+  try { assertNativeLine(buffer); return true; }
+  catch (error) { finish(error); return false; }
+}
+export async function streamNativeDiagnostics(stream, onChunk, onError) {
+  stream.setEncoding("utf8");
+  try { for await (const chunk of stream.iterator({ destroyOnReturn: false })) await onChunk(String(chunk)); }
+  catch (cause) { stream.pause(); await observationFailure(cause, onError); }
+}
+async function observationFailure(cause, onError) {
+  const error = nativeObservationError(cause);
+  try { await onError(error); }
+  catch (publication) { error.cleanup_error ??= { code: publication.code ?? null, message: publication.message }; }
+}
+export function nativeObservationError(cause, details = {}) {
+  return !cause.code || /^[A-Z_]+$/.test(cause.code) ? Object.assign(new Error("Native evidence reader failed", { cause }), { code: "operation_observation_lost", details: { native_outcome: "unknown", observation_error: { code: cause.code ?? null, message: cause.message }, ...details } }) : cause;
+}

package/dist/harness-runtime/lib/observation-clock.d.mts

@@ -0,0 +1,18 @@
+export const OBSERVATION_CLOCK_CONTRACT_VERSION: "operation-progress@1";
+export function validateObservationDuration(value: number, label?: string): number;
+export interface ObservationState {
+  policy: string; timeout_ms: number; started_at: number; cursor?: unknown;
+  observed_at: number | null; elapsed_ms: number; uncertainty_elapsed_ms: number;
+  gaps: number; observation_lost: boolean;
+}
+export class ObservationClock {
+  constructor(options: { timeoutMs: number; gapMs?: number; uncertaintyMs?: number;
+    wall?: () => number; monotonic?: () => number; onGap?: (value: Record<string, unknown>) => void;
+    saved?: ObservationState | null });
+  observationLost: boolean;
+  sample(progress?: unknown, progressAt?: number): boolean;
+  state(): ObservationState;
+}
+export function observedTimeout(callback: (clock: ObservationClock) => void, timeoutMs: number,
+  options?: { gapMs?: number; uncertaintyMs?: number; wall?: () => number; monotonic?: () => number;
+    onGap?: (value: Record<string, unknown>) => void; progress?: () => unknown; saved?: ObservationState | null }): ReturnType<typeof setInterval>;

package/dist/harness-runtime/lib/observation-clock.mjs

@@ -1,36 +1,92 @@
-/** Only observed time counts toward inactivity. A scheduling/clock gap is not
- * evidence of OS sleep, nor of provider progress. Call sample regularly. */
+export const OBSERVATION_CLOCK_CONTRACT_VERSION = "operation-progress@1";
+export function validateObservationDuration(value, label = "observation duration") {
+  if (!Number.isSafeInteger(value) || value < 1 || value > 2_147_483_647)
+    throw new RangeError(`${label} must be integer milliseconds in 1..2147483647`);
+  return value;
+}
+
+/** Only observed monotonic time is silence. A clock gap is uncertainty, never
+ * progress or proof of provider failure. Durable snapshots retain that episode. */
 export class ObservationClock {
-  constructor({ timeoutMs, gapMs = 60_000, wall = Date.now, monotonic = () => performance.now(), onGap = () => {} }) {
-    if (!(timeoutMs > 0) || !(gapMs > 0)) throw new RangeError("positive observation timeout and gap required");
-    Object.assign(this, { timeoutMs, gapMs, wall, monotonic, onGap });
-    this.lastWall = wall(); this.lastMono = monotonic(); this.elapsed = 0;
-    this.progress = undefined;
+  constructor({ timeoutMs, gapMs = 60_000, uncertaintyMs = 120_000, wall = Date.now,
+    monotonic = () => performance.now(), onGap = () => {}, saved = null }) {
+    validateObservationDuration(timeoutMs); validateObservationDuration(gapMs, "gap duration");
+    validateObservationDuration(uncertaintyMs, "observation recovery duration");
+    Object.assign(this, { timeoutMs, gapMs, uncertaintyMs, wall, monotonic, onGap });
+    this.lastWall = wall(); this.lastMono = monotonic(); this.startedWall = this.lastWall;
+    this.elapsed = 0; this.progress = undefined; this.progressAt = null;
+    this.uncertain = false; this.uncertaintyElapsed = 0; this.gaps = 0; this.observationLost = false;
+    if (saved) {
+      if (saved.policy !== OBSERVATION_CLOCK_CONTRACT_VERSION || saved.timeout_ms !== timeoutMs
+        || !Number.isFinite(saved.started_at) || !Number.isSafeInteger(saved.gaps) || saved.gaps < 0
+        || saved.observed_at !== null && !Number.isFinite(saved.observed_at)
+        || typeof saved.observation_lost !== "boolean"
+        || !Number.isFinite(saved.elapsed_ms) || saved.elapsed_ms < 0
+        || !Number.isFinite(saved.uncertainty_elapsed_ms) || saved.uncertainty_elapsed_ms < 0)
+        throw new RangeError("invalid retained observation clock");
+      this.startedWall = saved.started_at; this.elapsed = saved.elapsed_ms;
+      this.progress = saved.cursor; this.progressAt = saved.observed_at;
+      // A reconstructed observer cannot prove silence during its absence.
+      this.uncertain = true; this.gaps = saved.gaps + 1;
+      this.uncertaintyElapsed = saved.uncertainty_elapsed_ms;
+      this.observationLost = saved.observation_lost || this.gaps > 1 || this.uncertaintyElapsed >= uncertaintyMs;
+    }
   }
   sample(progress, progressAt) {
+    if (progress && typeof progress === "object" && Object.hasOwn(progress, "cursor")) {
+      progressAt = progress.observed_at; progress = progress.cursor;
+    }
     const wall = this.wall(), mono = this.monotonic();
     const delta = mono - this.lastMono, wallDelta = wall - this.lastWall;
-    const gap = delta > this.gapMs || wallDelta > this.gapMs || delta < 0 || wallDelta < 0;
+    const gap = !Number.isFinite(delta) || !Number.isFinite(wallDelta)
+      || delta > this.gapMs || wallDelta > this.gapMs || delta < 0 || wallDelta < 0;
     if (gap) {
+      this.uncertain = true; this.gaps++;
       this.onGap({ source: "observer_clock", classification: "observation_gap", confirmed_sleep: false,
-        started_at: new Date(this.lastWall).toISOString(), observed_at: new Date(wall).toISOString(),
+        started_at: Number.isFinite(this.lastWall) ? this.lastWall : null, observed_at: Number.isFinite(wall) ? wall : null,
         wall_delta_ms: wallDelta, monotonic_delta_ms: delta });
-      this.elapsed = 0;
-    } else this.elapsed += delta;
+    } else {
+      this.elapsed += delta;
+      if (this.uncertain) this.uncertaintyElapsed += delta;
+    }
     this.lastWall = wall; this.lastMono = mono;
-    if (progress !== undefined && progress !== this.progress) {
-      this.progress = progress;
-      this.elapsed = !gap && Number.isFinite(progressAt) ? Math.max(0, Math.min(this.timeoutMs, wall - progressAt)) : 0;
+    const validCursor = typeof progress === "string" || typeof progress === "boolean"
+      || typeof progress === "number" && Number.isFinite(progress);
+    const changed = validCursor && progress !== this.progress;
+    const timestamped = progressAt !== undefined;
+    const validTime = !timestamped ? wall >= this.startedWall && (this.progressAt === null || wall >= this.progressAt)
+      : Number.isFinite(progressAt) && progressAt >= this.startedWall
+      && progressAt <= wall && (this.progressAt === null || progressAt >= this.progressAt);
+    if (changed && validTime && !this.observationLost) {
+      const eventAt = timestamped ? progressAt : wall;
+      // A delayed pre-gap event cannot establish that observation has recovered.
+      const recovers = !this.uncertain || eventAt >= wall - Math.max(0, gap ? 0 : delta);
+      this.progress = progress; this.progressAt = eventAt;
+      this.elapsed = Math.max(0, wall - eventAt);
+      if (recovers) { this.uncertain = false; this.gaps = 0; this.uncertaintyElapsed = 0; }
+    }
+    if (changed && timestamped && Number.isFinite(progressAt) && !validTime && progressAt > wall) {
+      if (!this.uncertain) this.onGap({ source: "observer_clock", classification: "clock_skew",
+        confirmed_sleep: false, observed_at: wall, signal_at: progressAt });
+      this.uncertain = true;
     }
-    return this.elapsed >= this.timeoutMs;
+    if (this.uncertain && (this.gaps > 1 || this.uncertaintyElapsed >= this.uncertaintyMs)) this.observationLost = true;
+    return this.observationLost || !this.uncertain && this.elapsed >= this.timeoutMs;
+  }
+  state() {
+    return { policy: OBSERVATION_CLOCK_CONTRACT_VERSION, timeout_ms: this.timeoutMs,
+      started_at: this.startedWall, cursor: this.progress, observed_at: this.progressAt,
+      elapsed_ms: this.elapsed, uncertainty_elapsed_ms: this.uncertaintyElapsed,
+      gaps: this.gaps, observation_lost: this.observationLost };
   }
 }
 
-/** Node timeout handle: callers can keep their existing clearTimeout cleanup. */
+/** Node timer handle, compatible with existing clearTimeout cleanup. */
 export function observedTimeout(callback, timeoutMs, options = {}) {
   const clock = new ObservationClock({ timeoutMs, ...options });
   const timer = setInterval(() => {
-    if (clock.sample(options.progress?.())) { clearInterval(timer); callback(); }
+    const snapshot = options.progress?.();
+    if (clock.sample(snapshot)) { clearInterval(timer); callback(clock); }
   }, Math.max(1, Math.min(1_000, timeoutMs / 4)));
   return timer;
 }

package/dist/harness-runtime/lib/operation-errors.d.mts

@@ -0,0 +1,14 @@
+export const OPERATION_ERROR_CONTRACT_VERSION: "operation-errors@2";
+export interface ErrorRecord {
+  code: string;
+  message: string;
+  retryable?: boolean;
+  exitCode?: number;
+  details?: unknown;
+  cause?: ErrorRecord;
+  cleanup_error?: ErrorRecord;
+}
+export function errorRecord(error: unknown, depth?: number): ErrorRecord;
+export function isObservationLoss(error: unknown): boolean;
+export function isProvenShellCorrection(error: unknown): boolean;
+export function reportedError(value: Record<string, unknown>, fallback: string): Error & ErrorRecord;

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

@@ -1,16 +1,113 @@
 // An observer losing its response does not establish that a provider Turn failed.
+export const OPERATION_ERROR_CONTRACT_VERSION = "operation-errors@2";
+// Only use after the native delivery/operation owner has been verified.
+export function isProvenShellCorrection(error) {
+  const details = error?.details;
+  return error?.code === "lifecycle_shell_syntax_invalid" && details?.phase === "prepare"
+    && details.effect === "no_effect" && details.recoverable === true
+    && details.disposition === "pre_cli_shell_refusal" && details.cli_admission_barrier === true
+    && typeof details.issued_invocation_id === "string" && details.issued_invocation_id.trim().length > 0
+    && typeof details.event_key === "string" && details.event_key.trim().length > 0;
+}
 export function isObservationLoss(error) {
-  return ["rpc_timeout", "native_timeout", "native_outcome_unknown", "native_backend_dead", "native_backend_pipe_broken", "bridge_exited", "bridge_pipe_broken", "daemon_timeout", "turn_timeout", "operation_observation_lost", "daemon_connection_closed"].includes(error?.code);
+  return ["rpc_timeout", "native_timeout", "native_outcome_unknown", "native_backend_dead", "native_backend_pipe_broken", "bridge_exited", "bridge_pipe_broken", "daemon_timeout", "turn_timeout", "operation_observation_lost", "daemon_connection_closed", "harness_adapter_timeout", "harness_adapter_output_limit", "harness_adapter_invalid", "subject_liveness_timeout", "command_observation_lost", "command_output_limit", "operation_output_limit"].includes(error?.code);
 }
 
-export function errorRecord(error, depth = 0) {
-  return {
-    code: typeof error?.code === "string" ? error.code : "operation_failed",
-    message: typeof error?.message === "string" ? error.message : String(error),
-    ...(typeof error?.retryable === "boolean" ? { retryable: error.retryable } : {}),
-    ...(error?.details !== undefined ? { details: error.details } : {}),
-    ...(error?.cause && depth < 3 ? { cause: errorRecord(error.cause, depth + 1) } : {}),
+function field(value, key) { try { return value?.[key]; } catch { return "[unreadable]"; } }
+function text(value) { try { return String(value); } catch { return "[unreadable]"; } }
+function boundedText(value, budget, limit = 16000) {
+  let result = value.slice(0, limit);
+  if (Buffer.byteLength(JSON.stringify(result)) > budget.remaining) result = result.slice(0, Math.max(0, Math.floor(budget.remaining / 6)));
+  budget.remaining -= Buffer.byteLength(JSON.stringify(result));
+  return result;
+}
+// Lifecycle controls are not optional diagnostics. Reserve them before bulk
+// messages/details, including nested typed causes, without copying authority
+// that was truncated into a different command or continuation receipt.
+const operationalDetailKeys = ["phase", "effect", "recoverable", "retryable_no_effect", "handoff_required", "storage_retry", "repeated_without_progress", "cleanup_unconfirmed", "native_dispatch_started", "disposition", "cli_admission_barrier", "native_pre_cli_refusal", "issued_invocation_id", "invocation_id", "event_key", "refusal_event_key", "hook_event_id", "work_id", "hook_retry_signature", "rejection_signature", "retry_command", "repair_command", "continuation", "retry_instruction", "recovery_instruction", "authority_truncated"];
+function operationalDetails(value, budget) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const entries = [];
+  let authorityTruncated = false;
+  for (const key of operationalDetailKeys) {
+    try { if (!Object.hasOwn(value, key)) continue; } catch { continue; }
+    const raw = field(value, key), reserved = { ...budget };
+    const name = boundedText(key, reserved), result = jsonDiagnostic(raw, 0, new Set(), reserved);
+    if (name !== key || typeof raw === "string" && result !== raw
+      || key === "continuation" && JSON.stringify(result).includes("[truncated]")) {
+      authorityTruncated ||= ["retry_command", "repair_command", "continuation"].includes(key);
+      continue;
+    }
+    Object.assign(budget, reserved);
+    entries.push([key, result]);
+  }
+  return { ...Object.fromEntries(entries), ...(authorityTruncated ? { recoverable: false, authority_truncated: true } : {}) };
+}
+function jsonDiagnostic(value, depth, seen, budget, excludedKeys = []) {
+  if (depth >= 12 || budget.remaining <= 0 || budget.nodes-- <= 0) return "[truncated]";
+  if (typeof value === "string") { const result = boundedText(value, budget); return result.length === value.length ? result : `${result}[truncated]`; }
+  if (value === null || typeof value === "boolean" || typeof value === "number" && Number.isFinite(value)) { budget.remaining -= String(value).length + 1; return value; }
+  if (typeof value !== "object") return "[unavailable]";
+  if (seen.has(value)) return "[circular]";
+  seen.add(value); budget.remaining -= 2;
+  let result;
+  try {
+    if (Array.isArray(value)) {
+      result = [];
+      for (let i = 0; i < Math.min(value.length, 256); i++) {
+        if (budget.remaining <= 0 || budget.nodes <= 0) { result.push("[truncated]"); break; }
+        result.push(jsonDiagnostic(field(value, i), depth + 1, seen, budget));
+      }
+      if (value.length > 256) result.push("[truncated]");
+    } else {
+      const entries = [];
+      // Error.message and the standard Error.cause are non-enumerable.
+      // Keep the original identity and shared bounds for nested diagnostics.
+      const errorFields = value instanceof Error ? ["message", "cause"].filter(key => field(value, key) !== undefined) : [];
+      for (const key of errorFields) {
+        if (budget.remaining <= 0 || budget.nodes <= 0) { entries.push(["[truncated]", true]); break; }
+        entries.push([boundedText(key, budget), jsonDiagnostic(field(value, key), depth + 1, seen, budget)]);
+      }
+      for (const key in value) {
+        if (!Object.hasOwn(value, key) || errorFields.includes(key) || excludedKeys.includes(key)) continue;
+        if (entries.length >= 256 || budget.remaining <= 0 || budget.nodes <= 0) { entries.push(["[truncated]", true]); break; }
+        const name = boundedText(key, budget);
+        entries.push([name, jsonDiagnostic(field(value, key), depth + 1, seen, budget)]);
+      }
+      result = Object.fromEntries(entries);
+    }
+  } catch { result = "[unreadable]"; }
+  seen.delete(value); return result;
+}
+
+function record(error, depth, seen, budget, pending) {
+  if (error && typeof error === "object") {
+    if (seen.has(error)) return { code: "diagnostic_cycle", message: "[circular]" };
+    seen.add(error);
+  }
+  const value = Object.fromEntries(["code", "message", "retryable", "exitCode", "details", "cause", "cleanup_error"].map(key => [key, field(error, key)]));
+  const result = {
+    code: boundedText(typeof value.code === "string" ? value.code : "operation_failed", budget),
+    ...(typeof value.retryable === "boolean" ? { retryable: value.retryable } : {}),
+    ...(typeof value.exitCode === "number" && Number.isFinite(value.exitCode) ? { exitCode: value.exitCode } : {}),
   };
+  pending.push([result, typeof value.message === "string" ? value.message : text(error), value.details]);
+  if (value.cause && value.cause !== "[unreadable]" && depth < 3) result.cause = record(value.cause, depth + 1, new Set(seen), budget, pending);
+  if (value.cleanup_error && value.cleanup_error !== "[unreadable]" && depth < 3) result.cleanup_error = record(value.cleanup_error, depth + 1, new Set(seen), budget, pending);
+  return result;
+}
+
+export function errorRecord(error, depth = 0, seen = new Set()) {
+  const budget = { remaining: 65536, nodes: 2048 }, pending = [];
+  // Reserve every typed code before messages and optional bulk details.
+  const result = record(error, depth, seen, budget, pending);
+  const controls = pending.map(([, , value]) => operationalDetails(value, budget));
+  for (const [target, message] of pending) target.message = boundedText(message, budget);
+  for (const [index, [target, , value]] of pending.entries()) if (value !== undefined) {
+    const details = jsonDiagnostic(value, 0, new Set(), budget, controls[index] ? operationalDetailKeys : []);
+    target.details = controls[index] ? { ...controls[index], ...(details && typeof details === "object" ? details : { "[truncated]": true }) } : details;
+  }
+  return result;
 }
 
 export function reportedError(value, fallback) {

package/dist/harness-runtime/lib/operation-progress.d.mts

@@ -0,0 +1,7 @@
+export const OPERATION_PROGRESS_CONTRACT: "dd-flow/operation-progress@1";
+export function operationDirectory(root: string, id: string): string;
+export function withOperationProgress<T>(root: string, id: string, action: () => T): T;
+export function readOperationRecord(root: string, id: string, name: string): Promise<Record<string, any> | null>;
+export function readOperationProgress(root: string, id: string, expected?: Record<string, unknown>): Promise<(Record<string, unknown> & { sequence: number; observed_at: string }) | null>;
+export function readOperationWaiting(root: string, id: string, expected?: Record<string, unknown>): Promise<boolean>;
+export function suspendOperationClock(clock: import("./observation-clock.mjs").ObservationClock): void;