@deksden-com/dd-flow-cli 0.9.0-beta.21 → 0.9.0-beta.23

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,24 @@
+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 = [];
+  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 };
+    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 } });
+    for (const id of state.sessions) if (!cancelled.has(id)) {
+      cancelled.add(id);
+      try { await cancel(id); } catch (error) { errors.push({ phase: "cancel", session_id: id, ...errorRecord(error) }); }
+    }
+    await new Promise(resolve => setTimeout(resolve, 50));
+  }
+}

package/dist/services/execution-policy.js

@@ -0,0 +1,61 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { harnessKey } from "./harness-config.js";
+/** Reads one complete profile.  A policy selects profiles; it never field-merges them. */
+export function loadAgentProfile(ddFlowHome, id) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(id))
+        throw new AppError("agent_profile_invalid", "Agent profile id is invalid", 2, { id });
+    const file = path.join(ddFlowHome, "agent-profiles", `${id}.json`);
+    let value;
+    try {
+        value = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch (cause) {
+        throw new AppError("agent_profile_missing", "Agent profile is unavailable", 1, { id, file, cause: String(cause) });
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new AppError("agent_profile_invalid", "Agent profile must be an object", 2, { id, file });
+    const profile = value;
+    if (profile.schema_id !== "dd-flow/agent-profile@1" || profile.id !== id
+        || !["codex", "zcode", "agy", "opencode", "grok", "droid"].includes(String(profile.harness))
+        || !nonempty(profile.provider) || !nonempty(profile.model) || !nonempty(profile.reasoning) || !nonempty(profile.mode)
+        || (profile.permission !== "allow" && profile.permission !== "deny")) {
+        throw new AppError("agent_profile_invalid", "Agent profile does not match dd-flow/agent-profile@1", 2, { id, file });
+    }
+    return profile;
+}
+/** Resolves a frozen policy with explicit topology.  Same profiles do not turn external work into native work. */
+export function resolveExecutionPolicy(input) {
+    const stage = input.stage ? input.policy.stage_overrides?.[input.stage] : undefined;
+    const coordinatorId = input.work?.agent_profile_id ?? stage?.agent_profile_id ?? input.policy.agent_profile_id;
+    if (!coordinatorId)
+        throw new AppError("execution_profile_missing", "Execution policy needs agent_profile_id before external dispatch", 1, { stage: input.stage ?? null });
+    const coordinator = loadAgentProfile(input.ddFlowHome, coordinatorId);
+    const delegation = input.work?.delegation ?? stage?.delegation ?? input.policy.delegation ?? { mode: "native" };
+    validateDelegation(delegation);
+    const worker = loadAgentProfile(input.ddFlowHome, delegation.agent_profile_id ?? coordinator.id);
+    if (delegation.mode === "native" && harnessKey(worker.harness) !== harnessKey(coordinator.harness)) {
+        throw new AppError("native_harness_mismatch", "Native delegation cannot change harness", 2, { coordinator_harness: coordinator.harness, worker_harness: worker.harness });
+    }
+    const resolved = {
+        coordinator,
+        worker,
+        delegation: { mode: delegation.mode, max_parallel: delegation.mode === "external" ? delegation.max_parallel ?? 1 : null }
+    };
+    return { ...resolved, profile_hash: digest(resolved) };
+}
+export function runtimeHarness(profile) { return harnessKey(profile.harness); }
+function validateDelegation(value) {
+    if (value.mode !== "native" && value.mode !== "external")
+        throw new AppError("execution_profile_invalid", "Delegation mode must be native or external", 2);
+    if (value.agent_profile_id !== undefined && !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(value.agent_profile_id))
+        throw new AppError("execution_profile_invalid", "Delegation profile id is invalid", 2);
+    if (value.max_parallel !== undefined && (!Number.isInteger(value.max_parallel) || value.max_parallel < 1))
+        throw new AppError("execution_profile_invalid", "External max_parallel must be a positive integer", 2);
+    if (value.mode === "native" && value.max_parallel !== undefined)
+        throw new AppError("execution_profile_invalid", "Native delegation does not accept max_parallel", 2);
+}
+function nonempty(value) { return typeof value === "string" && Boolean(value.trim()); }
+function digest(value) { return crypto.createHash("sha256").update(JSON.stringify(value)).digest("hex"); }

package/dist/services/external-work-launch.js

@@ -0,0 +1,76 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { ensureWorkLaunchStorage } from "../storage/database.js";
+import { AppError } from "../shared/errors.js";
+import { adapterSessionId, runHarnessAdapter } from "./harness-adapter.js";
+import { harnessRuntimeArguments, resolveHarnessCommand } from "./harness-config.js";
+import { resolveExecutionPolicy, runtimeHarness } from "./execution-policy.js";
+import { assertRunMutationAllowed } from "./run-recovery.js";
+import { workStartCommand } from "./work-registry.js";
+/**
+ * Creates an external provider root for one already-created Work.  The launch
+ * is not a Work claim: only the worker's trusted `work start` hook binds it.
+ */
+export async function launchExternalWork(context, input) {
+    ensureWorkLaunchStorage(context.db);
+    const work = context.db.get("SELECT work_id, project_id, run_id, status, payload_json FROM works WHERE work_id = ?", [input.workId]);
+    if (!work)
+        throw new AppError("not_found", "Work was not found", 1, { work_id: input.workId });
+    if (work.status !== "created")
+        throw new AppError("invalid_work_state", "Only created Work can be launched externally", 2, { work_id: work.work_id, status: work.status });
+    const run = context.db.get("SELECT run_root, workspace_root, index_json FROM runs WHERE project_id = ? AND id = ?", [work.project_id, work.run_id]);
+    if (!run?.run_root)
+        throw new AppError("runtime_missing", "Work has no materialized RUN root", 1, { work_id: work.work_id });
+    const existing = context.db.get("SELECT operation_id, status, provider_session_id, profile_hash, journal_path FROM work_launches WHERE work_id = ?", [work.work_id]);
+    if (existing)
+        return { ok: true, work_id: work.work_id, operation_id: existing.operation_id, status: existing.status, provider_session_id: existing.provider_session_id, profile_hash: existing.profile_hash, journal_path: existing.journal_path, idempotent: true };
+    const generation = assertRunMutationAllowed(context, work.project_id, work.run_id);
+    const snapshot = JSON.parse(run.index_json);
+    const override = workOverride(work.payload_json);
+    const resolved = resolveExecutionPolicy({ ddFlowHome: context.ddFlowHome, policy: snapshot.execution_profile?.settings?.execution ?? {}, ...(input.stage ? { stage: input.stage } : {}), ...(override ? { work: override } : {}) });
+    if (resolved.delegation.mode !== "external")
+        throw new AppError("external_launch_not_selected", "This Work's frozen policy selects native delegation", 2, { work_id: work.work_id });
+    const operationId = `OPR-${crypto.randomUUID()}`;
+    const root = path.join(run.run_root, "external-launches", operationId);
+    const journal = path.join(root, "adapter.events.jsonl");
+    fs.mkdirSync(root, { recursive: true });
+    const now = context.now();
+    context.db.run("INSERT INTO work_launches (operation_id, work_id, profile_json, profile_hash, status, state_dir, journal_path, provider_session_id, adapter_receipt_json, created_at, updated_at) VALUES (?, ?, ?, ?, 'launching', ?, ?, NULL, NULL, ?, ?)", [operationId, work.work_id, JSON.stringify(resolved), resolved.profile_hash, root, journal, now, now]);
+    const executable = resolveHarnessCommand(context.ddFlowHome, runtimeHarness(resolved.worker), "adapter");
+    const common = ["--state-dir", root, "--journal", journal, "--cwd", run.workspace_root, "--provider", resolved.worker.provider, "--model", resolved.worker.model, "--reasoning", resolved.worker.reasoning, "--mode", resolved.worker.mode, "--permission", resolved.worker.permission, "--project-root", run.workspace_root, "--dd-flow-home", context.ddFlowHome, ...harnessRuntimeArguments(context.ddFlowHome, runtimeHarness(resolved.worker)), "--json"];
+    const evidence = (value) => fs.appendFileSync(journal, `${JSON.stringify({ type: "adapter_call", at: context.now(), ...value })}\n`);
+    try {
+        const call = (args, timeoutMs) => runHarnessAdapter({ executable, args, env: context.env, ...(timeoutMs ? { timeoutMs } : {}), ...(input.progress ? { progress: input.progress } : {}), onEvidence: evidence });
+        await call(["daemon", "start", ...common]);
+        const created = await call(["session", "create", ...common]);
+        const sessionId = adapterSessionId(created);
+        if (!sessionId)
+            throw new AppError("harness_adapter_invalid", "Harness adapter did not return a typed Session id", 1, { work_id: work.work_id, harness: runtimeHarness(resolved.worker) });
+        const promptFile = path.join(root, "launch.md");
+        fs.writeFileSync(promptFile, `Start the assigned Work now. Your first tool call must be this exact standalone command:\n\n${workStartCommand(context, work)}\n\nUse the packet returned by that command. Do not claim another Work or run this command more than once.\n`);
+        const prompted = await call(["session", "prompt", "--session-id", sessionId, "--prompt-file", promptFile, ...common], 45 * 60_000);
+        assertRunMutationAllowed(context, work.project_id, work.run_id, generation);
+        context.db.run("UPDATE work_launches SET status = 'start_requested', provider_session_id = ?, adapter_receipt_json = ?, updated_at = ? WHERE operation_id = ?", [sessionId, JSON.stringify({ create: created, prompt: prompted }), context.now(), operationId]);
+        return { ok: true, work_id: work.work_id, operation_id: operationId, status: "start_requested", session: { harness_id: runtimeHarness(resolved.worker), session_id: sessionId }, profile_hash: resolved.profile_hash, journal_path: journal };
+    }
+    catch (error) {
+        context.db.run("UPDATE work_launches SET status = 'failed', adapter_receipt_json = ?, updated_at = ? WHERE operation_id = ?", [JSON.stringify({ error: String(error) }), context.now(), operationId]);
+        throw error;
+    }
+}
+function workOverride(payload) {
+    if (!payload)
+        return undefined;
+    let value;
+    try {
+        value = JSON.parse(payload);
+    }
+    catch {
+        return undefined;
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const execution = value.execution_override;
+    return execution && typeof execution === "object" && !Array.isArray(execution) ? execution : undefined;
+}

package/dist/services/harness-adapter.js

@@ -1,5 +1,6 @@
 import { spawn } from "node:child_process";
 import { AppError } from "../shared/errors.js";
+const maxAdapterOutputBytes = 1_000_000;
 /** Runs one harness command with the lifecycle guarantees shared by agent services. */
 export function runHarnessAdapter(input) {
     const timeoutMs = input.timeoutMs ?? 120_000;
@@ -8,6 +9,7 @@ export function runHarnessAdapter(input) {
         const child = spawn(input.executable, input.args, { env: input.env, detached, stdio: ["ignore", "pipe", "pipe"] });
         let stdout = "";
         let stderr = "";
+        let outputTooLarge = false;
         let timedOut = false;
         let killTimer;
         const terminate = (signal) => { try {
@@ -20,11 +22,19 @@ export function runHarnessAdapter(input) {
         const heartbeat = input.progress && input.progressMessage ? setInterval(() => input.progress?.(`${input.progressMessage}; waiting for adapter completion`), 15_000) : undefined;
         const timer = setTimeout(() => { timedOut = true; terminate("SIGTERM"); killTimer = setTimeout(() => terminate("SIGKILL"), 5_000); }, timeoutMs);
         const evidence = (value) => input.onEvidence?.({ executable: input.executable, args: input.args, ...value, at: new Date().toISOString() });
-        child.stdout.setEncoding("utf8").on("data", (chunk) => { stdout += chunk; });
-        child.stderr.setEncoding("utf8").on("data", (chunk) => { stderr += chunk; });
+        const append = (current, chunk) => {
+            if (Buffer.byteLength(current) + Buffer.byteLength(chunk) > maxAdapterOutputBytes) {
+                outputTooLarge = true;
+                terminate("SIGTERM");
+                return current;
+            }
+            return current + chunk;
+        };
+        child.stdout.setEncoding("utf8").on("data", (chunk) => { stdout = append(stdout, chunk); });
+        child.stderr.setEncoding("utf8").on("data", (chunk) => { stderr = append(stderr, chunk); });
         child.once("error", (error) => { clearTimeout(timer); if (heartbeat)
             clearInterval(heartbeat); if (killTimer)
-            clearTimeout(killTimer); evidence({ status: null, error: error.message }); reject(new AppError("merge_adapter_failed", "Harness adapter call failed", 1, { executable: input.executable, args: input.args.slice(0, 3), error: error.message })); });
+            clearTimeout(killTimer); evidence({ status: null, error: error.message }); reject(new AppError("harness_adapter_failed", "Harness adapter call failed", 1, { executable: input.executable, args: input.args.slice(0, 3), error: error.message })); });
         child.once("close", (status, signal) => {
             clearTimeout(timer);
             if (heartbeat)
@@ -32,15 +42,20 @@ export function runHarnessAdapter(input) {
             if (killTimer)
                 clearTimeout(killTimer);
             evidence({ status, signal, timed_out: timedOut, stdout, stderr });
+            if (outputTooLarge)
+                return reject(new AppError("harness_adapter_output_limit", "Harness adapter exceeded the bounded reply limit", 1, { executable: input.executable, args: input.args.slice(0, 3), max_output_bytes: maxAdapterOutputBytes }));
             if (timedOut)
-                return reject(new AppError("merge_adapter_timeout", "Harness adapter call timed out", 1, { executable: input.executable, args: input.args.slice(0, 3), timeout_ms: timeoutMs }));
+                return reject(new AppError("harness_adapter_timeout", "Harness adapter call timed out", 1, { executable: input.executable, args: input.args.slice(0, 3), timeout_ms: timeoutMs }));
             if (status !== 0)
-                return reject(new AppError("merge_adapter_failed", "Harness adapter call failed", 1, { executable: input.executable, args: input.args.slice(0, 3), status, signal, stderr }));
+                return reject(new AppError("harness_adapter_failed", "Harness adapter call failed", 1, { executable: input.executable, args: input.args.slice(0, 3), status, signal, stderr }));
             try {
-                resolve(JSON.parse(stdout));
+                const reply = JSON.parse(stdout);
+                if (!reply || typeof reply !== "object" || Array.isArray(reply))
+                    throw new Error("not object");
+                resolve(reply);
             }
             catch {
-                reject(new AppError("merge_adapter_invalid", "Harness adapter returned invalid JSON", 1, { executable: input.executable, stdout }));
+                reject(new AppError("harness_adapter_invalid", "Harness adapter returned one invalid JSON object", 1, { executable: input.executable }));
             }
         });
     });
@@ -48,12 +63,14 @@ export function runHarnessAdapter(input) {
 export function adapterSessionId(value) {
     if (!value || typeof value !== "object")
         return null;
-    for (const [key, item] of Object.entries(value)) {
-        if (["session_id", "sessionId", "provider_session_id", "providerSessionId", "adapter_session_id", "adapterSessionId", "thread_id", "threadId", "conversation_id"].includes(key) && typeof item === "string")
-            return item;
-        const nested = adapterSessionId(item);
-        if (nested)
-            return nested;
-    }
+    const reply = value;
+    for (const key of ["provider_session_id", "adapter_session_id", "session_id"])
+        if (typeof reply[key] === "string" && reply[key].trim())
+            return reply[key];
+    const session = reply.session;
+    if (session && typeof session === "object" && !Array.isArray(session))
+        for (const key of ["provider_session_id", "session_id"])
+            if (typeof session[key] === "string" && String(session[key]).trim())
+                return session[key];
     return null;
 }

package/dist/services/hooks.js

@@ -324,10 +324,12 @@ export function handleCodexHook(context, input) {
     // Codex retains the root session_id for a thread-spawned child, while the
     // payload transcript belongs to the current agent_id. Keep lineage separate
     // from ownership: otherwise a child overwrites the root transcript binding.
-    const bindingOwnerId = providerSessionId ?? rootProviderSessionId;
-    const binding = bindingOwnerId ? upsertSessionBindingFromPayload(context, project, bindingOwnerId, payload) : undefined;
+    const eventKey = hookEventKey(payload, eventName, toolName, command);
     const storageId = providerSessionId ? storageSessionId(nativeSessionIdentity("codex-desktop", providerSessionId)) : null;
     const parentSessionId = parentProviderSessionId ? storageSessionId(nativeSessionIdentity("codex-desktop", parentProviderSessionId)) : null;
+    assertHookEventReplay(context, { projectId: project.id, eventKey, harness: "codex-desktop", providerSessionId: providerSessionId ?? null, parentSessionId, daemonId: stringValue(context.env.DD_FLOW_DAEMON_ID) ?? null, sessionId: storageId, turnId: turnId ?? null, eventName, toolName: toolName ?? null, matchKey, cwd: stringValue(payload.cwd) ?? null });
+    const bindingOwnerId = providerSessionId ?? rootProviderSessionId;
+    const binding = bindingOwnerId ? upsertSessionBindingFromPayload(context, project, bindingOwnerId, payload) : undefined;
     const observedSession = flowPayload
         ? bindObservedFlowSession(context, project, {
             ...flowPayload,
@@ -338,7 +340,6 @@ export function handleCodexHook(context, input) {
         : undefined;
     const effectiveSessionId = observedSession?.session_id ?? storageId;
     const protocolId = observedSession?.protocol_id ?? binding?.protocol_id ?? null;
-    const eventKey = hookEventKey(payload, eventName, toolName, command);
     const inserted = recordHookEvent(context, {
         projectId: project.id,
         protocolId,
@@ -458,6 +459,10 @@ export function handleZcodeEvent(context, input) {
     const sessionId = storageSessionId(nativeSessionIdentity("zcode-acp", providerSessionId));
     const parentSessionId = childProviderSessionId ? storageSessionId(nativeSessionIdentity("zcode-acp", rootProviderSessionId)) : null;
     const agentId = stringValue(runtime.agentId);
+    const eventKey = stringValue(update.toolCallId) ?? crypto.createHash("sha256").update(JSON.stringify({
+        harness: "zcode-acp", providerSessionId, command
+    })).digest("hex");
+    assertHookEventReplay(context, { projectId: project.id, eventKey, harness: "zcode-acp", providerSessionId, parentSessionId, daemonId: daemonId ?? null, sessionId, turnId: null, eventName: "PreToolUse", toolName: toolName ?? "Bash", matchKey, cwd: expectedRoot });
     const observedSession = flowPayload ? bindObservedFlowSession(context, project, {
         ...flowPayload,
         harness: "zcode-acp",
@@ -465,9 +470,6 @@ export function handleZcodeEvent(context, input) {
         agent_id: agentId ?? null,
         parent_session_id: parentSessionId
     }, sessionId) : undefined;
-    const eventKey = stringValue(update.toolCallId) ?? crypto.createHash("sha256").update(JSON.stringify({
-        harness: "zcode-acp", providerSessionId, command
-    })).digest("hex");
     const payload = {
         session_id: providerSessionId,
         agent_id: agentId,
@@ -564,12 +566,13 @@ export function handleGrokEvent(context, input) {
     const parentSessionId = isChild ? storageSessionId(nativeSessionIdentity("grok-acp", stringValue(ddGrok.parentProviderSessionId) ?? rootProviderSessionId)) : null;
     const daemonId = stringValue(ddGrok.daemonId);
     const agentId = stringValue(hook.agent_id) ?? stringValue(hook.agentId);
-    const observedSession = flowPayload ? bindObservedFlowSession(context, project, {
-        ...flowPayload, harness: "grok-acp", provider_session_id: providerSessionId, agent_id: agentId ?? null, parent_session_id: parentSessionId
-    }, sessionId) : undefined;
     const eventKey = stringValue(hook.event_id) ?? stringValue(hook.eventId) ?? crypto.createHash("sha256").update(JSON.stringify({
         harness: "grok-acp", providerSessionId, command, turn: hook.turn_id ?? hook.turnId ?? null
     })).digest("hex");
+    assertHookEventReplay(context, { projectId: project.id, eventKey, harness: "grok-acp", providerSessionId, parentSessionId, daemonId: daemonId ?? null, sessionId, turnId: stringValue(hook.turn_id) ?? stringValue(hook.turnId) ?? null, eventName: "PreToolUse", toolName: toolName ?? "Bash", matchKey, cwd: expectedRoot });
+    const observedSession = flowPayload ? bindObservedFlowSession(context, project, {
+        ...flowPayload, harness: "grok-acp", provider_session_id: providerSessionId, agent_id: agentId ?? null, parent_session_id: parentSessionId
+    }, sessionId) : undefined;
     const payload = {
         ...hook, session_id: providerSessionId, agent_id: agentId, cwd: expectedRoot, tool_name: toolName ?? "Bash", tool_input: rawInput,
         command, provider: stringValue(observedProfile.provider), model: stringValue(observedProfile.model), reasoning: stringValue(observedProfile.reasoning), mode: stringValue(observedProfile.mode), agent_type: stringValue(hook.subagent_type) ?? stringValue(hook.subagentType)
@@ -668,6 +671,7 @@ function handleControlledToolEvent(context, input, event, harness) {
         }
     }
     const agentId = stringValue(session.agent_id);
+    assertHookEventReplay(context, { projectId: project.id, eventKey: baseKey, harness, providerSessionId, parentSessionId, daemonId, sessionId, turnId: stringValue(event.message_id) ?? null, eventName: "PreToolUse", toolName, matchKey, cwd: expectedRoot });
     const observedSession = flowPayload ? bindObservedFlowSession(context, project, {
         ...flowPayload, harness, provider_session_id: providerSessionId, agent_id: agentId ?? null,
         parent_session_id: parentSessionId, provider: stringValue(profile.provider) ?? null, model: stringValue(profile.model) ?? null,
@@ -914,21 +918,24 @@ export function claimRecentMatchingHookEvent(context, input) {
 /** Finds the trusted event that a stage- or Work-specific claimant will atomically claim. */
 export function findRecentMatchingHookEvent(context, input) {
     const freshAfter = new Date(Date.parse(context.now()) - 60_000).toISOString();
-    const find = () => context.db.get(`SELECT id, event_key FROM hook_events
+    const find = () => context.db.all(`SELECT id, event_key FROM hook_events
      WHERE project_id = ? AND match_key = ? AND status = 'observed' AND created_at >= ?
-     ORDER BY id DESC LIMIT 1`, [input.projectId, input.matchKey, freshAfter]);
-    let event = find();
+     ORDER BY id DESC LIMIT 2`, [input.projectId, input.matchKey, freshAfter]);
+    let events = find();
     // Some harnesses publish nested-agent tool events concurrently with command
     // execution. Give the trusted event a short bounded window to reach SQLite.
     const deadline = Date.now() + 250;
-    while (!event?.event_key && Date.now() < deadline) {
+    while (events.length === 0 && Date.now() < deadline) {
         Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
-        event = find();
+        events = find();
     }
-    if (!event?.event_key) {
+    if (events.length === 0 || !events[0]?.event_key) {
         throw new AppError(input.errorCode, `${input.operation} requires one matching harness lifecycle event. Stay in this Session and retry the exact standalone lifecycle command; do not create a new Session.`, 1);
     }
-    return { id: event.id, eventKey: event.event_key };
+    if (events.length > 1) {
+        throw new AppError("ambiguous_lifecycle_receipt", `${input.operation} has more than one fresh matching lifecycle event; provide its exact hook event ID`, 1, { match_key: input.matchKey, event_keys: events.map((event) => event.event_key) });
+    }
+    return { id: events[0].id, eventKey: events[0].event_key };
 }
 /** Fallback for Desktop paths that execute the original command after a hook rewrite. */
 export function claimBootstrapHookEvent(context, input) {
@@ -1405,12 +1412,11 @@ function sessionBinding(context, projectId, sessionId) {
     return context.db.get("SELECT * FROM codex_session_bindings WHERE project_id = ? AND session_id = ?", [projectId, sessionId]);
 }
 function recordHookEvent(context, input) {
-    const existing = context.db.get("SELECT id FROM hook_events WHERE project_id = ? AND event_key = ?", [input.projectId, input.eventKey]);
-    if (existing)
+    if (assertHookEventReplay(context, input))
         return false;
     context.db.run(`INSERT INTO hook_events
-      (project_id, protocol_id, harness, provider_session_id, parent_session_id, daemon_id, session_id, agent_id, turn_id, transcript_path, provider, model, reasoning, mode, agent_type, cwd, event_key, match_key, event_name, tool_name, status, sanitized_summary, created_at)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+        (project_id, protocol_id, harness, provider_session_id, parent_session_id, daemon_id, session_id, agent_id, turn_id, transcript_path, provider, model, reasoning, mode, agent_type, cwd, event_key, match_key, event_name, tool_name, status, sanitized_summary, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
         input.projectId,
         input.protocolId,
         input.harness,
@@ -1437,6 +1443,23 @@ function recordHookEvent(context, input) {
     ]);
     return true;
 }
+/** A duplicate delivery is harmless only when all durable identity facts match. */
+function assertHookEventReplay(context, input) {
+    const existing = context.db.get(`SELECT harness, provider_session_id, parent_session_id, daemon_id, session_id, turn_id, event_name, tool_name, match_key, cwd
+       FROM hook_events WHERE project_id = ? AND event_key = ?`, [input.projectId, input.eventKey]);
+    if (existing) {
+        const observed = {
+            harness: input.harness, provider_session_id: input.providerSessionId, parent_session_id: input.parentSessionId,
+            daemon_id: input.daemonId ?? null, session_id: input.sessionId, turn_id: input.turnId,
+            event_name: input.eventName, tool_name: input.toolName, match_key: input.matchKey, cwd: input.cwd
+        };
+        if (Object.entries(observed).some(([key, value]) => existing[key] !== value)) {
+            throw new AppError("hook_event_replay_mismatch", "Lifecycle event ID was already observed with different immutable identity", 1, { event_key: input.eventKey });
+        }
+        return true;
+    }
+    return false;
+}
 function projectForHook(context, explicitRoot, cwd) {
     if (explicitRoot)
         return requireProjectByRoot(context, resolveProjectRoot(explicitRoot));