@deksden-com/dd-flow-cli 0.9.0-beta.136 → 0.9.0-beta.138

package/dist/cli/run-cli.js

@@ -1,4 +1,5 @@
 import fs from "node:fs";
+import { prepareResponseDestination, writeResponseFile } from "./response-file.js";
 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";
@@ -12,7 +13,14 @@ 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 { resolveHelp } from "./help.js";
+import { renderHumanError, writePreparationError } from "./error-output.js";
+import { runOperatorProfilesCli } from "./operator-profiles.js";
+import { runSetupCli } from "./setup.js";
+import { runCompletionCli } from "./completion-cli.js";
+import { runHarnessesCli } from "./harnesses.js";
+import { runModelsCli } from "./models.js";
+import { parseOutputOptions } from "./output-options.js";
 import { AppError, errorRecord, isAppError } from "../shared/errors.js";
 import { entityReferenceVariants } from "../shared/entity-references.js";
 import { writeJson, parseJsonObject } from "../shared/json.js";
@@ -22,7 +30,7 @@ import { getPlanStatus, preparePlanItemMutation, updatePlanItem } from "../servi
 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, 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 { getCodexHomeStatus, getCodexHooksStatus, handleCodexHook, handleAgyEvent, handleDroidEvent, handleGrokEvent, handleOpenCodeEvent, handleZcodeHook, handleZcodeEvent, isolatedDdFlowHomeFromHookStdin, claimBootstrapHookEvent, findRecentMatchingHookEvent, stageStartMatchKey, stageLifecycleMatchKey, 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";
@@ -30,12 +38,12 @@ import { getCanonStatus, registerCanonRoot, resolveCanonRoot, prepareCanonRegist
 import { getRuntimeStatus } from "../services/status.js";
 import { getCliVersionReport } from "../services/build-info.js";
 import { parseCommandArgs } from "../services/lifecycle-command.js";
-import { prepareError, prepareJsonFile, prepareJsonSchema, prepareJsonText, prepareTextFile } from "./input-preparation.js";
+import { prepareError, prepareJsonFile, prepareJsonSchema, prepareJsonText, prepareTextFile, prepareFileBytes, readBoundedUtf8Stream } 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, prepareFlowSessionPayload, registerFlowSession, stopFlowSession, stopMergeWorker, syncFlowSessionUsage } from "../services/sessions.js";
 import { getProtocolBranchContext } from "../services/branch-context.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 { attachFlowRunStage, readFlowRunExecutionBundle, prepareFlowRunStageAttachment, prepareRawFlowRunStageCompletion, completeFlowRun, prepareFlowRunCompletion, completeFlowRunStage, getFlowRunSessions, getFlowRunTimeline, getStoredFlowRunUsage, getFlowRunFlagsStatus, getFlowRunStatus, getFlowRunConfig, getFlowRunVariables, listFlowRuns, reviseFlowRunFlags, setFlowRunConfig, prepareFlowRunConfig, prepareFlowRunVariable, setFlowRunVariable, startFlowRun, resolveRun, 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";
@@ -46,21 +54,34 @@ import { requireProjectByRoot } from "../services/projects.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, 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 { getVnextWorkStatus, isVnextSpecifyFlow, isVnextSpecifyRun, prepareVnextSpecifyStart } from "../services/vnext-specify.js";
+import { isVnextProtocolizeRun, prepareProtocolizeResultPath, prepareVnextProtocolizeStart } from "../services/vnext-protocolize.js";
+import { isVnextPlanRun, prepareVnextPlanStart, prepareVnextPlanFinish } from "../services/vnext-plan.js";
+import { dispatchVnextPlanReview, isVnextPlanReviewRun, prepareVnextPlanReviewStart, recordVnextPlanReviewCapacity } from "../services/vnext-plan-review.js";
+import { addVnextCodeRepair, prepareVnextCodeRepair, prepareVnextCodeStart } from "../services/vnext-code.js";
+import { isVnextCodeReviewRun, prepareCodeReviewDecision, prepareVnextCodeReviewRepair, prepareVnextCodeReviewStart } from "../services/vnext-code-review.js";
+import { applyVnextMerge, getVnextMergeRequest, isVnextMergeRun, prepareVnextMergeFinish, prepareVnextMergeStart, repairVnextMerge, routeVnextMergeRequest } from "../services/vnext-merge.js";
+import { sdlcStageHandlers } from "../services/stage-handlers.js";
+import { startMemoryStage, finishMemoryStage } from "../services/memory-stage-dispatch.js";
+import { bindStageCoordinatorWork } from "../services/work-registry.js";
+import { registerMemoryCompositionFromStage } from "../services/memory-compose-handler.js";
+import { runMemoryVerificationChecks } from "../services/memory-verify-handler.js";
+import { registerMemoryReviewFromStage, collectMemoryInitialReviewFromStage } from "../services/memory-review-handler.js";
+import { PreparedRetainedMemoryReviewAuthority } from "../services/memory-retained-review-authority.js";
+import { PreparedRetainedMemoryReviewResults } from "../services/memory-retained-review-results.js";
+import { registerMemoryCorrectionsFromStage, registerMemorySecondCorrectionsFromStage, runMemoryCorrectionChecksFromStage, runMemorySecondCorrectionChecksFromStage, registerCorrectedMemoryReviewFromStage, registerSecondCorrectedMemoryReviewFromStage, collectCorrectedMemoryReviewFromStage, collectSecondCorrectedMemoryReviewFromStage } from "../services/memory-review-handler.js";
+import { integrateMemoryFinishFromStage, registerMemoryFinishEvidenceFromStage } from "../services/memory-finish-handler.js";
+import { registerMemoryRepairBaselineFromStage, registerMemorySecondRepairBaselineFromStage, reserveMemoryRepairWriterCopyFromStage, reserveMemorySecondRepairCopyFromStage, materializeMemoryRepairWriterCopyFromStage, materializeMemorySecondRepairCopyFromStage, prepareMemoryRepairDispatchFromStage, prepareMemorySecondRepairDispatchFromStage, registerMemoryRepairCurrentViewFromStage, registerMemorySecondRepairCurrentViewFromStage, registerMemoryRepairPublicationSourceFromStage, reserveMemoryRepairPublicationAgainstSourceFromStage, reserveMemorySecondRepairPublicationFromStage, applyMemoryRepairPublicationFromStage, applyMemorySecondRepairPublicationFromStage, finishMemoryRepairPublicationFromStage, finishMemorySecondRepairPublicationFromStage } from "../services/memory-review-handler.js";
 import { mergeServerStatus, serveMergeRequests, stopMergeServer } from "../services/merge-server.js";
-import { getVnextFanoutStatus, observeVnextNativeChildren, prepareNativeObservations, reconcileVnextFanout } from "../services/vnext-fanout.js";
-import { pauseStageForUser, resumeStageAfterUser, prepareStagePause, prepareStageResume } from "../services/stage-pause.js";
+import { getVnextFanoutStatus, memoryStageFanoutDescriptor, observeVnextNativeChildren, prepareNativeObservations, reconcileVnextFanout } from "../services/vnext-fanout.js";
+import { pauseStageForUser, resumeStageAfterUser, prepareStagePause, prepareStageResume, stagePauseCommand } from "../services/stage-pause.js";
+import { runtimeCommand } from "../services/runtime-command.js";
+import { managedLifecycleCommand } from "../services/lifecycle-invocations.js";
 import { blockStageForRuntime, unblockStageAfterRuntimeRepair, prepareStageRuntimeBlock, prepareStageRuntimeUnblock } from "../services/stage-blocker.js";
 import { classifyCliOperation, requiresExplicitUpgradeAuthorization } from "../services/cli-operation-classifier.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 { addWorkBatch, prepareWorkBatch, prepareWorkDeps, prepareWorkDelete, prepareWorkSettlement, prepareWorkRetry, assertStageLifecycleOwner, assertWorkLifecycleOwner, cancelWork, deleteWork, failWork, finishWork, listWorks, mutateWorkDeps, prepareWorkResult, workResultByteLimit, 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";
@@ -89,6 +110,21 @@ export async function runCli(args, io = defaultIo, env = process.env) {
     return withMaintenanceDiagnosticScope(() => runCliRequest(args, io, env));
 }
 async function runCliRequest(args, io, env) {
+    try {
+        const help = resolveHelp(args);
+        if (help) {
+            if (help.json)
+                writeJson(io.stdout, help.data);
+            else
+                io.stdout.write(`${help.text}\n`);
+            return 0;
+        }
+    }
+    catch (error) {
+        const record = errorRecord(error);
+        writePreparationError(io, args, record);
+        return record.exitCode;
+    }
     let output;
     try {
         output = parseOutputOptions(args);
@@ -114,7 +150,7 @@ async function runCliRequest(args, io, env) {
         catch (persistence) {
             rejection.details.lifecycle_diagnostic_error = String(persistence);
         }
-        writeJson(io.stderr, { ok: false, error: errorRecord(rejection) });
+        writePreparationError(io, args, errorRecord(rejection));
         return rejection.exitCode;
     }
     const progress = progressForCommand(output.args);
@@ -132,11 +168,16 @@ async function runCliRequest(args, io, env) {
                 io.stdout.write(`dd-flow ${payload.cli.version}\n`);
             return 0;
         }
-        const help = helpForArgs(output.args);
-        if (help) {
-            io.stdout.write(`${help}\n`);
-            return 0;
-        }
+        if (output.args[0] === "completion")
+            return runCompletionCli(args, io);
+        if (output.args[0] === "setup")
+            return runSetupCli(args, env, io);
+        if (output.args[0] === "harnesses")
+            return runHarnessesCli(args, env, io);
+        if (output.args[0] === "models")
+            return runModelsCli(args, io);
+        if (output.args[0] === "profiles")
+            return runOperatorProfilesCli(args, env, io);
         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));
@@ -436,6 +477,8 @@ async function runCliRequest(args, io, env) {
         if (invocationSettlement && error.details.effect !== "committed") {
             try {
                 if (isAppError(error)) {
+                    delete error.details.retry_command;
+                    delete error.details.retry_instruction;
                     const settled = errorRecord(error);
                     settleLifecycleRejection(invocationSettlement.context, invocationSettlement.id, settled);
                     // Serialization owns a copy. Publish the committed settlement, not
@@ -446,6 +489,8 @@ async function runCliRequest(args, io, env) {
                     settleLifecycleInvocation(invocationSettlement.context, invocationSettlement.id, { error: { code: "unexpected", message: String(error), exitCode: 1, details: {} } });
             }
             catch (persistenceError) {
+                if (isAppError(error))
+                    error.details.recoverable = false;
                 io.stderr.write(`Invocation settlement persistence failed: ${String(persistenceError)}\n`);
             }
         }
@@ -478,7 +523,7 @@ async function runCliRequest(args, io, env) {
         else if (output.json)
             writeJson(io.stderr, visible);
         else
-            io.stderr.write(renderHumanError(payload));
+            io.stderr.write(renderHumanError(payload, args));
         return isAppError(error) ? error.exitCode : 1;
     }
     finally {
@@ -540,115 +585,6 @@ function databaseModeForCommand(args, classification) {
         return "read_existing";
     return "initialize";
 }
-function renderHumanError(payload) {
-    const lines = [`dd-flow: ${payload.error.message}`];
-    const details = recordObject(payload.error.details);
-    const compatibility = recordObject(details?.compatibility);
-    const remediation = recordObject(details?.remediation);
-    if (compatibility) {
-        lines.push(`Compatibility: ${String(compatibility.verdict ?? "unknown")} (${String(compatibility.engine_resolution ?? "unknown")})`);
-        if (compatibility.blocked_operation)
-            lines.push(`Blocked operation: ${String(compatibility.blocked_operation)}`);
-        if (compatibility.install_hint)
-            lines.push(`Install compatible engine: ${String(compatibility.install_hint)}`);
-    }
-    if (remediation?.mb_upgrade_mode)
-        lines.push(`Upgrade mode: ${String(remediation.mb_upgrade_mode)}`);
-    if (details?.preferred_command)
-        lines.push(`Preferred command: ${String(details.preferred_command)}`);
-    const related = Array.isArray(details?.related_commands) ? details.related_commands.map(String) : [];
-    if (related.length > 0) {
-        lines.push("", "Related commands:");
-        for (const command of related)
-            lines.push(`  ${command}`);
-    }
-    return `${lines.join("\n")}\n`;
-}
-function parseOutputOptions(args) {
-    const stripped = [];
-    let json = false;
-    let progressJsonl = false;
-    let responseFile = null;
-    for (let index = 0; index < args.length; index += 1) {
-        const arg = args[index];
-        if (arg === undefined)
-            continue;
-        if (arg === "--json") {
-            json = true;
-            continue;
-        }
-        if (arg === "--progress-jsonl") {
-            progressJsonl = true;
-            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?.trim() || file.startsWith("--"))
-                throw new AppError("usage", "--response-file requires a path", 2);
-            responseFile = file;
-            continue;
-        }
-        stripped.push(arg);
-    }
-    if (responseFile && !json)
-        throw new AppError("usage", "--response-file requires --json", 2);
-    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
- * the lifecycle command. */
-function writeResponseFile(payload, output) {
-    if (!output.responseFile)
-        return payload;
-    const file = path.resolve(output.responseFile);
-    try {
-        fs.mkdirSync(path.dirname(file), { recursive: true });
-        const temporary = `${file}.tmp-${process.pid}-${crypto.randomUUID()}`;
-        fs.writeFileSync(temporary, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
-        fs.renameSync(temporary, file);
-    }
-    catch (error) {
-        // The lifecycle mutation may already be accepted. Do not retry it just
-        // because its optional full-response file could not be written.
-        return { ...(payload && typeof payload === "object" && !Array.isArray(payload) ? payload : { ok: true, result: payload }), response_file: file, response_file_error: String(error) };
-    }
-    if (!payload || typeof payload !== "object" || Array.isArray(payload))
-        return { ok: true, response_file: file };
-    const visible = { ...payload, response_file: file };
-    delete visible.worker_prompt_markdown;
-    return visible;
-}
 function progressForCommand(args) {
     const [family, command, subcommand] = args;
     if (family === "merge-queue" && command === "wait-next") {
@@ -936,7 +872,7 @@ async function prepareCliInputValue(args, context, io, scopeProjectRoot, respons
     if (route.key === "run attach-stage")
         prepareFlowRunStageAttachment(context, stageAttachmentInput(parsed));
     if (route.key === "run complete-stage")
-        prepareFlowRunStageCompletion(context, stageCompletionInput(parsed));
+        prepareRawFlowRunStageCompletion(context, stageCompletionInput(parsed));
     if (route.key === "run override")
         prepareFlowRunCompletion(context, runOverrideInput(parsed));
     if (route.key === "engine bind-run")
@@ -1053,7 +989,7 @@ async function prepareCliInputValue(args, context, io, scopeProjectRoot, respons
     }
     if (route.key === "run snapshot bootstrap create") {
         try {
-            prepareEvalBootstrapSnapshot(context, { projectRoot: requiredOption(parsed, "project-root"), output: requiredOption(parsed, "output") });
+            prepareEvalBootstrapSnapshot(context, { projectRoot: requiredOption(parsed, "project-root"), output: requiredOption(parsed, "output"), flow: optionalOption(parsed, "flow") });
         }
         catch (error) {
             return prepareError(error, { parameter: "project-root/output" });
@@ -1175,7 +1111,9 @@ async function prepareCliInputValue(args, context, io, scopeProjectRoot, respons
     if (route.key === "work add-batch") {
         const file = requiredOption(parsed, "file");
         try {
-            prepared.workBatch = prepareWorkBatch(context, { parentWorkId: requiredOption(parsed, "parent"), file });
+            prepared.workBatch = prepareWorkBatch(context, { parentWorkId: requiredOption(parsed, "parent"), file,
+                ...(optionalOption(parsed, "stage") ? { stage: optionalOption(parsed, "stage") } : {}),
+                ...(optionalOption(parsed, "request-key") ? { requestKey: optionalOption(parsed, "request-key") } : {}) });
         }
         catch (error) {
             return prepareError(error, { parameter: "file/parent", file });
@@ -1264,6 +1202,21 @@ async function prepareCliInputValue(args, context, io, scopeProjectRoot, respons
             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 (!hasOption(parsed, "bootstrap")) {
+            const bundle = readFlowRunExecutionBundle(context, { projectRoot: requiredOption(parsed, "project-root"), runId: requiredPosition(parsed, 0, "run-id") });
+            if (bundle)
+                prepared.stageBindingBundle = { stage, bundle, ...(contextSha256 ? { contextSha256 } : {}) };
+            if (bundle?.descriptor.descriptor.id === "mb-init") {
+                bundle.descriptor.stage(stage);
+                if (hasOption(parsed, "dir"))
+                    throw new AppError("usage", "Memory stage layout belongs to its frozen descriptor", 2);
+                const loaded = contextFile && contextSha256 ? loadExternalStageContext({ file: contextFile, expectedSha256: contextSha256, stage }) : undefined;
+                if (loaded)
+                    prepared.stageStart = { externalContext: loaded };
+                prepared.memoryStage = { operation: "start", bytes: loaded ? Buffer.from(loaded.bytes) : Buffer.alloc(0) };
+                return prepared;
+            }
+        }
         if (contextFile && contextSha256) {
             try {
                 prepared.stageStart = { externalContext: loadExternalStageContext({ file: contextFile, expectedSha256: contextSha256, stage }) };
@@ -1354,7 +1307,8 @@ async function prepareCliInputValue(args, context, io, scopeProjectRoot, respons
         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) };
+        const maxBytes = workResultByteLimit(context, requiredPosition(parsed, 0, "work-id"));
+        prepared.workFinish = { result: resultFile ? prepareTextFile(resultFile, "Work result", maxBytes).text : await readStdin(io.stdin, maxBytes) };
         prepareWorkResult(context, requiredPosition(parsed, 0, "work-id"), prepared.workFinish.result);
     }
     if (family === "stage" && command === "fanout" && requiredPosition(parsed, 0, "fanout action") === "reconcile") {
@@ -1363,6 +1317,13 @@ async function prepareCliInputValue(args, context, io, scopeProjectRoot, respons
     if (family === "stage" && command === "native" && requiredPosition(parsed, 0, "native action") === "observe") {
         prepared.observations = prepareNativeObservations(prepareJsonFile(requiredOption(parsed, "observations-file"), "native observations").value);
     }
+    if (family === "memory" && (["compose", "corrections"].includes(command ?? "") && parsed.positional[0] === "register"
+        || command === "repair" && parsed.positional[0] === "publication-reserve")) {
+        const bytes = prepareFileBytes(requiredOption(parsed, "result-file"), `Memory ${command} result`, 1024 * 1024).bytes;
+        if (!bytes.length || bytes.length > 1024 * 1024)
+            throw new AppError("usage", "Memory operation result exceeds its byte bound", 2);
+        prepared.memoryOperationBytes = bytes;
+    }
     if (family !== "stage" || command !== "finish")
         return prepared;
     const projectRoot = requiredOption(parsed, "project-root");
@@ -1378,6 +1339,21 @@ async function prepareCliInputValue(args, context, io, scopeProjectRoot, respons
     const semanticFile = optionalOption(parsed, "semantic-file") ?? optionalOption(parsed, "data");
     const resultFile = optionalOption(parsed, "result-file") ?? semanticFile;
     const runtime = run(projectRoot, runId);
+    if (JSON.parse(runtime.indexJson).execution_bundle?.flow_id === "mb-init") {
+        const bundle = readFlowRunExecutionBundle(context, { projectRoot, runId });
+        if (!bundle || bundle.descriptor.descriptor.id !== "mb-init")
+            throw new AppError("cli_input_unprepared", "Memory RUN bundle is unavailable", 1);
+        bundle.descriptor.stage(stage);
+        if (["dir", "outcome", "decision-file", "verification-file", "retry-check", "reason", "reason-file", "request", "work"].some(option => hasOption(parsed, option)))
+            throw new AppError("usage", "Memory stage finish requires its registered JSON result, not legacy result options", 2);
+        if (Boolean(resultFile) === resultStdin)
+            throw new AppError("usage", "Memory stage finish requires exactly one result input", 2);
+        const bytes = resultStdin ? Buffer.from(await readStdin(io.stdin, 1024 * 1024)) : prepareFileBytes(resultFile, "Memory stage result", 1024 * 1024).bytes;
+        if (!bytes.length || bytes.length > 1024 * 1024)
+            throw new AppError("usage", "Memory stage result exceeds its byte bound", 2);
+        prepared.memoryStage = { operation: "finish", bytes };
+        return prepared;
+    }
     const terminalReplay = (name) => {
         let index;
         try {
@@ -1649,9 +1625,10 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
     }
     if (family === "stage" && command === "fanout") {
         const action = requiredPosition(parsed, 0, "fanout action");
-        const runId = requiredPosition(parsed, 1, "run-id");
         const stage = requiredOption(parsed, "stage");
         const projectRoot = requiredScopeProjectRoot(scopeProjectRoot, "stage fanout");
+        const project = requireProjectByRoot(context, resolveProjectRoot(projectRoot));
+        const runId = resolveRun(context, project.id, requiredPosition(parsed, 1, "run-id")).id;
         if (action === "status")
             return getVnextFanoutStatus(context, { projectRoot, runId, stage });
         if (action === "reconcile")
@@ -1687,7 +1664,9 @@ 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"), prepared: prepared.workBatch });
+        return addWorkBatch(context, { parentWorkId: requiredOption(parsed, "parent"), file: requiredOption(parsed, "file"), prepared: prepared.workBatch,
+            ...(optionalOption(parsed, "stage") ? { stage: optionalOption(parsed, "stage") } : {}),
+            ...(optionalOption(parsed, "request-key") ? { requestKey: optionalOption(parsed, "request-key") } : {}) });
     }
     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")) } : {}) });
@@ -1724,7 +1703,8 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
         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));
+        const maxBytes = workResultByteLimit(context, workId);
+        const result = prepared.workFinish?.result ?? (resultFile ? prepareTextFile(resultFile, "Work result", maxBytes).text : await readStdin(io.stdin, maxBytes));
         return await finishWork(context, workId, result, commandProgress(io, output), retryReceiptId ? { receiptId: retryReceiptId, reason: retryReason } : undefined);
     }
     if (family === "work" && command === "fail") {
@@ -1738,6 +1718,8 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
     if (family === "work" && command === "retry")
         return retryWork(context, requiredPosition(parsed, 0, "work-id"), requiredOption(parsed, "reason"));
     if (family === "stage" && command === "start") {
+        if (prepared.stageBindingBundle)
+            context = { ...context, stageBindingBundle: prepared.stageBindingBundle };
         const dir = optionalOption(parsed, "dir");
         const bootstrap = hasOption(parsed, "bootstrap");
         const subject = optionalOption(parsed, "subject");
@@ -1755,6 +1737,34 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
         const projectRoot = requiredOption(parsed, "project-root");
         const stage = requiredOption(parsed, "stage");
         const externalContext = prepared.stageStart?.externalContext;
+        if (prepared.memoryStage?.operation === "start") {
+            const runId = requiredPosition(parsed, 0, "run-id");
+            const event = hookEventId ?? findRecentMatchingHookEvent(context, {
+                projectId: requireProjectByRoot(context, resolveProjectRoot(projectRoot)).id,
+                matchKey: entityReferenceVariants(runId).map(reference => stageStartMatchKey(reference, stage, projectRoot, contextSha256)),
+                errorCode: "trusted_session_binding_required", operation: "Memory stage start"
+            }).eventKey;
+            const work = startMemoryStage(context, { projectRoot, runId, stage, bytes: prepared.memoryStage.bytes });
+            try {
+                const binding = bindStageCoordinatorWork(context, { workId: work.work_id, hookEventId: event, stage,
+                    promptPath: work.prompt_path, resultPath: work.result_path, ...(contextSha256 ? { contextSha256 } : {}) });
+                // The frozen semantic prompt is also restored by auxiliary owners in
+                // other CLI contexts. Keep native invocation authority in this current
+                // delivery, not in those immutable instruction/custody bytes.
+                const finish = managedLifecycleCommand(context, runtimeCommand(context, ["stage", "finish", runId,
+                    "--stage", stage, "--project-root", projectRoot, "--result-file", work.result_path, "--json"]));
+                const pause = stagePauseCommand(context, { projectRoot, runId, stage, workId: work.work_id });
+                const orchestration = memoryStageFanoutDescriptor(context, { projectRoot, runId, stage });
+                const delivery = { ...work, binding, ...(orchestration ? { orchestration } : {}), next: { finish_command: finish, pause_command: pause },
+                    worker_prompt_markdown: `${work.worker_prompt_markdown}\n## Current lifecycle commands\n\nWrite the semantic result to the assigned result path, then execute exactly:\n${finish}\n\nFor a required user choice, write the question file named by this command, then execute exactly:\n${pause}\n` };
+                bindLifecyclePublishedPacket(context, delivery.worker_prompt_markdown);
+                return controlLifecycleReply(context, { projectRoot, runId }, delivery);
+            }
+            catch (error) {
+                throw new AppError("memory_stage_binding_pending", "Memory Stage allocated; trusted coordinator binding remains incomplete", 1, { effect: "committed", run_id: runId, stage, work_id: work.work_id, next_action: "reconcile_memory_stage_binding",
+                    cause: error instanceof AppError ? error.code : "coordinator_binding_failure" });
+            }
+        }
         const claimVnextStageStart = (runId) => {
             registerProject(context, { root: projectRoot });
             return findRecentMatchingHookEvent(context, {
@@ -1783,7 +1793,7 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
                     })
                     : claimVnextStageStart(requiredPosition(parsed, 0, "run-id"));
             }
-            const result = launchVnextSpecify(context, {
+            const result = sdlcStageHandlers.specify.entry(context, {
                 projectRoot,
                 ...(prepared.stageStart?.intakeMarkdown !== undefined ? { intakeMarkdown: prepared.stageStart.intakeMarkdown } : externalContext ? { intakeMarkdown: runnerIntake(externalContext) } : intakeFile ? { intakeFile } : { intakeMarkdown: await readStdin(io.stdin) }),
                 hookEventId,
@@ -1795,27 +1805,27 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
         }
         if (!bootstrap && stage === "protocolize" && isVnextProtocolizeRun(context, { projectRoot, runId: requiredPosition(parsed, 0, "run-id") })) {
             hookEventId ??= claimVnextStageStart(requiredPosition(parsed, 0, "run-id"));
-            return attachExternalStageContext(await startVnextProtocolize(context, { projectRoot, runId: requiredPosition(parsed, 0, "run-id"), hookEventId, ...(contextSha256 ? { contextSha256 } : {}), ...(externalContext ? { externalContext } : {}) }, prepared.protocolizeStart), externalContext);
+            return attachExternalStageContext(await sdlcStageHandlers.protocolize.entry(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 } : {}) }, prepared.planStart), externalContext);
+            return attachExternalStageContext(sdlcStageHandlers.plan.entry(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 } : {}) }, prepared.planReviewStart), externalContext);
+            return attachExternalStageContext(sdlcStageHandlers["plan-review"].entry(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 } : {}) }, prepared.codeStart), externalContext);
+            return attachExternalStageContext(await sdlcStageHandlers.code.entry(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 } : {}) }, prepared.codeReviewStart), externalContext);
+            return attachExternalStageContext(sdlcStageHandlers["code-review"].entry(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 } : {}) }, prepared.mergeStart), externalContext);
+            return attachExternalStageContext(await sdlcStageHandlers.merge.entry(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);
@@ -1849,6 +1859,17 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
         const hookEventId = optionalOption(parsed, "hook-event-id");
         if (retryCheckId && !retryReason?.trim())
             throw new AppError("usage", "--retry-check requires --reason explaining the recovered environment", 2);
+        if (prepared.memoryStage?.operation === "finish") {
+            // Descriptor settlement validates exact coordinator custody and claims
+            // the fresh hook atomically with result acceptance. Do not consume it
+            // through the SDLC lifecycle owner before that settlement.
+            return controlledReply(finishMemoryStage(context, { projectRoot, runId, stage, bytes: prepared.memoryStage.bytes,
+                hookEventId: hookEventId ?? findRecentMatchingHookEvent(context, {
+                    projectId: requireProjectByRoot(context, resolveProjectRoot(projectRoot)).id,
+                    matchKey: entityReferenceVariants(runId).map(reference => stageLifecycleMatchKey("stage_finish", reference, stage, projectRoot)),
+                    errorCode: "trusted_session_binding_required", operation: "Memory stage finish"
+                }).eventKey }));
+        }
         const protectedLifecycle = (stage === "specify" && isVnextSpecifyRun(context, { projectRoot, runId }))
             || (stage === "protocolize" && isVnextProtocolizeRun(context, { projectRoot, runId }))
             || (stage === "plan" && isVnextPlanRun(context, { projectRoot, runId }))
@@ -1868,7 +1889,7 @@ 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 controlledReply(await finishVnextSpecifyStage(context, {
+            return controlledReply(await sdlcStageHandlers.specify.finish(context, {
                 projectRoot,
                 runId,
                 ...(resultFile ? { resultFile } : prepared.stageFinish?.value ? {} : { resultJson: await readStdin(io.stdin) }),
@@ -1880,34 +1901,34 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
             if (!resultFile || resultStdin || hasOption(parsed, "outcome")) {
                 throw new AppError("usage", "vNext PROTOCOLIZE requires exactly --result-file", 2);
             }
-            return controlledReply(await finishVnextProtocolize(context, { projectRoot, runId, resultFile, ...(prepared.stageFinish?.value ? { result: prepared.stageFinish.value } : {}) }));
+            return controlledReply(await sdlcStageHandlers.protocolize.finish(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 controlledReply(await finishVnextPlan(context, { projectRoot, runId, ...(prepared.planFinish ? { prepared: prepared.planFinish } : {}) }));
+            return controlledReply(await sdlcStageHandlers.plan.finish(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 controlledReply(await finishVnextPlanReview(context, { projectRoot, runId, ...(decisionFile ? { decisionFile } : {}), ...(prepared.stageFinish?.value ? { decision: prepared.stageFinish.value, decisionText: prepared.stageFinish.text } : {}) }));
+            return controlledReply(await sdlcStageHandlers["plan-review"].finish(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 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) }));
+            return controlledReply(await sdlcStageHandlers.code.finish(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 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) }));
+            return controlledReply(await sdlcStageHandlers["code-review"].finish(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 controlledReply(await finishVnextMerge(context, { projectRoot, runId, requestId: requiredOption(parsed, "request"), workId: requiredOption(parsed, "work"), ...(retryCheckId ? { retryCheckId, retryReason: retryReason } : {}), progress: commandProgress(io, output) }, prepared.mergeFinish));
+            return controlledReply(await sdlcStageHandlers.merge.finish(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);
@@ -2055,7 +2076,7 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
         return prepared.schemaValidation;
     }
     if (family === "memory") {
-        return dispatchMemory(command, parsed);
+        return dispatchMemory(context, command, parsed, prepared);
     }
     if (family === "migration") {
         return dispatchMigration(context, command, parsed, classification, prepared);
@@ -2368,7 +2389,7 @@ function dispatchMergeWorker(context, command, parsed) {
     }
     throw new AppError("usage", `Unknown merge-worker command: ${command ?? "<empty>"}`, 2);
 }
-function dispatchMemory(command, parsed) {
+function dispatchMemory(context, command, parsed, prepared) {
     const subcommand = requiredPosition(parsed, 0, "memory subcommand");
     if (command === "permissions" && subcommand === "preflight") {
         return preflightMemoryPermissions({
@@ -2379,6 +2400,103 @@ function dispatchMemory(command, parsed) {
             mode: requiredOption(parsed, "mode")
         });
     }
+    const scope = () => {
+        const projectRoot = requiredOption(parsed, "project-root");
+        const project = requireProjectByRoot(context, resolveProjectRoot(projectRoot));
+        return { projectRoot, runId: resolveRun(context, project.id, requiredOption(parsed, "run")).id };
+    };
+    if (command === "repair") {
+        const wave = requiredOption(parsed, "wave");
+        if (wave !== "1" && wave !== "2")
+            throw new AppError("usage", "Memory repairs support only waves 1 and 2", 2);
+        const work = { ...scope(), workId: requiredOption(parsed, "work") };
+        if (subcommand === "baseline")
+            return (wave === "1" ? registerMemoryRepairBaselineFromStage : registerMemorySecondRepairBaselineFromStage)(context, work);
+        if (subcommand === "copy-reserve")
+            return (wave === "1" ? reserveMemoryRepairWriterCopyFromStage : reserveMemorySecondRepairCopyFromStage)(context, work);
+        if (subcommand === "copy-materialize")
+            return (wave === "1" ? materializeMemoryRepairWriterCopyFromStage : materializeMemorySecondRepairCopyFromStage)(context, work);
+        if (subcommand === "copy-dispatch")
+            return (wave === "1" ? prepareMemoryRepairDispatchFromStage : prepareMemorySecondRepairDispatchFromStage)(context, work);
+        const workspaceRoot = requiredOption(parsed, "workspace-root");
+        if (wave === "2") {
+            const bundle = readFlowRunExecutionBundle(context, work);
+            if (!bundle || bundle.descriptor.descriptor.id !== "mb-init" || bundle.execution.snapshot().scope.workspace !== workspaceRoot)
+                throw new AppError("memory_repair_scope_invalid", "Repair workspace does not match its frozen memory RUN", 2, { phase: "prepare", effect: "no_effect" });
+        }
+        if (subcommand === "current-view")
+            return wave === "1"
+                ? registerMemoryRepairCurrentViewFromStage(context, { ...work, workspaceRoot })
+                : registerMemorySecondRepairCurrentViewFromStage(context, work);
+        const output = { ...work, workspaceRoot, workSessionId: requiredOption(parsed, "work-session") };
+        if (subcommand === "publication-source" && wave === "1")
+            return registerMemoryRepairPublicationSourceFromStage(context, output);
+        if (subcommand === "publication-reserve") {
+            if (!prepared.memoryOperationBytes)
+                throw new AppError("cli_input_unprepared", "Memory repair output bytes were not prepared", 1);
+            return (wave === "1" ? reserveMemoryRepairPublicationAgainstSourceFromStage : reserveMemorySecondRepairPublicationFromStage)(context, { ...output, bytes: prepared.memoryOperationBytes });
+        }
+        if (subcommand === "publication-apply")
+            return (wave === "1" ? applyMemoryRepairPublicationFromStage : applyMemorySecondRepairPublicationFromStage)(context, output);
+        if (subcommand === "publication-finish")
+            return (wave === "1" ? finishMemoryRepairPublicationFromStage : finishMemorySecondRepairPublicationFromStage)(context, output);
+    }
+    if (command === "compose" && subcommand === "register") {
+        if (!prepared.memoryOperationBytes)
+            throw new AppError("cli_input_unprepared", "Memory composition bytes were not prepared", 1);
+        try {
+            return registerMemoryCompositionFromStage(context, { ...scope(), requestKey: requiredOption(parsed, "request-key"), bytes: prepared.memoryOperationBytes });
+        }
+        catch (error) {
+            if (error instanceof AppError && (error.code === "memory_stage_result_invalid"
+                || error.code === "memory_preflight_handler_invalid" && ["unselected_preflight_source", "proposed_source_sha256_mismatch"].includes(String(error.details.reason))) && error.details.phase === "prepare"
+                && error.details.effect === "no_effect" && error.details.recoverable === true) {
+                error.details.retry_command = runtimeCommand(context, ["memory", "compose", "register", "--run", requiredOption(parsed, "run"),
+                    "--project-root", requiredOption(parsed, "project-root"), "--request-key", requiredOption(parsed, "request-key"),
+                    "--result-file", requiredOption(parsed, "result-file"), "--json", "--progress-jsonl"]);
+                error.details.retry_instruction = "Correct only the rejected composition proposal, then execute retry_command in this same Session. No Work graph was registered by this rejected call; do not dispatch children or finish the Stage until registration succeeds.";
+            }
+            throw error;
+        }
+    }
+    if (command === "verify" && subcommand === "checks")
+        return runMemoryVerificationChecks(context, scope());
+    if (command === "review" && subcommand === "register")
+        return registerMemoryReviewFromStage(context, scope());
+    if (command === "review" && subcommand === "collect") {
+        const wave = collectMemoryInitialReviewFromStage(context, scope());
+        const selected = scope(), bundle = readFlowRunExecutionBundle(context, selected);
+        if (!bundle)
+            throw new AppError("memory_review_handler_invalid", "Registered Memory bundle required", 2);
+        const project = requireProjectByRoot(context, resolveProjectRoot(selected.projectRoot));
+        const retained = PreparedRetainedMemoryReviewResults.prepare(context, PreparedRetainedMemoryReviewAuthority.prepare(context, { projectId: project.id, runId: selected.runId }, bundle));
+        return { references: wave.references(), projection: wave.resultProjection(),
+            correction_plan_binding: { schema_id: "dd-flow/memory-review-correction-plan@1", run_id: selected.runId, wave: 1, review_sha256: retained.sha256 } };
+    }
+    if (command === "finish" && subcommand === "evidence")
+        return registerMemoryFinishEvidenceFromStage(context, scope());
+    if (command === "finish" && subcommand === "integrate")
+        return integrateMemoryFinishFromStage(context, scope());
+    if (command === "corrections" || command === "review" && ["selective-register", "selective-collect"].includes(subcommand)) {
+        const wave = requiredOption(parsed, "wave");
+        if (wave !== "1" && wave !== "2")
+            throw new AppError("usage", "Memory corrections support only waves 1 and 2", 2);
+        if (command === "corrections" && subcommand === "register") {
+            if (!prepared.memoryOperationBytes)
+                throw new AppError("cli_input_unprepared", "Memory correction plan bytes were not prepared", 1);
+            const register = wave === "1" ? registerMemoryCorrectionsFromStage : registerMemorySecondCorrectionsFromStage;
+            return register(context, { ...scope(), bytes: prepared.memoryOperationBytes });
+        }
+        if (command === "corrections" && subcommand === "checks")
+            return (wave === "1" ? runMemoryCorrectionChecksFromStage : runMemorySecondCorrectionChecksFromStage)(context, scope());
+        if (command === "review" && subcommand === "selective-register")
+            return (wave === "1" ? registerCorrectedMemoryReviewFromStage : registerSecondCorrectedMemoryReviewFromStage)(context, scope());
+        if (command === "review" && subcommand === "selective-collect") {
+            const accepted = (wave === "1" ? collectCorrectedMemoryReviewFromStage : collectSecondCorrectedMemoryReviewFromStage)(context, scope());
+            return { wave: Number(wave), references: accepted.references(), projection: accepted.resultProjection(),
+                ...(wave === "1" ? { correction_plan_binding: { schema_id: "dd-flow/memory-review-correction-plan@1", run_id: scope().runId, wave: 2, review_sha256: accepted.sha256 } } : {}) };
+        }
+    }
     throw new AppError("usage", `Unknown memory command: ${["memory", command, subcommand].filter(Boolean).join(" ")}`, 2);
 }
 function completedCommandExitCode(payload) {
@@ -2504,7 +2622,8 @@ function dispatchRun(context, command, parsed, prepared = {}) {
             if (bootstrapAction === "create")
                 return createEvalBootstrapSnapshot(context, {
                     projectRoot: requiredOption(parsed, "project-root"),
-                    output: requiredOption(parsed, "output")
+                    output: requiredOption(parsed, "output"),
+                    flow: optionalOption(parsed, "flow")
                 });
             if (bootstrapAction === "restore")
                 return restoreEvalBootstrapSnapshot(context, snapshotRestoreInput(parsed), prepared.bootstrapRestore);
@@ -2600,7 +2719,8 @@ function dispatchRun(context, command, parsed, prepared = {}) {
         return attachFlowRunStage(context, stageAttachmentInput(parsed));
     }
     if (command === "complete-stage") {
-        return completeFlowRunStage(context, stageCompletionInput(parsed));
+        const input = stageCompletionInput(parsed);
+        return completeFlowRunStage(context, input, prepareRawFlowRunStageCompletion(context, input));
     }
     if (command === "complete") {
         throw new AppError("usage", "run complete is retired; only an operator may use run override", 2);
@@ -3184,7 +3304,7 @@ function parseArgs(args) {
 function requiredPosition(parsed, index, label) {
     const value = parsed.positional[index];
     if (!value) {
-        throw new AppError("usage", `Missing required argument: ${label}`, 2);
+        throw new AppError("usage", `Missing required argument: ${label}`, 2, { parameter: label, reason: "missing_required_argument" });
     }
     return value;
 }
@@ -3194,7 +3314,7 @@ function allOptions(parsed, key) {
 function requiredScopeProjectRoot(root, operation) {
     if (root)
         return root;
-    throw new AppError("usage", `${operation} requires --project-root or a unique protocol context`, 2);
+    throw new AppError("usage", `${operation} requires --project-root or a unique protocol context`, 2, { parameter: "project-root", reason: "missing_required_option" });
 }
 function requiredOptionOrScope(parsed, root, key) {
     return root ?? requiredOption(parsed, key);
@@ -3213,7 +3333,7 @@ function requiredOptionAlias(parsed, keys) {
         if (value)
             return value;
     }
-    throw new AppError("usage", `Missing required option: ${keys.map((key) => `--${key}`).join(" or ")}`, 2);
+    throw new AppError("usage", `Missing required option: ${keys.map((key) => `--${key}`).join(" or ")}`, 2, { parameter: [...keys].sort(), reason: "missing_required_option" });
 }
 function hasOption(parsed, key) {
     return parsed.options.has(key);
@@ -3243,11 +3363,13 @@ function parseWorktreePolicy(value) {
     }
     throw new AppError("validation", "--worktree must be keep or remove", 2);
 }
-async function readStdin(stream) {
+async function readStdin(stream, maxBytes) {
     if (!stream) {
         return "";
     }
     let data = "";
+    if (maxBytes !== undefined)
+        return readBoundedUtf8Stream(stream, maxBytes);
     stream.setEncoding("utf8");
     for await (const chunk of stream) {
         data += chunk;
@@ -3263,7 +3385,8 @@ function refreshDashboardsAfterMutation(context, args, result, resolvedScope) {
         const projectRoot = projectRootForMutation(context, args, result, resolvedScope);
         if (!projectRoot)
             return [];
-        autoRefreshDashboards(context, { projectRoot });
+        const runId = result && typeof result === "object" && "run_id" in result && typeof result.run_id === "string" ? result.run_id : undefined;
+        autoRefreshDashboards(context, { projectRoot, ...(runId ? { runId } : {}) });
         return [];
     }
     catch (error) {