@deksden-com/dd-flow-cli 0.9.0-beta.144 → 0.9.0-beta.149

package/dist/cli/run-cli.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import { prepareResponseDestination, writeResponseFile } from "./response-file.js";
+import { preparePromptDelivery, publishPromptDelivery } from "../services/prompt-delivery.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";
@@ -49,6 +50,7 @@ import { validateSchema } from "../services/schema-validation.js";
 import { preflightMemoryPermissions } from "../services/memory-permissions.js";
 import { ingestDroidUsage, ingestAgyUsage, ingestGrokUsage, ingestOpenCodeUsage, ingestZcodeUsage } from "../services/usage.js";
 import { applyMigration, assessMigrationImpact, assertUpgradeRunStorageReady, planMigration, prepareMigrationApply, verifyMigrationReport } from "../services/migrations.js";
+import { PreparedUpgradeStorageReadiness } from "../services/memory-upgrade-storage-readiness.js";
 import { publishProjectSummary } from "../services/project-summary.js";
 import { requireProjectByRoot } from "../services/projects.js";
 import { resolveProjectRoot, resolveDdFlowHome } from "../storage/paths.js";
@@ -62,9 +64,11 @@ import { addVnextCodeRepair, prepareVnextCodeRepair, prepareVnextCodeStart } fro
 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 { startMemoryStage, finishMemoryStage, startMemoryUpgradeStage, finishMemoryUpgradeStage } from "../services/memory-stage-dispatch.js";
+import { startDiagnosticStage, finishDiagnosticStage } from "../services/diagnostic-stage-handlers.js";
+import { isDiagnosticFlow } from "../domain/diagnostic-flows.js";
 import { bindStageCoordinatorWork } from "../services/work-registry.js";
-import { registerMemoryCompositionFromStage } from "../services/memory-compose-handler.js";
+import { registerMemoryCompositionFromStage, publishMemoryUpgradeFromStage } 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";
@@ -73,7 +77,7 @@ import { registerMemoryCorrectionsFromStage, registerMemorySecondCorrectionsFrom
 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, memoryStageFanoutDescriptor, observeVnextNativeChildren, prepareNativeObservations, reconcileVnextFanout } from "../services/vnext-fanout.js";
+import { getVnextFanoutStatus, memoryStageFanoutDescriptor, diagnosticStageFanoutDescriptor, 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";
@@ -81,7 +85,7 @@ import { blockStageForRuntime, unblockStageAfterRuntimeRepair, prepareStageRunti
 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, workResultByteLimit, retryWork, showWork, startWork } from "../services/work-registry.js";
+import { addWorkBatch, assertGenericWorkBatchAllowed, 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";
@@ -328,7 +332,7 @@ async function runCliRequest(args, io, env) {
         if (!invocationId) {
             const preparationContext = createContext({ ...env }, "read_existing", undefined, maintenanceOptions);
             try {
-                preparedInput = await prepareCliInput(invocationArgs, preparationContext, io, scopeProjectRoot, output.responseFile);
+                preparedInput = await prepareCliInput(invocationArgs, preparationContext, io, scopeProjectRoot, output.responseFile, undefined, commandProgress(io, output));
             }
             finally {
                 preparationContext.db.close?.();
@@ -357,8 +361,8 @@ async function runCliRequest(args, io, env) {
                         throw error;
                     }
                 },
-                prepare: async () => { preparedInput = await prepareCliInput(invocationArgs, dispatchContext, io, scopeProjectRoot, output.responseFile, preparedRoute); },
-                assertCurrent: scope => assertLifecycleInvocationCurrent(dispatchContext, scope, command) });
+                prepare: async () => { preparedInput = await prepareCliInput(invocationArgs, dispatchContext, io, scopeProjectRoot, output.responseFile, preparedRoute, commandProgress(io, output)); },
+                assertCurrent: scope => assertLifecycleInvocationCurrent(dispatchContext, scope, command), progress: commandProgress(io, output) });
             if (admission.replay) {
                 retainedOutcome = admission.outcome;
                 settleHook = undefined;
@@ -386,7 +390,7 @@ async function runCliRequest(args, io, env) {
             throw new AppError(error.code, error.message, error.exitCode, error.details);
         }
         if (!retainedOutcome && !preparedInput)
-            preparedInput = await prepareCliInput(invocationArgs, dispatchContext, io, scopeProjectRoot, output.responseFile);
+            preparedInput = await prepareCliInput(invocationArgs, dispatchContext, io, scopeProjectRoot, output.responseFile, undefined, commandProgress(io, output));
         if (!retainedOutcome)
             await preflightCliCompatibility(dispatchContext, invocationArgs, env, scopeProjectRoot);
         if (!retainedOutcome) {
@@ -394,11 +398,10 @@ async function runCliRequest(args, io, env) {
             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") {
+        const result = preparePromptDelivery(retainedOutcome ? retainedOutcome.result : await dispatch(dispatchArgs, dispatchContext, io, scopeProjectRoot, classification, output, preparedInput));
+        if (!retainedOutcome && result && typeof result === "object" && "worker_prompt_markdown" in result && typeof result.worker_prompt_markdown === "string") {
             try {
-                bindLifecyclePublishedPacket(dispatchContext, fs.readFileSync(result.prompt_path, "utf8"));
+                bindLifecyclePublishedPacket(dispatchContext, result.worker_prompt_markdown);
             }
             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) });
@@ -422,6 +425,7 @@ async function runCliRequest(args, io, env) {
             writeProgressJsonl(io, "done", "Command finished");
         emitHumanProgress(io, output, progress, "done");
         const payload = attachProgress(resultWithWarnings, progress, output);
+        publishPromptDelivery(payload);
         const visible = writeResponseFile(payload, output);
         const maintenanceReceipt = payload;
         const maintenanceExpiry = maintenanceReceipt?.lease_expires_at ?? maintenanceReceipt?.process?.lease_expires_at;
@@ -436,7 +440,7 @@ async function runCliRequest(args, io, env) {
         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) {
+        if (!settleHook && !invocationSettlement && error.code !== "prompt_delivery_pending") {
             let earlyContext;
             try {
                 const command = quote(["dd-flow", ...args]);
@@ -481,11 +485,9 @@ async function runCliRequest(args, io, env) {
                 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
-                    // the original rejection which has no successor authority.
-                    Object.assign(error.details, settled.details);
+                    // The common settlement classifies original validated proof before
+                    // errorRecord clones diagnostic objects and loses capability identity.
+                    settleLifecycleRejection(invocationSettlement.context, invocationSettlement.id, error);
                 }
                 else
                     settleLifecycleInvocation(invocationSettlement.context, invocationSettlement.id, { error: { code: "unexpected", message: String(error), exitCode: 1, details: {} } });
@@ -558,6 +560,8 @@ function databaseModeForCommand(args, classification) {
     if (isRuntimeMaintenance(args))
         return "read_existing";
     const [family, command] = args;
+    if (family === "migration" && command === "readiness")
+        return "prepared_existing";
     // 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"))
@@ -635,7 +639,12 @@ function writeProgressJsonl(io, phase, message, detail) {
     io.stderr.write(`${JSON.stringify({ schema_id: "dd-flow/progress@1", phase, message, at: new Date().toISOString(), ...(detail ? { detail } : {}) })}\n`);
 }
 function commandProgress(io, output) {
-    return (message) => output.progressJsonl ? writeProgressJsonl(io, "running", message) : io.stderr.write(`[running] ${message}\n`);
+    return (message) => {
+        if (output.progressJsonl)
+            writeProgressJsonl(io, "running", message);
+        else if (!output.json && !output.hookJsonOnly)
+            io.stderr.write(`[running] ${message}\n`);
+    };
 }
 function attachProgress(result, progress, output) {
     if (progress.length === 0 || output.hookJsonOnly)
@@ -842,6 +851,14 @@ function stringValue(value) {
 function shortSha(value) {
     return value ? value.slice(0, 12) : "unknown";
 }
+function compositionProposalRetry(context, parsed) {
+    return {
+        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"]),
+        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."
+    };
+}
 /** 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) {
@@ -852,7 +869,7 @@ async function prepareCliInput(...args) {
         return prepareError(error);
     }
 }
-async function prepareCliInputValue(args, context, io, scopeProjectRoot, responseFile = null, route = prepareCommandRoute(args)) {
+async function prepareCliInputValue(args, context, io, scopeProjectRoot, responseFile = null, route = prepareCommandRoute(args), progress) {
     const { family, command, parsed } = route;
     const prepared = { route };
     if (optionalOption(parsed, "reason-file")) {
@@ -941,6 +958,10 @@ async function prepareCliInputValue(args, context, io, scopeProjectRoot, respons
         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 readiness")
+        prepared.upgradeStorageScope = {
+            projectRoot: requiredOption(parsed, "project-root"), workspaceRoot: requiredOption(parsed, "workspace-root"), requestId: requiredOption(parsed, "request-id")
+        };
     if (route.key === "migration verify")
         prepared.migrationVerification = verifyMigrationReport(context, { file: requiredOption(parsed, "file") });
     if (responseFile)
@@ -1115,6 +1136,7 @@ async function prepareCliInputValue(args, context, io, scopeProjectRoot, respons
     if (route.key === "work add-batch") {
         const file = requiredOption(parsed, "file");
         try {
+            assertGenericWorkBatchAllowed(context, requiredOption(parsed, "parent"));
             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") } : {}) });
@@ -1210,14 +1232,15 @@ async function prepareCliInputValue(args, context, io, scopeProjectRoot, respons
             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") {
+            if (bundle && (["mb-init", "mb-upgrade"].includes(bundle.descriptor.descriptor.id) || isDiagnosticFlow(bundle.descriptor.descriptor.id))) {
                 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) };
+                prepared.memoryStage = { operation: "start", bytes: loaded ? Buffer.from(loaded.bytes) : Buffer.alloc(0),
+                    flowId: isDiagnosticFlow(bundle.descriptor.descriptor.id) ? bundle.descriptor.descriptor.id : bundle.descriptor.descriptor.id === "mb-upgrade" ? "mb-upgrade" : "mb-init" };
                 return prepared;
             }
         }
@@ -1313,7 +1336,7 @@ async function prepareCliInputValue(args, context, io, scopeProjectRoot, respons
             throw new AppError("usage", "work finish requires exactly one of --result-file or --result-stdin", 2);
         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);
+        prepareWorkResult(context, requiredPosition(parsed, 0, "work-id"), prepared.workFinish.result, progress);
     }
     if (family === "stage" && command === "fanout" && requiredPosition(parsed, 0, "fanout action") === "reconcile") {
         prepared.observations = prepareNativeObservations(prepareJsonFile(requiredOption(parsed, "observations-file"), "native observations").value);
@@ -1323,10 +1346,18 @@ async function prepareCliInputValue(args, context, io, scopeProjectRoot, respons
     }
     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;
+        try {
+            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, { phase: "prepare", effect: "no_effect", recoverable: true });
+            prepared.memoryOperationBytes = bytes;
+        }
+        catch (error) {
+            if (command === "compose" && isAppError(error) && error.details.phase === "prepare"
+                && error.details.effect === "no_effect" && error.details.recoverable === true)
+                Object.assign(error.details, compositionProposalRetry(context, parsed));
+            throw error;
+        }
     }
     if (family !== "stage" || command !== "finish")
         return prepared;
@@ -1343,10 +1374,11 @@ 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 retainedFlowId = JSON.parse(runtime.indexJson).execution_bundle?.flow_id;
+    if (["mb-init", "mb-upgrade"].includes(retainedFlowId) || isDiagnosticFlow(retainedFlowId)) {
         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);
+        if (!bundle || !["mb-init", "mb-upgrade"].includes(bundle.descriptor.descriptor.id) && !isDiagnosticFlow(bundle.descriptor.descriptor.id))
+            throw new AppError("cli_input_unprepared", "Registered 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);
@@ -1355,7 +1387,7 @@ async function prepareCliInputValue(args, context, io, scopeProjectRoot, respons
         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 };
+        prepared.memoryStage = { operation: "finish", bytes, flowId: isDiagnosticFlow(bundle.descriptor.descriptor.id) ? bundle.descriptor.descriptor.id : bundle.descriptor.descriptor.id === "mb-upgrade" ? "mb-upgrade" : "mb-init" };
         return prepared;
     }
     const terminalReplay = (name) => {
@@ -1668,6 +1700,7 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
         });
     }
     if (family === "work" && command === "add-batch") {
+        assertGenericWorkBatchAllowed(context, requiredOption(parsed, "parent"));
         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") } : {}) });
@@ -1694,7 +1727,7 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
         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 } : {}), ...(recoveryId ? { recoveryId } : {}), projectRoot });
+        return startWork(context, requiredPosition(parsed, 0, "work-id"), { ...(hookEventId ? { hookEventId } : {}), ...(recoveryId ? { recoveryId } : {}), projectRoot, progress: commandProgress(io, output) });
     }
     if (family === "work" && command === "finish") {
         const resultFile = optionalOption(parsed, "result-file");
@@ -1748,7 +1781,7 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
                 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 });
+            const work = (isDiagnosticFlow(prepared.memoryStage.flowId) ? startDiagnosticStage : prepared.memoryStage.flowId === "mb-upgrade" ? startMemoryUpgradeStage : 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 } : {}) });
@@ -1758,7 +1791,7 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
                 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 orchestration = memoryStageFanoutDescriptor(context, { projectRoot, runId, stage }) ?? diagnosticStageFanoutDescriptor(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);
@@ -1867,7 +1900,7 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
             // 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,
+            return controlledReply((isDiagnosticFlow(prepared.memoryStage.flowId) ? finishDiagnosticStage : prepared.memoryStage.flowId === "mb-upgrade" ? finishMemoryUpgradeStage : 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)),
@@ -2179,6 +2212,13 @@ function dispatchEngine(context, command, parsed, classification, prepared) {
 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 === "readiness") {
+        if (!prepared.upgradeStorageScope)
+            throw new AppError("validation", "Upgrade storage scope must be prepared before publication", 2);
+        // Unlike the initial readonly syntax pass, this connection is admitted
+        // prepared-existing. Physical writer checks still precede receipt writes.
+        return { ok: true, ...PreparedUpgradeStorageReadiness.prepare(context, prepared.upgradeStorageScope).apply(context) };
+    }
     if (command === "plan" || command === "report") {
         return planMigration(context, {
             projectRoot: requiredOption(parsed, "project-root"),
@@ -2425,7 +2465,7 @@ function dispatchMemory(context, command, parsed, prepared) {
         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)
+            if (!bundle || !["mb-init", "mb-upgrade"].includes(bundle.descriptor.descriptor.id) || 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")
@@ -2455,14 +2495,13 @@ function dispatchMemory(context, command, parsed, prepared) {
             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.";
+                Object.assign(error.details, compositionProposalRetry(context, parsed));
             }
             throw error;
         }
     }
+    if (command === "upgrade" && subcommand === "publish")
+        return publishMemoryUpgradeFromStage(context, scope());
     if (command === "verify" && subcommand === "checks")
         return runMemoryVerificationChecks(context, scope());
     if (command === "review" && subcommand === "register")

package/dist/cli/setup.js

@@ -129,7 +129,8 @@ export async function runSetupCli(args, env, io = { stdout: process.stdout, stde
                     throw error;
                 }
             }
-            result = { ...installed, action: route.key === "setup update" ? "setup_update" : "setup_install", observed_cli: observedCli,
+            result = { ...installed, request_installation: installed.installation,
+                action: route.key === "setup update" ? "setup_update" : "setup_install", observed_cli: observedCli,
                 executor: installed.executor ? { profile_id: installed.executor.id, revision: hybridDigest(installed.executor), readiness: "unknown_requires_qualification" } : { profile_id: null, readiness: "not_configured" },
                 ...readSetupStatus(home) };
         }

package/dist/cli.js

@@ -49,10 +49,28 @@ if (args[0] === "init" || args[0] === "flow" && args[1] === "mb-init") {
     publishSetup('imports_ready');
     process.exit(await runMemoryInitCli(args, process.env));
 }
+if (args[0] === "upgrade" || args[0] === "flow" && args[1] === "mb-upgrade") {
+    const { runMemoryUpgradeCli } = await import("./cli/memory-upgrade.js");
+    process.exit(await runMemoryUpgradeCli(args, process.env));
+}
+if (args[0] === "review" || args[0] === "flow" && ["mb-audit", "project-review"].includes(args[1] ?? "")) {
+    publishSetup('ingress_entered');
+    const { runDiagnosticCli } = await import("./cli/diagnostic.js");
+    publishSetup('imports_ready');
+    process.exit(await runDiagnosticCli(args, process.env));
+}
 if (args.slice(0, 3).join(" ") === "runtime storage admit") {
     const { runMemoryStorageAdmissionCli } = await import("./cli/memory-storage-admission.js");
     process.exit(runMemoryStorageAdmissionCli(args));
 }
+if (args.slice(0, 3).join(" ") === "runtime storage qualify") {
+    const { runMemoryStorageQualificationCli } = await import("./cli/memory-storage-qualification.js");
+    process.exit(runMemoryStorageQualificationCli(args));
+}
+if (args.slice(0, 3).join(" ") === "runtime storage transition") {
+    const { runMemoryStorageTransitionCli } = await import("./cli/memory-storage-transition.js");
+    process.exit(runMemoryStorageTransitionCli(args));
+}
 if (args.slice(0, 3).join(" ") === "runtime flow admit") {
     const { runMemoryFlowAdmissionCli } = await import("./cli/memory-flow-admission.js");
     process.exit(await runMemoryFlowAdmissionCli(args));

package/dist/domain/diagnostic-aspects.js

@@ -0,0 +1,103 @@
+/** Registered baseline coverage; applicability remains agent-owned. */
+export const diagnosticAspects = {
+    "mb-audit": [
+        {
+            "id": "01",
+            "question": "Structure, indexes and reachability of active memory"
+        },
+        {
+            "id": "02",
+            "question": "Links, frontmatter and durable traceability"
+        },
+        {
+            "id": "03",
+            "question": "Source of truth, duplicates, freshness and factual contradictions"
+        },
+        {
+            "id": "04",
+            "question": "Delivery docs, epics/features, protocols and verification matrices"
+        },
+        {
+            "id": "05",
+            "question": "System boundaries, C4, ADRs and contracts"
+        },
+        {
+            "id": "06",
+            "question": "Scenarios, fixtures, evidence and runners"
+        },
+        {
+            "id": "07",
+            "question": "UI contracts and user guides"
+        },
+        {
+            "id": "08",
+            "question": "Engineering standards and code contracts"
+        },
+        {
+            "id": "09",
+            "question": "Operations, release policy and active named deferrals"
+        },
+        {
+            "id": "10",
+            "question": "Memory lifecycle, archives and durable promotion"
+        },
+        {
+            "id": "11",
+            "question": "Code-to-memory traceability"
+        },
+        {
+            "id": "12",
+            "question": "Project agent skills, prompts and execution guidance"
+        }
+    ],
+    "project-review": [
+        {
+            "id": "structure_navigation_review",
+            "question": "Can readers locate system truth and delivery evidence?"
+        },
+        {
+            "id": "feature_epic_layer_review",
+            "question": "Are durable capabilities and delivery layers coherent?"
+        },
+        {
+            "id": "spec_conformance_review",
+            "question": "Does actual project behavior conform to its normative specs?"
+        },
+        {
+            "id": "architecture_harmonization_review",
+            "question": "Are architecture and boundaries coherent top-down?"
+        },
+        {
+            "id": "adr_decision_review",
+            "question": "Are significant decisions, alternatives and consequences recorded?"
+        },
+        {
+            "id": "scenario_evidence_review",
+            "question": "Do actual scenarios, fixtures, checks and evidence cover capabilities?"
+        },
+        {
+            "id": "contract_traceability_review",
+            "question": "Are public contracts traced through implementation and tests?"
+        },
+        {
+            "id": "frontmatter_crosslink_review",
+            "question": "Are metadata and cross-links factual and current?"
+        },
+        {
+            "id": "engineering_standards_review",
+            "question": "Does actual code follow applicable engineering standards?"
+        },
+        {
+            "id": "operations_policy_review",
+            "question": "Are applicable Git, environment and delivery policies followed?"
+        },
+        {
+            "id": "protocol_delivery_trace_review",
+            "question": "Do protocols and RUNs factually establish delivery and closure?"
+        },
+        {
+            "id": "def_followup_review",
+            "question": "Are active DEFs visible, deduplicated and bound to future gates?"
+        }
+    ]
+};

package/dist/domain/diagnostic-flows.js

@@ -0,0 +1,8 @@
+/** Only the accepted E5 read-only slice, not a registry of future workflows. */
+export const diagnosticFlowStages = Object.freeze({
+    "mb-audit": ["preflight", "audit", "review", "report"],
+    "project-review": ["preflight", "analyze", "review", "report"]
+});
+export function isDiagnosticFlow(id) {
+    return typeof id === "string" && Object.hasOwn(diagnosticFlowStages, id);
+}

package/dist/domain/stage-handler-identities.js

@@ -18,3 +18,11 @@ export const memoryInitHandlerIdentities = Object.freeze({
     review: Object.freeze({ stage: "review", entryId: "memory-stage-entry", finishId: "memory-stage-finish" }),
     finish: Object.freeze({ stage: "finish", entryId: "memory-stage-entry", finishId: "memory-stage-finish" })
 });
+export const memoryUpgradeHandlerIdentities = Object.freeze({
+    preflight: Object.freeze({ stage: "preflight", entryId: "memory-upgrade-stage-entry", finishId: "memory-upgrade-stage-finish" }),
+    "diff-analysis": Object.freeze({ stage: "diff-analysis", entryId: "memory-upgrade-stage-entry", finishId: "memory-upgrade-stage-finish" }),
+    upgrade: Object.freeze({ stage: "upgrade", entryId: "memory-upgrade-stage-entry", finishId: "memory-upgrade-stage-finish" }),
+    verify: Object.freeze({ stage: "verify", entryId: "memory-upgrade-stage-entry", finishId: "memory-upgrade-stage-finish" }),
+    review: Object.freeze({ stage: "review", entryId: "memory-upgrade-stage-entry", finishId: "memory-upgrade-stage-finish" }),
+    finish: Object.freeze({ stage: "finish", entryId: "memory-upgrade-stage-entry", finishId: "memory-upgrade-stage-finish" })
+});

package/dist/harness-runtime/bin/dd-agy.mjs

@@ -23,7 +23,7 @@ async function hook(options) {
     const normalized = { schema_id: "dd-flow/agy-tool-event@1", event_id: identity.event_id, phase, daemon_id: identity.daemon_id, launch_cwd: identity.launch_cwd, conversation_id: payload.conversationId, parent_conversation_id: identity.parent_conversation_id, execution_num: payload.executionNum, step_index: payload.stepIdx, tool: payload.toolCall?.name, input: args, workspace_paths: payload.workspacePaths, transcript_path: payload.transcriptPath, model: payload.modelName, profile: identity.profile, ...(phase === "after" ? { error: payload.error ?? "" } : {}) };
     await invokeNativeHook({ bin: options["dd-flow-bin"] ?? identity.dd_flow_bin,
       args: ["agy", "event", "handle", "--project-root", options["project-root"] ?? identity.project_root, "--json"],
-      payload: normalized, home: options["dd-flow-home"] ?? identity.dd_flow_home, timeoutMs: budget.remaining("admission", 15_000) });
+      payload: normalized, home: options["dd-flow-home"] ?? identity.dd_flow_home, timeoutMs: budget.remaining("admission") });
   }
   return event === "PreToolUse" ? { decision: "allow" } : {};
   } catch (error) {
@@ -31,8 +31,8 @@ async function hook(options) {
     // reads only receipts matching request IDs it actually accepted this turn.
     const correctable = event === "PreToolUse" && error.code === "lifecycle_shell_syntax_invalid" && error.details?.effect === "no_effect"
       && error.details?.recoverable === true && error.details?.disposition === "pre_cli_shell_refusal";
-    try { await writeJsonAtomic(path.join(options["state-dir"], "hook-failures", `${requestId}.json`), { request_id: requestId, observed_at: new Date().toISOString(), code: error.code ?? "agy_hook_rejected", message: error.message,
-      details: { ...error.details, effect: correctable ? "no_effect" : "unknown", ...(correctable ? { native_pre_cli_refusal: true } : {}) } }); }
+    try { await budget.run(() => writeJsonAtomic(path.join(options["state-dir"], "hook-failures", `${requestId}.json`), { request_id: requestId, observed_at: new Date().toISOString(), code: error.code ?? "agy_hook_rejected", message: error.message,
+      details: { ...error.details, effect: correctable ? "no_effect" : "unknown", ...(correctable ? { native_pre_cli_refusal: true } : {}) } }, () => budget.remaining("failure_receipt_commit")), "failure_receipt"); }
     catch (storage) { process.stderr.write(`${JSON.stringify({ code: error.code, receipt_error: storage.message })}\n`); }
     throw error;
   }

package/dist/harness-runtime/bin/dd-grok.mjs

@@ -12,12 +12,12 @@ async function hook(options) {
   const budget = hookBudget();
   const stdin = await readNativeHookInput(process.stdin, budget); const payload = JSON.parse(stdin || "{}"); const identity = await callDaemon(options["state-dir"], "hook.resolve", { sessionId: payload.sessionId ?? payload.session_id, payload }, budget.remaining("identity"));
   const enriched = { ...payload, _meta: { ...(payload._meta ?? {}), ddGrok: identity } }; const args = ["grok", "event", "handle", "--project-root", options["project-root"], "--json"]; const command = options["dd-flow-bin"];
-  try { return await invokeNativeHook({ bin: command, args, home: options["dd-flow-home"], payload: enriched, timeoutMs: budget.remaining("admission", 15_000) }); }
+  try { return await invokeNativeHook({ bin: command, args, home: options["dd-flow-home"], payload: enriched, timeoutMs: budget.remaining("admission") }); }
   catch (error) {
     if (identity.nativeHookBinding) error.details = { ...error.details, native_hook_binding: identity.nativeHookBinding };
     try {
-      await writeNativeHookFailure(options["state-dir"], identity.nativeHookBinding, error, hookBudget(1_000, null));
-      if (identity.nativeHookBinding) await callDaemon(options["state-dir"], "hook.failed", { requestId: identity.nativeHookBinding.request_id }, 1_000);
+      await writeNativeHookFailure(options["state-dir"], identity.nativeHookBinding, error, budget);
+      if (identity.nativeHookBinding) await callDaemon(options["state-dir"], "hook.failed", { requestId: identity.nativeHookBinding.request_id }, budget.remaining("failure_notification"));
     } catch (storage) { process.stderr.write(`${JSON.stringify({ code: error.code, receipt_error: storage.message })}\n`); }
     throw error;
   }

package/dist/harness-runtime/bin/dd-zcode.mjs

@@ -37,14 +37,14 @@ async function hook(options) {
   const identity = await callDaemon(options["state-dir"], "hook.resolve", { sessionId: payload.session_id ?? payload.sessionId, payload }, budget.remaining("identity"));
   const command = options["dd-flow-bin"]; const args = ["zcode", "hook", "handle", "--project-root", options["project-root"], "--json"];
 
-  try { return await invokeNativeHook({ bin: command, args, home: options["dd-flow-home"], timeoutMs: budget.remaining("admission", 15_000), payload: { ...payload, _meta: { ...(payload._meta ?? {}), ddZcode: identity } } }); }
+  try { return await invokeNativeHook({ bin: command, args, home: options["dd-flow-home"], timeoutMs: budget.remaining("admission"), payload: { ...payload, _meta: { ...(payload._meta ?? {}), ddZcode: identity } } }); }
   catch (error) {
     if (identity.nativeHookBinding) error.details = { ...error.details, native_hook_binding: identity.nativeHookBinding };
     try {
-      // The 25s work budget leaves this bounded 2s evidence tail inside the
-      // qualified 30s native hook limit, even after the work deadline expired.
-      await writeNativeHookFailure(options["state-dir"], identity.nativeHookBinding, error, hookBudget(1_000, null));
-      if (identity.nativeHookBinding) await callDaemon(options["state-dir"], "hook.failed", { requestId: identity.nativeHookBinding.request_id }, 1_000);
+      // Evidence shares the original deadline; an expired admission cannot
+      // start a new independent failure-report window.
+      await writeNativeHookFailure(options["state-dir"], identity.nativeHookBinding, error, budget);
+      if (identity.nativeHookBinding) await callDaemon(options["state-dir"], "hook.failed", { requestId: identity.nativeHookBinding.request_id }, budget.remaining("failure_notification"));
     } catch (storage) { process.stderr.write(`${JSON.stringify({ code: error.code, receipt_error: storage.message })}\n`); }
     throw error;
   }