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

package/dist/cli/help.js

@@ -2,6 +2,70 @@ import { AppError } from "../shared/errors.js";
 import { commandInputs, commandAliases } from "./command-inputs.js";
 import { commandKeyForPositions, globalOptionDocumentation, optionsForCommandTree, routerNativeRoute } from "./command-metadata.js";
 const helpPages = new Map([
+    ["flow mb-audit", `dd-flow flow mb-audit - read-only Memory Bank audit
+
+Usage:
+  dd-flow flow mb-audit --project-root /absolute/project --request-id ID --intake-file /absolute/request.txt [--profile ID] --json
+
+Describe quick/full or focused audit scope in the original intake. Stages are
+preflight → audit → review → report. Applicable aspects use assigned read-only
+Work and independent critics. Missing evidence and active DEFs remain visible.
+Reports and runtime state live in DD_FLOW_HOME; project files are not repaired.
+The snapshot includes selected dirty/untracked source, excluding private inputs.
+
+Profiles, engine, canon and objective are frozen before dispatch. Exact replay
+may omit intake/profile selectors; supplied selectors must match the original.
+--prepare-only creates the snapshot and RUN without Sessions; --detach returns
+the controller receipt. Neither is a dry run. Default execution is managed,
+with fresh stage Sessions and external Work (concurrency 1).
+Use existing run drive status and run control commands for observation/recovery.`],
+    ["flow project-review", `dd-flow review / flow project-review - read-only project-conformance review
+
+Usage:
+  dd-flow review --project-root /absolute/project --request-id ID --intake-file /absolute/request.txt [--profile ID] --json
+
+Both spellings share validation and effects. Describe the review focus and
+constraints in the original intake. Stages are preflight → analyze → review →
+report. Compare specs, features, ADRs, scenarios and policy with actual code and
+evidence. This is not SDLC CODE-REVIEW and never implicitly repairs the project.
+All baseline aspects retain applicability and coverage; independent criticism,
+rejected findings and uncertainty remain in runtime evidence.
+
+Execution uses an isolated read-only snapshot and frozen global canon. No local
+Memory Bank installation is required. Profiles and the original request remain
+pinned on replay. --prepare-only creates runtime state without Sessions;
+--detach returns the accepted controller receipt. Default execution is managed,
+with fresh stage Sessions and external Work. Use run drive status / run control
+to observe, answer, stop or reconcile the exact retained RUN.`],
+    ["runtime storage qualify", `dd-flow runtime storage qualify - pre-probe selected-engine capability
+
+--operation memory-upgrade checks existing storage with the executing engine.
+Compatible stores use ordinary operation admission. Otherwise, drained source
+stores are copied with committed WAL to a private temporary directory; actual
+migration and target operation admission run only on those copies.
+
+Requires explicit canonical DD_FLOW_HOME and DD_FLOW_RESOURCE_HOME. The result
+is capability only: it does not authorize writes, create a RUN, publish migration
+evidence for real stores or start a model. Original storage is never migrated.
+Public upgrade still requires a separately retained plan and explicit apply.`],
+    ["runtime storage transition", `dd-flow runtime storage transition - selected-engine pre-context storage transport
+
+Normal project entry remains dd-flow upgrade. This transport executes only in
+the immutable entrypoint selected by the original retained upgrade request.
+It requires explicit DD_FLOW_HOME and DD_FLOW_RESOURCE_HOME and never initializes
+storage, chooses another engine, starts a model or allocates a RUN.
+
+--action plan retains both store snapshots and returns exact apply/status commands.
+apply requires the retained --expected-sha256 and --offline; both backups are
+verified before the first schema change. Unknown effects require exact-request
+status/reconciliation, not a new selector or replacement plan.
+
+recovery-plan requires the migration SHA, --recovery-id and --offline. Selecting
+recovery fences both stores and aborts the old apply; recover and recovery-status
+use the returned recovery SHA. Restoration is never automatic.
+
+The offline switch acknowledges external drain; logical and physical registered
+owners are checked independently. No owner is terminated by this transport.`],
     ["flow mb-init", `dd-flow init / flow mb-init - managed project Memory Bank initialization
 
 Usage:
@@ -332,7 +396,7 @@ Examples:
     ],
     [
         "canon",
-        `dd-flow canon - register and resolve the canonical Memory Bank checkout
+        `dd-flow canon - register and resolve the canonical Memory Bank source
 
 Usage:
   dd-flow canon register --root <canonical-dd-memorybank-root> --json
@@ -341,6 +405,8 @@ Usage:
 
 Discovery order is explicit --root, then DD_MEMORYBANK, then the globally registered runtime value in DD_FLOW_HOME, then known nearby dd-memorybank checkouts from the current working directory. Explicit --root is the only source considered for that command. If multiple different valid canonical checkouts are found, resolve fails closed with blockers so the caller chooses intentionally.
 
+Without an explicit, environment or registered source, the release installed by setup in DD_FLOW_HOME takes precedence over nearby checkouts. Its commit comes from the retained release manifest, not ancestor Git history. A degraded installation is reported; it never silently falls back to a nearby checkout.
+
 A valid canonical root contains dd-flow/README.md, mbb/index.md, protocol/index.md, and canonical-only entrypoints such as dd-flow/mb-init.md, dd-flow/mb-upgrade.md, and dd-flow/mb-distill.md. Current canon runs mb-upgrade review as the 05-review stage inside mb-upgrade, not as a top-level mb-upgrade-review.md entrypoint.
 
 Examples:

package/dist/cli/hook-ingress.js

@@ -1,10 +1,11 @@
 import { fileURLToPath } from "node:url";
 import { performance } from "node:perf_hooks";
+import { channel } from "node:diagnostics_channel";
 import { parseCommandArgs, parseLifecycleCommand, lifecycleCommandFromPayload, continuationCommand } from "../services/lifecycle-command.js";
 import { errorRecord, AppError } from "../shared/errors.js";
 import { parseJsonObject } from "../shared/json.js";
 const workerFile = fileURLToPath(import.meta.url);
-const ingressBudgetMs = 20_000; // Native host timeout is 30s; this includes cold module/DB open.
+const ingressBudgetMs = 20_000; // Shared admission budget; host separately allows cold CLI startup/cleanup.
 const { hookBudget, readNativeHookInput } = await import("../harness-runtime/lib/native-hook-command.mjs");
 /** Lightweight entry: unrelated hooks never load the router or open storage. */
 export async function runHookIngress(args) {
@@ -46,15 +47,32 @@ export async function runHookIngress(args) {
 }
 // A bounded CLI subprocess, not a detached writer: its successful reply follows COMMIT.
 if (process.argv[1] === workerFile) {
+    const started = performance.now();
+    const timing = channel("dd-flow.sqlite.ingress");
+    let previousPhase;
+    const trace = (value) => {
+        const record = value;
+        if (record.phase === previousPhase)
+            return;
+        previousPhase = record.phase;
+        process.stderr.write(`${JSON.stringify({ kind: "native_hook_phase", phase: record.phase, elapsed_ms: Math.round(performance.now() - started), ...(record.remaining_ms !== undefined ? { remaining_ms: record.remaining_ms } : {}) })}\n`);
+    };
+    timing.subscribe(trace);
     try {
-        const stdin = await readNativeHookInput(process.stdin, hookBudget(ingressBudgetMs, process.env.DD_FLOW_HOOK_DEADLINE_AT ? Number(process.env.DD_FLOW_HOOK_DEADLINE_AT) : null));
+        const budget = hookBudget(ingressBudgetMs, process.env.DD_FLOW_HOOK_DEADLINE_AT ? Number(process.env.DD_FLOW_HOOK_DEADLINE_AT) : null);
+        const phase = (name) => trace({ phase: name, remaining_ms: budget.remaining(name) });
+        phase("input");
+        const stdin = await readNativeHookInput(process.stdin, budget);
         const payload = parseJsonObject(stdin, "native hook stdin");
-        const started = performance.now();
+        phase("verification");
         const { verifyCodexHookDelivery } = await import("../services/codex-hook-delivery.js");
         const proof = await verifyCodexHookDelivery(process.env, payload);
         const verified = performance.now();
+        phase("import");
         const [{ createContext }, { handleCodexHook }] = await Promise.all([import("../runtime/context.js"), import("../services/hooks.js")]);
+        phase("imported");
         const loaded = performance.now();
+        phase("store_open");
         const context = createContext(process.env, "hook");
         const opened = performance.now();
         try {
@@ -62,7 +80,10 @@ if (process.argv[1] === workerFile) {
                 context.codexHookProof = proof;
             const parsed = parseCommandArgs(process.argv.slice(5));
             const projectRoot = parsed.options.get("project-root")?.[0];
+            phase("receipt");
             const result = handleCodexHook(context, { event: "PreToolUse", ...(projectRoot ? { projectRoot } : {}), stdin });
+            phase("committed");
+            phase("ack");
             process.stdout.write(`${JSON.stringify({ ...(result.hookSpecificOutput ? { hookSpecificOutput: result.hookSpecificOutput } : {}), timing: {
                     verify_ms: Math.round(verified - started), load_ms: Math.round(loaded - verified), open_ms: Math.round(opened - loaded), receipt_ms: Math.round(performance.now() - opened)
                 } })}\n`);
@@ -75,4 +96,7 @@ if (process.argv[1] === workerFile) {
         process.stderr.write(`${JSON.stringify({ ok: false, error: errorRecord(error) })}\n`);
         process.exitCode = 1;
     }
+    finally {
+        timing.unsubscribe(trace);
+    }
 }

package/dist/cli/memory-flow-admission.js

@@ -6,6 +6,7 @@ import { hybridDigest } from "../services/hybrid-contracts.js";
 import { AppError, errorRecord } from "../shared/errors.js";
 import { writePreparationError } from "./error-output.js";
 import { memoryInitStartupInputSchemas } from "../services/memory-init-startup-custody.js";
+import { isDiagnosticFlow } from "../domain/diagnostic-flows.js";
 /** Executing engine's real handler admission only. The caller owns independent
  * release/source selection; this command never opens storage or creates a RUN. */
 export async function runMemoryFlowAdmissionCli(args, io = process) {
@@ -20,8 +21,10 @@ export async function runMemoryFlowAdmissionCli(args, io = process) {
             throw new AppError("usage", "Flow admission requires an exact source snapshot and independent digest", 2, { effect: "no_effect" });
         }
         const selected = input;
+        const operation = route.parsed.options.get("operation")?.[0] ?? "";
+        const flowId = isDiagnosticFlow(operation) ? operation : operation === "memory-upgrade" ? "mb-upgrade" : "mb-init";
         const startupSchema = memoryInitStartupInputSchemas.find(schema => schema === selected.startup_input_schema);
-        if (Object.hasOwn(selected, "startup_input_schema") && startupSchema === undefined) {
+        if (Object.hasOwn(selected, "startup_input_schema") && (startupSchema === undefined || flowId !== "mb-init")) {
             throw new AppError("usage", "Executing engine does not support the requested startup input schema", 2, { effect: "no_effect" });
         }
         if (typeof selected.source_sha256 !== "string" || !/^[a-f0-9]{64}$/.test(selected.source_sha256)) {
@@ -29,9 +32,12 @@ export async function runMemoryFlowAdmissionCli(args, io = process) {
         }
         const source = PreparedInstalledFlowSource.restoreRetained(selected.source, selected.source_sha256);
         const flow = source.resolveRegisteredFlow();
-        const facts = { schema_id: startupSchema === undefined ? "dd-flow/memory-init-engine-flow@1" : "dd-flow/memory-init-engine-flow@2",
+        if (flow.descriptor.id !== flowId)
+            throw new AppError("usage", "Flow source does not match the requested engine admission operation", 2, { effect: "no_effect" });
+        const facts = { schema_id: isDiagnosticFlow(flowId) ? "dd-flow/diagnostic-engine-flow@1" : flowId === "mb-upgrade" ? "dd-flow/memory-upgrade-engine-flow@1"
+                : startupSchema === undefined ? "dd-flow/memory-init-engine-flow@1" : "dd-flow/memory-init-engine-flow@2",
             ...(startupSchema === undefined ? {} : { startup_input_schema: startupSchema }),
-            flow_id: "mb-init", source_sha256: source.sha256,
+            flow_id: flowId, source_sha256: source.sha256,
             descriptor_sha256: source.descriptorReference().sha256, stages: flow.descriptor.stages.map(stage => stage.id) };
         io.stdout.write(`${JSON.stringify({ ok: true, action: "runtime_flow_admit", facts, sha256: hybridDigest(facts) }, null, output.json ? undefined : 2)}\n`);
         return 0;

package/dist/cli/memory-init-invocation.js

@@ -3,15 +3,22 @@ import { AppError } from "../shared/errors.js";
 import { hybridDigest } from "../services/hybrid-contracts.js";
 import { prepareCommandRoute } from "./command-inputs.js";
 const stages = new Set(["preflight", "discover", "compose", "verify", "review", "finish"]);
+const upgradeStages = new Set(["preflight", "diff-analysis", "upgrade", "verify", "review", "finish"]);
 function refuse(message) {
     throw new AppError("usage", message, 2, { phase: "prepare", effect: "no_effect" });
 }
 /** Pure invocation preparation. File bytes, stored replay and productive
  * authority remain with their existing owners; no ambient defaults here. */
 export function prepareMemoryInitInvocation(args) {
+    return prepareMemoryInvocation(args, "mb-init");
+}
+export function prepareMemoryUpgradeInvocation(args) {
+    return prepareMemoryInvocation(args, "mb-upgrade");
+}
+function prepareMemoryInvocation(args, flowId) {
     const route = prepareCommandRoute(args);
-    if (!["init", "flow mb-init"].includes(route.key))
-        refuse("Use init or flow mb-init");
+    if (!(flowId === "mb-init" ? ["init", "flow mb-init"] : ["upgrade", "flow mb-upgrade"]).includes(route.key))
+        refuse(`Use ${flowId === "mb-init" ? "init" : "upgrade"} or flow ${flowId}`);
     const options = route.parsed.options;
     const value = (name) => options.get(name)?.[0];
     const scope = { projectRoot: value("project-root"), workspaceRoot: value("workspace-root"), requestId: value("request-id") };
@@ -38,7 +45,7 @@ export function prepareMemoryInitInvocation(args) {
         execution.rootProfile = profile;
     for (const assignment of options.get("stage-profile") ?? []) {
         const at = assignment.indexOf("="), stage = assignment.slice(0, at), profile = assignment.slice(at + 1);
-        if (at < 1 || !stages.has(stage) || !profile.trim() || execution.stageProfiles?.[stage] !== undefined)
+        if (at < 1 || !(flowId === "mb-init" ? stages : upgradeStages).has(stage) || !profile.trim() || execution.stageProfiles?.[stage] !== undefined)
             refuse("--stage-profile requires a unique stage=profile assignment");
         (execution.stageProfiles ??= {})[stage] = profile;
     }

package/dist/cli/memory-init.js

@@ -13,7 +13,7 @@ import { PreparedMemoryInitLintCapability } from "../services/memory-init-lint-c
 import { PreparedMemoryInitWorktrunkCapability } from "../services/memory-init-worktrunk-capability.js";
 import { produceMemoryInitNativeCapacity } from "../services/memory-init-native-capacity.js";
 import { openMemoryInitStores, assertMemoryInitStorePrerequisites } from "../services/memory-init-stores.js";
-import { prepareMemoryInitControllerStart } from "../services/memory-init-controller-start.js";
+import { prepareMemoryInitControllerStart, prepareMemoryUpgradeControllerStart } from "../services/memory-init-controller-start.js";
 import { runControllerStatus } from "../services/run-controller.js";
 import { requireRun } from "../services/run-controller-state.js";
 import { requireProjectByRoot } from "../services/projects.js";
@@ -28,6 +28,8 @@ import { onboardExecutor } from "../services/executor-onboarding.js";
 import { readOperatorProfiles, readOperatorProfileInput } from "../services/operator-profiles.js";
 import { resolveDdFlowHome } from "../storage/paths.js";
 import { askExecutorChoice } from "./executor-onboarding.js";
+import { isDiagnosticFlow } from "../domain/diagnostic-flows.js";
+import { prepareDiagnosticControllerStart } from "../services/memory-init-controller-start.js";
 /** Backpressure bounds the observing client's output; closing it never controls the RUN. */
 export async function writeMemoryInitObservation(stdout, text) {
     const disconnected = () => Boolean(stdout.destroyed);
@@ -159,73 +161,7 @@ export async function runMemoryInitCli(args, env = process.env, io = process) {
         // Beyond this boundary, absence of a success receipt is not no-effect.
         effects = true;
         const started = startMemoryInitRun(context, invocation.scope, prepared ? () => prepared : undefined);
-        if (invocation.prepareOnly) {
-            const run = requireRun(context, requireProjectByRoot(context, invocation.scope.projectRoot).id, started.runId);
-            const response = { ok: true, action: "flow_mb_init_prepared", flow_id: "mb-init", ...started,
-                run_id: started.runId, request_id: invocation.scope.requestId, run_root: run.run_root,
-                project_root: run.project_root, workspace_root: run.workspace_root };
-            await writeMemoryInitObservation(io.stdout, `${JSON.stringify(writeResponseFile(response, output), null, output.json || output.progressJsonl ? undefined : 2)}\n`);
-            return 0;
-        }
-        const launch = prepareMemoryInitControllerStart(context, invocation.scope);
-        // Use the existing RUN-bound router: a global CLI must not launch its own
-        // controller code in place of the independently frozen RUN executable.
-        const receiptChunks = [];
-        let receiptSize = 0, oversizedReceipt = false;
-        const capture = new Writable({ write(chunk, _, next) {
-                receiptSize += Buffer.byteLength(chunk);
-                if (receiptSize > 1024 * 1024)
-                    oversizedReceipt = true;
-                else
-                    receiptChunks.push(Buffer.from(chunk));
-                next();
-            } });
-        const routed = await routeArgsThroughEngine(context, ["run", "drive", "launch", "--project-root", launch.input.projectRoot,
-            "--run", launch.input.runId, "--request-id", launch.input.requestId, "--context-file", launch.input.contextFile,
-            "--context-sha256", launch.input.contextSha256, "--json"], { stdout: capture, stderr: io.stderr }, undefined, { ...env, DD_FLOW_ENGINE_MODE: undefined }, invocation.scope.projectRoot);
-        if (!routed?.routed || routed.inProcess || routed.exitCode !== 0 || oversizedReceipt)
-            throw new AppError("memory_init_controller_launch_unknown", "Observe or reconcile the exact RUN-bound controller launch", 1, { effect: "unknown" });
-        let receipt;
-        try {
-            receipt = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(receiptChunks)));
-        }
-        catch {
-            throw new AppError("memory_init_controller_launch_unknown", "Selected engine returned no valid controller receipt", 1, { effect: "unknown" });
-        }
-        const accepted = receipt.controller;
-        if (receipt.ok !== true || !accepted || accepted.run_id !== started.runId || accepted.request_id !== invocation.scope.requestId)
-            throw new AppError("memory_init_controller_launch_unknown", "Selected engine returned a foreign controller receipt", 1, { effect: "unknown" });
-        const emit = (result) => writeMemoryInitObservation(io.stdout, `${JSON.stringify(result, null, output.json || output.progressJsonl ? undefined : 2)}\n`);
-        if (output.progressJsonl && !await emit({ ok: true, action: "flow_accepted", flow_id: "mb-init", ...started, ...receipt }))
-            return 0;
-        let result = receipt;
-        if (!invocation.detach) {
-            let after = 0;
-            let recentEvents = [];
-            for (;;) {
-                // The client has no ownership of the detached controller process.
-                if (io.stdout.destroyed)
-                    return 0;
-                result = runControllerStatus(context, { projectRoot: invocation.scope.projectRoot, runId: started.runId, after });
-                const events = result.events, controller = result.controller;
-                after = result.next_cursor;
-                recentEvents = [...recentEvents, ...events].slice(-100);
-                if (output.progressJsonl && events.length && !await emit({ ok: true, action: "flow_progress", flow_id: "mb-init", ...result }))
-                    return 0;
-                if (!controller)
-                    throw new AppError("memory_init_controller_receipt_missing", "Observe or reconcile the retained controller", 1, { effect: "unknown" });
-                if (["completed", "cancelled", "superseded", "recovery_required", "failed", "waiting_for_user", "waiting_for_context"].includes(controller.status)) {
-                    result = { ...result, events: recentEvents };
-                    break;
-                }
-                await delay(250);
-            }
-        }
-        const response = { ...result, action: "flow_mb_init", flow_id: "mb-init", run_id: started.runId, request_id: invocation.scope.requestId };
-        if (!await emit(writeResponseFile(response, output)))
-            return 0;
-        const status = result.controller?.status;
-        return ["recovery_required", "failed", "cancelled", "superseded"].includes(status ?? "") ? 1 : 0;
+        return await launchAndObserveMemoryFlow(context, invocation, started, "mb-init", output, env, io);
     }
     catch (error) {
         const record = errorRecord(error);
@@ -238,3 +174,76 @@ export async function runMemoryInitCli(args, env = process.env, io = process) {
         context?.db.close?.();
     }
 }
+/** Shared foreground observer only; the existing RUN-bound controller owns
+ * physical Sessions. Neither alias gains another orchestration lifecycle. */
+export async function launchAndObserveMemoryFlow(context, invocation, started, flowId, output, env, io) {
+    const action = `flow_${flowId.replaceAll("-", "_")}`;
+    if (invocation.prepareOnly) {
+        const run = requireRun(context, requireProjectByRoot(context, invocation.scope.projectRoot).id, started.runId);
+        const response = { ok: true, action: `${action}_prepared`, flow_id: flowId, ...started,
+            run_id: started.runId, request_id: invocation.scope.requestId, run_root: run.run_root,
+            project_root: run.project_root, workspace_root: run.workspace_root };
+        await writeMemoryInitObservation(io.stdout, `${JSON.stringify(writeResponseFile(response, output), null, output.json || output.progressJsonl ? undefined : 2)}\n`);
+        return 0;
+    }
+    const launch = isDiagnosticFlow(flowId) ? prepareDiagnosticControllerStart(context, invocation.scope, flowId)
+        : (flowId === "mb-init" ? prepareMemoryInitControllerStart : prepareMemoryUpgradeControllerStart)(context, invocation.scope);
+    // Use the existing RUN-bound router: a global CLI must not launch its own
+    // controller code in place of the independently frozen RUN executable.
+    const receiptChunks = [];
+    let receiptSize = 0, oversizedReceipt = false;
+    const capture = new Writable({ write(chunk, _, next) {
+            receiptSize += Buffer.byteLength(chunk);
+            if (receiptSize > 1024 * 1024)
+                oversizedReceipt = true;
+            else
+                receiptChunks.push(Buffer.from(chunk));
+            next();
+        } });
+    const routed = await routeArgsThroughEngine(context, ["run", "drive", "launch", "--project-root", launch.input.projectRoot,
+        "--run", launch.input.runId, "--request-id", launch.input.requestId, "--context-file", launch.input.contextFile,
+        "--context-sha256", launch.input.contextSha256, "--json"], { stdout: capture, stderr: io.stderr }, undefined, { ...env, DD_FLOW_ENGINE_MODE: undefined }, invocation.scope.projectRoot);
+    if (!routed?.routed || routed.inProcess || routed.exitCode !== 0 || oversizedReceipt)
+        throw new AppError("memory_init_controller_launch_unknown", "Observe or reconcile the exact RUN-bound controller launch", 1, { effect: "unknown" });
+    let receipt;
+    try {
+        receipt = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(receiptChunks)));
+    }
+    catch {
+        throw new AppError("memory_init_controller_launch_unknown", "Selected engine returned no valid controller receipt", 1, { effect: "unknown" });
+    }
+    const accepted = receipt.controller;
+    if (receipt.ok !== true || !accepted || accepted.run_id !== started.runId || accepted.request_id !== invocation.scope.requestId)
+        throw new AppError("memory_init_controller_launch_unknown", "Selected engine returned a foreign controller receipt", 1, { effect: "unknown" });
+    const emit = (result) => writeMemoryInitObservation(io.stdout, `${JSON.stringify(result, null, output.json || output.progressJsonl ? undefined : 2)}\n`);
+    if (output.progressJsonl && !await emit({ ok: true, action: "flow_accepted", flow_id: flowId, ...started, ...receipt }))
+        return 0;
+    let result = receipt;
+    if (!invocation.detach) {
+        let after = 0;
+        let recentEvents = [];
+        for (;;) {
+            // The client has no ownership of the detached controller process.
+            if (io.stdout.destroyed)
+                return 0;
+            result = runControllerStatus(context, { projectRoot: invocation.scope.projectRoot, runId: started.runId, after });
+            const events = result.events, controller = result.controller;
+            after = result.next_cursor;
+            recentEvents = [...recentEvents, ...events].slice(-100);
+            if (output.progressJsonl && events.length && !await emit({ ok: true, action: "flow_progress", flow_id: flowId, ...result }))
+                return 0;
+            if (!controller)
+                throw new AppError("memory_init_controller_receipt_missing", "Observe or reconcile the retained controller", 1, { effect: "unknown" });
+            if (["completed", "cancelled", "superseded", "recovery_required", "failed", "waiting_for_user", "waiting_for_context"].includes(controller.status)) {
+                result = { ...result, events: recentEvents };
+                break;
+            }
+            await delay(250);
+        }
+    }
+    const response = { ...result, action, flow_id: flowId, run_id: started.runId, request_id: invocation.scope.requestId };
+    if (!await emit(writeResponseFile(response, output)))
+        return 0;
+    const status = result.controller?.status;
+    return ["recovery_required", "failed", "cancelled", "superseded"].includes(status ?? "") ? 1 : 0;
+}

package/dist/cli/memory-storage-admission.js

@@ -17,6 +17,7 @@ export function runMemoryStorageAdmissionCli(args, env = process.env, io = proce
         if (route.key !== "runtime storage admit" || output.responseFile || output.progressJsonl) {
             throw new AppError("usage", "Storage admission accepts stdout output only", 2, { effect: "no_effect" });
         }
+        const operation = route.parsed.options.get("operation")[0];
         const home = env.DD_FLOW_HOME;
         if (!home || !path.isAbsolute(home) || path.resolve(home) !== home || fs.realpathSync(home) !== home) {
             throw new AppError("usage", "Storage admission requires an explicit canonical absolute DD_FLOW_HOME", 2, { effect: "no_effect" });
@@ -27,7 +28,7 @@ export function runMemoryStorageAdmissionCli(args, env = process.env, io = proce
         const resource = PreparedMemoryInitResourceStorage.prepare({ ddFlowHome: home, env });
         const context = createContext(env, "prepared_existing");
         const facts = withStoreCleanup(() => {
-            const run = PreparedMemoryInitRuntimeStorage.prepare(context);
+            const run = operation === "memory-upgrade" ? PreparedMemoryInitRuntimeStorage.prepareUpgrade(context) : PreparedMemoryInitRuntimeStorage.prepare(context);
             const resourceWriter = getResourceDatabase(path.dirname(resource.facts().store_path), "prepared_existing");
             return withStoreCleanup(() => {
                 if (resourceWriter.get("SELECT dd_flow_writer_version() AS version")?.version !== resource.facts().executing_writer_version) {
@@ -38,7 +39,7 @@ export function runMemoryStorageAdmissionCli(args, env = process.env, io = proce
                 if (!current.isFile() || current.nlink !== 1 || current.dev !== owner.dev || current.ino !== owner.ino) {
                     throw new AppError("run_storage_changed", "RUN store changed during admission", 1, { effect: "no_effect" });
                 }
-                return { schema_id: "dd-flow/memory-init-engine-storage@1", operation: "memory-init", route: "verified-no-op", outcome: "no-op",
+                return { schema_id: `dd-flow/${operation}-engine-storage@1`, operation, route: "verified-no-op", outcome: "no-op",
                     run: { ...run.facts(), store_dev: owner.dev, store_ino: owner.ino }, resource: resource.facts() };
             }, () => resourceWriter.close?.());
         }, () => context.db.close?.());

package/dist/cli/memory-storage-qualification.js

@@ -0,0 +1,105 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { Writable } from "node:stream";
+import { DatabaseSync } from "node:sqlite";
+import { getDatabase, getResourceDatabase } from "../storage/database.js";
+import { canonicalPath } from "../storage/paths.js";
+import { prepareCommandRoute } from "./command-inputs.js";
+import { parseOutputOptions } from "./output-options.js";
+import { runMemoryStorageAdmissionCli } from "./memory-storage-admission.js";
+import { writePreparationError } from "./error-output.js";
+import { AppError, errorRecord } from "../shared/errors.js";
+import { hybridDigest } from "../services/hybrid-contracts.js";
+import { captureStoreMigrationState } from "../storage/writer-migration.js";
+import { PreparedPairedWriterMigration, observeDrainedMigrationStores } from "../storage/paired-writer-migration.js";
+import { assertImportAdmission } from "../storage/import-guard.js";
+/** Capability only. Exercise the actual target migration/admission on private
+ * WAL-aware copies before paying for a native probe. Never grants real-store
+ * write admission, productive migration proof or a runtime permit. */
+export function runMemoryStorageQualificationCli(args, env = process.env, io = process) {
+    let temporary;
+    try {
+        const output = parseOutputOptions(args), route = prepareCommandRoute(output.args);
+        if (route.key !== "runtime storage qualify" || output.responseFile || output.progressJsonl)
+            throw new AppError("usage", "Storage qualification accepts stdout output only", 2, { effect: "no_effect" });
+        const home = env.DD_FLOW_HOME, resource = env.DD_FLOW_RESOURCE_HOME;
+        for (const root of [home, resource])
+            if (!root || !path.isAbsolute(root) || canonicalPath(root, false) !== root)
+                throw new AppError("usage", "Qualification requires both explicit canonical storage Homes", 2, { effect: "no_effect" });
+        for (const root of new Set([home, resource]))
+            assertImportAdmission(root);
+        const stores = [{ database: path.join(home, "db.sqlite") }, { database: path.join(resource, "runtime.sqlite") }];
+        const admit = (selected) => {
+            let stdout = "", stderr = "";
+            const collect = (write) => new Writable({ write(chunk, _encoding, done) { write(chunk.toString()); done(); } });
+            const code = runMemoryStorageAdmissionCli(["runtime", "storage", "admit", "--operation", "memory-upgrade", "--json"], selected, { stdout: collect(chunk => { stdout += chunk; }), stderr: collect(chunk => { stderr += chunk; }) });
+            return { code, stdout, stderr };
+        };
+        const current = admit(env);
+        let selectedRoute = "verified-no-op";
+        if (current.code !== 0) {
+            // No simulation of a live runtime: the normal admission above remains
+            // sufficient for compatible stores; changed stores must already drain.
+            temporary = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "dd-upgrade-capability-")));
+            const runHome = path.join(temporary, "run"), resourceHome = path.join(temporary, "resource");
+            fs.mkdirSync(runHome);
+            fs.mkdirSync(resourceHome);
+            const copies = [path.join(runHome, "db.sqlite"), path.join(resourceHome, "runtime.sqlite")];
+            stores.forEach((store, index) => {
+                if (!fs.existsSync(store.database)) {
+                    if (["-wal", "-shm", "-journal"].some(suffix => fs.existsSync(store.database + suffix)))
+                        throw new AppError("storage_capability_invalid", "Missing source store retains sidecars", 1, { effect: "no_effect" });
+                    const fresh = index === 0 ? getDatabase(runHome, "create_new") : getResourceDatabase(resourceHome, "create_new");
+                    fresh.close?.();
+                    return;
+                }
+                const owner = fs.lstatSync(store.database);
+                if (!owner.isFile() || owner.nlink !== 1)
+                    throw new AppError("storage_capability_invalid", "Source store must have one regular physical owner", 1, { effect: "no_effect" });
+                const reader = new DatabaseSync(store.database, { readOnly: true });
+                try {
+                    reader.exec(`VACUUM INTO '${copies[index].replaceAll("'", "''")}'`);
+                    const copy = new DatabaseSync(copies[index], { readOnly: true });
+                    try {
+                        if (hybridDigest(captureStoreMigrationState(reader)) !== hybridDigest(captureStoreMigrationState(copy)))
+                            throw new AppError("storage_capability_invalid", "Source changed during private qualification", 1, { effect: "no_effect" });
+                    }
+                    finally {
+                        copy.close();
+                    }
+                    const after = fs.lstatSync(store.database);
+                    if (after.dev !== owner.dev || after.ino !== owner.ino || after.nlink !== 1)
+                        throw new AppError("storage_capability_invalid", "Source store owner changed", 1, { effect: "no_effect" });
+                }
+                finally {
+                    reader.close();
+                }
+            });
+            let checked = admit({ ...env, DD_FLOW_HOME: runHome, DD_FLOW_RESOURCE_HOME: resourceHome });
+            if (checked.code !== 0) {
+                observeDrainedMigrationStores(stores.filter(store => fs.existsSync(store.database)));
+                PreparedPairedWriterMigration.prepare({ requestId: "capability-only", requestFile: path.join(temporary, "plan.json"), projectRoot: temporary,
+                    workspaceRoot: temporary, runHome, resourceHome, selectionSha256: hybridDigest(stores), bootstrapSchema: "memory-upgrade@1" }).apply();
+                checked = admit({ ...env, DD_FLOW_HOME: runHome, DD_FLOW_RESOURCE_HOME: resourceHome });
+                selectedRoute = "migration";
+            }
+            if (checked.code !== 0)
+                throw new AppError("storage_capability_invalid", "Target cannot admit its privately migrated copies", 1, { effect: "no_effect", admission: JSON.parse(checked.stderr) });
+        }
+        const facts = { schema_id: "dd-flow/memory-upgrade-storage-capability@1", operation: "memory-upgrade", route: selectedRoute,
+            source_stores: stores.map(store => store.database), productive_admission: false };
+        io.stdout.write(`${JSON.stringify({ ok: true, action: "runtime_storage_qualify", facts, sha256: hybridDigest(facts) })}\n`);
+        return 0;
+    }
+    catch (error) {
+        const record = errorRecord(error);
+        record.details = { ...record.details, effect: "no_effect" };
+        writePreparationError(io, args, record);
+        return record.exitCode;
+    }
+    finally {
+        if (temporary)
+            fs.rmSync(temporary, { recursive: true, force: true });
+    }
+}