@deksden-com/dd-flow-cli 0.9.0-beta.16 → 0.9.0-beta.161

package/dist/harness-runtime/lib/opencode-plugin.mjs

@@ -0,0 +1,112 @@
+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, isNativeHookObservationLoss } 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 }, ...(binding.nativeWorkStartAdmission ? { deferWorkStart: true } : {}) }, budget.remaining("identity")), "identity");
+      if (identity.observationOnly === true) {
+        if (!binding.nativeWorkStartAdmission || identity.daemonId !== binding.daemonId || identity.sessionId !== event.sessionID
+          || identity.messageId !== event.messageID || identity.toolCallId !== event.id || identity.command !== input.command)
+          throw Object.assign(new Error("Ordinary native callback binding differs"), { code: "native_hook_unproven" });
+        return { observationOnly: true };
+      }
+      if (phase === "before" && identity.fastAck === true) {
+        const proof = identity.nativeHookBinding;
+        if (!binding.nativeWorkStartAdmission || proof?.native_admission !== "assigned_work_start" || proof.source_harness !== "opencode-server"
+          || proof.daemon_id !== binding.daemonId || proof.provider_session_id !== event.sessionID
+          || proof.tool_call_id !== `${event.messageID}:${event.id}` || proof.native_command !== input.command)
+          throw Object.assign(new Error("Deferred native callback binding differs"), { code: "native_hook_unproven" });
+        return { fastAck: true };
+      }
+      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, verified = false) => {
+      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") });
+        if (!verified) await budget.run(() => resolve(binding.stateDir, "hook.verify", { binding: identity.nativeHookBinding, retain_after: result?.observed === true }, 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 } : {}) };
+        let storageError;
+        try { await writeNativeHookFailure(binding.stateDir, identity.nativeHookBinding, error); }
+        catch (storage) {
+          storageError = storage;
+          error.details.receipt_error = { code: storage.code ?? "hook_receipt_write_failed", message: storage.message };
+        }
+        if (storageError?.code !== "native_hook_identity_conflict") try {
+          await resolve(binding.stateDir, "hook.failed", storageError ? { binding: identity.nativeHookBinding, failure: errorRecord(error) } : {}, storageError ? 5_000 : budget.remaining("failure_notification"));
+        } catch (notify) { if (storageError) 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);
+      if (payload.fastAck === true || payload.observationOnly === true) return;
+      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 };
+      // Use the exact admitted before delivery. A later prompt may already be
+      // active; resolving against that prompt would misattribute this result.
+      try {
+        await budget.run(() => resolve(binding.stateDir, "hook.verify", { binding: original.native_hook_binding, phase: "after" }, budget.remaining("generation")), "generation");
+        await deliver({ ...original, phase: "after", outcome }, budget, true);
+      } catch (error) {
+        if (!isNativeHookObservationLoss(error)) throw error;
+        // An observation timeout is not the already-finished tool's outcome.
+        process.stderr.write(`${JSON.stringify({ kind: "native_hook_observation_unavailable", code: error.code, event_id: original.event_id })}\n`);
+        return; // Retain the original binding for a later exact observation.
+      }
+      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,140 @@
+// An observer losing its response does not establish that a provider Turn failed.
+export const OPERATION_ERROR_CONTRACT_VERSION = "operation-errors@2";
+// A lost hook response does not prove that the issued CLI or Turn failed.
+// Do not downgrade a structured rejection merely because a transport wrapped it.
+export function isNativeHookObservationLoss(error) {
+  if (!["native_hook_timeout", "native_hook_failed"].includes(error?.code)) return false;
+  const details = error?.details;
+  const transport = code => ["ETIMEDOUT", "ECONNRESET", "ECONNREFUSED", "EPIPE", "native_hook_timeout", "native_hook_failed"].includes(code) || isObservationLoss({ code });
+  if (details?.decision === "deny" || details?.permissionDecision === "deny"
+    || details?.hookSpecificOutput?.permissionDecision === "deny" || details?.lifecycle_outcome?.effect === "no_effect"
+    || details?.disposition === "pre_cli_shell_refusal"
+    || typeof details?.primary_error?.code === "string" && !transport(details.primary_error.code)
+    || typeof error?.cause?.code === "string" && !transport(error.cause.code)) return false;
+  return true;
+}
+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", "correction_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,118 @@
+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','verification_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)
+    || progress.phase === 'verification_progress' && (typeof progress.native_request_id !== 'string' || !progress.native_request_id || progress.native_request_id.length > 256)
+    || !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 (phase === 'verification_progress' && (typeof metadata.native_request_id !== 'string' || !metadata.native_request_id || metadata.native_request_id.length > 256))
+      throw Object.assign(new Error('verification progress requires an actual checkpoint'), { code: 'operation_progress_invalid' });
+    if (prior && phase === 'verification_progress' && prior.phase === phase && prior.native_request_id === metadata.native_request_id) return prior;
+    if (prior && phase === prior.phase && !['native_progress', 'verification_progress'].includes(phase)
+      && (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}>;

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

@@ -0,0 +1,200 @@
+import { spawn } from "node:child_process";
+import { errorRecord, reportedError } from "./operation-errors.mjs";
+import { ObservationClock, validateObservationDuration } from "./observation-clock.mjs";
+import { terminateCommandTree } from "./native-hook-command.mjs";
+import { SETUP_STARTUP_MS, publishSetup, setupObserver, observationDetails, isSetupPhase } from './setup-progress.mjs';
+let probeSequence = 0;
+
+function failure(message, code) {
+  return Object.assign(new Error(message), { code });
+}
+const phaseDiagnostic = value => isSetupPhase(value) || ["native_hook_phase", "process_maintenance_phase"].includes(value?.kind);
+
+export function reportedFailure(stdout, stderr, fallback, fallbackCode = "flow_reconciliation_failed", retainedError = null) {
+  for (const text of [stdout, stderr]) {
+    // 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 !phaseDiagnostic(JSON.parse(line)); }
+      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 (phaseDiagnostic(value)) 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);
+}
+
+function processTarget(executable, args) {
+  return /\.[cm]?js$/.test(executable) ? { command: process.execPath, args: [executable, ...args] } : { command: executable, args };
+}
+
+// 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, startupMs = null, phase = "utility", signal = null, onDiagnostic = null, result = false, progress = null } = {}) {
+  if (startupMs !== null) validateObservationDuration(startupMs);
+  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 setupProbe = ['native-version', 'native-doctor'].includes(phase);
+  const step = setupProbe ? `version-${++probeSequence}` : null;
+  if (setupProbe) publishSetup('probe_started', step);
+  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) => {
+    const child = spawn(target.command, target.args, { cwd, env: { ...process.env, ...env },
+      detached: process.platform !== "win32", stdio: [input === null ? "ignore" : "pipe", "pipe", "pipe"] });
+    const maxTail = 64 * 1024, maxLine = 1024 * 1024;
+    let stdout = "", stderr = "", pendingStderr = "", settled = false, primary = null, cursor = 0, droppingStructured = false;
+    let cleanupTimer = null, inputError = null, termination = null, retainedError = null, prettyError = "";
+    const phases = new Set();
+    const clock = timeoutMs === null ? null : new ObservationClock({ timeoutMs: startupMs ?? timeoutMs });
+    const observeSetup = setupObserver(env.DD_EVAL_OPERATION_ID ?? process.env.DD_EVAL_OPERATION_ID);
+    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);
+      if (!error && setupProbe) publishSetup('probe_completed', step);
+      error ? reject(error) : resolve(value);
+    };
+    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;
+      if (kind === 'setup_phase') {
+        if (observeSetup(value)) {
+          if (clock) clock.setupProgress = { phase: value.phase, sequence: value.sequence, step: value.step, operation_id: value.operation_id };
+          if (clock) clock.timeoutMs = ['ingress_entered', 'probe_started'].includes(value.phase) ? startupMs ?? timeoutMs : timeoutMs;
+          productive();
+          if (setupProbe || phase === 'engine-probe') publishSetup(value.phase, `${step ?? 'engine'}:${value.sequence}:${value.step ?? ''}`);
+        }
+        return;
+      }
+      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); }
+    };
+    let observedProgress = 0;
+    const timer = clock ? setInterval(() => {
+      if (progress) {
+        try {
+          const next = progress();
+          if (!Number.isSafeInteger(next) || next < 0) throw new RangeError('progress must be a non-negative integer');
+          if (next > observedProgress) { observedProgress = next; productive(); }
+        } catch (error) { stop(error); return; }
+      }
+      if (clock.sample(cursor)) stop(Object.assign(failure("command observation became quiet", "command_observation_lost"),
+        { details: observationDetails(clock, phase, child.pid) }));
+    }, 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");
+      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);
+        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 => { 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, signal) => {
+      if (pendingStderr) deliverProgress(pendingStderr);
+      if (primary) { void (termination ?? Promise.resolve()).then(() => finish(primary)); return; }
+      if (result) return finish(inputError, { exit_code: status, signal, stdout: stdout.trim(), stderr });
+      if (status !== 0) {
+        const error = reportedFailure(stdout, stderr, `${executable} exited ${status}`, json ? "flow_reconciliation_failed" : "command_failed", retainedError);
+        error.details = { reason: 'child_exit', exit_code: status, signal, phase, pid: child.pid, ...error.details };
+        return finish(error);
+      }
+      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 commandJson(bin, args, options = {}) { return await command(bin, args, true, { startupMs: options.timeoutMs ?? SETUP_STARTUP_MS, ...options }); }
+export async function commandText(bin, args, options = {}) { return await command(bin, args, false, { startupMs: options.timeoutMs ?? SETUP_STARTUP_MS, ...options }); }
+export async function commandResult(bin, args, options = {}) { return await command(bin, args, false, { startupMs: options.timeoutMs ?? SETUP_STARTUP_MS, ...options, result: true }); }

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

@@ -0,0 +1,10 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const run = promisify(execFile);
+
+/** Inspect OS descendants without using process names as ownership. A start-time
+ * identity prevents a later unrelated process with a recycled PID being killed. */
+export async function processSnapshot() {
+  const { stdout } = await run("ps", ["-axo", "pid=,ppid=,pgid=,lstart=,stat="], { timeout: 5_000 });
+  return stdout.trim().split("\n").flatMap(line => { const parts = line.trim().split(/\s+/); return parts.length >= 9 ? [{ pid: Number(parts[0]), ppid: Number(parts[1]), pgid: Number(parts[2]), started: parts.slice(3, 8).join(" "), zombie: parts[8].startsWith("Z") }] : []; });
+}