@deksden-com/dd-flow-cli 0.9.0-beta.15 → 0.9.0-beta.150

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", "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,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}>;

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

@@ -0,0 +1,201 @@
+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 maxOutput = 8 * 1024 * 1024, maxTail = 64 * 1024, maxLine = 1024 * 1024;
+    let stdout = "", stderr = "", pendingStderr = "", settled = false, primary = null, cursor = 0, droppingStructured = false;
+    let outputBytes = 0, cleanupTimer = null, inputError = null, termination = null, retainedError = null, prettyError = "";
+    const phases = new Set();
+    const clock = timeoutMs === null ? null : new ObservationClock({ timeoutMs: 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"); outputBytes += Buffer.byteLength(data);
+      if (outputBytes > maxOutput) stop(failure("command final output exceeds 8 MiB", "command_output_limit"));
+      else stdout += data;
+    });
+    child.stderr.setEncoding("utf8").on("data", data => {
+      diagnostic(data, "stderr"); stderr = (stderr + data).slice(-maxTail);
+      if (droppingStructured) {
+        const end = data.indexOf("\n");
+        if (end < 0) return;
+        data = data.slice(end + 1); droppingStructured = false;
+      }
+      pendingStderr += data;
+      for (;;) {
+        const end = pendingStderr.indexOf("\n"); if (end < 0) break;
+        const line = pendingStderr.slice(0, end); pendingStderr = pendingStderr.slice(end + 1);
+        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") }] : []; });
+}

package/dist/harness-runtime/lib/provider-overload-policy.d.mts

@@ -0,0 +1,15 @@
+export const CAPACITY_POLICY: "provider-overload-episode@1";
+export const MAX_OVERLOAD_RETRIES: 3;
+export const MAX_RETRY_AFTER_MS: 30000;
+export function classifyProviderError(native: unknown): string;
+export function safeProviderError(native: unknown): Record<string, unknown>;
+export type RequestProof = { kind: "native_turn"; session_id: string; turn_id: string } | { kind: "stream_request"; daemon_instance: string; connection_id: string; operation_id: string; turn_generation: number; session_id: string; outbound_position: number; terminal_position: number };
+export function streamRequestKey(proof: unknown): string | null;
+export type CapacityRefusal = { policy: string; ordinal: number; session_id: string; turn_id: string; request_key?: string; request_proof?: RequestProof; first_observed_at: string; native_terminal_at?: string; native_terminal_basis?: string };
+export function parseCapacityOperation(id: string): { root: string; ordinal: number };
+export function normalizeProviderFailure(error: unknown, sessionId?: string, turnId?: string): null | { code: string; session_id: string; turn_id: string; request_key: string; request_proof: RequestProof; native_error: Record<string, unknown>; observed_at: unknown; terminal_at: unknown; native_turn_items: unknown; primary_error: { details?: Record<string, unknown> } };
+export function terminalProviderOverload(error: unknown, sessionId?: string, turnId?: string): boolean;
+export function nativeItemsSettled(items: unknown): boolean;
+export function capacityBackoff(error: unknown, ordinal: number, now?: number, random?: () => number): number;
+export function refusalObservation(error: unknown, ordinal: number, firstObservedAt: string): CapacityRefusal;
+export function overloadExhausted(refusals: CapacityRefusal[], maxRetries?: number): null | { policy: string; reason: string; attempts: number; refusals: CapacityRefusal[] };