@deksden-com/dd-flow-cli 0.9.0-beta.22 → 0.9.0-beta.24

package/dist/harness-runtime/lib/driver-recovery.mjs

@@ -0,0 +1,129 @@
+import { processSnapshot } from "./process-snapshot.mjs";
+import { readdir, readFile, mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { inspectDaemonOperation } from "./daemon-operations.mjs";
+import { writeJsonAtomic } from "./runner-events.mjs";
+import { reportedError } from "./operation-errors.mjs";
+import { ObservationClock } from "./observation-clock.mjs";
+import { runtimeProcess } from "./managed-daemon.mjs";
+
+/** Explicit same-Session restart retains native stores and the old daemon
+ * receipt; it does not turn a terminal directory into a new execution. */
+export async function authorizeRetainedDaemonResume(root, previous, sessionId, config) {
+  const sessions = [...(previous.sessions ?? []), ...(previous.root_session_id ? [previous.root_session_id] : [])];
+  if (previous.shutdown_state !== "clean" || previous.active_tree === true || typeof sessionId !== "string" || !sessions.some(session => (typeof session === "string" ? session : session.provider_session_id) === sessionId)) throw Object.assign(new Error("terminal daemon restart requires a retained, settled Session identity"), { code: "daemon_state_terminal" });
+  for (const key of ["cwd", "projectRoot", "ddFlowHome", "ddFlowBin", "provider", "model", "reasoning", "mode", "variant", "agent", "bin", "noFlow"]) {
+    if ((previous.config?.[key] ?? null) !== (config[key] ?? null)) throw Object.assign(new Error(`retained daemon configuration changed: ${key}`), { code: "daemon_config_mismatch" });
+  }
+  await assertDaemonReplaceable(root);
+  await reconcileDriverReplies(root);
+  if (!/^[a-zA-Z0-9-]+$/.test(previous.daemon_id ?? "")) throw Object.assign(new Error("original daemon identity is invalid"), { code: "daemon_state_terminal" });
+  const directory = path.join(root, "daemon-history"); await mkdir(directory, { recursive: true, mode: 0o700 });
+  const file = path.join(directory, `${previous.daemon_id}.json`), bytes = `${JSON.stringify(previous, null, 2)}\n`;
+  try { await writeFile(file, bytes, { flag: "wx", mode: 0o600 }); }
+  catch (error) { if (error.code !== "EEXIST" || await readFile(file, "utf8") !== bytes) throw error; }
+}
+
+/** A dead bridge alone does not prove its provider tree was stopped. Require
+ * the adapter's durable clean-shutdown receipt as well, for every bridge. */
+export async function recoverySettlement(driversRoot) {
+  const daemons = [];
+  const registries = new Map();
+  async function visit(directory) {
+    const entries = await readdir(directory, { withFileTypes: true });
+    const daemonRoot = entries.some(entry => entry.name === "daemon.json" && entry.isFile());
+    for (const entry of entries) {
+      const file = path.join(directory, entry.name);
+      if (entry.isSymbolicLink()) throw Object.assign(new Error("driver evidence contains a symbolic link"), { code: "recovery_settlement_unconfirmed" });
+      // Native stores contain package/auth symlinks, not adapter daemon
+      // receipts. Do not traverse their contents as a daemon inventory.
+      if (entry.isDirectory()) {
+        if (daemonRoot && ["gemini", "grok-home", "home", "xdg-data", "xdg-cache", "xdg-config"].includes(entry.name)) continue;
+        await visit(file);
+      }
+      else if (entry.name === "daemon.json") {
+        const state = JSON.parse(await readFile(file, "utf8"));
+        if (state.shutdown_state !== "clean" || state.active_tree === true) throw Object.assign(new Error("provider tree has no clean shutdown receipt"), { code: "recovery_settlement_unconfirmed" });
+        await assertDaemonReplaceable(directory);
+        await reconcileDriverReplies(directory);
+        if (state.config?.resourceHome && state.resource_process?.id) {
+          const key = state.config.resourceHome;
+          if (!registries.has(key)) registries.set(key, await runtimeProcess(state.config, "status"));
+          const processes = registries.get(key)?.processes;
+          if (!Array.isArray(processes) || !processes.some(record => record.id === state.resource_process.id)) throw Object.assign(new Error("managed daemon registration is missing"), { code: "recovery_settlement_unconfirmed" });
+          const attemptRoot = path.dirname(path.resolve(driversRoot));
+          for (const record of processes.filter(record => record.id === state.resource_process.id || [record.stdout_path, record.stderr_path].some(file => typeof file === "string" && path.resolve(file).startsWith(`${attemptRoot}${path.sep}`)))) {
+            if (!["stopped", "failed"].includes(record.state)) throw Object.assign(new Error("a retained managed process has not settled"), { code: "recovery_settlement_unconfirmed", details: { process_id: record.id, state: record.state } });
+            if (Number.isInteger(record.pid) && record.pid > 0) {
+              try { process.kill(record.pid, 0); }
+              catch (error) { if (error.code === "ESRCH") continue; }
+              if (typeof record.pid_started_at === "string" && record.pid_started_at.trim()) {
+                const observed = (await processSnapshot()).find(item => item.pid === record.pid);
+                if (!observed || record.pid_started_at.trim().replace(/\s+/g, " ") !== observed.started) continue;
+              }
+              throw Object.assign(new Error("a retained managed process is still live or unconfirmed"), { code: "recovery_settlement_unconfirmed", details: { process_id: record.id } });
+            }
+          }
+        }
+        daemons.push({ state_file: file, daemon_id: state.daemon_id, shutdown_state: state.shutdown_state, pid: state.pid });
+      }
+    }
+  }
+  await visit(driversRoot);
+  if (!daemons.length) throw Object.assign(new Error("no provider shutdown evidence found"), { code: "recovery_settlement_unconfirmed" });
+  return { settled: true, reason: "observed_clean_adapter_shutdown", observed_at: new Date().toISOString(), daemons };
+}
+
+export async function assertDaemonReplaceable(root) {
+  let state;
+  try { state = JSON.parse(await readFile(path.join(root, "daemon.json"), "utf8")); }
+  catch (error) { if (error.code === "ENOENT") return; throw error; }
+  if (!Number.isInteger(state.pid) || state.pid <= 0) throw Object.assign(new Error("original daemon ownership is unknown"), { code: "operation_observation_lost", details: { state_dir: root } });
+  const pids = new Set([state.pid, state.provider_pid, ...(state.owned_processes ?? []).map(process => process.pid)].filter(pid => Number.isInteger(pid) && pid > 0));
+  for (const pid of pids) {
+    try { process.kill(pid, 0); }
+    catch (error) { if (error.code === "ESRCH") continue; }
+    const retained = state.owned_processes?.filter(record => record.pid === pid && typeof record.started === "string" && record.started.trim());
+    if (retained?.length) {
+      const observed = (await processSnapshot()).find(record => record.pid === pid);
+      if (!observed || retained.every(record => record.started !== observed.started)) continue;
+    }
+    throw Object.assign(new Error("original daemon/provider is live or its ownership is unconfirmed; do not create a competing bridge"), { code: "operation_observation_lost", details: { state_dir: root, pid } });
+  }
+}
+
+/** Observe the original operation; never re-send its parameters. */
+export async function recoverDriverReply(root, id, { timeoutMs = 30_000, pollMs = 250 } = {}) {
+  const clock = new ObservationClock({ timeoutMs });
+  do {
+    let receipt;
+    try { receipt = await inspectDaemonOperation(root, id); }
+    catch (error) { if (error.code !== "operation_not_found") throw error; }
+    if (receipt?.state === "completed") return receipt.result;
+    if (receipt?.state === "failed") throw reportedError(receipt.error, "provider operation failed");
+    if (clock.sample()) break;
+    await new Promise(resolve => setTimeout(resolve, pollMs));
+  } while (true);
+  throw Object.assign(new Error("original provider operation has no confirmed reply; reconcile it before starting another Turn"), {
+    code: "operation_observation_lost", details: { operation_id: id, state_dir: root }
+  });
+}
+
+/** Crash recovery barrier. Import late replies into the client ledger before
+ * any subsequent productive call, even when a new runner process is used. */
+export async function reconcileDriverReplies(root) {
+  const directory = path.join(root, "client-operations");
+  let entries;
+  try { entries = await readdir(directory); } catch (error) { if (error.code === "ENOENT") return; throw error; }
+  for (const entry of entries.filter(name => name.endsWith(".json"))) {
+    const file = path.join(directory, entry), record = JSON.parse(await readFile(file, "utf8"));
+    if (["completed", "failed"].includes(record.state)) continue;
+    let receipt;
+    try { receipt = await inspectDaemonOperation(root, record.operation_id); }
+    catch (error) { if (error.code !== "operation_not_found") throw error; }
+    if (!["completed", "failed"].includes(receipt?.state)) throw Object.assign(new Error("a previous driver request has an unknown outcome; no new productive request was sent"), {
+      code: "operation_observation_lost", details: { operation_id: record.operation_id, state_dir: root }
+    });
+    await writeJsonAtomic(file, { ...record, state: receipt.state, result: receipt.result, error: receipt.error, reconciled_at: new Date().toISOString() });
+  }
+}

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

@@ -0,0 +1,66 @@
+import { createHash } from "node:crypto";
+import { open, readFile, readdir, stat } from "node:fs/promises";
+import path from "node:path";
+
+/** Cache native filenames, then read only a bounded header and small settings.
+ * New child discovery may walk the directory once; heartbeats never replay it. */
+export class DroidMetadataReader {
+  constructor(factory) { this.factory = factory; this.files = new Map(); this.cache = new Map(); }
+  async locate(id) {
+    if (this.files.has(id)) return this.files.get(id);
+    const visit = async directory => {
+      for (const entry of await readdir(directory, { withFileTypes: true }).catch(error => { if (error.code === "ENOENT") return []; throw error; })) {
+        const file = path.join(directory, entry.name);
+        if (entry.isDirectory()) await visit(file);
+        else if (entry.isFile() && entry.name.endsWith(".jsonl")) this.files.set(entry.name.slice(0, -6), file);
+      }
+    };
+    await visit(path.join(this.factory, "sessions"));
+    return this.files.get(id) ?? null;
+  }
+  async read(id) {
+    const file = await this.locate(id); if (!file) return null;
+    const settingsFile = file.replace(/\.jsonl$/, ".settings.json");
+    const info = await stat(settingsFile).catch(error => { if (error.code === "ENOENT") return null; throw error; });
+    if (!info || info.size > 1_048_576) return null;
+    const identity = `${info.ino}:${info.mtimeMs}:${info.size}`;
+    if (this.cache.get(id)?.identity === identity) return this.cache.get(id).value;
+    const handle = await open(file, "r"); const buffer = Buffer.alloc(65_536);
+    let header;
+    try { const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0); header = JSON.parse(buffer.subarray(0, bytesRead).toString("utf8").split("\n")[0]); }
+    finally { await handle.close(); }
+    if (header.type !== "session_start" || header.id !== id) throw Object.assign(new Error("native metadata Session identity differs"), { code: "session_identity_mismatch" });
+    let bytes, settings;
+    try { bytes = await readFile(settingsFile, "utf8"); settings = JSON.parse(bytes); }
+    catch (error) { if (error instanceof SyntaxError || error.code === "ENOENT") return null; throw error; }
+    const value = { header, settings, transcript_path: file, source: { path: settingsFile, sha256: createHash("sha256").update(bytes).digest("hex") } };
+    this.cache.set(id, { identity, value }); return value;
+  }
+}
+
+export function parseDroidRoutingLine(line) {
+  if (!line.includes("[Model-Router] Model transition | Context: ")) return null;
+  let context; try { context = JSON.parse(line.split(" | Context: ").slice(1).join(" | Context: ")); } catch { return null; }
+  if (context.slot !== "main" || typeof context.sessionId !== "string" || typeof context.modelId !== "string") return null;
+  return { session_id: context.sessionId, model: context.modelId, previous_model: context.previousModelId ?? null,
+    reason: typeof context.reason === "string" ? context.reason : null, native_timestamp: /^\[([^\]]+)\]/.exec(line)?.[1] ?? null,
+    event_sha256: createHash("sha256").update(line).digest("hex") };
+}
+
+/** Keep the cursor in daemon state. Bound every read, tolerate incomplete lines
+ * and restart from zero after truncation/rotation of this execution's own log. */
+export async function readDroidRoutingLog(file, cursor = {}) {
+  let handle;
+  try { handle = await open(file, "r"); } catch (error) { if (error.code === "ENOENT") return { cursor, events: [] }; throw error; }
+  try {
+    const info = await handle.stat();
+    const offset = info.ino === cursor.ino && info.size >= (cursor.offset ?? 0) ? cursor.offset ?? 0 : 0;
+    const buffer = Buffer.alloc(Math.min(1_048_576, Math.max(0, info.size - offset)));
+    const { bytesRead } = await handle.read(buffer, 0, buffer.length, offset);
+    const end = buffer.subarray(0, bytesRead).lastIndexOf(10) + 1;
+    const lines = buffer.subarray(0, end).toString("utf8").split("\n");
+    // Persist offsets only, never a partial native line that may contain secrets.
+    return { cursor: { ino: info.ino, offset: offset + (end || (bytesRead === buffer.length && bytesRead === 1_048_576 ? bytesRead : 0)) }, events: lines.map(parseDroidRoutingLine).filter(Boolean) };
+
+  } finally { await handle.close(); }
+}

package/dist/harness-runtime/lib/managed-daemon.mjs

@@ -0,0 +1,119 @@
+import { lstat } from "node:fs/promises";
+import { commandJson } from "./process-json.mjs";
+import { errorRecord } from "./operation-errors.mjs";
+
+const leases = new Map();
+
+export function assertDaemonOwnership() {
+  for (const lease of leases.values()) if (lease.error) throw lease.error;
+}
+
+export async function runtimeProcess(config, action, options = {}) {
+  if (!config.resourceHome || !config.ddFlowHome || !config.ddFlowBin) return null;
+  const args = ["runtime", "process", action];
+  for (const [key, value] of Object.entries(options)) if (value !== null && value !== undefined) args.push(`--${key}`, String(value));
+  return await commandJson(config.ddFlowBin, args, {
+    cwd: config.cwd,
+    env: { ...(config.env ?? {}), DD_FLOW_HOME: config.ddFlowHome, DD_FLOW_RESOURCE_HOME: config.resourceHome }
+  });
+}
+
+export async function registerDaemonProcess(config, input) {
+  const result = await runtimeProcess(config, "register", { ...input, "owner-pid": process.pid, "lease-ms": 300_000 });
+  return result?.process ? { id: result.process.id, lease_token: result.process.lease_token, kind: input.kind } : null;
+}
+
+export async function confirmDaemonProcess(config, record, child) {
+  if (!record) return;
+  if (!child?.pid) {
+    await finishDaemonProcess(config, record, "failed", "daemon_spawn_missing_pid");
+    return;
+  }
+  await runtimeProcess(config, "confirm", { id: record.id, "lease-token": record.lease_token, pid: child.pid, "process-group-id": child.pid, "owner-pid": record.kind?.endsWith("-daemon") ? child.pid : process.pid, "lease-ms": 300_000 });
+}
+
+export async function heartbeatDaemonProcess(config, record) {
+  if (!record?.id || !record.lease_token) return;
+  let lease = leases.get(record.id);
+  if (!lease) {
+    lease = { pending: null, error: null, timer: null, lost: false };
+    leases.set(record.id, lease);
+    lease.timer = setInterval(() => { void heartbeatDaemonProcess(config, record).catch(() => {}); }, 60_000);
+    lease.timer.unref();
+  }
+  if (lease.lost) throw lease.error;
+  if (lease.pending) return await lease.pending;
+  lease.pending = (async () => {
+    try {
+      const result = await runtimeProcess(config, "heartbeat", { id: record.id, "lease-token": record.lease_token, "lease-ms": 300_000 });
+      if (result?.ok !== true) {
+        lease.lost = true; clearInterval(lease.timer);
+        throw Object.assign(new Error("managed process lease is no longer owned; new productive operations are blocked"), { code: "process_lease_lost", details: { process_id: record.id } });
+      }
+      lease.error = null;
+    } catch (cause) {
+      lease.error = cause.code === "process_lease_lost" ? cause : Object.assign(new Error("cannot confirm managed process ownership"), { code: "process_ownership_unknown", cause, details: { process_id: record.id } });
+      throw lease.error;
+    }
+  })();
+  try { await lease.pending; } finally { lease.pending = null; }
+}
+
+export async function finishDaemonProcess(config, process, state = "stopped", reason = "daemon_stopped") {
+  if (process?.id && process.lease_token) {
+    const lease = leases.get(process.id); if (lease) clearInterval(lease.timer);
+    const result = await runtimeProcess(config, "finish", { id: process.id, "lease-token": process.lease_token, state, reason });
+    if (result?.ok !== true) throw Object.assign(new Error("managed process finish was not accepted"), { code: "process_lease_lost", details: { process_id: process.id } });
+    leases.delete(process.id);
+  }
+}
+
+/** Preserve the startup error and retain the lease/resources if cleanup cannot
+ * prove termination. A failed cleanup is not a terminal managed process. */
+export async function cleanupFailedStart(config, record, child, original) {
+  try {
+    await stopProcessGroup(child);
+    await finishDaemonProcess(config, record, "failed", original.code ?? "startup_failed");
+  } catch (cleanup) {
+    original.details = { ...original.details, cleanup_failed: errorRecord(cleanup), process_id: record?.id ?? null, pid: child?.pid ?? null };
+  }
+}
+
+export async function stopProcessGroup(child, graceMs = 1_000) {
+  if (!child?.pid) return;
+  // Harness bridges are detached on Unix, so their own process group is the
+  // smallest reliable unit of cleanup. Windows has no equivalent negative-PID
+  // signal operation; there the direct child is the safe best effort.
+  const target = process.platform === "win32" ? child.pid : -child.pid;
+  const alive = () => { try { process.kill(target, 0); return true; } catch (error) { if (error.code === "ESRCH") return false; if (error.code === "EPERM") return true; throw error; } };
+  if (!alive()) return;
+  if (child.exitCode !== undefined && child.exitCode !== null) {
+    // The leader can exit a few ticks before its helpers. Observe their normal
+    // shutdown before failing ownership; never signal a leaderless group.
+    const deadline = Date.now() + Math.max(1_000, graceMs);
+    while (alive() && Date.now() < deadline) await new Promise(resolve => setTimeout(resolve, 25));
+    if (!alive()) return;
+    throw Object.assign(new Error("process group remains after its leader exited; ownership cannot be proven from this child handle"), { code: "process_group_ownership_unknown", details: { pid: child.pid } });
+  }
+  process.kill(target, "SIGTERM");
+  await new Promise((resolve) => setTimeout(resolve, graceMs));
+  if (!alive()) return;
+  process.kill(target, "SIGKILL");
+  // Grace controls escalation, not the OS acknowledgement budget. A caller
+  // testing immediate escalation must still allow the kernel to reap children.
+  const deadline = Date.now() + Math.max(1_000, graceMs);
+  while (alive() && Date.now() < deadline) await new Promise((resolve) => setTimeout(resolve, 25));
+  if (alive()) throw Object.assign(new Error(`process group ${child.pid} did not stop`), { code: "process_group_stop_incomplete" });
+}
+
+/** A daemon acknowledgement is not a completed stop until its endpoint closes. */
+export async function confirmDaemonStopped(request, socket, timeoutMs = 30_000) {
+  const result = await request();
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try { await lstat(socket); }
+    catch (error) { if (error.code === "ENOENT") return result; throw error; }
+    await new Promise((resolve) => setTimeout(resolve, 25));
+  }
+  throw Object.assign(new Error("daemon acknowledged stop but its socket remained live"), { code: "daemon_stop_incomplete", details: { socket } });
+}

package/dist/harness-runtime/lib/model-observations.mjs

@@ -0,0 +1,77 @@
+import { createHash } from "node:crypto";
+import { mkdir, open, readFile } from "node:fs/promises";
+import path from "node:path";
+import { withRunnerLock } from "./runner-lock.mjs";
+
+const text = value => typeof value === "string" && value.trim() ? value.trim() : null;
+const fields = ["provider", "model", "reasoning", "mode", "permission_mode"];
+export const observedFields = value => Object.fromEntries(fields.map(key => [key, text(value?.[key])]));
+export const modelObservationFile = journal => path.join(path.dirname(journal), "model-observations.jsonl");
+
+/** Routing is allowed. Permission/autonomy changes remain integrity failures.
+ * Missing native fields are unknown, never proof that the request was applied. */
+export function checkObservedProfile(requested, observed, { strict = false, required = [] } = {}) {
+  const unknown = fields.filter(key => requested?.[key] && !observed?.[key]);
+  const changes = fields.filter(key => requested?.[key] && observed?.[key] && requested[key] !== observed[key]);
+  const violations = changes.filter(key => strict || ["mode", "permission_mode"].includes(key));
+  const missing = required.filter(key => !observed?.[key]);
+  if (violations.length || missing.length) throw Object.assign(new Error("native execution profile integrity is not confirmed"), {
+    code: "profile_integrity_violation", details: { requested: observedFields(requested), observed: observedFields(observed), violations, missing }
+  });
+  return { requested: observedFields(requested), observed: observedFields(observed), status: unknown.length ? "incomplete" : changes.length ? "mixed" : "matched", matched: !unknown.length && !changes.length, unknown, changes };
+}
+
+export async function readModelObservations(journal) {
+  try { const text = await readFile(modelObservationFile(journal), "utf8"); return text.slice(0, text.lastIndexOf("\n") + 1).split("\n").filter(Boolean).map(JSON.parse); }
+  catch (error) { if (error.code === "ENOENT") return []; throw error; }
+}
+
+/** Only adapter-verified native facts enter this file. It records changes,
+ * not every tool or token; reading it never requires replaying native history. */
+export async function observeModel({ journal, harness, sessionId, parentSessionId = null, requested = {}, observed = {}, source, evidence = "configured", reason = null, nativeTimestamp = null, previousModel = null }) {
+  if (!journal || !sessionId) return null;
+  if (!source || !["configured", "request", "response", "unavailable"].includes(evidence)) throw new Error("model observation requires a native source and evidence level");
+  const file = modelObservationFile(journal), profile = observedFields(observed);
+  await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+  return withRunnerLock(file, async () => {
+    const events = await readModelObservations(journal);
+    const replay = source?.event_sha256 ? events.find(item => item.session_id === sessionId && item.source?.event_sha256 === source.event_sha256) : null;
+    if (replay) return replay;
+    const channel = source?.channel ?? evidence;
+    const previous = events.findLast(item => item.harness === harness && item.session_id === sessionId && (item.source?.channel ?? item.evidence) === channel);
+    const normalizedReason = text(reason)?.slice(0, 200) ?? null;
+    if (previous && JSON.stringify(previous.observed) === JSON.stringify(profile) && previous.reason === normalizedReason && previous.evidence === evidence) return previous;
+    const previousKnown = events.findLast(item => item.harness === harness && item.session_id === sessionId && item.evidence === evidence && item.observed?.model);
+    const fromModel = text(previousModel) ?? previousKnown?.observed.model ?? null;
+    const changed = Boolean(profile.model && fromModel && profile.model !== fromModel);
+    const value = { schema_id: "dd-flow/model-observation@1", sequence: events.length + 1,
+      harness, session_id: sessionId, parent_session_id: parentSessionId,
+      kind: changed ? "model_changed" : !profile.model ? "model_observation_unavailable" : "model_observed",
+      previous_model: fromModel, requested: observedFields(requested), observed: profile,
+      source, evidence, reason: normalizedReason, native_timestamp: text(nativeTimestamp), observed_at: new Date().toISOString() };
+    value.id = createHash("sha256").update(JSON.stringify(value)).digest("hex");
+    const handle = await open(file, "a", 0o600);
+    try {
+      const bytes = await readFile(file); const committed = bytes.lastIndexOf(10) + 1;
+      if (committed < bytes.length) await handle.truncate(committed);
+      await handle.write(`${JSON.stringify(value)}\n`); await handle.sync();
+    } finally { await handle.close(); }
+    const directory = await open(path.dirname(file), "r");
+    try { await directory.sync(); } finally { await directory.close(); }
+    return value;
+  });
+}
+
+export function modelAttribution(events) {
+  const sessions = new Map();
+  for (const event of events) {
+    const key = `${event.harness}:${event.session_id}`;
+    const session = sessions.get(key) ?? { harness: event.harness, session_id: event.session_id, parent_session_id: event.parent_session_id, requested: event.requested, observations: [] };
+    session.observations.push(event); sessions.set(key, session);
+  }
+  const models = [...new Set(events.map(event => event.observed?.model).filter(Boolean))];
+  const incomplete = !events.length || [...sessions.values()].some(session => session.observations.some(event => event.evidence === "unavailable" || !event.observed?.model));
+  return { models, mixed: models.length > 1 || events.some(event => event.observed?.model && event.requested?.model && event.observed.model !== event.requested.model),
+    observation_completeness: incomplete ? "incomplete" : "available_native_sources", transitions: events.filter(event => event.kind === "model_changed"),
+    sessions: [...sessions.values()], usage_attribution: "session_totals_unattributed_to_model", note: "Native settings/events do not prove undisclosed server routing or per-model token costs." };
+}

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

@@ -0,0 +1,33 @@
+/** Only observed time counts toward inactivity. A scheduling/clock gap is not
+ * evidence of OS sleep, nor of provider progress. Call sample regularly. */
+export class ObservationClock {
+  constructor({ timeoutMs, gapMs = 60_000, wall = Date.now, monotonic = () => performance.now(), onGap = () => {} }) {
+    if (!(timeoutMs > 0) || !(gapMs > 0)) throw new RangeError("positive observation timeout and gap required");
+    Object.assign(this, { timeoutMs, gapMs, wall, monotonic, onGap });
+    this.lastWall = wall(); this.lastMono = monotonic(); this.elapsed = 0;
+    this.progress = undefined;
+  }
+  sample(progress) {
+    const wall = this.wall(), mono = this.monotonic();
+    const delta = mono - this.lastMono, wallDelta = wall - this.lastWall;
+    const gap = delta > this.gapMs || wallDelta > this.gapMs || delta < 0 || wallDelta < 0;
+    if (gap) {
+      this.onGap({ source: "observer_clock", classification: "observation_gap", confirmed_sleep: false,
+        started_at: new Date(this.lastWall).toISOString(), observed_at: new Date(wall).toISOString(),
+        wall_delta_ms: wallDelta, monotonic_delta_ms: delta });
+      this.elapsed = 0;
+    } else this.elapsed += delta;
+    this.lastWall = wall; this.lastMono = mono;
+    if (progress !== undefined && progress !== this.progress) { this.progress = progress; this.elapsed = 0; }
+    return this.elapsed >= this.timeoutMs;
+  }
+}
+
+/** Node timeout handle: callers can keep their existing clearTimeout cleanup. */
+export function observedTimeout(callback, timeoutMs, options = {}) {
+  const clock = new ObservationClock({ timeoutMs, ...options });
+  const timer = setInterval(() => {
+    if (clock.sample(options.progress?.())) { clearInterval(timer); callback(); }
+  }, Math.max(1, Math.min(1_000, timeoutMs / 4)));
+  return timer;
+}

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.mjs

@@ -0,0 +1,19 @@
+// An observer losing its response does not establish that a provider Turn failed.
+export function isObservationLoss(error) {
+  return ["rpc_timeout", "daemon_timeout", "turn_timeout", "operation_observation_lost", "daemon_connection_closed"].includes(error?.code);
+}
+
+export function errorRecord(error, depth = 0) {
+  return {
+    code: typeof error?.code === "string" ? error.code : "operation_failed",
+    message: typeof error?.message === "string" ? error.message : String(error),
+    ...(typeof error?.retryable === "boolean" ? { retryable: error.retryable } : {}),
+    ...(error?.details !== undefined ? { details: error.details } : {}),
+    ...(error?.cause && depth < 3 ? { cause: errorRecord(error.cause, depth + 1) } : {}),
+  };
+}
+
+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/process-json.mjs

@@ -0,0 +1,61 @@
+import { spawn } from "node:child_process";
+import { reportedError } from "./operation-errors.mjs";
+
+function failure(message, code) {
+  return Object.assign(new Error(message), { code });
+}
+
+function reportedFailure(stdout, stderr, fallback) {
+  for (const text of [stdout, stderr]) {
+    for (const line of text.trim().split(/\n/).reverse()) {
+      try {
+        const value = JSON.parse(line);
+        const error = value?.error;
+        if (typeof error?.code === "string" && error.code) return reportedError(error, fallback);
+      } catch { /* Not a structured CLI error line. */ }
+    }
+  }
+  return failure(stderr.trim() || stdout.trim() || fallback, "flow_reconciliation_failed");
+}
+
+function processTarget(executable, args) {
+  return /\.[cm]?js$/.test(executable) ? { command: process.execPath, args: [executable, ...args] } : { command: executable, args };
+}
+
+export async function commandJson(bin, args, { cwd, env = {}, input = null, onProgress = null } = {}) {
+  return await new Promise((resolve, reject) => {
+    // A canonical runtime may intentionally shadow the ambient `dd-flow`
+    // executable with its captured engine.  Keep that choice in the supplied
+    // environment rather than letting a host-global shim leak into a run.
+    const executable = bin === "dd-flow" && typeof env.DD_FLOW_BIN === "string" ? env.DD_FLOW_BIN : bin;
+    const target = processTarget(executable, [...args, "--json"]);
+    const child = spawn(target.command, target.args, { cwd, env: { ...process.env, ...env }, stdio: [input === null ? "ignore" : "pipe", "pipe", "pipe"] });
+    let stdout = ""; let stderr = ""; let pendingStderr = "";
+    child.stdout.setEncoding("utf8").on("data", (data) => { stdout += data; });
+    child.stderr.setEncoding("utf8").on("data", (data) => {
+      stderr += data; pendingStderr += data;
+      for (;;) {
+        const end = pendingStderr.indexOf("\n"); if (end < 0) break;
+        const line = pendingStderr.slice(0, end); pendingStderr = pendingStderr.slice(end + 1);
+        if (typeof onProgress === "function") { try { onProgress(JSON.parse(line)); } catch { /* Ordinary diagnostics stay in stderr evidence. */ } }
+      }
+    });
+    child.on("error", reject);
+    if (input !== null) child.stdin.end(input);
+    child.on("close", (status) => {
+      if (status !== 0) return reject(reportedFailure(stdout, stderr, `${executable} exited ${status}`));
+      try { resolve(JSON.parse(stdout.trim())); }
+      catch (error) { reject(failure(`${bin} returned invalid JSON: ${error.message}`, "flow_reconciliation_failed")); }
+    });
+  });
+}
+
+export async function commandText(bin, args, { cwd, env = {} } = {}) {
+  return await new Promise((resolve, reject) => {
+    const executable = bin === "dd-flow" && typeof env.DD_FLOW_BIN === "string" ? env.DD_FLOW_BIN : bin;
+    const target = processTarget(executable, args);
+    const child = spawn(target.command, target.args, { cwd, env: { ...process.env, ...env }, stdio: ["ignore", "pipe", "pipe"] }); let stdout = ""; let stderr = "";
+    child.stdout.setEncoding("utf8").on("data", (data) => { stdout += data; }); child.stderr.setEncoding("utf8").on("data", (data) => { stderr += data; }); child.on("error", reject);
+    child.on("close", (status) => status === 0 ? resolve(stdout.trim()) : reject(failure(stderr.trim() || stdout.trim() || `${executable} exited ${status}`, "command_failed")));
+  });
+}

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") }] : []; });
+}