@deksden-com/dd-flow-cli 0.9.0-beta.9 → 0.9.0-beta.90

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,34 @@
+import { spawn } from "node:child_process";
+
+/** Preserve the native hook protocol across the CLI process boundary. */
+export async function invokeNativeHook({ bin, args, payload, home, timeoutMs = 15_000 }) {
+  const script = /\.[cm]?js$/.test(bin);
+  const output = await new Promise((resolve, reject) => {
+    const child = spawn(script ? process.execPath : bin, [...(script ? [bin] : []), ...args], {
+      env: { ...process.env, DD_FLOW_HOME: home }, stdio: ["pipe", "pipe", "pipe"]
+    });
+    let stdout = "", stderr = "", failure;
+    const stop = error => { failure ??= error; child.kill("SIGKILL"); };
+    const timer = setTimeout(() => stop(Object.assign(new Error("Native hook admission timed out"), { code: "native_hook_timeout" })), 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 => { clearTimeout(timer); reject(error); });
+    child.on("close", code => {
+      clearTimeout(timer);
+      if (failure) return reject(failure);
+      if (code !== 0) {
+        let record;
+        try { record = JSON.parse(stderr.trim()).error; } catch { /* Non-JSON stderr remains diagnostic evidence. */ }
+        return reject(Object.assign(new Error(record?.message ?? (stderr.trim() || "Native hook admission failed")), { code: record?.code ?? "native_hook_failed", details: record?.details }));
+      }
+      resolve(stdout);
+    });
+    child.stdin.end(`${JSON.stringify(payload)}\n`);
+  });
+  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,70 @@
+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(), ...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 = ""; 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") }] : []; });
+}

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));
+  }
+}

package/dist/harness-runtime/lib/tool-observations.d.mts

@@ -0,0 +1,17 @@
+export interface ToolEvent {
+  session?: { harness_id: string; session_id: string };
+  call_id?: string;
+  status?: string;
+  name?: string;
+  reason?: string;
+  [key: string]: unknown;
+}
+export class ToolObservations {
+  calls: Map<string, ToolEvent>;
+  gaps: Set<string>;
+  add(event: ToolEvent | null): void;
+  summary(sessionId?: string, cursor?: Set<string>): { total: number; failures: number; pending: number; by_tool: Record<string, number>; completeness: string; sessions: Array<{ session: { harness_id: string; session_id: string }; total: number; failures: number; pending: number; by_tool: Record<string, number> }>; reasons: string[] };
+  cursor(): Set<string>;
+}
+export function codexToolObservation(record: Record<string, unknown>, sessionId: string): ToolEvent | null;
+export function replayToolJournal(file: string, options: { harness: string; rootSessionId: string; adapterSessionId?: string }, reducer?: ToolObservations): ToolObservations;