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

package/dist/cli/run-cli.js

@@ -1,6 +1,11 @@
 import fs from "node:fs";
 import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { quote } from "shell-quote";
+import { observeLifecycleCommand } from "../services/lifecycle-invocations.js";
+import { assertLifecycleInvocationCurrent, awaitLifecycleInvocation, issueLifecycleInvocation, lifecycleInvocationScope, settleLifecycleInvocation, settleLifecycleRejection } from "../services/lifecycle-invocations.js";
 import { createContext, createRouterContext } from "../runtime/context.js";
+import { migrateStoreWriter } from "../storage/writer-migration.js";
 import { helpForArgs } from "./help.js";
 import { AppError, isAppError } from "../shared/errors.js";
 import { writeJson } from "../shared/json.js";
@@ -10,7 +15,7 @@ import { blockPlanItem, completePlanItem, getPlanStatus, skipPlanItem, startPlan
 import { cancelMergeQueueJob, claimNextMergeJob, claimMergeJob, claimMergeBundle, completeMergeBundle, completeMergeJob, failMergeBundle, failMergeJob, getMergeBundleStatus, getMergeQueueStatus, noteMergeJob, waitNextMergeJob } from "../services/merge-queue.js";
 import { getMergeWorkerStatus, oneShotMergeClaim, startMergeWorker, stopProjectMergeWorker } from "../services/merge-worker.js";
 import { cleanupApply, cleanupScan } from "../services/cleanup.js";
-import { getCodexHomeStatus, getCodexHooksStatus, handleCodexHook, handleAgyEvent, handleGrokEvent, handleOpenCodeEvent, handleZcodeEvent, isolatedDdFlowHomeFromHookStdin, claimBootstrapHookEvent, findRecentMatchingHookEvent, stageStartMatchKey, initCodexHome, installCodexHooks, planCodexHome, printCodexHomeEnv, printCodexHooks, removeCodexHome, removeCodexHooks } from "../services/hooks.js";
+import { getCodexHomeStatus, getCodexHooksStatus, handleCodexHook, handleAgyEvent, handleDroidEvent, handleGrokEvent, handleOpenCodeEvent, handleZcodeHook, handleZcodeEvent, isolatedDdFlowHomeFromHookStdin, claimBootstrapHookEvent, findRecentMatchingHookEvent, stageStartMatchKey, initCodexHome, installCodexHooks, planCodexHome, printCodexHomeEnv, printCodexHooks, removeCodexHome, removeCodexHooks } from "../services/hooks.js";
 import { bootstrapWorktree, closeWorktree, createWorktreeRecord, getWorktreeStatus, planWorktree } from "../services/worktrees.js";
 import { acquireLaneLock, cancelLaneWaiter, checkLaneWorkspace, getLaneWaiters, getLaneStatus, heartbeatLaneLock, releaseLaneLock, setLaneWorkspace, waitAcquireLaneLock, waitForLaneLock } from "../services/lanes.js";
 import { getProjectConfigStatus, setProjectConfigValue } from "../services/config.js";
@@ -26,7 +31,7 @@ import { attachFlowRunStage, completeFlowRun, completeFlowRunStage, getFlowRunSe
 import { previewNextEntityId } from "../services/ids.js";
 import { validateSchema } from "../services/schema-validation.js";
 import { preflightMemoryPermissions } from "../services/memory-permissions.js";
-import { ingestAgyUsage, ingestGrokUsage, ingestOpenCodeUsage, ingestZcodeUsage } from "../services/usage.js";
+import { ingestDroidUsage, ingestAgyUsage, ingestGrokUsage, ingestOpenCodeUsage, ingestZcodeUsage } from "../services/usage.js";
 import { applyMigration, assessMigrationImpact, assertUpgradeRunStorageReady, planMigration, verifyMigrationReport } from "../services/migrations.js";
 import { publishProjectSummary } from "../services/project-summary.js";
 import { requireProjectByRoot } from "../services/projects.js";
@@ -39,18 +44,30 @@ import { finishVnextPlan, isVnextPlanRun, startVnextPlan } from "../services/vne
 import { dispatchVnextPlanReview, finishVnextPlanReview, isVnextPlanReviewRun, recordVnextPlanReviewCapacity, startVnextPlanReview } from "../services/vnext-plan-review.js";
 import { addVnextCodeRepair, finishVnextCode, startVnextCode } from "../services/vnext-code.js";
 import { addVnextCodeReviewRepair, finishVnextCodeReview, isVnextCodeReviewRun, startVnextCodeReview } from "../services/vnext-code-review.js";
-import { applyVnextMerge, finishVnextMerge, getVnextMergeRequest, isVnextMergeRun, routeVnextMergeRequest, startVnextMerge } from "../services/vnext-merge.js";
+import { applyVnextMerge, finishVnextMerge, getVnextMergeRequest, isVnextMergeRun, repairVnextMerge, routeVnextMergeRequest, startVnextMerge } from "../services/vnext-merge.js";
 import { mergeServerStatus, serveMergeRequests, stopMergeServer } from "../services/merge-server.js";
-import { getVnextFanoutStatus } from "../services/vnext-fanout.js";
+import { getVnextFanoutStatus, observeVnextNativeChildren, reconcileVnextFanout } from "../services/vnext-fanout.js";
 import { pauseStageForUser, resumeStageAfterUser } from "../services/stage-pause.js";
 import { blockStageForRuntime, unblockStageAfterRuntimeRepair } from "../services/stage-blocker.js";
 import { classifyCliOperation, requiresExplicitUpgradeAuthorization } from "../services/cli-operation-classifier.js";
 import { renderWorkerPrompt } from "../services/prompts.js";
 import { finishStage, startStage } from "../services/stage-lifecycle.js";
-import { addWorkBatch, cancelWork, deleteWork, failWork, finishWork, listWorks, mutateWorkDeps, retryWork, showWork, startWork } from "../services/work-registry.js";
+import { addWorkBatch, assertStageLifecycleOwner, assertWorkLifecycleOwner, cancelWork, deleteWork, failWork, finishWork, listWorks, mutateWorkDeps, retryWork, showWork, startWork } from "../services/work-registry.js";
+import { launchExternalWork } from "../services/external-work-launch.js";
 import { createEvalBootstrapSnapshot, createEvalRunSnapshot, prepareVnextSpecifyRun, restoreEvalBootstrapSnapshot, restoreEvalRunSnapshot } from "../services/eval-snapshots.js";
+import { forkRunFromSnapshot } from "../services/run-fork.js";
+import { acceptRunRecovery, assertRunMutationAllowed, beginRunRecovery, inspectRunRecovery, recordRecoveryCapture, recoveryGuard, resumeRunRecovery, sealRunRecovery } from "../services/run-recovery.js";
+import { recoveryRuntimeAdmission } from "../services/run-recovery-runtime.js";
 import { loadExternalStageContext } from "../services/stage-context.js";
-import { confirmManagedProcess, finishManagedProcess, heartbeatManagedProcess, managedProcessStatus, reconcileExpiredManagedProcesses, registerManagedProcess } from "../services/managed-processes.js";
+import { stopManagedProcess, confirmManagedProcess, finishManagedProcess, heartbeatManagedProcess, managedProcessRuntimeHome, managedProcessStatus, processIsAlive, reconcileExpiredManagedProcesses, registerManagedProcess } from "../services/managed-processes.js";
+import { fenceRuntimeBudget, runtimeBudgetStatus, admitRuntimeCheck, parseRuntimeBudget, reserveProviderTurn, releaseProviderTurns } from "../services/runtime-budget.js";
+import { stopRuntimeScope } from "../services/runtime-scope-stop.js";
+import { launchRuntimeScopeControl, launchRuntimeScopeResume, reconcileRuntimeScopeControl, serveRuntimeScopeControl } from "../services/runtime-scope-worker.js";
+import { launchRunController, resumeRunController, serveRunController, runControllerStatus, answerRunController, supplyRunControllerContext } from "../services/run-controller.js";
+import { controllerHitlAdmission } from "../services/run-controller-adapter.js";
+import { controlLifecycleReply, runControlStatus } from "../services/run-control.js";
+import { reconcileRunControl, requestRunControl, serveRunControl } from "../services/run-control-worker.js";
+import { startRuntimeService } from "../services/runtime-service.js";
 const defaultIo = {
     stdout: process.stdout,
     stderr: process.stderr,
@@ -58,9 +75,20 @@ const defaultIo = {
 };
 const flagValue = "__dd_flow_flag__";
 export async function runCli(args, io = defaultIo, env = process.env) {
-    const output = parseOutputOptions(args);
+    let output;
+    try {
+        output = parseOutputOptions(args);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        writeJson(io.stderr, { ok: false, error: { code: "usage", message } });
+        return 2;
+    }
     const progress = progressForCommand(output.args);
     let heartbeat;
+    let invocationSettlement;
+    let settleHook;
+    let diagnosticHome;
     try {
         if (output.args.length === 1 && output.args[0] === "--version") {
             const payload = getCliVersionReport();
@@ -75,6 +103,16 @@ export async function runCli(args, io = defaultIo, env = process.env) {
             io.stdout.write(`${help}\n`);
             return 0;
         }
+        assertSingletonOptions(output.args);
+        if (output.args[0] === "run" && ["drive", "control"].includes(output.args[1] ?? "")) {
+            const controlArgs = parseArgs(output.args.slice(2));
+            requiredOption(controlArgs, "run");
+            requiredOption(controlArgs, "project-root");
+        }
+        if (io.stdin?.isTTY && ["work", "stage"].includes(output.args[0] ?? "") && output.args[1] === "finish"
+            && hasOption(parseArgs(output.args.slice(2)), "result-stdin")) {
+            throw new AppError("usage", "--result-stdin requires non-interactive input. Pipe or redirect the complete JSON into this command, or use --result-file; interactive terminals can truncate long JSON and wait indefinitely for EOF.", 2);
+        }
         const classification = classifyCliOperation(output.args, env);
         if (requiresExplicitUpgradeAuthorization(output.args) && classification.mode !== "mb_upgrade") {
             throw new AppError("upgrade_authorization_required", "This mb-upgrade command requires the explicit mb-upgrade authorization marker and allowlisted target context", 1, {
@@ -94,14 +132,54 @@ export async function runCli(args, io = defaultIo, env = process.env) {
         if (routed?.routed && !routed.inProcess) {
             if (heartbeat)
                 clearInterval(heartbeat);
-            emitHumanProgress(io, output, progress, "done");
+            emitHumanProgress(io, output, progress, routed.exitCode === 0 ? "done" : "failed");
+            if (output.progressJsonl && routed.exitCode !== 0)
+                writeProgressJsonl(io, "failed", "Routed engine failed", { exit_code: routed.exitCode });
             return routed.exitCode;
         }
         const dispatchContext = routed?.inProcess
             ? createContext({ ...env, DD_FLOW_ENGINE_MODE: "1", DD_FLOW_ENGINE_HOME: "in-process", DD_FLOW_ROUTED_FROM: getCliVersionReport().cli.version }, databaseModeForCommand(output.args, classification))
-            : createContext(env, databaseModeForCommand(output.args, classification));
+            : createContext({ ...env }, databaseModeForCommand(output.args, classification));
+        diagnosticHome = dispatchContext.ddFlowHome;
         preflightCliCompatibility(dispatchContext, output.args, env, scopeProjectRoot);
-        const result = await dispatch(output.args, dispatchContext, io, scopeProjectRoot, classification, output);
+        dispatchContext.env.DD_FLOW_INVOCATION_READONLY = classification.mode === "read_only_diagnostics" ? "1" : undefined;
+        let dispatchArgs = output.args;
+        settleHook = observeLifecycleCommand(dispatchContext, quote(["dd-flow", ...dispatchArgs]));
+        let retainedOutcome;
+        const invocationId = optionalOption(parseArgs(output.args.slice(2)), "invocation-id");
+        if (invocationId) {
+            const command = quote(["dd-flow", ...output.args]);
+            const admission = await awaitLifecycleInvocation(dispatchContext, { id: invocationId, command,
+                assertCurrent: scope => assertLifecycleInvocationCurrent(dispatchContext, scope, command) });
+            if (admission.replay) {
+                retainedOutcome = admission.outcome;
+                settleHook = undefined;
+                delete dispatchContext.observeLifecycleHook;
+            }
+            else {
+                invocationSettlement = { context: dispatchContext, id: invocationId };
+                dispatchArgs = [...output.args, "--hook-event-id", admission.eventKey];
+                dispatchContext.env.DD_FLOW_INVOCATION_SCOPE = JSON.stringify(lifecycleInvocationScope(dispatchContext, invocationId));
+                dispatchContext.env.DD_FLOW_CURRENT_INVOCATION = invocationId;
+            }
+        }
+        if (retainedOutcome?.error) {
+            const error = retainedOutcome.error;
+            throw new AppError(error.code, error.message, error.exitCode, error.details);
+        }
+        if (!retainedOutcome)
+            settleHook = observeLifecycleCommand(dispatchContext, quote(["dd-flow", ...dispatchArgs]));
+        const result = retainedOutcome ? retainedOutcome.result : await dispatch(dispatchArgs, dispatchContext, io, scopeProjectRoot, classification, output);
+        const completedHook = settleHook;
+        settleHook = undefined;
+        completedHook?.({ result });
+        if (invocationSettlement) {
+            const completed = invocationSettlement;
+            invocationSettlement = undefined;
+            // A failure to persist an already completed result is an unknown reply,
+            // not a failed operation eligible for a new productive retry.
+            settleLifecycleInvocation(completed.context, completed.id, { result });
+        }
         const refreshWarnings = refreshDashboardsAfterMutation(dispatchContext, output.args, result, scopeProjectRoot);
         const resultWithWarnings = addWarnings(result, refreshWarnings);
         if (heartbeat)
@@ -117,9 +195,41 @@ export async function runCli(args, io = defaultIo, env = process.env) {
             io.stdout.write(renderHumanResult(output.args, payload));
         return completedCommandExitCode(payload);
     }
-    catch (error) {
+    catch (caught) {
+        const error = isAppError(caught) ? caught : new AppError("unexpected", caught instanceof Error ? caught.message : String(caught), 1, { effect: "unknown", cause: { code: caught?.code ?? null, sqlite_extended_code: caught?.errcode ?? null } });
+        if (diagnosticHome && (!isAppError(caught) || error.code === "storage_write_failed")) {
+            try {
+                const directory = path.join(diagnosticHome, "diagnostics", "cli");
+                fs.mkdirSync(directory, { recursive: true });
+                const artifact = path.join(directory, `${randomUUID()}.json`);
+                fs.writeFileSync(artifact, JSON.stringify({ code: error.code, message: error.message, details: error.details, stack: caught instanceof Error ? caught.stack : null }), { flag: "wx", mode: 0o600 });
+                error.details.diagnostic_artifact = artifact;
+            }
+            catch (secondary) {
+                io.stderr.write(`CLI diagnostic persistence failed: ${String(secondary)}\n`);
+            }
+        }
         if (heartbeat)
             clearInterval(heartbeat);
+        if (invocationSettlement && error.details.effect !== "committed") {
+            try {
+                if (isAppError(error))
+                    settleLifecycleRejection(invocationSettlement.context, invocationSettlement.id, { code: error.code, message: error.message, exitCode: error.exitCode, details: error.details });
+                else
+                    settleLifecycleInvocation(invocationSettlement.context, invocationSettlement.id, { error: { code: "unexpected", message: String(error), exitCode: 1, details: {} } });
+            }
+            catch (persistenceError) {
+                io.stderr.write(`Invocation settlement persistence failed: ${String(persistenceError)}\n`);
+            }
+        }
+        if (settleHook) {
+            try {
+                settleHook({ error: isAppError(error) ? error : { code: "unexpected", message: String(error), details: {} } });
+            }
+            catch (persistence) {
+                io.stderr.write(`${JSON.stringify({ primary: String(error), lifecycle_persistence_error: String(persistence) })}\n`);
+            }
+        }
         const payload = isAppError(error)
             ? { ok: false, error: { code: error.code, message: error.message, details: error.details } }
             : { ok: false, error: { code: "unexpected", message: String(error) } };
@@ -127,7 +237,13 @@ export async function runCli(args, io = defaultIo, env = process.env) {
         if (output.progressJsonl)
             writeProgressJsonl(io, "failed", payload.error.message, { code: payload.error.code });
         const errorPayload = attachProgress(payload, progress, output);
-        const visible = writeResponseFile(errorPayload, output);
+        let visible = errorPayload;
+        try {
+            visible = writeResponseFile(errorPayload, output);
+        }
+        catch (publication) {
+            error.details.response_publication_error = { code: publication?.code ?? "response_publication_failed", message: publication instanceof Error ? publication.message : String(publication) };
+        }
         if (output.json && output.progressJsonl)
             writeJson(io.stdout, errorPayload);
         else if (output.json)
@@ -152,6 +268,7 @@ function resolveProjectRootBeforeRouting(args, env) {
 function databaseModeForCommand(args, classification) {
     const [family, command] = args;
     if (family === "engine" ||
+        family === "storage" && command === "migrate-writer" ||
         family === "version" ||
         family === "schema" ||
         family === "canon" && command === "resolve" ||
@@ -503,6 +620,20 @@ function shortSha(value) {
 async function dispatch(args, context, io, scopeProjectRoot = null, classification = classifyCliOperation(args, context.env), output = parseOutputOptions(args)) {
     const [family, command, ...rest] = args;
     const parsed = parseArgs(rest);
+    if (family === "zcode" && command === "invocation" && parsed.positional[0] === "prepare") {
+        const payload = JSON.parse(await readStdin(io.stdin));
+        if (typeof payload.command !== "string" || !payload.scope || typeof payload.scope !== "object")
+            throw new AppError("usage", "Expected command and managed scope on stdin", 2);
+        assertLifecycleInvocationCurrent(context, payload.scope, payload.command);
+        return { ok: true, ...issueLifecycleInvocation(context, payload.command, payload.scope) };
+    }
+    if (family === "storage" && command === "migrate-writer") {
+        if (parsed.positional.length || [...parsed.options.keys()].some(key => !["database", "backup", "offline"].includes(key)) || [...parsed.options.values()].some(values => values.length !== 1))
+            throw new AppError("usage", "Usage: dd-flow storage migrate-writer --database ABSOLUTE_DB --backup NEW_ABSOLUTE_FILE --offline", 2);
+        if (parsed.options.get("offline")?.[0] !== flagValue)
+            throw new AppError("usage", "Writer migration requires --offline after draining all local and external runtime owners", 2);
+        return { ok: true, ...migrateStoreWriter(requiredOption(parsed, "database"), requiredOption(parsed, "backup")) };
+    }
     if (family === "engine") {
         return dispatchEngine(context, command, parsed, classification);
     }
@@ -517,7 +648,7 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
         return getCliVersionReport();
     }
     if (family === "runtime") {
-        return await dispatchRuntime(context, command, parsed);
+        return await dispatchRuntime(context, command, parsed, commandProgress(io, output));
     }
     if (family === "canon") {
         return dispatchCanon(context, command, parsed);
@@ -660,12 +791,19 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
         const projectRoot = requiredScopeProjectRoot(scopeProjectRoot, "stage fanout");
         if (action === "status")
             return getVnextFanoutStatus(context, { projectRoot, runId, stage });
+        if (action === "reconcile")
+            return reconcileVnextFanout(context, { projectRoot, runId, stage, observations: JSON.parse(fs.readFileSync(requiredOption(parsed, "observations-file"), "utf8")) });
         if (action === "dispatch") {
             if (stage === "plan-review")
                 return dispatchVnextPlanReview(context, { projectRoot, runId });
             return getVnextFanoutStatus(context, { projectRoot, runId, stage });
         }
-        throw new AppError("usage", "Use: dd-flow stage fanout <status|dispatch> <RUN> --stage <stage> --project-root <path>", 2);
+        throw new AppError("usage", "Use: dd-flow stage fanout <status|dispatch|reconcile> <RUN> --stage <stage> --project-root <path>; reconcile requires --observations-file <native-observations.json>", 2);
+    }
+    if (family === "stage" && command === "native") {
+        if (requiredPosition(parsed, 0, "native action") !== "observe")
+            throw new AppError("usage", "Use: dd-flow stage native observe <RUN> --stage <stage> --observations-file <native-observations.json> --project-root <path>", 2);
+        return observeVnextNativeChildren(context, { projectRoot: requiredScopeProjectRoot(scopeProjectRoot, "stage native observe"), runId: requiredPosition(parsed, 1, "run-id"), stage: requiredOption(parsed, "stage"), observations: JSON.parse(fs.readFileSync(requiredOption(parsed, "observations-file"), "utf8")) });
     }
     if (family === "run" && command === "capacity") {
         if (requiredPosition(parsed, 0, "capacity action") !== "record")
@@ -752,21 +890,34 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
     }
     if (family === "work" && command === "delete")
         return deleteWork(context, requiredPosition(parsed, 0, "work-id"));
+    if (family === "work" && command === "launch")
+        return await launchExternalWork(context, { workId: requiredPosition(parsed, 0, "work-id"), ...(optionalOption(parsed, "stage") ? { stage: optionalOption(parsed, "stage") } : {}), progress: commandProgress(io, output) });
     if (family === "work" && command === "start") {
         const hookEventId = optionalOption(parsed, "hook-event-id");
+        const recoveryId = optionalOption(parsed, "recovery-id");
         const projectRoot = requiredScopeProjectRoot(scopeProjectRoot, "work start");
-        return startWork(context, requiredPosition(parsed, 0, "work-id"), { ...(hookEventId ? { hookEventId } : {}), projectRoot });
+        return startWork(context, requiredPosition(parsed, 0, "work-id"), { ...(hookEventId ? { hookEventId } : {}), ...(recoveryId ? { recoveryId } : {}), projectRoot });
     }
     if (family === "work" && command === "finish") {
         const resultFile = optionalOption(parsed, "result-file");
         const resultStdin = hasOption(parsed, "result-stdin");
         if (Boolean(resultFile) === resultStdin)
             throw new AppError("usage", "work finish requires exactly one of --result-file or --result-stdin", 2);
+        const workId = requiredPosition(parsed, 0, "work-id");
+        const projectRoot = requiredScopeProjectRoot(scopeProjectRoot, "work finish");
+        assertWorkLifecycleOwner(context, { workId, projectRoot, operation: "work_finish", ...(optionalOption(parsed, "hook-event-id") ? { hookEventId: optionalOption(parsed, "hook-event-id") } : {}) });
+        const retryReceiptId = optionalOption(parsed, "retry-check"), retryReason = optionalOption(parsed, "reason");
+        if (Boolean(retryReceiptId) !== Boolean(retryReason))
+            throw new AppError("usage", "--retry-check and --reason must be supplied together", 2);
         const result = resultFile ? fs.readFileSync(path.resolve(resultFile), "utf8") : await readStdin(io.stdin);
-        return await finishWork(context, requiredPosition(parsed, 0, "work-id"), result, commandProgress(io, output));
+        return await finishWork(context, workId, result, commandProgress(io, output), retryReceiptId ? { receiptId: retryReceiptId, reason: retryReason } : undefined);
+    }
+    if (family === "work" && command === "fail") {
+        const workId = requiredPosition(parsed, 0, "work-id");
+        const projectRoot = requiredScopeProjectRoot(scopeProjectRoot, "work fail");
+        assertWorkLifecycleOwner(context, { workId, projectRoot, operation: "work_fail", ...(optionalOption(parsed, "hook-event-id") ? { hookEventId: optionalOption(parsed, "hook-event-id") } : {}) });
+        return failWork(context, workId, requiredOption(parsed, "reason"));
     }
-    if (family === "work" && command === "fail")
-        return failWork(context, requiredPosition(parsed, 0, "work-id"), requiredOption(parsed, "reason"));
     if (family === "work" && command === "cancel")
         return cancelWork(context, requiredPosition(parsed, 0, "work-id"), requiredOption(parsed, "reason"));
     if (family === "work" && command === "retry")
@@ -874,9 +1025,23 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
         const projectRoot = requiredOption(parsed, "project-root");
         const runId = requiredPosition(parsed, 0, "run-id");
         const stage = requiredOption(parsed, "stage");
+        const controlledReply = (result) => controlLifecycleReply(context, { projectRoot, runId }, result);
         const semanticFile = optionalOption(parsed, "semantic-file") ?? optionalOption(parsed, "data");
         const resultFile = optionalOption(parsed, "result-file") ?? semanticFile;
         const resultStdin = hasOption(parsed, "result-stdin");
+        const retryCheckId = optionalOption(parsed, "retry-check");
+        const retryReason = optionalOption(parsed, "reason");
+        const hookEventId = optionalOption(parsed, "hook-event-id");
+        if (retryCheckId && !retryReason?.trim())
+            throw new AppError("usage", "--retry-check requires --reason explaining the recovered environment", 2);
+        const protectedLifecycle = (stage === "specify" && isVnextSpecifyRun(context, { projectRoot, runId }))
+            || (stage === "protocolize" && isVnextProtocolizeRun(context, { projectRoot, runId }))
+            || (stage === "plan" && isVnextPlanRun(context, { projectRoot, runId }))
+            || (stage === "plan-review" && isVnextPlanReviewRun(context, { projectRoot, runId }))
+            || (stage === "code" && isVnextPlanRun(context, { projectRoot, runId }))
+            || (stage === "code-review" && isVnextCodeReviewRun(context, { projectRoot, runId }));
+        if (protectedLifecycle)
+            assertStageLifecycleOwner(context, { projectRoot, runId, stage, operation: "stage_finish", ...(hookEventId ? { hookEventId } : {}) });
         if (stage === "specify" && isVnextSpecifyRun(context, { projectRoot, runId })) {
             const outcome = optionalOption(parsed, "outcome");
             if (!outcome || !["specified", "failed", "cancelled"].includes(outcome)) {
@@ -888,65 +1053,77 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
             if (!resultFile && !resultStdin) {
                 throw new AppError("usage", "vNext SPECIFY finish requires --result-file or --result-stdin", 2);
             }
-            return finishVnextSpecifyStage(context, {
+            return controlledReply(await finishVnextSpecifyStage(context, {
                 projectRoot,
                 runId,
                 ...(resultFile ? { resultFile } : { resultJson: await readStdin(io.stdin) }),
                 outcome: outcome
-            });
+            }));
         }
         if (stage === "protocolize" && isVnextProtocolizeRun(context, { projectRoot, runId })) {
             if (!resultFile || resultStdin || hasOption(parsed, "outcome")) {
                 throw new AppError("usage", "vNext PROTOCOLIZE requires exactly --result-file", 2);
             }
-            return finishVnextProtocolize(context, { projectRoot, runId, resultFile });
+            return controlledReply(await finishVnextProtocolize(context, { projectRoot, runId, resultFile }));
         }
         if (stage === "plan" && isVnextPlanRun(context, { projectRoot, runId })) {
             if (optionalOption(parsed, "code-work-batch-file"))
                 throw new AppError("usage", "vNext PLAN derives its CODE batch from accepted semantic plans; do not supply a batch file", 2);
-            return finishVnextPlan(context, { projectRoot, runId });
+            return controlledReply(await finishVnextPlan(context, { projectRoot, runId }));
         }
         if (stage === "plan-review" && isVnextPlanReviewRun(context, { projectRoot, runId })) {
             if (resultStdin || hasOption(parsed, "outcome"))
                 throw new AppError("usage", "vNext PLAN-REVIEW uses --decision-file", 2);
             const decisionFile = optionalOption(parsed, "decision-file");
-            return finishVnextPlanReview(context, { projectRoot, runId, ...(decisionFile ? { decisionFile } : {}) });
+            return controlledReply(await finishVnextPlanReview(context, { projectRoot, runId, ...(decisionFile ? { decisionFile } : {}) }));
         }
         if (stage === "code" && isVnextPlanRun(context, { projectRoot, runId })) {
             if (semanticFile || resultFile || resultStdin || hasOption(parsed, "outcome")) {
                 throw new AppError("usage", "vNext CODE finish accepts only --verification-file", 2);
             }
-            return await finishVnextCode(context, { projectRoot, runId, verificationFile: optionalOption(parsed, "verification-file") ?? path.join("<missing>", "code-verification.json"), progress: commandProgress(io, output) });
+            return controlledReply(await finishVnextCode(context, { projectRoot, runId, verificationFile: optionalOption(parsed, "verification-file") ?? path.join("<missing>", "code-verification.json"), ...(retryCheckId ? { retryCheckId, retryReason: retryReason } : {}), progress: commandProgress(io, output) }));
         }
         if (stage === "code-review" && isVnextCodeReviewRun(context, { projectRoot, runId })) {
             if (resultStdin || semanticFile || resultFile || hasOption(parsed, "outcome"))
                 throw new AppError("usage", "vNext CODE-REVIEW uses --decision-file", 2);
-            return await finishVnextCodeReview(context, { projectRoot, runId, ...(optionalOption(parsed, "decision-file") ? { decisionFile: optionalOption(parsed, "decision-file") } : {}), progress: commandProgress(io, output) });
+            return controlledReply(await finishVnextCodeReview(context, { projectRoot, runId, ...(optionalOption(parsed, "decision-file") ? { decisionFile: optionalOption(parsed, "decision-file") } : {}), ...(retryCheckId ? { retryCheckId, retryReason: retryReason } : {}), progress: commandProgress(io, output) }));
         }
         if (stage === "merge" && isVnextMergeRun(context, { projectRoot, runId })) {
             if (resultStdin || semanticFile || resultFile || hasOption(parsed, "outcome"))
                 throw new AppError("usage", "vNext MERGE uses the Work result path returned by stage start", 2);
-            return await finishVnextMerge(context, { projectRoot, runId, requestId: requiredOption(parsed, "request"), workId: requiredOption(parsed, "work"), progress: commandProgress(io, output) });
+            return controlledReply(await finishVnextMerge(context, { projectRoot, runId, requestId: requiredOption(parsed, "request"), workId: requiredOption(parsed, "work"), ...(retryCheckId ? { retryCheckId, retryReason: retryReason } : {}), progress: commandProgress(io, output) }));
         }
         if (hasOption(parsed, "outcome") || hasOption(parsed, "result-file") || resultStdin) {
             throw new AppError("usage", "--outcome, --result-file and --result-stdin are only available for vNext SPECIFY", 2);
         }
-        return finishStage(context, {
+        return controlledReply(await finishStage(context, {
             projectRoot,
             runId,
             stage,
             ...(dir ? { dir } : {}),
             ...(semanticFile ? { semanticFile } : {})
-        });
+        }));
     }
     if (family === "stage" && command === "pause") {
         if (!hasOption(parsed, "question-stdin"))
             throw new AppError("usage", "stage pause requires --question-stdin", 2);
+        const projectRoot = requiredOption(parsed, "project-root");
+        const runId = requiredPosition(parsed, 0, "run-id");
+        const stage = requiredOption(parsed, "stage");
+        const workId = requiredOption(parsed, "work");
+        const protectedLifecycle = (stage === "specify" && isVnextSpecifyRun(context, { projectRoot, runId }))
+            || (stage === "protocolize" && isVnextProtocolizeRun(context, { projectRoot, runId }))
+            || (stage === "plan" && isVnextPlanRun(context, { projectRoot, runId }))
+            || (stage === "plan-review" && isVnextPlanReviewRun(context, { projectRoot, runId }))
+            || (stage === "code" && isVnextPlanRun(context, { projectRoot, runId }))
+            || (stage === "code-review" && isVnextCodeReviewRun(context, { projectRoot, runId }));
+        if (protectedLifecycle)
+            assertStageLifecycleOwner(context, { projectRoot, runId, stage, workId, operation: "stage_pause", ...(optionalOption(parsed, "hook-event-id") ? { hookEventId: optionalOption(parsed, "hook-event-id") } : {}) });
         return pauseStageForUser(context, {
-            projectRoot: requiredOption(parsed, "project-root"),
-            runId: requiredPosition(parsed, 0, "run-id"),
-            stage: requiredOption(parsed, "stage"),
-            workId: requiredOption(parsed, "work"),
+            projectRoot,
+            runId,
+            stage,
+            workId,
             question: await readStdin(io.stdin)
         });
     }
@@ -1007,6 +1184,48 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
         return dispatchSession(context, command, parsed);
     }
     if (family === "run") {
+        if (command === "control") {
+            const action = requiredPosition(parsed, 0, "control action");
+            const scope = { projectRoot: requiredOption(parsed, "project-root"), runId: requiredOption(parsed, "run") };
+            if (action === "status")
+                return runControlStatus(context, scope);
+            if (action === "reconcile") {
+                if ([...parsed.options.keys()].some(key => !["run", "project-root", "control-id", "request-id"].includes(key)) || [...parsed.options.values()].some(values => values.length !== 1))
+                    throw new AppError("usage", "Use run control reconcile --run ID --project-root PATH --control-id ID --request-id ID", 2);
+                return await reconcileRunControl(context, { ...scope, controlId: requiredOption(parsed, "control-id"), requestId: requiredOption(parsed, "request-id") });
+            }
+            if (action === "resume") {
+                if (["force", "grace-ms", "escalate"].some(option => hasOption(parsed, option)))
+                    throw new AppError("usage", "Resume does not accept stop or pause escalation options", 2);
+                return await resumeRunController(context, { ...scope, requestId: requiredOption(parsed, "request-id"), controlId: requiredOption(parsed, "from"), ...(hasOption(parsed, "wait-ms") ? { waitMs: Number(requiredOption(parsed, "wait-ms")) } : {}) });
+            }
+            if (action === "serve")
+                return await serveRunControl(context, { ...scope, controlId: requiredOption(parsed, "control-id") });
+            if (action === "pause" || action === "stop")
+                return await requestRunControl(context, {
+                    ...scope, action, requestId: requiredOption(parsed, "request-id"),
+                    ...(hasOption(parsed, "force") ? { force: true } : {}),
+                    ...(hasOption(parsed, "grace-ms") ? { graceMs: Number(requiredOption(parsed, "grace-ms")) } : {}),
+                    ...(hasOption(parsed, "escalate") ? { escalate: requiredOption(parsed, "escalate") } : {}),
+                    ...(hasOption(parsed, "wait-ms") ? { waitMs: Number(requiredOption(parsed, "wait-ms")) } : {})
+                });
+            throw new AppError("usage", "Use: dd-flow run control pause|stop|resume|reconcile|status", 2);
+        }
+        if (command === "drive") {
+            const action = requiredPosition(parsed, 0, "drive action");
+            const scope = { projectRoot: requiredOption(parsed, "project-root"), runId: requiredOption(parsed, "run") };
+            if (action === "status")
+                return runControllerStatus(context, { ...scope, ...(optionalOption(parsed, "after") ? { after: Number(optionalOption(parsed, "after")) } : {}) });
+            if (action === "launch")
+                return await launchRunController(context, { ...scope, requestId: requiredOption(parsed, "request-id"), contextFile: requiredOption(parsed, "context-file"), contextSha256: requiredOption(parsed, "context-sha256"), ...(optionalOption(parsed, "stop-after") ? { stopAfter: optionalOption(parsed, "stop-after") } : {}), ...(optionalOption(parsed, "capture-root") ? { captureRoot: optionalOption(parsed, "capture-root") } : {}) });
+            if (action === "serve")
+                return await serveRunController(context, { ...scope, controllerId: requiredOption(parsed, "controller-id") });
+            if (action === "answer")
+                return answerRunController(context, { ...scope, requestId: requiredOption(parsed, "request-id"), pauseId: requiredOption(parsed, "pause-id"), answerFile: requiredOption(parsed, "answer-file") });
+            if (action === "context")
+                return supplyRunControllerContext(context, { ...scope, controllerId: requiredOption(parsed, "controller-id"), requestId: requiredOption(parsed, "request-id"), stage: requiredOption(parsed, "stage"), contextFile: requiredOption(parsed, "context-file"), contextSha256: requiredOption(parsed, "context-sha256") });
+            throw new AppError("usage", "Use: dd-flow run drive launch|status|answer|context", 2);
+        }
         return dispatchRun(context, command, parsed);
     }
     if (family === "stat") {
@@ -1039,6 +1258,9 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
     if (family === "codex" && command === "hook") {
         return dispatchCodexHook(context, parsed, await readStdin(io.stdin));
     }
+    if (family === "zcode" && command === "hook") {
+        return dispatchZcodeHook(context, parsed, await readStdin(io.stdin));
+    }
     if (family === "zcode" && command === "event") {
         return dispatchZcodeEvent(context, parsed, await readStdin(io.stdin));
     }
@@ -1063,6 +1285,16 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
             throw new AppError("usage", "Unknown opencode usage action", 2);
         return ingestOpenCodeUsage(context, { projectRoot: requiredOption(parsed, "project-root"), stdin: await readStdin(io.stdin) });
     }
+    if (family === "droid" && command === "event") {
+        if (requiredPosition(parsed, 0, "droid event action") !== "handle")
+            throw new AppError("usage", "Unknown droid event action", 2);
+        return handleDroidEvent(context, { projectRoot: requiredOption(parsed, "project-root"), stdin: await readStdin(io.stdin) });
+    }
+    if (family === "droid" && command === "usage") {
+        if (requiredPosition(parsed, 0, "droid usage action") !== "ingest")
+            throw new AppError("usage", "Unknown droid usage action", 2);
+        return ingestDroidUsage(context, { projectRoot: requiredOption(parsed, "project-root"), stdin: await readStdin(io.stdin) });
+    }
     if (family === "agy" && command === "event")
         return dispatchAgyEvent(context, parsed, await readStdin(io.stdin));
     if (family === "agy" && command === "usage") {
@@ -1247,6 +1479,8 @@ async function dispatchMerge(context, command, parsed, progress) {
     }
     if (command === "apply")
         return applyVnextMerge(context, { projectRoot: requiredOption(parsed, "project-root"), requestId: requiredPosition(parsed, 0, "merge-request-id"), workId: requiredOption(parsed, "work"), ...(progress ? { progress } : {}) });
+    if (command === "repair")
+        return await repairVnextMerge(context, { projectRoot: requiredOption(parsed, "project-root"), requestId: requiredPosition(parsed, 0, "merge-request-id") });
     if (command === "request") {
         const action = requiredPosition(parsed, 0, "request action");
         const requestId = requiredPosition(parsed, 1, "merge-request-id");
@@ -1410,6 +1644,24 @@ function dispatchSession(context, command, parsed) {
     throw new AppError("usage", `Unknown session command: ${command ?? "<empty>"}`, 2);
 }
 function dispatchRun(context, command, parsed) {
+    if (command === "recovery") {
+        const action = requiredPosition(parsed, 0, "recovery action");
+        const projectRoot = requiredOption(parsed, "project-root");
+        const runId = requiredPosition(parsed, 1, "run-id");
+        if (action === "inspect")
+            return inspectRunRecovery(context, { projectRoot, runId });
+        if (action === "begin")
+            return beginRunRecovery(context, { projectRoot, runId, interruption: requiredOption(parsed, "interruption-json") });
+        if (action === "seal")
+            return sealRunRecovery(context, { projectRoot, runId, recoveryId: requiredOption(parsed, "recovery-id"), settlement: requiredOption(parsed, "settlement-json") });
+        if (action === "capture")
+            return recordRecoveryCapture(context, { projectRoot, runId, recoveryId: requiredOption(parsed, "recovery-id"), capturePath: requiredOption(parsed, "capture-path") });
+        if (action === "resume")
+            return resumeRunRecovery(context, { projectRoot, runId, recoveryId: requiredOption(parsed, "recovery-id"), daemonId: requiredOption(parsed, "daemon-id"), harness: requiredOption(parsed, "harness"), nativeSessionId: requiredOption(parsed, "native-session-id") });
+        if (action === "accept")
+            return acceptRunRecovery(context, { projectRoot, runId, recoveryId: requiredOption(parsed, "recovery-id"), ...(optionalOption(parsed, "hook-event-id") ? { hookEventId: optionalOption(parsed, "hook-event-id") } : {}) });
+        throw new AppError("usage", "Use: dd-flow run recovery inspect|begin|seal|capture|resume|accept", 2);
+    }
     if (command === "snapshot") {
         const action = requiredPosition(parsed, 0, "snapshot action");
         if (action === "bootstrap") {
@@ -1428,16 +1680,20 @@ function dispatchRun(context, command, parsed) {
         }
         if (action === "create") {
             const candidate = parsed.options.has("candidate");
+            const incomplete = parsed.options.has("incomplete");
+            const recoveryId = optionalOption(parsed, "recovery-id");
             const stageEntry = optionalOption(parsed, "stage-entry");
-            if (candidate && stageEntry !== undefined)
-                throw new AppError("usage", "Use either --candidate or --stage-entry, not both", 2);
-            if (!candidate && stageEntry === undefined)
-                throw new AppError("usage", "Snapshot create requires --candidate or --stage-entry", 2);
+            if (Number(candidate) + Number(incomplete) + Number(stageEntry !== undefined) + Number(recoveryId !== undefined) !== 1)
+                throw new AppError("usage", "Use exactly one of --candidate, --incomplete, --recovery-id or --stage-entry", 2);
             const input = {
                 projectRoot: requiredOption(parsed, "project-root"),
                 runId: requiredPosition(parsed, 1, "run-id"),
                 output: requiredOption(parsed, "output")
             };
+            if (incomplete)
+                return createEvalRunSnapshot(context, { ...input, incomplete: true });
+            if (recoveryId)
+                return createEvalRunSnapshot(context, { ...input, recoveryId });
             return candidate
                 ? createEvalRunSnapshot(context, { ...input, candidate: true })
                 : createEvalRunSnapshot(context, { ...input, stageEntry: stageEntry });
@@ -1445,12 +1701,23 @@ function dispatchRun(context, command, parsed) {
         if (action === "restore")
             return restoreEvalRunSnapshot(context, {
                 snapshot: requiredOption(parsed, "snapshot"),
+                executionRoutingFile: optionalOption(parsed, "execution-routing-file"),
+                ...(optionalOption(parsed, "recovery-id") ? { recoveryId: requiredOption(parsed, "recovery-id") } : {}),
                 projectRoot: requiredOption(parsed, "project-root")
             });
         throw new AppError("usage", "Use: dd-flow run snapshot bootstrap create|restore | dd-flow run snapshot create <RUN> (--stage-entry <stage>|--candidate) --project-root <path> --output <directory> | dd-flow run snapshot restore --snapshot <directory> --project-root <path>", 2);
     }
+    if (command === "fork") {
+        return forkRunFromSnapshot(context, {
+            snapshot: requiredOption(parsed, "from"),
+            output: requiredOption(parsed, "output"),
+            engineVersion: requiredOption(parsed, "engine-version"),
+            requestId: requiredOption(parsed, "request-id"),
+            ...(optionalOption(parsed, "integrity-checksum") ? { integrityChecksum: optionalOption(parsed, "integrity-checksum") } : {})
+        });
+    }
     if (command === "prepare-vnext-specify") {
-        return prepareVnextSpecifyRun(context, { projectRoot: requiredOption(parsed, "project-root"), slug: requiredOption(parsed, "slug") });
+        return prepareVnextSpecifyRun(context, { projectRoot: requiredOption(parsed, "project-root"), slug: requiredOption(parsed, "slug"), executionRoutingFile: optionalOption(parsed, "execution-routing-file") });
     }
     if (command === "start") {
         if (optionalOption(parsed, "flow-kind") === "mb-upgrade") {
@@ -1467,6 +1734,7 @@ function dispatchRun(context, command, parsed) {
             nextAction: optionalOption(parsed, "next-action"),
             preset: optionalOption(parsed, "preset"),
             taskProfile: readOptionalJsonFile(optionalOption(parsed, "task-profile-file")),
+            executionRoutingFile: optionalOption(parsed, "execution-routing-file"),
             ...(protocolOverrides ? { protocolOverrides } : {}),
             runOverrides: parseFlowFlagOverrides(allOptions(parsed, "flag"))
         });
@@ -1581,30 +1849,113 @@ function dispatchRun(context, command, parsed) {
     }
     throw new AppError("usage", `Unknown run command: ${command ?? "<empty>"}`, 2);
 }
-async function dispatchRuntime(context, command, parsed) {
+async function dispatchRuntime(context, command, parsed, progress) {
+    if (command === "scope") {
+        if (parsed.positional.length === 1 && parsed.positional[0] === "reconcile") {
+            if ([...parsed.options.keys()].some(key => !["scope-id", "request-id", "generation"].includes(key)) || [...parsed.options.values()].some(values => values.length !== 1))
+                throw new AppError("usage", "Use runtime scope reconcile --scope-id ID --generation N --request-id ID", 2);
+            return { ok: true, ...await reconcileRuntimeScopeControl(context, requiredOption(parsed, "scope-id"), Number(requiredOption(parsed, "generation")), requiredOption(parsed, "request-id")) };
+        }
+        if (parsed.positional.length === 1 && parsed.positional[0] === "resume") {
+            if ([...parsed.options.keys()].some(key => !["scope-id", "request-id", "generation", "capture-key"].includes(key)) || [...parsed.options.values()].some(values => values.length !== 1))
+                throw new AppError("usage", "Use runtime scope resume --scope-id ID --request-id ID --generation N --capture-key SHA256", 2);
+            return { ok: true, ...await launchRuntimeScopeResume(context, { scopeId: requiredOption(parsed, "scope-id"), requestId: requiredOption(parsed, "request-id"), generation: Number(requiredOption(parsed, "generation")), captureKey: requiredOption(parsed, "capture-key") }) };
+        }
+        if (parsed.positional.length === 1 && parsed.positional[0] === "control") {
+            if ([...parsed.options.keys()].some(key => !["scope-id", "request-id", "mode", "manifest-json"].includes(key)) || [...parsed.options.values()].some(values => values.length !== 1))
+                throw new AppError("usage", "Use runtime scope control --scope-id ID --request-id ID --mode pause|stop [--manifest-json JSON]", 2);
+            const mode = requiredOption(parsed, "mode");
+            if (mode !== "pause" && mode !== "stop")
+                throw new AppError("usage", "Scope control mode must be pause or stop", 2);
+            return { ok: true, ...await launchRuntimeScopeControl(context, requiredOption(parsed, "scope-id"), requiredOption(parsed, "request-id"), mode, hasOption(parsed, "manifest-json") ? JSON.parse(requiredOption(parsed, "manifest-json")) : undefined) };
+        }
+        if (parsed.positional.length === 1 && parsed.positional[0] === "serve") {
+            if ([...parsed.options.keys()].some(key => !["scope-id", "generation"].includes(key)) || [...parsed.options.values()].some(values => values.length !== 1))
+                throw new AppError("usage", "Invalid internal scope worker arguments", 2);
+            return { ok: true, ...await serveRuntimeScopeControl(context, requiredOption(parsed, "scope-id"), Number(requiredOption(parsed, "generation"))) };
+        }
+        if (parsed.positional.length === 1 && parsed.positional[0] === "stop") {
+            if ([...parsed.options.keys()].some(key => !["scope-id", "request-id"].includes(key)) || [...parsed.options.values()].some(values => values.length !== 1))
+                throw new AppError("usage", "Usage: dd-flow runtime scope stop --scope-id EVAL_ID --request-id ID", 2);
+            return { ok: true, ...await stopRuntimeScope(context, requiredOption(parsed, "scope-id"), requiredOption(parsed, "request-id")) };
+        }
+        if (parsed.positional.length === 1 && parsed.positional[0] === "status") {
+            if ([...parsed.options.keys()].some(key => key !== "scope-id") || [...parsed.options.values()].some(values => values.length !== 1))
+                throw new AppError("usage", "Usage: dd-flow runtime scope status --scope-id EVAL_ID", 2);
+            return { ok: true, ...runtimeBudgetStatus(context, requiredOption(parsed, "scope-id")) };
+        }
+        if (parsed.positional.length !== 1 || parsed.positional[0] !== "fence" || [...parsed.options.keys()].some(key => !["scope-id", "request-id"].includes(key)) || [...parsed.options.values()].some(values => values.length !== 1))
+            throw new AppError("usage", "Usage: dd-flow runtime scope fence --scope-id EVAL_ID --request-id ID", 2);
+        return { ok: true, ...fenceRuntimeBudget(context, requiredOption(parsed, "scope-id"), requiredOption(parsed, "request-id")) };
+    }
     if (command !== "process")
-        throw new AppError("usage", "Usage: dd-flow runtime process <register|confirm|heartbeat|finish|status|reconcile>", 2);
+        throw new AppError("usage", "Usage: dd-flow runtime <scope|process>; see dd-flow runtime scope --help", 2);
     const action = requiredPosition(parsed, 0, "runtime process action");
+    if (action === "check-admission")
+        return { ok: true, ...admitRuntimeCheck(context, requiredOption(parsed, "id"), requiredOption(parsed, "lease-token")) };
+    if (action === "start")
+        return await startRuntimeService(context, { projectRoot: requiredOption(parsed, "project-root"), runId: requiredOption(parsed, "run"), command: requiredOption(parsed, "command"), ports: requiredOption(parsed, "ports").split(","), readyPort: requiredOption(parsed, "ready-port"), readyPath: optionalOption(parsed, "ready-path") ?? "/", timeoutMs: optionalPositiveNumber(parsed, "ready-timeout-ms", true) ?? 30_000, progress });
+    if (action === "stop")
+        return { ok: true, process: await stopManagedProcess(context, { id: requiredOption(parsed, "id"), leaseToken: requiredOption(parsed, "lease-token"), ...(optionalPositiveNumber(parsed, "grace-ms", true) ? { graceMs: optionalPositiveNumber(parsed, "grace-ms", true) } : {}) }) };
     if (action === "register") {
         const leaseMs = optionalPositiveNumber(parsed, "lease-ms", true);
+        const budget = parseRuntimeBudget(optionalOption(parsed, "budget-json"));
+        const projectId = optionalOption(parsed, "project-id") ?? null, runId = optionalOption(parsed, "run") ?? null;
+        const guard = projectId && runId ? recoveryGuard(context, projectId, runId) : null;
+        const run = projectId && runId ? context.db.get("SELECT id FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]) : null;
         const process = registerManagedProcess(context, {
             kind: requiredOption(parsed, "kind"), ownerId: requiredOption(parsed, "owner"),
-            projectId: optionalOption(parsed, "project-id") ?? null, runId: optionalOption(parsed, "run") ?? null,
+            uniqueActiveOperation: requiredOption(parsed, "kind") === "eval-observer",
+            ...(requiredOption(parsed, "kind") === "eval-observer" ? { pid: optionalPositiveNumber(parsed, "pid", true) ?? 0, ...(optionalPositiveNumber(parsed, "process-group-id", true) ? { processGroupId: optionalPositiveNumber(parsed, "process-group-id", true) } : {}) } : {}),
+            ownerPid: optionalPositiveNumber(parsed, "owner-pid", true),
+            projectId, runId,
             workId: optionalOption(parsed, "work") ?? null, checkId: optionalOption(parsed, "check") ?? null,
             operationId: optionalOption(parsed, "operation") ?? null, stdoutPath: optionalOption(parsed, "stdout") ?? null,
-            stderrPath: optionalOption(parsed, "stderr") ?? null, ...(leaseMs ? { leaseMs } : {})
+            stderrPath: optionalOption(parsed, "stderr") ?? null, ...(leaseMs ? { leaseMs } : {}),
+            metadata: { ...(budget ? { budget, harness: optionalOption(parsed, "harness") ?? null } : {}), ...(projectId && runId ? { run_generation: guard?.generation ?? 0, run_admitted: Boolean(run) && !["draining", "sealed", "resuming"].includes(guard?.status ?? "") } : {}), ...(optionalOption(parsed, "dispatch-barrier") ? { dispatch_barrier: optionalOption(parsed, "dispatch-barrier") } : {}), ...(optionalOption(parsed, "role") ? { role: optionalOption(parsed, "role") } : {}), ...(optionalOption(parsed, "state-dir") ? { state_dir: optionalOption(parsed, "state-dir") } : {}), ...(optionalOption(parsed, "adapter-executable") ? { adapter_executable: optionalOption(parsed, "adapter-executable") } : {}) }
         });
         return { ok: true, process };
     }
     if (action === "confirm") {
         const leaseMs = optionalPositiveNumber(parsed, "lease-ms", true);
         const processGroupId = optionalPositiveNumber(parsed, "process-group-id", true);
-        return { ok: true, process: confirmManagedProcess(context, { id: requiredOption(parsed, "id"), leaseToken: requiredOption(parsed, "lease-token"), pid: optionalPositiveNumber(parsed, "pid", true) ?? 0, ...(processGroupId ? { processGroupId } : {}), ...(leaseMs ? { leaseMs } : {}) }) };
+        return { ok: true, process: confirmManagedProcess(context, { id: requiredOption(parsed, "id"), leaseToken: requiredOption(parsed, "lease-token"), ownerPid: optionalPositiveNumber(parsed, "owner-pid", true), pid: optionalPositiveNumber(parsed, "pid", true) ?? 0, ...(processGroupId ? { processGroupId } : {}), ...(leaseMs ? { leaseMs } : {}) }) };
     }
     if (action === "heartbeat") {
         const leaseMs = optionalPositiveNumber(parsed, "lease-ms", true);
         return { ok: heartbeatManagedProcess(context, { id: requiredOption(parsed, "id"), leaseToken: requiredOption(parsed, "lease-token"), ...(leaseMs ? { leaseMs } : {}) }) };
     }
+    if (action === "admission") {
+        const record = managedProcessStatus(context).find(process => process.id === requiredOption(parsed, "id"));
+        if (!record || record.lease_token !== requiredOption(parsed, "lease-token") || record.owner_id !== requiredOption(parsed, "owner") || record.state !== "running" || !record.pid || !record.pid_started_at || !processIsAlive(record))
+            throw new AppError("process_ownership_unknown", "Productive dispatch requires its current confirmed runtime owner", 1);
+        const metadata = JSON.parse(record.metadata_json);
+        if (metadata.state_dir !== requiredOption(parsed, "state-dir"))
+            throw new AppError("process_ownership_unknown", "Runtime admission belongs to another state directory", 1);
+        if (record.project_id && record.run_id) {
+            if (managedProcessRuntimeHome(record, context) !== context.ddFlowHome)
+                throw new AppError("process_runtime_scope_mismatch", "Runtime admission belongs to another or unproven flow home", 1);
+            const recovering = recoveryRuntimeAdmission(context, record, { stateDir: requiredOption(parsed, "state-dir"), daemonId: optionalOption(parsed, "daemon-id"), operationId: optionalOption(parsed, "operation-id"), operation: optionalOption(parsed, "operation"), nativeSessionId: optionalOption(parsed, "native-session-id"), promptSha256: optionalOption(parsed, "prompt-sha256") });
+            if (!recovering) {
+                if (metadata.run_admitted !== true || !Number.isSafeInteger(metadata.run_generation))
+                    throw new AppError("run_recovery_guarded", "Runtime was not admitted before the RUN fence; reconcile its launch", 1);
+                assertRunMutationAllowed(context, record.project_id, record.run_id, metadata.run_generation);
+            }
+            const run = context.db.get("SELECT status FROM runs WHERE project_id = ? AND id = ?", [record.project_id, record.run_id]);
+            const retainedHitlPrompt = recovering && ["paused", "waiting_for_user"].includes(run?.status ?? "") && ["session.prompt", "session.resume"].includes(optionalOption(parsed, "operation") ?? "") && context.db.get("SELECT 1 FROM run_recovery_bindings b JOIN run_recovery_guards g ON g.recovery_id = b.recovery_id WHERE g.project_id = ? AND g.run_id = ? AND g.generation = ? AND b.daemon_id = ? AND b.provider_session_id = ?", [record.project_id, record.run_id, metadata.run_generation, optionalOption(parsed, "daemon-id"), optionalOption(parsed, "native-session-id")]);
+            const acceptedHitlPrompt = ["paused", "waiting_for_user"].includes(run?.status ?? "") && controllerHitlAdmission(context, record, { stateDir: requiredOption(parsed, "state-dir"), operationId: optionalOption(parsed, "operation-id"), operation: optionalOption(parsed, "operation"), nativeSessionId: optionalOption(parsed, "native-session-id"), promptSha256: optionalOption(parsed, "prompt-sha256") });
+            if (!run || run.status !== "running" && !retainedHitlPrompt && !acceptedHitlPrompt && !["judge", "probe"].includes(metadata.role ?? ""))
+                throw new AppError("invalid_run_state", "Subject dispatch requires a running RUN or its retained recovery/HITL prompt", 1);
+        }
+        const budget = reserveProviderTurn(context, record, { operationId: optionalOption(parsed, "operation-id") ?? "", operation: optionalOption(parsed, "operation") ?? "", sessionId: optionalOption(parsed, "native-session-id"), daemonId: optionalOption(parsed, "daemon-id") });
+        return { ok: true, ...budget, process_id: record.id, generation: metadata.run_generation ?? null };
+    }
+    if (action === "release-turn") {
+        const record = managedProcessStatus(context).find(process => process.id === requiredOption(parsed, "id"));
+        if (!record || record.lease_token !== requiredOption(parsed, "lease-token") || record.owner_id !== requiredOption(parsed, "owner") || managedProcessRuntimeHome(record, context) !== context.ddFlowHome)
+            throw new AppError("process_ownership_unknown", "Budget release requires its retained physical owner", 1);
+        return releaseProviderTurns(context, record, { daemonId: requiredOption(parsed, "daemon-id"), operationId: optionalOption(parsed, "operation-id"), observationFile: optionalOption(parsed, "observation-file") });
+    }
     if (action === "finish") {
         const state = requiredOption(parsed, "state");
         if (state !== "stopped" && state !== "failed")
@@ -1615,7 +1966,7 @@ async function dispatchRuntime(context, command, parsed) {
         return { ok: true, processes: managedProcessStatus(context) };
     if (action === "reconcile")
         return { ok: true, processes: await reconcileExpiredManagedProcesses(context, requiredOption(parsed, "owner"), optionalPositiveNumber(parsed, "grace-ms", true)) };
-    throw new AppError("usage", "Usage: dd-flow runtime process <register|confirm|heartbeat|finish|status|reconcile>", 2);
+    throw new AppError("usage", "Usage: dd-flow runtime process <start|stop|register|confirm|heartbeat|admission|finish|status|reconcile>", 2);
 }
 function dispatchStat(context, command, parsed) {
     if (command === "usage") {
@@ -1797,16 +2148,37 @@ function dispatchSchema(context, command, parsed) {
     if (command === "validate") {
         const schemaDir = optionalOption(parsed, "schema-dir");
         const projectRoot = optionalOption(parsed, "project-root");
+        const file = requiredOption(parsed, "file");
+        // A generic validation command can still bind to the exact RUN without
+        // searching project directories: run_id is a structural field in the
+        // submitted artifact and the database owns its materialized run_root.
+        const explicitRunId = optionalOption(parsed, "run");
+        const declaredRunId = explicitRunId ?? readRunId(file);
+        const fileRunRoot = path.basename(file) === "run.json" ? path.dirname(path.resolve(file)) : undefined;
+        const bound = projectRoot
+            ? context.db.get("SELECT r.id, r.run_root FROM runs r JOIN projects p ON p.id = r.project_id WHERE p.root = ? AND (r.id = ? OR r.run_root = ?) LIMIT 1", [fs.realpathSync(projectRoot), declaredRunId ?? "", fileRunRoot ?? ""])
+            : undefined;
         return validateSchema({
             schemaName: requiredOption(parsed, "schema"),
-            file: requiredOption(parsed, "file"),
+            file,
             ...(schemaDir ? { schemaDir } : {}),
             ...(projectRoot ? { projectRoot } : {}),
+            ...(declaredRunId || bound?.id ? { runId: declaredRunId ?? bound.id } : {}),
+            ...(bound?.run_root ? { runRoot: bound.run_root } : {}),
             ddFlowHome: context.ddFlowHome
         });
     }
     throw new AppError("usage", `Unknown schema command: ${command ?? "<empty>"}`, 2);
 }
+function readRunId(file) {
+    try {
+        const value = JSON.parse(fs.readFileSync(file, "utf8"));
+        return typeof value.run_id === "string" && value.run_id.trim() ? value.run_id : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 async function dispatchLane(context, command, parsed) {
     if (command === "status") {
         return getLaneStatus(context, { projectRoot: requiredOption(parsed, "project-root"), lane: optionalOption(parsed, "lane") });
@@ -2006,6 +2378,15 @@ function dispatchZcodeEvent(context, parsed, stdin) {
     }
     throw new AppError("usage", `Unknown zcode event action: ${action}`, 2);
 }
+function dispatchZcodeHook(context, parsed, stdin) {
+    if (requiredPosition(parsed, 0, "zcode hook action") !== "handle")
+        throw new AppError("usage", "Unknown zcode hook action", 2);
+    const result = handleZcodeHook(context, { projectRoot: requiredOption(parsed, "project-root"), stdin });
+    if (result && typeof result === "object" && !Array.isArray(result) && "hookSpecificOutput" in result) {
+        return { hookSpecificOutput: result.hookSpecificOutput };
+    }
+    return {};
+}
 function dispatchGrokEvent(context, parsed, stdin) {
     const action = requiredPosition(parsed, 0, "grok event action");
     if (action === "handle") {
@@ -2128,6 +2509,21 @@ function parseFlowFlagOverrides(values) {
 function parseArgs(args) {
     return parseCommandArgs(args);
 }
+/** Most CLI options name one authority, path or target.  Silently taking the
+ * last duplicate can widen a mutation after an operator typo.  Keep only the
+ * options consumed as intentional arrays repeatable. */
+function assertSingletonOptions(args) {
+    const repeatable = new Set(["alias", "flag", "hide", "check-ref", "evidence", "from-check", "from-finding", "from-unresolved", "on", "origin-work"]);
+    const parsed = parseCommandArgs(args);
+    if (args[0] === "stage" && args[1] === "finish"
+        && ["result-file", "semantic-file", "data", "result-stdin"].filter(name => parsed.options.has(name)).length > 1) {
+        throw new AppError("usage", "Stage finish requires exactly one result input; result-file, semantic-file, data and result-stdin are mutually exclusive", 2);
+    }
+    for (const [name, values] of parsed.options) {
+        if (!repeatable.has(name) && values.length > 1)
+            throw new AppError("usage", `--${name} may be supplied only once`, 2);
+    }
+}
 function requiredPosition(parsed, index, label) {
     const value = parsed.positional[index];
     if (!value) {
@@ -2303,7 +2699,7 @@ function projectRootForMutation(context, args, result, resolvedScope) {
     if (family === "merge-queue") {
         return projectRootForMergeQueueMutation(context, command, parsed);
     }
-    if (family === "merge" && ["one-shot", "apply", "request"].includes(command ?? "")) {
+    if (family === "merge" && ["one-shot", "apply", "repair", "request"].includes(command ?? "")) {
         return requiredOption(parsed, "project-root");
     }
     if (family === "merge-worker" && ["start", "stop"].includes(command ?? "")) {
@@ -2336,7 +2732,7 @@ function projectRootForMutation(context, args, result, resolvedScope) {
     if (family === "opencode" && ((command === "event" && requiredPosition(parsed, 0, "opencode event action") === "handle") || command === "usage")) {
         return requiredOption(parsed, "project-root");
     }
-    if (family === "agy" && ((command === "event" && requiredPosition(parsed, 0, "agy event action") === "handle") || command === "usage"))
+    if (["agy", "droid"].includes(family ?? "") && ((command === "event" && requiredPosition(parsed, 0, `${family} event action`) === "handle") || command === "usage"))
         return requiredOption(parsed, "project-root");
     if (family === "codex" && command === "hooks") {
         const action = requiredPosition(parsed, 0, "codex hooks action");