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

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,13 @@
+export const CAPACITY_POLICY: "provider-overload-episode@1";
+export const MAX_OVERLOAD_RETRIES: 2;
+export const MAX_RETRY_AFTER_MS: 30000;
+export function classifyProviderError(native: unknown): string;
+export function safeProviderError(native: unknown): Record<string, unknown>;
+export type CapacityRefusal = { policy: string; ordinal: number; session_id: string; turn_id: string; 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; 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[] };

package/dist/harness-runtime/lib/provider-overload-policy.mjs

@@ -0,0 +1,138 @@
+/** Pure policy shared by the controller and pinned-engine EVAL consumers. */
+export const CAPACITY_POLICY = "provider-overload-episode@1";
+export const MAX_OVERLOAD_RETRIES = 2;
+export const MAX_RETRY_AFTER_MS = 30_000;
+
+function policyError(code, message, details = {}) { return Object.assign(new Error(message), { code, details }); }
+
+/** Only call on a native error envelope, never prompt or tool output. */
+export function classifyProviderError(native) {
+  if (!native || typeof native !== "object") return "provider_failed";
+  const code = [native.code, native.type, native.codexErrorInfo?.code ?? native.codexErrorInfo].filter(value => typeof value === "string").join(" ");
+  const message = String(native.message ?? "");
+  const text = `${code} ${message}`;
+  const status = Number(native.status ?? native.statusCode ?? native.status_code ?? native.http_status);
+  if (status === 402 || /quota|usageLimitExceeded|sessionBudgetExceeded|billing|payment.required|balance.exhausted|insufficient.credit|resource_exhausted.*limit/i.test(text)) return "provider_quota_exhausted";
+  if (status === 401 || status === 403 || /provider_auth_failed|invalid.api.key|authentication|unauthorized|eligib|forbidden|access.denied|rejected.this.account/i.test(text)) return "provider_auth_failed";
+  if (/provider_capacity_transient|serverOverloaded|model.?capacity|at capacity|server.overload|model.overload|server.?busy/i.test(text) || /(?:^|\s)overloaded_error(?:\s|$)/i.test(code) || status === 503 || status === 529) return "provider_capacity_transient";
+  if (/rateLimitExceeded|rate.limit/i.test(text) && (native.retryAfter !== undefined || native.retry_after !== undefined || Object.keys(native.headers ?? {}).some(key => key.toLowerCase() === "retry-after"))) return "provider_rate_limited";
+  return status === 429 || /provider_limit_unknown|\b429\b|rateLimitExceeded|rate.limit/i.test(text) ? "provider_limit_unknown" : "provider_failed";
+}
+
+/** Public retry evidence excludes response bodies, credentials and other headers. */
+export function safeProviderError(native) {
+  const result = { code: classifyProviderError(native) };
+  if (!native || typeof native !== "object") return result;
+  const status = native.status ?? native.statusCode ?? native.status_code ?? native.http_status;
+  if (Number.isInteger(Number(status))) result.status = Number(status);
+  const header = Object.entries(native.headers ?? {}).find(([key]) => key.toLowerCase() === "retry-after")?.[1];
+  const retry = header ?? native.retryAfter ?? native.retry_after;
+  if (retry !== undefined && retry !== null) result.retryAfter = typeof retry === "string" && retry.length <= 128 || typeof retry === "number" && Number.isFinite(retry) ? retry : "invalid-retry-after";
+  if (typeof native.willRetry === "boolean") result.willRetry = native.willRetry;
+  for (const key of ["reset_at", "resets_at", "resetAt", "resetsAt", "reset_time"]) {
+    const value = native[key];
+    if (typeof value === "string" && value.length <= 128 || typeof value === "number" && Number.isFinite(value)) result[key] = value;
+  }
+  return result;
+}
+
+export function parseCapacityOperation(id) {
+  if (typeof id !== "string" || !id) throw policyError("capacity_continuation_conflict", "Missing capacity operation identity");
+  const match = /^(.*):capacity:(\d+):session\.prompt$/.exec(id);
+  if (!match) return { root: id, ordinal: 0 };
+  const ordinal = Number(match[2]);
+  if (!Number.isSafeInteger(ordinal) || ordinal < 1 || String(ordinal) !== match[2]) throw policyError("capacity_continuation_conflict", "Capacity ordinal is not a canonical positive safe integer", { operation_id: id });
+  return { root: match[1], ordinal };
+}
+
+export function normalizeProviderFailure(error, expectedSessionId, expectedTurnId) {
+  let current = error;
+  for (let depth = 0; depth < 4 && current && typeof current === "object"; depth++) {
+    // The same continuation authority applies to a proven v2 execution
+    // refusal. Never classify transport loss or an active native retry here.
+    if (current.code === "provider_capacity_transient" || current.code === "provider_rate_limited") {
+      const details = current.details ?? {};
+      if (!["opencode.v2.session.execution", "agy.result", "acp.error_response", "droid.agent_turn_outcome", "grok.subagent.event"].includes(details.native_source) || details.terminal_status !== "failed"
+        || details.will_retry === true || details.native_retry_active === true || details.provider_error?.willRetry === true
+        || details.provider_error && !["provider_capacity_transient", "provider_rate_limited"].includes(classifyProviderError(details.provider_error))
+        || typeof details.provider_session_id !== "string" || !details.provider_session_id
+        || typeof details.turn_id !== "string" || !details.turn_id || details.native_turn_id !== details.turn_id
+        || expectedSessionId !== undefined && details.provider_session_id !== expectedSessionId
+        || expectedTurnId !== undefined && details.turn_id !== expectedTurnId) return null;
+      return { code: "serverOverloaded", session_id: details.provider_session_id, turn_id: details.turn_id,
+        native_error: details.provider_error ?? { type: details.native_error_type, status: details.http_status }, observed_at: details.observed_at ?? null,
+        terminal_at: null, terminal_basis: null, native_turn_items: details.native_turn_items ?? null, primary_error: current };
+    }
+    if (current.code === "turn_interrupted") {
+      const details = current.details ?? {}, native = details.provider_error;
+      const code = typeof native?.codexErrorInfo === "string" ? native.codexErrorInfo : native?.codexErrorInfo?.code;
+      if (native?.willRetry === true || details.terminal_status !== "failed" || typeof details.provider_session_id !== "string" || !details.provider_session_id
+        || expectedSessionId !== undefined && details.provider_session_id !== expectedSessionId
+        || typeof details.turn_id !== "string" || !details.turn_id || details.native_turn_id !== details.turn_id
+        || expectedTurnId !== undefined && details.turn_id !== expectedTurnId || typeof code !== "string") return null;
+      return { code, session_id: details.provider_session_id, turn_id: details.turn_id, native_error: native,
+        observed_at: details.observed_at ?? null, terminal_at: details.terminal_at ?? null, terminal_basis: details.terminal_basis ?? null,
+        native_turn_items: details.native_turn_items ?? null, primary_error: current };
+    }
+    // No arbitrary recursive cause search: an ownership/hook/lifecycle error wins.
+    if (current.code !== "harness_adapter_failed") return null;
+    current = current.details?.cause ?? current.cause;
+  }
+  return null;
+}
+
+export function terminalProviderOverload(error, expectedSessionId, expectedTurnId) {
+  const normalized = normalizeProviderFailure(error, expectedSessionId, expectedTurnId);
+  return normalized !== null && ["provider_capacity_transient", "provider_rate_limited"].includes(classifyProviderError(normalized.native_error));
+}
+
+export function nativeItemsSettled(items) {
+  return items?.observed === true && typeof items.possible_effects === "boolean" && items.pending !== true
+    && (items.possible_effects === false || items.pending === false);
+}
+
+export function capacityBackoff(error, ordinal, now = Date.now(), random = Math.random) {
+  if (!Number.isSafeInteger(ordinal) || ordinal < 1 || !Number.isFinite(now)) throw policyError("capacity_continuation_conflict", "Invalid capacity timing identity");
+  const native = normalizeProviderFailure(error)?.native_error ?? error?.details?.provider_error ?? error;
+  const header = Object.entries(native?.headers ?? {}).find(([key]) => key.toLowerCase() === "retry-after")?.[1];
+  const value = header ?? native?.retryAfter ?? native?.retry_after;
+  let retry = 0;
+  if (value !== undefined && value !== null) {
+    retry = typeof value === "number" || typeof value === "string" && /^\d+(\.\d+)?$/.test(value.trim()) ? Number(value) * 1000 : typeof value === "string" && /^\w{3}, \d{2} \w{3} \d{4} \d{2}:\d{2}:\d{2} GMT$/.test(value.trim()) ? Math.max(0, Date.parse(value) - now) : NaN;
+    if (!Number.isFinite(retry) || retry < 0 || !Number.isFinite(now + retry) || now + retry > 8.64e15)
+      throw policyError("capacity_retry_metadata_invalid", "Retry-After cannot be represented safely", { retry_after: value });
+  }
+  const jitter = random();
+  if (!Number.isFinite(jitter) || jitter < 0 || jitter >= 1) throw policyError("capacity_retry_metadata_invalid", "Invalid retry jitter");
+  const wait = Math.max((ordinal === 1 ? 5_000 : 15_000) + Math.floor(jitter * 251), retry);
+  if (wait > MAX_RETRY_AFTER_MS) throw policyError("provider_unavailable", "Provider requested a delay beyond the retry budget", { policy: CAPACITY_POLICY, reason: "retry_after_exceeds_budget", retry_after_ms: retry, suggested_retry_at: new Date(now + retry).toISOString() });
+  return wait;
+}
+
+export function refusalObservation(error, ordinal, firstObservedAt) {
+  const failure = normalizeProviderFailure(error);
+  const observed = Date.parse(firstObservedAt);
+  if (!failure || !Number.isSafeInteger(ordinal) || ordinal < 0 || !Number.isFinite(observed))
+    throw policyError("capacity_continuation_conflict", "Refusal lacks an immutable native identity/time");
+  if (failure.observed_at !== null && (typeof failure.observed_at !== "string" || !Number.isFinite(Date.parse(failure.observed_at)) || Date.parse(failure.observed_at) !== observed))
+    throw policyError("capacity_continuation_conflict", "Native refusal observation time is invalid or changed");
+  const native = failure.terminal_at && Date.parse(failure.terminal_at);
+  return { policy: CAPACITY_POLICY, ordinal, session_id: failure.session_id, turn_id: failure.turn_id,
+    first_observed_at: firstObservedAt, ...(Number.isFinite(native) && typeof failure.terminal_basis === "string" && failure.terminal_basis ? { native_terminal_at: failure.terminal_at, native_terminal_basis: failure.terminal_basis } : {}) };
+}
+
+export function overloadExhausted(refusals, maxRetries = MAX_OVERLOAD_RETRIES) {
+  if (!Number.isSafeInteger(maxRetries) || maxRetries < 0 || maxRetries > MAX_OVERLOAD_RETRIES) throw policyError("capacity_continuation_conflict", "Invalid retry budget");
+  for (const [index, refusal] of refusals.entries()) {
+    const previous = refusals[index - 1];
+    if (typeof refusal.first_observed_at !== "string" || !Number.isFinite(Date.parse(refusal.first_observed_at))
+      || previous && Date.parse(refusal.first_observed_at) < Date.parse(previous.first_observed_at))
+      throw policyError("capacity_continuation_conflict", "Refusal observation clock reversed or is invalid");
+  }
+  for (const [index, refusal] of refusals.entries()) {
+    if (refusal.policy !== CAPACITY_POLICY) throw policyError("capacity_policy_mismatch", "Retained episode uses another retry policy");
+    const previous = refusals[index - 1];
+    if (refusal.ordinal !== index || previous && (refusal.session_id !== previous.session_id || refusals.slice(0, index).some(item => item.turn_id === refusal.turn_id))) throw policyError("capacity_continuation_conflict", "Refusal chain identity is inconsistent");
+  }
+  return refusals.length > maxRetries ? { policy: CAPACITY_POLICY, reason: "overload_retries_exhausted", attempts: refusals.length, refusals } : null;
+}

package/dist/harness-runtime/lib/runner-events.mjs

@@ -0,0 +1,200 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, open, readFile, rename, unlink } from "node:fs/promises";
+import path from "node:path";
+import { withRunnerLock as withLock } from "./runner-lock.mjs";
+import { isObservationLoss, errorRecord } from "./operation-errors.mjs";
+import { operationContext } from "./operation-context.mjs";
+
+const appendQueues = new Map();
+
+export function canonicalJson(value) {
+  const normalize = (item) => {
+    if (Array.isArray(item)) return item.map(normalize);
+    if (item && typeof item === "object") return Object.fromEntries(Object.keys(item).sort().map((key) => [key, normalize(item[key])]));
+    return item;
+  };
+  return `${JSON.stringify(normalize(value))}\n`;
+}
+
+export function sha256(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+export function hashJson(value) { return sha256(canonicalJson(value)); }
+
+export async function writeJsonAtomic(file, value) {
+  await mkdir(path.dirname(file), { recursive: true });
+  const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    const payload = await open(temporary, "wx", 0o600);
+    try { await payload.writeFile(`${JSON.stringify(value, null, 2)}\n`); await payload.sync(); }
+    finally { await payload.close(); }
+    await rename(temporary, file);
+    const directory = await open(path.dirname(file), "r");
+    try { await directory.sync(); }
+    finally { await directory.close(); }
+  } finally { await unlink(temporary).catch(error => { if (error.code !== "ENOENT") throw error; }); }
+}
+
+export async function readJsonLines(file, label = "JSONL") {
+  try {
+    const source = await readFile(file, "utf8");
+    return source.split("\n").filter(Boolean).map((line, index) => {
+      try { return JSON.parse(line); }
+      catch { throw new Error(`invalid ${label} record at ${file}:${index + 1}`); }
+    });
+  } catch (error) {
+    if (error?.code === "ENOENT") return [];
+    throw error;
+  }
+}
+
+export async function readEvents(file) {
+  const records = await readJsonLines(file, "runner event");
+  return records.map((record, index) => {
+    try { return validateRunnerEvent(record); }
+    catch { throw new Error(`invalid runner event at ${file}:${index + 1}`); }
+  });
+}
+
+export function validateRunnerEvent(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value) || value.specversion !== "1.0" || typeof value.id !== "string" || typeof value.source !== "string" || typeof value.type !== "string" || typeof value.time !== "string" || !value.data || typeof value.data !== "object" || !Number.isInteger(value.data.sequence) || value.data.sequence < 1) {
+    throw new Error("invalid normalized runner event");
+  }
+  return value;
+}
+
+export async function appendEvent(file, input) {
+  const prior = appendQueues.get(file) ?? Promise.resolve();
+  const current = prior.then(() => withLock(file, async () => {
+    const events = await readEvents(file);
+    // Internal callers can validate a dispatch or bind its generation under
+    // the same cross-process lock that orders cancellation and completion.
+    if (input.deduplicate && input.id) { const existing = events.find(event => event.id === input.id); if (existing) return existing; }
+    if (input.beforeAppend?.(events) === false) return null;
+    const sequence = events.length + 1;
+    const event = {
+      specversion: "1.0",
+      id: input.id ?? `EVT-${randomUUID()}`,
+      source: input.source,
+      type: input.type,
+      time: input.time ?? new Date().toISOString(),
+      subject: input.subject ?? "runner",
+      datacontenttype: "application/json",
+      runid: input.runId,
+      executionid: input.executionId,
+      traceid: input.traceId,
+      spanid: input.spanId ?? randomUUID(),
+      ...(input.parentSpanId ? { parentspanid: input.parentSpanId } : {}),
+      data: { sequence, ...input.data }
+    };
+    const context = operationContext.getStore();
+    if (context?.eventsFile === file && context.executionId === input.executionId && context.operationId && input.executionId) {
+      event.data.execution_operation_id ??= context.operationId;
+    }
+    validateRunnerEvent(event);
+    await mkdir(path.dirname(file), { recursive: true });
+    const handle = await open(file, "a");
+    try { await handle.write(`${JSON.stringify(event)}\n`); await handle.sync(); }
+    finally { await handle.close(); }
+    return event;
+  }));
+  const tail = current.catch(() => {}); appendQueues.set(file, tail);
+  try { return await current; }
+  finally { if (appendQueues.get(file) === tail) appendQueues.delete(file); }
+}
+
+export function reduceEvents(events) {
+  const operations = new Map();
+  let state = "planned";
+  for (const event of events) {
+    const data = event?.data ?? {};
+    if (["dev.dd.eval.planned", "dev.dd.eval.completed"].includes(event.type) && typeof data.state === "string") state = data.state;
+    if (typeof data.operation_id !== "string") continue;
+    const prior = operations.get(data.operation_id) ?? { id: data.operation_id, requested: false, started: false, terminal: null };
+    if (event.type.endsWith(".requested")) prior.requested = true;
+    if (event.type.endsWith(".started")) prior.started = true;
+    if (event.type.endsWith(".observation_lost")) prior.observation_lost = data.error ?? { code: "observation_lost" };
+    if (event.type.endsWith(".completed") || event.type.endsWith(".failed") || event.type.endsWith(".cancelled")) {
+      const terminal = event.type.split(".").at(-1);
+      const result = terminal === "completed" ? data.result : { error: data.error ?? null };
+      const resultHash = hashJson({ terminal, result });
+      if (prior.terminal && (prior.terminal !== terminal || prior.result_hash !== resultHash)) {
+        throw Object.assign(new Error(`runner operation ${data.operation_id} has conflicting terminal events`), { code: "journal_conflict", operation_id: data.operation_id });
+      }
+      prior.terminal = terminal;
+      prior.result = result;
+      prior.result_hash = resultHash;
+    }
+    operations.set(data.operation_id, prior);
+  }
+  return { state, operations: Object.fromEntries([...operations].map(([id, value]) => [id, value])) };
+}
+
+export async function recordOperation({ eventsFile, source, runId, executionId, traceId, operationId, operation, subject = "runner", action }) {
+  const existing = await withLock(`${eventsFile}.${operationId.replace(/[^a-zA-Z0-9._-]/g, "_")}`, async () => {
+    const current = reduceEvents(await readEvents(eventsFile)).operations[operationId];
+    if (current?.terminal === "completed") return current;
+    if (current?.terminal) throw Object.assign(new Error(`operation ${operationId} is already ${current.terminal}; use explicit recovery instead of replaying it`), { code: "operation_terminal", operation_id: operationId, terminal: current.terminal });
+    if (current?.started && !current.terminal) {
+      const error = new Error(current.observation_lost
+        ? `operation ${operationId} has no confirmed outcome; reconcile its provider state before retrying`
+        : `operation ${operationId} is already in progress; reconcile before retrying`);
+      error.code = current.observation_lost ? "operation_observation_lost" : "operation_in_progress";
+      error.operation_id = operationId;
+      throw error;
+    }
+    await appendEvent(eventsFile, { source, runId, executionId, traceId, subject, type: "dev.dd.eval.operation.requested", data: { operation_id: operationId, operation, status: "requested" } });
+    await appendEvent(eventsFile, { source, runId, executionId, traceId, subject, type: "dev.dd.eval.operation.started", data: { operation_id: operationId, operation, status: "started" } });
+    return null;
+  });
+  if (existing) return { reused: true, operation_id: operationId, result: existing.result };
+  try {
+    const result = await operationContext.run({ operationId, eventsFile, runId, executionId }, action);
+    await completeOperation({ eventsFile, source, runId, executionId, traceId, subject, operationId, operation, result });
+    return { reused: false, operation_id: operationId, result };
+  } catch (error) {
+    if (isObservationLoss(error)) await observationLost({ eventsFile, source, runId, executionId, traceId, subject, operationId, operation, error });
+    else await failOperation({ eventsFile, source, runId, executionId, traceId, subject, operationId, operation, error });
+    throw error;
+  }
+}
+
+export async function completeOperation({ eventsFile, source, runId, executionId, traceId, subject = "runner", operationId, operation, result }) {
+  return await settleOperation({ eventsFile, source, runId, executionId, traceId, subject, operationId, operation, terminal: "completed", result });
+}
+
+export async function failOperation({ eventsFile, source, runId, executionId, traceId, subject = "runner", operationId, operation, error }) {
+  return await settleOperation({ eventsFile, source, runId, executionId, traceId, subject, operationId, operation, terminal: "failed", result: { error: errorRecord(error) } });
+}
+
+/** A lost observer response is deliberately non-terminal: replay could duplicate a provider Turn. */
+export async function observationLost({ eventsFile, source, runId, executionId, traceId, subject = "runner", operationId, operation, error }) {
+  return await withLock(`${eventsFile}.${operationId.replace(/[^a-zA-Z0-9._-]/g, "_")}`, async () => {
+    const existing = reduceEvents(await readEvents(eventsFile)).operations[operationId];
+    if (existing?.terminal) return { reused: true, operation_id: operationId, result: existing.result };
+    if (!existing?.started) throw Object.assign(new Error(`operation ${operationId} has no started receipt`), { code: "operation_not_started" });
+    if (existing.observation_lost) return { reused: true, operation_id: operationId, observation_lost: existing.observation_lost };
+    const recorded = errorRecord(error);
+    await appendEvent(eventsFile, { source, runId, executionId, traceId, subject, type: "dev.dd.eval.operation.observation_lost", data: { operation_id: operationId, operation, status: "observation_lost", error: recorded } });
+    return { reused: false, operation_id: operationId, observation_lost: recorded };
+  });
+}
+
+async function settleOperation({ eventsFile, source, runId, executionId, traceId, subject, operationId, operation, terminal, result }) {
+  return await withLock(`${eventsFile}.${operationId.replace(/[^a-zA-Z0-9._-]/g, "_")}`, async () => {
+    const existing = reduceEvents(await readEvents(eventsFile)).operations[operationId];
+    const expectedHash = hashJson({ terminal, result });
+    if (existing?.terminal) {
+      if (existing.terminal === terminal && existing.result_hash === expectedHash) return { reused: true, operation_id: operationId, result: existing.result };
+      throw Object.assign(new Error(`runner operation ${operationId} has conflicting terminal result`), { code: "journal_conflict", operation_id: operationId });
+    }
+    if (!existing?.started) throw Object.assign(new Error(`operation ${operationId} has no started receipt`), { code: "operation_not_started" });
+    const type = terminal === "completed" ? "dev.dd.eval.operation.completed" : "dev.dd.eval.operation.failed";
+    const data = terminal === "completed"
+      ? { operation_id: operationId, operation, status: terminal, result }
+      : { operation_id: operationId, operation, status: terminal, error: result.error };
+    await appendEvent(eventsFile, { source, runId, executionId, traceId, subject, type, data });
+    return { reused: false, operation_id: operationId, result };
+  });
+}

package/dist/harness-runtime/lib/runner-lock.mjs

@@ -0,0 +1,42 @@
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readdirSync, readFileSync, writeFileSync, unlinkSync, rmdirSync } from "node:fs";
+import path from "node:path";
+
+function release(lock, owner) {
+  try { unlinkSync(path.join(lock, owner)); } catch (error) { if (error.code === "ENOENT") return; throw error; }
+  // Never recursively remove a directory: another owner may already have acquired it.
+  try { rmdirSync(lock); } catch (error) { if (!["ENOENT", "ENOTEMPTY", "EEXIST"].includes(error.code)) throw error; }
+}
+
+function reclaimDeadOwner(lock) {
+  let entries;
+  try { entries = readdirSync(lock); } catch (error) { if (error.code === "ENOENT") return; throw error; }
+  if (entries.length !== 1 || !/^owner-.*\.json$/.test(entries[0])) return;
+  let owner;
+  try { owner = JSON.parse(readFileSync(path.join(lock, entries[0]), "utf8")); } catch { return; }
+  if (!Number.isInteger(owner.pid) || owner.pid <= 0) return;
+  try { process.kill(owner.pid, 0); }
+  catch (error) { if (error.code === "ESRCH") release(lock, entries[0]); }
+  // A live/reused PID or unknown owner is conservative: age never proves death.
+}
+
+export async function withRunnerLock(file, action, { timeoutMs = 30_000 } = {}) {
+  const lock = `${file}.lock`;
+  const owner = `owner-${process.pid}-${randomUUID()}.json`;
+  const deadline = performance.now() + timeoutMs;
+  for (;;) {
+    let acquired = false;
+    try { mkdirSync(lock); acquired = true; }
+    catch (error) { if (error.code !== "EEXIST") throw error; }
+    if (acquired) {
+      // No await between acquisition and identifying the owner.
+      try { writeFileSync(path.join(lock, owner), JSON.stringify({ pid: process.pid }), { flag: "wx" }); }
+      catch (error) { release(lock, owner); throw error; }
+      try { return await action(); }
+      finally { release(lock, owner); }
+    }
+    reclaimDeadOwner(lock);
+    if (performance.now() >= deadline) throw Object.assign(new Error(`runner lock has a live or unconfirmed owner: ${lock}; inspect its owner before recovery`), { code: "runner_lock_timeout" });
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  }
+}

package/dist/harness-runtime/lib/session-settlement.mjs

@@ -0,0 +1,30 @@
+import { errorRecord } from "./operation-errors.mjs";
+
+/** Diagnostic failure never prevents cancellation of already owned Sessions.
+ * Only a fresh successful observation can establish settlement. */
+export async function waitForSettlement({ observe, cancel, knownSessions = () => [], timeoutMs = 5_000 }) {
+  const deadline = performance.now() + timeoutMs;
+  const cancelled = new Set(), errors = [];
+  if (cancel) for (const id of knownSessions()) {
+    cancelled.add(id);
+    try { await cancel(id); } catch (error) { errors.push({ phase: "cancel", session_id: id, ...errorRecord(error) }); }
+  }
+  for (;;) {
+    let state;
+    try { state = await observe(); }
+    catch (error) {
+      if (!cancel) throw error;
+      errors.push({ phase: "observe", ...errorRecord(error) });
+      state = { sessions: knownSessions(), active: true, observation_error: errorRecord(error) };
+    }
+    if (!state.active && state.sessions.length === 0) return { ...state, cleanup_errors: errors };
+    // The observation budget must not skip a newly discovered owned target.
+    // Attempt its cancellation once, then leave physical settlement pending.
+    for (const id of state.sessions) if (cancel && !cancelled.has(id)) {
+      cancelled.add(id);
+      try { await cancel(id); } catch (error) { errors.push({ phase: "cancel", session_id: id, ...errorRecord(error) }); }
+    }
+    if (!cancel || performance.now() >= deadline) throw Object.assign(new Error("daemon still owns an unsettled Session tree"), { code: "tree_not_settled", details: { ...state, cleanup_errors: errors } });
+    await new Promise(resolve => setTimeout(resolve, 50));
+  }
+}