@deksden-com/dd-flow-cli 0.9.0-beta.15 → 0.9.0-beta.151

package/dist/cli/input-preparation.js

@@ -0,0 +1,165 @@
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { AppError, isAppError } from "../shared/errors.js";
+import { validateSchema } from "../services/schema-validation.js";
+export function prepareError(error, input = {}) {
+    if (isAppError(error)) {
+        // A malformed user input is safely correctable.  A broken schema registry,
+        // binding, or storage is not; do not disguise infrastructure damage as a
+        // retryable command typo.
+        const inputErrorCodes = new Set([
+            "usage", "validation", "schema_validation", "invalid_json", "not_found",
+            "path_escape", "input_file_missing", "input_file_not_regular", "input_file_unreadable",
+            "response_file_parent_invalid", "response_file_invalid", "context_checksum_mismatch", "invalid_run_config_state", "invalid_work_state", "invalid_stage_state", "runtime_budget_invalid", "runtime_scope_manifest_invalid", "runtime_scope_resume_invalid",
+            "fork_path_conflict", "fork_output_not_empty", "fork_checkpoint_invalid", "fork_engine_unavailable", "snapshot_missing",
+            "repair_check_declaration_missing", "review_repair_check_required", "review_check_reference_unknown", "semantic_status_inconsistent", "migration_report_invalid", "controller_context_missing", "snapshot_output_inside_runtime"
+        ]);
+        if (!inputErrorCodes.has(error.code) && error.details.phase !== "prepare")
+            throw error;
+        throw new AppError(error.code, error.message, 2, {
+            ...error.details,
+            phase: "prepare",
+            effect: error.details.effect ?? "no_effect",
+            recoverable: error.details.recoverable ?? true,
+            ...input
+        });
+    }
+    const code = error?.code;
+    if (typeof input.file !== "string" || !["ENOENT", "EACCES", "EPERM", "EISDIR", "ENOTDIR", "ELOOP", "ENAMETOOLONG"].includes(code ?? ""))
+        throw error;
+    throw new AppError("input_file_unreadable", `Cannot read input file${typeof input.file === "string" ? `: ${input.file}` : ""}`, 2, {
+        phase: "prepare", effect: "no_effect", recoverable: true, ...input, cause: code ?? String(error)
+    });
+}
+export function prepareTextFile(file, label = "input file", maxBytes) {
+    const prepared = prepareFileBytes(file, label, maxBytes);
+    if (maxBytes === undefined)
+        return { file: prepared.file, text: prepared.bytes.toString("utf8") };
+    try {
+        return { file: prepared.file, text: new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(prepared.bytes) };
+    }
+    catch {
+        return prepareError(new AppError("validation", `${label} must contain valid UTF-8`, 2), { file: prepared.file, label });
+    }
+}
+export async function readBoundedUtf8Stream(stream, maxBytes) {
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 0)
+        throw new AppError("usage", "Invalid input byte bound", 2);
+    const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+    let data = "", byteLength = 0;
+    for await (const chunk of stream) {
+        const bytes = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+        byteLength += bytes.length;
+        if (byteLength > maxBytes)
+            throw new AppError("usage", "Standard input exceeds its byte bound", 2);
+        try {
+            data += decoder.decode(bytes, { stream: true });
+        }
+        catch {
+            throw new AppError("validation", "Standard input must contain valid UTF-8", 2);
+        }
+    }
+    try {
+        return data + decoder.decode();
+    }
+    catch {
+        throw new AppError("validation", "Standard input must contain valid UTF-8", 2);
+    }
+}
+export function prepareFileBytes(file, label = "input file", maxBytes) {
+    const absolute = path.resolve(file);
+    let descriptor;
+    try {
+        descriptor = fs.openSync(absolute, fs.constants.O_RDONLY | fs.constants.O_NONBLOCK);
+        const stat = fs.fstatSync(descriptor);
+        if (!stat.isFile()) {
+            throw new AppError("input_file_not_regular", `${label} must be a readable regular file: ${absolute}`, 2, { file: absolute, label });
+        }
+        if (maxBytes === undefined)
+            return { file: absolute, bytes: fs.readFileSync(descriptor) };
+        if (!Number.isSafeInteger(maxBytes) || maxBytes < 0)
+            throw new AppError("usage", "Invalid input byte bound", 2);
+        const oversized = () => new AppError("usage", `${label} exceeds its byte bound`, 2);
+        if (stat.size > maxBytes)
+            throw oversized();
+        // Read at most one extra byte: the file can grow after fstat.
+        const buffer = Buffer.alloc(maxBytes + 1);
+        let length = 0;
+        while (length < buffer.length) {
+            const count = fs.readSync(descriptor, buffer, length, buffer.length - length, null);
+            if (!count)
+                break;
+            length += count;
+        }
+        if (length > maxBytes)
+            throw oversized();
+        return { file: absolute, bytes: buffer.subarray(0, length) };
+    }
+    catch (error) {
+        if (error?.code === "ENOENT") {
+            throw new AppError("input_file_missing", `${label} does not exist: ${absolute}`, 2, {
+                phase: "prepare", effect: "no_effect", recoverable: true, file: absolute, label
+            });
+        }
+        return prepareError(error, { file: absolute, label });
+    }
+    finally {
+        if (descriptor !== undefined)
+            fs.closeSync(descriptor);
+    }
+}
+export function prepareJsonText(text, input) {
+    try {
+        return { file: input.file, text, value: JSON.parse(text) };
+    }
+    catch {
+        // Keep the established public code so agents can recognise this as a
+        // safe correction-and-retry condition.
+        throw new AppError("invalid_json", `Invalid JSON in ${input.label ?? "input"}: ${input.file}`, 2, {
+            phase: "prepare", effect: "no_effect", recoverable: true, file: input.file, label: input.label ?? "input",
+            cause: "Invalid JSON syntax", input_sha256: crypto.createHash("sha256").update(text).digest("hex")
+        });
+    }
+}
+export function prepareJsonFile(file, label = "input JSON") {
+    const prepared = prepareTextFile(file, label);
+    return prepareJsonText(prepared.text, { file: prepared.file, label });
+}
+export function prepareJsonSchema(file, label, schema) {
+    const prepared = prepareJsonFile(file, label);
+    try {
+        validateSchema({ ...schema, file: prepared.file, data: prepared.value });
+    }
+    catch (error) {
+        return prepareError(error, { file: prepared.file, label });
+    }
+    return prepared;
+}
+/** Read-only destination check; execution still handles filesystem races. */
+export function prepareOutputFile(value) { return prepareOutput(value, false); }
+export function prepareOutputDirectory(value) { return prepareOutput(value, true); }
+function prepareOutput(value, directory) {
+    const file = path.resolve(value);
+    try {
+        let ancestor = directory ? file : path.dirname(file);
+        while (!fs.existsSync(ancestor) && path.dirname(ancestor) !== ancestor)
+            ancestor = path.dirname(ancestor);
+        if (!fs.statSync(ancestor).isDirectory())
+            throw new AppError("validation", "Output parent must be a directory", 2);
+        fs.accessSync(ancestor, fs.constants.W_OK | fs.constants.X_OK);
+        if (fs.existsSync(file)) {
+            const stat = fs.statSync(file);
+            if (directory ? !stat.isDirectory() : !stat.isFile())
+                throw new AppError("validation", directory ? "Output must name a directory" : "Output must name a regular file", 2);
+            fs.accessSync(file, fs.constants.W_OK | (directory ? fs.constants.X_OK : 0));
+        }
+        return file;
+    }
+    catch (error) {
+        const code = error?.code;
+        if (["ENOENT", "EACCES", "EPERM", "ENOTDIR", "ELOOP", "ENAMETOOLONG"].includes(code ?? ""))
+            return prepareError(new AppError("validation", "Output destination is not writable or has an invalid parent", 2, { cause: code }), { file, parameter: "output" });
+        return prepareError(error, { file, parameter: "output" });
+    }
+}

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

@@ -0,0 +1,50 @@
+import { prepareCommandRoute } from "./command-inputs.js";
+import { parseOutputOptions } from "./output-options.js";
+import { readBoundedUtf8Stream, prepareJsonText } from "./input-preparation.js";
+import { PreparedInstalledFlowSource } from "../services/installed-flow-source.js";
+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) {
+    try {
+        const output = parseOutputOptions(args), route = prepareCommandRoute(output.args);
+        if (route.key !== "runtime flow admit" || output.responseFile || output.progressJsonl) {
+            throw new AppError("usage", "Flow admission accepts bounded stdin and stdout output only", 2, { effect: "no_effect" });
+        }
+        const input = prepareJsonText(await readBoundedUtf8Stream(io.stdin, 64 * 1024 * 1024), { file: "<stdin>", label: "flow admission" }).value;
+        if (!input || typeof input !== "object" || Array.isArray(input)
+            || !["source,source_sha256", "source,source_sha256,startup_input_schema"].includes(Object.keys(input).sort().join())) {
+            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 || 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)) {
+            throw new AppError("usage", "Flow admission requires a SHA-256 source digest", 2, { effect: "no_effect" });
+        }
+        const source = PreparedInstalledFlowSource.restoreRetained(selected.source, selected.source_sha256);
+        const flow = source.resolveRegisteredFlow();
+        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: 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;
+    }
+    catch (error) {
+        const record = errorRecord(error);
+        writePreparationError(io, args, record);
+        return record.exitCode;
+    }
+}

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

@@ -0,0 +1,85 @@
+import path from "node:path";
+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 (!(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") };
+    if (![scope.projectRoot, scope.workspaceRoot].every(path.isAbsolute)
+        || !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$/.test(scope.requestId))
+        refuse("Init needs absolute roots and a bounded request id");
+    const execution = {};
+    const maxParallel = value("max-parallel");
+    const delegation = value("delegation"), nativeConfigHome = value("native-config-home");
+    if (maxParallel !== undefined || delegation !== undefined)
+        execution.delegation = {
+            mode: delegation === "native" ? "native" : "external", max_parallel: Number(maxParallel ?? 1)
+        };
+    if (delegation === "native" && Number(maxParallel ?? 1) > 15)
+        refuse("Native concurrency must be 1..15");
+    if (nativeConfigHome !== undefined && (!path.isAbsolute(nativeConfigHome) || delegation !== "native")
+        || options.has("allow-live-probe") && delegation !== "native")
+        refuse("Native probe options require explicit native delegation; an optional config home must be absolute");
+    const profile = value("profile");
+    const profileFile = value("profile-file");
+    if (profileFile !== undefined && (!path.isAbsolute(profileFile) || profile !== undefined))
+        refuse("--profile-file must be absolute and is exclusive with --profile");
+    if (profile !== undefined)
+        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 || !(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;
+    }
+    if (options.has("work-profile")) {
+        execution.workProfiles = [...options.get("work-profile")];
+        if (new Set(execution.workProfiles).size !== execution.workProfiles.length)
+            refuse("--work-profile must not repeat a profile");
+    }
+    const intakeFile = value("intake-file"), intakeSha256 = value("intake-sha256");
+    if (Boolean(intakeFile) !== Boolean(intakeSha256)
+        || intakeSha256 !== undefined && !/^[a-f0-9]{64}$/.test(intakeSha256)
+        || intakeFile !== undefined && !path.isAbsolute(intakeFile))
+        refuse("Original intake needs an absolute --intake-file and --intake-sha256 pair");
+    const gitRoute = value("git-route"), integrationBranch = value("integration-branch");
+    if (Boolean(gitRoute) !== Boolean(integrationBranch))
+        refuse("--git-route and --integration-branch must be supplied together");
+    const gitPolicy = gitRoute === undefined ? undefined : {
+        route: gitRoute, integrationBranch: integrationBranch
+    };
+    if (options.has("prepare-only") && options.has("detach"))
+        refuse("--prepare-only does not launch a controller and is exclusive with --detach");
+    return { scope, execution, gitPolicy, intakeFile, intakeSha256, profileFile, nativeConfigHome, allowLiveProbe: options.has("allow-live-probe"), nonInteractive: options.has("non-interactive"), detach: options.has("detach"), prepareOnly: options.has("prepare-only") };
+}
+/** Omitted selectors replay the retained choices, never current aliases.
+ * Supplied selectors must equal the original raw selection, not merely resolve
+ * to today's equivalent profile. Intake paths are locators, hashes bind bytes. */
+export function assertMemoryInitInvocationReplay(invocation, original, intakeSha256) {
+    if (hybridDigest(invocation.scope) !== hybridDigest(original.scope)
+        || invocation.intakeSha256 !== undefined && invocation.intakeSha256 !== intakeSha256
+        || invocation.gitPolicy !== undefined && hybridDigest(invocation.gitPolicy) !== hybridDigest(original.git_policy)
+        || Object.entries(invocation.execution).some(([key, value]) => !Object.hasOwn(original.execution, key)
+            || hybridDigest(value) !== hybridDigest(key === "delegation" && invocation.execution.delegation?.mode === "native"
+                ? { mode: original.execution.delegation?.mode, max_parallel: original.execution.delegation?.max_parallel }
+                : original.execution[key]))) {
+        throw new AppError("memory_init_request_conflict", "Request id belongs to different original init inputs", 1, { effect: "no_effect", next_action: "replay_exact_request_or_choose_new_id" });
+    }
+}

package/dist/cli/memory-init.js

@@ -0,0 +1,249 @@
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { setTimeout as delay } from "node:timers/promises";
+import { Writable } from "node:stream";
+import { once } from "node:events";
+import { createContext } from "../runtime/context.js";
+import { AppError, errorRecord } from "../shared/errors.js";
+import { hybridDigest } from "../services/hybrid-contracts.js";
+import { readMemoryInitStartupInput } from "../services/memory-init-startup-custody.js";
+import { readMemoryInitRequestInput } from "../services/memory-init-request-input.js";
+import { prepareMemoryInitFreshRequest, prepareMemoryInitSelection, startMemoryInitRun } from "../services/memory-init-start.js";
+import { PreparedMemoryInitLintCapability } from "../services/memory-init-lint-capability.js";
+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, 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";
+import { routeArgsThroughEngine } from "../services/engines.js";
+import { parseRuntimeBudget } from "../services/runtime-budget.js";
+import { prepareFileBytes } from "./input-preparation.js";
+import { prepareMemoryInitInvocation, assertMemoryInitInvocationReplay } from "./memory-init-invocation.js";
+import { parseOutputOptions } from "./output-options.js";
+import { prepareResponseDestination, writeResponseFile } from "./response-file.js";
+import { writePreparationError } from "./error-output.js";
+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);
+    if (disconnected())
+        return false;
+    const waiting = new AbortController();
+    try {
+        // Observe errors even when write returns true: a short pipe write can
+        // report EPIPE asynchronously. Writable emits callback errors as events.
+        const closed = once(stdout, "close", { signal: waiting.signal });
+        const written = new Promise(resolve => {
+            stdout.write(text, error => { if (!error)
+                resolve(); });
+        });
+        await Promise.race([written, closed]);
+        return !disconnected();
+    }
+    catch (error) {
+        if (error.code === "EPIPE")
+            return false;
+        throw error;
+    }
+    finally {
+        waiting.abort();
+    }
+}
+/** Both public spellings enter this owner. The controller, never this observer,
+ * owns Sessions and productive dispatch; disconnect does not request stop. */
+export async function runMemoryInitCli(args, env = process.env, io = process) {
+    let context;
+    let effects = false;
+    try {
+        const output = parseOutputOptions(args), invocation = prepareMemoryInitInvocation(output.args);
+        parseRuntimeBudget(env.DD_FLOW_RUNTIME_BUDGET);
+        if (output.responseFile)
+            prepareResponseDestination(output.responseFile);
+        const reader = createContext(env, "read_existing");
+        let retained;
+        try {
+            retained = readMemoryInitStartupInput(reader, invocation.scope);
+        }
+        finally {
+            reader.db.close?.();
+        }
+        let prepared;
+        if (retained) {
+            if (retained.payload.schema_id !== "dd-flow/memory-init-startup-input@3")
+                throw new AppError("memory_init_original_request_required", "Public init replay requires independently retained original input", 1, { effect: "no_effect" });
+            const raw = readMemoryInitRequestInput(retained.payload.request_input, invocation.scope, retained.payload.objective);
+            // A supplied file is an explicit selector and must still match. Omitted
+            // files never reopen mutable profile inputs during exact replay.
+            if (invocation.profileFile)
+                invocation.execution.rootProfile = readOperatorProfileInput(invocation.profileFile);
+            assertMemoryInitInvocationReplay(invocation, raw.selection, retained.payload.request_input.intake_sha256);
+            if (invocation.nativeConfigHome) {
+                const reference = retained.payload.execution.snapshot.settings.delegation.native_capacity_receipt;
+                const encoded = retained.payload.execution.receipt_blobs?.find(([checksum]) => checksum === reference?.sha256)?.[1];
+                if (!encoded || JSON.parse(Buffer.from(encoded, "base64").toString("utf8")).input.native_config_home !== invocation.nativeConfigHome)
+                    throw new AppError("memory_init_request_conflict", "Native private configuration selection changed", 1, { effect: "no_effect" });
+            }
+            context = openMemoryInitStores(env, { scope: invocation.scope, selectionSha256: hybridDigest(raw.selection) }).context;
+        }
+        else {
+            if (!invocation.intakeFile || !invocation.intakeSha256 || !invocation.gitPolicy)
+                throw new AppError("usage", "Fresh init requires original intake file/hash and explicit Git route/integration branch", 2, { phase: "prepare", effect: "no_effect" });
+            const raw = prepareFileBytes(invocation.intakeFile, "original init intake", 64 * 1024).bytes;
+            if (createHash("sha256").update(raw).digest("hex") !== invocation.intakeSha256)
+                throw new AppError("memory_init_intake_changed", "Original intake bytes differ from --intake-sha256", 2, { phase: "prepare", effect: "no_effect" });
+            let objective;
+            try {
+                objective = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(raw);
+            }
+            catch {
+                throw new AppError("usage", "Original init intake must be UTF-8", 2, { phase: "prepare", effect: "no_effect" });
+            }
+            // Controller birth/lease confirmation uses this OS observation. Known
+            // inability must refuse before candidate, stores or project publication.
+            const identity = spawnSync("ps", ["-o", "lstart=", "-p", String(process.pid)], { env: { ...env, TZ: "UTC", LC_ALL: "C" }, encoding: "utf8", timeout: 1000, shell: false, windowsHide: true });
+            if (identity.error || identity.signal || identity.status !== 0 || !identity.stdout.trim())
+                throw new AppError("memory_init_runtime_unavailable", "Controller physical identity observation is unavailable", 1, { phase: "prepare", effect: "no_effect", next_action: "restore_system_process_observation" });
+            const stdin = io.stdin ?? process.stdin;
+            const nonInteractive = invocation.nonInteractive || output.json || output.progressJsonl
+                || !stdin.isTTY || !io.stderr.isTTY;
+            const selected = await onboardExecutor({
+                ...(typeof invocation.execution.rootProfile === "string" ? { profileId: invocation.execution.rootProfile } : {}),
+                ...(invocation.profileFile ? { profileFile: invocation.profileFile } : {})
+            }, () => readOperatorProfiles(resolveDdFlowHome(env)), { allowSkip: false, nonInteractive }, settings => askExecutorChoice(settings, { stdin, stderr: io.stderr }, { allowSave: false, allowSkip: false }));
+            if (selected.source === "explicit-file" || selected.source === "explicit-profile")
+                invocation.execution.rootProfile = selected.profile;
+            else if (invocation.execution.rootProfile === undefined && selected.source === "explicit-id")
+                invocation.execution.rootProfile = selected.profile.id;
+            let native;
+            if (invocation.execution.delegation?.mode === "native") {
+                if (!invocation.allowLiveProbe)
+                    throw new AppError("usage", "Fresh native init requires --allow-live-probe", 2, { effect: "no_effect" });
+                const admissionReader = createContext(env, "read_existing");
+                let profile;
+                try {
+                    const baseline = prepareMemoryInitSelection(admissionReader, invocation.scope, { execution: {
+                            ...invocation.execution, delegation: { mode: "external", max_parallel: invocation.execution.delegation.max_parallel ?? 1 }
+                        }, gitPolicy: invocation.gitPolicy, objective });
+                    PreparedMemoryInitLintCapability.prepare(baseline.target, env);
+                    PreparedMemoryInitWorktrunkCapability.prepare(baseline.target, env);
+                    baseline.engine.admitMemoryInitFlow(baseline.source, "dd-flow/memory-init-startup-input@3");
+                    assertMemoryInitStorePrerequisites(env, invocation.scope);
+                    const snapshot = baseline.execution.snapshot();
+                    profile = snapshot.profiles.find(entry => entry.id === snapshot.settings.root_profile).profile;
+                    if (snapshot.profiles.some(entry => hybridDigest({ ...entry.profile, id: profile.id }) !== hybridDigest(profile)))
+                        throw new AppError("generic_execution_invalid", "Native delegation cannot change execution profiles", 2, { effect: "no_effect" });
+                }
+                finally {
+                    admissionReader.db.close?.();
+                }
+                // From here a failed reply cannot imply no effect: daemon/child custody
+                // is independent from later startup publication and RUN allocation.
+                effects = true;
+                native = await produceMemoryInitNativeCapacity({ home: resolveDdFlowHome(env), scope: invocation.scope, profile,
+                    maximum: invocation.execution.delegation.max_parallel ?? 1,
+                    ...(invocation.nativeConfigHome !== undefined ? { nativeConfigHome: invocation.nativeConfigHome } : {}),
+                    allowLiveProbe: invocation.allowLiveProbe, env, requestSha256: hybridDigest({ scope: invocation.scope,
+                        execution: invocation.execution, gitPolicy: invocation.gitPolicy, objective, intake: invocation.intakeSha256 }) });
+                invocation.execution.delegation.nativeCapacityReceipt = native.reference;
+            }
+            const owner = prepareMemoryInitFreshRequest(env, invocation.scope, { execution: invocation.execution, gitPolicy: invocation.gitPolicy, objective,
+                ...(native ? { receipts: native.receipts, receiptBytes: native.receiptBytes } : {}) }, raw);
+            context = owner.context;
+            prepared = owner.prepared;
+        }
+        // Beyond this boundary, absence of a success receipt is not no-effect.
+        effects = true;
+        const started = startMemoryInitRun(context, invocation.scope, prepared ? () => prepared : undefined);
+        return await launchAndObserveMemoryFlow(context, invocation, started, "mb-init", output, env, io);
+    }
+    catch (error) {
+        const record = errorRecord(error);
+        if (effects)
+            record.details = { ...record.details, effect: record.details.effect === "partial" ? "partial" : "unknown", next_action: "observe_or_reconcile_exact_request" };
+        writePreparationError(io, args, record);
+        return record.exitCode;
+    }
+    finally {
+        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

@@ -0,0 +1,54 @@
+import fs from "node:fs";
+import path from "node:path";
+import { prepareCommandRoute } from "./command-inputs.js";
+import { parseOutputOptions } from "./output-options.js";
+import { createContext } from "../runtime/context.js";
+import { getResourceDatabase } from "../storage/database.js";
+import { withStoreCleanup } from "../storage/native-cleanup.js";
+import { PreparedMemoryInitRuntimeStorage } from "../services/memory-init-storage.js";
+import { PreparedMemoryInitResourceStorage } from "../services/memory-init-resource-storage.js";
+import { hybridDigest } from "../services/hybrid-contracts.js";
+import { AppError, errorRecord } from "../shared/errors.js";
+import { writePreparationError } from "./error-output.js";
+/** Selected engine's non-migrating operation admission. No AppContext initialize. */
+export function runMemoryStorageAdmissionCli(args, env = process.env, io = process) {
+    try {
+        const output = parseOutputOptions(args), route = prepareCommandRoute(output.args);
+        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" });
+        }
+        const file = path.join(home, "db.sqlite"), owner = fs.lstatSync(file);
+        if (!owner.isFile() || owner.nlink !== 1)
+            throw new AppError("run_storage_unprepared", "RUN storage must be a regular single-linked file", 1, { effect: "no_effect" });
+        const resource = PreparedMemoryInitResourceStorage.prepare({ ddFlowHome: home, env });
+        const context = createContext(env, "prepared_existing");
+        const facts = withStoreCleanup(() => {
+            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) {
+                    throw new AppError("store_writer_incompatible", "Resource connection writer differs from admitted storage", 1, { effect: "no_effect" });
+                }
+                resource.revalidate({ ddFlowHome: home, env });
+                const current = fs.lstatSync(file);
+                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/${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?.());
+        io.stdout.write(`${JSON.stringify({ ok: true, action: "runtime_storage_admit", facts, sha256: hybridDigest(facts) }, null, output.json ? undefined : 2)}\n`);
+        return 0;
+    }
+    catch (error) {
+        const record = errorRecord(error);
+        writePreparationError(io, args, record);
+        return record.exitCode;
+    }
+}