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

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

@@ -0,0 +1,251 @@
+import { spawn } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { reportedFailure } from "./process-json.mjs";
+import { errorRecord, reportedError } from "./operation-errors.mjs";
+import { writeJsonAtomic } from "./runner-events.mjs";
+
+/** Retain accepted native requests in the existing operation hook ledger. */
+export async function acceptNativeHookRequest(stateDir, binding, current = null) {
+  if (["operation_id", "daemon_id", "tool_call_id", "root_provider_session_id", "provider_session_id"].some(key => typeof binding[key] !== "string" || !binding[key])
+    || !Number.isSafeInteger(binding.turn_generation) || binding.turn_generation < 0
+    || !/^[a-f0-9]{64}$/.test(binding.command_sha256 ?? "")) throw Object.assign(new Error("Native hook has no current owned operation"), { code: "native_hook_unproven" });
+  const key = JSON.stringify([binding.provider_session_id, binding.tool_call_id, binding.event]);
+  const existing = current && [...current.requests.values()].find(value => JSON.stringify([value.binding.provider_session_id, value.binding.tool_call_id, value.binding.event]) === key)?.binding;
+  const same = value => {
+    if (value.command_sha256 !== binding.command_sha256 || value.native_cwd !== binding.native_cwd) throw Object.assign(new Error("Native tool identity was reused with changed hook input"), { code: "native_hook_identity_conflict" });
+    return value;
+  };
+  if (existing) return same(existing);
+  current && (current.accepting ??= new Map());
+  if (current?.accepting.has(key)) return same(await current.accepting.get(key));
+  const accepted = (async () => {
+  const directory = path.join(stateDir, "operations", createHash("sha256").update(binding.operation_id).digest("hex"));
+  const requested = JSON.parse(await readFile(path.join(directory, "requested.json"), "utf8"));
+  if (requested.operation_id !== binding.operation_id || requested.daemon_id !== binding.daemon_id || !["session.prompt", "session.create", "session.start"].includes(requested.operation)
+    || requested.operation === "session.prompt" && requested.session_id && requested.session_id !== binding.root_provider_session_id) throw Object.assign(new Error("Native hook operation does not match its retained owner"), { code: "native_hook_unproven" });
+  const receipt = { ...binding, schema_id: "dd-flow/hook-request@1", request_id: randomUUID() };
+  await writeJsonAtomic(path.join(directory, "hooks", `${receipt.request_id}.json`), receipt);
+  return receipt;
+  })();
+  current?.accepting.set(key, accepted);
+  try { return await accepted; } finally { current?.accepting.delete(key); }
+}
+
+export async function writeNativeHookFailure(stateDir, binding, error, budget) {
+  if (!binding?.request_id || !/^[A-Za-z0-9-]{1,128}$/.test(binding.request_id)) return;
+  await budget.run(() => writeJsonAtomic(path.join(stateDir, "hook-failures", `${binding.request_id}.json`), {
+    ...errorRecord(error), request_id: binding.request_id, observed_at: new Date().toISOString(), native_hook_binding: binding,
+  }, () => budget.remaining("failure_receipt_commit")), "failure_receipt");
+}
+
+/** Read only requests accepted for this exact live operation, never scan a mailbox. */
+export async function readNativeHookFailures(stateDir, requests, current, reject) {
+  for (const [id, accepted] of requests) {
+    if (accepted.current !== current) continue;
+    let value;
+    try { value = JSON.parse(await readFile(path.join(stateDir, "hook-failures", `${id}.json`), "utf8")); }
+    catch (error) { if (error.code === "ENOENT") continue; value = { code: "native_hook_receipt_invalid", message: error.message }; }
+    if (value.request_id !== id || !value.native_hook_binding || JSON.stringify(value.native_hook_binding) !== JSON.stringify(accepted.binding) || typeof value.code !== "string" || typeof value.message !== "string") {
+      if (!accepted.diagnostic) {
+        accepted.diagnostic = { code: "native_hook_receipt_invalid", message: "Accepted hook request has an unreadable or unbound failure receipt", request_id: id, operation_id: accepted.binding.operation_id, effect: "unknown", receipt_bound: false };
+        process.stderr.write(`${JSON.stringify({ native_hook_diagnostic: accepted.diagnostic })}\n`);
+      }
+      continue;
+    }
+    requests.delete(id);
+    const error = reportedError(value, "Native hook failed");
+    error.details = { ...error.details, native_hook_binding: accepted.binding };
+    reject(error);
+  }
+}
+
+/** The caller supplies its qualified native limit; phases share that deadline. */
+export function hookBudget(timeoutMs = 25_000, deadlineAt = process.env.DD_FLOW_HOOK_DEADLINE_AT ? Number(process.env.DD_FLOW_HOOK_DEADLINE_AT) : null) {
+  if (deadlineAt !== null && (!Number.isSafeInteger(deadlineAt) || deadlineAt < 0)) throw Object.assign(new Error("Invalid native hook deadline"), { code: "hook_deadline_invalid", details: { effect: "unknown" } });
+  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.floor(Math.min(maximum, value)));
+  };
+  return { deadlineAt: Math.floor(Date.now() + duration), remaining, async run(action, phase) {
+    const timeoutMs = remaining(phase);
+    let timer;
+    try { return await Promise.race([Promise.resolve().then(() => { remaining(phase); return 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, nodeBin = process.execPath, input = null, cwd, env = {}, timeoutMs = 15_000, timeoutCode = "native_hook_timeout", inheritDeadline = true, cleanupWithinBudget = false, maintenanceProgress = null, signal }) {
+  if (signal?.aborted) throw Object.assign(new Error("Bounded CLI request cancelled before launch"), { code: "process_maintenance_cancelled", details: { effect: "no_effect" } });
+  const inherited = inheritDeadline ? env.DD_FLOW_HOOK_DEADLINE_AT ?? process.env.DD_FLOW_HOOK_DEADLINE_AT : undefined;
+  if (inherited !== undefined) {
+    const deadline = Number(inherited);
+    if (!Number.isSafeInteger(deadline) || deadline < 0) throw Object.assign(new Error("Invalid native hook deadline"), { code: "hook_deadline_invalid", details: { effect: "no_effect" } });
+    timeoutMs = Math.min(timeoutMs, deadline - Date.now());
+  }
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) throw Object.assign(new Error("Native hook budget exhausted before subprocess launch"), { code: timeoutCode, details: { phase: "subprocess", effect: "no_effect" } });
+  if (maintenanceProgress && (!Number.isFinite(maintenanceProgress.inactivityMs) || maintenanceProgress.inactivityMs <= 0
+    || maintenanceProgress.startupMs !== undefined && (!Number.isFinite(maintenanceProgress.startupMs) || maintenanceProgress.startupMs <= 0)
+    || typeof maintenanceProgress.action !== "string" || !(maintenanceProgress.processId === null || typeof maintenanceProgress.processId === "string")))
+    throw Object.assign(new Error("Invalid maintenance progress budget"), { code: "process_maintenance_timeout", details: { effect: "no_effect", native_dispatch_started: false } });
+  const started = performance.now();
+  // Transport/physical cleanup has its own small tail inside the outer limit.
+  const cleanupMs = Math.min(500, timeoutMs / 5);
+  const commandMs = cleanupWithinBudget ? Math.max(1, timeoutMs - cleanupMs) : timeoutMs;
+  const deadlineAt = Math.floor(Date.now() + Math.max(0, commandMs - Math.min(250, commandMs / 10)));
+  const script = /\.[cm]?js$/.test(bin);
+  const output = await new Promise((resolve, reject) => {
+    const child = spawn(script ? nodeBin : bin, [...(script ? [bin] : []), ...args], {
+      cwd, env: { ...process.env, ...env, DD_FLOW_HOOK_DEADLINE_AT: String(deadlineAt) }, detached: process.platform !== "win32", stdio: ["pipe", "pipe", "pipe"]
+    });
+    let stdout = "", stderr = "", failure, cleanupTimer, settled = false, termination;
+    let timer, phaseBuffer = "", lastProgress = started;
+    const progressPhases = new Set();
+    let importsReady = maintenanceProgress?.startupMs === undefined;
+    const silenceMs = () => importsReady ? maintenanceProgress?.inactivityMs : maintenanceProgress.startupMs;
+    const commandDeadline = started + commandMs;
+    const finish = (error, value) => {
+      if (settled) return;
+      settled = true; clearTimeout(timer); clearTimeout(cleanupTimer); signal?.removeEventListener("abort", abort);
+      if (error) {
+        const diagnostics = hookDiagnostics(stderr);
+        if (diagnostics.length) error.details = { ...error.details, hook_diagnostics: diagnostics };
+        reject(error);
+      } else resolve(value);
+    };
+    const stop = error => {
+      if (termination || settled) return;
+      failure ??= error;
+      clearTimeout(timer);
+      failure.details = { ...failure.details, failure_at: new Date().toISOString(), elapsed_ms: Math.round(performance.now() - started), effect: "unknown", subprocess_pid: child.pid ?? null };
+      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);
+      }, cleanupWithinBudget ? cleanupMs : 500);
+    };
+    // A useful, request-bound phase advances the silence window, not ownership
+    // authority. The child storage deadline and parent uncertainty horizon stay
+    // fixed; repeated phases, logging and polling cannot keep a writer alive.
+    const arm = () => {
+      clearTimeout(timer);
+      const now = performance.now();
+      const remaining = Math.min(commandDeadline - now, maintenanceProgress ? lastProgress + silenceMs() - now : Infinity);
+      if (remaining <= 0) { stop(Object.assign(new Error("Bounded CLI request timed out"), { code: timeoutCode,
+        details: maintenanceProgress ? { phase: importsReady ? "storage" : "startup", inactivity_ms: silenceMs(),
+          ownership_horizon_ms: commandMs } : {} })); return; }
+      timer = setTimeout(arm, Math.ceil(remaining));
+    };
+    arm();
+    const abort = () => stop(Object.assign(new Error("Bounded CLI request cancelled"), { code: "process_maintenance_cancelled" }));
+    signal?.addEventListener("abort", abort, { once: true });
+    if (signal?.aborted) abort();
+    child.stdout.setEncoding("utf8").on("data", chunk => { stdout += chunk; if (stdout.length > 1_048_576) stop(new Error("Native hook response exceeds protocol limit")); });
+    // Match the existing response bound: a legal bounded error tree may exceed
+    // 64KiB when pretty-printed, plus maintenance phases preceding the receipt.
+    child.stderr.setEncoding("utf8").on("data", chunk => {
+      stderr = (stderr + chunk).slice(-1_048_576);
+      if (!maintenanceProgress || termination || settled) return;
+      phaseBuffer += chunk;
+      const lines = phaseBuffer.split("\n"); phaseBuffer = lines.pop().slice(-16_384);
+      for (const line of lines) {
+        if (line.length > 16_384) continue;
+        let phase; try { phase = JSON.parse(line); } catch { continue; }
+        if (phase?.kind !== "process_maintenance_phase" || phase.action !== maintenanceProgress.action
+          || (phase.process_id ?? null) !== maintenanceProgress.processId || phase.native_dispatch_started !== false
+          || !["request", "imports_ready", "store_open", "store_validation", "lookup", "writer_reservation", "writer_reserved", "write", "commit", "committed", "ack"].includes(phase.phase)
+          || phase.store_kind !== undefined && !["run", "resource"].includes(phase.store_kind)) continue;
+        const key = `${phase.store_kind ?? ""}:${phase.phase}`;
+        if (progressPhases.has(key)) continue;
+        // Delayed observation cannot revive an already-expired silence window.
+        const now = performance.now();
+        if (now >= commandDeadline || now - lastProgress >= silenceMs()) { arm(); return; }
+        // Cold imports are not a stalled storage operation. Readiness is an
+        // actual boundary, never a timer heartbeat; the ownership horizon stays fixed.
+        if (["imports_ready", "store_open"].includes(phase.phase)) importsReady = true;
+        progressPhases.add(key); lastProgress = now; arm();
+      }
+    });
+    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;
+}
+
+/** Only our structured phase allowlist crosses a timeout, never raw stderr/env. */
+function hookDiagnostics(stderr) {
+  return stderr.split("\n").flatMap(line => {
+    try {
+      const value = JSON.parse(line);
+      if (!["native_hook_phase", "process_maintenance_phase"].includes(value?.kind)) return [];
+      const phase = typeof value.phase === "string" && /^[a-z_]{1,48}$/.test(value.phase) ? value.phase : null;
+      if (!phase) return [];
+      return [{ phase, ...Object.fromEntries(["elapsed_ms", "remaining_ms", "sqlite_extended_code"].filter(key => Number.isFinite(value[key])).map(key => [key, value[key]])), ...(value.kind === "process_maintenance_phase" ? { ...Object.fromEntries(["action", "process_id", "operation_id", "lease_expires_at", "store_kind", "maintenance_effect", "attempt_kind", "role"].filter(key => typeof value[key] === "string" && /^[A-Za-z0-9:._-]{1,128}$/.test(value[key])).map(key => [key, value[key]])), ...(typeof value.native_dispatch_started === "boolean" ? { native_dispatch_started: value.native_dispatch_started } : {}) } : {}) }];
+    } catch { return []; }
+  }).slice(-16);
+}
+
+export async function invokeNativeHook({ bin, args, nodeBin, payload, home, cwd, env, timeoutMs = 25_000 }) {
+  const output = await runBoundedCommand({ bin, args, nodeBin, input: `${JSON.stringify(payload)}\n`, cwd, env: { ...env, DD_FLOW_HOME: home }, timeoutMs, cleanupWithinBudget: true });
+  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/native-request-proof.d.mts

@@ -0,0 +1,2 @@
+export function nativeCommandFingerprint(input: { executable: string; args: string[]; cwd: string; env: Record<string, string | undefined>; operationId: string }): string;
+export function prepareDaemonRequest<T extends { id: string; operation: string; params?: Record<string, unknown> }>(request: T): T & { invocation_sha256?: string };

package/dist/harness-runtime/lib/native-request-proof.mjs

@@ -0,0 +1,65 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { randomUUID } from 'node:crypto';
+import { hashJson } from './runner-events.mjs';
+
+const environmentKeys = ['HOME', 'CODEX_HOME', 'DD_FLOW_CONFIG_HOME', 'DD_FLOW_RESOURCE_HOME', 'DD_FLOW_HOME', 'DD_FLOW_BIN', 'DD_FLOW_ENGINE_HOME'];
+const fail = reason => { throw Object.assign(new Error('Native request proof does not match its prepared command'), {
+  code: 'native_request_proof_conflict', details: { reason, effect: 'no_effect' }
+}); };
+
+/** Independent transport identity: prepared by the caller before launching
+ * the adapter, and recomputed by the adapter's shared request builder. */
+export function nativeCommandFingerprint({ executable, args, cwd, env, operationId }) {
+  return hashJson({ executable, args, cwd, operation_id: operationId,
+    environment: Object.fromEntries([...environmentKeys, ...(env.PLAYWRIGHT_BROWSERS_PATH === undefined ? [] : ['PLAYWRIGHT_BROWSERS_PATH'])].map(key => [key, env[key] ?? null])) });
+}
+
+/** Called after the adapter's own argument preparation but before its RPC or
+ * daemon-start action. No provider response can supply this fingerprint. */
+export function prepareDaemonRequest(request) {
+  const file = process.env.DD_FLOW_NATIVE_REQUEST_PROOF_FILE;
+  const expected = process.env.DD_FLOW_NATIVE_COMMAND_SHA256;
+  const operation = process.env.DD_FLOW_NATIVE_REQUEST_OPERATION;
+  if (file === undefined && expected === undefined) return request;
+  // Control helpers may inspect status before their owned stop RPC. Status
+  // cannot consume the productive/control request's independently bound proof.
+  if (operation && request.operation !== operation) {
+    if (request.operation === 'daemon.status' && operation === 'daemon.stop') return request;
+    fail('operation_changed');
+  }
+  const ownerText = process.env.DD_FLOW_NATIVE_REQUEST_PROOF_OWNER;
+  // Never forward caller proof authority into the daemon/provider process.
+  delete process.env.DD_FLOW_NATIVE_REQUEST_PROOF_FILE;
+  delete process.env.DD_FLOW_NATIVE_COMMAND_SHA256;
+  delete process.env.DD_FLOW_NATIVE_REQUEST_OPERATION;
+  delete process.env.DD_FLOW_NATIVE_REQUEST_PROOF_OWNER;
+  if (!file || !path.isAbsolute(file) || !/^[a-f0-9]{64}$/.test(expected ?? '')
+    || typeof request.id !== 'string' || !request.id || typeof request.operation !== 'string' || request.operation !== operation) fail('invalid_owner');
+  const command = nativeCommandFingerprint({ executable: process.argv[1], args: process.argv.slice(2),
+    cwd: process.cwd(), env: process.env, operationId: request.id });
+  if (command !== expected || fs.realpathSync(path.dirname(file)) !== path.dirname(file)) fail('command_changed');
+  let owner;
+  try { owner = JSON.parse(ownerText ?? 'null'); } catch { fail('invalid_parent_owner'); }
+  const parent = fs.lstatSync(path.dirname(file));
+  if (!parent.isDirectory() || parent.dev !== owner?.dev || parent.ino !== owner?.ino) fail('proof_parent_changed');
+  const proof = { schema_id: 'dd-flow/native-request-proof@1', operation_id: request.id, operation: request.operation,
+    command_sha256: command, params_sha256: hashJson({ operation: request.operation, params: request.params ?? {} }),
+    session_id: request.params?.sessionId ?? null };
+  const temporary = `${file}.${randomUUID()}.tmp`;
+  const fd = fs.openSync(temporary, 'wx', 0o600);
+  try {
+    fs.writeFileSync(fd, JSON.stringify(proof)); fs.fsyncSync(fd);
+    const current = fs.lstatSync(path.dirname(file));
+    if (parent.dev !== current.dev || parent.ino !== current.ino || !current.isDirectory()) fail('proof_parent_changed');
+    try { fs.linkSync(temporary, file); }
+    catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      const stat = fs.lstatSync(file);
+      if (!stat.isFile() || stat.nlink !== 1 || stat.size > 16 * 1024
+        || hashJson(JSON.parse(fs.readFileSync(file, 'utf8'))) !== hashJson(proof)) fail('retained_request_changed');
+    }
+  } finally { fs.closeSync(fd); fs.unlinkSync(temporary); }
+  return { ...request, invocation_sha256: command };
+}

package/dist/harness-runtime/lib/native-streams.mjs

@@ -0,0 +1,45 @@
+// Async iteration backpressures the native pipe while its existing evidence
+// sink drains. Bound one JSON reply, never lifetime diagnostics.
+export const MAX_NATIVE_LINE_BYTES = 8 * 1024 * 1024;
+export async function readNativeLines(stream, onLine, onError) {
+  let buffer = "";
+  stream.setEncoding("utf8");
+  try {
+    for await (const chunk of stream.iterator({ destroyOnReturn: false })) {
+      buffer += chunk;
+      let at;
+      while ((at = buffer.indexOf("\n")) >= 0) {
+        const line = buffer.slice(0, at); buffer = buffer.slice(at + 1);
+        assertLine(line);
+        if (line.trim()) await onLine(line);
+      }
+      assertLine(buffer);
+    }
+    if (buffer.trim()) { assertLine(buffer); await onLine(buffer); }
+  } catch (cause) { stream.pause(); await observationFailure(cause, onError); }
+}
+export function assertNativeLine(line, phase = "reply") {
+  if (Buffer.byteLength(line) > MAX_NATIVE_LINE_BYTES) throw Object.assign(new Error(`Native JSON ${phase} exceeds the bounded capture limit`), { code: phase === "request" ? "native_request_limit" : "operation_observation_lost", details: { reason: `native_${phase}_limit`, limit_bytes: MAX_NATIVE_LINE_BYTES, ...(phase === "request" ? { effect: "no_effect" } : { native_outcome: "unknown" }) } });
+}
+const assertLine = assertNativeLine;
+export function admitNativeRequestBuffer(buffer, socket, schema) {
+  try { assertNativeLine(buffer, "request"); return true; }
+  catch (error) { socket.pause(); socket.end(`${JSON.stringify({ schema_id: schema, id: null, ok: false, error: { code: error.code, message: error.message, details: error.details } })}\n`, () => socket.destroy()); return false; }
+}
+export function retainNativeReplyBuffer(buffer, finish) {
+  try { assertNativeLine(buffer); return true; }
+  catch (error) { finish(error); return false; }
+}
+export async function streamNativeDiagnostics(stream, onChunk, onError) {
+  stream.setEncoding("utf8");
+  try { for await (const chunk of stream.iterator({ destroyOnReturn: false })) await onChunk(String(chunk)); }
+  catch (cause) { stream.pause(); await observationFailure(cause, onError); }
+}
+async function observationFailure(cause, onError) {
+  const error = nativeObservationError(cause);
+  try { await onError(error); }
+  catch (publication) { error.cleanup_error ??= { code: publication.code ?? null, message: publication.message }; }
+}
+export function nativeObservationError(cause, details = {}) {
+  return !cause.code || /^[A-Z_]+$/.test(cause.code) ? Object.assign(new Error("Native evidence reader failed", { cause }), { code: "operation_observation_lost", details: { native_outcome: "unknown", observation_error: { code: cause.code ?? null, message: cause.message }, ...details } }) : cause;
+}

package/dist/harness-runtime/lib/observation-clock.d.mts

@@ -0,0 +1,18 @@
+export const OBSERVATION_CLOCK_CONTRACT_VERSION: "operation-progress@1";
+export function validateObservationDuration(value: number, label?: string): number;
+export interface ObservationState {
+  policy: string; timeout_ms: number; started_at: number; cursor?: unknown;
+  observed_at: number | null; elapsed_ms: number; uncertainty_elapsed_ms: number;
+  gaps: number; uncertain?: boolean; observation_lost: boolean;
+}
+export class ObservationClock {
+  constructor(options: { timeoutMs: number; gapMs?: number; uncertaintyMs?: number;
+    wall?: () => number; monotonic?: () => number; onGap?: (value: Record<string, unknown>) => void;
+    saved?: ObservationState | null; snapshotIsLive?: boolean });
+  observationLost: boolean;
+  sample(progress?: unknown, progressAt?: number): boolean;
+  state(): ObservationState;
+}
+export function observedTimeout(callback: (clock: ObservationClock) => void, timeoutMs: number,
+  options?: { gapMs?: number; uncertaintyMs?: number; wall?: () => number; monotonic?: () => number;
+    onGap?: (value: Record<string, unknown>) => void; progress?: () => unknown; saved?: ObservationState | null }): ReturnType<typeof setInterval>;

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

@@ -0,0 +1,95 @@
+export const OBSERVATION_CLOCK_CONTRACT_VERSION = "operation-progress@1";
+export function validateObservationDuration(value, label = "observation duration") {
+  if (!Number.isSafeInteger(value) || value < 1 || value > 2_147_483_647)
+    throw new RangeError(`${label} must be integer milliseconds in 1..2147483647`);
+  return value;
+}
+
+/** Only observed monotonic time is silence. A clock gap is uncertainty, never
+ * progress or proof of provider failure. Durable snapshots retain that episode. */
+export class ObservationClock {
+  constructor({ timeoutMs, gapMs = 60_000, uncertaintyMs = 120_000, wall = Date.now,
+    monotonic = () => performance.now(), onGap = () => {}, saved = null, snapshotIsLive = false }) {
+    validateObservationDuration(timeoutMs); validateObservationDuration(gapMs, "gap duration");
+    validateObservationDuration(uncertaintyMs, "observation recovery duration");
+    Object.assign(this, { timeoutMs, gapMs, uncertaintyMs, wall, monotonic, onGap });
+    this.lastWall = wall(); this.lastMono = monotonic(); this.startedWall = this.lastWall;
+    this.elapsed = 0; this.progress = undefined; this.progressAt = null;
+    this.uncertain = false; this.uncertaintyElapsed = 0; this.gaps = 0; this.observationLost = false;
+    if (saved) {
+      if (saved.policy !== OBSERVATION_CLOCK_CONTRACT_VERSION || saved.timeout_ms !== timeoutMs
+        || !Number.isFinite(saved.started_at) || !Number.isSafeInteger(saved.gaps) || saved.gaps < 0
+        || saved.observed_at !== null && !Number.isFinite(saved.observed_at)
+        || typeof saved.observation_lost !== "boolean"
+        || saved.uncertain !== undefined && typeof saved.uncertain !== "boolean"
+        || !Number.isFinite(saved.elapsed_ms) || saved.elapsed_ms < 0
+        || !Number.isFinite(saved.uncertainty_elapsed_ms) || saved.uncertainty_elapsed_ms < 0)
+        throw new RangeError("invalid retained observation clock");
+      this.startedWall = saved.started_at; this.elapsed = saved.elapsed_ms;
+      this.progress = saved.cursor; this.progressAt = saved.observed_at;
+      // Durable reconstruction has an observation gap. Transferring a freshly
+      // observed producer clock is not a second restart of that same producer.
+      this.uncertain = snapshotIsLive ? saved.uncertain ?? true : true;
+      this.gaps = saved.gaps + (snapshotIsLive ? 0 : 1);
+      this.uncertaintyElapsed = saved.uncertainty_elapsed_ms;
+      this.observationLost = saved.observation_lost || this.gaps > 1 || this.uncertaintyElapsed >= uncertaintyMs;
+    }
+  }
+  sample(progress, progressAt) {
+    if (progress && typeof progress === "object" && Object.hasOwn(progress, "cursor")) {
+      progressAt = progress.observed_at; progress = progress.cursor;
+    }
+    const wall = this.wall(), mono = this.monotonic();
+    const delta = mono - this.lastMono, wallDelta = wall - this.lastWall;
+    const gap = !Number.isFinite(delta) || !Number.isFinite(wallDelta)
+      || delta > this.gapMs || wallDelta > this.gapMs || delta < 0 || wallDelta < 0;
+    if (gap) {
+      this.uncertain = true; this.gaps++;
+      this.onGap({ source: "observer_clock", classification: "observation_gap", confirmed_sleep: false,
+        started_at: Number.isFinite(this.lastWall) ? this.lastWall : null, observed_at: Number.isFinite(wall) ? wall : null,
+        wall_delta_ms: wallDelta, monotonic_delta_ms: delta });
+    } else {
+      this.elapsed += delta;
+      if (this.uncertain) this.uncertaintyElapsed += delta;
+    }
+    this.lastWall = wall; this.lastMono = mono;
+    const validCursor = typeof progress === "string" || typeof progress === "boolean"
+      || typeof progress === "number" && Number.isFinite(progress);
+    const changed = validCursor && progress !== this.progress;
+    const timestamped = progressAt !== undefined;
+    const validTime = !timestamped ? wall >= this.startedWall && (this.progressAt === null || wall >= this.progressAt)
+      : Number.isFinite(progressAt) && progressAt >= this.startedWall
+      && progressAt <= wall && (this.progressAt === null || progressAt >= this.progressAt);
+    if (changed && validTime && !this.observationLost) {
+      const eventAt = timestamped ? progressAt : wall;
+      // A delayed pre-gap event cannot establish that observation has recovered.
+      const recovers = !this.uncertain || eventAt >= wall - Math.max(0, gap ? 0 : delta);
+      this.progress = progress; this.progressAt = eventAt;
+      this.elapsed = Math.max(0, wall - eventAt);
+      if (recovers) { this.uncertain = false; this.gaps = 0; this.uncertaintyElapsed = 0; }
+    }
+    if (changed && timestamped && Number.isFinite(progressAt) && !validTime && progressAt > wall) {
+      if (!this.uncertain) this.onGap({ source: "observer_clock", classification: "clock_skew",
+        confirmed_sleep: false, observed_at: wall, signal_at: progressAt });
+      this.uncertain = true;
+    }
+    if (this.uncertain && (this.gaps > 1 || this.uncertaintyElapsed >= this.uncertaintyMs)) this.observationLost = true;
+    return this.observationLost || !this.uncertain && this.elapsed >= this.timeoutMs;
+  }
+  state() {
+    return { policy: OBSERVATION_CLOCK_CONTRACT_VERSION, timeout_ms: this.timeoutMs,
+      started_at: this.startedWall, cursor: this.progress, observed_at: this.progressAt,
+      elapsed_ms: this.elapsed, uncertainty_elapsed_ms: this.uncertaintyElapsed,
+      gaps: this.gaps, uncertain: this.uncertain, observation_lost: this.observationLost };
+  }
+}
+
+/** Node timer handle, compatible with existing clearTimeout cleanup. */
+export function observedTimeout(callback, timeoutMs, options = {}) {
+  const clock = new ObservationClock({ timeoutMs, ...options });
+  const timer = setInterval(() => {
+    const snapshot = options.progress?.();
+    if (clock.sample(snapshot)) { clearInterval(timer); callback(clock); }
+  }, Math.max(1, Math.min(1_000, timeoutMs / 4)));
+  return timer;
+}

package/dist/harness-runtime/lib/opencode-plugin.mjs

@@ -0,0 +1,85 @@
+import path from "node:path";
+import { managedFlowEnv } from './managed-flow-env.mjs';
+import * as Plugin from "../vendor/opencode-plugin.mjs";
+import { hookBudget, invokeNativeHook, writeNativeHookFailure } from "./native-hook-command.mjs";
+import { callDaemon } from "./dd-opencode-daemon.mjs";
+import { errorRecord } from "./operation-errors.mjs";
+
+/** Launch-bound server plugin; never uses a process-global 'last Session'. */
+export function makeOpenCodePlugin(binding, invoke = invokeNativeHook, resolve = callDaemon) {
+  return Plugin.define({ id: binding.ddFlowBin ? "dd-flow" : "dd-flow-security", async setup(ctx) {
+    const participating = new Map();
+    const key = event => JSON.stringify([binding.daemonId, event.sessionID, event.messageID, event.id]);
+    const envelope = async (phase, event, budget, outcome) => {
+      const input = event.input;
+      if (!input || typeof input !== "object" || typeof input.command !== "string") throw new Error("OpenCode shell input is unavailable");
+      const identity = await budget.run(() => resolve(binding.stateDir, "hook.resolve", { sessionId: event.sessionID,
+        payload: { phase, message_id: event.messageID, tool_call_id: event.id, input } }, budget.remaining("identity")), "identity");
+      const info = identity?.nativeSession;
+      if (!identity?.nativeHookBinding || info?.id !== event.sessionID || !info.directory) throw Object.assign(new Error("OpenCode Session identity is unavailable"), { code: "native_hook_unproven" });
+      const cwd = path.resolve(info.directory, input.workdir ?? ".");
+      return { schema_id: "dd-flow/opencode-tool-event@1", native_protocol: 2,
+        native_hook_binding: identity.nativeHookBinding,
+        event_id: [binding.daemonId, event.sessionID, event.messageID, event.id].join(":"), phase,
+        daemon_id: binding.daemonId, server_version: binding.version, plugin_sha256: process.env.DD_OPENCODE_PLUGIN_SHA256,
+        session: { provider_session_id: info.id, parent_provider_session_id: info.parentID ?? null,
+          agent_id: event.agent, directory: cwd, project_id: info.projectID },
+        message_id: event.messageID, tool_call_id: event.id, tool: "shell", native_tool: event.tool,
+        profile: { provider: info.model?.providerID, model: info.model?.id, variant: info.model?.variant ?? "default", agent: event.agent },
+        input: { ...input, workdir: cwd }, ...(outcome ? { outcome } : {}) };
+    };
+    const deliver = async (payload, budget) => {
+      const identity = { nativeHookBinding: payload.native_hook_binding };
+      try {
+        const result = await invoke({ bin: binding.ddFlowBin, nodeBin: binding.nodeBin,
+          args: ["opencode", "event", "handle", "--project-root", binding.projectRoot, "--json"],
+          payload: { ...payload, native_hook_binding: identity.nativeHookBinding }, home: binding.ddFlowHome, timeoutMs: budget.remaining("admission") });
+        await budget.run(() => resolve(binding.stateDir, "hook.verify", { binding: identity.nativeHookBinding }, budget.remaining("generation")), "generation");
+        if (result?.permissionDecision === "deny" || result?.hookSpecificOutput?.permissionDecision === "deny") throw Object.assign(new Error("dd-flow denied native shell admission"), { code: "native_hook_rejected" });
+        return result;
+      } catch (error) {
+        error.details = { ...error.details, native_hook_binding: identity.nativeHookBinding, ...(payload.phase === "after" ? { effect: "unknown", tool_outcome: payload.outcome } : {}) };
+        try { await writeNativeHookFailure(binding.stateDir, identity.nativeHookBinding, error, budget); await resolve(binding.stateDir, "hook.failed", {}, budget.remaining("failure_notification")); }
+        catch (storage) {
+          error.details.receipt_error = { code: storage.code ?? "hook_receipt_write_failed", message: storage.message };
+          try { await resolve(binding.stateDir, "hook.failed", { binding: identity.nativeHookBinding, failure: errorRecord(error) }, budget.remaining("failure_notification")); }
+          catch (notify) { error.details.receipt_error.notification_error = notify.code ?? "hook_notification_failed"; }
+        }
+        throw error;
+      }
+    };
+    await ctx.shell.hook("create.before", event => {
+      Object.assign(event.env, managedFlowEnv(binding));
+      delete event.env.OPENCODE_PASSWORD; delete event.env.OPENCODE_SERVER_PASSWORD;
+    });
+    await ctx.tool.hook("execute.before", async event => {
+      if (event.tool !== "shell") return;
+      if (event.input.timeout === undefined) event.input.timeout = 0;
+      if (!binding.ddFlowBin) return;
+      const budget = hookBudget(), payload = await envelope("before", event, budget);
+      event.input = { ...event.input, workdir: payload.session.directory };
+      const result = await deliver({ ...payload, input: event.input }, budget);
+      if (result?.observed) {
+        participating.set(key(event), payload);
+        await ctx.storage.set(key(event), JSON.parse(JSON.stringify(payload)));
+        // The common observer, not OpenCode's fixed 120-second cutoff, owns
+        // flow CLI inactivity. No lifecycle process is detached here.
+        event.input = { ...event.input, ...(result.hookSpecificOutput?.updatedInput ?? {}), timeout: 0, background: false };
+      } else if (event.input.timeout === undefined) event.input.timeout = 0;
+    });
+    await ctx.tool.hook("execute.after", async event => {
+      if (event.tool !== "shell") return;
+      const budget = hookBudget(), original = participating.get(key(event)) ?? await ctx.storage.get(key(event));
+      if (!original) return; // Ordinary shell tools do not create lifecycle receipts.
+      const output = event.result?.output;
+      const success = event.status === "completed" && output?.status !== "running" && output?.exit === 0 && !output?.timeout && !output?.signal;
+      const outcome = { status: success ? "completed" : output?.status === "running" ? "running" : "failed",
+        exit_code: output?.exit ?? null, signal: output?.signal ?? null, shell_id: output?.shellID ?? null };
+      const payload = await envelope("after", event, budget, outcome);
+      await deliver({ ...payload, ...(original ? { event_id: original.event_id } : {}) }, budget);
+      participating.delete(key(event));
+      await ctx.storage.remove(key(event));
+    });
+    return () => participating.clear();
+  } });
+}

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.d.mts

@@ -0,0 +1,16 @@
+export const OPERATION_ERROR_CONTRACT_VERSION: "operation-errors@2";
+export interface ErrorRecord {
+  code: string;
+  message: string;
+  retryable?: boolean;
+  exitCode?: number;
+  details?: unknown;
+  cause?: ErrorRecord;
+  cleanup_error?: ErrorRecord;
+}
+export function errorRecord(error: unknown, depth?: number): ErrorRecord;
+export function redactDiagnostic(value: string): string;
+export function diagnosticJson(value: unknown): string;
+export function isObservationLoss(error: unknown): boolean;
+export function isProvenShellCorrection(error: unknown): boolean;
+export function reportedError(value: Record<string, unknown>, fallback: string): Error & ErrorRecord;