@deksden-com/dd-flow-cli 0.9.0-beta.10 → 0.9.0-beta.103

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

@@ -0,0 +1,296 @@
+import { lstat, readFile, readdir, mkdir } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import { commandJson } from "./process-json.mjs";
+import { errorRecord } from "./operation-errors.mjs";
+import { writeJsonAtomic } from "./runner-events.mjs";
+import { runBoundedCommand } from "./native-hook-command.mjs";
+
+const leases = new Map();
+
+/** Freeze resource ownership independently of whether Subject hooks are enabled. */
+export function bindRuntimeOwner(config, env = process.env) {
+  const raw = Object.hasOwn(config, "runtime_owner") ? config.runtime_owner === null ? undefined : JSON.stringify(config.runtime_owner) : env.DD_FLOW_RUNTIME_OWNER;
+  if (raw === undefined) return config.runtime_owner = null;
+  let owner;
+  try { if (raw.length > 16_384) throw new Error(); owner = JSON.parse(raw); }
+  catch { throw Object.assign(new Error("runtime ownership descriptor is invalid"), { code: "runtime_owner_invalid" }); }
+  const fields = ["schema_id", "owner_id", "role", "project_id", "run_id", "work_id", "operation_id", "state_dir", "dd_flow_home", "dd_flow_bin", "resource_home", "adapter_executable", "budget"];
+  const text = value => typeof value === "string" && value.trim().length > 0;
+  if (!owner || typeof owner !== "object" || Array.isArray(owner) || Object.keys(owner).some(key => !fields.includes(key))
+    || owner.schema_id !== "dd-flow/runtime-owner@1" || !text(owner.owner_id) || !text(owner.operation_id)
+    || !["subject", "worker", "merge", "judge", "probe"].includes(owner.role)
+    || ["state_dir", "dd_flow_home", "dd_flow_bin", "resource_home"].some(key => !text(owner[key]) || !path.isAbsolute(owner[key]))
+    || (owner.adapter_executable !== undefined && (!text(owner.adapter_executable) || !path.isAbsolute(owner.adapter_executable)))
+    || ["project_id", "run_id", "work_id"].some(key => owner[key] !== undefined && !text(owner[key]))
+    || (["subject", "worker", "merge"].includes(owner.role) && (!text(owner.project_id) || !text(owner.run_id)))
+    || (["worker", "merge"].includes(owner.role) && !text(owner.work_id))
+    || (["judge", "probe"].includes(owner.role) && owner.work_id !== undefined)) {
+    throw Object.assign(new Error("runtime ownership descriptor does not match its role and scope"), { code: "runtime_owner_invalid" });
+  }
+  if (owner.budget !== undefined) {
+    const budget = owner.budget, names = ["codex-desktop", "zcode-acp", "grok-acp", "antigravity-cli", "opencode-server", "droid-cli"];
+    if (!budget || typeof budget !== "object" || Array.isArray(budget) || Object.keys(budget).some(key => !["schema_id", "scope_id", "per_harness"].includes(key)) || budget.schema_id !== "dd-flow/runtime-budget@1" || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(budget.scope_id ?? "") || !budget.per_harness || typeof budget.per_harness !== "object" || Array.isArray(budget.per_harness) || Object.entries(budget.per_harness).some(([name, limit]) => !names.includes(name) || !Number.isSafeInteger(limit) || limit < 1 || limit > 1024)) throw Object.assign(new Error("runtime owner budget is invalid"), { code: "runtime_budget_invalid" });
+  }
+  config.runtime_owner = Object.fromEntries(fields.filter(key => owner[key] !== undefined).map(key => [key, owner[key]]));
+  return config.runtime_owner;
+}
+
+/** Reject rebinding before provider setup, including the already-running path. */
+export async function prepareRuntimeOwner(config, stateDir, env = process.env) {
+  const owner = bindRuntimeOwner(config, env);
+  if (owner && path.resolve(owner.state_dir) !== path.resolve(stateDir)) {
+    throw Object.assign(new Error("runtime owner belongs to another state directory"), { code: "runtime_owner_mismatch" });
+  }
+  let previous;
+  try { previous = JSON.parse(await readFile(path.join(stateDir, "daemon.json"), "utf8")); }
+  catch (error) { if (error.code === "ENOENT") return owner; throw error; }
+  const retained = bindRuntimeOwner({ runtime_owner: previous?.config?.runtime_owner ?? null }, {});
+  if (JSON.stringify(retained) !== JSON.stringify(owner)) {
+    throw Object.assign(new Error("retained daemon ownership differs; use explicit recovery instead of rebinding its sessions"), { code: "runtime_owner_mismatch" });
+  }
+  return owner;
+}
+
+export async function assertDaemonOwnership(stateDir, dispatch = {}, assertCurrent = () => {}) {
+  for (const lease of leases.values()) {
+    if (lease.error) throw lease.error;
+    if (Date.now() >= lease.expiresAt) throw Object.assign(new Error("managed process renewal is overdue"), { code: "process_ownership_unknown" });
+  }
+  const state = JSON.parse(await readFile(path.join(stateDir, "daemon.json"), "utf8"));
+  const owner = bindRuntimeOwner({ runtime_owner: state.config?.runtime_owner ?? null }, {});
+  if (!owner) return;
+  const record = state.resource_process;
+  if (owner.state_dir !== stateDir || !record?.id || !record.lease_token) throw Object.assign(new Error("owned daemon has no confirmed resource binding"), { code: "process_ownership_unknown" });
+  for (;;) {
+    assertCurrent();
+    const result = await runtimeProcess(state.config, "admission", { id: record.id, "lease-token": record.lease_token, owner: owner.owner_id, "state-dir": stateDir, "daemon-id": state.daemon_id ?? state.config?.daemonId, ...dispatch });
+    assertCurrent();
+    if (result?.ok === true && result.admitted === true && result.process_id === record.id) return;
+    if (result?.ok !== true || result.reason !== "provider_capacity" || result.process_id !== record.id) throw Object.assign(new Error("productive runtime admission was not confirmed"), { code: "process_ownership_unknown" });
+    const predecessor = result.blocking_turns?.find(turn => turn?.process_id === record.id
+      && turn?.session_id === dispatch["native-session-id"]
+      && turn?.operation_id !== dispatch["operation-id"]);
+    if (predecessor) throw Object.assign(new Error("the same managed Session has an unsettled productive predecessor; reconcile it before dispatching another Turn"), {
+      code: "settlement_reconciliation_required",
+      details: { session_id: dispatch["native-session-id"], predecessor_operation_id: predecessor.operation_id, predecessor_operation: predecessor.operation }
+    });
+    // The daemon, not its disposable socket client, owns this queue. Recheck
+    // the RUN fence and process lease on every admission attempt.
+    await new Promise(resolve => setTimeout(resolve, 250));
+  }
+}
+
+/** Snapshot terminal operations BEFORE observing native idle. A later Turn
+ * cannot be released by an older observation of the same Session. */
+export async function budgetObservationScope(stateDir, sessionId) {
+  const state = await budgetState(stateDir);
+  if (!state?.config?.runtime_owner?.budget || !sessionId) return null;
+  const daemonId = state.daemon_id ?? state.config?.daemonId, operationIds = [];
+  for (const name of await readdir(path.join(stateDir, "operations")).catch(error => { if (error.code === "ENOENT") return []; throw error; })) {
+    const directory = path.join(stateDir, "operations", name);
+    try {
+      const requested = JSON.parse(await readFile(path.join(directory, "requested.json"), "utf8"));
+      const result = JSON.parse(await readFile(path.join(directory, "result.json"), "utf8"));
+      if (requested.daemon_id === daemonId && requested.session_id === sessionId && ["completed", "failed", "interrupted"].includes(result.state) && ["session.prompt", "session.start", "session.resume"].includes(requested.operation)) operationIds.push(requested.operation_id);
+    } catch (error) { if (error.code !== "ENOENT") throw error; }
+  }
+  return { stateDir, state, daemonId, sessionId, operationIds };
+}
+
+export async function releaseBudgetObservation(scope, observation) {
+  if (!scope || !scope.operationIds.length || observation?.settled !== true) return;
+  const id = observation.provider_session_id ?? observation.session_id ?? observation.adapter_session_id;
+  if (id !== scope.sessionId) throw Object.assign(new Error("budget observation belongs to another Session"), { code: "session_identity_mismatch" });
+  const directory = path.join(scope.stateDir, "budget-observations");
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  const file = path.join(directory, `${randomUUID()}.json`);
+  await writeJsonAtomic(file, { daemon_id: scope.daemonId, session_id: scope.sessionId, settled: true, operation_ids: scope.operationIds, observed_at: new Date().toISOString() });
+  await releaseBudget(scope.state, { "observation-file": file });
+}
+
+export async function completeBudgetOperation(stateDir, request, result, observe) {
+  const state = await budgetState(stateDir);
+  if (!state?.config?.runtime_owner?.budget) return { state: "not_required" };
+  if (["session.create", "session.fork"].includes(request.operation)) {
+    await releaseBudget(state, { "operation-id": request.id });
+    return { state: "settled", operation_ids: [request.id], source: "creation_receipt" };
+  }
+  const sessionId = request.params?.sessionId;
+  // A productive daemon receipt is bound to this exact dispatch. Reuse its
+  // complete tree proof instead of immediately asking the provider again.
+  if (["session.prompt", "session.start", "session.resume"].includes(request.operation)
+    && result?.settled === true
+    && typeof sessionId === "string"
+    && (result.provider_session_id ?? result.session_id ?? result.adapter_session_id) === sessionId) {
+    const scope = { stateDir, state, daemonId: state.daemon_id ?? state.config?.daemonId, sessionId, operationIds: [request.id] };
+    await releaseBudgetObservation(scope, result);
+    return { state: "settled", operation_ids: [request.id], source: "operation_receipt" };
+  }
+  // A known live tree is not a reason to poll it again. Preserve capacity and
+  // let the next explicit reconciliation obtain fresh proof.
+  if (result?.settled === false) return { state: "pending", reason: "tree_unsettled" };
+  const scope = await budgetObservationScope(stateDir, request.params?.sessionId);
+  if (!scope?.operationIds.length) return { state: "not_required" };
+  // Reconciliation requires a fresh, explicit proof.  Treating an arbitrary
+  // productive reply as proof would silently release a live turn.
+  if (!observe) return { state: "pending", reason: "settlement_evidence_required" };
+  const observation = await observe();
+  if (observation?.settled !== true) return { state: "pending", reason: "tree_unsettled" };
+  await releaseBudgetObservation(scope, observation);
+  return { state: "settled", operation_ids: scope.operationIds, source: "reconciliation_observation" };
+}
+
+async function budgetState(stateDir) {
+  try { return JSON.parse(await readFile(path.join(stateDir, "daemon.json"), "utf8")); }
+  catch (error) { if (error.code === "ENOENT") return null; throw error; }
+}
+
+async function releaseBudget(state, options) {
+  const record = state.resource_process, owner = state.config.runtime_owner;
+  const receipt = await runtimeProcess(state.config, "release-turn", { id: record.id, "lease-token": record.lease_token, owner: owner.owner_id, "daemon-id": state.daemon_id ?? state.config?.daemonId, ...options });
+  if (receipt?.ok !== true) throw Object.assign(new Error("runtime budget release was not confirmed"), { code: "runtime_budget_release_unconfirmed" });
+}
+
+export async function runtimeProcess(config, action, options = {}) {
+  const owner = config.runtime_owner;
+  const resourceHome = owner?.resource_home ?? config.resourceHome;
+  const ddFlowHome = owner?.dd_flow_home ?? config.ddFlowHome;
+  const ddFlowBin = owner?.dd_flow_bin ?? config.ddFlowBin;
+  if (!resourceHome || !ddFlowHome || !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));
+  if (action === "heartbeat") return JSON.parse(await runBoundedCommand({ bin: ddFlowBin, args: [...args, "--json"], cwd: config.cwd,
+    env: { ...(config.env ?? {}), DD_FLOW_HOME: ddFlowHome, DD_FLOW_RESOURCE_HOME: resourceHome }, timeoutMs: 15_000, timeoutCode: "process_heartbeat_timeout" }));
+  return await commandJson(ddFlowBin, args, {
+    cwd: config.cwd,
+    env: { ...(config.env ?? {}), DD_FLOW_HOME: ddFlowHome, DD_FLOW_RESOURCE_HOME: resourceHome }
+  });
+}
+
+export async function registerDaemonProcess(config, input) {
+  const owner = bindRuntimeOwner(config);
+  const harness = ({ "codex-daemon": "codex-desktop", "codex-provider": "codex-desktop", "zcode-daemon": "zcode-acp", "zcode-provider": "zcode-acp", "grok-daemon": "grok-acp", "grok-provider": "grok-acp", "agy-daemon": "antigravity-cli", "opencode-daemon": "opencode-server", "droid-daemon": "droid-cli" })[input.kind];
+  const scope = owner ? { owner: owner.owner_id, "project-id": owner.project_id, run: owner.run_id, work: owner.work_id, role: owner.role, "state-dir": owner.state_dir, "adapter-executable": owner.adapter_executable, ...(owner.budget ? { "budget-json": JSON.stringify(owner.budget), harness } : {}), ...(owner.project_id && owner.run_id || owner.budget ? { "dispatch-barrier": "run-generation@1" } : {}), operation: `${owner.operation_id}:${input.operation ?? input.kind}` } : {};
+  const result = await runtimeProcess(config, "register", { ...input, ...scope, "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 });
+}
+
+/** Provider bridges use a different process group from their daemon. Publish
+ * the exact binding before initialize can start productive provider traffic. */
+export async function startManagedBridge({ config, state, bridge, kind, publish }) {
+  state.pid = process.pid;
+  await publish(state);
+  const provider = config.runtime_owner ? await registerDaemonProcess(config, { kind, owner: config.runtime_owner.owner_id, operation: kind }) : null;
+  bridge.options.onSpawn = async child => {
+    await confirmDaemonProcess(config, provider, child);
+    await heartbeatDaemonProcess(config, provider);
+    state.provider_pid = child.pid;
+    state.provider_process = provider;
+    await publish(state);
+  };
+  try { return await bridge.start(); }
+  catch (error) { await cleanupFailedStart(config, provider, bridge.child, error); throw error; }
+}
+
+export async function closeManagedBridge(config, state, bridge) {
+  await bridge.close();
+  await finishDaemonProcess(config, state.provider_process, "stopped", "daemon_stopped");
+}
+
+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, expiresAt: Date.now() + 300_000 };
+    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;
+      lease.expiresAt = Date.now() + 300_000;
+    } 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) || (child.signalCode !== undefined && child.signalCode !== 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;
+  if (child.exitCode != null || child.signalCode != null) return stopProcessGroup(child, graceMs);
+  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/native-hook-command.d.mts

@@ -0,0 +1 @@
+export function invokeNativeHook(input: { bin: string; args: string[]; payload: unknown; home?: string | undefined; timeoutMs?: number }): Promise<Record<string, unknown> & { timing?: Record<string, number> }>;

package/dist/harness-runtime/lib/native-hook-command.mjs

@@ -0,0 +1,108 @@
+import { spawn } from "node:child_process";
+import { reportedFailure } from "./process-json.mjs";
+
+/** Native command hooks have a 30s outer limit; leave room for transport and cleanup. */
+export function hookBudget(timeoutMs = 25_000, deadlineAt = null) {
+  const started = performance.now();
+  const duration = Math.max(0, Math.min(timeoutMs, Number.isFinite(deadlineAt) ? deadlineAt - Date.now() : timeoutMs));
+  const remaining = (phase, maximum = duration) => {
+    const value = duration - (performance.now() - started);
+    if (value <= 0) throw Object.assign(new Error(`Native hook deadline exceeded during ${phase}`), { code: "native_hook_timeout", details: { phase, elapsed_ms: Math.round(performance.now() - started), effect: "unknown" } });
+    return Math.max(1, Math.min(maximum, value));
+  };
+  return { deadlineAt: Date.now() + duration, remaining, async run(action, phase) {
+    const timeoutMs = remaining(phase);
+    let timer;
+    try { return await Promise.race([Promise.resolve().then(action), new Promise((_, reject) => { timer = setTimeout(() => reject(Object.assign(new Error(`Native hook deadline exceeded during ${phase}`), { code: "native_hook_timeout", details: { phase, effect: "unknown" } })), timeoutMs); })]); }
+    finally { clearTimeout(timer); }
+  } };
+}
+
+/** Bound native hook ingress before parsing or opening adapter state. */
+export function readNativeHookInput(stream, budget, maxBytes = 1_048_576) {
+  return new Promise((resolve, reject) => {
+    const chunks = []; let bytes = 0, done = false;
+    const cleanup = () => { clearTimeout(timer); stream.off("data", onData); stream.off("end", onEnd); stream.off("error", onError); };
+    const finish = (error, value) => { if (done) return; done = true; cleanup(); if (error) { stream.destroy(); reject(error); } else resolve(value); };
+    const onData = chunk => {
+      const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      bytes += buffer.length;
+      if (bytes > maxBytes) finish(Object.assign(new Error("Native hook input exceeds 1 MiB"), { code: "native_hook_input_too_large" }));
+      else chunks.push(buffer);
+    };
+    const onEnd = () => finish(null, Buffer.concat(chunks).toString("utf8"));
+    const onError = error => finish(error);
+    let timeoutMs;
+    try { timeoutMs = budget.remaining("input"); } catch (error) { reject(error); return; }
+    const timer = setTimeout(() => finish(Object.assign(new Error("Native hook deadline exceeded during input"), { code: "native_hook_timeout", details: { phase: "input", effect: "unknown" } })), timeoutMs);
+    stream.on("data", onData).once("end", onEnd).once("error", onError);
+    stream.resume();
+  });
+}
+
+export async function terminateCommandTree(child, { platform = process.platform, launch = spawn, timeoutMs = 400 } = {}) {
+  if (!child.pid) return;
+  if (platform !== "win32") { process.kill(-child.pid, "SIGKILL"); return; }
+  // Node's child.kill on Windows only terminates the leader. taskkill is the
+  // native subtree primitive; bound its own lifetime as well as the request.
+  await new Promise((resolve, reject) => {
+    const killer = launch("taskkill", ["/PID", String(child.pid), "/T", "/F"], { windowsHide: true, stdio: "ignore" });
+    let settled = false, timer;
+    const finish = error => { if (settled) return; settled = true; clearTimeout(timer); error ? reject(error) : resolve(); };
+    timer = setTimeout(() => { killer.kill("SIGKILL"); killer.unref(); finish(Object.assign(new Error("Windows subtree cleanup timed out"), { code: "process_cleanup_timeout" })); }, timeoutMs);
+    killer.once("error", finish);
+    killer.once("close", code => finish(code === 0 ? null : Object.assign(new Error(`taskkill exited ${code}`), { code: "process_cleanup_failed" })));
+  });
+}
+
+/** Preserve the native hook protocol across the CLI process boundary. */
+export async function runBoundedCommand({ bin, args, input = null, cwd, env = {}, timeoutMs = 15_000, timeoutCode = "native_hook_timeout" }) {
+  const started = performance.now();
+  const script = /\.[cm]?js$/.test(bin);
+  const output = await new Promise((resolve, reject) => {
+    const child = spawn(script ? process.execPath : bin, [...(script ? [bin] : []), ...args], {
+      cwd, env: { ...process.env, ...env }, detached: process.platform !== "win32", stdio: ["pipe", "pipe", "pipe"]
+    });
+    let stdout = "", stderr = "", failure, cleanupTimer, settled = false, termination;
+    const finish = (error, value) => { if (settled) return; settled = true; clearTimeout(timer); clearTimeout(cleanupTimer); error ? reject(error) : resolve(value); };
+    const stop = error => {
+      if (termination || settled) return;
+      failure ??= error;
+      failure.details = { ...failure.details, elapsed_ms: Math.round(performance.now() - started), effect: "unknown" };
+      termination = terminateCommandTree(child).catch(cleanup => {
+        if (cleanup.code === "ESRCH") return;
+        failure.details.cleanup_error = { code: cleanup.code, message: cleanup.message };
+        failure.details.cleanup_unconfirmed = true;
+        child.kill("SIGKILL");
+      });
+      cleanupTimer ??= setTimeout(() => {
+        failure.details.cleanup_unconfirmed = true;
+        child.stdin.destroy(); child.stdout.destroy(); child.stderr.destroy(); child.unref();
+        finish(failure);
+      }, 500);
+    };
+    const timer = setTimeout(() => stop(Object.assign(new Error("Bounded CLI request timed out"), { code: timeoutCode })), timeoutMs);
+    child.stdout.setEncoding("utf8").on("data", chunk => { stdout += chunk; if (stdout.length > 1_048_576) stop(new Error("Native hook response exceeds protocol limit")); });
+    child.stderr.setEncoding("utf8").on("data", chunk => { stderr = (stderr + chunk).slice(-65_536); });
+    child.stdin.on("error", error => { failure ??= error; });
+    child.on("error", error => finish(failure ?? error));
+    child.on("close", code => {
+      if (failure) { void (termination ?? Promise.resolve()).then(() => finish(failure)); return; }
+      if (code !== 0) {
+        return finish(reportedFailure(stdout, stderr, "Native hook admission failed", "native_hook_failed"));
+      }
+      finish(null, stdout);
+    });
+    child.stdin.end(input);
+  });
+  return output;
+}
+
+export async function invokeNativeHook({ bin, args, payload, home, cwd, env, timeoutMs = 15_000 }) {
+  const output = await runBoundedCommand({ bin, args, input: `${JSON.stringify(payload)}\n`, cwd, env: { ...env, DD_FLOW_HOME: home }, timeoutMs });
+  let result;
+  try { result = JSON.parse(output); } catch { throw Object.assign(new Error("Invalid native hook JSON response"), { code: "native_hook_response_invalid" }); }
+  if (result?.ok === false && typeof result.error?.code === "string") throw Object.assign(new Error(result.error.message ?? "Native hook failed"), { code: result.error.code, details: result.error.details });
+  if (!result || typeof result !== "object" || Array.isArray(result) || result.ok === false) throw Object.assign(new Error("Native hook did not return a successful protocol object"), { code: "native_hook_response_invalid" });
+  return result;
+}

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

@@ -0,0 +1,36 @@
+/** 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, progressAt) {
+    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 = !gap && Number.isFinite(progressAt) ? Math.max(0, Math.min(this.timeoutMs, wall - progressAt)) : 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", "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"].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,71 @@
+import { spawn } from "node:child_process";
+import { reportedError } from "./operation-errors.mjs";
+
+function failure(message, code) {
+  return Object.assign(new Error(message), { code });
+}
+
+export function reportedFailure(stdout, stderr, fallback, fallbackCode = "flow_reconciliation_failed") {
+  for (const text of [stdout, stderr]) {
+    for (const line of [text.trim(), ...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);
+        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. */ }
+    }
+  }
+  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 };
+}
+
+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 = ""; let settled = false; let progressError = null;
+    const finish = (error, value) => { if (settled) return; settled = true; error ? reject(error) : resolve(value); };
+    const deliverProgress = (line) => {
+      let value; try { value = JSON.parse(line); } catch { return; }
+      if (typeof onProgress !== "function" || progressError) return;
+      try { const returned = onProgress(value); if (returned && typeof returned.then === "function") { Promise.resolve(returned).catch(() => {}); throw failure("commandJson onProgress must be synchronous", "progress_callback_async"); } }
+      catch (error) { progressError = error; child.kill("SIGKILL"); }
+    };
+    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);
+        deliverProgress(line);
+      }
+    });
+    child.once("error", (error) => finish(progressError ?? error));
+    if (input !== null) child.stdin.end(input);
+    child.on("close", (status) => {
+      if (pendingStderr) deliverProgress(pendingStderr);
+      if (progressError) return finish(progressError);
+      if (status !== 0) return finish(reportedFailure(stdout, stderr, `${executable} exited ${status}`));
+      try { const value = JSON.parse(stdout.trim()); if (value?.ok === false) { const error = value.error && typeof value.error === "object" ? value.error : value; if (typeof error.code === "string") return finish(reportedError(error, `${bin} returned an error envelope`)); } finish(null, value); }
+      catch (error) { finish(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") }] : []; });
+}