@deksden-com/dd-flow-cli 0.9.0-beta.13 → 0.9.0-beta.134

package/dist/cli/run-cli.js

@@ -1,56 +1,83 @@
 import fs from "node:fs";
+import { requiredOption, optionalOption, optionalNumber, optionalPositiveNumber } from "./argument-values.js";
+import { resolveCommandPaths, resolveCommandProjectRoot } from "../services/command-context.js";
+import { assertAuxiliaryCommandScope, cliManagedInvocationScope, manualRecoveryInvocationScope, assertManualRecoveryInvocationTarget } from "../services/lifecycle-invocations.js";
 import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { quote } from "shell-quote";
+import { observeLifecycleCommand, observedLifecycleNativeEvent } from "../services/lifecycle-invocations.js";
+import { verifyCodexHookDelivery } from "../services/codex-hook-delivery.js";
+import { assertLifecycleInvocationCurrent, awaitLifecycleInvocation, bindLifecyclePublishedPacket, expandLifecycleInvocationArgs, issueLifecycleInvocation, prepareLifecycleIssuance, lifecycleInvocationScope, observedLifecycleDiagnostic, observedLifecycleInvocation, resolveObservedLifecycleArgs, retainObservedLifecycleSemantics, settleLifecycleInvocation, settleLifecyclePreparationRejection, settleLifecycleRejection, validateLifecyclePathAliases } from "../services/lifecycle-invocations.js";
 import { createContext, createRouterContext } from "../runtime/context.js";
+import { dispatchNativeHook, isNativeHookIngress } from "./native-hook-ingress.js";
+import { isRuntimeMaintenance, runtimeMaintenanceDiagnostics, withMaintenanceDiagnosticScope } from "./runtime-maintenance-diagnostics.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";
-import { archiveProject, getProjectStatus, migrateProjectIds, registerProject, resolveProject } from "../services/projects.js";
-import { cancelProtocol, getProtocolBlockers, getProtocolStatus, getReadyProtocols, implementProtocol, readyForMerge, registerProtocol, requireProtocol, syncProtocolFromRun, transitionProtocol } from "../services/protocols.js";
-import { blockPlanItem, completePlanItem, getPlanStatus, skipPlanItem, startPlanItem } from "../services/plans.js";
-import { cancelMergeQueueJob, claimNextMergeJob, claimMergeJob, claimMergeBundle, completeMergeBundle, completeMergeJob, failMergeBundle, failMergeJob, getMergeBundleStatus, getMergeQueueStatus, noteMergeJob, waitNextMergeJob } from "../services/merge-queue.js";
+import { AppError, errorRecord, isAppError } from "../shared/errors.js";
+import { entityReferenceVariants } from "../shared/entity-references.js";
+import { writeJson, parseJsonObject } from "../shared/json.js";
+import { archiveProject, prepareProjectArchive, getProjectStatus, migrateProjectIds, registerProject, resolveProject } from "../services/projects.js";
+import { cancelProtocol, getProtocolBlockers, getProtocolStatus, getReadyProtocols, implementProtocol, readyForMerge, registerProtocol, prepareProtocolRegistration, requireProtocol, syncProtocolFromRun, prepareProtocolTransition, transitionProtocol } from "../services/protocols.js";
+import { getPlanStatus, preparePlanItemMutation, updatePlanItem } from "../services/plans.js";
+import { cancelMergeQueueJob, prepareMergeQueueCancellation, prepareMergeQueueWait, prepareMergeClaim, prepareMergeBundleClaim, claimNextMergeJob, claimMergeJob, claimMergeBundle, completeMergeBundle, prepareMergeBundleCompletion, completeMergeJob, prepareMergeJobCompletion, failMergeBundle, prepareMergeBundleFailure, failMergeJob, prepareMergeJobFailure, getMergeBundleStatus, getMergeQueueStatus, noteMergeJob, prepareMergeJobNote, 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 { 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";
-import { getCanonStatus, registerCanonRoot, resolveCanonRoot } from "../services/canon.js";
+import { cleanupApply, cleanupScan, prepareCleanupApply } from "../services/cleanup.js";
+import { getCodexHomeStatus, getCodexHooksStatus, handleCodexHook, handleAgyEvent, handleDroidEvent, handleGrokEvent, handleOpenCodeEvent, handleZcodeHook, handleZcodeEvent, isolatedDdFlowHomeFromHookStdin, claimBootstrapHookEvent, findRecentMatchingHookEvent, stageStartMatchKey, initCodexHome, prepareCodexHome, prepareCodexHooks, installCodexHooks, planCodexHome, printCodexHomeEnv, printCodexHooks, removeCodexHome, prepareCodexHomeRemoval, removeCodexHooks } from "../services/hooks.js";
+import { bootstrapWorktree, closeWorktree, createWorktreeRecord, prepareWorktreeCreate, prepareWorktreeBootstrap, prepareWorktreeClose, getWorktreeStatus, planWorktree } from "../services/worktrees.js";
+import { acquireLaneLock, cancelLaneWaiter, prepareLaneWaiterCancellation, checkLaneWorkspace, getLaneWaiters, getLaneStatus, heartbeatLaneLock, releaseLaneLock, setLaneWorkspace, prepareLaneWorkspace, prepareLaneLock, waitAcquireLaneLock, waitForLaneLock } from "../services/lanes.js";
+import { getProjectConfigStatus, prepareProjectConfigValue, setProjectConfigValue } from "../services/config.js";
+import { getCanonStatus, registerCanonRoot, resolveCanonRoot, prepareCanonRegistration } from "../services/canon.js";
 import { getRuntimeStatus } from "../services/status.js";
 import { getCliVersionReport } from "../services/build-info.js";
 import { parseCommandArgs } from "../services/lifecycle-command.js";
-import { autoRefreshDashboards, dashboardData, getCmuxStatus, openDashboard, openGlobalDashboard, openProtocolDashboard, refreshAllDashboards, refreshDashboard, refreshGlobalDashboard, renderDashboard, renderGlobalDashboard } from "../services/dashboard.js";
+import { prepareError, prepareJsonFile, prepareJsonSchema, prepareJsonText, prepareTextFile } from "./input-preparation.js";
+import { autoRefreshDashboards, dashboardData, getCmuxStatus, openDashboard, openGlobalDashboard, openProtocolDashboard, refreshAllDashboards, prepareDashboardRefresh, prepareDashboardRender, prepareGlobalDashboardRender, prepareDashboardOptions, refreshDashboard, refreshGlobalDashboard, renderDashboard, renderGlobalDashboard } from "../services/dashboard.js";
 import { dashboardTargetSummary, preferredDashboardCommand, relatedDashboardCommands, resolveDashboardTarget } from "../services/dashboard-targets.js";
-import { getFlowSessionStatus, registerFlowSession, stopFlowSession, stopMergeWorker, syncFlowSessionUsage } from "../services/sessions.js";
+import { getFlowSessionStatus, prepareFlowSessionPayload, registerFlowSession, stopFlowSession, stopMergeWorker, syncFlowSessionUsage } from "../services/sessions.js";
 import { getProtocolBranchContext } from "../services/branch-context.js";
-import { attachFlowRunStage, completeFlowRun, completeFlowRunStage, getFlowRunSessions, getFlowRunTimeline, getStoredFlowRunUsage, getFlowRunFlagsStatus, getFlowRunStatus, getFlowRunConfig, getFlowRunVariables, listFlowRuns, reviseFlowRunFlags, setFlowRunConfig, setFlowRunVariable, startFlowRun } from "../services/runs.js";
+import { attachFlowRunStage, prepareFlowRunStageAttachment, prepareFlowRunStageCompletion, completeFlowRun, prepareFlowRunCompletion, completeFlowRunStage, getFlowRunSessions, getFlowRunTimeline, getStoredFlowRunUsage, getFlowRunFlagsStatus, getFlowRunStatus, getFlowRunConfig, getFlowRunVariables, listFlowRuns, reviseFlowRunFlags, setFlowRunConfig, prepareFlowRunConfig, prepareFlowRunVariable, setFlowRunVariable, startFlowRun, prepareFlowRunStart } from "../services/runs.js";
 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 { applyMigration, assessMigrationImpact, assertUpgradeRunStorageReady, planMigration, verifyMigrationReport } from "../services/migrations.js";
+import { ingestDroidUsage, ingestAgyUsage, ingestGrokUsage, ingestOpenCodeUsage, ingestZcodeUsage } from "../services/usage.js";
+import { applyMigration, assessMigrationImpact, assertUpgradeRunStorageReady, planMigration, prepareMigrationApply, verifyMigrationReport } from "../services/migrations.js";
 import { publishProjectSummary } from "../services/project-summary.js";
 import { requireProjectByRoot } from "../services/projects.js";
-import { resolveProjectRoot } from "../storage/paths.js";
-import { doctorEngines, bindRunEngine, engineInfo, installCurrentEngine, listEngines, resolveEngine, resolveExplicitProjectRoot, resolveOperationProjectRoot, routeArgsThroughEngine } from "../services/engines.js";
+import { resolveProjectRoot, resolveDdFlowHome } from "../storage/paths.js";
+import { doctorEngines, bindRunEngine, prepareRunEngineBind, engineInfo, installCurrentEngine, listEngines, resolveEngine, resolveExplicitProjectRoot, resolveOperationProjectRoot, routeArgsThroughEngine } from "../services/engines.js";
 import { preflightCliCompatibility } from "../services/compatibility-preflight.js";
-import { finishVnextSpecifyStage, getVnextWorkStatus, isVnextSpecifyFlow, isVnextSpecifyRun, launchVnextSpecify } from "../services/vnext-specify.js";
-import { finishVnextProtocolize, isVnextProtocolizeRun, startVnextProtocolize } from "../services/vnext-protocolize.js";
-import { finishVnextPlan, isVnextPlanRun, startVnextPlan } from "../services/vnext-plan.js";
-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, repairVnextMerge, routeVnextMergeRequest, startVnextMerge } from "../services/vnext-merge.js";
+import { finishVnextSpecifyStage, getVnextWorkStatus, isVnextSpecifyFlow, isVnextSpecifyRun, launchVnextSpecify, prepareVnextSpecifyStart } from "../services/vnext-specify.js";
+import { finishVnextProtocolize, isVnextProtocolizeRun, prepareProtocolizeResultPath, prepareVnextProtocolizeStart, startVnextProtocolize } from "../services/vnext-protocolize.js";
+import { finishVnextPlan, isVnextPlanRun, startVnextPlan, prepareVnextPlanStart, prepareVnextPlanFinish } from "../services/vnext-plan.js";
+import { dispatchVnextPlanReview, finishVnextPlanReview, isVnextPlanReviewRun, prepareVnextPlanReviewStart, recordVnextPlanReviewCapacity, startVnextPlanReview } from "../services/vnext-plan-review.js";
+import { addVnextCodeRepair, finishVnextCode, prepareVnextCodeRepair, prepareVnextCodeStart, startVnextCode } from "../services/vnext-code.js";
+import { finishVnextCodeReview, isVnextCodeReviewRun, prepareCodeReviewDecision, prepareVnextCodeReviewRepair, prepareVnextCodeReviewStart, startVnextCodeReview } from "../services/vnext-code-review.js";
+import { applyVnextMerge, finishVnextMerge, getVnextMergeRequest, isVnextMergeRun, prepareVnextMergeFinish, prepareVnextMergeStart, 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 { pauseStageForUser, resumeStageAfterUser } from "../services/stage-pause.js";
-import { blockStageForRuntime, unblockStageAfterRuntimeRepair } from "../services/stage-blocker.js";
+import { getVnextFanoutStatus, observeVnextNativeChildren, prepareNativeObservations, reconcileVnextFanout } from "../services/vnext-fanout.js";
+import { pauseStageForUser, resumeStageAfterUser, prepareStagePause, prepareStageResume } from "../services/stage-pause.js";
+import { blockStageForRuntime, unblockStageAfterRuntimeRepair, prepareStageRuntimeBlock, prepareStageRuntimeUnblock } 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 { createEvalBootstrapSnapshot, createEvalRunSnapshot, prepareVnextSpecifyRun, restoreEvalBootstrapSnapshot, restoreEvalRunSnapshot } from "../services/eval-snapshots.js";
-import { loadExternalStageContext } from "../services/stage-context.js";
-import { confirmManagedProcess, finishManagedProcess, heartbeatManagedProcess, managedProcessStatus, reconcileExpiredManagedProcesses, registerManagedProcess } from "../services/managed-processes.js";
+import { prepareWorkerPrompt, renderWorkerPrompt } from "../services/prompts.js";
+import { finishStage, prepareStageFinish, startStage, prepareLegacyStageStart } from "../services/stage-lifecycle.js";
+import { addWorkBatch, prepareWorkBatch, prepareWorkDeps, prepareWorkDelete, prepareWorkSettlement, prepareWorkRetry, assertStageLifecycleOwner, assertWorkLifecycleOwner, cancelWork, deleteWork, failWork, finishWork, listWorks, mutateWorkDeps, prepareWorkResult, retryWork, showWork, startWork } from "../services/work-registry.js";
+import { launchExternalWork } from "../services/external-work-launch.js";
+import { createEvalBootstrapSnapshot, prepareEvalBootstrapSnapshot, createEvalRunSnapshot, prepareEvalRunSnapshotCreation, prepareVnextSpecifyRun, prepareEvalRunRestore, prepareEvalBootstrapRestore, restoreEvalBootstrapSnapshot, restoreEvalRunSnapshot } from "../services/eval-snapshots.js";
+import { forkRunFromSnapshot, prepareRunFork } from "../services/run-fork.js";
+import { acceptRunRecovery, beginRunRecovery, inspectRunRecovery, prepareRecoveryCapture, prepareRecoveryPayload, prepareRunRecoveryResume, recordRecoveryCapture, resumeRunRecovery, sealRunRecovery } from "../services/run-recovery.js";
+import { loadExternalStageContext, prepareExternalStageContext } from "../services/stage-context.js";
+import { vnextStageDirectory } from "../domain/stage-catalog.js";
+import { prepareCommandRoute } from "./command-inputs.js";
+import { parseLifecycleCommand } from "../services/lifecycle-command.js";
+import { dispatchRuntimeProcess, prepareRuntimeProcess } from "./runtime-process.js";
+import { fenceRuntimeBudget, runtimeBudgetStatus, prepareRuntimeScopeControl, prepareRuntimeScopeFence } from "../services/runtime-budget.js";
+import { stopRuntimeScope } from "../services/runtime-scope-stop.js";
+import { launchRuntimeScopeControl, launchRuntimeScopeResume, prepareRuntimeScopeReconciliation, prepareRuntimeScopeServing, reconcileRuntimeScopeControl, serveRuntimeScopeControl } from "../services/runtime-scope-worker.js";
+import { prepareRuntimeScopeResumeRequest } from "../services/runtime-scope-resume.js";
+import { launchRunController, prepareRunControllerLaunch, resumeRunController, serveRunController, runControllerStatus, answerRunController, prepareRunControllerAnswer, supplyRunControllerContext, prepareRunControllerContext } from "../services/run-controller.js";
+import { controlLifecycleReply, runControlStatus } from "../services/run-control.js";
+import { reconcileRunControl, requestRunControl, serveRunControl } from "../services/run-control-worker.js";
+import { startRuntimeService, prepareRuntimeService } from "../services/runtime-service.js";
 const defaultIo = {
     stdout: process.stdout,
     stderr: process.stderr,
@@ -58,9 +85,43 @@ const defaultIo = {
 };
 const flagValue = "__dd_flow_flag__";
 export async function runCli(args, io = defaultIo, env = process.env) {
-    const output = parseOutputOptions(args);
+    return withMaintenanceDiagnosticScope(() => runCliRequest(args, io, env));
+}
+async function runCliRequest(args, io, env) {
+    let output;
+    try {
+        output = parseOutputOptions(args);
+    }
+    catch (error) {
+        const rejection = isAppError(error) ? error : new AppError("usage", error instanceof Error ? error.message : String(error), 2);
+        Object.assign(rejection.details, { phase: "prepare", effect: "no_effect", recoverable: true, ...rejection.details });
+        try {
+            const command = quote(["dd-flow", ...args]);
+            const analysis = parseLifecycleCommand(command);
+            const event = analysis.kind !== "none" || analysis.auxiliary
+                ? observedLifecycleNativeEvent(createRouterContext(env), command, env.DD_FLOW_DAEMON_ID) : null;
+            if (event) {
+                const context = createContext({ ...env }, "hook");
+                try {
+                    observeLifecycleCommand(context, command, event)({ error: rejection });
+                }
+                finally {
+                    context.db.close?.();
+                }
+            }
+        }
+        catch (persistence) {
+            rejection.details.lifecycle_diagnostic_error = String(persistence);
+        }
+        writeJson(io.stderr, { ok: false, error: errorRecord(rejection) });
+        return rejection.exitCode;
+    }
     const progress = progressForCommand(output.args);
     let heartbeat;
+    let invocationSettlement;
+    let settleHook;
+    let diagnosticHome;
+    let maintenanceDiagnostics;
     try {
         if (output.args.length === 1 && output.args[0] === "--version") {
             const payload = getCliVersionReport();
@@ -75,6 +136,50 @@ export async function runCli(args, io = defaultIo, env = process.env) {
             io.stdout.write(`${help}\n`);
             return 0;
         }
+        const suppliedInvocationId = optionalOption(parseArgs(output.args.slice(2)), "invocation-id");
+        if (isNativeHookIngress(output.args)) {
+            writeJson(io.stdout, await dispatchNativeHook(output.args, await readStdin(io.stdin), env));
+            return 0;
+        }
+        if (output.args.slice(0, 3).join(" ") === "codex hook handle") {
+            const parsed = prepareCommandRoute(output.args).parsed;
+            const stdin = await readStdin(io.stdin);
+            const payload = parseJsonObject(stdin || "{}", "codex hook stdin");
+            const event = requiredOption(parsed, "event");
+            const isolatedHome = event === "PreToolUse" ? isolatedDdFlowHomeFromHookStdin(stdin) : null;
+            const hookEnv = isolatedHome ? { ...env, DD_FLOW_HOME: isolatedHome } : env;
+            const proof = await verifyCodexHookDelivery(hookEnv, payload);
+            let opened;
+            const mode = databaseModeForCommand(output.args, classifyCliOperation(output.args, hookEnv));
+            const context = {
+                env: hookEnv, ddFlowHome: resolveDdFlowHome(hookEnv), now: () => new Date().toISOString(),
+                get db() { return (opened ??= createContext(hookEnv, mode)).db; }
+            };
+            try {
+                // Retired events retain the explicit startup/migration path. PreToolUse
+                // only opens its selected prepared store when the handler needs it.
+                if (mode !== "hook")
+                    opened = createContext(hookEnv, mode);
+                if (proof)
+                    context.codexHookProof = proof;
+                const result = handleCodexHook(context, { event, projectRoot: optionalOption(parsed, "project-root"), stdin });
+                writeJson(io.stdout, result && typeof result === "object" && !Array.isArray(result) && "hookSpecificOutput" in result
+                    ? { hookSpecificOutput: result.hookSpecificOutput } : {});
+                return 0;
+            }
+            finally {
+                opened?.db.close?.();
+            }
+        }
+        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, {
@@ -82,26 +187,189 @@ export async function runCli(args, io = defaultIo, env = process.env) {
                 required_marker: "DD_FLOW_COMPATIBILITY_MODE=mb-upgrade"
             });
         }
-        const routerContext = createRouterContext(env);
+        // Registration may bootstrap the resource registry, but never the unrelated
+        // RUN store. Its caller's absolute deadline also bounds that first open.
+        const maintenanceOptions = isRuntimeMaintenance(output.args) ? { resourceDatabaseMode: output.args[2] === "register" ? "initialize" : output.args[2] === "status" ? "read_existing" : "prepared_existing", ...(env.DD_FLOW_HOOK_DEADLINE_AT ? { databaseDeadlineAt: Number(env.DD_FLOW_HOOK_DEADLINE_AT) } : {}) } : {};
+        // Keep ordinary CLI JSON/stderr compatibility; bounded maintenance callers
+        // provide this request's deadline and consume its structured phase evidence.
+        if (maintenanceOptions.databaseDeadlineAt !== undefined)
+            maintenanceDiagnostics = runtimeMaintenanceDiagnostics(output.args, maintenanceOptions.databaseDeadlineAt, line => io.stderr.write(line));
+        const routerContext = createRouterContext(env, maintenanceOptions.databaseDeadlineAt);
+        const publicCommand = quote(["dd-flow", ...output.args]);
+        const nativeCommand = quote(["dd-flow", ...args]);
+        const lifecycleCommand = parseLifecycleCommand(publicCommand);
+        if (lifecycleCommand.kind === "standalone")
+            validateLifecyclePathAliases(output.args, lifecycleCommand.invocation.operation);
+        const managedScope = lifecycleCommand.kind === "standalone" && env.DD_FLOW_DAEMON_ID ? cliManagedInvocationScope({ ...routerContext, env }) : null;
+        const nativeEvent = env.DD_FLOW_DAEMON_ID && lifecycleCommand.kind === "standalone"
+            ? observedLifecycleNativeEvent(routerContext, nativeCommand, env.DD_FLOW_DAEMON_ID) : null;
+        const nativeEventKey = nativeEvent && routerContext.db.get("SELECT event_key FROM hook_events WHERE project_id = ? AND id = ?", [nativeEvent.project_id, nativeEvent.id])?.event_key;
+        const observedInvocation = managedScope ? observedLifecycleInvocation(routerContext, publicCommand, managedScope, nativeEventKey ? { eventKey: nativeEventKey } : undefined) : null;
+        if (managedScope && suppliedInvocationId
+            && routerContext.db.get("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'lifecycle_invocations'")
+            && routerContext.db.get("SELECT id FROM lifecycle_invocations WHERE id = ?", [suppliedInvocationId])) {
+            const suppliedScope = lifecycleInvocationScope({ ...routerContext, env }, suppliedInvocationId);
+            if (["projectRoot", "daemonId", "rootSessionId", "runId", "generation"].some(key => suppliedScope[key] !== managedScope[key])) {
+                throw new AppError("invocation_scope_mismatch", "Explicit lifecycle assignment differs from the current physical native owner", 1, { effect: "no_effect", recoverable: false });
+            }
+        }
+        const diagnostic = env.DD_FLOW_DAEMON_ID && lifecycleCommand.kind === "standalone"
+            ? observedLifecycleDiagnostic(routerContext, publicCommand, env.DD_FLOW_DAEMON_ID, observedInvocation?.id) : null;
+        if (diagnostic && (!nativeEvent || Number(diagnostic.hook_event_id) > nativeEvent.id)) {
+            throw new AppError("lifecycle_shell_syntax_invalid", `Native observer rejected the shell form: ${String(diagnostic.reason ?? "unsupported shell composition")}. Write structured input to a file and run the returned dd-flow command separately.`, 2, { ...diagnostic, phase: "prepare", effect: "no_effect", recoverable: true });
+        }
+        let manualRecoveryHookEventKey;
+        if (!observedInvocation && !suppliedInvocationId && env.DD_FLOW_DAEMON_ID && lifecycleCommand.kind === "standalone") {
+            const receipt = nativeEvent && routerContext.db.get("SELECT event_key,harness,provider_session_id,parent_session_id,daemon_id,status FROM hook_events WHERE id = ? AND project_id = ?", [nativeEvent.id, nativeEvent.project_id]);
+            const manual = managedScope && receipt?.status === "observed" ? manualRecoveryInvocationScope({ ...routerContext, env }, managedScope.projectRoot, { daemonId: receipt.daemon_id, rootSessionId: receipt.provider_session_id, sessionId: receipt.provider_session_id, parentSessionId: receipt.parent_session_id, toolCallId: String(nativeEvent.id) }, receipt.harness) : null;
+            if (!manual || JSON.stringify(manual) !== JSON.stringify(managedScope))
+                throw new AppError(nativeEvent ? "invocation_assignment_missing" : "invocation_receipt_missing", nativeEvent ? "Native call was observed, but its arguments do not match an issued lifecycle assignment" : "Managed lifecycle command has no committed native receipt", 1, { effect: "no_effect", recoverable: false });
+            assertManualRecoveryInvocationTarget({ ...routerContext, env }, manual, publicCommand);
+            manualRecoveryHookEventKey = receipt.event_key;
+        }
+        const invocationId = observedInvocation?.id ?? suppliedInvocationId;
+        let boundInvocationArgs;
+        try {
+            boundInvocationArgs = observedInvocation
+                ? resolveObservedLifecycleArgs(routerContext, observedInvocation.id, output.args)
+                : invocationId && invocationId !== suppliedInvocationId
+                    ? [...output.args.filter((_, index, values) => values[index - 1] !== "--invocation-id" && values[index] !== "--invocation-id"), "--invocation-id", invocationId]
+                    : output.args;
+        }
+        catch (error) {
+            if (!(observedInvocation && error instanceof AppError))
+                throw error;
+            const rejectionContext = createContext({ ...env }, "hook");
+            try {
+                Object.assign(error.details, settleLifecyclePreparationRejection(rejectionContext, observedInvocation.id, error));
+            }
+            finally {
+                rejectionContext.db.close?.();
+            }
+            throw error;
+        }
+        const observedOperation = lifecycleCommand.kind === "standalone" ? lifecycleCommand.invocation.operation : null;
+        if (observedInvocation && !observedOperation)
+            throw new AppError("invocation_command_invalid", "Observed lifecycle command could not be parsed", 1);
+        const invocationScope = invocationId ? lifecycleInvocationScope({ ...routerContext, env }, invocationId) : undefined;
+        const expandedInvocationArgs = invocationScope && observedOperation
+            ? expandLifecycleInvocationArgs(routerContext, boundInvocationArgs, invocationScope, observedOperation)
+            : boundInvocationArgs;
+        const retainedOutput = observedInvocation ? parseOutputOptions(expandedInvocationArgs) : null;
+        if (retainedOutput?.responseFile)
+            output.responseFile = retainedOutput.responseFile;
+        let invocationArgs = retainedOutput?.args ?? expandedInvocationArgs;
         emitHumanProgress(io, output, progress, "start");
         if (output.progressJsonl) {
             writeProgressJsonl(io, "start", `Starting ${output.args.slice(0, 3).join(" ")}`);
             heartbeat = setInterval(() => writeProgressJsonl(io, "running", "Command is still running"), 15_000);
         }
-        const scopeProjectRoot = resolveProjectRootBeforeRouting(output.args, env);
-        const routedArgs = output.responseFile ? [...output.args, "--response-file", output.responseFile] : output.args;
+        // Route by retained authority, so a mistyped project path reaches the CLI
+        // validator instead of selecting a different engine or failing preflight.
+        const scopeProjectRoot = invocationScope?.projectRoot ?? resolveCommandProjectRoot(routerContext, output.args, resolveProjectRootBeforeRouting(output.args, env, maintenanceOptions.databaseDeadlineAt));
+        assertAuxiliaryCommandScope({ ...routerContext, env }, publicCommand, scopeProjectRoot);
+        invocationArgs = resolveCommandPaths(routerContext, invocationArgs, scopeProjectRoot);
+        const routedArgs = output.responseFile ? [...invocationArgs, "--response-file", output.responseFile] : invocationArgs;
         const routed = await routeArgsThroughEngine(routerContext, output.json ? [...routedArgs, "--json", ...(output.progressJsonl ? ["--progress-jsonl"] : [])] : routedArgs, io, io.stdin, env, scopeProjectRoot);
         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;
         }
+        let preparedInput;
+        let preparedRoute;
+        if (!invocationId) {
+            const preparationContext = createContext({ ...env }, "read_existing", undefined, maintenanceOptions);
+            try {
+                preparedInput = await prepareCliInput(invocationArgs, preparationContext, io, scopeProjectRoot, output.responseFile);
+            }
+            finally {
+                preparationContext.db.close?.();
+            }
+        }
         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));
-        preflightCliCompatibility(dispatchContext, output.args, env, scopeProjectRoot);
-        const result = await dispatch(output.args, dispatchContext, io, scopeProjectRoot, classification, output);
+            ? createContext({ ...env, DD_FLOW_ENGINE_MODE: "1", DD_FLOW_ENGINE_HOME: "in-process", DD_FLOW_ROUTED_FROM: getCliVersionReport().cli.version }, databaseModeForCommand(invocationArgs, classification), undefined, maintenanceOptions)
+            : createContext({ ...env }, databaseModeForCommand(invocationArgs, classification), undefined, maintenanceOptions);
+        diagnosticHome = dispatchContext.ddFlowHome;
+        dispatchContext.env.DD_FLOW_INVOCATION_READONLY = classification.mode === "read_only_diagnostics" ? "1" : undefined;
+        let dispatchArgs = invocationArgs;
+        let retainedOutcome;
+        // Issued transports may deliver their receipt asynchronously. Observe only
+        // after admission; retained outcomes must not need a fresh hook receipt.
+        if (invocationId) {
+            const command = quote(["dd-flow", ...invocationArgs]);
+            const admission = await awaitLifecycleInvocation(dispatchContext, { id: invocationId, command,
+                validateArgs: () => {
+                    try {
+                        preparedRoute = prepareCommandRoute(invocationArgs);
+                    }
+                    catch (error) {
+                        if (error instanceof AppError && error.code === "usage" && ["invocation-id", "hook-event-id"].includes(String(error.details.parameter ?? ""))) {
+                            throw new AppError("lifecycle_contract_invalid", `The runtime generated arguments rejected by its own CLI contract: ${error.message}`, 1, { ...error.details, recoverable: false, operation: observedOperation });
+                        }
+                        throw error;
+                    }
+                },
+                prepare: async () => { preparedInput = await prepareCliInput(invocationArgs, dispatchContext, io, scopeProjectRoot, output.responseFile, preparedRoute); },
+                assertCurrent: scope => assertLifecycleInvocationCurrent(dispatchContext, scope, command) });
+            if (admission.replay) {
+                retainedOutcome = admission.outcome;
+                settleHook = undefined;
+                delete dispatchContext.observeLifecycleHook;
+            }
+            else {
+                invocationSettlement = { context: dispatchContext, id: invocationId };
+                if (observedInvocation)
+                    retainObservedLifecycleSemantics(dispatchContext, invocationId, invocationArgs);
+                dispatchArgs = [...invocationArgs, "--hook-event-id", admission.eventKey];
+                preparedInput?.route?.parsed.options.set("hook-event-id", [admission.eventKey]);
+                dispatchContext.env.DD_FLOW_INVOCATION_SCOPE = JSON.stringify(lifecycleInvocationScope(dispatchContext, invocationId));
+                dispatchContext.env.DD_FLOW_CURRENT_INVOCATION = invocationId;
+            }
+        }
+        if (!invocationId && manualRecoveryHookEventKey) {
+            // Keep the physically scoped receipt selected by admission; a service must
+            // not rediscover a different daemon's matching command event.
+            if (!invocationArgs.includes("--hook-event-id"))
+                dispatchArgs = [...invocationArgs, "--hook-event-id", manualRecoveryHookEventKey];
+            preparedInput?.route?.parsed.options.set("hook-event-id", [manualRecoveryHookEventKey]);
+        }
+        if (retainedOutcome?.error) {
+            const error = retainedOutcome.error;
+            throw new AppError(error.code, error.message, error.exitCode, error.details);
+        }
+        if (!retainedOutcome && !preparedInput)
+            preparedInput = await prepareCliInput(invocationArgs, dispatchContext, io, scopeProjectRoot, output.responseFile);
+        if (!retainedOutcome)
+            await preflightCliCompatibility(dispatchContext, invocationArgs, env, scopeProjectRoot);
+        if (!retainedOutcome) {
+            const command = !invocationId ? nativeCommand : quote(["dd-flow", ...dispatchArgs]);
+            const event = !invocationId ? nativeEvent : null;
+            settleHook = observeLifecycleCommand(dispatchContext, command, event ?? undefined);
+        }
+        const result = retainedOutcome ? retainedOutcome.result : await dispatch(dispatchArgs, dispatchContext, io, scopeProjectRoot, classification, output, preparedInput);
+        if (!retainedOutcome && invocationArgs[0] === "stage" && invocationArgs[1] === "start"
+            && result && typeof result === "object" && "prompt_path" in result && typeof result.prompt_path === "string") {
+            try {
+                bindLifecyclePublishedPacket(dispatchContext, fs.readFileSync(result.prompt_path, "utf8"));
+            }
+            catch (cause) {
+                throw new AppError("invocation_packet_binding_failed", "Stage started but its published lifecycle assignments could not be retained", 1, { effect: "committed", cause: String(cause) });
+            }
+        }
+        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)
@@ -111,23 +379,99 @@ export async function runCli(args, io = defaultIo, env = process.env) {
         emitHumanProgress(io, output, progress, "done");
         const payload = attachProgress(resultWithWarnings, progress, output);
         const visible = writeResponseFile(payload, output);
+        const maintenanceReceipt = payload;
+        const maintenanceExpiry = maintenanceReceipt?.lease_expires_at ?? maintenanceReceipt?.process?.lease_expires_at;
+        maintenanceDiagnostics?.phase("ack", { ...(typeof maintenanceExpiry === "string" && Number.isFinite(Date.parse(maintenanceExpiry)) ? { lease_expires_at: maintenanceExpiry } : {}) });
         if (output.json)
             writeJson(io.stdout, visible);
         else
             io.stdout.write(renderHumanResult(output.args, payload));
         return completedCommandExitCode(payload);
     }
-    catch (error) {
+    catch (caught) {
+        const record = errorRecord(caught);
+        maintenanceDiagnostics?.failure(caught);
+        const error = isAppError(caught) ? caught : Object.assign(new AppError(record.code, record.message, record.exitCode, { effect: "unknown", ...record.details, ...(caught?.errcode !== undefined ? { sqlite_extended_code: caught.errcode } : {}) }), { ...(record.cause ? { cause: record.cause } : {}), ...(record.cleanup_error ? { cleanup_error: record.cleanup_error } : {}), ...(record.retryable !== undefined ? { retryable: record.retryable } : {}) });
+        if (!settleHook && !invocationSettlement) {
+            let earlyContext;
+            try {
+                const command = quote(["dd-flow", ...args]);
+                const analysis = parseLifecycleCommand(command);
+                // Maintenance failures must not start an unrelated, unbounded hook
+                // lookup after their own request deadline has already expired.
+                const router = analysis.kind !== "none" || analysis.auxiliary ? createRouterContext(env) : null;
+                const event = router ? observedLifecycleNativeEvent(router, command, env.DD_FLOW_DAEMON_ID) : null;
+                // A correctable prepare rejection precedes the terminal command's
+                // single-use claim. Correlate its unique hook by the same lifecycle
+                // match key used at dispatch, including compound provider tool shells;
+                // otherwise a repaired retry sees two fresh, unclaimed events.
+                if (router && (event || (error.details.phase === "prepare" && error.details.effect === "no_effect"
+                    && fs.existsSync(path.join(router.ddFlowHome, "db.sqlite"))))) {
+                    earlyContext = createContext({ ...env }, "hook");
+                    observeLifecycleCommand(earlyContext, command, event ?? undefined)({ error });
+                }
+            }
+            catch (persistence) {
+                error.details.lifecycle_diagnostic_error = String(persistence);
+            }
+            finally {
+                earlyContext?.db.close?.();
+            }
+        }
+        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);
-        const payload = isAppError(error)
-            ? { ok: false, error: { code: error.code, message: error.message, details: error.details } }
-            : { ok: false, error: { code: "unexpected", message: String(error) } };
+        if (invocationSettlement && error.details.effect !== "committed") {
+            try {
+                if (isAppError(error)) {
+                    const settled = errorRecord(error);
+                    settleLifecycleRejection(invocationSettlement.context, invocationSettlement.id, settled);
+                    // Serialization owns a copy. Publish the committed settlement, not
+                    // the original rejection which has no successor authority.
+                    Object.assign(error.details, settled.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 = { ok: false, error: errorRecord(error) };
+        progress.splice(0, progress.length, ...progress.filter(event => event.phase !== "done"));
+        if (progress.length)
+            progress.push({ phase: "failed", message: payload.error.message, at: new Date().toISOString() });
         emitHumanProgress(io, output, progress, "failed");
         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 {
+            if (error.details.parameter !== "response-file")
+                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)
@@ -136,22 +480,50 @@ export async function runCli(args, io = defaultIo, env = process.env) {
             io.stderr.write(renderHumanError(payload));
         return isAppError(error) ? error.exitCode : 1;
     }
+    finally {
+        maintenanceDiagnostics?.close();
+    }
 }
-function resolveProjectRootBeforeRouting(args, env) {
+function resolveProjectRootBeforeRouting(args, env, deadlineAt) {
     const explicit = resolveExplicitProjectRoot(args);
     if (explicit)
         return explicit;
     try {
         // Router identity lookup is read-only; it must not initialize or migrate runtime storage.
-        return resolveOperationProjectRoot(createContext(env, "read_existing"), args);
+        const context = createContext(env, "read_existing", undefined, deadlineAt === undefined ? {} : { databaseDeadlineAt: deadlineAt });
+        try {
+            return resolveOperationProjectRoot(context, args);
+        }
+        finally {
+            context.db.close?.();
+        }
     }
     catch {
         return null;
     }
 }
 function databaseModeForCommand(args, classification) {
+    if (isNativeHookIngress(args))
+        return "hook";
+    if (isRuntimeMaintenance(args))
+        return "read_existing";
     const [family, command] = args;
+    // Managed attempts are issued only from a prepared store. Opening that
+    // existing writer must not run migrations before their input is admitted.
+    if (parseArgs(args.slice(2)).options.has("invocation-id"))
+        return "hook";
+    // Native hook ingress must remain synchronous, but it must not run schema
+    // migration/VACUUM while the provider is waiting for its decision.  Startup
+    // prepares the store; the hook mode only verifies the prepared contract and
+    // records the receipt.
+    if (family === "codex" && command === "hook" && args[2] === "handle") {
+        // Only the participating PreToolUse ingress needs the prepared hot-path
+        // contract. SessionStart/Stop/PostToolUse are observational no-ops here
+        // and retain the ordinary startup path for backwards compatibility.
+        return optionalOption(parseArgs(args.slice(3)), "event") === "PreToolUse" ? "hook" : "initialize";
+    }
     if (family === "engine" ||
+        family === "storage" && command === "migrate-writer" ||
         family === "version" ||
         family === "schema" ||
         family === "canon" && command === "resolve" ||
@@ -207,8 +579,10 @@ function parseOutputOptions(args) {
             continue;
         }
         if (arg === "--response-file") {
+            if (responseFile !== null)
+                throw new AppError("usage", "--response-file may be supplied only once", 2);
             const file = args[++index];
-            if (!file)
+            if (!file?.trim() || file.startsWith("--"))
                 throw new AppError("usage", "--response-file requires a path", 2);
             responseFile = file;
             continue;
@@ -220,6 +594,33 @@ function parseOutputOptions(args) {
     const hookJsonOnly = stripped[0] === "codex" && stripped[1] === "hook" && stripped[2] === "handle";
     return { json: json || hookJsonOnly, progressJsonl, args: stripped, hookJsonOnly, responseFile };
 }
+/** Validate the response destination without creating it.  The response is an
+ * optional publication, but a known-bad destination should never be found
+ * only after a successful lifecycle mutation. */
+function prepareResponseDestination(value) {
+    const file = path.resolve(value);
+    const parent = path.dirname(file);
+    try {
+        let ancestor = parent;
+        for (;;) {
+            try {
+                if (!fs.statSync(ancestor).isDirectory())
+                    throw new AppError("response_file_parent_invalid", "--response-file parent must be a directory", 2, { file, parent });
+                break;
+            }
+            catch (error) {
+                if (error.code !== "ENOENT" || path.dirname(ancestor) === ancestor)
+                    throw error;
+                ancestor = path.dirname(ancestor);
+            }
+        }
+        if (fs.existsSync(file) && !fs.statSync(file).isFile())
+            throw new AppError("response_file_invalid", "--response-file must name a regular file", 2, { file });
+    }
+    catch (error) {
+        return prepareError(error, { parameter: "response-file", file, parent });
+    }
+}
 /** Persist the complete machine response for harnesses that cap tool output.
  * The visible response keeps routing fields but omits the potentially large
  * rendered prompt; an agent can safely read the named file without rerunning
@@ -500,27 +901,636 @@ function stringValue(value) {
 function shortSha(value) {
     return value ? value.slice(0, 12) : "unknown";
 }
-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);
+/** All caller supplied file/stdin data is consumed here, before a managed
+ * invocation is allowed to claim execution or a stage claims its hook event. */
+async function prepareCliInput(...args) {
+    try {
+        return await prepareCliInputValue(...args);
+    }
+    catch (error) {
+        return prepareError(error);
+    }
+}
+async function prepareCliInputValue(args, context, io, scopeProjectRoot, responseFile = null, route = prepareCommandRoute(args)) {
+    const { family, command, parsed } = route;
+    const prepared = { route };
+    if (optionalOption(parsed, "reason-file")) {
+        const value = prepareJsonFile(requiredOption(parsed, "reason-file"), "Check recovery evidence").value;
+        if (!value || typeof value.reason !== "string" || !value.reason.trim() || Object.keys(value).some(key => key !== "reason"))
+            throw new AppError("validation", "Recovery evidence must be a JSON object with one nonempty reason", 2);
+        prepared.retryReason = value.reason;
+    }
+    else if (optionalOption(parsed, "retry-check"))
+        prepared.retryReason = optionalOption(parsed, "reason");
+    if (route.key === "project register")
+        resolveProjectRoot(requiredOption(parsed, "root"));
+    if (route.key === "project archive")
+        prepareProjectArchive(context, { idOrAlias: parsed.positional[0], root: optionalOption(parsed, "root"), reason: requiredOption(parsed, "reason") });
+    if (route.key === "protocol register")
+        prepareProtocolRegistration(context, { handshakeId: requiredPosition(parsed, 0, "handshake-id"), projectRoot: requiredOption(parsed, "project-root"), workspacePath: optionalOption(parsed, "workspace-path") });
+    if (route.key === "canon register")
+        prepared.canonRegistration = prepareCanonRegistration(context, { root: requiredOption(parsed, "root") });
+    if (route.key === "run attach-stage")
+        prepareFlowRunStageAttachment(context, stageAttachmentInput(parsed));
+    if (route.key === "run complete-stage")
+        prepareFlowRunStageCompletion(context, stageCompletionInput(parsed));
+    if (route.key === "run override")
+        prepareFlowRunCompletion(context, runOverrideInput(parsed));
+    if (route.key === "engine bind-run")
+        prepared.engineBind = await prepareRunEngineBind(context, engineBindInput(parsed));
+    if (route.key === "worktree create")
+        prepared.worktreeCreate = prepareWorktreeCreate(context, { protocolId: requiredOption(parsed, "protocol-id"), projectRoot: requiredScopeProjectRoot(scopeProjectRoot, "worktree create"), branch: requiredOption(parsed, "branch"), base: requiredOption(parsed, "base"), path: requiredOption(parsed, "path") });
+    if (route.key === "worktree bootstrap")
+        prepared.worktreeBootstrap = prepareWorktreeBootstrap(context, { protocolId: requiredOption(parsed, "protocol-id"), projectRoot: requiredScopeProjectRoot(scopeProjectRoot, "worktree bootstrap") });
+    if (route.key === "worktree close")
+        prepareWorktreeClose(context, { protocolId: requiredOption(parsed, "protocol-id"), projectRoot: requiredScopeProjectRoot(scopeProjectRoot, "worktree close"), mode: requiredOption(parsed, "mode") });
+    if (route.key.startsWith("plan item "))
+        preparePlanItemMutation(context, planItemInput(parsed, requiredScopeProjectRoot(scopeProjectRoot, route.key)));
+    if (route.key === "lane workspace set")
+        prepareLaneWorkspace(context, laneWorkspaceInput(parsed));
+    if (route.key === "lane waiter cancel")
+        prepareLaneWaiterCancellation(context, laneWaiterCancelInput(parsed));
+    if (route.key === "merge-queue complete")
+        prepareMergeJobCompletion(context, { ...mergeJobTarget(parsed, scopeProjectRoot), summary: requiredOption(parsed, "summary") });
+    if (route.key === "merge-queue cancel")
+        prepareMergeQueueCancellation(context, mergeCancellationInput(parsed, scopeProjectRoot));
+    if (route.key === "merge-queue wait-next")
+        prepareMergeQueueWait(context, mergeWaitInput(parsed, scopeProjectRoot));
+    if (route.key === "merge-queue next" || route.key === "merge-queue claim")
+        prepareMergeClaim(context, { projectRoot: requiredOptionOrScope(parsed, scopeProjectRoot, "project-root"), workerId: requiredWorkerId(parsed), workspacePath: workspacePathOption(parsed), ...(route.key === "merge-queue claim" ? { protocolId: requiredPosition(parsed, 0, "protocol-id") } : {}) });
+    if (route.key === "merge-queue note")
+        prepareMergeJobNote(context, { protocolId: requiredPosition(parsed, 0, "protocol-id"), projectRoot: requiredScopeProjectRoot(scopeProjectRoot, "merge-queue note"), workerId: requiredWorkerId(parsed), summary: requiredOption(parsed, "summary") });
+    if (route.key === "merge bundle complete")
+        prepareMergeBundleCompletion(context, { projectRoot: requiredOption(parsed, "project-root"), workspacePath: workspacePathOption(parsed), workerId: requiredWorkerId(parsed), summary: requiredOption(parsed, "summary") });
+    if (route.key === "merge bundle claim")
+        prepareMergeBundleClaim(context, { projectRoot: requiredOption(parsed, "project-root"), workspacePath: workspacePathOption(parsed), workerId: requiredWorkerId(parsed) });
+    if (route.key === "merge bundle fail")
+        prepareMergeBundleFailure(context, { projectRoot: requiredOption(parsed, "project-root"), workspacePath: workspacePathOption(parsed), workerId: requiredWorkerId(parsed), reason: requiredOption(parsed, "reason"), requeue: parseBoolean(requiredOption(parsed, "requeue"), "requeue") });
+    if (route.key === "merge-queue fail")
+        prepareMergeJobFailure(context, { ...mergeJobTarget(parsed, scopeProjectRoot), reason: requiredOption(parsed, "reason"), requeue: parseBoolean(requiredOption(parsed, "requeue"), "requeue") });
+    if (route.key.startsWith("lane lock ") && route.key !== "lane lock status") {
+        const action = requiredPosition(parsed, 0, "lane lock action");
+        prepareLaneLock(context, {
+            projectRoot: requiredOption(parsed, "project-root"), lane: requiredOption(parsed, "lane"), workerId: requiredOption(parsed, "worker-id"),
+            workspacePath: workspacePathOption(parsed), leaseToken: optionalOption(parsed, "lease-token"), reason: optionalOption(parsed, "reason"),
+            ttlSeconds: optionalNumber(parsed, "ttl"), timeoutSeconds: optionalNumber(parsed, "timeout"), pollIntervalSeconds: optionalNumber(parsed, "poll-interval")
+        }, action);
+    }
+    if (route.key === "run recovery begin")
+        prepared.recoveryPayload = prepareRecoveryPayload(requiredOption(parsed, "interruption-json"), "interruption");
+    if (route.key === "run recovery seal")
+        prepared.recoveryPayload = prepareRecoveryPayload(requiredOption(parsed, "settlement-json"), "settlement");
+    if (route.key === "run recovery capture")
+        prepared.recoveryCapture = prepareRecoveryCapture(context, recoveryCaptureInput(parsed));
+    if (route.key === "run recovery resume")
+        prepared.recoveryResume = prepareRunRecoveryResume(context, recoveryResumeInput(parsed));
+    if (route.key === "run drive answer")
+        prepared.controllerAnswer = prepareRunControllerAnswer(context, controllerAnswerInput(parsed));
+    if (route.key === "run drive launch")
+        prepared.controllerLaunch = prepareRunControllerLaunch(context, controllerLaunchInput(parsed));
+    if (route.key === "run drive context")
+        prepared.controllerContext = prepareRunControllerContext(context, controllerContextInput(parsed));
+    if (route.key === "protocol transition" || route.key === "transition")
+        prepared.protocolTransition = prepareProtocolTransition(context, protocolTransitionInput(parsed, scopeProjectRoot ?? resolveOperationProjectRoot(context, args)));
+    if (route.key === "codex home init")
+        prepared.codexHome = prepareCodexHome(context, codexHomeInput(parsed));
+    if (route.key === "codex home remove")
+        prepareCodexHomeRemoval(context, { projectRoot: requiredOption(parsed, "project-root"), profile: optionalOption(parsed, "profile"), mode: requiredOption(parsed, "mode") });
+    if (["codex hooks install", "codex hooks remove"].includes(route.key))
+        prepared.codexHooks = prepareCodexHooks(context, { projectRoot: requiredOption(parsed, "project-root"), target: optionalOption(parsed, "target"), profile: optionalOption(parsed, "profile"), yes: hasOption(parsed, "yes") });
+    if (route.key === "migration apply")
+        prepared.migrationApply = prepareMigrationApply(context, migrationApplyInput(parsed, classifyCliOperation(args, context.env)));
+    if (route.key === "migration verify")
+        prepared.migrationVerification = verifyMigrationReport(context, { file: requiredOption(parsed, "file") });
+    if (responseFile)
+        prepareResponseDestination(responseFile);
+    if (family === "dashboard") {
+        const action = dashboardAction(command);
+        prepareDashboardOptions({ format: optionalOption(parsed, "format"), viewer: optionalOption(parsed, "viewer"), open: optionalOption(parsed, "open") });
+        const target = resolveDashboardTarget(context, { action, project: optionalOption(parsed, "project"), projectRoot: optionalOption(parsed, "project-root"), protocol: optionalOption(parsed, "protocol"), all: hasOption(parsed, "all"), global: hasOption(parsed, "global") || command?.endsWith("-global") });
+        if (action === "refresh" && target.kind !== "global" && optionalOption(parsed, "output") !== undefined) {
+            throw new AppError("validation", "--output is supported only for global dashboard refresh; use dashboard render for a custom project/protocol output", 2, { parameter: "output" });
+        }
+        if (target.kind === "protocol")
+            requireProtocol(context, target.protocolId, target.project.id);
+        if (action !== "data") {
+            if (target.kind === "global" || target.kind === "all_projects") {
+                prepareGlobalDashboardRender(context, { output: optionalOption(parsed, "output"), format: optionalOption(parsed, "format") ?? (command?.endsWith("-global") ? undefined : "html") });
+            }
+            else {
+                const format = optionalOption(parsed, "format") ?? (action === "open" || hasOption(parsed, "project") ? "html" : undefined);
+                const input = { projectRoot: target.project.root, format, ...(target.kind === "protocol" ? { protocol: target.protocolId } : {}) };
+                if (action === "refresh")
+                    prepareDashboardRefresh(context, { ...input, open: optionalOption(parsed, "open") });
+                else if (action === "render")
+                    prepareDashboardRender(context, { ...input, output: optionalOption(parsed, "output") });
+                else if (target.kind === "protocol") {
+                    if (format !== "html")
+                        throw new AppError("validation", "Protocol dashboard open supports --format html", 2, { protocol: target.protocolId });
+                    prepareDashboardRender(context, input);
+                }
+            }
+        }
+    }
+    if (route.key === "prompt render") {
+        const input = workerPromptInput(parsed);
+        prepared.workerPrompt = { input, value: prepareWorkerPrompt(context, input) };
+    }
+    if (route.key === "run snapshot restore" || route.key === "run snapshot bootstrap restore") {
+        try {
+            const input = snapshotRestoreInput(parsed);
+            if (route.key === "run snapshot restore")
+                prepared.snapshotRestore = prepareEvalRunRestore(context, input);
+            else
+                prepared.bootstrapRestore = prepareEvalBootstrapRestore(input);
+        }
+        catch (error) {
+            return prepareError(error, { parameter: "snapshot/project-root" });
+        }
+    }
+    if (route.key === "run snapshot bootstrap create") {
+        try {
+            prepareEvalBootstrapSnapshot(context, { projectRoot: requiredOption(parsed, "project-root"), output: requiredOption(parsed, "output") });
+        }
+        catch (error) {
+            return prepareError(error, { parameter: "project-root/output" });
+        }
+    }
+    if (route.key === "run snapshot create") {
+        prepareEvalRunSnapshotCreation(context, snapshotCreateInput(parsed));
+    }
+    if (route.key === "run start") {
+        try {
+            const input = runStartInput(parsed);
+            prepared.runStart = { input, value: prepareFlowRunStart(context, input) };
+        }
+        catch (error) {
+            return prepareError(error, { parameter: "run start" });
+        }
+    }
+    if (route.key === "run fork") {
+        try {
+            prepared.runFork = prepareRunFork(runForkInput(parsed));
+        }
+        catch (error) {
+            return prepareError(error, { parameter: "from/output" });
+        }
+    }
+    if (["runtime scope fence", "runtime scope stop"].includes(route.key))
+        prepareRuntimeScopeFence(requiredOption(parsed, "scope-id"), requiredOption(parsed, "request-id"));
+    if (route.key === "runtime scope resume")
+        prepareRuntimeScopeResumeRequest(context, runtimeScopeResumeInput(parsed));
+    if (route.key === "runtime scope reconcile")
+        prepareRuntimeScopeReconciliation(context, requiredOption(parsed, "scope-id"), Number(requiredOption(parsed, "generation")), requiredOption(parsed, "request-id"));
+    if (route.key === "runtime scope serve")
+        prepareRuntimeScopeServing(context, requiredOption(parsed, "scope-id"), Number(requiredOption(parsed, "generation")));
+    if (route.key === "runtime scope control") {
+        try {
+            const raw = optionalOption(parsed, "manifest-json");
+            prepared.runtimeManifest = prepareRuntimeScopeControl(requiredOption(parsed, "scope-id"), requiredOption(parsed, "request-id"), requiredOption(parsed, "mode"), raw === undefined ? undefined : prepareJsonText(raw, { file: "<manifest-json>", label: "scope manifest" }).value, context);
+        }
+        catch (error) {
+            return prepareError(error, { parameter: "scope-id/request-id/manifest-json" });
+        }
+    }
+    if (family === "runtime" && command === "process")
+        Object.assign(prepared, prepareRuntimeProcess(context, route.key, parsed));
+    if (route.key === "runtime process start") {
+        try {
+            prepareRuntimeService(context, runtimeServiceInput(parsed));
+        }
+        catch (error) {
+            return prepareError(error, { parameter: "runtime process start" });
+        }
+    }
+    if (family === "work" && command === "retry") {
+        try {
+            prepareWorkRetry(context, requiredPosition(parsed, 0, "work-id"), requiredOption(parsed, "reason"));
+        }
+        catch (error) {
+            return prepareError(error, { parameter: "work-id/reason" });
+        }
+    }
+    if (family === "work" && (command === "fail" || command === "cancel")) {
+        try {
+            prepareWorkSettlement(context, requiredPosition(parsed, 0, "work-id"), command === "fail" ? "failed" : "cancelled", requiredOption(parsed, "reason"));
+        }
+        catch (error) {
+            return prepareError(error, { parameter: "work-id/reason" });
+        }
+    }
+    if (family === "work" && (command === "deps" || command === "delete")) {
+        try {
+            if (command === "delete")
+                prepareWorkDelete(context, requiredPosition(parsed, 0, "work-id"));
+            else
+                prepareWorkDeps(context, { workId: requiredPosition(parsed, 1, "work-id"), action: requiredPosition(parsed, 0, "action"), on: parsed.options.get("on") ?? [] });
+        }
+        catch (error) {
+            return prepareError(error, { parameter: "work-id/on" });
+        }
+    }
+    if (route.key === "cleanup apply") {
+        const planFile = requiredOption(parsed, "plan-file");
+        try {
+            prepared.cleanup = prepareCleanupApply(context, { projectRoot: requiredOption(parsed, "project-root"), planFile, reason: requiredOption(parsed, "reason"), force: hasOption(parsed, "force") });
+        }
+        catch (error) {
+            return prepareError(error, { parameter: "plan-file", file: planFile });
+        }
+    }
+    if (route.key === "stage block" || route.key === "stage unblock") {
+        const input = { projectRoot: requiredOption(parsed, "project-root"), runId: requiredPosition(parsed, 0, "run-id"), stage: requiredOption(parsed, "stage"), workId: requiredOption(parsed, "work") };
+        try {
+            if (route.key === "stage block") {
+                const summaryFile = optionalOption(parsed, "summary-file"), summaryStdin = hasOption(parsed, "summary-stdin");
+                if (Boolean(summaryFile) === summaryStdin)
+                    throw new AppError("usage", "stage block requires exactly one of --summary-file or --summary-stdin", 2);
+                prepared.interactionText = summaryFile ? prepareTextFile(summaryFile, "Runtime block summary").text : await readStdin(io.stdin);
+                prepareStageRuntimeBlock(context, { ...input, kind: requiredOption(parsed, "kind"), code: requiredOption(parsed, "code"), summary: prepared.interactionText, retryable: hasOption(parsed, "retryable") });
+            }
+            else
+                prepareStageRuntimeUnblock(context, input);
+        }
+        catch (error) {
+            return prepareError(error, { parameter: "stage/work/summary" });
+        }
+    }
+    if (route.key === "zcode invocation prepare") {
+        const value = prepareJsonText(await readStdin(io.stdin), { file: "<stdin>", label: "invocation issuance" }).value;
+        const payload = value && typeof value === "object" ? value : {};
+        try {
+            prepared.lifecycleIssuance = prepareLifecycleIssuance(payload.command, payload.scope);
+        }
+        catch (error) {
+            if (error instanceof AppError && ["invocation_command_invalid", "invocation_scope_invalid"].includes(error.code))
+                return prepareError(new AppError("usage", error.message, 2, { cause_code: error.code }), { parameter: "stdin" });
+            throw error;
+        }
+        assertLifecycleInvocationCurrent(context, prepared.lifecycleIssuance.scope, prepared.lifecycleIssuance.command);
+    }
+    if (route.key === "work add-batch") {
+        const file = requiredOption(parsed, "file");
+        try {
+            prepared.workBatch = prepareWorkBatch(context, { parentWorkId: requiredOption(parsed, "parent"), file });
+        }
+        catch (error) {
+            return prepareError(error, { parameter: "file/parent", file });
+        }
+    }
+    if (route.key === "work repair add") {
+        const taskFile = optionalOption(parsed, "task-file"), taskStdin = hasOption(parsed, "task-stdin");
+        if (Boolean(taskFile) === taskStdin)
+            throw new AppError("usage", "work repair add requires exactly one of --task-file or --task-stdin", 2);
+        if (taskStdin && io.stdin?.isTTY)
+            throw new AppError("usage", "--task-stdin requires piped or redirected input", 2);
+        const task = taskFile ? prepareTextFile(taskFile, "Repair task").text : await readStdin(io.stdin);
+        prepared.workRepair = prepareCliWorkRepair(context, parsed, task, scopeProjectRoot);
+    }
+    if (route.key === "run config set" || route.key === "run vars set") {
+        const input = { projectRoot: requiredOption(parsed, "project-root"), runId: requiredPosition(parsed, 1, "run-id"), key: requiredOption(parsed, "key"), value: requiredOption(parsed, "value") };
+        try {
+            if (route.key === "run config set")
+                prepareFlowRunConfig(context, { ...input, reason: requiredOption(parsed, "reason") });
+            else
+                prepareFlowRunVariable(context, input);
+        }
+        catch (error) {
+            return prepareError(error, { parameter: "run config/vars" });
+        }
+    }
+    if (route.key === "schema validate") {
+        try {
+            prepared.schemaValidation = dispatchSchema(context, command, parsed);
+        }
+        catch (error) {
+            return prepareError(error, { parameter: "file", file: requiredOption(parsed, "file") });
+        }
+    }
+    if (route.key === "project config set") {
+        try {
+            prepareProjectConfigValue(requiredOption(parsed, "key"), requiredOption(parsed, "value"));
+        }
+        catch (error) {
+            return prepareError(error, { parameter: "key/value" });
+        }
+    }
+    if (family === "session" && command === "register") {
+        try {
+            prepared.sessionPayload = prepareFlowSessionPayload({ payloadBase64: optionalOption(parsed, "payload-base64"), payloadFile: optionalOption(parsed, "payload-file"), payloadJson: optionalOption(parsed, "payload-json") });
+        }
+        catch (error) {
+            return prepareError(error, { parameter: "session payload" });
+        }
+    }
+    const run = (projectRoot, runId) => {
+        try {
+            const project = requireProjectByRoot(context, resolveProjectRoot(projectRoot));
+            const row = context.db.get("SELECT run_root, workspace_root, index_json FROM runs WHERE project_id = ? AND id = ?", [project.id, runId]);
+            if (!row)
+                throw new AppError("not_found", "RUN is not registered", 2, { run_id: runId });
+            if (!row.run_root)
+                throw new AppError("runtime_missing", "RUN artifact root is unavailable", 1, { run_id: runId });
+            return { runRoot: row.run_root, workspaceRoot: row.workspace_root, indexJson: row.index_json };
+        }
+        catch (error) {
+            return prepareError(error, { parameter: "run-id", run_id: runId });
+        }
+    };
+    const json = (file, stdin, label, schema) => {
+        if (stdin) {
+            // The caller awaits this helper; the synchronous facade below is only
+            // used for file inputs.  Keep stdin handling in the stage branch.
+            throw new AppError("usage", `${label} stdin preparation must be awaited`, 2);
+        }
+        if (!file)
+            throw new AppError("usage", `${label} input is required`, 2);
+        return prepareJsonSchema(file, label, schema);
+    };
+    if (family === "stage" && command === "start") {
+        const stage = requiredOption(parsed, "stage");
+        if (stage !== "specify" && ["bootstrap", "intake-file", "intake-stdin"].some(option => hasOption(parsed, option)))
+            throw new AppError("usage", "--bootstrap and intake inputs are only supported for SPECIFY", 2);
+        requiredOption(parsed, "project-root");
+        if (!hasOption(parsed, "bootstrap"))
+            requiredPosition(parsed, 0, "run-id");
+        if (hasOption(parsed, "session-id"))
+            throw new AppError("usage", "--session-id is managed by the harness lifecycle adapter and is not accepted", 2);
+        const contextFile = optionalOption(parsed, "context-file"), contextSha256 = optionalOption(parsed, "context-sha256");
+        if (Boolean(contextFile) !== Boolean(contextSha256))
+            throw new AppError("usage", "stage start requires --context-file together with --context-sha256", 2);
+        if ([hasOption(parsed, "intake-file"), hasOption(parsed, "intake-stdin"), Boolean(contextFile)].filter(Boolean).length > 1)
+            throw new AppError("usage", "Use exactly one of --intake-file, --intake-stdin or --context-file", 2);
+        if (contextFile && contextSha256) {
+            try {
+                prepared.stageStart = { externalContext: loadExternalStageContext({ file: contextFile, expectedSha256: contextSha256, stage }) };
+            }
+            catch (error) {
+                return prepareError(error, { file: contextFile, parameter: "context-file" });
+            }
+            if (!hasOption(parsed, "bootstrap")) {
+                const { runRoot } = run(requiredOption(parsed, "project-root"), requiredPosition(parsed, 0, "run-id"));
+                prepareExternalStageContext({ stageRoot: path.join(runRoot, vnextStageDirectory(stage)), loaded: prepared.stageStart.externalContext });
+            }
+        }
+        if (stage === "specify") {
+            const intakeFile = optionalOption(parsed, "intake-file");
+            if (intakeFile)
+                prepared.stageStart = { intakeMarkdown: prepareTextFile(intakeFile, "SPECIFY intake").text };
+            else if (hasOption(parsed, "intake-stdin"))
+                prepared.stageStart = { intakeMarkdown: await readStdin(io.stdin) };
+            else if (prepared.stageStart?.externalContext)
+                prepared.stageStart.intakeMarkdown = runnerIntake(prepared.stageStart.externalContext);
+            const projectRoot = requiredOption(parsed, "project-root");
+            const bootstrap = hasOption(parsed, "bootstrap");
+            if (isVnextSpecifyFlow(projectRoot) && (bootstrap || isVnextSpecifyRun(context, { projectRoot, runId: requiredPosition(parsed, 0, "run-id") }))) {
+                prepared.specifyStart = prepareVnextSpecifyStart(context, { projectRoot, ...(prepared.stageStart?.intakeMarkdown !== undefined ? { intakeMarkdown: prepared.stageStart.intakeMarkdown } : {}), ...(prepared.stageStart?.externalContext ? { externalContext: prepared.stageStart.externalContext } : {}), slug: optionalOption(parsed, "subject"), ...(!bootstrap ? { runId: requiredPosition(parsed, 0, "run-id") } : {}) });
+            }
+            else if (bootstrap) {
+                if (hasOption(parsed, "intake-stdin") || contextFile)
+                    throw new AppError("usage", "Legacy SPECIFY bootstrap supports --intake-file, not stdin or runner context", 2);
+                prepared.legacyStageStart = prepareLegacyStageStart(context, { projectRoot, stage, bootstrap: { subject: requiredOption(parsed, "subject"), ...(intakeFile ? { intakeFile } : {}) }, ...(optionalOption(parsed, "dir") ? { dir: optionalOption(parsed, "dir") } : {}) }, prepared.stageStart?.intakeMarkdown);
+            }
+        }
+        if (stage === "merge" && isVnextMergeRun(context, { projectRoot: requiredOption(parsed, "project-root"), runId: requiredPosition(parsed, 0, "run-id") })) {
+            prepared.mergeStart = prepareVnextMergeStart(context, { projectRoot: requiredOption(parsed, "project-root"), runId: requiredPosition(parsed, 0, "run-id"), ...(prepared.stageStart?.externalContext ? { externalContext: prepared.stageStart.externalContext } : {}) });
+        }
+        if (stage === "protocolize" && isVnextProtocolizeRun(context, { projectRoot: requiredOption(parsed, "project-root"), runId: requiredPosition(parsed, 0, "run-id") })) {
+            prepared.protocolizeStart = prepareVnextProtocolizeStart(context, { projectRoot: requiredOption(parsed, "project-root"), runId: requiredPosition(parsed, 0, "run-id"), ...(prepared.stageStart?.externalContext ? { externalContext: prepared.stageStart.externalContext } : {}) });
+        }
+        if (stage === "plan" && isVnextPlanRun(context, { projectRoot: requiredOption(parsed, "project-root"), runId: requiredPosition(parsed, 0, "run-id") })) {
+            prepared.planStart = prepareVnextPlanStart(context, { projectRoot: requiredOption(parsed, "project-root"), runId: requiredPosition(parsed, 0, "run-id"), ...(prepared.stageStart?.externalContext ? { externalContext: prepared.stageStart.externalContext } : {}) });
+        }
+        if (stage === "plan-review" && isVnextPlanReviewRun(context, { projectRoot: requiredOption(parsed, "project-root"), runId: requiredPosition(parsed, 0, "run-id") })) {
+            prepared.planReviewStart = prepareVnextPlanReviewStart(context, { projectRoot: requiredOption(parsed, "project-root"), runId: requiredPosition(parsed, 0, "run-id"), ...(prepared.stageStart?.externalContext ? { externalContext: prepared.stageStart.externalContext } : {}) });
+        }
+        if (stage === "code" && isVnextPlanRun(context, { projectRoot: requiredOption(parsed, "project-root"), runId: requiredPosition(parsed, 0, "run-id") })) {
+            prepared.codeStart = prepareVnextCodeStart(context, { projectRoot: requiredOption(parsed, "project-root"), runId: requiredPosition(parsed, 0, "run-id"), ...(prepared.stageStart?.externalContext ? { externalContext: prepared.stageStart.externalContext } : {}) });
+        }
+        if (stage === "code-review" && isVnextCodeReviewRun(context, { projectRoot: requiredOption(parsed, "project-root"), runId: requiredPosition(parsed, 0, "run-id") })) {
+            prepared.codeReviewStart = prepareVnextCodeReviewStart(context, { projectRoot: requiredOption(parsed, "project-root"), runId: requiredPosition(parsed, 0, "run-id"), ...(prepared.stageStart?.externalContext ? { externalContext: prepared.stageStart.externalContext } : {}) });
+        }
+        if (![prepared.specifyStart, prepared.protocolizeStart, prepared.planStart, prepared.planReviewStart, prepared.codeStart, prepared.codeReviewStart, prepared.mergeStart, prepared.legacyStageStart].some(Boolean)) {
+            if (prepared.stageStart?.externalContext)
+                throw new AppError("usage", "--context-file is currently supported only by vNext flow stages", 2);
+            prepared.legacyStageStart = prepareLegacyStageStart(context, { projectRoot: requiredOption(parsed, "project-root"), runId: requiredPosition(parsed, 0, "run-id"), stage, ...(optionalOption(parsed, "dir") ? { dir: optionalOption(parsed, "dir") } : {}) });
+        }
+    }
+    if (family === "stage" && (command === "pause" || command === "resume")) {
+        requiredPosition(parsed, 0, "run-id");
+        requiredOption(parsed, "project-root");
+        requiredOption(parsed, "stage");
+        requiredOption(parsed, "work");
+        const fileParameter = command === "pause" ? "question-file" : "answer-file";
+        const stdinParameter = command === "pause" ? "question-stdin" : "answer-stdin";
+        const inputFile = optionalOption(parsed, fileParameter);
+        const fromStdin = hasOption(parsed, stdinParameter);
+        if (Boolean(inputFile) === fromStdin)
+            throw new AppError("usage", `stage ${command} requires exactly one of --${fileParameter} or --${stdinParameter}`, 2);
+        if (fromStdin && io.stdin?.isTTY)
+            throw new AppError("usage", `--${stdinParameter} requires piped or redirected input`, 2);
+        prepared.interactionText = inputFile ? prepareTextFile(inputFile, command === "pause" ? "User question" : "User answer").text : await readStdin(io.stdin);
+        if (!prepared.interactionText.trim())
+            return prepareError(new AppError("validation", `stage ${command} requires non-empty input`, 2), { parameter: inputFile ? fileParameter : stdinParameter });
+        const input = { projectRoot: requiredOption(parsed, "project-root"), runId: requiredPosition(parsed, 0, "run-id"), stage: requiredOption(parsed, "stage"), workId: requiredOption(parsed, "work") };
+        try {
+            if (command === "pause")
+                prepareStagePause(context, { ...input, question: prepared.interactionText });
+            else
+                prepared.resumeEvidence = prepareStageResume(context, { ...input, answer: prepared.interactionText }).evidence;
+        }
+        catch (error) {
+            return prepareError(error, { parameter: "stage/work" });
+        }
+    }
+    if (family === "work" && command === "finish") {
+        const retryReceiptId = optionalOption(parsed, "retry-check"), retryReason = prepared.retryReason;
+        if (Boolean(retryReceiptId) !== Boolean(retryReason))
+            throw new AppError("usage", "--retry-check and --reason must be supplied together", 2);
+        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);
+        prepared.workFinish = { result: resultFile ? prepareTextFile(resultFile, "Work result").text : await readStdin(io.stdin) };
+        prepareWorkResult(context, requiredPosition(parsed, 0, "work-id"), prepared.workFinish.result);
+    }
+    if (family === "stage" && command === "fanout" && requiredPosition(parsed, 0, "fanout action") === "reconcile") {
+        prepared.observations = prepareNativeObservations(prepareJsonFile(requiredOption(parsed, "observations-file"), "native observations").value);
+    }
+    if (family === "stage" && command === "native" && requiredPosition(parsed, 0, "native action") === "observe") {
+        prepared.observations = prepareNativeObservations(prepareJsonFile(requiredOption(parsed, "observations-file"), "native observations").value);
+    }
+    if (family !== "stage" || command !== "finish")
+        return prepared;
+    const projectRoot = requiredOption(parsed, "project-root");
+    const runId = requiredPosition(parsed, 0, "run-id");
+    const stage = requiredOption(parsed, "stage");
+    if (hasOption(parsed, "status"))
+        throw new AppError("usage", "Stage status belongs in the semantic input file", 2);
+    if (["result-file", "semantic-file", "data", "result-stdin"].filter(key => hasOption(parsed, key)).length > 1)
+        throw new AppError("usage", "Use exactly one result input: --result-file, --semantic-file, --data or --result-stdin", 2);
+    if (Boolean(optionalOption(parsed, "retry-check")) !== Boolean(prepared.retryReason))
+        throw new AppError("usage", "--retry-check requires recovery evidence", 2);
+    const resultStdin = hasOption(parsed, "result-stdin");
+    const semanticFile = optionalOption(parsed, "semantic-file") ?? optionalOption(parsed, "data");
+    const resultFile = optionalOption(parsed, "result-file") ?? semanticFile;
+    const runtime = run(projectRoot, runId);
+    const terminalReplay = (name) => {
+        let index;
+        try {
+            index = JSON.parse(runtime.indexJson);
+        }
+        catch (error) {
+            throw new AppError("runtime_artifact_invalid", "RUN index is not valid retained JSON", 1, { run_id: runId, cause: error instanceof Error ? error.message : String(error) });
+        }
+        return index.stage_runs?.some(entry => entry.stage === name && entry.status === "done") === true
+            && fs.existsSync(path.join(runtime.runRoot, vnextStageDirectory(name), "stage-report.json"));
+    };
+    const acceptStageInputs = (allowed) => {
+        const options = allowed.split(" ");
+        for (const name of ["dir", "semantic-file", "data", "result-file", "result-stdin", "outcome", "decision-file", "verification-file", "retry-check", "reason", "reason-file", "request", "work"]) {
+            if (hasOption(parsed, name) && !options.includes(name === "reason-file" ? "reason" : name))
+                throw new AppError("usage", `stage finish ${stage} does not accept --${name} for this flow`, 2, { parameter: name });
+        }
+    };
+    const fromStdin = async (label, schema) => {
+        const value = prepareJsonText(await readStdin(io.stdin), { file: "<stdin>", label });
+        try {
+            validateSchema({ ...schema, file: value.file, data: value.value });
+        }
+        catch (error) {
+            return prepareError(error, { file: value.file, label });
+        }
+        return value;
+    };
+    if (stage === "specify" && isVnextSpecifyRun(context, { projectRoot, runId })) {
+        acceptStageInputs("result-file semantic-file data result-stdin outcome");
+        const outcome = optionalOption(parsed, "outcome");
+        if (!outcome || !["specified", "failed", "cancelled"].includes(outcome))
+            throw new AppError("usage", "vNext SPECIFY requires --outcome specified|failed|cancelled; use stage pause for a user question", 2);
+        if (Boolean(resultFile) === resultStdin)
+            throw new AppError("usage", "vNext SPECIFY finish requires exactly one result input", 2);
+        const schema = { schemaName: "vnext-specify", projectRoot, ddFlowHome: context.ddFlowHome, runId, runRoot: runtime.runRoot };
+        const input = resultStdin ? await fromStdin("SPECIFY result", schema) : json(resultFile, false, "SPECIFY result", schema);
+        prepared.stageFinish = { value: input.value, text: input.text };
+    }
+    else if (stage === "protocolize" && isVnextProtocolizeRun(context, { projectRoot, runId })) {
+        acceptStageInputs("result-file semantic-file data");
+        if (!resultFile || resultStdin || hasOption(parsed, "outcome"))
+            throw new AppError("usage", "vNext PROTOCOLIZE requires exactly --result-file", 2);
+        let absolute;
+        try {
+            absolute = prepareProtocolizeResultPath(runtime.runRoot, resultFile);
+        }
+        catch (error) {
+            return prepareError(error, { file: resultFile });
+        }
+        const input = json(absolute, false, "PROTOCOLIZE result", { schemaName: "vnext-protocolize-result", projectRoot, ddFlowHome: context.ddFlowHome, runId, runRoot: runtime.runRoot });
+        prepared.stageFinish = { value: input.value, text: input.text };
+    }
+    else if (stage === "plan" && isVnextPlanRun(context, { projectRoot, runId })) {
+        acceptStageInputs("");
+        if (hasOption(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);
+        try {
+            prepared.planFinish = prepareVnextPlanFinish(context, { projectRoot, runId });
+        }
+        catch (error) {
+            return prepareError(error, { parameter: "PLAN artifacts" });
+        }
+    }
+    else if (stage === "merge" && isVnextMergeRun(context, { projectRoot, runId })) {
+        acceptStageInputs("request work retry-check reason");
+        if (resultStdin || resultFile || hasOption(parsed, "outcome"))
+            throw new AppError("usage", "vNext MERGE uses the Work result path returned by stage start", 2);
+        requiredOption(parsed, "request");
+        requiredOption(parsed, "work");
+        try {
+            prepared.mergeFinish = prepareVnextMergeFinish(context, { projectRoot, runId, requestId: requiredOption(parsed, "request"), workId: requiredOption(parsed, "work"), ...(optionalOption(parsed, "retry-check") ? { retryCheckId: optionalOption(parsed, "retry-check"), retryReason: prepared.retryReason } : {}) });
+        }
+        catch (error) {
+            return prepareError(error, { parameter: "MERGE finish" });
+        }
+    }
+    else if (stage === "plan-review" && isVnextPlanReviewRun(context, { projectRoot, runId })) {
+        acceptStageInputs("decision-file");
+        if (resultStdin || hasOption(parsed, "outcome"))
+            throw new AppError("usage", "vNext PLAN-REVIEW uses --decision-file", 2);
+        const decision = optionalOption(parsed, "decision-file") ?? path.join(runtime.runRoot, "04-plan-review", "decision.json");
+        const input = json(decision, false, "PLAN-REVIEW decision", { schemaName: "plan-review-decision", projectRoot, ddFlowHome: context.ddFlowHome, runId, runRoot: runtime.runRoot });
+        prepared.stageFinish = { value: input.value, text: input.text };
+    }
+    else if (stage === "code" && isVnextPlanRun(context, { projectRoot, runId })) {
+        acceptStageInputs("verification-file retry-check reason");
+        if (semanticFile || resultFile || resultStdin || hasOption(parsed, "outcome"))
+            throw new AppError("usage", "vNext CODE finish accepts only --verification-file", 2);
+        const verification = optionalOption(parsed, "verification-file");
+        if (!verification)
+            throw new AppError("usage", "vNext CODE finish requires --verification-file", 2);
+        if (!terminalReplay(stage)) {
+            const input = json(verification, false, "CODE verification", { schemaName: "code-verification", projectRoot: runtime.workspaceRoot, ddFlowHome: context.ddFlowHome, runId, runRoot: runtime.runRoot });
+            prepared.stageFinish = { value: input.value, text: input.text };
+        }
+    }
+    else if (stage === "code-review" && isVnextCodeReviewRun(context, { projectRoot, runId })) {
+        acceptStageInputs("decision-file retry-check reason");
+        if (resultStdin || semanticFile || resultFile || hasOption(parsed, "outcome"))
+            throw new AppError("usage", "vNext CODE-REVIEW uses --decision-file", 2);
+        const decision = optionalOption(parsed, "decision-file") ?? path.join(runtime.runRoot, "06-code-review", "decision.json");
+        if (!terminalReplay(stage)) {
+            const input = prepareCodeReviewDecision(runtime.runRoot, optionalOption(parsed, "decision-file"));
+            try {
+                validateSchema({ schemaName: "code-review-decision", file: decision, data: input.value, projectRoot: runtime.workspaceRoot, ddFlowHome: context.ddFlowHome, runId, runRoot: runtime.runRoot });
+            }
+            catch (error) {
+                return prepareError(error, { file: decision, label: "CODE-REVIEW decision" });
+            }
+            prepared.stageFinish = input;
+        }
+    }
+    else {
+        acceptStageInputs("dir semantic-file data");
+        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);
+        prepared.legacyStageFinish = prepareStageFinish(context, { projectRoot, runId, stage, ...(optionalOption(parsed, "dir") ? { dir: optionalOption(parsed, "dir") } : {}), ...(semanticFile ? { semanticFile } : {}) });
+    }
+    return prepared;
+}
+async function dispatch(args, context, io, scopeProjectRoot = null, classification = classifyCliOperation(args, context.env), output = parseOutputOptions(args), prepared = {}) {
+    if (!prepared.route)
+        throw new AppError("command_not_prepared", "Command dispatch requires prepared arguments", 1);
+    const { family, command, parsed } = prepared.route;
+    if (family === "zcode" && command === "invocation" && parsed.positional[0] === "prepare") {
+        const payload = prepared.lifecycleIssuance;
+        if (!payload)
+            throw new AppError("command_not_prepared", "Invocation issuance requires prepared input", 1);
+        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);
+        return dispatchEngine(context, command, parsed, classification, prepared);
     }
     if (family === "status") {
-        const rootParsed = parseArgs([command ?? "", ...rest]);
         return getRuntimeStatus(context, {
-            projectRoot: optionalOption(rootParsed, "project-root") ?? optionalOption(rootParsed, "root"),
-            checkRegistry: hasOption(rootParsed, "check-registry")
+            projectRoot: optionalOption(parsed, "project-root") ?? optionalOption(parsed, "root"),
+            checkRegistry: hasOption(parsed, "check-registry")
         });
     }
     if (family === "version") {
         return getCliVersionReport();
     }
     if (family === "runtime") {
-        return await dispatchRuntime(context, command, parsed);
+        return await dispatchRuntime(context, command, parsed, commandProgress(io, output), prepared);
     }
     if (family === "canon") {
-        return dispatchCanon(context, command, parsed);
+        return dispatchCanon(context, command, parsed, prepared);
     }
     if (family === "project" && command === "register") {
         return registerProject(context, { root: requiredOption(parsed, "root") });
@@ -597,16 +1607,7 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
         return readyForMerge(context, { protocolId, projectRoot: requiredScopeProjectRoot(scopeProjectRoot, "protocol ready-for-merge") });
     }
     if (family === "protocol" && command === "transition") {
-        const protocolId = requiredPosition(parsed, 0, "protocol-id");
-        const reason = optionalOption(parsed, "reason");
-        return transitionProtocol(context, {
-            protocolId,
-            projectRoot: requiredScopeProjectRoot(scopeProjectRoot, "protocol transition"),
-            to: requiredOption(parsed, "to"),
-            jsonFile: requiredOptionAlias(parsed, ["payload-file", "json-file"]),
-            force: hasOption(parsed, "force"),
-            ...(reason ? { reason } : {})
-        });
+        return transitionProtocol(context, protocolTransitionInput(parsed, scopeProjectRoot), prepared.protocolTransition);
     }
     if (family === "protocol" && command === "sync-from-run") {
         const protocolId = requiredPosition(parsed, 0, "protocol-id");
@@ -631,17 +1632,7 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
         });
     }
     if (family === "transition") {
-        const transitionParsed = parseArgs([command ?? "", ...rest]);
-        const protocolId = requiredPosition(transitionParsed, 0, "protocol-id");
-        const reason = optionalOption(transitionParsed, "reason");
-        return transitionProtocol(context, {
-            protocolId,
-            projectRoot: requiredScopeProjectRoot(scopeProjectRoot, "transition"),
-            to: requiredOption(transitionParsed, "to"),
-            jsonFile: requiredOptionAlias(transitionParsed, ["payload-file", "json-file"]),
-            force: hasOption(transitionParsed, "force"),
-            ...(reason ? { reason } : {})
-        });
+        return transitionProtocol(context, protocolTransitionInput(parsed, scopeProjectRoot), prepared.protocolTransition);
     }
     if (family === "plan" && command === "status") {
         const protocolId = requiredPosition(parsed, 0, "protocol-id");
@@ -660,12 +1651,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: prepared.observations ?? prepareJsonFile(requiredOption(parsed, "observations-file"), "native observations").value });
         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: prepared.observations ?? prepareJsonFile(requiredOption(parsed, "observations-file"), "native observations").value });
     }
     if (family === "run" && command === "capacity") {
         if (requiredPosition(parsed, 0, "capacity action") !== "record")
@@ -677,16 +1675,7 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
         return dispatchPlanItem(context, parsed, requiredScopeProjectRoot(scopeProjectRoot, "plan item"));
     }
     if (family === "prompt" && command === "render") {
-        const workspaceRoot = optionalOption(parsed, "workspace-root");
-        const taskFile = optionalOption(parsed, "task-file");
-        return renderWorkerPrompt(context, {
-            projectRoot: requiredOption(parsed, "project-root"),
-            runId: requiredOption(parsed, "run"),
-            stage: requiredOption(parsed, "stage"),
-            profile: requiredOption(parsed, "profile"),
-            ...(taskFile ? { taskFile } : { planItemId: requiredOption(parsed, "plan-item") }),
-            ...(workspaceRoot ? { workspaceRoot } : {})
-        });
+        return renderWorkerPrompt(context, prepared.workerPrompt?.input ?? workerPromptInput(parsed), prepared.workerPrompt?.value);
     }
     if (family === "work" && command === "status") {
         return getVnextWorkStatus(context, {
@@ -695,7 +1684,7 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
         });
     }
     if (family === "work" && command === "add-batch") {
-        return addWorkBatch(context, { parentWorkId: requiredOption(parsed, "parent"), file: requiredOption(parsed, "file") });
+        return addWorkBatch(context, { parentWorkId: requiredOption(parsed, "parent"), file: requiredOption(parsed, "file"), prepared: prepared.workBatch });
     }
     if (family === "work" && command === "ls") {
         return listWorks(context, { ...(optionalOption(parsed, "run") ? { runId: optionalOption(parsed, "run") } : {}), ...(optionalOption(parsed, "parent") ? { parentWorkId: optionalOption(parsed, "parent") } : {}), ...(optionalOption(parsed, "status") ? { status: optionalOption(parsed, "status") } : {}), ...(hasOption(parsed, "ready") ? { ready: true } : {}), ...(hasOption(parsed, "include-results") ? { includeResults: true } : {}), ...(optionalOption(parsed, "limit") ? { limit: Number(optionalOption(parsed, "limit")) } : {}) });
@@ -703,48 +1692,9 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
     if (family === "work" && command === "show")
         return showWork(context, requiredPosition(parsed, 0, "work-id"));
     if (family === "work" && command === "repair" && requiredPosition(parsed, 0, "action") === "add") {
-        if (!hasOption(parsed, "task-stdin"))
-            throw new AppError("usage", "work repair add requires --task-stdin", 2);
-        const origins = parsed.options.get("origin-work") ?? [];
-        const findings = parsed.options.get("from-finding") ?? [];
-        const unresolved = parsed.options.get("from-unresolved") ?? [];
-        if (!origins.length && !findings.length)
-            throw new AppError("usage", "work repair add requires --from-check with --origin-work, --from-finding, or --from-unresolved with --origin-work", 2);
-        if (findings.length)
-            return addVnextCodeReviewRepair(context, {
-                projectRoot: requiredScopeProjectRoot(scopeProjectRoot, "work repair add"),
-                runId: requiredOption(parsed, "run"),
-                findingIds: findings,
-                checkRefsByFinding: Object.fromEntries(findings.map((finding) => [finding, parsed.options.get("check-ref") ?? []])),
-                objective: await readStdin(io.stdin)
-            });
-        if (unresolved.length) {
-            if (!origins.length)
-                throw new AppError("usage", "semantic repair requires at least one --origin-work", 2);
-            const verificationPath = requiredOption(parsed, "verification-file");
-            return addVnextCodeRepair(context, {
-                projectRoot: requiredScopeProjectRoot(scopeProjectRoot, "work repair add"),
-                runId: requiredOption(parsed, "run"),
-                originWorkIds: origins,
-                semanticUnresolved: unresolved,
-                verificationPath,
-                objective: await readStdin(io.stdin)
-            });
-        }
-        if (!hasOption(parsed, "from-check"))
-            throw new AppError("usage", "check repair requires --from-check", 2);
-        if (!origins.length)
-            throw new AppError("usage", "check repair requires at least one --origin-work", 2);
-        const receipts = parsed.options.get("from-check") ?? [];
-        if (receipts.length !== 1)
-            throw new AppError("usage", "check repair accepts exactly one --from-check; create one causal repair Work per failed receipt", 2);
-        return addVnextCodeRepair(context, {
-            projectRoot: requiredScopeProjectRoot(scopeProjectRoot, "work repair add"),
-            runId: requiredOption(parsed, "run"),
-            checkReceiptId: receipts[0],
-            originWorkIds: origins,
-            objective: await readStdin(io.stdin)
-        });
+        if (!prepared.workRepair)
+            throw new AppError("cli_input_unprepared", "Repair input was not prepared", 1);
+        return addVnextCodeRepair(context, prepared.workRepair.input, prepared.workRepair.value);
     }
     if (family === "work" && command === "deps") {
         const on = parsed.options.get("on") ?? [];
@@ -752,21 +1702,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 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));
+        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 = prepared.retryReason;
+        if (Boolean(retryReceiptId) !== Boolean(retryReason))
+            throw new AppError("usage", "--retry-check and --reason must be supplied together", 2);
+        const result = prepared.workFinish?.result ?? (resultFile ? prepareTextFile(resultFile, "Work result").text : await readStdin(io.stdin));
+        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")
@@ -788,12 +1751,12 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
         const requireSessionBinding = hasOption(parsed, "require-session-binding");
         const projectRoot = requiredOption(parsed, "project-root");
         const stage = requiredOption(parsed, "stage");
-        const externalContext = contextFile && contextSha256 ? loadExternalStageContext({ file: contextFile, expectedSha256: contextSha256, stage }) : undefined;
+        const externalContext = prepared.stageStart?.externalContext;
         const claimVnextStageStart = (runId) => {
             registerProject(context, { root: projectRoot });
             return findRecentMatchingHookEvent(context, {
                 projectId: requireProjectByRoot(context, resolveProjectRoot(projectRoot)).id,
-                matchKey: stageStartMatchKey(runId, stage, projectRoot, contextSha256),
+                matchKey: entityReferenceVariants(runId).map((reference) => stageStartMatchKey(reference, stage, projectRoot, contextSha256)),
                 errorCode: "trusted_session_binding_required",
                 operation: `vNext ${stage.toUpperCase()} start`
             }).eventKey;
@@ -819,37 +1782,37 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
             }
             const result = launchVnextSpecify(context, {
                 projectRoot,
-                ...(externalContext ? { intakeMarkdown: runnerIntake(externalContext) } : intakeFile ? { intakeFile } : { intakeMarkdown: await readStdin(io.stdin) }),
+                ...(prepared.stageStart?.intakeMarkdown !== undefined ? { intakeMarkdown: prepared.stageStart.intakeMarkdown } : externalContext ? { intakeMarkdown: runnerIntake(externalContext) } : intakeFile ? { intakeFile } : { intakeMarkdown: await readStdin(io.stdin) }),
                 hookEventId,
                 ...(subject ? { slug: subject } : {}),
                 ...(externalContext ? { externalContext } : {}),
                 ...(!bootstrap ? { runId: requiredPosition(parsed, 0, "run-id") } : {})
-            });
+            }, prepared.specifyStart);
             return attachExternalStageContext(result, externalContext);
         }
         if (!bootstrap && stage === "protocolize" && isVnextProtocolizeRun(context, { projectRoot, runId: requiredPosition(parsed, 0, "run-id") })) {
             hookEventId ??= claimVnextStageStart(requiredPosition(parsed, 0, "run-id"));
-            return attachExternalStageContext(startVnextProtocolize(context, { projectRoot, runId: requiredPosition(parsed, 0, "run-id"), hookEventId, ...(contextSha256 ? { contextSha256 } : {}), ...(externalContext ? { externalContext } : {}) }), externalContext);
+            return attachExternalStageContext(await startVnextProtocolize(context, { projectRoot, runId: requiredPosition(parsed, 0, "run-id"), hookEventId, ...(contextSha256 ? { contextSha256 } : {}), ...(externalContext ? { externalContext } : {}) }, prepared.protocolizeStart), externalContext);
         }
         if (!bootstrap && stage === "plan" && isVnextPlanRun(context, { projectRoot, runId: requiredPosition(parsed, 0, "run-id") })) {
             hookEventId ??= claimVnextStageStart(requiredPosition(parsed, 0, "run-id"));
-            return attachExternalStageContext(startVnextPlan(context, { projectRoot, runId: requiredPosition(parsed, 0, "run-id"), hookEventId, ...(contextSha256 ? { contextSha256 } : {}), ...(externalContext ? { externalContext } : {}) }), externalContext);
+            return attachExternalStageContext(startVnextPlan(context, { projectRoot, runId: requiredPosition(parsed, 0, "run-id"), hookEventId, ...(contextSha256 ? { contextSha256 } : {}), ...(externalContext ? { externalContext } : {}) }, prepared.planStart), externalContext);
         }
         if (!bootstrap && stage === "plan-review" && isVnextPlanReviewRun(context, { projectRoot, runId: requiredPosition(parsed, 0, "run-id") })) {
             hookEventId ??= claimVnextStageStart(requiredPosition(parsed, 0, "run-id"));
-            return attachExternalStageContext(startVnextPlanReview(context, { projectRoot, runId: requiredPosition(parsed, 0, "run-id"), hookEventId, ...(contextSha256 ? { contextSha256 } : {}), ...(externalContext ? { externalContext } : {}) }), externalContext);
+            return attachExternalStageContext(startVnextPlanReview(context, { projectRoot, runId: requiredPosition(parsed, 0, "run-id"), hookEventId, ...(contextSha256 ? { contextSha256 } : {}), ...(externalContext ? { externalContext } : {}) }, prepared.planReviewStart), externalContext);
         }
         if (!bootstrap && stage === "code" && isVnextPlanRun(context, { projectRoot, runId: requiredPosition(parsed, 0, "run-id") })) {
             hookEventId ??= claimVnextStageStart(requiredPosition(parsed, 0, "run-id"));
-            return attachExternalStageContext(await startVnextCode(context, { projectRoot, runId: requiredPosition(parsed, 0, "run-id"), hookEventId, progress: commandProgress(io, output), ...(contextSha256 ? { contextSha256 } : {}), ...(externalContext ? { externalContext } : {}) }), externalContext);
+            return attachExternalStageContext(await startVnextCode(context, { projectRoot, runId: requiredPosition(parsed, 0, "run-id"), hookEventId, progress: commandProgress(io, output), ...(contextSha256 ? { contextSha256 } : {}), ...(externalContext ? { externalContext } : {}) }, prepared.codeStart), externalContext);
         }
         if (!bootstrap && stage === "code-review" && isVnextCodeReviewRun(context, { projectRoot, runId: requiredPosition(parsed, 0, "run-id") })) {
             hookEventId ??= claimVnextStageStart(requiredPosition(parsed, 0, "run-id"));
-            return attachExternalStageContext(startVnextCodeReview(context, { projectRoot, runId: requiredPosition(parsed, 0, "run-id"), hookEventId, ...(contextSha256 ? { contextSha256 } : {}), ...(externalContext ? { externalContext } : {}) }), externalContext);
+            return attachExternalStageContext(startVnextCodeReview(context, { projectRoot, runId: requiredPosition(parsed, 0, "run-id"), hookEventId, ...(contextSha256 ? { contextSha256 } : {}), ...(externalContext ? { externalContext } : {}) }, prepared.codeReviewStart), externalContext);
         }
         if (!bootstrap && stage === "merge" && isVnextMergeRun(context, { projectRoot, runId: requiredPosition(parsed, 0, "run-id") })) {
             hookEventId ??= claimVnextStageStart(requiredPosition(parsed, 0, "run-id"));
-            return attachExternalStageContext(await startVnextMerge(context, { projectRoot, runId: requiredPosition(parsed, 0, "run-id"), hookEventId, progress: commandProgress(io, output), ...(contextSha256 ? { contextSha256 } : {}), ...(externalContext ? { externalContext } : {}) }), externalContext);
+            return attachExternalStageContext(await startVnextMerge(context, { projectRoot, runId: requiredPosition(parsed, 0, "run-id"), hookEventId, progress: commandProgress(io, output), ...(contextSha256 ? { contextSha256 } : {}), ...(externalContext ? { externalContext } : {}) }, prepared.mergeStart), externalContext);
         }
         if (intakeStdin) {
             throw new AppError("usage", "--intake-stdin is only available for vNext SPECIFY", 2);
@@ -864,7 +1827,7 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
             ...(hookEventId ? { hookEventId } : {}),
             ...(requireSessionBinding ? { requireSessionBinding: true } : {}),
             ...(dir ? { dir } : {})
-        });
+        }, prepared.legacyStageStart);
     }
     if (family === "stage" && command === "finish") {
         const dir = optionalOption(parsed, "dir");
@@ -874,9 +1837,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 = prepared.retryReason;
+        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,84 +1865,92 @@ 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) }),
+                ...(resultFile ? { resultFile } : prepared.stageFinish?.value ? {} : { resultJson: await readStdin(io.stdin) }),
+                ...(prepared.stageFinish?.value ? { result: prepared.stageFinish.value } : {}),
                 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, ...(prepared.stageFinish?.value ? { result: prepared.stageFinish.value } : {}) }));
         }
         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, ...(prepared.planFinish ? { prepared: prepared.planFinish } : {}) }));
         }
         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 } : {}), ...(prepared.stageFinish?.value ? { decision: prepared.stageFinish.value, decisionText: prepared.stageFinish.text } : {}) }));
         }
         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"), ...(prepared.stageFinish?.value ? { verification: prepared.stageFinish.value } : {}), ...(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") } : {}), ...(prepared.stageFinish?.value ? { decision: prepared.stageFinish.value, decisionText: prepared.stageFinish.text } : {}), ...(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) }, prepared.mergeFinish));
         }
         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 } : {})
-        });
+        }, prepared.legacyStageFinish));
     }
     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"),
-            question: await readStdin(io.stdin)
+            projectRoot,
+            runId,
+            stage,
+            workId,
+            question: prepared.interactionText ?? await readStdin(io.stdin)
         });
     }
     if (family === "stage" && command === "resume") {
-        if (!hasOption(parsed, "answer-stdin"))
-            throw new AppError("usage", "stage resume requires --answer-stdin", 2);
         const hookEventId = optionalOption(parsed, "hook-event-id");
         return resumeStageAfterUser(context, {
             projectRoot: requiredOption(parsed, "project-root"),
             runId: requiredPosition(parsed, 0, "run-id"),
             stage: requiredOption(parsed, "stage"),
             workId: requiredOption(parsed, "work"),
-            answer: await readStdin(io.stdin),
+            answer: prepared.interactionText ?? await readStdin(io.stdin),
+            evidence: prepared.resumeEvidence,
             ...(hookEventId ? { hookEventId } : {})
         });
     }
     if (family === "stage" && command === "block") {
-        if (!hasOption(parsed, "summary-stdin"))
-            throw new AppError("usage", "stage block requires --summary-stdin", 2);
         const kind = requiredOption(parsed, "kind");
         if (kind !== "engine" && kind !== "harness" && kind !== "environment")
             throw new AppError("usage", "--kind must be engine, harness or environment", 2);
@@ -976,7 +1961,7 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
             workId: requiredOption(parsed, "work"),
             kind,
             code: requiredOption(parsed, "code"),
-            summary: await readStdin(io.stdin),
+            summary: prepared.interactionText ?? await readStdin(io.stdin),
             retryable: hasOption(parsed, "retryable")
         });
     }
@@ -1001,13 +1986,55 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
         return dispatchMergeWorker(context, command, parsed);
     }
     if (family === "cleanup") {
-        return dispatchCleanup(context, command, parsed);
+        return dispatchCleanup(context, command, parsed, prepared.cleanup);
     }
     if (family === "session") {
-        return dispatchSession(context, command, parsed);
+        return dispatchSession(context, command, parsed, prepared.sessionPayload);
     }
     if (family === "run") {
-        return dispatchRun(context, command, parsed);
+        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, controllerLaunchInput(parsed), prepared.controllerLaunch);
+            if (action === "serve")
+                return await serveRunController(context, { ...scope, controllerId: requiredOption(parsed, "controller-id") });
+            if (action === "answer")
+                return answerRunController(context, controllerAnswerInput(parsed), prepared.controllerAnswer);
+            if (action === "context")
+                return supplyRunControllerContext(context, controllerContextInput(parsed), prepared.controllerContext);
+            throw new AppError("usage", "Use: dd-flow run drive launch|status|answer|context", 2);
+        }
+        return dispatchRun(context, command, parsed, prepared);
     }
     if (family === "stat") {
         return dispatchStat(context, command, parsed);
@@ -1022,22 +2049,26 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
         return dispatchDashboard(context, command, parsed);
     }
     if (family === "schema") {
-        return dispatchSchema(context, command, parsed);
+        return prepared.schemaValidation;
     }
     if (family === "memory") {
         return dispatchMemory(command, parsed);
     }
     if (family === "migration") {
-        return dispatchMigration(context, command, parsed, classification);
+        return dispatchMigration(context, command, parsed, classification, prepared);
     }
     if (family === "codex" && command === "hooks") {
-        return dispatchCodexHooks(context, parsed);
+        return dispatchCodexHooks(context, parsed, prepared);
     }
     if (family === "codex" && command === "home") {
-        return dispatchCodexHome(context, parsed);
+        return dispatchCodexHome(context, parsed, prepared);
     }
     if (family === "codex" && command === "hook") {
-        return dispatchCodexHook(context, parsed, await readStdin(io.stdin));
+        // `handle` is owned by the pre-context ingress above, never generic dispatch.
+        throw new AppError("usage", "Use: dd-flow codex hook handle --event EVENT", 2);
+    }
+    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 +2094,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") {
@@ -1071,11 +2112,14 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
         return ingestAgyUsage(context, { projectRoot: requiredOption(parsed, "project-root"), stdin: await readStdin(io.stdin) });
     }
     if (family === "worktree") {
-        return dispatchWorktree(context, command, parsed, requiredScopeProjectRoot(scopeProjectRoot, `worktree ${command ?? ""}`));
+        return dispatchWorktree(context, command, parsed, requiredScopeProjectRoot(scopeProjectRoot, `worktree ${command ?? ""}`), prepared);
     }
     throw new AppError("usage", `Unknown command: ${args.join(" ") || "<empty>"}`, 2);
 }
-function dispatchEngine(context, command, parsed, classification) {
+function engineBindInput(parsed) {
+    return { projectRoot: requiredOption(parsed, "project-root"), runId: requiredPosition(parsed, 0, "run-id"), packageName: optionalOption(parsed, "package"), engineVersion: requiredOption(parsed, "engine-version"), integrityChecksum: optionalOption(parsed, "integrity-checksum"), reason: requiredOption(parsed, "reason") };
+}
+function dispatchEngine(context, command, parsed, classification, prepared) {
     if (command === "install") {
         return installCurrentEngine(context, { force: hasOption(parsed, "force") });
     }
@@ -1100,18 +2144,11 @@ function dispatchEngine(context, command, parsed, classification) {
         });
     }
     if (command === "bind-run") {
-        return bindRunEngine(context, {
-            projectRoot: requiredOption(parsed, "project-root"),
-            runId: requiredPosition(parsed, 0, "run-id"),
-            packageName: optionalOption(parsed, "package"),
-            engineVersion: requiredOption(parsed, "engine-version"),
-            integrityChecksum: optionalOption(parsed, "integrity-checksum"),
-            reason: requiredOption(parsed, "reason")
-        });
+        return bindRunEngine(context, engineBindInput(parsed), prepared.engineBind);
     }
     throw new AppError("usage", `Unknown engine command: ${command ?? "<empty>"}`, 2);
 }
-function dispatchMigration(context, command, parsed, classification) {
+function dispatchMigration(context, command, parsed, classification, prepared) {
     if (command === "impact")
         return assessMigrationImpact(context, { projectRoot: requiredOption(parsed, "project-root"), ...(optionalOption(parsed, "target-version") ? { targetVersion: optionalOption(parsed, "target-version") } : {}), ...(optionalOption(parsed, "mode") ? { mode: optionalOption(parsed, "mode") } : {}) });
     if (command === "plan" || command === "report") {
@@ -1127,26 +2164,42 @@ function dispatchMigration(context, command, parsed, classification) {
         });
     }
     if (command === "verify") {
-        return verifyMigrationReport(context, { file: requiredOption(parsed, "file") });
+        return prepared.migrationVerification ?? verifyMigrationReport(context, { file: requiredOption(parsed, "file") });
     }
     if (command === "apply") {
-        return applyMigration(context, {
-            projectRoot: requiredOption(parsed, "project-root"),
-            sourceVersion: optionalOption(parsed, "source-version"),
-            targetVersion: optionalOption(parsed, "target-version"),
-            runId: optionalOption(parsed, "run"),
-            backupPath: optionalOption(parsed, "backup-path"),
-            backupCreatedAt: optionalOption(parsed, "backup-created-at"),
-            reportFile: optionalOption(parsed, "file"),
-            allowActive: false,
-            classification
-        });
+        return applyMigration(context, migrationApplyInput(parsed, classification), prepared.migrationApply);
     }
     throw new AppError("usage", `Unknown migration command: ${command ?? "<empty>"}`, 2);
 }
-function dispatchCanon(context, command, parsed) {
+function protocolTransitionInput(parsed, scopeProjectRoot) {
+    const reason = optionalOption(parsed, "reason");
+    return { protocolId: requiredPosition(parsed, 0, "protocol-id"), projectRoot: requiredScopeProjectRoot(scopeProjectRoot, "protocol transition"), to: requiredOption(parsed, "to"), jsonFile: requiredOptionAlias(parsed, ["payload-file", "json-file"]), force: hasOption(parsed, "force"), ...(reason ? { reason } : {}) };
+}
+function controllerAnswerInput(parsed) {
+    return { projectRoot: requiredOption(parsed, "project-root"), runId: requiredOption(parsed, "run"), requestId: requiredOption(parsed, "request-id"), pauseId: requiredOption(parsed, "pause-id"), answerFile: requiredOption(parsed, "answer-file") };
+}
+function controllerLaunchInput(parsed) {
+    return { projectRoot: requiredOption(parsed, "project-root"), runId: requiredOption(parsed, "run"), 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") } : {}) };
+}
+function controllerContextInput(parsed) {
+    return { projectRoot: requiredOption(parsed, "project-root"), runId: requiredOption(parsed, "run"), controllerId: requiredOption(parsed, "controller-id"), requestId: requiredOption(parsed, "request-id"), stage: requiredOption(parsed, "stage"), contextFile: requiredOption(parsed, "context-file"), contextSha256: requiredOption(parsed, "context-sha256") };
+}
+function migrationApplyInput(parsed, classification) {
+    return {
+        projectRoot: requiredOption(parsed, "project-root"),
+        sourceVersion: optionalOption(parsed, "source-version"),
+        targetVersion: optionalOption(parsed, "target-version"),
+        runId: optionalOption(parsed, "run"),
+        backupPath: optionalOption(parsed, "backup-path"),
+        backupCreatedAt: optionalOption(parsed, "backup-created-at"),
+        reportFile: optionalOption(parsed, "file"),
+        allowActive: false,
+        classification
+    };
+}
+function dispatchCanon(context, command, parsed, prepared) {
     if (command === "register") {
-        return registerCanonRoot(context, { root: requiredOption(parsed, "root") });
+        return registerCanonRoot(context, { root: requiredOption(parsed, "root") }, prepared.canonRegistration);
     }
     if (command === "status") {
         return getCanonStatus(context, { root: optionalOption(parsed, "root") });
@@ -1156,6 +2209,15 @@ function dispatchCanon(context, command, parsed) {
     }
     throw new AppError("usage", `Unknown canon command: ${command ?? "<empty>"}`, 2);
 }
+function mergeJobTarget(parsed, scopeProjectRoot) {
+    return { protocolId: requiredPosition(parsed, 0, "protocol-id"), projectRoot: requiredScopeProjectRoot(scopeProjectRoot, "merge-queue"), workerId: requiredWorkerId(parsed), workspacePath: workspacePathOption(parsed) };
+}
+function mergeCancellationInput(parsed, scopeProjectRoot) {
+    return { protocolId: requiredPosition(parsed, 0, "protocol-id"), projectRoot: requiredScopeProjectRoot(scopeProjectRoot, "merge-queue cancel"), reason: requiredOption(parsed, "reason"), workerId: optionalOption(parsed, "worker-id"), workspacePath: optionalOption(parsed, "path"), force: hasOption(parsed, "force") };
+}
+function mergeWaitInput(parsed, scopeProjectRoot) {
+    return { projectRoot: requiredOptionOrScope(parsed, scopeProjectRoot, "project-root"), workerId: requiredWorkerId(parsed), timeoutSeconds: optionalNumber(parsed, "timeout"), pollIntervalSeconds: optionalNumber(parsed, "poll-interval"), workspacePath: workspacePathOption(parsed), acquireLock: parseOptionalBoolean(optionalOption(parsed, "acquire-lock"), "acquire-lock") ?? false };
+}
 function dispatchMergeQueue(context, command, parsed, scopeProjectRoot) {
     if (hasOption(parsed, "session-id")) {
         throw new AppError("usage", "--session-id is no longer accepted on merge-queue commands; use --worker-id", 2);
@@ -1179,32 +2241,17 @@ function dispatchMergeQueue(context, command, parsed, scopeProjectRoot) {
         });
     }
     if (command === "wait-next") {
-        return waitNextMergeJob(context, {
-            projectRoot: requiredOptionOrScope(parsed, scopeProjectRoot, "project-root"),
-            workerId: requiredWorkerId(parsed),
-            timeoutSeconds: optionalNumber(parsed, "timeout"),
-            pollIntervalSeconds: optionalNumber(parsed, "poll-interval"),
-            workspacePath: workspacePathOption(parsed),
-            acquireLock: parseOptionalBoolean(optionalOption(parsed, "acquire-lock"), "acquire-lock") ?? false
-        });
+        return waitNextMergeJob(context, mergeWaitInput(parsed, scopeProjectRoot));
     }
     if (command === "complete") {
-        const protocolId = requiredPosition(parsed, 0, "protocol-id");
         return completeMergeJob(context, {
-            protocolId,
-            projectRoot: requiredScopeProjectRoot(scopeProjectRoot, "merge-queue complete"),
-            workerId: requiredWorkerId(parsed),
-            workspacePath: workspacePathOption(parsed),
+            ...mergeJobTarget(parsed, scopeProjectRoot),
             summary: requiredOption(parsed, "summary")
         });
     }
     if (command === "fail") {
-        const protocolId = requiredPosition(parsed, 0, "protocol-id");
         return failMergeJob(context, {
-            protocolId,
-            projectRoot: requiredScopeProjectRoot(scopeProjectRoot, "merge-queue fail"),
-            workerId: requiredWorkerId(parsed),
-            workspacePath: workspacePathOption(parsed),
+            ...mergeJobTarget(parsed, scopeProjectRoot),
             reason: requiredOption(parsed, "reason"),
             requeue: parseBoolean(requiredOption(parsed, "requeue"), "requeue")
         });
@@ -1219,15 +2266,7 @@ function dispatchMergeQueue(context, command, parsed, scopeProjectRoot) {
         });
     }
     if (command === "cancel") {
-        const protocolId = requiredPosition(parsed, 0, "protocol-id");
-        return cancelMergeQueueJob(context, {
-            protocolId,
-            projectRoot: requiredScopeProjectRoot(scopeProjectRoot, "merge-queue cancel"),
-            reason: requiredOption(parsed, "reason"),
-            workerId: optionalOption(parsed, "worker-id"),
-            workspacePath: optionalOption(parsed, "path"),
-            force: hasOption(parsed, "force")
-        });
+        return cancelMergeQueueJob(context, mergeCancellationInput(parsed, scopeProjectRoot));
     }
     throw new AppError("usage", `Unknown merge-queue command: ${command ?? "<empty>"}`, 2);
 }
@@ -1345,7 +2384,7 @@ function completedCommandExitCode(payload) {
     const exitCode = payload.exit_code;
     return typeof exitCode === "number" && Number.isInteger(exitCode) ? exitCode : 0;
 }
-function dispatchCleanup(context, command, parsed) {
+function dispatchCleanup(context, command, parsed, prepared) {
     if (command === "scan") {
         return cleanupScan(context, { projectRoot: requiredOption(parsed, "project-root") });
     }
@@ -1353,6 +2392,7 @@ function dispatchCleanup(context, command, parsed) {
         return cleanupApply(context, {
             projectRoot: requiredOption(parsed, "project-root"),
             planFile: requiredOption(parsed, "plan-file"),
+            prepared,
             reason: requiredOption(parsed, "reason"),
             force: hasOption(parsed, "force")
         });
@@ -1373,12 +2413,14 @@ function dispatchProjectConfig(context, parsed) {
     }
     throw new AppError("usage", `Unknown project config action: ${action}`, 2);
 }
-function dispatchSession(context, command, parsed) {
+function dispatchSession(context, command, parsed, preparedPayload) {
     if (command === "register") {
         return registerFlowSession(context, {
+            ...(preparedPayload ? { preparedPayload } : {}),
             payloadBase64: optionalOption(parsed, "payload-base64"),
             payloadJson: optionalOption(parsed, "payload-json"),
             payloadFile: optionalOption(parsed, "payload-file"),
+            hookEventId: optionalOption(parsed, "hook-event-id"),
             sessionId: optionalOption(parsed, "session-id")
         });
     }
@@ -1411,7 +2453,45 @@ function dispatchSession(context, command, parsed) {
     }
     throw new AppError("usage", `Unknown session command: ${command ?? "<empty>"}`, 2);
 }
-function dispatchRun(context, command, parsed) {
+function snapshotCreateInput(parsed) {
+    const recoveryId = optionalOption(parsed, "recovery-id"), stageEntry = optionalOption(parsed, "stage-entry");
+    return { projectRoot: requiredOption(parsed, "project-root"), runId: requiredPosition(parsed, 1, "run-id"), output: requiredOption(parsed, "output"), candidate: parsed.options.has("candidate"), incomplete: parsed.options.has("incomplete"), ...(recoveryId !== undefined ? { recoveryId } : {}), ...(stageEntry !== undefined ? { stageEntry } : {}) };
+}
+function snapshotRestoreInput(parsed) {
+    return { snapshot: requiredOption(parsed, "snapshot"), projectRoot: requiredOption(parsed, "project-root"), executionRoutingFile: optionalOption(parsed, "execution-routing-file"), operationalDecisionFile: optionalOption(parsed, "operational-decision-file"), ...(optionalOption(parsed, "recovery-id") ? { recoveryId: requiredOption(parsed, "recovery-id") } : {}) };
+}
+function runStartInput(parsed) {
+    const protocolOverrides = readOptionalJsonFile(optionalOption(parsed, "protocol-override-file"));
+    return { projectRoot: requiredOption(parsed, "project-root"), workspaceRoot: optionalOption(parsed, "workspace-root"), flowKind: requiredOption(parsed, "flow-kind"), subjectType: requiredOption(parsed, "subject-type"), subjectId: requiredOption(parsed, "subject-id"), slug: requiredOption(parsed, "slug"), nextAction: optionalOption(parsed, "next-action"), preset: optionalOption(parsed, "preset"), taskProfile: readOptionalJsonFile(optionalOption(parsed, "task-profile-file")), executionRoutingFile: optionalOption(parsed, "execution-routing-file"), ...(protocolOverrides !== undefined ? { protocolOverrides } : {}), runOverrides: parseFlowFlagOverrides(allOptions(parsed, "flag")) };
+}
+function runForkInput(parsed) {
+    return { 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") } : {}), ...(optionalOption(parsed, "operational-decision-file") ? { operationalDecisionFile: optionalOption(parsed, "operational-decision-file") } : {}) };
+}
+function recoveryCaptureInput(parsed) {
+    return { projectRoot: requiredOption(parsed, "project-root"), runId: requiredPosition(parsed, 1, "run-id"), recoveryId: requiredOption(parsed, "recovery-id"), capturePath: requiredOption(parsed, "capture-path") };
+}
+function recoveryResumeInput(parsed) {
+    return { projectRoot: requiredOption(parsed, "project-root"), runId: requiredPosition(parsed, 1, "run-id"), recoveryId: requiredOption(parsed, "recovery-id"), daemonId: requiredOption(parsed, "daemon-id"), harness: requiredOption(parsed, "harness"), nativeSessionId: requiredOption(parsed, "native-session-id") };
+}
+function dispatchRun(context, command, parsed, prepared = {}) {
+    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") }, prepared.recoveryPayload);
+        if (action === "seal")
+            return sealRunRecovery(context, { projectRoot, runId, recoveryId: requiredOption(parsed, "recovery-id"), settlement: requiredOption(parsed, "settlement-json") }, prepared.recoveryPayload);
+        if (action === "capture")
+            return recordRecoveryCapture(context, recoveryCaptureInput(parsed), prepared.recoveryCapture);
+        if (action === "resume")
+            return resumeRunRecovery(context, recoveryResumeInput(parsed), prepared.recoveryResume);
+        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") {
@@ -1422,56 +2502,27 @@ function dispatchRun(context, command, parsed) {
                     output: requiredOption(parsed, "output")
                 });
             if (bootstrapAction === "restore")
-                return restoreEvalBootstrapSnapshot(context, {
-                    snapshot: requiredOption(parsed, "snapshot"),
-                    projectRoot: requiredOption(parsed, "project-root")
-                });
+                return restoreEvalBootstrapSnapshot(context, snapshotRestoreInput(parsed), prepared.bootstrapRestore);
             throw new AppError("usage", "Use: dd-flow run snapshot bootstrap create|restore", 2);
         }
         if (action === "create") {
-            const candidate = parsed.options.has("candidate");
-            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);
-            const input = {
-                projectRoot: requiredOption(parsed, "project-root"),
-                runId: requiredPosition(parsed, 1, "run-id"),
-                output: requiredOption(parsed, "output")
-            };
-            return candidate
-                ? createEvalRunSnapshot(context, { ...input, candidate: true })
-                : createEvalRunSnapshot(context, { ...input, stageEntry: stageEntry });
+            return createEvalRunSnapshot(context, snapshotCreateInput(parsed));
         }
         if (action === "restore")
-            return restoreEvalRunSnapshot(context, {
-                snapshot: requiredOption(parsed, "snapshot"),
-                projectRoot: requiredOption(parsed, "project-root")
-            });
+            return restoreEvalRunSnapshot(context, snapshotRestoreInput(parsed), prepared.snapshotRestore);
         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, runForkInput(parsed), prepared.runFork);
+    }
     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") {
             assertUpgradeRunStorageReady(context, requiredOption(parsed, "project-root"));
         }
-        const protocolOverrides = readOptionalJsonFile(optionalOption(parsed, "protocol-override-file"));
-        return startFlowRun(context, {
-            projectRoot: requiredOption(parsed, "project-root"),
-            workspaceRoot: optionalOption(parsed, "workspace-root"),
-            flowKind: requiredOption(parsed, "flow-kind"),
-            subjectType: requiredOption(parsed, "subject-type"),
-            subjectId: requiredOption(parsed, "subject-id"),
-            slug: requiredOption(parsed, "slug"),
-            nextAction: optionalOption(parsed, "next-action"),
-            preset: optionalOption(parsed, "preset"),
-            taskProfile: readOptionalJsonFile(optionalOption(parsed, "task-profile-file")),
-            ...(protocolOverrides ? { protocolOverrides } : {}),
-            runOverrides: parseFlowFlagOverrides(allOptions(parsed, "flag"))
-        });
+        return startFlowRun(context, prepared.runStart?.input ?? runStartInput(parsed), prepared.runStart?.value);
     }
     if (command === "status") {
         return getFlowRunStatus(context, {
@@ -1541,83 +2592,79 @@ function dispatchRun(context, command, parsed) {
         throw new AppError("usage", `Unknown run flags command: ${action}`, 2);
     }
     if (command === "attach-stage") {
-        return attachFlowRunStage(context, {
-            projectRoot: requiredOption(parsed, "project-root"),
-            runId: requiredPosition(parsed, 0, "run-id"),
-            stage: requiredOption(parsed, "stage"),
-            dir: requiredOption(parsed, "dir"),
-            status: requiredOption(parsed, "status"),
-            dataSchemaId: optionalOption(parsed, "data-schema-id")
-        });
+        return attachFlowRunStage(context, stageAttachmentInput(parsed));
     }
     if (command === "complete-stage") {
-        const stageReport = optionalOption(parsed, "stage-report") ?? optionalOption(parsed, "dashboard");
-        return completeFlowRunStage(context, {
-            projectRoot: requiredOption(parsed, "project-root"),
-            runId: requiredPosition(parsed, 0, "run-id"),
-            stage: requiredOption(parsed, "stage"),
-            status: requiredOption(parsed, "status"),
-            stageReport,
-            data: optionalOption(parsed, "data"),
-            dataSchemaId: optionalOption(parsed, "data-schema-id"),
-            report: optionalOption(parsed, "report"),
-            aliases: allOptions(parsed, "alias")
-        });
+        return completeFlowRunStage(context, stageCompletionInput(parsed));
     }
     if (command === "complete") {
         throw new AppError("usage", "run complete is retired; only an operator may use run override", 2);
     }
     if (command === "override") {
-        const status = requiredOption(parsed, "status");
-        if (!['cancelled', 'failed'].includes(status)) {
-            throw new AppError("usage", "run override status must be cancelled or failed", 2, { status });
-        }
-        return completeFlowRun(context, {
-            projectRoot: requiredOption(parsed, "project-root"),
-            runId: requiredPosition(parsed, 0, "run-id"),
-            status,
-            verdict: optionalOption(parsed, "verdict"),
-            nextAction: optionalOption(parsed, "next-action"),
-            manualOverrideReason: requiredOption(parsed, "reason")
-        });
+        return completeFlowRun(context, runOverrideInput(parsed));
     }
     throw new AppError("usage", `Unknown run command: ${command ?? "<empty>"}`, 2);
 }
-async function dispatchRuntime(context, command, parsed) {
+function stageAttachmentInput(parsed) {
+    return { projectRoot: requiredOption(parsed, "project-root"), runId: requiredPosition(parsed, 0, "run-id"), stage: requiredOption(parsed, "stage"), dir: requiredOption(parsed, "dir"), status: requiredOption(parsed, "status"), dataSchemaId: optionalOption(parsed, "data-schema-id") };
+}
+function runOverrideInput(parsed) {
+    return { projectRoot: requiredOption(parsed, "project-root"), runId: requiredPosition(parsed, 0, "run-id"), status: requiredOption(parsed, "status"), verdict: optionalOption(parsed, "verdict"), nextAction: optionalOption(parsed, "next-action"), manualOverrideReason: requiredOption(parsed, "reason") };
+}
+function stageCompletionInput(parsed) {
+    return { projectRoot: requiredOption(parsed, "project-root"), runId: requiredPosition(parsed, 0, "run-id"), stage: requiredOption(parsed, "stage"), status: requiredOption(parsed, "status"), stageReport: optionalOption(parsed, "stage-report") ?? optionalOption(parsed, "dashboard"), data: optionalOption(parsed, "data"), dataSchemaId: optionalOption(parsed, "data-schema-id"), report: optionalOption(parsed, "report"), aliases: allOptions(parsed, "alias") };
+}
+function runtimeServiceInput(parsed) {
+    return { 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 };
+}
+function runtimeScopeResumeInput(parsed) {
+    return { scopeId: requiredOption(parsed, "scope-id"), requestId: requiredOption(parsed, "request-id"), generation: Number(requiredOption(parsed, "generation")), captureKey: requiredOption(parsed, "capture-key") };
+}
+async function dispatchRuntime(context, command, parsed, progress, prepared = {}) {
+    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, runtimeScopeResumeInput(parsed)) };
+        }
+        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, undefined, undefined, undefined, prepared.runtimeManifest) };
+        }
+        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 === "register") {
-        const leaseMs = optionalPositiveNumber(parsed, "lease-ms", true);
-        const process = registerManagedProcess(context, {
-            kind: requiredOption(parsed, "kind"), ownerId: requiredOption(parsed, "owner"),
-            projectId: optionalOption(parsed, "project-id") ?? null, runId: optionalOption(parsed, "run") ?? null,
-            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 } : {})
-        });
-        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 } : {}) }) };
-    }
-    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 === "finish") {
-        const state = requiredOption(parsed, "state");
-        if (state !== "stopped" && state !== "failed")
-            throw new AppError("validation", "--state must be stopped or failed", 2);
-        return { ok: finishManagedProcess(context, { id: requiredOption(parsed, "id"), leaseToken: requiredOption(parsed, "lease-token"), state: state, reason: optionalOption(parsed, "reason") ?? null }) };
-    }
-    if (action === "status")
-        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);
+    if (action === "start")
+        return await startRuntimeService(context, { ...runtimeServiceInput(parsed), progress });
+    return await dispatchRuntimeProcess(context, action, parsed, prepared);
 }
 function dispatchStat(context, command, parsed) {
     if (command === "usage") {
@@ -1651,7 +2698,7 @@ function dispatchCmux(context, parsed) {
     }
     throw new AppError("usage", `Unknown integration cmux action: ${action}`, 2);
 }
-function dispatchDashboard(context, command, parsed) {
+async function dispatchDashboard(context, command, parsed) {
     const action = dashboardAction(command);
     if (command === "data") {
         const target = resolveDashboardTarget(context, {
@@ -1686,7 +2733,7 @@ function dispatchDashboard(context, command, parsed) {
             projectRoot: optionalOption(parsed, "project-root"),
             protocol: optionalOption(parsed, "protocol")
         });
-        return withDashboardGuidance(action, target, openDashboardForResolvedTarget(context, target, parsed));
+        return withDashboardGuidance(action, target, await openDashboardForResolvedTarget(context, target, parsed));
     }
     if (command === "refresh") {
         const open = optionalOption(parsed, "open");
@@ -1700,7 +2747,7 @@ function dispatchDashboard(context, command, parsed) {
             protocol: optionalOption(parsed, "protocol"),
             all: hasOption(parsed, "all")
         });
-        return withDashboardGuidance(action, target, refreshDashboardForResolvedTarget(context, target, parsed, open));
+        return withDashboardGuidance(action, target, await refreshDashboardForResolvedTarget(context, target, parsed, open));
     }
     if (command === "refresh-global") {
         const target = resolveDashboardTarget(context, { action: "refresh", global: true });
@@ -1804,7 +2851,9 @@ function dispatchSchema(context, command, parsed) {
         // 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 data = prepareJsonFile(file, "schema input").value;
+        const declared = data && typeof data === "object" && "run_id" in data ? data.run_id : undefined;
+        const declaredRunId = explicitRunId ?? (typeof declared === "string" && declared.trim() ? declared : undefined);
         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 ?? ""])
@@ -1812,6 +2861,7 @@ function dispatchSchema(context, command, parsed) {
         return validateSchema({
             schemaName: requiredOption(parsed, "schema"),
             file,
+            data,
             ...(schemaDir ? { schemaDir } : {}),
             ...(projectRoot ? { projectRoot } : {}),
             ...(declaredRunId || bound?.id ? { runId: declaredRunId ?? bound.id } : {}),
@@ -1821,14 +2871,11 @@ function dispatchSchema(context, command, parsed) {
     }
     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;
-    }
+function laneWorkspaceInput(parsed) {
+    return { projectRoot: requiredOption(parsed, "project-root"), lane: requiredOption(parsed, "lane"), workspacePath: requiredOption(parsed, "path"), branch: optionalOption(parsed, "branch") };
+}
+function laneWaiterCancelInput(parsed) {
+    return { projectRoot: requiredOption(parsed, "project-root"), lane: requiredOption(parsed, "lane"), workerId: requiredOption(parsed, "worker-id"), reason: requiredOption(parsed, "reason") };
 }
 async function dispatchLane(context, command, parsed) {
     if (command === "status") {
@@ -1840,24 +2887,14 @@ async function dispatchLane(context, command, parsed) {
     if (command === "waiter") {
         const action = requiredPosition(parsed, 0, "lane waiter action");
         if (action === "cancel") {
-            return cancelLaneWaiter(context, {
-                projectRoot: requiredOption(parsed, "project-root"),
-                lane: requiredOption(parsed, "lane"),
-                workerId: requiredOption(parsed, "worker-id"),
-                reason: requiredOption(parsed, "reason")
-            });
+            return cancelLaneWaiter(context, laneWaiterCancelInput(parsed));
         }
         throw new AppError("usage", `Unknown lane waiter action: ${action}`, 2);
     }
     if (command === "workspace") {
         const action = requiredPosition(parsed, 0, "lane workspace action");
         if (action === "set") {
-            return setLaneWorkspace(context, {
-                projectRoot: requiredOption(parsed, "project-root"),
-                lane: requiredOption(parsed, "lane"),
-                workspacePath: requiredOption(parsed, "path"),
-                branch: optionalOption(parsed, "branch")
-            });
+            return setLaneWorkspace(context, laneWorkspaceInput(parsed));
         }
         if (action === "check") {
             return checkLaneWorkspace(context, {
@@ -1929,7 +2966,7 @@ async function dispatchLane(context, command, parsed) {
     }
     throw new AppError("usage", `Unknown lane command: ${command ?? "<empty>"}`, 2);
 }
-function dispatchCodexHooks(context, parsed) {
+function dispatchCodexHooks(context, parsed, prepared) {
     const action = requiredPosition(parsed, 0, "codex hooks action");
     if (action === "print") {
         return printCodexHooks(context, {
@@ -1951,7 +2988,7 @@ function dispatchCodexHooks(context, parsed) {
             target: optionalOption(parsed, "target"),
             profile: optionalOption(parsed, "profile"),
             yes: hasOption(parsed, "yes")
-        });
+        }, prepared.codexHooks);
     }
     if (action === "remove") {
         return removeCodexHooks(context, {
@@ -1959,11 +2996,14 @@ function dispatchCodexHooks(context, parsed) {
             target: optionalOption(parsed, "target"),
             profile: optionalOption(parsed, "profile"),
             yes: hasOption(parsed, "yes")
-        });
+        }, prepared.codexHooks);
     }
     throw new AppError("usage", `Unknown codex hooks action: ${action}`, 2);
 }
-function dispatchCodexHome(context, parsed) {
+function codexHomeInput(parsed) {
+    return { projectRoot: requiredOption(parsed, "project-root"), profile: optionalOption(parsed, "profile"), sourceHome: optionalOption(parsed, "source-home"), targetHome: optionalOption(parsed, "target-home") };
+}
+function dispatchCodexHome(context, parsed, prepared) {
     const action = requiredPosition(parsed, 0, "codex home action");
     if (action === "plan") {
         return planCodexHome(context, {
@@ -1974,12 +3014,7 @@ function dispatchCodexHome(context, parsed) {
         });
     }
     if (action === "init") {
-        return initCodexHome(context, {
-            projectRoot: requiredOption(parsed, "project-root"),
-            profile: optionalOption(parsed, "profile"),
-            sourceHome: optionalOption(parsed, "source-home"),
-            targetHome: optionalOption(parsed, "target-home")
-        });
+        return initCodexHome(context, codexHomeInput(parsed), prepared.codexHome);
     }
     if (action === "status") {
         return getCodexHomeStatus(context, {
@@ -2002,23 +3037,6 @@ function dispatchCodexHome(context, parsed) {
     }
     throw new AppError("usage", `Unknown codex home action: ${action}`, 2);
 }
-function dispatchCodexHook(context, parsed, stdin) {
-    const action = requiredPosition(parsed, 0, "codex hook action");
-    if (action === "handle") {
-        const isolatedHome = isolatedDdFlowHomeFromHookStdin(stdin);
-        const hookContext = isolatedHome ? createContext({ ...context.env, DD_FLOW_HOME: isolatedHome }) : context;
-        const result = handleCodexHook(hookContext, {
-            event: requiredOption(parsed, "event"),
-            projectRoot: optionalOption(parsed, "project-root"),
-            stdin
-        });
-        if (result && typeof result === "object" && !Array.isArray(result) && "hookSpecificOutput" in result) {
-            return { hookSpecificOutput: result.hookSpecificOutput };
-        }
-        return {};
-    }
-    throw new AppError("usage", `Unknown codex hook action: ${action}`, 2);
-}
 function dispatchZcodeEvent(context, parsed, stdin) {
     const action = requiredPosition(parsed, 0, "zcode event action");
     if (action === "handle") {
@@ -2029,6 +3047,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") {
@@ -2052,7 +3079,7 @@ function dispatchAgyEvent(context, parsed, stdin) {
         return handleAgyEvent(context, { projectRoot: requiredOption(parsed, "project-root"), stdin });
     throw new AppError("usage", `Unknown agy event action: ${action}`, 2);
 }
-function dispatchWorktree(context, command, parsed, scopeProjectRoot) {
+function dispatchWorktree(context, command, parsed, scopeProjectRoot, prepared) {
     if (command === "plan") {
         return planWorktree(context, { protocolId: requiredOption(parsed, "protocol-id"), projectRoot: scopeProjectRoot });
     }
@@ -2063,13 +3090,13 @@ function dispatchWorktree(context, command, parsed, scopeProjectRoot) {
             branch: requiredOption(parsed, "branch"),
             base: requiredOption(parsed, "base"),
             path: requiredOption(parsed, "path")
-        });
+        }, prepared.worktreeCreate);
     }
     if (command === "status") {
         return getWorktreeStatus(context, { protocolId: requiredOption(parsed, "protocol-id"), projectRoot: scopeProjectRoot });
     }
     if (command === "bootstrap") {
-        return bootstrapWorktree(context, { protocolId: requiredOption(parsed, "protocol-id"), projectRoot: scopeProjectRoot });
+        return bootstrapWorktree(context, { protocolId: requiredOption(parsed, "protocol-id"), projectRoot: scopeProjectRoot }, prepared.worktreeBootstrap);
     }
     if (command === "close") {
         return closeWorktree(context, {
@@ -2081,52 +3108,50 @@ function dispatchWorktree(context, command, parsed, scopeProjectRoot) {
     throw new AppError("usage", `Unknown worktree command: ${command ?? "<empty>"}`, 2);
 }
 function dispatchPlanItem(context, parsed, projectRoot) {
+    return updatePlanItem(context, planItemInput(parsed, projectRoot));
+}
+function planItemInput(parsed, projectRoot) {
     const action = requiredPosition(parsed, 0, "plan item action");
     const protocolId = requiredPosition(parsed, 1, "protocol-id");
     const itemId = requiredPosition(parsed, 2, "item-id");
     if (action === "start") {
-        return startPlanItem(context, { protocolId, projectRoot, itemId });
+        return { protocolId, projectRoot, itemId, action };
     }
     if (action === "done") {
-        return completePlanItem(context, {
+        return {
+            action,
             protocolId,
             projectRoot,
             itemId,
             summary: requiredOption(parsed, "summary"),
             evidence: parsed.options.get("evidence") ?? []
-        });
+        };
     }
     if (action === "block") {
-        return blockPlanItem(context, {
+        return {
+            action,
             protocolId,
             projectRoot,
             itemId,
             reason: requiredOption(parsed, "reason"),
             userRequired: parseBoolean(requiredOption(parsed, "user-required"), "user-required")
-        });
+        };
     }
     if (action === "skip") {
-        return skipPlanItem(context, {
+        return {
+            action,
             protocolId,
             projectRoot,
             itemId,
             reason: requiredOption(parsed, "reason")
-        });
+        };
     }
     throw new AppError("usage", `Unknown plan item action: ${action}`, 2);
 }
 function readOptionalJsonFile(file) {
     if (!file)
         return undefined;
-    if (!fs.existsSync(file)) {
-        throw new AppError("not_found", `JSON file does not exist: ${file}`, 1);
-    }
-    try {
-        return JSON.parse(fs.readFileSync(file, "utf8"));
-    }
-    catch {
-        throw new AppError("validation", `JSON file is malformed: ${file}`, 2);
-    }
+    return prepareJsonFile(file, "JSON input").value;
 }
 function parseFlowFlagOverrides(values) {
     const result = {};
@@ -2158,21 +3183,9 @@ function requiredPosition(parsed, index, label) {
     }
     return value;
 }
-function optionalOption(parsed, key) {
-    const values = parsed.options.get(key);
-    const value = values?.[values.length - 1];
-    return value === flagValue ? undefined : value;
-}
 function allOptions(parsed, key) {
     return (parsed.options.get(key) ?? []).filter((value) => value !== flagValue);
 }
-function requiredOption(parsed, key) {
-    const value = optionalOption(parsed, key);
-    if (!value) {
-        throw new AppError("usage", `Missing required option: --${key}`, 2);
-    }
-    return value;
-}
 function requiredScopeProjectRoot(root, operation) {
     if (root)
         return root;
@@ -2212,26 +3225,6 @@ function parseBoolean(value, key) {
 function parseOptionalBoolean(value, key) {
     return typeof value === "string" ? parseBoolean(value, key) : undefined;
 }
-function optionalNumber(parsed, key) {
-    const value = optionalOption(parsed, key);
-    if (typeof value === "undefined") {
-        return undefined;
-    }
-    const parsedNumber = Number(value);
-    if (!Number.isFinite(parsedNumber)) {
-        throw new AppError("validation", `--${key} must be a number`, 2);
-    }
-    return parsedNumber;
-}
-function optionalPositiveNumber(parsed, key, integer = false) {
-    const value = optionalNumber(parsed, key);
-    if (typeof value === "undefined")
-        return undefined;
-    if (value <= 0 || (integer && !Number.isInteger(value))) {
-        throw new AppError("validation", `--${key} must be a positive${integer ? " integer" : ""} number`, 2);
-    }
-    return value;
-}
 function requiredWorkerId(parsed) {
     return requiredOption(parsed, "worker-id");
 }
@@ -2327,7 +3320,7 @@ function projectRootForMutation(context, args, result, resolvedScope) {
         return projectRootForMergeQueueMutation(context, command, parsed);
     }
     if (family === "merge" && ["one-shot", "apply", "repair", "request"].includes(command ?? "")) {
-        return requiredOption(parsed, "project-root");
+        return resolvedScope ?? requiredOption(parsed, "project-root");
     }
     if (family === "merge-worker" && ["start", "stop"].includes(command ?? "")) {
         return requiredOption(parsed, "project-root");
@@ -2345,7 +3338,7 @@ function projectRootForMutation(context, args, result, resolvedScope) {
         return requiredOption(parsed, "project-root");
     }
     if (family === "stage" && ["start", "pause", "resume", "finish"].includes(command ?? "")) {
-        return requiredOption(parsed, "project-root");
+        return resolvedScope ?? requiredOption(parsed, "project-root");
     }
     if (family === "worktree" && ["create", "bootstrap", "close"].includes(command ?? "")) {
         return protocolProjectRoot(context, requiredOption(parsed, "protocol-id"));
@@ -2359,7 +3352,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");
@@ -2396,14 +3389,36 @@ function projectRootForMergeQueueMutation(context, command, parsed) {
 function protocolProjectRoot(context, protocolId) {
     return requireProtocol(context, protocolId).project_root;
 }
+function prepareCliWorkRepair(context, parsed, objective, scopeProjectRoot) {
+    const origins = parsed.options.get("origin-work") ?? [], findings = parsed.options.get("from-finding") ?? [], unresolved = parsed.options.get("from-unresolved") ?? [], receipts = parsed.options.get("from-check") ?? [];
+    if ([findings.length > 0, unresolved.length > 0, receipts.length > 0].filter(Boolean).length !== 1)
+        throw new AppError("usage", "Repair requires exactly one source: --from-check, --from-finding or --from-unresolved", 2);
+    const scope = { projectRoot: requiredScopeProjectRoot(scopeProjectRoot, "work repair add"), runId: requiredOption(parsed, "run"), objective };
+    if (findings.length) {
+        if (origins.length || hasOption(parsed, "verification-file"))
+            throw new AppError("usage", "Finding repair derives its origins and cannot accept --origin-work or --verification-file", 2);
+        return prepareVnextCodeReviewRepair(context, { ...scope, findingIds: findings, checkRefsByFinding: Object.fromEntries(findings.map(finding => [finding, parsed.options.get("check-ref") ?? []])) });
+    }
+    if (!origins.length)
+        throw new AppError("usage", "Repair requires at least one --origin-work", 2);
+    if (hasOption(parsed, "check-ref"))
+        throw new AppError("usage", "--check-ref is only supported with --from-finding", 2);
+    if (receipts.length > 1)
+        throw new AppError("usage", "Create one repair Work per --from-check receipt", 2);
+    if (!unresolved.length && hasOption(parsed, "verification-file"))
+        throw new AppError("usage", "--verification-file is only supported with --from-unresolved", 2);
+    const input = { ...scope, originWorkIds: origins, ...(unresolved.length ? { semanticUnresolved: unresolved, verificationPath: requiredOption(parsed, "verification-file") } : { checkReceiptId: receipts[0] }) };
+    return { input, value: prepareVnextCodeRepair(context, input) };
+}
+function workerPromptInput(parsed) {
+    const workspaceRoot = optionalOption(parsed, "workspace-root"), taskFile = optionalOption(parsed, "task-file");
+    return { projectRoot: requiredOption(parsed, "project-root"), runId: requiredOption(parsed, "run"), stage: requiredOption(parsed, "stage"), profile: requiredOption(parsed, "profile"), ...(taskFile ? { taskFile } : { planItemId: requiredOption(parsed, "plan-item") }), ...(workspaceRoot ? { workspaceRoot } : {}) };
+}
 function runnerIntake(context) {
     const input = context.value.task_input?.[0];
     if (!input?.path)
         throw new AppError("validation", "Runner SPECIFY context requires one ordered task_input file", 2);
-    const file = path.resolve(input.path);
-    if (!fs.existsSync(file) || !fs.statSync(file).isFile())
-        throw new AppError("not_found", "Runner SPECIFY task input is missing", 2, { task_input: file });
-    return fs.readFileSync(file, "utf8");
+    return prepareTextFile(input.path, "Runner SPECIFY task input").text;
 }
 /** Stage services install context before their lifecycle transition.  Keeping
  * this check here makes an incomplete service migration fail closed instead of