@deksden-com/dd-flow-cli 0.9.0-beta.152 → 0.9.0-beta.155

package/dist/cli/help.js

@@ -2,6 +2,121 @@ 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([
+    ...["release", "deploy", "publish"].map((flow) => [`flow ${flow}`, `dd-flow flow ${flow} - start or replay one request-bound delivery RUN
+
+Usage:
+  dd-flow flow ${flow} --project-root /absolute/project --request-id ID --intake-file /absolute/request.txt --profile ID --json
+  dd-flow flow ${flow} --project-root /absolute/project --request-id ID --detach --json
+
+Fresh execution uses the installed canon and selected frozen engine, preserves
+the original request and operates in the assigned checkout. Managed Stage
+Sessions use the ordinary controller; independent verification requires a
+different physical Session, not merely another profile name. Starting the RUN
+does not approve a version, target, publication or deployment. Each productive
+operation needs its exact retained user approval and fresh access readback.
+
+Replay the same request ID to restore the original RUN, bundle, workspace and
+profiles. Omit current selectors and intake on replay; supplied values must match.
+--prepare-only creates runtime state but launches no provider Session; --detach
+returns the controller receipt without cancelling it. Unknown productive effects
+require original-intent reconciliation, never a new request or automatic retry.
+Use --option NAME --help for each option's exact contract.`]),
+    ["delivery", `dd-flow delivery - operations inside an existing delivery RUN
+
+Usage:
+  dd-flow delivery inputs RUN --project-root /absolute/project --stage STAGE --json
+  dd-flow delivery checks RUN --project-root /absolute/project --stage prepare --result-file /absolute/artifact.json --json
+  dd-flow delivery execute RUN --project-root /absolute/project --stage publish --result-file /absolute/approval.json --json
+  dd-flow delivery reconcile RUN --project-root /absolute/project --stage publish --json
+
+inputs is read-only and grants no authority. checks, execute and reconcile must
+use the exact command issued to the current physical Stage coordinator; an
+ambient scope variable or a Work Session cannot authorize them. They never
+allocate a new RUN. Use each command's --help or --option NAME --help for inputs.
+Checks use existing project policy and runner. Execution requires separate exact
+user approval, fresh access and original intent. Reconcile reads the original
+result without new publication or implicit retry; Stage/RUN finish is separate.`],
+    ["flow interactive", `dd-flow flow interactive - start or replay one request-bound interactive RUN
+
+Usage:
+  dd-flow flow interactive --project-root /absolute/project --request-id ID --intake-file /absolute/request.txt [--profile ID] --json
+  dd-flow flow interactive --project-root /absolute/project --request-id ID --execution managed --intake-file /absolute/request.txt --detach --json
+
+The default attached route requires a unique current trusted observation of this
+exact launch argv, workspace and profile. No automatic managed fallback. Managed
+execution must be selected explicitly and uses the existing RUN-bound controller.
+
+The project-local curated pack, engine, profiles, original request and Git baseline
+are frozen before execution. Use an existing registered project/prepared Home and
+assigned checkout; this command does not create a worktree or migrate storage.
+--prepare-only retains runtime state without productive dispatch: not a dry run.
+Replay may omit selectors; supplied values must match original retained intent.
+
+Stages: preflight → interactive → consolidation → hardening → review → integration.
+Use interactive inputs/turn/finish/scope within this same RUN. Explicit finish
+closes free-turn intake, not review, Git approval or RUN completion. Hardening and
+independent critics use registered Work and actual checks. Scoped Git integration
+preserves unrelated work and never pushes. Historical RUNs keep their own engine.`],
+    ["interactive", `dd-flow interactive - operate on an existing interactive RUN
+
+Commands:
+  inputs       Read original request, turns, HITL answers and current digest.
+  turn         Retain verbatim user input with stable identity and expected digest.
+  finish       Explicitly close free-turn intake; no new RUN or automatic approval.
+  scope        Retain selected mutation scope backed by genuine delivered input.
+  git-inputs   Inspect original selected workspace/index/HEAD versions read-only.
+  register     Register the initial hardening/review Work graph, not a provider.
+  checks       Select and execute current obligations through the common runner.
+  correction   Register a separate author from the exact negative reviewer Work.
+  re-review    Register a fresh independent critic after correction and checks.
+  integrate    Perform/reconcile only the accepted scoped local Git operation.
+
+All commands require --project-root and --run. Use a command's --help or
+--option NAME --help for its exact required inputs. They do not allocate a new RUN.
+The top-level finish alias accepts exactly the same inputs as interactive finish.
+Read-only inputs/git-inputs never initialize stores. Write operations require the
+existing prepared store; they do not migrate it. Exact retries preserve original
+custody. Unknown Git effects require reconciliation, not another commit or push.
+Use ordinary run control for cancellation; observer disconnect is not stop.`],
+    ["flow review-fix", `dd-flow flow review-fix - agree diagnostic scope and retain a raw handoff
+
+Usage:
+  dd-flow flow review-fix --project-root /absolute/project --request-id ID --source-run RUN-001-audit --finding FIND-001 --intake-file /absolute/request.txt [--profile ID] --json
+
+Stages: intake → scope-review → handoff. Select exact accepted diagnostic findings;
+selection is not approval to implement. The private snapshot is read-only.
+Scope-review uses a physically independent Session and considers the original
+request plus every actual delivered answer. Deferred, declined and needs_scope
+remain distinct from a ready handoff. No code, project documents or Git are changed.
+
+CLI retains original finding evidence and raw user inputs, not an agent-authored
+replacement specification. Even ready scope grants no formalization authority:
+only a separate explicit user request may start an ordinary SPECIFY-first SDLC RUN.
+
+Profiles, engine, canon, findings and original request are frozen before dispatch.
+Replay may omit selectors; supplied values must match the retained request.
+--prepare-only creates the source snapshot and RUN without controller/provider
+Sessions; it is not a dry run. --detach returns the controller receipt.
+Default execution is managed new_session with external concurrency 1; same_session
+cannot provide independent scope-review and refuses before request allocation.`],
+    ["flow mb-distill", `dd-flow flow mb-distill - extract and promote reusable practices
+
+Usage:
+  dd-flow flow mb-distill --project-root /absolute/project --request-id ID --intake-file /absolute/request.txt [--profile ID] --json
+
+Stages: preflight → extract → review → promote → verify → finish.
+Extraction uses a read-only source snapshot, domain/process applicability and
+independent novelty/portability critics. Promotion requires a separately accepted destination
+and exact candidate/document write scope. Source selection never grants shared
+canon write authority. Verification reads original selected documents and actual
+published outputs in an independent physical Session; missing evidence refuses.
+
+Profiles, engine, canon and original request are frozen before dispatch. Exact
+replay may omit selectors; supplied selectors must match the retained request.
+--prepare-only retains the snapshot and RUN without launching provider Sessions;
+it is not a dry run. --detach returns the controller receipt. Default execution
+uses fresh stage Sessions and external Work with concurrency 1. Use existing
+run drive status and run control commands to observe or reconcile this RUN.`],
     ["flow mb-audit", `dd-flow flow mb-audit - read-only Memory Bank audit
 
 Usage:
@@ -301,6 +416,7 @@ Core commands:
   storage migrate-writer      Explicitly back up and fence a drained SQLite store.
   runtime scope fence/status/stop Fence, inspect, or cancel one retained EVAL scope.
   memory permissions preflight Check Memory Bank write/read permissions.
+  memory distill inputs/publish Read retained input or publish an accepted scope in an already bound distill RUN.
   integration cmux status       Inspect optional cmux integration.
   codex home/hooks/hook         Manage Codex homes, hooks, and hook events.
   zcode event/usage             Ingest trusted zcode-acp lifecycle and usage evidence.
@@ -431,7 +547,7 @@ Usage:
   dd-flow run recovery inspect|begin|seal|capture|resume <RUN-ID|RUN-short-id> --project-root <root> --json
   dd-flow run snapshot create <RUN-ID|RUN-short-id> (--stage-entry <stage>|--candidate|--incomplete|--recovery-id <RCV-ID>) --project-root <root> --output <directory> --json
   dd-flow run snapshot restore --snapshot <directory> --project-root <prepared-root> [--recovery-id <RCV-ID>] --json
-  dd-flow run snapshot bootstrap create --project-root <root> --output <directory> [--flow sdlc|mb-init] --json
+  dd-flow run snapshot bootstrap create --project-root <root> --output <directory> [--flow <flow>] --json
   dd-flow run snapshot bootstrap restore --snapshot <directory> --project-root <prepared-root> --json
   dd-flow run fork --from <sealed-stage-entry-snapshot> --output <empty-directory> --engine-version <exact-version> --request-id <id> [--integrity-checksum <sha256>] --json
   dd-flow run timeline <RUN-ID|RUN-short-id> --project-root <root> --json

package/dist/cli/hook-ingress.js

@@ -1,9 +1,9 @@
 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";
+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");
@@ -22,6 +22,7 @@ export async function runHookIngress(args) {
             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");
@@ -31,72 +32,58 @@ export async function runHookIngress(args) {
             process.stdout.write("{}\n");
             return 0;
         }
-        const started = performance.now();
-        const { invokeNativeHook } = await import("../harness-runtime/lib/native-hook-command.mjs");
-        const result = await invokeNativeHook({ bin: workerFile, args, payload, home: process.env.DD_FLOW_HOME, timeoutMs: budget.remaining("admission") });
-        const { timing, ...output } = result;
-        process.stderr.write(`${JSON.stringify({ kind: "hook_ingress", total_ms: Math.round(performance.now() - started), ...timing })}\n`);
-        process.stdout.write(`${JSON.stringify(output)}\n`);
-        return 0;
-    }
-    catch (error) {
-        const record = errorRecord(error);
-        process.stderr.write(`${JSON.stringify({ ok: false, error: record })}\n`);
-        return record.exitCode;
-    }
-}
-// 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 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) });
+        // 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");
-        const stdin = await readNativeHookInput(process.stdin, budget);
-        const payload = parseJsonObject(stdin, "native hook stdin");
         phase("verification");
         const { verifyCodexHookDelivery } = await import("../services/codex-hook-delivery.js");
         const proof = await verifyCodexHookDelivery(process.env, payload);
-        const verified = performance.now();
+        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("imported");
-        const loaded = performance.now();
         phase("store_open");
         const context = createContext(process.env, "hook");
-        const opened = performance.now();
         try {
             if (proof)
                 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 });
+            const result = handleCodexHook(context, { event, ...(root ? { projectRoot: root } : {}), 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`);
+            // 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) {
-        process.stderr.write(`${JSON.stringify({ ok: false, error: errorRecord(error) })}\n`);
-        process.exitCode = 1;
-    }
-    finally {
-        timing.unsubscribe(trace);
+        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/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?.();
+    }
+}

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

@@ -2,11 +2,13 @@ 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 { PreparedProjectFlowSource } from "../services/project-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";
+import { isDeliveryFlow } from "../domain/delivery-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) {
@@ -22,7 +24,7 @@ export async function runMemoryFlowAdmissionCli(args, io = process) {
         }
         const selected = input;
         const operation = route.parsed.options.get("operation")?.[0] ?? "";
-        const flowId = isDiagnosticFlow(operation) ? operation : operation === "memory-upgrade" ? "mb-upgrade" : "mb-init";
+        const flowId = isDeliveryFlow(operation) ? operation : operation === "interactive" ? "interactive" : operation === "review-fix" ? "review-fix" : operation === "mb-fix" ? "mb-fix" : operation === "mb-distill" ? "mb-distill" : 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" });
@@ -30,11 +32,13 @@ export async function runMemoryFlowAdmissionCli(args, io = process) {
         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 source = flowId === "interactive"
+            ? PreparedProjectFlowSource.restoreRetained(selected.source, selected.source_sha256)
+            : 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"
+        const facts = { schema_id: isDeliveryFlow(flowId) ? "dd-flow/delivery-engine-flow@1" : flowId === "interactive" ? "dd-flow/interactive-engine-flow@1" : flowId === "review-fix" ? "dd-flow/review-fix-engine-flow@1" : flowId === "mb-fix" ? "dd-flow/memory-fix-engine-flow@1" : flowId === "mb-distill" ? "dd-flow/distill-engine-flow@1" : 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,