@deksden-com/dd-flow-cli 0.9.0-beta.75 → 0.9.0-beta.79

package/dist/cli.js

@@ -1,4 +1,8 @@
 #!/usr/bin/env node
-import { runCli } from "./cli/run-cli.js";
-const exitCode = await runCli(process.argv.slice(2));
+const args = process.argv.slice(2);
+const managedHook = Boolean(process.env.DD_FLOW_CODEX_STATE_DIR) && args.slice(0, 3).join(" ") === "codex hook handle" && !args.includes("--help") && !args.includes("-h");
+const exitCode = managedHook
+    ? await (await import("./cli/hook-ingress.js")).runHookIngress(args)
+    : await (await import("./cli/run-cli.js")).runCli(args);
 process.exitCode = exitCode;
+export {};

package/dist/harness-runtime/lib/dd-codex-daemon.d.mts

@@ -0,0 +1 @@
+export function callDaemon(stateDir: string, operation: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<Record<string, unknown>>;

package/dist/harness-runtime/lib/dd-codex-daemon.mjs

@@ -81,7 +81,7 @@ export async function callDaemon(stateDir, operation, params = {}, timeoutMs = 3
 }
 
 export async function startDaemon(options) {
-  const paths = locations(options.stateDir); const cwd = absolute(options.cwd, "--cwd"); const config = { cwd, journal: absolute(options.journal, "--journal"), bin: options.bin ?? null, ddFlowBin: options.ddFlowBin ? absolute(options.ddFlowBin, "--dd-flow-bin") : null, ddFlowHome: options.ddFlowHome ? absolute(options.ddFlowHome, "--dd-flow-home") : null, projectRoot: options.projectRoot ? absolute(options.projectRoot, "--project-root") : cwd, resourceHome: process.env.DD_FLOW_RESOURCE_HOME ? absolute(process.env.DD_FLOW_RESOURCE_HOME, "DD_FLOW_RESOURCE_HOME") : null, env: options.ddFlowHome ? { DD_FLOW_HOME: absolute(options.ddFlowHome, "--dd-flow-home") } : {} };
+  const paths = locations(options.stateDir); const cwd = absolute(options.cwd, "--cwd"); const config = { cwd, journal: absolute(options.journal, "--journal"), bin: options.bin ?? null, ddFlowBin: options.ddFlowBin ? absolute(options.ddFlowBin, "--dd-flow-bin") : null, ddFlowHome: options.ddFlowHome ? absolute(options.ddFlowHome, "--dd-flow-home") : null, projectRoot: options.projectRoot ? absolute(options.projectRoot, "--project-root") : cwd, resourceHome: process.env.DD_FLOW_RESOURCE_HOME ? absolute(process.env.DD_FLOW_RESOURCE_HOME, "DD_FLOW_RESOURCE_HOME") : null, env: options.ddFlowHome ? { DD_FLOW_HOME: absolute(options.ddFlowHome, "--dd-flow-home"), ...(options.ddFlowBin ? { DD_FLOW_BIN: absolute(options.ddFlowBin, "--dd-flow-bin") } : {}) } : {} };
   await prepareRuntimeOwner(config, paths.dir);
   await mkdir(paths.dir, { recursive: true, mode: 0o700 }); await chmod(paths.dir, 0o700);
   try { const status = await callDaemon(paths.dir, "daemon.status", {}, 1_000); if (JSON.stringify(status.config) !== JSON.stringify(config)) throw Object.assign(new Error("running daemon has a different configuration"), { code: "daemon_config_mismatch" }); return { ...status, already_running: true }; } catch (error) { if (!["daemon_not_running", "daemon_timeout"].includes(error.code)) throw error; }
@@ -96,10 +96,14 @@ export async function stopDaemon(options) { const timeoutMs = options.timeoutMs
 
 export async function serveDaemon(stateDir) {
   const paths = locations(stateDir); const state = await readState(paths.state); if (!state || state.schema_id !== stateSchema) throw Object.assign(new Error("daemon state missing"), { code: "daemon_state_missing" });
-  const bridge = new CodexBridge({ ...state.config, env: { ...state.config.env, DD_FLOW_DAEMON_ID: state.daemon_id } }); await bridge.start(); const sessions = new Set(state.sessions ?? []); let active = null; let server; let persist = Promise.resolve();
+  const bridge = new CodexBridge({ ...state.config, env: { ...state.config.env, CODEX_HOME: process.env.CODEX_HOME, DD_FLOW_DAEMON_ID: state.daemon_id, DD_FLOW_CODEX_STATE_DIR: paths.dir } }); await bridge.start(); const sessions = new Set(state.sessions ?? []); let active = null; let server; let persist = Promise.resolve();
   const save = (patch = {}) => { Object.assign(state, patch, { pid: process.pid, updated_at: new Date().toISOString(), sessions: [...sessions] }); const snapshot = structuredClone(state); persist = persist.then(() => writeState(paths.state, snapshot)).then(() => heartbeatDaemonProcess(snapshot.config, snapshot.resource_process).catch(() => {})); return persist; };
   const dispatch = async (operation, params) => {
     const assertDispatch = captureDispatchGuard(bridge);
+    if (operation === "hook.verify") {
+      if (params.daemonId !== state.daemon_id) throw Object.assign(new Error("Hook daemon identity differs"), { code: "native_hook_unproven" });
+      return { ...bridge.verifyNativeHook(params), daemonId: state.daemon_id, ddFlowHome: state.config.ddFlowHome, projectRoot: state.config.projectRoot };
+    }
     if (operation === "daemon.status") return { daemon_id: state.daemon_id, pid: process.pid, cwd: state.cwd, journal: state.journal, config: state.config, sessions: [...sessions], active_operation: active, shutdown_state: state.shutdown_state };
     // The runner may need to retire an orphaned daemon after its caller was
     // interrupted. `daemon.stop` is the one control operation that remains
@@ -124,6 +128,7 @@ export async function serveDaemon(stateDir) {
       const owned = new Set(sessions);
       for (const id of owned) for (const child of bridge.directChildren?.(id) ?? []) owned.add(child.provider_session_id);
       if (!owned.has(params.sessionId)) throw Object.assign(new Error("inspection Session is not owned by this daemon"), { code: "session_identity_mismatch" });
+      bridge.assertHookHealthy(params.sessionId);
       try { return await inspectCodexTree(bridge, { ...state.config, ...params }, { remember: id => sessions.add(id), active: () => active }); }
       finally { await save(); }
     }

package/dist/harness-runtime/lib/dd-codex.mjs

@@ -7,6 +7,13 @@ import { ObservationClock, observedTimeout } from "./observation-clock.mjs";
 import { observeModel } from "./model-observations.mjs";
 
 const LATE_RESPONSE_GRACE_MS = 5_000;
+const CODEX_SESSION_CONFIG = Object.freeze({
+  bypass_hook_trust: true,
+  "features.plugins": false,
+  "features.multi_agent_v2.enabled": true,
+  "features.multi_agent_v2.tool_namespace": "collaboration",
+  "features.multi_agent_v2.wait_agent_enabled": true
+});
 
 // Minimal JSON-RPC wrapper around the public Codex app-server protocol.  It is
 // intentionally one-shot: the provider owns durable Threads, while the caller
@@ -61,6 +68,8 @@ export class CodexBridge {
   receive(line) {
     let message; try { message = JSON.parse(line); } catch { this.journal.write("malformed", { line }); return; }
     this.observeTopology(message);
+    this.observeNativeHook(message);
+    this.observeHookFailure(message);
     if (["model/rerouted", "thread/settings/updated"].includes(message.method)) {
       const params = message.params ?? {}, id = params.threadId;
       let root = id; const seen = new Set();
@@ -117,24 +126,122 @@ export class CodexBridge {
     if (threadId && message.method === "item/completed" && message.params?.item?.type === "agentMessage") this.finalMessages.set(threadId, { item: message.params.item, completedAt: Date.now() });
   }
 
+  isManagedHook(run) {
+    const home = this.options.env?.CODEX_HOME;
+    return Boolean(home && run?.eventName === "preToolUse" && run.handlerType === "command"
+      && run.executionMode === "sync" && run.statusMessage === "dd-flow runtime observation"
+      && run.sourcePath === path.join(home, "hooks.json"));
+  }
+
+  observeNativeHook(message) {
+    if (message.method === "turn/completed") {
+      const { threadId, turn } = message.params ?? {};
+      for (const [id, hook] of this.activeHooks ?? []) {
+        if (hook.threadId === threadId && hook.turnId === turn?.id) this.activeHooks.delete(id);
+      }
+      return;
+    }
+    if (!["hook/started", "hook/completed"].includes(message.method)) return;
+    const { threadId, turnId, run } = message.params ?? {};
+    if (!this.isManagedHook(run) || typeof run.id !== "string" || !threadId) return;
+    this.activeHooks ??= new Map();
+    if (message.method === "hook/started") this.activeHooks.set(run.id, { threadId, turnId });
+    else this.activeHooks.delete(run.id);
+  }
+
+  verifyNativeHook(input) {
+    const { rootSessionId, sessionId, toolCallId, turnId } = input;
+    const home = this.options.env?.CODEX_HOME;
+    const id = `pre-tool-use:0:${path.join(home ?? "", "hooks.json")}:${toolCallId}`;
+    const active = this.activeHooks?.get(id);
+    let current = sessionId;
+    const seen = new Set();
+    while (current && current !== rootSessionId && !seen.has(current)) {
+      seen.add(current); current = this.descendants.get(current)?.parent_provider_session_id;
+    }
+    if (!active || active.threadId !== sessionId || active.turnId !== turnId || !toolCallId
+        || current !== rootSessionId || !this.requestedProfiles.has(rootSessionId)) {
+      fail("No matching active managed native hook", "native_hook_unproven", { provider_session_id: sessionId, tool_call_id: toolCallId });
+    }
+    return { rootSessionId, sessionId, toolCallId, parentSessionId: sessionId === rootSessionId ? null : this.descendants.get(sessionId)?.parent_provider_session_id };
+  }
+
+  observeHookFailure(message) {
+    const { threadId, turnId, run } = message.params ?? {};
+    const home = this.options.env?.CODEX_HOME;
+    if (message.method !== "hook/completed" || run?.status !== "failed" ||
+        run.eventName !== "preToolUse" || run.handlerType !== "command" ||
+        run.statusMessage !== "dd-flow runtime observation" || !home ||
+        run.sourcePath !== path.join(home, "hooks.json")) return;
+    const ancestors = new Set();
+    let root;
+    let current = threadId;
+    while (current && !ancestors.has(current)) {
+      ancestors.add(current);
+      if (this.requestedProfiles.has(current)) root = current;
+      current = this.descendants.get(current)?.parent_provider_session_id;
+    }
+    if (!root) return;
+    this.hookFailures ??= new Map();
+    if (this.hookFailures.has(root)) return;
+    const entries = Array.isArray(run.entries) ? run.entries : [];
+    const reason = entries.filter(entry => entry.kind === "error").map(entry => entry.text).join("; ");
+    const error = Object.assign(new Error(reason || "Managed Codex hook failed"), {
+      code: /timed out/i.test(reason) ? "native_hook_timeout" : "native_hook_failed",
+      details: { provider_session_id: threadId, root_provider_session_id: root, turn_id: turnId,
+        hook_run_id: run.id, effect: "unknown", duration_ms: run.durationMs }
+    });
+    this.hookFailures.set(root, error);
+    this.journal.write("native_hook_failure", { code: error.code, message: error.message, ...error.details });
+    for (const [id, pending] of this.pending) {
+      if (ancestors.has(pending.threadId) && pending.method !== "turn/interrupt") {
+        clearTimeout(pending.timer); this.pending.delete(id); pending.reject(error);
+      }
+    }
+  }
+
+  assertHookHealthy(sessionId) {
+    const visited = new Set();
+    while (sessionId && !visited.has(sessionId)) {
+      visited.add(sessionId);
+      const error = this.hookFailures?.get(sessionId);
+      if (error) throw error;
+      sessionId = this.descendants.get(sessionId)?.parent_provider_session_id;
+    }
+  }
+
   // Collaboration child Threads are provider facts.  Keep only objects that
   // explicitly carry a parent relationship, including native spawn receipts.
   // A wait/send receiver is not necessarily a child of its sender.
   observeTopology(value, depth = 0) {
     if (!value || typeof value !== "object" || depth > 8) return;
     if (Array.isArray(value)) { for (const item of value) this.observeTopology(item, depth + 1); return; }
+    const activity = value.params?.item;
+    const activityParent = value.params?.threadId;
+    if (activity?.type === "subAgentActivity" && typeof activity.agentThreadId === "string" && activity.agentThreadId &&
+        typeof activityParent === "string" && activityParent && activity.agentThreadId !== activityParent) {
+      const previous = this.descendants.get(activity.agentThreadId);
+      const observed = activity.kind === "completed" ? "completed" : activity.kind === "interrupted" ? "interrupted" : "running";
+      const status = previous?.status === "completed" ? "completed" : observed;
+      this.descendants.set(activity.agentThreadId, { ...previous, provider_session_id: activity.agentThreadId,
+        parent_provider_session_id: activityParent, status, agent_path: activity.agentPath ?? previous?.agent_path ?? null,
+        source: "codex.app_server.subAgentActivity" });
+    }
     if (value.type === "collabAgentToolCall" && value.tool === "spawnAgent" &&
         typeof value.senderThreadId === "string" && value.senderThreadId && Array.isArray(value.receiverThreadIds)) {
       for (const child of value.receiverThreadIds) {
         if (typeof child !== "string" || !child || child === value.senderThreadId) continue;
-        this.descendants.set(child, { provider_session_id: child, parent_provider_session_id: value.senderThreadId,
-          status: value.agentsStates?.[child]?.status ?? "unknown", source: "codex.app_server" });
+        const previous = this.descendants.get(child);
+        this.descendants.set(child, { ...previous, provider_session_id: child, parent_provider_session_id: value.senderThreadId,
+          status: previous?.status === "completed" ? "completed" : value.agentsStates?.[child]?.status ?? "unknown", source: "codex.app_server" });
       }
     }
     const id = value.threadId ?? value.id ?? null;
     const parent = value.parentThreadId ?? value.parent_thread_id ?? null;
     if (typeof id === "string" && id && typeof parent === "string" && parent) {
-      this.descendants.set(id, { provider_session_id: id, parent_provider_session_id: parent, status: value.status?.type ?? value.status ?? "unknown", source: "codex.app_server" });
+      const previous = this.descendants.get(id);
+      this.descendants.set(id, { ...previous, provider_session_id: id, parent_provider_session_id: parent,
+        status: previous?.status === "completed" ? "completed" : value.status?.type ?? value.status ?? "unknown", source: "codex.app_server" });
     }
     for (const child of Object.values(value)) this.observeTopology(child, depth + 1);
   }
@@ -169,7 +276,7 @@ export class CodexBridge {
           this.pending.delete(id); reject(timeoutError);
         }, LATE_RESPONSE_GRACE_MS);
       }, timeoutMs, { onGap: gap => this.journal.write("observation_gap", { ...gap, method, request_id: id }) });
-      this.pending.set(id, { resolve, reject, timer, method }); this.send({ jsonrpc: "2.0", id, method, params });
+      this.pending.set(id, { resolve, reject, timer, method, threadId: params.threadId }); this.send({ jsonrpc: "2.0", id, method, params });
     });
   }
   send(value) {
@@ -198,6 +305,21 @@ async function withBridge(options, action) { const bridge = new CodexBridge(opti
 function profile(options) { return { harness: "codex-desktop", model: options.model ?? null, reasoning: options.reasoning ?? null }; }
 function threadId(result) { const id = result?.thread?.id ?? result?.threadId; return required(id, "Codex thread id"); }
 function directChildren(bridge, sessionId) { return typeof bridge?.directChildren === "function" ? bridge.directChildren(sessionId) : []; }
+function codexSessionConfig() { return { ...CODEX_SESSION_CONFIG }; }
+
+async function requestConfiguredThread(bridge, method, params, timeoutMs) {
+  try { return await bridge.request(method, { ...params, config: codexSessionConfig() }, timeoutMs); }
+  catch (error) {
+    const data = error?.details?.data;
+    const key = data?.configKey ?? data?.config_key ?? null;
+    if (error?.code === "rpc_error" && (data?.reason === "config" || String(key ?? "").startsWith("features.multi_agent_v2"))) {
+      throw Object.assign(new Error("Codex runtime rejected the required multi-agent v2 session configuration"), {
+        code: "codex_multi_agent_v2_unavailable", cause: error, details: { method, provider_error: error.details }
+      });
+    }
+    throw error;
+  }
+}
 
 function threadReceipt(thread) {
   // Thread reads can include the whole transcript even with includeTurns:false.
@@ -231,13 +353,12 @@ export async function createSessionWithBridge(bridge, options) {
   // dd-codex is the eval-only adapter. Its CODEX_HOME is generated by
   // dd-flow, so trust only that managed PreToolUse hook for this thread and
   // do not load user plugin hooks into the isolated evaluator.
-  const result = await bridge.request("thread/start", {
+  const result = await requestConfiguredThread(bridge, "thread/start", {
     cwd,
     model: options.model ?? null,
     approvalPolicy: "never",
     sandbox: "danger-full-access",
-    ephemeral: false,
-    config: { bypass_hook_trust: true, "features.plugins": false }
+    ephemeral: false
   });
   // ThreadStartParams has no reasoning-effort field.  The first turn applies
   // it, so reporting the Desktop default here would be a false profile drift.
@@ -258,6 +379,7 @@ export async function startSessionWithBridge(bridge, options) {
   bridge.requestedProfiles?.set(sessionId, profile(options));
   bridge.finalMessages?.delete(sessionId);
   options.assertDispatch?.();
+  bridge.assertHookHealthy?.(sessionId);
   const started = await bridge.request("turn/start", { threadId: sessionId, input: [{ type: "text", text: prompt }], cwd, model: options.model ?? null, effort: options.reasoning ?? null, approvalPolicy: "never", sandboxPolicy: { type: "dangerFullAccess" } }, options.timeoutMs ?? 30_000);
   const turn = started?.turn ?? started; const turnId = turn?.id ?? null;
   if (typeof turnId !== "string" || !turnId) throw new Error("Codex did not return a Turn id");
@@ -273,10 +395,12 @@ export async function promptSessionWithBridge(bridge, options) {
   bridge.requestedProfiles?.set(sessionId, profile(options));
   bridge.finalMessages?.delete(sessionId);
   options.assertDispatch?.();
+  bridge.assertHookHealthy?.(sessionId);
   const started = await bridge.request("turn/start", { threadId: sessionId, input: [{ type: "text", text: prompt }], cwd, model: options.model ?? null, effort: options.reasoning ?? null, approvalPolicy: "never", sandboxPolicy: { type: "dangerFullAccess" } }, options.timeoutMs ?? 1_800_000);
   const turn = started?.turn ?? started; const turnId = turn?.id ?? null;
   const completed = await waitForTurn(bridge, sessionId, turnId, options.timeoutMs ?? 1_800_000, options, cwd);
   const thread = await readCompletedThread(bridge, sessionId);
+  bridge.assertHookHealthy?.(sessionId);
   const assistantText = latestAssistantText(thread) ?? latestAssistantText(completed);
   return { harness: "codex-desktop", provider_session_id: sessionId, adapter_session_id: sessionId, turn_id: turnId, status: "completed", turn: completed, ...(thread ? { thread: threadReceipt(thread) } : {}), descendants: directChildren(bridge, sessionId), ...(assistantText ? { assistant_text: assistantText } : {}), requested_profile: profile(options), observed_profile: await observeCodexProfile(bridge, options, sessionId, { model: thread?.model ?? null, reasoning: thread?.reasoningEffort ?? null, provider: thread?.modelProvider ?? null }, "thread/read.after_turn") };
 }
@@ -285,13 +409,12 @@ async function ensureThreadLoaded(bridge, sessionId, options, cwd) {
   const value = await bridge.request("thread/read", { threadId: sessionId, includeTurns: false }, 10_000);
   const thread = value?.thread ?? value;
   if (thread?.status?.type !== "notLoaded") return;
-  await bridge.request("thread/resume", {
+  await requestConfiguredThread(bridge, "thread/resume", {
     threadId: sessionId,
     cwd,
     model: options.model ?? null,
     approvalPolicy: "never",
-    sandbox: "danger-full-access",
-    config: { bypass_hook_trust: true, "features.plugins": false }
+    sandbox: "danger-full-access"
   }, 30_000);
 }
 
@@ -303,6 +426,7 @@ async function waitForTurn(bridge, sessionId, turnId, timeoutMs, options, cwd) {
   const failureNotBefore = Date.now() + 1_000;
   let nextStoredReadAt = Date.now();
   while (!clock.sample(bridge.activity?.get(sessionId))) {
+    bridge.assertHookHealthy?.(sessionId);
     const known = bridge.turns.get(turnId) ?? bridge.turns.get(sessionId); if (known?.status === "completed") return terminalTurn(known.value, turnId, bridge);
     if (Date.now() >= nextStoredReadAt) {
       const stored = await readTurn(bridge, sessionId, turnId, false);
@@ -374,20 +498,20 @@ async function readTurn(bridge, sessionId, turnId, includeTurns) {
     const result = await bridge.request("thread/read", { threadId: sessionId, includeTurns }, 10_000);
     const thread = result?.thread ?? result;
     return { turn: Array.isArray(thread?.turns) ? thread.turns.find((turn) => turn?.id === turnId) ?? null : null, threadStatus: thread?.status?.type ?? null };
-  } catch { return null; }
+  } catch { bridge.assertHookHealthy?.(sessionId); return null; }
 }
 
 async function readPersistedTurn(bridge, sessionId, turnId) {
   try {
     const result = await bridge.request("thread/turns/list", { threadId: sessionId, limit: 20, sortDirection: "desc", itemsView: "summary" }, 10_000);
     return Array.isArray(result?.data) ? result.data.find((turn) => turn?.id === turnId) ?? null : null;
-  } catch { return null; }
+  } catch { bridge.assertHookHealthy?.(sessionId); return null; }
 }
 
 async function readCompletedThread(bridge, sessionId) {
   for (let attempt = 0; attempt < 8; attempt += 1) {
     try { const result = await bridge.request("thread/read", { threadId: sessionId, includeTurns: true }, 10_000); return result?.thread ?? result; }
-    catch (error) { bridge.journal.write("thread_read_retry", { session_id: sessionId, attempt, error: error.message }); await new Promise((resolve) => setTimeout(resolve, 150)); }
+    catch (error) { bridge.assertHookHealthy?.(sessionId); bridge.journal.write("thread_read_retry", { session_id: sessionId, attempt, error: error.message }); await new Promise((resolve) => setTimeout(resolve, 150)); }
   }
   return null;
 }

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

@@ -16,7 +16,7 @@ import { DroidMetadataReader, readDroidRoutingLog } from "./droid-observation.mj
 const metadataReaders = new Map();
 function metadataReader(factory) { if (!metadataReaders.has(factory)) metadataReaders.set(factory, new DroidMetadataReader(factory)); return metadataReaders.get(factory); }
 import { confirmDaemonProcess, finishDaemonProcess, heartbeatDaemonProcess, registerDaemonProcess, stopProcessGroup } from "./managed-daemon.mjs";
-import { renderAdapterPolicy } from "./delegation-instructions.mjs";
+import { renderAdapterPolicy, lifecycleRetryInstruction } from "./delegation-instructions.mjs";
 
 const run = promisify(execFile);
 export const DROID_CONTRACT = "dd-droid-harness@1";
@@ -55,7 +55,7 @@ export async function prepareDroidHome(config) {
   const command = `${shell(process.execPath)} ${shell(config.entryPath)} hook handle --state-dir ${shell(paths.dir)}`;
   const hooks = Object.fromEntries(["SessionStart", "PreToolUse", "PostToolUse", "Stop", "SessionEnd", "SubagentStop"].map(event => [event, [{ matcher: "*", hooks: [{ type: "command", command, timeout: 30 }] }]]));
   await writeJsonAtomic(path.join(paths.factory, "hooks.json"), hooks);
-  const worker = `---\nname: dd-flow-worker\ndescription: Execute one explicit dd-flow Work packet or a technical capacity marker\nmodel: ${config.model}\nreasoningEffort: ${config.reasoning}\nmcpServers: []\n---\nFor a Work assignment, your first technical action is the exact standalone work start command supplied by the coordinator. If that command is absent, report an incomplete packet and stop: do not run stage pause, stage finish, or another lifecycle command. Follow only the returned Work packet, invoke its exact work finish or fail command, then stop. A Task child never executes or finishes its coordinator's Stage Work. Do not create children or take another Work. For a technical capacity marker, only return the requested marker; do not read the project or call dd-flow.\n`;
+  const worker = `---\nname: dd-flow-worker\ndescription: Execute one explicit dd-flow Work packet or a technical capacity marker\nmodel: ${config.model}\nreasoningEffort: ${config.reasoning}\nmcpServers: []\n---\nFor a Work assignment, your first technical action is the exact standalone work start command supplied by the coordinator. If that command is absent, report an incomplete packet and stop: do not run stage pause, stage finish, or another lifecycle command. Execute the supplied operation and target exactly; lifecycle invocation IDs are internal runtime authority, so never add or invent them. Continue only after a successful start returns the Work packet. ${lifecycleRetryInstruction} Follow only the returned Work packet, invoke its exact work finish or fail command, then stop. A Task child never executes or finishes its coordinator's Stage Work. Do not create children or take another Work. For a technical capacity marker, only return the requested marker; do not read the project or call dd-flow.\n`;
   await writeFile(path.join(paths.factory, "droids", "dd-flow-worker.md"), worker, { mode: 0o600 });
   return { hooks_sha256: createHash("sha256").update(JSON.stringify(hooks)).digest("hex"), worker_sha256: createHash("sha256").update(worker).digest("hex") };
 }

package/dist/harness-runtime/lib/dd-zcode-daemon.mjs

@@ -145,7 +145,7 @@ export async function startDaemon(options) {
     ddFlowHome: options.ddFlowHome ? absolute(options.ddFlowHome, "--dd-flow-home") : null,
     projectRoot: options.projectRoot ? absolute(options.projectRoot, "--project-root") : null,
     resourceHome: process.env.DD_FLOW_RESOURCE_HOME ? absolute(process.env.DD_FLOW_RESOURCE_HOME, "DD_FLOW_RESOURCE_HOME") : null,
-    env: options.ddFlowHome ? { DD_FLOW_HOME: absolute(options.ddFlowHome, "--dd-flow-home") } : {},
+    env: options.ddFlowHome ? { DD_FLOW_HOME: absolute(options.ddFlowHome, "--dd-flow-home"), ...(options.ddFlowBin ? { DD_FLOW_BIN: absolute(options.ddFlowBin, "--dd-flow-bin") } : {}) } : {},
     livenessTimeoutMs: positiveDuration(options.livenessTimeoutMs, "livenessTimeoutMs", DEFAULT_LIVENESS_TIMEOUT_MS),
     requestTimeoutMs: optionalDuration(options.requestTimeoutMs, "requestTimeoutMs", DEFAULT_REQUEST_TIMEOUT_MS),
   };

package/dist/harness-runtime/lib/delegation-instructions.mjs

@@ -1,8 +1,9 @@
 const ADAPTERS = {
   codex: {
     name: "Codex",
-    launch: "Call the native `spawn_agent` tool in its exposed namespace once per assignment. Use the schema available in this Session: v2 accepts `task_name`, `message`, and `fork_turns: \"none\"`; v1 accepts `message` and `fork_context: false` without task_name. Never mix these schemas. Use the assignment's task_name only with v2. Keep the current model and reasoning by omitting overrides. Do not create a root Session or run the child's command yourself.",
-    wait: "The spawn result is a handle, not completion. Use the exposed native wait_agent (or wait in older schemas) and completion messages. V2 waits for mailbox updates; v1 waits on the returned agent IDs using the arguments in its tool schema. An update is not necessarily final: wait for each child's terminal result. A wait timeout leaves the same child running: continue waiting without relaunch or interruption. Release a settled child only when a release tool is exposed and its Work result has been recorded."
+    launch: "This Session uses the Codex multi-agent v2 API in the `collaboration` namespace. In code mode call `tools.collaboration__spawn_agent` once per assignment with exactly `task_name`, `message`, and `fork_turns: \"none\"` for fresh context. Keep the current model and reasoning by omitting overrides. Do not create a root Session or run the child's command yourself.",
+    wait: "The spawn result is a handle, not completion. In code mode use `tools.collaboration__wait_agent` and native completion messages until every launched child is terminal. A mailbox update is not necessarily final. A wait timeout leaves the same child running: continue waiting without relaunch or interruption. Retain terminal results and product Work receipts. Codex v2 owns idle-agent residency; do not interrupt a completed child as cleanup.",
+    partial: "If a spawn is refused, stop issuing new spawns and retain every successful child handle. Wait for every already-launched child to become terminal; silence is not completion. Do not interrupt a running child to free capacity, and do not interrupt completed children as cleanup. Report completed/launched assignments, assignments not launched and the exact refusal. Return after this partial wave; the controller will issue remaining Work when capacity is available. Do not replay an ambiguous spawn."
   },
   zcode: {
     name: "ZCode",
@@ -43,10 +44,13 @@ function requireAdapter(harness) {
 }
 
 export function delegationContract(harness) {
+  const key = delegationAdapter(harness);
   requireAdapter(harness);
-  return `dd-flow/delegation/${delegationAdapter(harness)}@1`;
+  return `dd-flow/delegation/${key}@${key === "codex" ? 2 : 1}`;
 }
 
+export const lifecycleRetryInstruction = "If the CLI rejects the call with effect=no_effect, recoverable=true and retry_command, execute that exact retry_command in this same Session after correcting the reported input. Never invent IDs. If the native shell tool rejects the launch before the CLI starts, correct only that tool-call error and repeat the same exact command; do not change its arguments. A hook/transport failure is an infrastructure error: stop and report it without retrying. For any other failure, stop and report the exact error; do not run status as a substitute, call a hook handler, retry blindly, or finish the Work.";
+
 export function workerDelegationTask({ workId, startCommand, launchPolicy }) {
   if (!workId || !startCommand) throw new Error("ready fan-out Work lacks its exact start command");
   const context = launchPolicy === "fresh_agent_required"
@@ -57,7 +61,11 @@ export function workerDelegationTask({ workId, startCommand, launchPolicy }) {
     context,
     "Your first technical action must be this exact standalone lifecycle command:",
     startCommand,
-    "Use only the authoritative Work packet returned by that command. Complete the assigned Work, write its required result, invoke its exact standalone work finish command, then stop.",
+    "Execute the issued operation and target exactly. Lifecycle invocation IDs are internal runtime authority and are intentionally omitted; never add or invent them. Preserve any explicit native receipt handle that the command does contain.",
+    "Use the native shell's inherited working directory. Do not set or override a workdir/cwd field for this lifecycle command.",
+    "Continue only if it succeeds and returns the authoritative Work packet.",
+    lifecycleRetryInstruction,
+    "After a successful start, complete the assigned Work, write its required result, invoke its exact standalone work finish command, then stop.",
     "Do not start another Work, create a child, change dependencies, ask the user, or treat a quiet sibling as failed. You cannot ask the user or pause the parent Stage. Missing facts go through this Work's declared result/failure contract; only the coordinator handles Stage HITL."
   ].join("\n");
 }
@@ -77,6 +85,7 @@ export function renderDelegationInstructions({ harness, stage, capacity, works =
     "Retain the frozen coordinator model and reasoning for native children; do not choose a different model, reasoning level or permission mode.",
     "You are the coordinator. The JSON assignments below contain child-only messages, not instructions for you to execute. Pass each message verbatim as the native tool's task/message/prompt argument. For context=fresh, select empty conversation context before launch; if unavailable, report the limitation and stop. Use only fields exposed by your actual native tool schema; if the native tool is absent, report that error without substituting a shell command.",
     "Every child must be a direct child of this current Session. Wait for all launched children to settle before returning. One failed child is evidence for the coordinator, not a reason to cancel its siblings.",
+    adapter.partial ?? "If a spawn is refused, stop issuing new spawns and retain every successful child handle. Wait for all already-launched children, then release completed children using the adapter's exposed native close/release mechanism when supported. A failed batch does not undo successful spawns. Report completed/launched assignments, assignments not launched and the exact refusal; never claim no children launched when any spawn succeeded. Return after this partial wave; the controller will issue remaining Work when capacity is available. Do not replay an ambiguous spawn.",
     "Do not finish this Stage, repair it, or start a successor in this Turn. Do not invent provider or internal session IDs; lifecycle evidence comes from the adapter.",
     adapter.wait,
     "Child assignments (JSON data):",

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/services/canon.js

@@ -1,27 +1,30 @@
 import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
+import { AppError } from "../shared/errors.js";
+import { prepareError } from "../cli/input-preparation.js";
 const canonRootKey = "canon.root";
-export function registerCanonRoot(context, input) {
+export function prepareCanonRegistration(context, input) {
+    if (typeof input.root !== "string" || !input.root.trim())
+        return prepareError(new AppError("validation", "Canon root must be a non-empty path", 2));
     const resolution = resolveCanonRoot(context, { explicitRoot: input.root, allowRegistered: false });
     if (!resolution.ok || !resolution.canon) {
-        return {
-            ...resolution,
-            action: "register",
-            exit_code: 1
-        };
+        return prepareError(new AppError("validation", "Canon root cannot be registered", 2, { root: input.root, blockers: resolution.blockers, candidates: resolution.candidates, bootstrap: resolution.bootstrap }));
     }
+    return resolution.canon;
+}
+export function registerCanonRoot(context, input, canon = prepareCanonRegistration(context, input)) {
     const now = context.now();
     context.db.run(`INSERT INTO runtime_config (key, value_json, created_at, updated_at)
      VALUES (?, ?, ?, ?)
      ON CONFLICT(key) DO UPDATE SET
        value_json = excluded.value_json,
-       updated_at = excluded.updated_at`, [canonRootKey, JSON.stringify({ root: resolution.canon.root }), now, now]);
+       updated_at = excluded.updated_at`, [canonRootKey, JSON.stringify({ root: canon.root }), now, now]);
     return {
         ok: true,
         action: "register",
         canon: {
-            ...resolution.canon,
+            ...canon,
             source: "registered"
         },
         db_path: context.db.path

package/dist/services/cleanup.js

@@ -2,8 +2,7 @@ import fs from "node:fs";
 import { spawnSync } from "node:child_process";
 import path from "node:path";
 import { AppError } from "../shared/errors.js";
-import { parseJsonObject } from "../shared/json.js";
-import { ensureReadableFile } from "../storage/database.js";
+import { prepareJsonFile } from "../cli/input-preparation.js";
 import { projectCheckoutRoot, resolveProjectRoot, runtimeStateJsonPath } from "../storage/paths.js";
 import { appendAudit } from "./audit.js";
 import { requireProjectByRoot } from "./projects.js";
@@ -173,20 +172,29 @@ export function cleanupScan(context, input) {
         plan: { project_root: project.root, project_id: project.id, actions }
     };
 }
-export function cleanupApply(context, input) {
-    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+export function prepareCleanupApply(context, input) {
     const reason = input.reason.trim();
     if (!reason) {
         throw new AppError("validation", "cleanup apply requires --reason", 2);
     }
-    ensureReadableFile(input.planFile);
-    const plan = validateCleanupPlan(parseJsonObject(fs.readFileSync(input.planFile, "utf8"), input.planFile), project);
+    const value = prepareJsonFile(input.planFile, "cleanup plan").value;
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new AppError("validation", "cleanup plan must be an object", 2);
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const plan = validateCleanupPlan(value, project);
     validateNoDestructiveSurprises(context, plan, input.force);
+    return { project, reason, plan };
+}
+export function cleanupApply(context, input) {
+    const { project, reason, plan } = input.prepared ?? prepareCleanupApply(context, input);
     const now = context.now();
     const results = [];
     context.db.beginWriteTransaction();
+    let executing = false;
     try {
+        validateNoDestructiveSurprises(context, plan, input.force);
         for (const action of plan.actions) {
+            executing = true;
             results.push(applyAction(context, action, reason, input.force, now));
         }
         const changed = results.filter((result) => result.changed).length;
@@ -203,6 +211,8 @@ export function cleanupApply(context, input) {
     }
     catch (error) {
         context.db.exec("ROLLBACK");
+        if (executing)
+            throw new AppError("cleanup_apply_failed", "Cleanup failed after execution began; inspect retained artifacts before retrying", 1, { effect: "unknown", database_rolled_back: true, attempted_results: results, cause: error instanceof Error ? error.message : String(error), ...(error instanceof AppError ? { cause_code: error.code } : {}) });
         throw error;
     }
     return {
@@ -251,11 +261,29 @@ function validateCleanupPlan(value, project) {
                 throw new AppError("validation", "close_flow_session requires a native session identity", 2);
             }
         }
+        const requiredField = action.kind === "discard_stale_run" ? "run_id"
+            : ["repair_protocol_state", "cancel_queue_job", "close_worktree_record"].includes(String(action.kind)) ? "protocol_id" : undefined;
+        if (requiredField && (typeof action[requiredField] !== "string" || !action[requiredField].trim()))
+            throw new AppError("validation", `cleanup ${String(action.kind)} requires ${requiredField}`, 2);
+        const numericField = action.kind === "expire_lane_lock" ? "lock_id" : action.kind === "expire_lane_waiter" ? "waiter_id" : undefined;
+        if (numericField && (!Number.isSafeInteger(action[numericField]) || action[numericField] < 1))
+            throw new AppError("validation", `cleanup ${String(action.kind)} requires a positive integer ${numericField}`, 2);
+        if (action.worktree_path !== undefined && (typeof action.worktree_path !== "string" || !path.isAbsolute(action.worktree_path)))
+            throw new AppError("validation", "cleanup worktree_path must be an absolute path", 2);
         return action;
     });
     return { project_root: project.root, project_id: project.id, actions };
 }
 function validateNoDestructiveSurprises(context, plan, force) {
+    for (const action of plan.actions) {
+        if (action.kind === "repair_protocol_state")
+            requireProtocol(context, action.protocol_id, action.project_id);
+        if (action.kind === "discard_stale_run") {
+            const run = context.db.get("SELECT index_json, status FROM runs WHERE project_id = ? AND id = ?", [action.project_id, action.run_id]);
+            if (run && ["running", "discarded"].includes(run.status))
+                cleanupRunIndex(run.index_json);
+        }
+    }
     const destructive = plan.actions.find((action) => action.kind === "close_worktree_record" && action.worktree_path && dirtyGit(action.worktree_path));
     if (destructive && !force) {
         throw new AppError("worktree_dirty", "cleanup apply refuses dirty worktree actions without --force --reason", 1, {
@@ -410,7 +438,7 @@ function applyAction(context, action, reason, force, now) {
     return { kind: action.kind, changed: false, skipped: true, reason: "invalid_action" };
 }
 function discardedRunIndex(indexJson, reason, now) {
-    const index = JSON.parse(indexJson);
+    const index = cleanupRunIndex(indexJson);
     index.schema_id = "dd-flow/flow-run@3";
     index.status = "discarded";
     index.verdict = "discarded";
@@ -420,12 +448,25 @@ function discardedRunIndex(indexJson, reason, now) {
     index.finished_at ??= now;
     return index;
 }
+function cleanupRunIndex(indexJson) {
+    try {
+        const index = JSON.parse(indexJson);
+        if (!index || typeof index !== "object" || Array.isArray(index))
+            throw new Error("RUN index must be an object");
+        return index;
+    }
+    catch (error) {
+        throw new AppError("runtime_state_invalid", "Cleanup cannot read retained RUN state", 1, { cause: String(error) });
+    }
+}
 function dirtyGit(worktreePath) {
     if (!fs.existsSync(worktreePath)) {
         return false;
     }
     const result = spawnSync("git", ["-C", worktreePath, "status", "--porcelain"], { encoding: "utf8" });
-    return result.status === 0 && result.stdout.trim().length > 0;
+    if (result.error || result.status !== 0)
+        throw new AppError("workspace_status_failed", "Cannot establish worktree status before cleanup", 1, { path: worktreePath, cause: result.error?.message ?? result.stderr });
+    return result.stdout.trim().length > 0;
 }
 function safeCleanupWorktreePath(context, projectId, worktreePath) {
     if (!fs.existsSync(worktreePath)) {