@deksden-com/dd-flow-cli 0.9.0-beta.14 → 0.9.0-beta.141

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

@@ -0,0 +1,92 @@
+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, 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 = !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: Number.isFinite(this.lastWall) ? this.lastWall : null, observed_at: Number.isFinite(wall) ? wall : null,
+        wall_delta_ms: wallDelta, monotonic_delta_ms: delta });
+    } else {
+      this.elapsed += delta;
+      if (this.uncertain) this.uncertaintyElapsed += delta;
+    }
+    this.lastWall = wall; this.lastMono = mono;
+    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;
+    }
+    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 timer handle, compatible with existing clearTimeout cleanup. */
+export function observedTimeout(callback, timeoutMs, options = {}) {
+  const clock = new ObservationClock({ timeoutMs, ...options });
+  const timer = setInterval(() => {
+    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/opencode-plugin.mjs

@@ -0,0 +1,85 @@
+import path from "node:path";
+import { managedFlowEnv } from './managed-flow-env.mjs';
+import * as Plugin from "../vendor/opencode-plugin.mjs";
+import { hookBudget, invokeNativeHook, writeNativeHookFailure } from "./native-hook-command.mjs";
+import { callDaemon } from "./dd-opencode-daemon.mjs";
+import { errorRecord } from "./operation-errors.mjs";
+
+/** Launch-bound server plugin; never uses a process-global 'last Session'. */
+export function makeOpenCodePlugin(binding, invoke = invokeNativeHook, resolve = callDaemon) {
+  return Plugin.define({ id: binding.ddFlowBin ? "dd-flow" : "dd-flow-security", async setup(ctx) {
+    const participating = new Map();
+    const key = event => JSON.stringify([binding.daemonId, event.sessionID, event.messageID, event.id]);
+    const envelope = async (phase, event, budget, outcome) => {
+      const input = event.input;
+      if (!input || typeof input !== "object" || typeof input.command !== "string") throw new Error("OpenCode shell input is unavailable");
+      const identity = await budget.run(() => resolve(binding.stateDir, "hook.resolve", { sessionId: event.sessionID,
+        payload: { phase, message_id: event.messageID, tool_call_id: event.id, input } }, budget.remaining("identity")), "identity");
+      const info = identity?.nativeSession;
+      if (!identity?.nativeHookBinding || info?.id !== event.sessionID || !info.directory) throw Object.assign(new Error("OpenCode Session identity is unavailable"), { code: "native_hook_unproven" });
+      const cwd = path.resolve(info.directory, input.workdir ?? ".");
+      return { schema_id: "dd-flow/opencode-tool-event@1", native_protocol: 2,
+        native_hook_binding: identity.nativeHookBinding,
+        event_id: [binding.daemonId, event.sessionID, event.messageID, event.id].join(":"), phase,
+        daemon_id: binding.daemonId, server_version: binding.version, plugin_sha256: process.env.DD_OPENCODE_PLUGIN_SHA256,
+        session: { provider_session_id: info.id, parent_provider_session_id: info.parentID ?? null,
+          agent_id: event.agent, directory: cwd, project_id: info.projectID },
+        message_id: event.messageID, tool_call_id: event.id, tool: "shell", native_tool: event.tool,
+        profile: { provider: info.model?.providerID, model: info.model?.id, variant: info.model?.variant ?? "default", agent: event.agent },
+        input: { ...input, workdir: cwd }, ...(outcome ? { outcome } : {}) };
+    };
+    const deliver = async (payload, budget) => {
+      const identity = { nativeHookBinding: payload.native_hook_binding };
+      try {
+        const result = await invoke({ bin: binding.ddFlowBin, nodeBin: binding.nodeBin,
+          args: ["opencode", "event", "handle", "--project-root", binding.projectRoot, "--json"],
+          payload: { ...payload, native_hook_binding: identity.nativeHookBinding }, home: binding.ddFlowHome, timeoutMs: budget.remaining("admission", 15000) });
+        await budget.run(() => resolve(binding.stateDir, "hook.verify", { binding: identity.nativeHookBinding }, budget.remaining("generation")), "generation");
+        if (result?.permissionDecision === "deny" || result?.hookSpecificOutput?.permissionDecision === "deny") throw Object.assign(new Error("dd-flow denied native shell admission"), { code: "native_hook_rejected" });
+        return result;
+      } catch (error) {
+        error.details = { ...error.details, native_hook_binding: identity.nativeHookBinding, ...(payload.phase === "after" ? { effect: "unknown", tool_outcome: payload.outcome } : {}) };
+        try { await writeNativeHookFailure(binding.stateDir, identity.nativeHookBinding, error, hookBudget(1_000, null)); await resolve(binding.stateDir, "hook.failed", {}, 1_000); }
+        catch (storage) {
+          error.details.receipt_error = { code: storage.code ?? "hook_receipt_write_failed", message: storage.message };
+          try { await resolve(binding.stateDir, "hook.failed", { binding: identity.nativeHookBinding, failure: errorRecord(error) }, 1_000); }
+          catch (notify) { error.details.receipt_error.notification_error = notify.code ?? "hook_notification_failed"; }
+        }
+        throw error;
+      }
+    };
+    await ctx.shell.hook("create.before", event => {
+      Object.assign(event.env, managedFlowEnv(binding));
+      delete event.env.OPENCODE_PASSWORD; delete event.env.OPENCODE_SERVER_PASSWORD;
+    });
+    await ctx.tool.hook("execute.before", async event => {
+      if (event.tool !== "shell") return;
+      if (event.input.timeout === undefined) event.input.timeout = 0;
+      if (!binding.ddFlowBin) return;
+      const budget = hookBudget(), payload = await envelope("before", event, budget);
+      event.input = { ...event.input, workdir: payload.session.directory };
+      const result = await deliver({ ...payload, input: event.input }, budget);
+      if (result?.observed) {
+        participating.set(key(event), payload);
+        await ctx.storage.set(key(event), JSON.parse(JSON.stringify(payload)));
+        // The common observer, not OpenCode's fixed 120-second cutoff, owns
+        // flow CLI inactivity. No lifecycle process is detached here.
+        event.input = { ...event.input, ...(result.hookSpecificOutput?.updatedInput ?? {}), timeout: 0, background: false };
+      } else if (event.input.timeout === undefined) event.input.timeout = 0;
+    });
+    await ctx.tool.hook("execute.after", async event => {
+      if (event.tool !== "shell") return;
+      const budget = hookBudget(), original = participating.get(key(event)) ?? await ctx.storage.get(key(event));
+      if (!original) return; // Ordinary shell tools do not create lifecycle receipts.
+      const output = event.result?.output;
+      const success = event.status === "completed" && output?.status !== "running" && output?.exit === 0 && !output?.timeout && !output?.signal;
+      const outcome = { status: success ? "completed" : output?.status === "running" ? "running" : "failed",
+        exit_code: output?.exit ?? null, signal: output?.signal ?? null, shell_id: output?.shellID ?? null };
+      const payload = await envelope("after", event, budget, outcome);
+      await deliver({ ...payload, ...(original ? { event_id: original.event_id } : {}) }, budget);
+      participating.delete(key(event));
+      await ctx.storage.remove(key(event));
+    });
+    return () => participating.clear();
+  } });
+}

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

@@ -0,0 +1,5 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+// The existing runner operation owns its child driver requests, including calls
+// nested in Judge/HITL/fanout. Async context keeps parallel executions separate.
+export const operationContext = new AsyncLocalStorage();

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

@@ -0,0 +1,16 @@
+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 redactDiagnostic(value: string): string;
+export function diagnosticJson(value: unknown): string;
+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

@@ -0,0 +1,127 @@
+// An observer losing its response does not establish that a provider Turn failed.
+export const OPERATION_ERROR_CONTRACT_VERSION = "operation-errors@2";
+export function redactDiagnostic(value) {
+  return value.replace(/\b(Bearer|Basic)\s+[^\s"']+/gi, "$1 <redacted>")
+    .replace(/(^|[^\w-])([\w-]+)(["']?\s*[=:]\s*["']?)([^\s"',;&}]+)/g,
+      (whole, prefix, key, separator) => /token|secret|password|api[_-]?key|authorization/i.test(key)
+        ? `${prefix}${key}${separator}<redacted>` : whole)
+    .replace(/(\b[A-Za-z][A-Za-z0-9+.-]{0,31}:\/\/)[^\s/:@]+:[^\s/@]+@/g, "$1<redacted>@");
+}
+export function diagnosticJson(value) {
+  return JSON.stringify(value, (key, item) => /token|secret|password|api[_-]?key|authorization/i.test(key)
+    ? "<redacted>" : typeof item === "string" ? redactDiagnostic(item) : item, 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", "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);
+}
+
+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) {
+  const record = errorRecord({ ...value, message: value.message ?? fallback });
+  return Object.assign(new Error(record.message), record);
+}

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;

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

@@ -0,0 +1,114 @@
+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;
+    // A later successful ownership gate is fresh liveness evidence while admission waits.
+    if (prior && phase === prior.phase && phase !== 'native_progress'
+      && (phase !== 'ownership_confirmed' || Date.parse(observedAt) <= Date.parse(prior.observed_at))) 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.d.mts

@@ -0,0 +1,5 @@
+type Options = { cwd?: string; env?: NodeJS.ProcessEnv; input?: string | null; onProgress?: (value: unknown) => void; progress?: () => number; startupMs?: number | null; timeoutMs?: number | null; phase?: string; signal?: AbortSignal; onDiagnostic?: (data: string, stream: string) => void };
+export function reportedFailure(stdout: string, stderr: string, fallback: string, fallbackCode?: string, retainedError?: Record<string, unknown> | null): Error & import('./operation-errors.mjs').ErrorRecord;
+export function commandJson(bin: string, args: string[], options?: Options): Promise<Record<string, unknown>>;
+export function commandText(bin: string, args: string[], options?: Options): Promise<string>;
+export function commandResult(bin: string, args: string[], options?: Options): Promise<{exit_code: number | null; signal: string | null; stdout: string; stderr: string}>;