@deksden-com/dd-flow-cli 0.9.0-beta.16 → 0.9.0-beta.160

package/dist/cli/hook-ingress.js

@@ -0,0 +1,89 @@
+import { fileURLToPath } from "node:url";
+import { performance } from "node:perf_hooks";
+import { parseCommandArgs, parseLifecycleCommand, lifecycleCommandFromPayload, continuationCommand } from "../services/lifecycle-command.js";
+import { errorRecord, AppError } from "../shared/errors.js";
+import { parseJsonObject } from "../shared/json.js";
+import { assignedLifecycleHookCommand, retainedWorkStartHookCommand } from "./native-hook-preparation.js";
+const workerFile = fileURLToPath(import.meta.url);
+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) {
+    try {
+        const parsed = parseCommandArgs(args.slice(3));
+        for (const [key, values] of parsed.options)
+            if (!["event", "project-root", "json"].includes(key) || values.length !== 1)
+                throw new AppError("usage", `Invalid hook option: ${key}`, 2);
+        const event = parsed.options.get("event")?.[0];
+        if (!event?.trim() || event === "__dd_flow_flag__" || parsed.positional.length)
+            throw new AppError("usage", "Hook ingress requires --event with a value", 2);
+        const root = parsed.options.get("project-root")?.[0];
+        if (root !== undefined && (!root.trim() || root === "__dd_flow_flag__"))
+            throw new AppError("usage", "--project-root requires a value", 2);
+        if (parsed.options.has("json") && parsed.options.get("json")?.[0] !== "__dd_flow_flag__")
+            throw new AppError("usage", "--json does not take a value", 2);
+        const started = performance.now();
+        const budget = hookBudget(ingressBudgetMs, process.env.DD_FLOW_HOOK_DEADLINE_AT ? Number(process.env.DD_FLOW_HOOK_DEADLINE_AT) : null);
+        const stdin = await readNativeHookInput(process.stdin, budget);
+        const payload = parseJsonObject(stdin || "{}", "native hook stdin");
+        const command = lifecycleCommandFromPayload(payload);
+        const analysis = command ? parseLifecycleCommand(command) : { kind: "none", unresolved: false };
+        if (event !== "PreToolUse" || !command || (analysis.kind === "none" && (!("participation" in analysis) || !["lifecycle", "auxiliary"].includes(analysis.participation)) && !continuationCommand(command))) {
+            process.stdout.write("{}\n");
+            return 0;
+        }
+        // Assigned Stage and settlement commands are admitted by the CLI's
+        // retained packet/CAS, not by a second live hook delivery. A supplied ID
+        // is not authority: the CLI still validates the current assignment, owner,
+        // generation and exact arguments before any mutation. Work start and all
+        // hook-only/legacy commands still need their native identity receipt.
+        if (process.env.DD_FLOW_CODEX_STATE_DIR && assignedLifecycleHookCommand(command, process.env)) {
+            process.stdout.write("{}\n");
+            return 0;
+        }
+        // Legacy and bootstrap/native-receipt paths still use their existing
+        // identity checks. Run them here rather than launching a second Node
+        // process with a second deadline; unknown outcomes must not be reissued.
+        const phase = (name) => {
+            process.stderr.write(`${JSON.stringify({ kind: "native_hook_phase", phase: name, elapsed_ms: Math.round(performance.now() - started), remaining_ms: budget.remaining(name) })}\n`);
+        };
+        phase("input");
+        phase("verification");
+        const { verifyCodexHookDelivery } = await import("../services/codex-hook-delivery.js");
+        const proof = await verifyCodexHookDelivery(process.env, payload);
+        if (proof && retainedWorkStartHookCommand(command, proof.nativeHookBinding)) {
+            process.stdout.write("{}\n");
+            return 0;
+        }
+        phase("import");
+        const [{ createContext }, { handleCodexHook }] = await Promise.all([import("../runtime/context.js"), import("../services/hooks.js")]);
+        phase("store_open");
+        const context = createContext(process.env, "hook");
+        try {
+            if (proof)
+                context.codexHookProof = proof;
+            phase("receipt");
+            const result = handleCodexHook(context, { event, ...(root ? { projectRoot: root } : {}), stdin });
+            phase("committed");
+            // Preserve the legacy public response; managed Codex only consumes the
+            // native hook protocol field, not internal receipt metadata.
+            const output = process.env.DD_FLOW_CODEX_STATE_DIR
+                ? result.hookSpecificOutput ? { hookSpecificOutput: result.hookSpecificOutput } : {}
+                : result;
+            process.stdout.write(`${JSON.stringify(output)}\n`);
+        }
+        finally {
+            context.db.close?.();
+        }
+        return 0;
+    }
+    catch (error) {
+        const record = errorRecord(error);
+        process.stderr.write(`${JSON.stringify({ ok: false, error: record })}\n`);
+        return record.exitCode;
+    }
+}
+// Compatibility with direct invocations of the formerly nested worker.
+if (process.argv[1] === workerFile) {
+    process.exitCode = await runHookIngress(process.argv.slice(2));
+}

package/dist/cli/input-preparation.js

@@ -0,0 +1,193 @@
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { AppError, isAppError } from "../shared/errors.js";
+import { validateSchema } from "../services/schema-validation.js";
+// Observe only bytes already consumed by CLI preparation; never reread a file
+// in a hook or while replaying a retained outcome.
+const consumedInputs = new AsyncLocalStorage();
+export function recordConsumedInput(bytes) {
+    recordConsumedInputDigest(crypto.createHash("sha256").update(bytes).digest("hex"));
+}
+export function recordConsumedInputDigest(digest) { consumedInputs.getStore()?.push(digest); }
+export async function withPreparedInputBinding(prepare) {
+    return consumedInputs.run([], async () => {
+        try {
+            return await prepare();
+        }
+        catch (error) {
+            const inputs = consumedInputs.getStore();
+            if (isAppError(error) && inputs.length)
+                error.details.consumed_input_sha256 = crypto.createHash("sha256").update(JSON.stringify(inputs)).digest("hex");
+            throw error;
+        }
+    });
+}
+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 {
+        const text = data + decoder.decode();
+        recordConsumedInput(text);
+        return text;
+    }
+    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) {
+            const bytes = fs.readFileSync(descriptor);
+            recordConsumedInput(bytes);
+            return { file: absolute, bytes };
+        }
+        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();
+        const bytes = buffer.subarray(0, length);
+        recordConsumedInput(bytes);
+        return { file: absolute, bytes };
+    }
+    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/interactive-invocation.js

@@ -0,0 +1,33 @@
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { interactiveStages } from "../domain/interactive-flow.js";
+import { prepareCommandRoute } from "./command-inputs.js";
+import { prepareFlowExecutionSelectors } from "./diagnostic-invocation.js";
+/** Pure input preparation. Defaults remain omitted for exact retained replay. */
+export function prepareInteractiveInvocation(args) {
+    const refuse = (message) => { throw new AppError("usage", message, 2, { phase: "prepare", effect: "no_effect" }); };
+    const route = prepareCommandRoute(args);
+    if (route.key !== "flow interactive")
+        refuse("Use flow interactive");
+    const options = route.parsed.options, value = (name) => options.get(name)?.[0];
+    const projectRoot = value("project-root"), requestId = value("request-id"), workspace = value("workspace");
+    if (!path.isAbsolute(projectRoot) || path.resolve(projectRoot) !== projectRoot
+        || !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$/.test(requestId)
+        || workspace !== undefined && (!path.isAbsolute(workspace) || path.resolve(workspace) !== workspace))
+        refuse("Interactive needs canonical absolute roots and a bounded request ID");
+    if (options.has("detach") && options.has("prepare-only"))
+        refuse("--detach and --prepare-only are exclusive");
+    const selected = prepareFlowExecutionSelectors(options, interactiveStages);
+    if (selected.profileFile !== undefined && !path.isAbsolute(selected.profileFile))
+        refuse("--profile-file must be absolute");
+    const execution = value("execution");
+    if (execution)
+        selected.execution.execution = execution;
+    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
+        ? { route: gitRoute, integrationBranch: integrationBranch } : undefined;
+    return { scope: { projectRoot, requestId }, workspace, ...selected, gitPolicy, intakeFile: value("intake-file"),
+        detach: options.has("detach"), prepareOnly: options.has("prepare-only"), nonInteractive: options.has("non-interactive") };
+}

package/dist/cli/interactive.js

@@ -0,0 +1,114 @@
+import { createContext } from "../runtime/context.js";
+import { AppError, errorRecord } from "../shared/errors.js";
+import { resolveDdFlowHome, resolveProjectRoot } from "../storage/paths.js";
+import { readInteractiveRequest, assertInteractiveLaunchReplay, retainInteractiveRequest, startInteractiveRun } from "../services/interactive-request.js";
+import { PreparedProjectFlowSource } from "../services/project-flow-source.js";
+import { readSetupStatus } from "../services/setup.js";
+import { selectMemoryInitInstalledEngine } from "../services/memory-init-engine-release.js";
+import { readOperatorProfiles, readOperatorProfileInput } from "../services/operator-profiles.js";
+import { onboardExecutor } from "../services/executor-onboarding.js";
+import { prepareInteractiveExecution } from "../services/interactive-execution.js";
+import { PreparedInteractiveGitBaseline } from "../services/interactive-git-baseline.js";
+import { PreparedInteractiveBeforeVersions } from "../services/interactive-before-versions.js";
+import { inspectMemoryGitExecutable } from "../services/memory-init-preflight.js";
+import { loadVnextWorkspacePolicy } from "../services/vnext-workspace-policy.js";
+import { readFlowRunExecutionBundle } from "../services/runs.js";
+import { requireProjectByRoot } from "../services/projects.js";
+import { requireRun } from "../services/run-controller-state.js";
+import { prepareInteractiveContexts, publishInteractiveContexts } from "../services/memory-init-contexts.js";
+import { prepareInteractiveInvocation } from "./interactive-invocation.js";
+import { askExecutorChoice } from "./executor-onboarding.js";
+import { prepareTextFile } from "./input-preparation.js";
+import { parseOutputOptions } from "./output-options.js";
+import { prepareResponseDestination, writeResponseFile } from "./response-file.js";
+import { writePreparationError } from "./error-output.js";
+import { launchAndObserveMemoryFlow } from "./memory-init.js";
+/** One request/bundle/RUN owner. Attached returns candidates for the current
+ * trusted Session; managed uses the existing detached controller and observer. */
+export async function runInteractiveCli(args, env = process.env, io = process) {
+    let context, effects = false;
+    try {
+        const output = parseOutputOptions(args), invocation = prepareInteractiveInvocation(output.args), home = resolveDdFlowHome(env);
+        if (output.responseFile)
+            prepareResponseDestination(output.responseFile);
+        if (resolveProjectRoot(invocation.scope.projectRoot) !== invocation.scope.projectRoot
+            || invocation.workspace !== undefined && resolveProjectRoot(invocation.workspace) !== invocation.workspace)
+            throw new AppError("usage", "Interactive roots must be canonical existing checkouts", 2, { effect: "no_effect" });
+        if (invocation.profileFile)
+            invocation.execution.rootProfile = readOperatorProfileInput(invocation.profileFile);
+        const raw = structuredClone(invocation.execution);
+        const requestText = invocation.intakeFile ? prepareTextFile(invocation.intakeFile, "interactive request", 64 * 1024).text : undefined;
+        context = createContext(env, "prepared_existing", undefined, { resourceDatabaseMode: "prepared_existing" });
+        const retained = readInteractiveRequest(context, invocation.scope);
+        if (retained) {
+            assertInteractiveLaunchReplay(context, invocation.scope, { launchSelection: raw,
+                ...(invocation.workspace !== undefined ? { workspace: invocation.workspace } : {}),
+                ...(requestText !== undefined ? { requestText } : {}), ...(invocation.gitPolicy ? { gitPolicy: invocation.gitPolicy } : {}) });
+            const originalExecution = retained.blobs.find(item => item.path === "runtime/execution.json");
+            if (!originalExecution)
+                throw new AppError("interactive_request_invalid", "Restore the original execution selection", 2, { effect: "no_effect" });
+            const execution = JSON.parse(Buffer.from(originalExecution.base64, "base64").toString());
+            if (invocation.detach && execution.execution !== "managed")
+                throw new AppError("usage", "--detach requires managed execution", 2, { effect: "no_effect" });
+        }
+        else {
+            if (!requestText?.trim())
+                throw new AppError("usage", "Fresh interactive flow requires --intake-file", 2, { effect: "no_effect" });
+            if (invocation.detach && invocation.execution.execution !== "managed")
+                throw new AppError("usage", "--detach requires explicit managed execution", 2, { effect: "no_effect" });
+            const workspace = invocation.workspace ?? invocation.scope.projectRoot;
+            const source = PreparedProjectFlowSource.fromProject({ projectRoot: invocation.scope.projectRoot, workspace, flowId: "interactive" });
+            const installation = readSetupStatus(home).installation;
+            if (!installation)
+                throw new AppError("interactive_setup_required", "Install the desired CLI release before interactive execution", 2, { effect: "no_effect" });
+            const engine = selectMemoryInitInstalledEngine(home, installation.manifest_sha256);
+            engine.admitInteractiveFlow(source);
+            const settings = readOperatorProfiles(home), selectedRoot = invocation.execution.rootProfile, stdin = io.stdin ?? process.stdin;
+            const executor = await onboardExecutor(typeof selectedRoot === "string" ? { profileId: selectedRoot } : selectedRoot ? { profile: selectedRoot } : {}, () => settings, { allowSkip: false, nonInteractive: invocation.nonInteractive || output.json || output.progressJsonl
+                    || !stdin.isTTY || !io.stderr.isTTY }, profiles => askExecutorChoice(profiles, { stdin, stderr: io.stderr }, { allowSave: false, allowSkip: false }));
+            if (!executor.profile)
+                throw new AppError("interactive_executor_required", "Select an interactive executor", 2, { effect: "no_effect" });
+            const execution = prepareInteractiveExecution(context, { scope: { ...invocation.scope, workspace }, flow: source.resolveRegisteredFlow(), profiles: settings,
+                selection: { ...raw, rootProfile: selectedRoot ?? executor.profile }, launchArgs: args });
+            const gitExecutable = inspectMemoryGitExecutable(env).executable;
+            const defaults = invocation.gitPolicy ? null : loadVnextWorkspacePolicy(invocation.scope.projectRoot).workspace;
+            const gitPolicy = invocation.gitPolicy ?? { route: defaults.route, integrationBranch: defaults.integration_branch };
+            const baseline = PreparedInteractiveGitBaseline.capture({ projectRoot: invocation.scope.projectRoot, workspace, gitExecutable, env });
+            const beforeVersions = PreparedInteractiveBeforeVersions.capture(baseline, []);
+            effects = true;
+            retainInteractiveRequest(context, { source, engine, execution: execution.execution, baseline, beforeVersions,
+                boundAt: context.now(), requestText, gitExecutable, gitPolicy, launchSelection: raw, receipts: execution.receipts, receiptBytes: execution.receiptBytes }, execution.attached ?? undefined);
+        }
+        effects = true;
+        const started = startInteractiveRun(context, invocation.scope), bundle = readFlowRunExecutionBundle(context, { projectRoot: invocation.scope.projectRoot, runId: started.runId });
+        if (!bundle || bundle.manifest.flow_id !== "interactive")
+            throw new AppError("interactive_bundle_missing", "Restore the original interactive RUN bundle", 1, { effect: "committed" });
+        const workspaceRoot = bundle.execution.snapshot().scope.workspace;
+        if (bundle.execution.settings.execution === "managed")
+            return await launchAndObserveMemoryFlow(context, { scope: { ...invocation.scope, workspaceRoot }, prepareOnly: invocation.prepareOnly, detach: invocation.detach }, started, "interactive", output, env, io);
+        const run = requireRun(context, requireProjectByRoot(context, invocation.scope.projectRoot).id, started.runId);
+        const row = context.db.get("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type='flow_run.start_root_owned' AND json_extract(payload_json,'$.run_id')=?", [run.project_id, run.id]);
+        const owner = row ? JSON.parse(row.payload_json).owner : null;
+        if (!owner || !Number.isSafeInteger(owner.dev) || !Number.isSafeInteger(owner.ino))
+            throw new AppError("interactive_root_owner_missing", "Restore original RUN directory ownership", 1, { effect: "committed" });
+        const contexts = prepareInteractiveContexts(bundle, run.run_root);
+        publishInteractiveContexts(bundle, contexts.objective, run.run_root, contexts.sha256, owner);
+        const entry = bundle.descriptor.descriptor.entry_stage;
+        const response = { ok: true, action: invocation.prepareOnly ? "flow_interactive_prepared" : "flow_interactive_attached", flow_id: "interactive",
+            ...started, run_id: started.runId, request_id: invocation.scope.requestId, project_root: run.project_root,
+            workspace_root: run.workspace_root, run_root: run.run_root, context_file: contexts.file, context_sha256: contexts.sha256,
+            entry_stage: entry, entry_context: JSON.parse(contexts.files.get(contexts.file).toString()).stages[entry] };
+        io.stdout.write(`${JSON.stringify(writeResponseFile(response, output), null, output.json || output.progressJsonl ? undefined : 2)}\n`);
+        return 0;
+    }
+    catch (error) {
+        const record = errorRecord(error);
+        if (effects)
+            record.details = { ...record.details, effect: ["unknown", "committed", "partial"].includes(String(record.details.effect)) ? record.details.effect : "partial", next_action: "reconcile_exact_request" };
+        writePreparationError(io, args, record);
+        return record.exitCode;
+    }
+    finally {
+        context?.db.close?.();
+    }
+}

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

@@ -0,0 +1,52 @@
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { memoryFixStages } from "../domain/memory-fix-flow.js";
+import { prepareCommandRoute } from "./command-inputs.js";
+import { prepareFlowExecutionSelectors } from "./diagnostic-invocation.js";
+import { hybridDigest } from "../services/hybrid-contracts.js";
+function refuse(message) { throw new AppError("usage", message, 2, { phase: "prepare", effect: "no_effect" }); }
+/** No file/profile lookup, workspace creation or RUN allocation. Omitted fresh
+ * selectors remain omitted so a replay can use its retained choices. */
+export function prepareMemoryFixInvocation(args) {
+    const route = prepareCommandRoute(args);
+    if (route.key !== "flow mb-fix")
+        refuse("Use flow mb-fix");
+    const options = route.parsed.options, value = (name) => options.get(name)?.[0];
+    const projectRoot = value("project-root"), requestId = value("request-id"), workspaceRoot = value("workspace-root");
+    if (!path.isAbsolute(projectRoot) || path.resolve(projectRoot) !== projectRoot
+        || !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$/.test(requestId)
+        || workspaceRoot !== undefined && (!path.isAbsolute(workspaceRoot) || path.resolve(workspaceRoot) !== workspaceRoot))
+        refuse("Repair needs canonical absolute roots and a bounded request ID");
+    const sourceRunId = value("source-run"), findingIds = options.get("finding");
+    if (sourceRunId !== undefined && !/^RUN-[0-9]+(?:-[a-z0-9][a-z0-9-]*)?$/.test(sourceRunId))
+        refuse("--source-run must identify one diagnostic RUN");
+    if (Boolean(sourceRunId) !== Boolean(findingIds) || findingIds && (!findingIds.length || findingIds.length > 4096
+        || findingIds.some(id => !id.trim() || id.length > 256 || /[\r\n\0]/.test(id)) || new Set(findingIds).size !== findingIds.length))
+        refuse("Select one --source-run with unique explicit --finding IDs, or omit both on replay");
+    if (options.has("detach") && options.has("prepare-only"))
+        refuse("--detach and --prepare-only are exclusive");
+    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 ? { route: gitRoute, integrationBranch: integrationBranch } : undefined;
+    const selected = prepareFlowExecutionSelectors(options, memoryFixStages);
+    if (selected.profileFile !== undefined && !path.isAbsolute(selected.profileFile))
+        refuse("--profile-file must be absolute");
+    return { scope: { projectRoot, requestId }, workspaceRoot, sourceRunId, findingIds: findingIds ? [...findingIds] : undefined,
+        ...selected, gitPolicy, intakeFile: value("intake-file"), detach: options.has("detach"), prepareOnly: options.has("prepare-only"),
+        nonInteractive: options.has("non-interactive") };
+}
+/** Supplied selectors compare with original raw intent, never current aliases,
+ * defaults or an inferred equivalent model. Omitted selectors remain pinned. */
+export function assertMemoryFixInvocationReplay(invocation, original, intakeText) {
+    if (hybridDigest(invocation.scope) !== hybridDigest(original.scope)
+        || invocation.workspaceRoot !== undefined && invocation.workspaceRoot !== original.execution.scope.workspace
+        || invocation.sourceRunId !== undefined && invocation.sourceRunId !== original.source_run_id
+        || invocation.findingIds !== undefined && hybridDigest(invocation.findingIds) !== hybridDigest(original.finding_ids)
+        || invocation.gitPolicy !== undefined && hybridDigest(invocation.gitPolicy) !== hybridDigest(original.git_policy)
+        || invocation.intakeFile !== undefined && intakeText !== original.request_text
+        || Object.entries(invocation.execution).some(([key, value]) => !original.launch_selection
+            || !Object.hasOwn(original.launch_selection, key)
+            || hybridDigest(value) !== hybridDigest(original.launch_selection[key])))
+        throw new AppError("memory_fix_request_conflict", "Repair request belongs to different original launch inputs", 2, { effect: "no_effect", next_action: "replay_exact_request_or_choose_new_id" });
+}

package/dist/cli/memory-fix.js

@@ -0,0 +1,100 @@
+import { createContext } from "../runtime/context.js";
+import { AppError, errorRecord } from "../shared/errors.js";
+import { resolveDdFlowHome, resolveProjectRoot } from "../storage/paths.js";
+import { readMemoryFixRequest, retainMemoryFixRequest, startMemoryFixRun } from "../services/memory-fix-request.js";
+import { readDiagnosticRepairIntake } from "../services/diagnostic-repair-intake.js";
+import { prepareMemoryFixWorkspace } from "../services/memory-fix-workspace.js";
+import { readSetupStatus } from "../services/setup.js";
+import { PreparedInstalledFlowSource } from "../services/installed-flow-source.js";
+import { selectMemoryInitInstalledEngine } from "../services/memory-init-engine-release.js";
+import { FrozenGenericExecution } from "../services/generic-execution.js";
+import { readOperatorProfiles, readOperatorProfileInput } from "../services/operator-profiles.js";
+import { onboardExecutor } from "../services/executor-onboarding.js";
+import { askExecutorChoice } from "./executor-onboarding.js";
+import { prepareMemoryFixInvocation, assertMemoryFixInvocationReplay } from "./memory-fix-invocation.js";
+import { parseOutputOptions } from "./output-options.js";
+import { prepareTextFile } from "./input-preparation.js";
+import { prepareResponseDestination } from "./response-file.js";
+import { writePreparationError } from "./error-output.js";
+import { launchAndObserveMemoryFlow } from "./memory-init.js";
+import { readFlowRunExecutionBundle } from "../services/runs.js";
+import { hybridDigest } from "../services/hybrid-contracts.js";
+/** Public repair entry uses existing prepared stores: a fresh repair already
+ * requires an accepted source diagnostic in this Home. Never initializes a new
+ * project/Home, migrates stores or changes global profiles to find that source. */
+export async function runMemoryFixCli(args, env = process.env, io = process) {
+    let context, effects = false;
+    try {
+        const output = parseOutputOptions(args), invocation = prepareMemoryFixInvocation(output.args), home = resolveDdFlowHome(env);
+        if (output.responseFile)
+            prepareResponseDestination(output.responseFile);
+        if (resolveProjectRoot(invocation.scope.projectRoot) !== invocation.scope.projectRoot)
+            throw new AppError("usage", "Repair project root must be canonical", 2, { effect: "no_effect" });
+        const reader = createContext(env, "read_existing");
+        let retained;
+        try {
+            retained = readMemoryFixRequest(reader, invocation.scope);
+            if (!retained) {
+                if (!invocation.sourceRunId || !invocation.findingIds)
+                    throw new AppError("usage", "Fresh repair requires --source-run and explicit --finding IDs", 2, { effect: "no_effect" });
+                readDiagnosticRepairIntake(reader, { projectRoot: invocation.scope.projectRoot, sourceRunId: invocation.sourceRunId, findingIds: invocation.findingIds });
+            }
+        }
+        finally {
+            reader.db.close?.();
+        }
+        if (invocation.profileFile)
+            invocation.execution.rootProfile = readOperatorProfileInput(invocation.profileFile);
+        let objective;
+        if (invocation.intakeFile)
+            objective = prepareTextFile(invocation.intakeFile, "repair intake", 64 * 1024).text;
+        if (retained)
+            assertMemoryFixInvocationReplay(invocation, retained, objective);
+        else if (!objective?.trim())
+            throw new AppError("usage", "Fresh repair requires --intake-file with its original request and constraints", 2, { effect: "no_effect" });
+        if (!retained) {
+            const installation = readSetupStatus(home).installation;
+            if (!installation)
+                throw new AppError("memory_fix_setup_required", "Install the desired canon and CLI before repair", 2, { effect: "no_effect" });
+            const source = PreparedInstalledFlowSource.fromInstalledRelease(home, installation.manifest_sha256, "mb-fix");
+            const engine = selectMemoryInitInstalledEngine(home, installation.manifest_sha256);
+            engine.admitMemoryFixFlow(source);
+            const settings = readOperatorProfiles(home), selectedRoot = invocation.execution.rootProfile, stdin = io.stdin ?? process.stdin;
+            const executor = await onboardExecutor(typeof selectedRoot === "string" ? { profileId: selectedRoot } : selectedRoot ? { profile: selectedRoot } : {}, () => settings, { allowSkip: false, nonInteractive: invocation.nonInteractive || output.json || output.progressJsonl
+                    || !stdin.isTTY || !io.stderr.isTTY }, profiles => askExecutorChoice(profiles, { stdin, stderr: io.stderr }, { allowSave: false, allowSkip: false }));
+            if (!executor.profile)
+                throw new AppError("memory_fix_executor_required", "Select a repair executor", 2, { effect: "no_effect" });
+            const selection = { ...invocation.execution, rootProfile: selectedRoot ?? executor.profile,
+                execution: "managed", stageSessionMode: "new_session", delegation: invocation.execution.delegation ?? { mode: "external", max_parallel: 1 } };
+            const preview = FrozenGenericExecution.prepare(source.resolveRegisteredFlow(), settings, selection, { ...invocation.scope, workspace: invocation.workspaceRoot ?? invocation.scope.projectRoot });
+            context = createContext(env, "prepared_existing", undefined, { resourceDatabaseMode: "prepared_existing" });
+            effects = true;
+            const workspace = await prepareMemoryFixWorkspace(context, { ...invocation.scope,
+                ...(invocation.workspaceRoot ? { workspaceRoot: invocation.workspaceRoot } : {}), ...(invocation.gitPolicy ? { gitPolicy: invocation.gitPolicy } : {}),
+                selectionSha256: hybridDigest({ objective, source_run: invocation.sourceRunId, finding_ids: invocation.findingIds,
+                    raw: invocation.execution, profiles: preview.snapshot().profiles, settings: preview.settings,
+                    source_sha256: source.sha256, engine_manifest_sha256: engine.manifestSha256 }) });
+            const execution = FrozenGenericExecution.prepare(source.resolveRegisteredFlow(), settings, selection, { ...invocation.scope, workspace: workspace.workspaceRoot });
+            retainMemoryFixRequest(context, { source, execution, engine, boundAt: context.now(), requestText: objective, sourceRunId: invocation.sourceRunId,
+                findingIds: invocation.findingIds, gitExecutable: workspace.gitExecutable, gitPolicy: workspace.gitPolicy }, invocation.execution);
+        }
+        else
+            context = createContext(env, "prepared_existing", undefined, { resourceDatabaseMode: "prepared_existing" });
+        effects = true;
+        const started = startMemoryFixRun(context, invocation.scope), bundle = readFlowRunExecutionBundle(context, { projectRoot: invocation.scope.projectRoot, runId: started.runId });
+        if (!bundle || bundle.manifest.flow_id !== "mb-fix")
+            throw new AppError("memory_fix_bundle_missing", "Restore the retained repair bundle", 1, { effect: "committed" });
+        return await launchAndObserveMemoryFlow(context, { scope: { ...invocation.scope, workspaceRoot: bundle.execution.snapshot().scope.workspace },
+            prepareOnly: invocation.prepareOnly, detach: invocation.detach }, started, "mb-fix", output, env, io);
+    }
+    catch (error) {
+        const record = errorRecord(error);
+        if (effects)
+            record.details = { ...record.details, effect: ["unknown", "committed", "partial"].includes(String(record.details.effect)) ? record.details.effect : "partial", next_action: "reconcile_exact_request" };
+        writePreparationError(io, args, record);
+        return record.exitCode;
+    }
+    finally {
+        context?.db.close?.();
+    }
+}