@deksden-com/dd-flow-cli 0.9.0-beta.135 → 0.9.0-beta.136

package/dist/cli/executor-onboarding.js

@@ -0,0 +1,71 @@
+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) {
+    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, 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")
+            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();
+            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/harnesses.js

@@ -0,0 +1,84 @@
+import { prepareCommandRoute } from "./command-inputs.js";
+import { writePreparationError } from "./error-output.js";
+import { parseOutputOptions } from "./output-options.js";
+import { optionalOption, optionalPositiveNumber } from "./argument-values.js";
+import { discoverHarnesses, harnessCatalog } from "../services/harness-discovery.js";
+import { AppError, errorRecord } from "../shared/errors.js";
+import { probeHarnessVersion } from "../services/harness-version-probe.js";
+import { probeHarnessDoctor } from "../services/harness-doctor.js";
+import { prepareResponseDestination, writeResponseFile } from "./response-file.js";
+import path from "node:path";
+import { validateModelScope } from "../services/model-discovery.js";
+/** Home-free ingress: process diagnostics require explicit effect admission. */
+export async function runHarnessesCli(args, env, 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);
+        const family = route.key === "harnesses show" ? route.parsed.positional[0] : optionalOption(route.parsed, "harness");
+        if (family && !harnessCatalog.entries.some(entry => entry.id === family))
+            throw new AppError("usage", "Unknown harness; see dd-flow harnesses --help", 2, { effect: "no_effect" });
+        const provider = optionalOption(route.parsed, "provider"), account = optionalOption(route.parsed, "account-sha256");
+        const observationFile = optionalOption(route.parsed, "model-observation-file");
+        let modelScope;
+        if (provider !== undefined || account !== undefined || observationFile !== undefined) {
+            if (!provider || !account)
+                throw new AppError("usage", "Doctor model observations require both --provider and --account-sha256", 2, { effect: "no_effect", help: "harnesses doctor" });
+            modelScope = { harness: family, provider, account_sha256: account };
+            validateModelScope(modelScope);
+            if (observationFile) {
+                if (output.responseFile && path.resolve(observationFile) === path.resolve(output.responseFile))
+                    throw new AppError("usage", "Model observation and command response destinations must differ", 2, { effect: "no_effect" });
+                prepareResponseDestination(observationFile);
+            }
+        }
+        const discovery = discoverHarnesses({ env, ...(family ? { harness: family } : {}),
+            ...(optionalOption(route.parsed, "executable") ? { executable: optionalOption(route.parsed, "executable") } : {}) });
+        let probe;
+        let modelObservation;
+        let observationPublication;
+        if (route.key === "harnesses doctor") {
+            const selected = discovery.entries[0]?.candidates.find(candidate => candidate.selected);
+            if (!selected)
+                throw new AppError("harness_selection_required", "Doctor requires one installed executable; use --executable for ambiguous installations", 1, { effect: "no_effect" });
+            const stateDir = optionalOption(route.parsed, "state-dir"), nativeExecutable = optionalOption(route.parsed, "native-executable");
+            const timeoutMs = optionalPositiveNumber(route.parsed, "timeout-ms", true);
+            probe = await probeHarnessDoctor({ harness: family, executable: selected.path, env,
+                ...(stateDir !== undefined ? { stateDir } : {}), ...(nativeExecutable !== undefined ? { nativeExecutable } : {}),
+                ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+                scope: { processes: route.parsed.options.has("allow-processes"), services: route.parsed.options.has("allow-services"),
+                    credentials: route.parsed.options.has("allow-credentials"), writes: route.parsed.options.has("allow-writes") } });
+            if (modelScope) {
+                modelObservation = { scope: modelScope, observed_at: new Date().toISOString(),
+                    status: probe.reported_models.length ? "listed" : "unavailable", complete: false, models: [...probe.reported_models] };
+                if (observationFile) {
+                    const published = writeResponseFile(modelObservation, { responseFile: observationFile });
+                    observationPublication = { path: observationFile, status: published.response_file_error ? "unknown" : "published",
+                        ...(published.response_file_error ? { error: published.response_file_error } : {}) };
+                }
+            }
+        }
+        else if (route.key === "harnesses probe-version") {
+            const selected = discovery.entries[0]?.candidates.find(candidate => candidate.selected);
+            if (!selected)
+                throw new AppError("harness_selection_required", "Version probe requires one installed executable; use --executable for ambiguous installations", 1, { effect: "no_effect" });
+            probe = await probeHarnessVersion({ harness: family, executable: selected.path, env,
+                ...(optionalPositiveNumber(route.parsed, "timeout-ms", true) === undefined ? {} : { timeoutMs: optionalPositiveNumber(route.parsed, "timeout-ms", true) }),
+                scope: { processes: route.parsed.options.has("allow-processes"), services: false,
+                    credentials: route.parsed.options.has("allow-credentials"), writes: route.parsed.options.has("allow-writes") } });
+        }
+        const result = { ok: true, action: route.key.replaceAll(" ", "_"), catalog: harnessCatalog, discovery, ...(probe ? { probe } : {}),
+            ...(modelObservation ? { model_observation: modelObservation, observation_scope_binding: "operator_declared_unverified" } : {}),
+            ...(observationPublication ? { model_observation_publication: observationPublication } : {}) };
+        io.stdout.write(`${JSON.stringify(writeResponseFile(result, output), null, json ? undefined : 2)}\n`);
+        return 0;
+    }
+    catch (error) {
+        const record = errorRecord(error);
+        writePreparationError(io, args, record);
+        return record.exitCode;
+    }
+}

package/dist/cli/models.js

@@ -0,0 +1,39 @@
+import { prepareCommandRoute } from "./command-inputs.js";
+import { optionalOption } from "./argument-values.js";
+import { parseOutputOptions } from "./output-options.js";
+import { prepareResponseDestination, writeResponseFile } from "./response-file.js";
+import { listOperatorModels } from "../services/model-catalog.js";
+import { AppError, errorRecord } from "../shared/errors.js";
+import { writePreparationError } from "./error-output.js";
+/** Model listing never opens an AppContext, starts a probe or reads credentials. */
+export function runModelsCli(args, io = process) {
+    let json = false;
+    try {
+        const output = parseOutputOptions(args);
+        json = output.json;
+        if (output.responseFile)
+            prepareResponseDestination(output.responseFile);
+        const route = prepareCommandRoute(output.args);
+        if (!["models list", "models show"].includes(route.key))
+            throw new AppError("usage", "Unknown models command; see dd-flow models --help", 2, { effect: "no_effect" });
+        const input = {};
+        for (const [option, field] of [["harness", "harness"], ["provider", "provider"], ["account-sha256", "accountSha256"],
+            ["seed-file", "seedFile"], ["observation-file", "observationFile"]]) {
+            const value = optionalOption(route.parsed, option);
+            if (value !== undefined)
+                input[field] = value;
+        }
+        if (route.key === "models show")
+            input.model = route.parsed.positional[0];
+        const models = listOperatorModels(input);
+        if (route.key === "models show" && models.entries.length === 0)
+            throw new AppError("model_not_found", "Model is absent from the selected seed and scoped observation", 1, { effect: "no_effect", help: "models" });
+        io.stdout.write(`${JSON.stringify(writeResponseFile({ ok: true, action: route.key.replaceAll(" ", "_"), ...models }, output), null, json ? undefined : 2)}\n`);
+        return 0;
+    }
+    catch (error) {
+        const record = errorRecord(error);
+        writePreparationError(io, args, record);
+        return record.exitCode;
+    }
+}

package/dist/cli/operator-profiles.js

@@ -0,0 +1,61 @@
+import { requiredOption, optionalOption } from "./argument-values.js";
+import { AppError } from "../shared/errors.js";
+import { errorRecord } from "../shared/errors.js";
+import { prepareCommandRoute } from "./command-inputs.js";
+import { parseOutputOptions } from "./output-options.js";
+import { writePreparationError } from "./error-output.js";
+import { resolveDdFlowHome } from "../storage/paths.js";
+import { prepareResponseDestination, writeResponseFile } from "./response-file.js";
+import { readOperatorProfiles, resolveOperatorProfile, mutateOperatorProfiles, readOperatorProfileInput } from "../services/operator-profiles.js";
+/** Home-only entrypoint; does not create AppContext, project registration or runtime DB. */
+export function dispatchOperatorProfiles(home, route) {
+    const action = route.command, parsed = route.parsed;
+    if (action === "list")
+        return { ok: true, action: "profiles_list", settings: readOperatorProfiles(home) };
+    if (action === "show") {
+        const settings = readOperatorProfiles(home), id = parsed.positional[0];
+        return { ok: true, action: "profiles_show", selected: id, revision: settings.revision, profile: resolveOperatorProfile(settings, id) };
+    }
+    let mutation;
+    if (action === "create")
+        mutation = { action, profile: readOperatorProfileInput(requiredOption(parsed, "file")), setDefault: parsed.options.has("set-default") };
+    else if (action === "edit")
+        mutation = { action, profile: readOperatorProfileInput(requiredOption(parsed, "file")) };
+    else if (action === "remove")
+        mutation = { action, id: parsed.positional[0] };
+    else if (action === "alias") {
+        const target = optionalOption(parsed, "target"), remove = parsed.options.has("remove");
+        if (Boolean(target) === remove)
+            throw new AppError("usage", "Use exactly one of --target ID or --remove; see dd-flow profiles alias --help", 2, { effect: "no_effect" });
+        mutation = { action, alias: parsed.positional[0], target: target ?? null };
+    }
+    else if (action === "set-default") {
+        const id = parsed.positional[0], clear = parsed.options.has("clear");
+        if (Boolean(id) === clear)
+            throw new AppError("usage", "Select one profile ID or --clear; see dd-flow profiles set-default --help", 2, { effect: "no_effect" });
+        mutation = { action, id: id ?? null };
+    }
+    else
+        throw new AppError("usage", "Unknown profiles command; use dd-flow profiles --help", 2, { effect: "no_effect" });
+    const settings = mutateOperatorProfiles(home, requiredOption(parsed, "expected-revision"), mutation);
+    return { ok: true, action: `profiles_${action}`, effect: "committed", settings };
+}
+/** Lightweight executable ingress; never imports the project/runtime business router. */
+export function runOperatorProfilesCli(args, env, 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);
+        const result = dispatchOperatorProfiles(resolveDdFlowHome(env), route);
+        io.stdout.write(`${JSON.stringify(writeResponseFile(result, output), null, json ? undefined : 2)}\n`);
+        return 0;
+    }
+    catch (error) {
+        const record = errorRecord(error);
+        writePreparationError(io, args, record);
+        return record.exitCode;
+    }
+}

package/dist/cli/output-options.js

@@ -0,0 +1,35 @@
+import { AppError } from "../shared/errors.js";
+/** Shared execution transport grammar. Help resolves before this function. */
+export function parseOutputOptions(args) {
+    const stripped = [];
+    let json = false, progressJsonl = false, responseFile = null;
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        if (arg === "--") {
+            stripped.push(...args.slice(index));
+            break;
+        }
+        if (arg === "--json") {
+            json = true;
+            continue;
+        }
+        if (arg === "--progress-jsonl") {
+            progressJsonl = true;
+            continue;
+        }
+        if (arg === "--response-file" || arg.startsWith("--response-file=")) {
+            if (responseFile !== null)
+                throw new AppError("usage", "--response-file may be supplied only once", 2);
+            const file = arg === "--response-file" ? args[++index] : arg.slice("--response-file=".length);
+            if (!file?.trim() || file.startsWith("--"))
+                throw new AppError("usage", "--response-file requires a path", 2);
+            responseFile = file;
+            continue;
+        }
+        stripped.push(arg);
+    }
+    if (responseFile && !json)
+        throw new AppError("usage", "--response-file requires --json", 2);
+    const hookJsonOnly = stripped[0] === "codex" && stripped[1] === "hook" && stripped[2] === "handle";
+    return { json: json || hookJsonOnly, progressJsonl, args: stripped, hookJsonOnly, responseFile };
+}

package/dist/cli/response-file.js

@@ -0,0 +1,69 @@
+import fs from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+/** Preflight does not create a parent, destination or runtime home. */
+export function prepareResponseDestination(value) {
+    const file = path.resolve(value);
+    try {
+        const inspect = (target) => {
+            try {
+                return fs.lstatSync(target);
+            }
+            catch (error) {
+                if (error.code === "ENOENT")
+                    return null;
+                throw error;
+            }
+        };
+        let parent = path.dirname(file);
+        let parentStat = inspect(parent);
+        while (!parentStat) {
+            const next = path.dirname(parent);
+            if (next === parent)
+                break;
+            parent = next;
+            parentStat = inspect(parent);
+        }
+        const targetStat = inspect(file);
+        if (!parentStat?.isDirectory() || targetStat && !targetStat.isFile())
+            throw new Error();
+    }
+    catch {
+        throw new AppError("response_file_invalid", "Response destination must be a regular file under a directory", 2, { parameter: "response-file", effect: "no_effect" });
+    }
+}
+/** Optional publication failure never changes the accepted operation outcome. */
+export function writeResponseFile(payload, output) {
+    if (!output.responseFile)
+        return payload;
+    const file = path.resolve(output.responseFile), temporary = `${file}.tmp-${randomUUID()}`;
+    const visible = payload && typeof payload === "object" && !Array.isArray(payload) ? { ...payload } : { ok: true, result: payload };
+    let ownsTemporary = false;
+    try {
+        prepareResponseDestination(file);
+        fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+        const fd = fs.openSync(temporary, "wx", 0o600);
+        ownsTemporary = true;
+        try {
+            fs.writeFileSync(fd, `${JSON.stringify(payload, null, 2)}\n`);
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        fs.renameSync(temporary, file);
+    }
+    catch {
+        return { ...visible, response_file: file, response_file_error: "Response publication failed; reconcile the accepted operation before retrying" };
+    }
+    finally {
+        try {
+            if (ownsTemporary && fs.existsSync(temporary))
+                fs.unlinkSync(temporary);
+        }
+        catch { /* Own temporary only; never mask the operation outcome. */ }
+    }
+    delete visible.worker_prompt_markdown;
+    return { ...visible, response_file: file };
+}

package/dist/cli/run-cli.js

@@ -70,6 +70,7 @@ import { vnextStageDirectory } from "../domain/stage-catalog.js";
 import { prepareCommandRoute } from "./command-inputs.js";
 import { parseLifecycleCommand } from "../services/lifecycle-command.js";
 import { dispatchRuntimeProcess, prepareRuntimeProcess } from "./runtime-process.js";
+import { reconcileFlowRunHealth } from "../services/run-health.js";
 import { fenceRuntimeBudget, runtimeBudgetStatus, prepareRuntimeScopeControl, prepareRuntimeScopeFence } from "../services/runtime-budget.js";
 import { stopRuntimeScope } from "../services/runtime-scope-stop.js";
 import { launchRuntimeScopeControl, launchRuntimeScopeResume, prepareRuntimeScopeReconciliation, prepareRuntimeScopeServing, reconcileRuntimeScopeControl, serveRuntimeScopeControl } from "../services/runtime-scope-worker.js";
@@ -505,6 +506,8 @@ function resolveProjectRootBeforeRouting(args, env, deadlineAt) {
 function databaseModeForCommand(args, classification) {
     if (isNativeHookIngress(args))
         return "hook";
+    if (args[0] === "run" && args[1] === "reconcile")
+        return args.includes("--apply") ? "reconcile" : "read_existing";
     if (isRuntimeMaintenance(args))
         return "read_existing";
     const [family, command] = args;
@@ -2474,6 +2477,8 @@ function recoveryResumeInput(parsed) {
     return { projectRoot: requiredOption(parsed, "project-root"), runId: requiredPosition(parsed, 1, "run-id"), recoveryId: requiredOption(parsed, "recovery-id"), daemonId: requiredOption(parsed, "daemon-id"), harness: requiredOption(parsed, "harness"), nativeSessionId: requiredOption(parsed, "native-session-id") };
 }
 function dispatchRun(context, command, parsed, prepared = {}) {
+    if (command === "reconcile")
+        return reconcileFlowRunHealth(context, { runId: parsed.positional[0], projectRoot: optionalOption(parsed, "project-root"), apply: hasOption(parsed, "apply"), noProgressMs: optionalNumber(parsed, "no-progress-ms") });
     if (command === "recovery") {
         const action = requiredPosition(parsed, 0, "recovery action");
         const projectRoot = requiredOption(parsed, "project-root");

package/dist/cli/setup.js

@@ -0,0 +1,147 @@
+import { prepareCommandRoute } from "./command-inputs.js";
+import path from "node:path";
+import { parseOutputOptions } from "./output-options.js";
+import { resolveDdFlowHome } from "../storage/paths.js";
+import { readSetupStatus, installAuthenticatedRelease, readRetainedSetupExecutor, hasDeferredSetupOnboarding, readSetupOnboarding, commitSetupOnboarding } from "../services/setup.js";
+import { readTrustedReleaseProducers, readReleaseBundle } from "../services/release-source.js";
+import { createReleaseCompatibility, installedCatalogVersions } from "../services/release-compatibility.js";
+import { getCliVersionReport } from "../services/build-info.js";
+import { readOperatorProfiles, readProfileCreationIntent } from "../services/operator-profiles.js";
+import { onboardExecutor, selectOnboardingExecutor } from "../services/executor-onboarding.js";
+import { askExecutorChoice } from "./executor-onboarding.js";
+import { requiredOption, optionalOption } from "./argument-values.js";
+import { AppError, errorRecord } from "../shared/errors.js";
+import { hybridDigest } from "../services/hybrid-contracts.js";
+import { prepareResponseDestination, writeResponseFile } from "./response-file.js";
+import { readRegistryRelease } from "../services/release-registry.js";
+import { writePreparationError } from "./error-output.js";
+/** Lightweight global diagnostic ingress; never creates a runtime context. */
+export async function runSetupCli(args, env, io = { stdout: process.stdout, stderr: process.stderr, stdin: process.stdin }) {
+    let json = false;
+    try {
+        const output = parseOutputOptions(args);
+        json = output.json;
+        if (output.responseFile)
+            prepareResponseDestination(output.responseFile);
+        const route = prepareCommandRoute(output.args);
+        const humanProgress = !output.json && !output.progressJsonl;
+        const reportHumanProgress = (message) => {
+            // Diagnostic delivery cannot turn a completed installation into failure.
+            try {
+                io.stderr.write(`setup: ${message}\n`);
+            }
+            catch { /* Best-effort human progress only. */ }
+        };
+        const home = resolveDdFlowHome(env);
+        let result;
+        if (route.key === "setup status")
+            result = { ok: true, action: "setup_status", observed_cli: getCliVersionReport().cli, ...readSetupStatus(home) };
+        else if (route.key === "setup" || route.key === "setup update") {
+            const parsed = route.parsed;
+            const source = optionalOption(parsed, "canon-source"), version = optionalOption(parsed, "canon-version");
+            const registryFile = optionalOption(parsed, "release-registry");
+            if (source && (version || registryFile))
+                throw new AppError("usage", "--canon-source is exclusive with --canon-version and --release-registry; see dd-flow setup --help", 2, { effect: "no_effect" });
+            const channel = (optionalOption(parsed, "channel") ?? "stable");
+            const selection = source ? null : readRegistryRelease(registryFile ?? env.DD_FLOW_RELEASE_REGISTRY ?? path.join(home, "release-registry.json"), channel, version);
+            const profile = optionalOption(parsed, "profile"), skip = parsed.options.has("skip-agent-setup");
+            const intentFile = optionalOption(parsed, "save-profile-intent");
+            if (intentFile && skip)
+                throw new AppError("usage", "--save-profile-intent conflicts with --skip-agent-setup", 2, { effect: "no_effect" });
+            let profileCreation = intentFile ? readProfileCreationIntent(intentFile) : undefined;
+            const stdin = io.stdin ?? process.stdin;
+            const nonInteractive = parsed.options.has("non-interactive") || output.json || output.progressJsonl
+                || !stdin.isTTY || !io.stderr.isTTY;
+            const profileFile = optionalOption(parsed, "profile-file");
+            const requestId = requiredOption(parsed, "request-id");
+            const retained = profile === undefined && profileFile === undefined && !intentFile && !skip ? readRetainedSetupExecutor(home, requestId) : null;
+            if (retained?.profileCreation)
+                profileCreation = retained.profileCreation;
+            const choice = { ...(profile !== undefined ? { profileId: profile } : {}),
+                ...(profileFile !== undefined ? { profileFile } : {}),
+                ...(retained?.executor ? { profile: retained.executor } : profileCreation && profile === undefined && profileFile === undefined ? { profile: profileCreation.profile } : {}),
+                skip: skip || retained !== null && retained.executor === null };
+            let deferred = hasDeferredSetupOnboarding(home, requestId);
+            let selected;
+            if (!deferred) {
+                try {
+                    selected = selectOnboardingExecutor(choice, () => readOperatorProfiles(home), { allowSkip: true });
+                }
+                catch (error) {
+                    if (!(error instanceof AppError) || error.code !== "agent_profile_missing" || nonInteractive
+                        || profile !== undefined || profileFile !== undefined || intentFile || skip)
+                        throw error;
+                    deferred = true;
+                }
+            }
+            else if (profile !== undefined || profileFile !== undefined || intentFile || skip) {
+                // Explicit continuation inputs still fail before downloading or replaying.
+                selected = selectOnboardingExecutor(choice, () => readOperatorProfiles(home), { allowSkip: true });
+            }
+            const observedCli = getCliVersionReport().cli;
+            const compatibility = createReleaseCompatibility({ channel,
+                catalogVersions: installedCatalogVersions, routerVersion: observedCli.version });
+            const producers = readTrustedReleaseProducers(requiredOption(parsed, "trust-file"));
+            const bundle = await readReleaseBundle(source ?? selection.envelope_url, producers, compatibility, {
+                ...(selection ? { expectedVersion: selection.version } : {}),
+                ...((output.progressJsonl || humanProgress) ? { onProgress: (progress) => {
+                        if (output.progressJsonl)
+                            io.stdout.write(`${JSON.stringify({ type: "setup_download_progress", request_id: requestId, ...progress })}\n`);
+                        else if (progress.received_bytes === progress.expected_bytes)
+                            reportHumanProgress(`${progress.artifact} archive received (${progress.received_bytes} bytes); integrity validation follows`);
+                    } } : {})
+            });
+            if (selection && bundle.authenticated.manifest.version !== selection.version)
+                throw new AppError("release_registry", "Authenticated release differs from selected registry version", 1, { reason: "selected_version_mismatch", phase: "release_selection", effect: "no_effect", help: "setup" });
+            const installed = installAuthenticatedRelease(home, { requestId, action: route.key === "setup update" ? "update" : "install",
+                envelope: bundle.envelope, trustedProducers: producers, compatibility, canonArchive: bundle.canonArchive, engineArchive: bundle.engineArchive,
+                ...(deferred ? { deferredOnboarding: true } : { executor: selected.profile, ...(profileCreation ? { profileCreation } : {}) }),
+                ...((output.progressJsonl || humanProgress) ? { onCheckpoint: phase => {
+                        if (output.progressJsonl)
+                            io.stdout.write(`${JSON.stringify({ type: "setup_progress", request_id: requestId, phase })}\n`);
+                        else
+                            reportHumanProgress({ prepared: "verified release request retained", canon_cached: "canon cache verified", engine_cached: "engine cache verified",
+                                profiles_saved: "profile settings saved", committed: "installation committed; runtime qualification remains unknown" }[phase]);
+                    } } : {}) });
+            if (humanProgress && installed.replayed)
+                reportHumanProgress("exact request replay verified; retained selection was not reactivated");
+            if (deferred) {
+                const saved = readSetupOnboarding(home, requestId);
+                const explicit = profile !== undefined || profileFile !== undefined || intentFile !== undefined || skip;
+                const deferredChoice = saved && !explicit ? { ...(saved.executor ? { profile: saved.executor } : { skip: true }),
+                    ...(saved.profileCreation ? { profileCreation: saved.profileCreation } : {}) } : choice;
+                try {
+                    selected ??= await onboardExecutor(deferredChoice, () => readOperatorProfiles(home), { allowSkip: true, nonInteractive }, settings => askExecutorChoice(settings, { stdin, stderr: io.stderr }));
+                    const consent = commitSetupOnboarding(home, requestId, { executor: selected.profile,
+                        ...(profileCreation ?? selected.profileCreation ? { profileCreation: profileCreation ?? selected.profileCreation } : {}) });
+                    installed.executor = consent.executor;
+                    if (humanProgress)
+                        reportHumanProgress("executor onboarding committed after installation");
+                }
+                catch (error) {
+                    if (error instanceof AppError) {
+                        error.details.installation = "committed";
+                        error.details.request_id = requestId;
+                        error.details.next_action = "Replay the same setup request to resume executor onboarding; installation remains retained";
+                    }
+                    throw error;
+                }
+            }
+            result = { ...installed, action: route.key === "setup update" ? "setup_update" : "setup_install", observed_cli: observedCli,
+                executor: installed.executor ? { profile_id: installed.executor.id, revision: hybridDigest(installed.executor), readiness: "unknown_requires_qualification" } : { profile_id: null, readiness: "not_configured" },
+                ...readSetupStatus(home) };
+        }
+        else
+            throw new AppError("usage", "Unknown setup command; see dd-flow setup --help", 2, { effect: "no_effect" });
+        io.stdout.write(`${JSON.stringify(writeResponseFile(result, output), null, json ? undefined : 2)}\n`);
+        return 0;
+    }
+    catch (error) {
+        const record = errorRecord(error);
+        writePreparationError(io, args, record);
+        if (!json && error instanceof AppError && error.details.installation === "committed") {
+            io.stderr.write("setup: installation remains committed; replay the same request to resume executor onboarding\n");
+        }
+        return record.exitCode;
+    }
+}

package/dist/services/cli-operation-classifier.js

@@ -6,6 +6,8 @@ export function classifyCliOperation(args, env = process.env) {
     if (isMbUpgradeMode(args, env)) {
         return { mode: "mb_upgrade", operation, family, command, action };
     }
+    if (family === "run" && command === "reconcile" && !args.includes("--apply"))
+        return { mode: "read_only_diagnostics", operation, family, command, action };
     if (isRouterNative(args)) {
         return { mode: "router_native", operation, family, command, action };
     }
@@ -85,6 +87,8 @@ function isRouterNative(args) {
         return true;
     if (["engine", "version", "schema"].includes(first))
         return true;
+    if (first === "run" && args[1] === "reconcile")
+        return true;
     if (first === "storage" && args[1] === "migrate-writer")
         return true;
     return (first === "codex" && args[1] === "hook" && args[2] === "handle")

package/dist/services/cli-upgrade-allowlist.js

@@ -0,0 +1,27 @@
+import { parseCommandArgs } from "./lifecycle-command.js";
+/** Syntax eligibility only. Storage/project/RUN authority is checked separately. */
+export function isUpgradeAllowlisted(args) {
+    const parsed = parseCommandArgs(args), [family, command] = parsed.positional;
+    const option = (name) => {
+        const value = parsed.options.get(name)?.at(-1);
+        return value && value !== "__dd_flow_flag__" ? value : null;
+    };
+    if (family === "status")
+        return true;
+    if (family === "engine" && command === "resolve")
+        return true;
+    if (family === "migration" && ["impact", "plan", "report", "verify", "apply"].includes(command ?? ""))
+        return true;
+    if (family === "memory" && command === "permissions" && parsed.positional[2] === "preflight")
+        return true;
+    if (family === "run" && command === "start")
+        return option("flow-kind") === "mb-upgrade";
+    const bound = Boolean(option("run") || parsed.positional.some(value => value.startsWith("RUN-")));
+    if (family === "stage" && ["start", "pause", "resume", "finish"].includes(command ?? ""))
+        return bound;
+    if (family === "session" && ["status", "register", "stop", "usage"].includes(command ?? ""))
+        return bound;
+    if (family === "dashboard" && ["data", "render", "refresh", "open"].includes(command ?? ""))
+        return true;
+    return false;
+}

package/dist/services/discovery/agy-discovery.js

@@ -0,0 +1,2 @@
+import { discoverExecutable } from "./static.js";
+export const discoverAgy = (input) => discoverExecutable("agy", ["agy"], input);

package/dist/services/discovery/codex-discovery.js

@@ -0,0 +1,2 @@
+import { discoverExecutable } from "./static.js";
+export const discoverCodex = (input) => discoverExecutable("codex", ["codex"], input);

package/dist/services/discovery/droid-discovery.js

@@ -0,0 +1,2 @@
+import { discoverExecutable } from "./static.js";
+export const discoverDroid = (input) => discoverExecutable("droid", ["droid"], input);

package/dist/services/discovery/grok-discovery.js

@@ -0,0 +1,2 @@
+import { discoverExecutable } from "./static.js";
+export const discoverGrok = (input) => discoverExecutable("grok", ["grok"], input);

package/dist/services/discovery/opencode-discovery.js

@@ -0,0 +1,2 @@
+import { discoverExecutable } from "./static.js";
+export const discoverOpenCode = (input) => discoverExecutable("opencode", ["opencode"], input);