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

package/dist/cli/completion-cli.js

@@ -0,0 +1,70 @@
+import { completionCandidates } from "./completion.js";
+import { prepareCommandRoute } from "./command-inputs.js";
+import { parseOutputOptions } from "./output-options.js";
+import { writePreparationError } from "./error-output.js";
+import { AppError, errorRecord } from "../shared/errors.js";
+import { prepareResponseDestination, writeResponseFile } from "./response-file.js";
+export function completionScript(shell) {
+    if (shell === "bash")
+        return `# dd-flow completion: bash
+_dd_flow_complete() {
+  local candidate
+  COMPREPLY=()
+  while IFS= read -r candidate; do
+    [ -n "$candidate" ] && COMPREPLY+=("$candidate")
+  done < <("${"$"}{COMP_WORDS[0]}" completion candidates -- "${"$"}{COMP_WORDS[@]:1:COMP_CWORD}")
+}
+complete -o default -F _dd_flow_complete dd-flow
+`;
+    if (shell === "zsh")
+        return `#compdef dd-flow
+_dd_flow_complete() {
+  local -a replies
+  replies=("${"$"}{(@f)$("${"$"}{words[1]}" completion candidates -- "${"$"}{(@)words[2,CURRENT]}")}")
+  if (( ${"$"}{#replies} )) && [[ -n "$replies[1]" ]]; then
+    compadd -a replies
+  else
+    _files
+  fi
+}
+compdef _dd_flow_complete dd-flow
+`;
+    if (shell === "fish")
+        return `function __dd_flow_candidates
+  set -l tokens (commandline -opc)
+  set -l prefix (commandline -ct)
+  set -l arguments
+  if test (count $tokens) -gt 1
+    set arguments $tokens[2..-1]
+  end
+  $tokens[1] completion candidates -- $arguments "$prefix"
+end
+complete -c dd-flow -a '(__dd_flow_candidates)'
+`;
+    throw new AppError("usage", "Supported completion shells: bash, zsh, fish", 2, { effect: "no_effect" });
+}
+/** Completion is grammar-only: never constructs an AppContext or writes a home. */
+export function runCompletionCli(args, io = { stdout: process.stdout, stderr: process.stderr }) {
+    let json = false;
+    try {
+        const output = parseOutputOptions(args);
+        json = output.json;
+        if (output.responseFile)
+            prepareResponseDestination(output.responseFile);
+        const route = prepareCommandRoute(output.args);
+        if (route.key === "completion candidates") {
+            const candidates = completionCandidates(route.parsed.positional);
+            io.stdout.write(json ? `${JSON.stringify(writeResponseFile({ candidates }, output))}\n` : candidates.map(value => `${value}\n`).join(""));
+        }
+        else {
+            const script = completionScript(route.command);
+            io.stdout.write(json ? `${JSON.stringify(writeResponseFile({ shell: route.command, script }, output))}\n` : script);
+        }
+        return 0;
+    }
+    catch (error) {
+        const record = errorRecord(error);
+        writePreparationError(io, args, record);
+        return record.exitCode;
+    }
+}

package/dist/cli/completion.js

@@ -0,0 +1,57 @@
+import { commandInputs } from "./command-inputs.js";
+import { globalOptionDocumentation, optionsForCommandTree } from "./command-metadata.js";
+const globalSwitches = globalOptionDocumentation.filter(option => option.kind === "switch").map(option => `--${option.name}`);
+const globalValues = globalOptionDocumentation.filter(option => option.kind === "value").map(option => `--${option.name}`);
+/** Read-only completion grammar. Last word is the cursor's unfinished token. */
+export function completionCandidates(words) {
+    const prefix = words.at(-1) ?? "";
+    const completed = words.slice(0, -1);
+    if (completed.includes("--"))
+        return [];
+    const positions = [];
+    let awaiting;
+    let routeKey;
+    const keys = Object.keys(commandInputs).filter(key => !commandInputs[key].retired);
+    const select = () => keys.filter(key => key.split(" ").every((part, index) => positions[index] === part))
+        .sort((left, right) => right.split(" ").length - left.split(" ").length)[0];
+    for (const word of completed) {
+        if (awaiting) {
+            awaiting = undefined;
+            continue;
+        }
+        if (word.startsWith("--")) {
+            const name = word.slice(2).split("=")[0];
+            const input = routeKey ? commandInputs[routeKey] : undefined;
+            const values = input?.values ?? [...new Set(Object.values(commandInputs).flatMap(item => item.values))];
+            if (!word.includes("=") && (values.includes(name) || globalValues.includes(`--${name}`)))
+                awaiting = name;
+            continue;
+        }
+        if (word === "-h")
+            continue;
+        positions.push(word);
+        routeKey = select();
+    }
+    const input = routeKey ? commandInputs[routeKey] : undefined;
+    let candidates;
+    const inline = prefix.match(/^--([^=]+)=(.*)$/);
+    if (awaiting || inline) {
+        const option = awaiting ?? inline[1];
+        candidates = option === "option" ? optionsForCommandTree(routeKey ?? positions.join(" ")).map(item => item.name)
+            : [...(input?.enums[option] ?? [])];
+        if (option === "option" && (inline?.[2] ?? prefix).startsWith("--"))
+            candidates = candidates.map(name => `--${name}`);
+        if (inline)
+            return candidates.filter(value => value.startsWith(inline[2])).map(value => `--${option}=${value}`).sort();
+    }
+    else if (prefix.startsWith("-")) {
+        candidates = [...globalSwitches, ...globalValues, ...(input ? [...input.values, ...input.switches].map(name => `--${name}`) : [])];
+    }
+    else {
+        candidates = keys.filter(key => {
+            const tokens = key.split(" ");
+            return positions.every((part, index) => tokens[index] === part) && tokens.length > positions.length;
+        }).map(key => key.split(" ")[positions.length]);
+    }
+    return [...new Set(candidates)].filter(value => value.startsWith(prefix)).sort();
+}

package/dist/cli/delivery.js

@@ -0,0 +1,108 @@
+import path from "node:path";
+import { createContext } from "../runtime/context.js";
+import { AppError, errorRecord } from "../shared/errors.js";
+import { deliveryFlowStages, isDeliveryFlow } from "../domain/delivery-flows.js";
+import { prepareCommandRoute } from "./command-inputs.js";
+import { prepareFlowExecutionSelectors } from "./diagnostic-invocation.js";
+import { parseOutputOptions } from "./output-options.js";
+import { prepareResponseDestination } from "./response-file.js";
+import { prepareTextFile } from "./input-preparation.js";
+import { writePreparationError } from "./error-output.js";
+import { resolveDdFlowHome, resolveProjectRoot } from "../storage/paths.js";
+import { readOperatorProfiles, readOperatorProfileInput } from "../services/operator-profiles.js";
+import { onboardExecutor } from "../services/executor-onboarding.js";
+import { askExecutorChoice } from "./executor-onboarding.js";
+import { PreparedInstalledFlowSource } from "../services/installed-flow-source.js";
+import { readSetupStatus } from "../services/setup.js";
+import { selectMemoryInitInstalledEngine } from "../services/memory-init-engine-release.js";
+import { FrozenGenericExecution } from "../services/generic-execution.js";
+import { readDeliveryRequest, retainDeliveryRequest, startDeliveryRun } from "../services/delivery-request.js";
+import { hybridDigest } from "../services/hybrid-contracts.js";
+import { registerProject } from "../services/projects.js";
+import { readFlowRunExecutionBundle } from "../services/runs.js";
+import { launchAndObserveMemoryFlow } from "./memory-init.js";
+function refuse(message) { throw new AppError("usage", message, 2, { phase: "prepare", effect: "no_effect" }); }
+export function prepareDeliveryInvocation(args) {
+    const route = prepareCommandRoute(args), flowId = route.command;
+    if (route.family !== "flow" || !isDeliveryFlow(flowId))
+        refuse("Use flow release, flow deploy or flow publish");
+    const options = route.parsed.options, value = (key) => options.get(key)?.[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("Use 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, deliveryFlowStages[flowId]);
+    if (selected.profileFile && !path.isAbsolute(selected.profileFile))
+        refuse("--profile-file must be absolute");
+    return { scope: { projectRoot, requestId, flowId }, workspace, ...selected, intakeFile: value("intake-file"),
+        detach: options.has("detach"), prepareOnly: options.has("prepare-only"), nonInteractive: options.has("non-interactive") };
+}
+/** Managed physical Sessions use the ordinary RUN controller. Launch is not
+ * publication permission; each productive operation still consumes approval. */
+export async function runDeliveryCli(args, env = process.env, io = process) {
+    let context, effects = false;
+    try {
+        const output = parseOutputOptions(args), invocation = prepareDeliveryInvocation(output.args), home = resolveDdFlowHome(env);
+        if (output.responseFile)
+            prepareResponseDestination(output.responseFile);
+        const { scope } = invocation;
+        if (resolveProjectRoot(scope.projectRoot) !== scope.projectRoot || invocation.workspace !== undefined
+            && resolveProjectRoot(invocation.workspace) !== invocation.workspace)
+            refuse("Roots must be canonical existing checkouts");
+        if (invocation.profileFile)
+            invocation.execution.rootProfile = readOperatorProfileInput(invocation.profileFile);
+        const text = invocation.intakeFile ? prepareTextFile(invocation.intakeFile, "delivery request", 64 * 1024).text : undefined;
+        context = createContext(env, "prepared_existing", undefined, { resourceDatabaseMode: "prepared_existing" });
+        const project = context.db.get("SELECT status FROM projects WHERE root=?", [scope.projectRoot]);
+        if (project && project.status !== "active")
+            refuse("Activate the selected project before delivery");
+        const retained = project ? readDeliveryRequest(context, scope) : null;
+        if (retained) {
+            if (Object.entries(invocation.execution).some(([key, value]) => !Object.hasOwn(retained.selection, key)
+                || hybridDigest(value) !== hybridDigest(retained.selection[key]))
+                || text !== undefined && text !== retained.objective
+                || invocation.workspace !== undefined && invocation.workspace !== retained.execution.scope.workspace)
+                refuse("Replay must preserve the original request, workspace and selectors");
+        }
+        else {
+            if (!text?.trim())
+                refuse("Fresh delivery requires --intake-file with the original request");
+            const setup = readSetupStatus(home);
+            if (!setup.installation || setup.installation_readiness !== "installed")
+                refuse("Install the desired canon and CLI using setup first");
+            const source = PreparedInstalledFlowSource.fromInstalledRelease(home, setup.installation.manifest_sha256, scope.flowId);
+            const engine = selectMemoryInitInstalledEngine(home, setup.installation.manifest_sha256);
+            engine.admitDeliveryFlow(source, scope.flowId);
+            const profiles = readOperatorProfiles(home), root = invocation.execution.rootProfile, stdin = io.stdin ?? process.stdin;
+            const selected = await onboardExecutor(typeof root === "string" ? { profileId: root } : root ? { profile: root } : {}, () => profiles, { allowSkip: false, nonInteractive: invocation.nonInteractive || output.json || output.progressJsonl
+                    || !stdin.isTTY || !io.stderr.isTTY }, settings => askExecutorChoice(settings, { stdin, stderr: io.stderr }, { allowSkip: false, allowSave: false }));
+            if (!selected.profile)
+                refuse("Select a delivery executor profile");
+            const execution = FrozenGenericExecution.prepare(source.resolveRegisteredFlow(), profiles, { ...invocation.execution,
+                rootProfile: root ?? selected.profile, execution: "managed", stageSessionMode: "new_session",
+                delegation: invocation.execution.delegation ?? { mode: "external", max_parallel: 1 } }, { projectRoot: scope.projectRoot, requestId: scope.requestId, workspace: invocation.workspace ?? scope.projectRoot });
+            effects = true;
+            registerProject(context, { root: scope.projectRoot });
+            retainDeliveryRequest(context, { scope, source, execution, engine, selection: invocation.execution, objective: text });
+        }
+        effects = true;
+        const started = startDeliveryRun(context, scope), bundle = readFlowRunExecutionBundle(context, { projectRoot: scope.projectRoot, runId: started.runId });
+        if (!bundle || bundle.manifest.flow_id !== scope.flowId)
+            throw new AppError("delivery_bundle_missing", "Restore the original delivery bundle", 1, { effect: "committed" });
+        return await launchAndObserveMemoryFlow(context, { ...invocation,
+            scope: { projectRoot: scope.projectRoot, requestId: scope.requestId, workspaceRoot: bundle.execution.snapshot().scope.workspace } }, started, scope.flowId, output, env, io);
+    }
+    catch (error) {
+        const record = errorRecord(error);
+        if (effects)
+            record.details = { ...record.details, effect: ["unknown", "partial", "committed"].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/diagnostic-invocation.js

@@ -0,0 +1,62 @@
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { diagnosticFlowStages } from "../domain/diagnostic-flows.js";
+import { distillStages } from "../domain/distill-flow.js";
+import { reviewFixStages } from "../domain/review-fix-flow.js";
+import { prepareCommandRoute } from "./command-inputs.js";
+function refuse(message) { throw new AppError("usage", message, 2, { effect: "no_effect" }); }
+/** Parser only: no files, operator settings, project mutation or runtime state. */
+export function prepareDiagnosticInvocation(args) {
+    const route = prepareCommandRoute(args), options = route.parsed.options;
+    const flowId = route.key === "flow review-fix" ? "review-fix" : route.key === "flow mb-distill" ? "mb-distill" : route.key === "flow mb-audit" ? "mb-audit"
+        : ["review", "flow project-review"].includes(route.key) ? "project-review" : refuse("Use flow mb-distill, flow mb-audit or review / flow project-review");
+    const stages = flowId === "review-fix" ? reviewFixStages : flowId === "mb-distill" ? distillStages : diagnosticFlowStages[flowId];
+    const value = (key) => options.get(key)?.[0];
+    const projectRoot = value("project-root"), requestId = value("request-id");
+    if (!path.isAbsolute(projectRoot) || path.resolve(projectRoot) !== projectRoot
+        || !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$/.test(requestId))
+        refuse("Use a canonical absolute project root and a bounded request ID");
+    if (options.has("detach") && options.has("prepare-only"))
+        refuse("--detach and --prepare-only are exclusive");
+    const selected = prepareFlowExecutionSelectors(options, stages);
+    const sourceRunId = value("source-run"), findingIds = options.get("finding");
+    if (Boolean(sourceRunId) !== Boolean(findingIds))
+        refuse("Supply --source-run together with one or more --finding values");
+    if (sourceRunId && (!/^RUN-[0-9]+-[a-z0-9-]+$/.test(sourceRunId) || !findingIds?.length || findingIds.length > 4096
+        || findingIds.some(id => !id.trim() || id.includes("\0")) || new Set(findingIds).size !== findingIds.length))
+        refuse("Select one exact source RUN and unique ordered finding IDs");
+    return { scope: { projectRoot, requestId, flowId }, ...selected,
+        ...(sourceRunId && findingIds ? { repairSelection: { sourceRunId, findingIds: [...findingIds] } } : {}), intakeFile: value("intake-file"),
+        detach: options.has("detach"), prepareOnly: options.has("prepare-only"), nonInteractive: options.has("non-interactive") };
+}
+/** Shared pure selectors for registered diagnostic and bounded repair launchers. */
+export function prepareFlowExecutionSelectors(options, stages) {
+    const value = (key) => options.get(key)?.[0];
+    if (value("profile") && value("profile-file"))
+        refuse("Use either --profile or --profile-file");
+    const execution = {};
+    if (value("profile"))
+        execution.rootProfile = value("profile");
+    const stageProfiles = {};
+    for (const assignment of options.get("stage-profile") ?? []) {
+        const match = /^([^=]+)=([^=]+)$/.exec(assignment);
+        if (!match || !stages.includes(match[1]) || Object.hasOwn(stageProfiles, match[1]))
+            refuse("--stage-profile requires one known stage=profile assignment per stage");
+        stageProfiles[match[1]] = match[2];
+    }
+    if (Object.keys(stageProfiles).length)
+        execution.stageProfiles = stageProfiles;
+    const workProfiles = options.get("work-profile");
+    if (workProfiles) {
+        if (workProfiles.some(id => !id.trim()) || new Set(workProfiles).size !== workProfiles.length)
+            refuse("Work profiles must be nonempty and unique");
+        execution.workProfiles = [...workProfiles];
+    }
+    if (value("max-parallel") !== undefined) {
+        const raw = value("max-parallel"), n = Number(raw);
+        if (!/^[1-9][0-9]*$/.test(raw) || !Number.isSafeInteger(n) || n > 64)
+            refuse("--max-parallel must be an integer from 1 to 64");
+        execution.delegation = { mode: "external", max_parallel: n };
+    }
+    return { execution, profileFile: value("profile-file") };
+}

package/dist/cli/diagnostic.js

@@ -0,0 +1,131 @@
+import { createContext } from "../runtime/context.js";
+import { AppError, errorRecord } from "../shared/errors.js";
+import { resolveDdFlowHome, resolveProjectRoot } from "../storage/paths.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 { readOperatorProfiles, readOperatorProfileInput } from "../services/operator-profiles.js";
+import { FrozenGenericExecution } from "../services/generic-execution.js";
+import { openMemoryInitStores } from "../services/memory-init-stores.js";
+import { registerProject, requireProjectByRoot } from "../services/projects.js";
+import { diagnosticSnapshotRoot } from "../services/diagnostic-snapshot.js";
+import { readDiagnosticRequest, retainDiagnosticRequest, startDiagnosticRun } from "../services/diagnostic-start.js";
+import { readFlowRunExecutionBundle } from "../services/runs.js";
+import { hybridDigest } from "../services/hybrid-contracts.js";
+import { onboardExecutor } from "../services/executor-onboarding.js";
+import { askExecutorChoice } from "./executor-onboarding.js";
+import { prepareDiagnosticInvocation } from "./diagnostic-invocation.js";
+import { parseOutputOptions } from "./output-options.js";
+import { prepareResponseDestination } from "./response-file.js";
+import { prepareFileBytes } from "./input-preparation.js";
+import { writePreparationError } from "./error-output.js";
+import { launchAndObserveMemoryFlow } from "./memory-init.js";
+import { publishSetup } from "../harness-runtime/lib/setup-progress.mjs";
+export async function runDiagnosticCli(args, env = process.env, io = process) {
+    let context, effects = false;
+    try {
+        const output = parseOutputOptions(args), invocation = prepareDiagnosticInvocation(output.args), home = resolveDdFlowHome(env);
+        if (output.responseFile)
+            prepareResponseDestination(output.responseFile);
+        const scope = invocation.scope;
+        if (resolveProjectRoot(scope.projectRoot) !== scope.projectRoot)
+            throw new AppError("usage", "Project root must be canonical", 2, { effect: "no_effect" });
+        const reader = createContext(env, "read_existing");
+        let retained = null;
+        try {
+            const project = reader.db.get("SELECT status FROM projects WHERE root=?", [scope.projectRoot]);
+            if (project?.status && project.status !== "active")
+                throw new AppError("diagnostic_project_inactive", "Activate the selected project explicitly before diagnosis", 2, { effect: "no_effect" });
+            if (project)
+                retained = readDiagnosticRequest(reader, scope);
+        }
+        finally {
+            reader.db.close?.();
+        }
+        if (scope.flowId === "review-fix" && !retained && !invocation.repairSelection)
+            throw new AppError("usage", "Fresh review-fix requires --source-run and explicit --finding selections", 2, { effect: "no_effect" });
+        if (invocation.profileFile)
+            invocation.execution.rootProfile = readOperatorProfileInput(invocation.profileFile);
+        const readIntake = () => {
+            if (!invocation.intakeFile)
+                throw new AppError("usage", "Fresh diagnosis requires --intake-file with the requested focus and constraints", 2, { effect: "no_effect" });
+            const bytes = prepareFileBytes(invocation.intakeFile, "diagnostic intake", 64 * 1024).bytes;
+            let text;
+            try {
+                text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+            }
+            catch {
+                throw new AppError("usage", "Diagnostic intake must be UTF-8", 2, { effect: "no_effect" });
+            }
+            if (!text.trim())
+                throw new AppError("usage", "Diagnostic intake cannot be empty", 2, { effect: "no_effect" });
+            return text;
+        };
+        if (retained) {
+            if (invocation.repairSelection && hybridDigest(invocation.repairSelection) !== hybridDigest(retained.repair_source?.selection))
+                throw new AppError("diagnostic_request_conflict", "Supplied finding selection differs from the retained review-fix request", 2, { effect: "no_effect" });
+            if (Object.entries(invocation.execution).some(([key, value]) => !Object.hasOwn(retained.selection, key) || hybridDigest(value) !== hybridDigest(retained.selection[key]))
+                || invocation.intakeFile && readIntake() !== retained.objective)
+                throw new AppError("diagnostic_request_conflict", "Supplied selectors differ from the original diagnostic request", 2, { effect: "no_effect" });
+        }
+        const objective = retained?.objective ?? readIntake();
+        let source, engine;
+        let rootProfile = invocation.execution.rootProfile;
+        if (!retained) {
+            const setup = readSetupStatus(home), installation = setup.installation;
+            if (!installation || setup.installation_readiness !== "installed")
+                throw new AppError("diagnostic_setup_required", "Install the desired canon and CLI with setup before diagnosis", 2, { effect: "no_effect" });
+            publishSetup("dependency_check_completed", "diagnostic:installation");
+            source = PreparedInstalledFlowSource.fromInstalledRelease(home, installation.manifest_sha256, scope.flowId);
+            publishSetup("dependency_check_completed", "diagnostic:canon");
+            engine = selectMemoryInitInstalledEngine(home, installation.manifest_sha256);
+            publishSetup("dependency_check_completed", "diagnostic:engine");
+            if (scope.flowId === "review-fix")
+                engine.admitReviewFixFlow(source);
+            else if (scope.flowId === "mb-distill")
+                engine.admitDistillFlow(source);
+            else
+                engine.admitDiagnosticFlow(source, scope.flowId);
+            publishSetup("dependency_check_completed", "diagnostic:handlers");
+            const stdin = io.stdin ?? process.stdin;
+            const selected = await onboardExecutor({ ...(typeof rootProfile === "string" ? { profileId: rootProfile } : {}),
+                ...(invocation.profileFile ? { profileFile: invocation.profileFile } : {}) }, () => readOperatorProfiles(home), { allowSkip: false, nonInteractive: invocation.nonInteractive || output.json || output.progressJsonl
+                    || !stdin.isTTY || !io.stderr.isTTY }, settings => askExecutorChoice(settings, { stdin, stderr: io.stderr }, { allowSave: false, allowSkip: false }));
+            if (!selected.profile)
+                throw new AppError("diagnostic_executor_required", "Select an executor profile before diagnosis", 2, { effect: "no_effect" });
+            rootProfile ??= selected.profile;
+        }
+        effects = true;
+        context = openMemoryInitStores(env, { scope: { projectRoot: scope.projectRoot, workspaceRoot: scope.projectRoot, requestId: scope.requestId },
+            selectionSha256: hybridDigest({ scope, objective, selection: retained?.selection ?? invocation.execution,
+                ...(scope.flowId === "review-fix" ? { repair_selection: retained?.repair_source?.selection ?? invocation.repairSelection } : {}) }) }).context;
+        publishSetup("dependency_check_completed", "diagnostic:stores");
+        registerProject(context, { root: scope.projectRoot });
+        if (!retained) {
+            const project = requireProjectByRoot(context, scope.projectRoot);
+            const workspace = diagnosticSnapshotRoot(context, { projectId: project.id, projectRoot: scope.projectRoot, sourceRoot: scope.projectRoot,
+                requestId: scope.requestId, flowId: scope.flowId });
+            const execution = FrozenGenericExecution.prepare(source.resolveRegisteredFlow(), readOperatorProfiles(home), {
+                ...invocation.execution, ...(rootProfile !== undefined ? { rootProfile } : {}), execution: "managed", stageSessionMode: "new_session",
+                delegation: invocation.execution.delegation ?? { mode: "external", max_parallel: 1 }
+            }, { requestId: scope.requestId, projectRoot: scope.projectRoot, workspace });
+            retainDiagnosticRequest(context, { scope, source: source, execution, engine: engine, objective, selection: invocation.execution,
+                ...(invocation.repairSelection ? { repairSelection: invocation.repairSelection } : {}) });
+        }
+        const started = startDiagnosticRun(context, scope), bundle = readFlowRunExecutionBundle(context, { projectRoot: scope.projectRoot, runId: started.runId });
+        if (!bundle)
+            throw new AppError("diagnostic_bundle_missing", "Restore the retained diagnostic bundle", 1, { effect: "committed" });
+        return await launchAndObserveMemoryFlow(context, { ...invocation,
+            scope: { projectRoot: scope.projectRoot, workspaceRoot: bundle.execution.snapshot().scope.workspace, requestId: scope.requestId } }, started, scope.flowId, 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/error-output.js

@@ -0,0 +1,62 @@
+import { hasHelpIntent } from "./help.js";
+import { commandHelpTopic } from "./command-metadata.js";
+import { writeJson } from "../shared/json.js";
+export function writePreparationError(io, args, error) {
+    const literal = args.indexOf("--");
+    const options = literal < 0 ? args : args.slice(0, literal);
+    const payload = { ok: false, error };
+    const help = hasHelpIntent(args);
+    let json = false;
+    for (let index = 0; index < options.length; index++) {
+        if (help && options[index] === "--option") {
+            index++;
+            continue;
+        }
+        if (options[index] === "--json")
+            json = true;
+    }
+    // Retain the hook's machine-only contract even when transport validation fails.
+    if (json || args.slice(0, 3).join(" ") === "codex hook handle")
+        writeJson(io.stderr, payload);
+    else
+        io.stderr.write(renderHumanError(payload, args));
+}
+export function renderHumanError(payload, args) {
+    const lines = [`dd-flow: ${payload.error.message}`, `code: ${payload.error.code}`];
+    const details = recordObject(payload.error.details);
+    for (const key of ["effect", "recoverable", "outcome", "instruction", "retry_instruction", "retry_command", "handoff_required", "work_id", "recovery_instruction"]) {
+        if (details?.[key] !== undefined)
+            lines.push(`${key}: ${String(details[key])}`);
+    }
+    const continuation = recordObject(details?.continuation);
+    if (continuation)
+        for (const key of ["outcome", "instruction", "work_id", "finish_command", "resume_command", "prompt_path"]) {
+            if (continuation[key] !== undefined)
+                lines.push(`continuation.${key}: ${String(continuation[key])}`);
+        }
+    const compatibility = recordObject(details?.compatibility);
+    const remediation = recordObject(details?.remediation);
+    if (compatibility) {
+        lines.push(`Compatibility: ${String(compatibility.verdict ?? "unknown")} (${String(compatibility.engine_resolution ?? "unknown")})`);
+        if (compatibility.blocked_operation)
+            lines.push(`Blocked operation: ${String(compatibility.blocked_operation)}`);
+        if (compatibility.install_hint)
+            lines.push(`Install compatible engine: ${String(compatibility.install_hint)}`);
+    }
+    if (remediation?.mb_upgrade_mode)
+        lines.push(`Upgrade mode: ${String(remediation.mb_upgrade_mode)}`);
+    if (details?.preferred_command)
+        lines.push(`Preferred command: ${String(details.preferred_command)}`);
+    const related = Array.isArray(details?.related_commands) ? details.related_commands.map(String) : [];
+    if (related.length > 0) {
+        lines.push("", "Related commands:");
+        for (const command of related)
+            lines.push(`  ${command}`);
+    }
+    const topic = commandHelpTopic(args, "");
+    lines.push(`See: dd-flow${topic ? ` ${topic}` : ""} --help`);
+    return `${lines.join("\n")}\n`;
+}
+function recordObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+}

package/dist/cli/executor-onboarding.js

@@ -0,0 +1,76 @@
+import { createInterface } from "node:readline";
+import { AppError } from "../shared/errors.js";
+import { prepareOperatorProfile, prepareProfileCreation, readOperatorProfileInput } from "../services/operator-profiles.js";
+/** One explicit choice; prompts go to stderr so stdout remains machine-readable. */
+export async function askExecutorChoice(settings, io, policy = {}) {
+    const ids = settings.profiles.map(entry => entry.id);
+    io.stderr.write(`Executor profiles: ${ids.length ? ids.join(", ") : "none configured"}\n`);
+    io.stderr.write(`Choose a profile ID/alias, file:/absolute/profile.json, create${policy.allowSkip === false ? "" : ", or skip"}. No model is selected automatically.\n`);
+    const terminal = createInterface({ input: io.stdin, output: io.stderr });
+    const lines = terminal[Symbol.asyncIterator]();
+    const cancelled = () => new AppError("onboarding_cancelled", "Executor onboarding was cancelled", 1, { effect: "no_effect" });
+    terminal.on("SIGINT", () => terminal.close());
+    const ask = async (prompt) => {
+        io.stderr.write(prompt);
+        const line = await lines.next();
+        if (line.done)
+            throw cancelled();
+        const answer = line.value.trim();
+        if (answer.length > 4096)
+            throw new AppError("usage", "Executor choice exceeds the input limit", 2, { effect: "no_effect" });
+        return answer;
+    };
+    try {
+        const answer = await ask("Executor: ");
+        if (answer === "skip") {
+            if (policy.allowSkip === false)
+                throw new AppError("agent_profile_missing", "This flow requires an executor profile", 1, { effect: "no_effect" });
+            return { skip: true };
+        }
+        if (answer === "create") {
+            io.stderr.write("Enter explicit profile settings; this does not probe providers or verify model access. Nothing is saved by this dialog.\n");
+            const input = { schema_id: "dd-flow/agent-profile@1" };
+            for (const [key, prompt] of [
+                ["id", "Profile ID: "], ["harness", "Harness (codex/zcode/agy/opencode/grok/droid): "],
+                ["provider", "Provider ID: "], ["model", "Model ID: "], ["reasoning", "Reasoning setting: "],
+                ["mode", "Mode setting: "], ["permission", "Permission (allow/deny): "]
+            ])
+                input[key] = await ask(prompt);
+            const profile = prepareOperatorProfile(input);
+            if (settings.profiles.some(entry => entry.id === profile.id) || Object.hasOwn(settings.aliases, profile.id)) {
+                throw new AppError("profile_id_conflict", "New profile ID collides with an existing profile or alias", 2, { effect: "no_effect" });
+            }
+            if (await ask("Use this profile for this operation? Type yes: ") !== "yes")
+                throw cancelled();
+            if (policy.allowSave === false)
+                return { profile };
+            const save = await ask("Save this profile globally during installation? Type yes or no: ");
+            if (save !== "yes" && save !== "no")
+                throw cancelled();
+            if (save === "yes") {
+                const defaultChoice = await ask("Set it as global default? Type yes or no: ");
+                if (defaultChoice !== "yes" && defaultChoice !== "no")
+                    throw cancelled();
+                return { profile, profileCreation: prepareProfileCreation(settings, profile, defaultChoice === "yes") };
+            }
+            return { profile };
+        }
+        if (answer.startsWith("file:")) {
+            const file = answer.slice(5);
+            if (!file.startsWith("/") && !/^[A-Za-z]:[\\/]/.test(file))
+                throw new AppError("usage", "Profile file must be an absolute path", 2, { effect: "no_effect" });
+            return { profile: readOperatorProfileInput(file) };
+        }
+        if (!answer)
+            throw new AppError("agent_profile_missing", "An explicit executor choice is required", 1, { effect: "no_effect" });
+        return { profileId: answer };
+    }
+    catch (error) {
+        if (error instanceof AppError)
+            throw error;
+        throw cancelled();
+    }
+    finally {
+        terminal.close();
+    }
+}

package/dist/cli/flows.js

@@ -0,0 +1,29 @@
+import { prepareCommandRoute } from "./command-inputs.js";
+import { parseOutputOptions } from "./output-options.js";
+import { prepareResponseDestination, writeResponseFile } from "./response-file.js";
+import { listBundledFlows, showBundledFlow } from "../services/flow-catalog.js";
+import { AppError, errorRecord } from "../shared/errors.js";
+import { writePreparationError } from "./error-output.js";
+/** Catalog inspection never creates an AppContext or executes a flow. */
+export function runFlowCatalogCli(args, io = process) {
+    try {
+        const output = parseOutputOptions(args);
+        const route = prepareCommandRoute(output.args);
+        let result;
+        if (route.key === "flow list")
+            result = { flows: listBundledFlows() };
+        else if (route.key === "flow show")
+            result = { flow: showBundledFlow(route.parsed.positional[0]) };
+        else
+            throw new AppError("usage", "Use dd-flow flow list or flow show <id>", 2, { effect: "no_effect" });
+        if (output.responseFile)
+            prepareResponseDestination(output.responseFile);
+        io.stdout.write(`${JSON.stringify(writeResponseFile({ ok: true, action: route.key.replaceAll(" ", "_"), ...result }, output), null, output.json ? undefined : 2)}\n`);
+        return 0;
+    }
+    catch (error) {
+        const record = errorRecord(error);
+        writePreparationError(io, args, record);
+        return record.exitCode;
+    }
+}