@deksden-com/dd-flow-cli 0.9.0-beta.22 → 0.9.0-beta.24

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,28 @@
+import { errorRecord } from "./operation-errors.mjs";
+
+/** Diagnostic failure never prevents cancellation of already owned Sessions.
+ * Only a fresh successful observation can establish settlement. */
+export async function waitForSettlement({ observe, cancel, knownSessions = () => [], timeoutMs = 5_000 }) {
+  const deadline = performance.now() + timeoutMs;
+  const cancelled = new Set(), errors = [];
+  if (cancel) for (const id of knownSessions()) {
+    cancelled.add(id);
+    try { await cancel(id); } catch (error) { errors.push({ phase: "cancel", session_id: id, ...errorRecord(error) }); }
+  }
+  for (;;) {
+    let state;
+    try { state = await observe(); }
+    catch (error) {
+      if (!cancel) throw error;
+      errors.push({ phase: "observe", ...errorRecord(error) });
+      state = { sessions: knownSessions(), active: true, observation_error: errorRecord(error) };
+    }
+    if (!state.active && state.sessions.length === 0) return { ...state, cleanup_errors: errors };
+    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/code-checks.js

@@ -125,7 +125,7 @@ export async function runCodeChecks(context, input) {
         }
         const after = workspaceState(input.workspaceRoot, [input.runHome]);
         const mutationPaths = changedPaths(before.files, after.files);
-        const artifacts = collectRequiredArtifacts(evidenceDir, group.requiredArtifacts);
+        const artifacts = collectCheckArtifacts(evidenceDir, group.requiredArtifacts);
         if (fs.existsSync(stderrPath)) {
             if (!artifacts.complete)
                 fs.appendFileSync(stderrPath, `\nmissing required evidence artifacts: ${artifacts.missing.join(", ")}\n`);
@@ -170,7 +170,7 @@ export function reconcileUnfinishedChecks(context, input) {
             throw new AppError("check_in_progress", "A previous check invocation is still initializing", 1, { check_receipt_id: pendingReceipt.id, initializing: true });
         }
         const after = workspaceState(input.workspaceRoot, input.runHome ? [input.runHome] : []);
-        const artifacts = receipt ? collectRequiredArtifacts(path.join(path.dirname(receipt.completion_path || pendingReceipt.receipt_path), "artifacts"), receipt.required_artifacts ?? []) : { complete: false, missing: [], items: [] };
+        const artifacts = receipt ? collectCheckArtifacts(path.join(path.dirname(receipt.completion_path || pendingReceipt.receipt_path), "artifacts"), receipt.required_artifacts ?? []) : { complete: false, missing: [], items: [] };
         const workspaceUnchanged = receipt?.before_fingerprint === after.fingerprint;
         const status = completion === null ? "aborted" : completion.exit_code === 0 && workspaceUnchanged && artifacts.complete ? "passed" : "failed";
         const exitCode = completion?.exit_code ?? null;
@@ -292,16 +292,30 @@ function readReceiptResources(file) { try {
 catch {
     return { ports: {} };
 } }
-function collectRequiredArtifacts(root, required) { const missing = []; const items = []; for (const relative of required) {
-    if (path.isAbsolute(relative) || relative.split(/[\\/]/).includes(".."))
-        throw new AppError("invalid_evidence_path", "Required evidence paths must be relative to DD_FLOW_EVIDENCE_DIR", 2, { path: relative });
-    const file = path.join(root, relative);
-    if (!fs.existsSync(file) || !fs.statSync(file).isFile()) {
-        missing.push(relative);
-        continue;
+function collectCheckArtifacts(root, required) {
+    for (const relative of required) {
+        if (path.isAbsolute(relative) || relative.split(/[\\/]/).includes(".."))
+            throw new AppError("invalid_evidence_path", "Required evidence paths must be relative to DD_FLOW_EVIDENCE_DIR", 2, { path: relative });
     }
-    items.push({ path: relative, sha256: crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex") });
-} return { complete: missing.length === 0, missing, items }; }
+    // Required paths are minimum obligations; retain all explicit check evidence.
+    // Never follow symlinks, including a replaced evidence root.
+    const items = [];
+    const visit = (directory) => {
+        for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+            const file = path.join(directory, entry.name);
+            if (entry.isDirectory())
+                visit(file);
+            else if (entry.isFile())
+                items.push({ path: path.relative(root, file), sha256: crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex") });
+        }
+    };
+    if (fs.existsSync(root) && fs.lstatSync(root).isDirectory())
+        visit(root);
+    items.sort((a, b) => a.path.localeCompare(b.path));
+    const retained = new Set(items.map((item) => item.path));
+    const missing = required.filter((relative) => !retained.has(path.normalize(relative)));
+    return { complete: missing.length === 0, missing, items };
+}
 function listFiles(root, current = root) { return fs.readdirSync(current, { withFileTypes: true }).flatMap((entry) => { if ([".git", "node_modules"].includes(entry.name))
     return []; const absolute = path.join(current, entry.name); return entry.isDirectory() ? listFiles(root, absolute) : [path.relative(root, absolute)]; }).sort(); }
 export function runCheck(command, cwd, environment, stdout, stderr, heartbeat, onSpawn, renewLease) {

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/runs.js

@@ -189,7 +189,8 @@ function snapshotVnextExecutionProfile(projectRoot) {
             merge_delivery: profile.merge_delivery,
             merge_cleanup: profile.merge_cleanup,
             stop_target: profile.stop_target,
-            code_bootstrap: profile.code_bootstrap
+            code_bootstrap: profile.code_bootstrap,
+            ...(profile.execution ? { execution: profile.execution } : {})
         }
     };
 }

package/dist/services/stage-context.js

@@ -76,8 +76,8 @@ export function renderExternalStageContext(input) {
     ].join("\n");
 }
 function validateContext(value, expectedStage) {
-    if (value.schema_id !== "dd-eval/stage-context@1")
-        throw new AppError("validation", "Stage context must use dd-eval/stage-context@1", 2);
+    if (value.schema_id !== "dd-flow/stage-context@1" && value.schema_id !== "dd-eval/stage-context@1")
+        throw new AppError("validation", "Stage context must use dd-flow/stage-context@1", 2);
     if (value.stage !== expectedStage)
         throw new AppError("validation", "Stage context does not match --stage", 2, { expected_stage: expectedStage, context_stage: value.stage });
     if (!value.objective?.trim())

package/dist/services/vnext-execution-profile.js

@@ -13,7 +13,7 @@ export function loadVnextExecutionProfile(projectRoot) {
         throw new AppError("execution_profile_missing", "vNext flow requires .memory-bank/dd-flow/project-execution.json", 1, { file, cause: String(error) });
     }
     const profile = value;
-    if (profile.schema_id !== "dd-flow/project-execution@2"
+    if ((profile.schema_id !== "dd-flow/project-execution@2" && profile.schema_id !== "dd-flow/project-execution@3")
         || (profile.stage_session_mode !== undefined && profile.stage_session_mode !== "same_session" && profile.stage_session_mode !== "new_session")
         || !["auto", "off", "standard", "deep"].includes(String(profile.plan_review_mode))
         || (profile.code_review_mode !== undefined && !["auto", "off", "standard", "deep"].includes(String(profile.code_review_mode)))
@@ -22,9 +22,44 @@ export function loadVnextExecutionProfile(projectRoot) {
         || !["retain", "delete_after_success"].includes(String(profile.merge_cleanup?.source))
         || !["code_completed", "code_review_completed", "merge_completed"].includes(String(profile.stop_target))
         || !profile.code_bootstrap || typeof profile.code_bootstrap.command !== "string" || !profile.code_bootstrap.command.trim()
-        || typeof profile.code_bootstrap.policy_ref !== "string" || !profile.code_bootstrap.policy_ref.trim()) {
-        throw new AppError("execution_profile_invalid", "Project execution profile does not match dd-flow/project-execution@2", 1, { file });
+        || typeof profile.code_bootstrap.policy_ref !== "string" || !profile.code_bootstrap.policy_ref.trim()
+        || !validRouting(profile.execution, profile.schema_id === "dd-flow/project-execution@3")) {
+        throw new AppError("execution_profile_invalid", "Project execution profile does not match its supported dd-flow schema", 1, { file });
     }
     return { ...profile, stage_session_mode: profile.stage_session_mode ?? "same_session", code_review_mode: profile.code_review_mode ?? "off" };
 }
 export function executionProfilePath(projectRoot) { return path.join(projectRoot, relativePath); }
+function validRouting(value, required) {
+    if (value === undefined)
+        return !required;
+    if (!object(value) || !profileId(value.agent_profile_id) || !override(value, true))
+        return false;
+    if (value.stage_overrides !== undefined) {
+        if (!object(value.stage_overrides))
+            return false;
+        for (const [stage, item] of Object.entries(value.stage_overrides))
+            if (!stage.trim() || !object(item) || !override(item, false))
+                return false;
+    }
+    return true;
+}
+function override(value, root) {
+    const allowed = root ? new Set(["agent_profile_id", "delegation", "stage_overrides"]) : new Set(["agent_profile_id", "delegation"]);
+    if (Object.keys(value).some(key => !allowed.has(key)))
+        return false;
+    if (!root && value.agent_profile_id === undefined && value.delegation === undefined)
+        return false;
+    if (value.agent_profile_id !== undefined && !profileId(value.agent_profile_id))
+        return false;
+    if (value.delegation === undefined)
+        return true;
+    if (!object(value.delegation) || (value.delegation.mode !== "native" && value.delegation.mode !== "external"))
+        return false;
+    if (value.delegation.agent_profile_id !== undefined && !profileId(value.delegation.agent_profile_id))
+        return false;
+    if (value.delegation.max_parallel !== undefined && (!Number.isInteger(value.delegation.max_parallel) || Number(value.delegation.max_parallel) < 1))
+        return false;
+    return value.delegation.mode !== "native" || value.delegation.max_parallel === undefined;
+}
+function profileId(value) { return typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(value); }
+function object(value) { return Boolean(value) && typeof value === "object" && !Array.isArray(value); }