@deksden-com/dd-flow-cli 0.9.0-beta.38 → 0.9.0-beta.39

package/dist/harness-runtime/lib/managed-daemon.mjs

@@ -1,25 +1,143 @@
-import { lstat } from "node:fs/promises";
+import { lstat, readFile, readdir, mkdir } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import path from "node:path";
 import { commandJson } from "./process-json.mjs";
 import { errorRecord } from "./operation-errors.mjs";
+import { writeJsonAtomic } from "./runner-events.mjs";
 
 const leases = new Map();
 
-export function assertDaemonOwnership() {
+/** Freeze resource ownership independently of whether Subject hooks are enabled. */
+export function bindRuntimeOwner(config, env = process.env) {
+  const raw = Object.hasOwn(config, "runtime_owner") ? config.runtime_owner === null ? undefined : JSON.stringify(config.runtime_owner) : env.DD_FLOW_RUNTIME_OWNER;
+  if (raw === undefined) return config.runtime_owner = null;
+  let owner;
+  try { if (raw.length > 16_384) throw new Error(); owner = JSON.parse(raw); }
+  catch { throw Object.assign(new Error("runtime ownership descriptor is invalid"), { code: "runtime_owner_invalid" }); }
+  const fields = ["schema_id", "owner_id", "role", "project_id", "run_id", "work_id", "operation_id", "state_dir", "dd_flow_home", "dd_flow_bin", "resource_home", "adapter_executable", "budget"];
+  const text = value => typeof value === "string" && value.trim().length > 0;
+  if (!owner || typeof owner !== "object" || Array.isArray(owner) || Object.keys(owner).some(key => !fields.includes(key))
+    || owner.schema_id !== "dd-flow/runtime-owner@1" || !text(owner.owner_id) || !text(owner.operation_id)
+    || !["subject", "worker", "merge", "judge", "probe"].includes(owner.role)
+    || ["state_dir", "dd_flow_home", "dd_flow_bin", "resource_home"].some(key => !text(owner[key]) || !path.isAbsolute(owner[key]))
+    || (owner.adapter_executable !== undefined && (!text(owner.adapter_executable) || !path.isAbsolute(owner.adapter_executable)))
+    || ["project_id", "run_id", "work_id"].some(key => owner[key] !== undefined && !text(owner[key]))
+    || (["subject", "worker", "merge"].includes(owner.role) && (!text(owner.project_id) || !text(owner.run_id)))
+    || (["worker", "merge"].includes(owner.role) && !text(owner.work_id))
+    || (["judge", "probe"].includes(owner.role) && owner.work_id !== undefined)) {
+    throw Object.assign(new Error("runtime ownership descriptor does not match its role and scope"), { code: "runtime_owner_invalid" });
+  }
+  if (owner.budget !== undefined) {
+    const budget = owner.budget, names = ["codex-desktop", "zcode-acp", "grok-acp", "antigravity-cli", "opencode-server", "droid-cli"];
+    if (!budget || typeof budget !== "object" || Array.isArray(budget) || Object.keys(budget).some(key => !["schema_id", "scope_id", "per_harness"].includes(key)) || budget.schema_id !== "dd-flow/runtime-budget@1" || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(budget.scope_id ?? "") || !budget.per_harness || typeof budget.per_harness !== "object" || Array.isArray(budget.per_harness) || Object.entries(budget.per_harness).some(([name, limit]) => !names.includes(name) || !Number.isSafeInteger(limit) || limit < 1 || limit > 1024)) throw Object.assign(new Error("runtime owner budget is invalid"), { code: "runtime_budget_invalid" });
+  }
+  config.runtime_owner = Object.fromEntries(fields.filter(key => owner[key] !== undefined).map(key => [key, owner[key]]));
+  return config.runtime_owner;
+}
+
+/** Reject rebinding before provider setup, including the already-running path. */
+export async function prepareRuntimeOwner(config, stateDir, env = process.env) {
+  const owner = bindRuntimeOwner(config, env);
+  if (owner && path.resolve(owner.state_dir) !== path.resolve(stateDir)) {
+    throw Object.assign(new Error("runtime owner belongs to another state directory"), { code: "runtime_owner_mismatch" });
+  }
+  let previous;
+  try { previous = JSON.parse(await readFile(path.join(stateDir, "daemon.json"), "utf8")); }
+  catch (error) { if (error.code === "ENOENT") return owner; throw error; }
+  const retained = bindRuntimeOwner({ runtime_owner: previous?.config?.runtime_owner ?? null }, {});
+  if (JSON.stringify(retained) !== JSON.stringify(owner)) {
+    throw Object.assign(new Error("retained daemon ownership differs; use explicit recovery instead of rebinding its sessions"), { code: "runtime_owner_mismatch" });
+  }
+  return owner;
+}
+
+export async function assertDaemonOwnership(stateDir, dispatch = {}, assertCurrent = () => {}) {
   for (const lease of leases.values()) if (lease.error) throw lease.error;
+  const state = JSON.parse(await readFile(path.join(stateDir, "daemon.json"), "utf8"));
+  const owner = bindRuntimeOwner({ runtime_owner: state.config?.runtime_owner ?? null }, {});
+  if (!owner) return;
+  const record = state.resource_process;
+  if (owner.state_dir !== stateDir || !record?.id || !record.lease_token) throw Object.assign(new Error("owned daemon has no confirmed resource binding"), { code: "process_ownership_unknown" });
+  for (;;) {
+    assertCurrent();
+    const result = await runtimeProcess(state.config, "admission", { id: record.id, "lease-token": record.lease_token, owner: owner.owner_id, "state-dir": stateDir, "daemon-id": state.daemon_id ?? state.config?.daemonId, ...dispatch });
+    assertCurrent();
+    if (result?.ok === true && result.admitted === true && result.process_id === record.id) return;
+    if (result?.ok !== true || result.reason !== "provider_capacity" || result.process_id !== record.id) throw Object.assign(new Error("productive runtime admission was not confirmed"), { code: "process_ownership_unknown" });
+    // The daemon, not its disposable socket client, owns this queue. Recheck
+    // the RUN fence and process lease on every admission attempt.
+    await new Promise(resolve => setTimeout(resolve, 250));
+  }
+}
+
+/** Snapshot terminal operations BEFORE observing native idle. A later Turn
+ * cannot be released by an older observation of the same Session. */
+export async function budgetObservationScope(stateDir, sessionId) {
+  const state = await budgetState(stateDir);
+  if (!state?.config?.runtime_owner?.budget || !sessionId) return null;
+  const daemonId = state.daemon_id ?? state.config?.daemonId, operationIds = [];
+  for (const name of await readdir(path.join(stateDir, "operations")).catch(error => { if (error.code === "ENOENT") return []; throw error; })) {
+    const directory = path.join(stateDir, "operations", name);
+    try {
+      const requested = JSON.parse(await readFile(path.join(directory, "requested.json"), "utf8"));
+      const result = JSON.parse(await readFile(path.join(directory, "result.json"), "utf8"));
+      if (requested.daemon_id === daemonId && requested.session_id === sessionId && ["completed", "failed"].includes(result.state) && ["session.prompt", "session.start", "session.resume"].includes(requested.operation)) operationIds.push(requested.operation_id);
+    } catch (error) { if (error.code !== "ENOENT") throw error; }
+  }
+  return { stateDir, state, daemonId, sessionId, operationIds };
+}
+
+export async function releaseBudgetObservation(scope, observation) {
+  if (!scope || !scope.operationIds.length || observation?.settled !== true) return;
+  const id = observation.provider_session_id ?? observation.session_id ?? observation.adapter_session_id;
+  if (id !== scope.sessionId) throw Object.assign(new Error("budget observation belongs to another Session"), { code: "session_identity_mismatch" });
+  const directory = path.join(scope.stateDir, "budget-observations");
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  const file = path.join(directory, `${randomUUID()}.json`);
+  await writeJsonAtomic(file, { daemon_id: scope.daemonId, session_id: scope.sessionId, settled: true, operation_ids: scope.operationIds, observed_at: new Date().toISOString() });
+  await releaseBudget(scope.state, { "observation-file": file });
+}
+
+export async function completeBudgetOperation(stateDir, request, result, observe) {
+  const state = await budgetState(stateDir);
+  if (!state?.config?.runtime_owner?.budget) return;
+  if (["session.create", "session.fork"].includes(request.operation)) return await releaseBudget(state, { "operation-id": request.id });
+  const scope = await budgetObservationScope(stateDir, request.params?.sessionId);
+  if (!scope?.operationIds.length) return;
+  const observation = observe ? await observe() : result;
+  await releaseBudgetObservation(scope, observation);
+}
+
+async function budgetState(stateDir) {
+  try { return JSON.parse(await readFile(path.join(stateDir, "daemon.json"), "utf8")); }
+  catch (error) { if (error.code === "ENOENT") return null; throw error; }
+}
+
+async function releaseBudget(state, options) {
+  const record = state.resource_process, owner = state.config.runtime_owner;
+  const receipt = await runtimeProcess(state.config, "release-turn", { id: record.id, "lease-token": record.lease_token, owner: owner.owner_id, "daemon-id": state.daemon_id ?? state.config?.daemonId, ...options });
+  if (receipt?.ok !== true) throw Object.assign(new Error("runtime budget release was not confirmed"), { code: "runtime_budget_release_unconfirmed" });
 }
 
 export async function runtimeProcess(config, action, options = {}) {
-  if (!config.resourceHome || !config.ddFlowHome || !config.ddFlowBin) return null;
+  const owner = config.runtime_owner;
+  const resourceHome = owner?.resource_home ?? config.resourceHome;
+  const ddFlowHome = owner?.dd_flow_home ?? config.ddFlowHome;
+  const ddFlowBin = owner?.dd_flow_bin ?? config.ddFlowBin;
+  if (!resourceHome || !ddFlowHome || !ddFlowBin) return null;
   const args = ["runtime", "process", action];
   for (const [key, value] of Object.entries(options)) if (value !== null && value !== undefined) args.push(`--${key}`, String(value));
-  return await commandJson(config.ddFlowBin, args, {
+  return await commandJson(ddFlowBin, args, {
     cwd: config.cwd,
-    env: { ...(config.env ?? {}), DD_FLOW_HOME: config.ddFlowHome, DD_FLOW_RESOURCE_HOME: config.resourceHome }
+    env: { ...(config.env ?? {}), DD_FLOW_HOME: ddFlowHome, DD_FLOW_RESOURCE_HOME: resourceHome }
   });
 }
 
 export async function registerDaemonProcess(config, input) {
-  const result = await runtimeProcess(config, "register", { ...input, "owner-pid": process.pid, "lease-ms": 300_000 });
+  const owner = bindRuntimeOwner(config);
+  const harness = ({ "codex-daemon": "codex-desktop", "zcode-daemon": "zcode-acp", "grok-daemon": "grok-acp", "agy-daemon": "antigravity-cli", "opencode-daemon": "opencode-server", "droid-daemon": "droid-cli" })[input.kind];
+  const scope = owner ? { owner: owner.owner_id, "project-id": owner.project_id, run: owner.run_id, work: owner.work_id, role: owner.role, "state-dir": owner.state_dir, "adapter-executable": owner.adapter_executable, ...(owner.budget ? { "budget-json": JSON.stringify(owner.budget), harness } : {}), ...(owner.project_id && owner.run_id || owner.budget ? { "dispatch-barrier": "run-generation@1" } : {}), operation: `${owner.operation_id}:${input.operation ?? input.kind}` } : {};
+  const result = await runtimeProcess(config, "register", { ...input, ...scope, "owner-pid": process.pid, "lease-ms": 300_000 });
   return result?.process ? { id: result.process.id, lease_token: result.process.lease_token, kind: input.kind } : null;
 }
 
@@ -98,6 +216,7 @@ export async function stopProcessGroup(child, graceMs = 1_000) {
   process.kill(target, "SIGTERM");
   await new Promise((resolve) => setTimeout(resolve, graceMs));
   if (!alive()) return;
+  if (child.exitCode != null || child.signalCode != null) return stopProcessGroup(child, graceMs);
   process.kill(target, "SIGKILL");
   // Grace controls escalation, not the OS acknowledgement budget. A caller
   // testing immediate escalation must still allow the kernel to reap children.

package/dist/harness-runtime/lib/process-json.mjs

@@ -7,7 +7,7 @@ function failure(message, code) {
 
 function reportedFailure(stdout, stderr, fallback) {
   for (const text of [stdout, stderr]) {
-    for (const line of text.trim().split(/\n/).reverse()) {
+    for (const line of [text.trim(), ...text.trim().split(/\n/).reverse()]) {
       try {
         const value = JSON.parse(line);
         const error = value?.error;

package/dist/harness-runtime/lib/session-settlement.mjs

@@ -18,11 +18,13 @@ export async function waitForSettlement({ observe, cancel, knownSessions = () =>
       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)) {
+    // The observation budget must not skip a newly discovered owned target.
+    // Attempt its cancellation once, then leave physical settlement pending.
+    for (const id of state.sessions) if (cancel && !cancelled.has(id)) {
       cancelled.add(id);
       try { await cancel(id); } catch (error) { errors.push({ phase: "cancel", session_id: id, ...errorRecord(error) }); }
     }
+    if (!cancel || performance.now() >= deadline) throw Object.assign(new Error("daemon still owns an unsettled Session tree"), { code: "tree_not_settled", details: { ...state, cleanup_errors: errors } });
     await new Promise(resolve => setTimeout(resolve, 50));
   }
 }

package/dist/schemas/run-control-receipt.schema.json

@@ -0,0 +1,99 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "dd-flow/run-control-receipt@1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_id", "ok", "request_id", "control_id", "scope", "generation", "requested_mode", "applied_mode", "state", "settled", "nodes", "unsettled_reasons", "resumability"],
+  "properties": {
+    "schema_id": { "const": "dd-flow/run-control-receipt@1" },
+    "ok": { "const": true },
+    "request_id": { "type": ["string", "null"], "minLength": 1, "maxLength": 128 },
+    "control_id": { "type": ["string", "null"], "pattern": "^CTL-[A-Za-z0-9][A-Za-z0-9._-]*$" },
+    "scope": {
+      "type": "object", "additionalProperties": false,
+      "required": ["project_id", "run_id"],
+      "properties": {
+        "project_id": { "type": "string", "minLength": 1 },
+        "run_id": { "type": "string", "pattern": "^RUN-[A-Za-z0-9][A-Za-z0-9._-]*$" }
+      }
+    },
+    "generation": { "type": "integer", "minimum": 0 },
+    "requested_mode": { "enum": [null, "pause", "stop", "resume"] },
+    "applied_mode": { "enum": [null, "pause", "stop", "resume"] },
+    "state": { "enum": ["not_requested", "pause_requested", "paused", "stop_requested", "stopped", "resuming", "running", "terminal_noop", "superseded", "recovery_required"] },
+    "settled": { "type": "boolean" },
+    "nodes": {
+      "type": "array",
+      "items": {
+        "type": "object", "additionalProperties": false,
+        "required": ["id", "role", "status", "acknowledged", "settled", "reason"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "role": { "enum": ["subject", "worker", "merge", "judge", "probe", "check", "process", "unknown"] },
+          "status": { "enum": ["pending", "unknown", "idle", "stopped", "completed"] },
+          "acknowledged": { "type": "boolean" },
+          "settled": { "type": "boolean" },
+          "reason": { "type": ["string", "null"] },
+          "receipt_path": { "type": "string", "minLength": 1 },
+          "details": { "type": "object" }
+        },
+        "allOf": [{
+          "if": { "properties": { "settled": { "const": true } } },
+          "then": { "properties": { "status": { "enum": ["idle", "stopped", "completed"] } } }
+        }]
+      }
+    },
+    "unsettled_reasons": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+    "resumability": { "enum": ["pending", "same_session", "replacement_allowed", "recovery_required", "not_applicable"] },
+    "recovery_id": { "type": ["string", "null"] },
+    "reused": { "type": "boolean" },
+    "next_cursor": { "type": "integer", "minimum": 0 },
+    "run_status": { "type": "string" },
+    "control": { "type": ["object", "null"] },
+    "operations": { "type": "array", "items": { "type": "object" } },
+    "worker": { "type": ["object", "null"] },
+    "resume_operation": { "type": ["object", "null"] },
+    "controller": { "type": "object" },
+    "operation_id": { "type": "string", "minLength": 1 },
+    "status": { "type": "string" },
+    "action": { "enum": ["pause", "stop", "resume"] },
+    "progress": {
+      "type": "array",
+      "items": { "type": "object", "additionalProperties": false, "required": ["phase", "message", "at"], "properties": { "phase": { "enum": ["start", "running", "done", "failed"] }, "message": { "type": "string" }, "at": { "type": "string" }, "detail": { "type": "object" } } }
+    },
+    "warnings": { "type": "array", "items": { "type": "object" } },
+    "response_file": { "type": "string", "minLength": 1 },
+    "response_file_error": { "type": "string" }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "state": { "not": { "enum": ["not_requested", "terminal_noop"] } } } },
+      "then": { "properties": { "control_id": { "type": "string" }, "request_id": { "type": "string" }, "requested_mode": { "type": "string" } } }
+    },
+    {
+      "if": { "properties": { "state": { "enum": ["paused", "stopped"] } } },
+      "then": { "properties": { "settled": { "const": true } } }
+    },
+    {
+      "if": { "properties": { "state": { "const": "paused" } } },
+      "then": { "properties": { "applied_mode": { "const": "pause" } } }
+    },
+    {
+      "if": { "properties": { "state": { "const": "stopped" } } },
+      "then": { "properties": { "applied_mode": { "const": "stop" } } }
+    },
+    {
+      "if": { "properties": { "settled": { "const": true } } },
+      "then": {
+        "properties": {
+          "nodes": { "items": { "properties": { "settled": { "const": true } } } },
+          "unsettled_reasons": { "maxItems": 0 }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "settled": { "const": false } } },
+      "then": { "properties": { "unsettled_reasons": { "minItems": 1 }, "resumability": { "enum": ["pending", "recovery_required", "not_applicable"] } } }
+    }
+  ]
+}

package/dist/schemas/run-control-request.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "dd-flow/run-control-request@1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_id", "request_id", "project_root", "run_id", "action"],
+  "properties": {
+    "schema_id": { "const": "dd-flow/run-control-request@1" },
+    "request_id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" },
+    "project_root": { "type": "string", "minLength": 1, "pattern": "^(?:/|[A-Za-z]:[\\\\/]|\\\\\\\\)" },
+    "run_id": { "type": "string", "pattern": "^RUN-[A-Za-z0-9][A-Za-z0-9._-]*$" },
+    "action": { "enum": ["pause", "stop", "resume"] },
+    "wait_ms": { "type": "integer", "minimum": 0, "maximum": 60000, "default": 0 },
+    "grace_ms": { "type": "integer", "minimum": 0, "maximum": 3600000, "default": 30000 },
+    "escalate": { "const": "interrupt" },
+    "force": { "type": "boolean" },
+    "from": { "type": "string", "pattern": "^CTL-[A-Za-z0-9][A-Za-z0-9._-]*$" }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "action": { "const": "pause" } } },
+      "then": { "not": { "anyOf": [{ "required": ["force"] }, { "required": ["from"] }] } }
+    },
+    {
+      "if": { "properties": { "action": { "const": "stop" } } },
+      "then": { "not": { "anyOf": [{ "required": ["grace_ms"] }, { "required": ["escalate"] }, { "required": ["from"] }] } }
+    },
+    {
+      "if": { "properties": { "action": { "const": "resume" } } },
+      "then": {
+        "required": ["from"],
+        "not": { "anyOf": [{ "required": ["grace_ms"] }, { "required": ["escalate"] }, { "required": ["force"] }] }
+      }
+    }
+  ]
+}

package/dist/services/cleanup.js

@@ -4,10 +4,10 @@ import path from "node:path";
 import { AppError } from "../shared/errors.js";
 import { parseJsonObject } from "../shared/json.js";
 import { ensureReadableFile } from "../storage/database.js";
-import { projectCheckoutRoot, resolveProjectRoot } from "../storage/paths.js";
+import { projectCheckoutRoot, resolveProjectRoot, runtimeStateJsonPath } from "../storage/paths.js";
 import { appendAudit } from "./audit.js";
 import { requireProjectByRoot } from "./projects.js";
-import { protocolRunDiagnostics, readProtocolRuntimeState, requireProtocol } from "./protocols.js";
+import { protocolRunDiagnostics, readProtocolRuntimeState, repairProtocolRuntimeState, requireProtocol } from "./protocols.js";
 import { publicSessionIdentity } from "./session-identity.js";
 const actionKinds = new Set([
     "repair_protocol_state",
@@ -25,7 +25,8 @@ export function cleanupScan(context, input) {
     const protocols = context.db.all("SELECT id, status, stage, state_path FROM protocols WHERE project_id = ? ORDER BY id ASC", [project.id]);
     for (const protocol of protocols) {
         const terminal = ["closed", "cancelled"].includes(protocol.status) || ["closed", "cancelled"].includes(protocol.stage);
-        if (!fs.existsSync(protocol.state_path)) {
+        const requiresMigration = protocol.state_path !== runtimeStateJsonPath(context.ddFlowHome, project.id, protocol.id);
+        if (!fs.existsSync(protocol.state_path) || requiresMigration) {
             pushFinding(findings, actions, "missing_protocol_runtime_state", "warning", {
                 protocol_id: protocol.id,
                 path: protocol.state_path,
@@ -43,6 +44,8 @@ export function cleanupScan(context, input) {
             }
         }
         const fullProtocol = requireProtocol(context, protocol.id, project.id);
+        if (requiresMigration)
+            continue;
         const state = readProtocolRuntimeState(context, fullProtocol).state;
         const diagnostics = protocolRunDiagnostics(context, fullProtocol, state).diagnostics;
         for (const diagnostic of diagnostics.filter((entry) => entry.code === "protocol_run_stage_mismatch")) {
@@ -283,7 +286,7 @@ function applyAction(context, action, reason, force, now) {
         const protocol = requireProtocol(context, action.protocol_id, action.project_id);
         const beforePath = protocol.state_path;
         const existed = fs.existsSync(beforePath);
-        readProtocolRuntimeState(context, protocol);
+        repairProtocolRuntimeState(context, protocol);
         return {
             kind: action.kind,
             changed: !existed || beforePath !== protocol.state_path,

package/dist/services/cli-operation-classifier.js

@@ -101,6 +101,8 @@ function isRouterNative(args) {
         return true;
     if (["engine", "version", "schema"].includes(first))
         return true;
+    if (first === "storage" && args[1] === "migrate-writer")
+        return true;
     return (first === "codex" && args[1] === "hook" && args[2] === "handle")
         || (first === "zcode" && args[1] === "event" && args[2] === "handle")
         || (first === "zcode" && args[1] === "usage" && args[2] === "ingest")
@@ -127,7 +129,7 @@ function isReadOnlyDiagnostic(family, command, action) {
     if (family === "plan")
         return command === "status";
     if (family === "run")
-        return command === "status" || command === "list";
+        return command === "status" || command === "list" || (["drive", "control"].includes(command ?? "") && action === "status");
     if (family === "lane") {
         return (command === "status" ||
             command === "waiters" ||

package/dist/services/code-checks.js

@@ -2,8 +2,10 @@ import crypto from "node:crypto";
 import { spawn, spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
+import { assertRunMutationAllowed } from "./run-recovery.js";
 import { AppError } from "../shared/errors.js";
 import { confirmManagedProcess, finishManagedProcess, heartbeatManagedProcess, managedProcessStatus, managedOwnerIsAlive, processTreeIsAlive, registerManagedProcess, reservePorts } from "./managed-processes.js";
+import { admitRuntimeCheck, runtimeBudgetForRun } from "./runtime-budget.js";
 const profileRelativePath = path.join(".memory-bank", "spec", "engineering", "code-check-profile.json");
 // Receipt reservation precedes child spawn so an interrupted CLI leaves an
 // auditable attempt. A second caller must not mistake that small handoff window
@@ -79,6 +81,7 @@ export function validateCheckDeclaration(workspaceRoot, check) {
 }
 export async function runCodeChecks(context, input) {
     reconcileUnfinishedChecks(context, input);
+    const generation = assertRunMutationAllowed(context, input.projectId, input.runId);
     for (const check of input.checks)
         validateCheckDeclaration(input.workspaceRoot, check);
     const { hash: profileHash, profile } = readCodeCheckProfile(input.workspaceRoot);
@@ -92,21 +95,35 @@ export async function runCodeChecks(context, input) {
         const startedAt = context.now();
         const inputHash = crypto.createHash("sha256").update(JSON.stringify({ gate: group.gate, command: group.command, environment: String(codeExecutionEnvironment(input.workspaceRoot).DD_FLOW_LOCAL_DATABASE_SUFFIX), required_artifacts: group.requiredArtifacts, ports: [...group.ports].sort() })).digest("hex");
         const epoch = crypto.createHash("sha256").update(`${group.gate}\0${before.fingerprint}`).digest("hex");
-        const reserved = reserveReceipt(context, { ...input, group, before, profileHash, inputHash, epoch, startedAt });
+        const reserved = reserveReceipt(context, { ...input, generation, group, before, profileHash, inputHash, epoch, startedAt });
         const { id, evidenceDir, stdoutPath, stderrPath, receiptPath, completionPath } = reserved;
         let resources = {};
         let result = { exitCode: null, error: "check did not start", aborted: true };
         try {
             fs.mkdirSync(evidenceDir, { recursive: true });
             writeReceipt(receiptPath, receiptFor({ ...reserved, resources, result, status: "running", after: before, mutationPaths: [], artifacts: [] }));
-            const managed = registerManagedProcess(context, { kind: "check", ownerPid: process.pid, ownerId: `check:${id}`, projectId: input.projectId, runId: input.runId, workId: input.workId ?? null, checkId: id, stdoutPath, stderrPath, metadata: { command: group.command } });
+            const budget = runtimeBudgetForRun(context, input.projectId, input.runId);
+            const managed = registerManagedProcess(context, { kind: "check", ownerPid: process.pid, ownerId: `check:${id}`, projectId: input.projectId, runId: input.runId, workId: input.workId ?? null, checkId: id, stdoutPath, stderrPath, metadata: { command: group.command, role: "check", budget } });
             const allocation = await reservePorts(context, { ownerId: managed.owner_id, processId: managed.id, names: group.ports });
             resources = allocation.ports;
-            input.progress?.(`check ${index + 1}/${groups.length} started: ${group.command}`);
+            try {
+                input.progress?.(`check ${index + 1}/${groups.length} preparing: ${group.command}`);
+                assertRunMutationAllowed(context, input.projectId, input.runId, generation);
+            }
+            catch (error) {
+                allocation.release();
+                finishManagedProcess(context, { id: managed.id, leaseToken: managed.lease_token, state: "failed", reason: "dispatch_fenced_before_spawn" });
+                throw error;
+            }
             const stdout = fs.openSync(stdoutPath, "a");
             const stderr = fs.openSync(stderrPath, "a");
             try {
-                result = await runCheck(group.command, input.workspaceRoot, { ...codeExecutionEnvironment(input.workspaceRoot), DD_FLOW_EVIDENCE_DIR: evidenceDir, DD_FLOW_CHECK_COMPLETION_FILE: completionPath, ...portEnvironment(resources) }, stdout, stderr, (elapsed) => input.progress?.(`check ${index + 1}/${groups.length} still running (${elapsed}s): ${group.command}`), (pid) => confirmManagedProcess(context, { id: managed.id, leaseToken: managed.lease_token, pid, processGroupId: process.platform === "win32" ? null : pid }), () => heartbeatManagedProcess(context, { id: managed.id, leaseToken: managed.lease_token }));
+                result = await runCheck(group.command, input.workspaceRoot, { ...codeExecutionEnvironment(input.workspaceRoot), DD_FLOW_EVIDENCE_DIR: evidenceDir, DD_FLOW_CHECK_COMPLETION_FILE: completionPath, ...portEnvironment(resources) }, stdout, stderr, (elapsed) => input.progress?.(`check ${index + 1}/${groups.length} still running (${elapsed}s): ${group.command}`), (pid) => {
+                    confirmManagedProcess(context, { id: managed.id, leaseToken: managed.lease_token, pid, processGroupId: process.platform === "win32" ? null : pid });
+                    assertRunMutationAllowed(context, input.projectId, input.runId, generation);
+                    if (budget)
+                        admitRuntimeCheck(context, managed.id, managed.lease_token);
+                }, () => heartbeatManagedProcess(context, { id: managed.id, leaseToken: managed.lease_token }));
             }
             finally {
                 fs.closeSync(stdout);
@@ -149,15 +166,19 @@ export async function runCodeChecks(context, input) {
  * a dead/terminal process becomes an explicit aborted receipt that can retry.
  */
 export function reconcileUnfinishedChecks(context, input) {
-    const where = input.workId ? "project_id = ? AND run_id = ? AND work_id = ? AND status = 'running'" : "project_id = ? AND run_id = ? AND status = 'running'";
+    let where = input.workId ? "project_id = ? AND run_id = ? AND work_id = ? AND status = 'running'" : "project_id = ? AND run_id = ? AND status = 'running'";
     const params = input.workId ? [input.projectId, input.runId, input.workId] : [input.projectId, input.runId];
+    if (input.receiptId) {
+        where += " AND id = ?";
+        params.push(input.receiptId);
+    }
     const pending = context.db.all(`SELECT id, receipt_path, started_at FROM check_receipts WHERE ${where}`, params);
     if (pending.length === 0)
         return [];
     const processes = managedProcessStatus(context);
     const reconciled = [];
     for (const pendingReceipt of pending) {
-        const process = processes.filter((item) => item.check_id === pendingReceipt.id).at(-1);
+        const process = processes.filter((item) => item.check_id === pendingReceipt.id && item.project_id === input.projectId && item.run_id === input.runId).at(-1);
         const receipt = readReceipt(pendingReceipt.receipt_path);
         const completion = receipt ? readCompletion(receipt.completion_path || path.join(path.dirname(pendingReceipt.receipt_path), "completion.json")) : null;
         // A stale lease after host sleep is not permission to duplicate a living
@@ -189,6 +210,7 @@ export function reconcileUnfinishedChecks(context, input) {
 function reserveReceipt(context, input) {
     context.db.exec("BEGIN IMMEDIATE");
     try {
+        assertRunMutationAllowed(context, input.projectId, input.runId, input.generation);
         const rows = context.db.all("SELECT id FROM check_receipts WHERE work_id IS ? AND run_id = ?", [input.workId ?? null, input.runId]);
         const ordinal = rows.reduce((max, row) => Math.max(max, Number(/\/RCP-(\d+)$/.exec(row.id)?.[1] ?? 0)), 0) + 1;
         const localId = `RCP-${String(ordinal).padStart(3, "0")}`;
@@ -321,7 +343,7 @@ function listFiles(root, current = root) { return fs.readdirSync(current, { with
 export function runCheck(command, cwd, environment, stdout, stderr, heartbeat, onSpawn, renewLease) {
     return new Promise((resolve) => {
         const started = Date.now();
-        const child = spawn("/bin/sh", ["-lc", checkShellScript()], { cwd, env: { ...environment, DD_FLOW_CHECK_COMMAND: command }, stdio: ["ignore", stdout, stderr], detached: process.platform !== "win32" });
+        const child = spawn("/bin/sh", ["-c", checkShellScript()], { cwd, env: { ...environment, DD_FLOW_CHECK_COMMAND: command }, stdio: ["pipe", stdout, stderr], detached: process.platform !== "win32" });
         let error = null;
         let stopping = false;
         let progress;
@@ -343,6 +365,7 @@ export function runCheck(command, cwd, environment, stdout, stderr, heartbeat, o
         // Register handlers before checking pid or calling persistence callbacks.
         // Failure is not completion until the spawned process has actually closed.
         child.once("error", (value) => { error = value.message; });
+        child.stdin.on("error", stop);
         child.once("close", (exitCode, signal) => {
             if (progress)
                 clearInterval(progress);
@@ -363,6 +386,7 @@ export function runCheck(command, cwd, environment, stdout, stderr, heartbeat, o
             stop(cause);
             return;
         }
+        child.stdin.end("admitted\n");
         progress = setInterval(() => {
             try {
                 if (!renewLease()) {
@@ -379,6 +403,8 @@ export function runCheck(command, cwd, environment, stdout, stderr, heartbeat, o
 }
 function checkShellScript() {
     return [
+        // The actual command cannot run before PID ownership and admission persist.
+        'IFS= read -r admission && [ "$admission" = admitted ] || exit 125',
         'completion="${DD_FLOW_CHECK_COMPLETION_FILE:-}"',
         '/bin/sh -lc "$DD_FLOW_CHECK_COMMAND"',
         "code=$?",

package/dist/services/controller-fanout.js

@@ -0,0 +1,105 @@
+import { AppError } from "../shared/errors.js";
+import { getVnextFanoutStatus, observeVnextNativeChildren, reconcileVnextFanout, subagentCapacityKey } from "./vnext-fanout.js";
+import { getFlowRunVariables } from "./runs.js";
+import { dispatchVnextPlanReview } from "./vnext-plan-review.js";
+import { resolveExecutionPolicy } from "./execution-policy.js";
+/** The shared controller owns this former eval-only Work-graph decision. */
+export async function nextControllerFanout(context, input) {
+    const children = input.children.filter(child => child.status !== "settled_by_root");
+    const observations = { harness_id: input.harness, parent_session_id: input.sessionId, children };
+    if (children.length) {
+        const observed = observeVnextNativeChildren(context, { ...input, observations });
+        const issues = observed.issues;
+        if (issues.length)
+            throw new AppError("fanout_reconciliation_required", "Native children have unresolved lifecycle ownership", 1, { issues });
+    }
+    let fanout = getVnextFanoutStatus(context, input).orchestration;
+    if (!fanout)
+        return { kind: "none" };
+    if (children.length) {
+        const reconciled = await reconcileVnextFanout(context, { ...input, observations });
+        const issues = reconciled.issues.filter(issue => issue.code !== "child_check_in_progress");
+        if (issues.length)
+            throw new AppError("fanout_reconciliation_required", "Native child outcome requires reconciliation, not replay", 1, { issues });
+        if (children.some(child => child.status === "running" || child.status === "unknown"))
+            return { kind: "wait", reason: "native_children_unsettled" };
+        fanout = getVnextFanoutStatus(context, input).orchestration;
+    }
+    if (fanout.state === "dispatch_required") {
+        dispatchVnextPlanReview(context, input);
+        fanout = getVnextFanoutStatus(context, input).orchestration;
+        if (fanout.state === "dispatch_required" || fanout.state === "capacity_required")
+            return { kind: "wait", reason: "qualified_capacity_required" };
+    }
+    const prompt = (text) => ({ kind: "prompt", prompt: text, fingerprint: JSON.stringify({ stage: input.stage, parent: fanout.parent_work_id, works: fanout.works, text }) });
+    if (fanout.state === "coordinator_required")
+        return prompt(`Continue the current ${input.stage} Stage using its authoritative packet. Materialize only its required Work graph with real dependencies. Do not launch children, finish the Stage, or start a successor. Return after registering the graph; the runtime will dispatch its ready Work.`);
+    if (fanout.works.failed || fanout.works.cancelled)
+        return prompt(`Some ${input.stage} child Work failed or was cancelled. Inspect its recorded receipts. Choose a legal scoped repair/retry or block the Stage with the concrete reason. Do not relaunch settled siblings or infer success from a child that omitted work finish.`);
+    if (fanout.works.ready.length) {
+        const choices = fanout.works.ready.map(work => {
+            const payload = context.db.get("SELECT payload_json FROM works WHERE work_id = ?", [work.work_id])?.payload_json;
+            const override = payload ? JSON.parse(payload).execution_override : undefined;
+            return { work, resolved: resolveExecutionPolicy({ ddFlowHome: context.ddFlowHome, policy: input.policy, profiles: input.profiles, stage: input.stage, ...(override ? { work: override } : {}) }) };
+        });
+        const external = choices.filter(choice => choice.resolved.delegation.mode === "external");
+        if (external.length) {
+            const maximum = Math.min(...external.map(choice => choice.resolved.delegation.max_parallel ?? 1));
+            return { kind: "external", works: external.slice(0, maximum).map(choice => choice.work) };
+        }
+        const variables = getFlowRunVariables(context, input);
+        const capacity = variables.variables[subagentCapacityKey];
+        if (typeof capacity !== "number" || !Number.isInteger(capacity) || capacity < 1)
+            return { kind: "wait", reason: "qualified_capacity_required" };
+        const wave = choices.slice(0, capacity).map(choice => choice.work);
+        return prompt([
+            `Launch exactly ${wave.length} direct native children for the current ${input.stage} Stage; the recorded capacity is ${capacity}.`,
+            "Use this harness's native child mechanism, not external roots or forks. Wait for these children to settle; do not cancel siblings because one failed. Do not finish this Stage or start a successor in this Turn.",
+            ...wave.map(work => {
+                if (!work.work_id || !work.start_command)
+                    throw new AppError("fanout_contract_invalid", "Ready Work omits its trusted start command", 1);
+                return `Assign one leaf child Work ${work.work_id}. ${work.launch_policy === "fresh_agent_required" ? "Use empty, non-inherited context when supported; a new Session id alone does not prove empty context." : "Inherit context only through the harness's declared mechanism."}\nIts first technical action must be this exact standalone command:\n${work.start_command}\nUse only the Work packet returned by it. Complete its declared result and exact work finish command, then stop. Do not create children or start another Work. Missing facts go through the Work's failure/result contract; only the coordinator handles Stage HITL.`;
+            })
+        ].join("\n\n"));
+    }
+    if (fanout.works.running)
+        return { kind: "wait", reason: "work_receipts_pending" };
+    if (fanout.works.created)
+        throw new AppError("fanout_graph_stalled", "Created Work has no ready or running dependency path", 1);
+    return prompt(`All declared ${input.stage} child Work has settled (${fanout.works.completed} completed). Read the accepted result receipts and continue this Stage's semantic decision under its original packet. Execute an exact repair command returned by a rejected stage finish; a rejection alone does not create repair Work. Return after finish or after declaring a repair graph. Do not start a successor Stage.`);
+}
+/** Normalize provider-observed topology only; never parse assistant prose. */
+export function controllerNativeChildren(receipt, rootSessionId) {
+    const candidates = [];
+    const object = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : {};
+    const list = (value) => Array.isArray(value) ? value : [];
+    const text = (value, keys) => { for (const key of keys)
+        if (typeof value[key] === "string" && value[key])
+            return value[key]; return null; };
+    const add = (raw, source, scopedParent = null, fallback = "unknown") => {
+        const value = object(raw);
+        const id = text(value, ["provider_session_id", "session_id", "sessionId", "childSessionId", "conversation_id", "conversationId", "id", "subagentId"]);
+        const parent = text(value, ["parent_provider_session_id", "parent_session_id", "parentSessionId", "parentID", "parentId"]) ?? scopedParent;
+        if (!id || parent !== rootSessionId)
+            return;
+        const state = String(value.status ?? value.state ?? fallback).toLowerCase();
+        const status = ["completed", "complete", "done", "idle", "success", "succeeded"].includes(state) ? "completed" : state === "settled_by_root" ? "settled_by_root" : ["failed", "error"].includes(state) ? "failed" : ["cancelled", "canceled"].includes(state) ? "cancelled" : ["running", "active", "pending"].includes(state) ? "running" : fallback;
+        candidates.push({ session_id: id, parent_session_id: parent, status, source });
+    };
+    for (const value of list(receipt.descendants))
+        add(value, "adapter.descendants");
+    for (const value of list(receipt.children))
+        add(value, "opencode.session.children");
+    const subagents = object(object(receipt.evidence).subagents ?? receipt.subagents);
+    for (const value of list(subagents.running))
+        add(value, "zcode/session/subagents", rootSessionId, "running");
+    for (const value of [...list(subagents.completed), ...list(object(subagents.ended).items)])
+        add(value, "zcode/session/subagents", rootSessionId, "completed");
+    const unique = new Map();
+    for (const child of candidates) {
+        const previous = unique.get(child.session_id);
+        if (!previous || previous.status === "unknown" || previous.status === "running" && child.status !== "running")
+            unique.set(child.session_id, child);
+    }
+    return [...unique.values()].sort((left, right) => left.session_id.localeCompare(right.session_id));
+}

package/dist/services/engines.js

@@ -276,6 +276,8 @@ function runIdForArgs(args) {
     const [family, command, ...rest] = args;
     const parsed = parseLightArgs(rest);
     if (family === "run" && command !== "start" && command !== "list") {
+        if (["drive", "control", "recovery", "capacity"].includes(command ?? ""))
+            return option(parsed, "run");
         if (command === "flags")
             return positional(parsed, 1);
         return positional(parsed, 0);