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

package/dist/cli/runtime-maintenance-diagnostics.js

@@ -0,0 +1,46 @@
+import { channel } from "node:diagnostics_channel";
+import { AsyncLocalStorage } from "node:async_hooks";
+const requests = new AsyncLocalStorage();
+export function isRuntimeMaintenance(args) {
+    return args[0] === "runtime" && args[1] === "process" && ["register", "heartbeat", "confirm", "admission", "finish", "check-admission", "release-turn", "status"].includes(args[2] ?? "");
+}
+export const withMaintenanceDiagnosticScope = (action) => requests.run(Symbol(), action);
+/** Request-local, bounded evidence; never command bytes, paths or lease tokens. */
+export function runtimeMaintenanceDiagnostics(args, deadline, write) {
+    const started = performance.now();
+    const request = requests.getStore();
+    const option = (name) => { const at = args.indexOf(`--${name}`); return at < 0 ? undefined : args[at + 1]; };
+    const safe = (value) => typeof value === "string" && /^[A-Za-z0-9:._-]{1,128}$/.test(value) ? value : undefined;
+    const identity = { action: safe(args[2]), process_id: safe(option("id")), operation_id: safe(option("operation-id") ?? option("operation")), native_dispatch_started: false };
+    let previous = "", count = 0, committed = false;
+    const phase = (name, details = {}) => {
+        const key = `${details.store_kind ?? ""}:${name}`;
+        if (key === previous || count >= 64)
+            return;
+        previous = key;
+        count++;
+        write(`${JSON.stringify({ kind: "process_maintenance_phase", ...identity, phase: name, elapsed_ms: Math.round(performance.now() - started), ...(deadline !== undefined ? { remaining_ms: Math.max(0, deadline - Date.now()) } : {}), ...details, ...(["ack", "failed"].includes(name) ? { maintenance_effect: committed ? "committed" : name === "ack" ? "no_mutation_observed" : "unknown" } : {}) })}\n`);
+    };
+    const timing = channel("dd-flow.sqlite.ingress");
+    const log = (message) => {
+        if (requests.getStore() !== request)
+            return;
+        const record = message;
+        if (record.phase === "committed" && record.store_kind === "resource")
+            committed = true;
+        phase(record.phase, { ...(record.store_kind ? { store_kind: record.store_kind } : {}) });
+    };
+    timing.subscribe(log);
+    phase("request", { maintenance_effect: "unknown" });
+    return { phase, failure: (error) => {
+            let current = error;
+            let sqlite;
+            for (let depth = 0; current && depth < 8; depth++) {
+                sqlite = current.errcode ?? current.sqlite_extended_code ?? current.details?.sqlite_extended_code;
+                if (Number.isSafeInteger(sqlite))
+                    break;
+                current = (current.cause ?? current.details?.cause);
+            }
+            phase("failed", { ...(Number.isSafeInteger(sqlite) ? { sqlite_extended_code: sqlite } : {}) });
+        }, close: () => timing.unsubscribe(log) };
+}

package/dist/cli/runtime-maintenance-ingress.js

@@ -0,0 +1,52 @@
+import { isRuntimeMaintenance, runtimeMaintenanceDiagnostics, withMaintenanceDiagnosticScope } from "./runtime-maintenance-diagnostics.js";
+import { errorRecord, isAppError } from "../shared/errors.js";
+import { writeJson } from "../shared/json.js";
+/** Only the already-selected engine's internal JSON transport takes this path.
+ * Operator calls and richer output formats retain the ordinary engine router. */
+export function isRuntimeMaintenanceIngress(args, env) {
+    return env.DD_FLOW_ENGINE_MODE === "1" && Number.isFinite(Number(env.DD_FLOW_HOOK_DEADLINE_AT))
+        && Number(env.DD_FLOW_HOOK_DEADLINE_AT) > 0 && args.includes("--json")
+        && isRuntimeMaintenance(args)
+        && !args.some(arg => ["--help", "-h", "--progress-jsonl", "--response-file"].includes(arg) || arg.startsWith("--response-file="));
+}
+export async function runRuntimeMaintenanceIngress(args, env = process.env, io = { stdout: process.stdout, stderr: process.stderr }) {
+    return withMaintenanceDiagnosticScope(async () => {
+        const deadline = Number(env.DD_FLOW_HOOK_DEADLINE_AT);
+        // Publish evidence before loading even the maintenance service graph.
+        const diagnostics = runtimeMaintenanceDiagnostics(args, deadline, line => io.stderr.write(line));
+        let context;
+        try {
+            const [{ createContext }, { prepareCommandRoute }, { resolveCommandProjectRoot, resolveCommandPaths }, processCommands, { preflightCliCompatibility }] = await Promise.all([
+                import("../runtime/context.js"), import("./command-inputs.js"), import("../services/command-context.js"), import("./runtime-process.js"),
+                import("../services/compatibility-preflight.js")
+            ]);
+            diagnostics.phase("imports_ready");
+            const invocation = args.filter(arg => arg !== "--json");
+            const options = { databaseDeadlineAt: deadline, resourceDatabaseMode: args[2] === "register" ? "initialize" : args[2] === "status" ? "read_existing" : "prepared_existing" };
+            context = createContext({ ...env, DD_FLOW_INVOCATION_READONLY: args[2] === "status" ? "1" : undefined }, "read_existing", undefined, options);
+            const root = resolveCommandProjectRoot(context, invocation, null);
+            const routedArgs = resolveCommandPaths(context, invocation, root);
+            const route = prepareCommandRoute(routedArgs);
+            const prepared = processCommands.prepareRuntimeProcess(context, route.key, route.parsed);
+            // Preserve the common compatibility gate; this is not a second dispatch
+            // implementation or permission granted by the ingress predicate.
+            await preflightCliCompatibility(context, routedArgs, env, root);
+            const result = await processCommands.dispatchRuntimeProcess(context, args[2], route.parsed, prepared);
+            const receipt = result;
+            const expiry = receipt?.lease_expires_at ?? receipt?.process?.lease_expires_at;
+            diagnostics.phase("ack", { ...(expiry && Number.isFinite(Date.parse(expiry)) ? { lease_expires_at: expiry } : {}) });
+            writeJson(io.stdout, result);
+            return 0;
+        }
+        catch (error) {
+            diagnostics.failure(error);
+            const record = errorRecord(error);
+            writeJson(io.stderr, { ok: false, error: { ...record, details: { ...(!isAppError(error) ? { effect: "unknown" } : {}), ...record.details } } });
+            return record.exitCode;
+        }
+        finally {
+            context?.db.close?.();
+            diagnostics.close();
+        }
+    });
+}

package/dist/cli/runtime-process.js

@@ -0,0 +1,153 @@
+import { AppError } from "../shared/errors.js";
+import { requiredOption, optionalOption, optionalNumber, optionalPositiveNumber } from "./argument-values.js";
+import { prepareError } from "./input-preparation.js";
+import { recoveryGuard, assertRunMutationAllowed } from "../services/run-recovery-guard.js";
+import { recoveryRuntimeAdmission } from "../services/run-recovery-guard.js";
+import { prepareManagedProcessRegistration, prepareManagedProcessConfirmation, prepareManagedProcessHeartbeat, prepareManagedProcessFinish, prepareManagedProcessStopOperation, prepareManagedProcessReconcile, stopManagedProcess, confirmManagedProcess, finishManagedProcess, renewManagedProcess, assertManagedProcessAdmission, managedProcessRuntimeHome, managedProcessStatus, processIsAlive, reconcileExpiredManagedProcesses, registerManagedProcess } from "../services/managed-processes.js";
+import { admitRuntimeCheck, parseRuntimeBudget, reserveProviderTurn, releaseProviderTurns, prepareProviderTurnRelease } from "../services/runtime-budget.js";
+import { managedProcessBinding, resourceHome } from "../services/managed-processes.js";
+function runtimeProcessStopInput(parsed) {
+    const graceMs = optionalNumber(parsed, "grace-ms");
+    return { id: requiredOption(parsed, "id"), leaseToken: requiredOption(parsed, "lease-token"), ...(graceMs !== undefined ? { graceMs } : {}) };
+}
+function runtimeProcessRegistrationInput(context, parsed) {
+    const leaseMs = optionalPositiveNumber(parsed, "lease-ms", true);
+    const budget = parseRuntimeBudget(optionalOption(parsed, "budget-json"));
+    const kind = requiredOption(parsed, "kind");
+    const projectId = optionalOption(parsed, "project-id") ?? null, runId = optionalOption(parsed, "run") ?? null;
+    const guard = projectId && runId ? recoveryGuard(context, projectId, runId) : null;
+    const run = projectId && runId ? context.db.get("SELECT id FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]) : null;
+    return {
+        ...(optionalOption(parsed, "id") ? { id: optionalOption(parsed, "id") } : {}), kind, ownerId: requiredOption(parsed, "owner"), uniqueActiveOperation: kind === "eval-observer",
+        ...(kind === "eval-observer" ? { pid: optionalPositiveNumber(parsed, "pid", true) ?? 0, ...(optionalPositiveNumber(parsed, "process-group-id", true) ? { processGroupId: optionalPositiveNumber(parsed, "process-group-id", true) } : {}) } : {}),
+        ownerPid: optionalPositiveNumber(parsed, "owner-pid", true), projectId, runId,
+        workId: optionalOption(parsed, "work") ?? null, checkId: optionalOption(parsed, "check") ?? null,
+        operationId: optionalOption(parsed, "operation") ?? null, stdoutPath: optionalOption(parsed, "stdout") ?? null,
+        stderrPath: optionalOption(parsed, "stderr") ?? null, ...(leaseMs !== undefined ? { leaseMs } : {}),
+        metadata: { ...(budget ? { budget, harness: optionalOption(parsed, "harness") ?? null } : {}), ...(projectId && runId ? { run_generation: guard?.generation ?? 0, run_admitted: Boolean(run) && !["draining", "sealed", "resuming"].includes(guard?.status ?? "") } : {}), ...(optionalOption(parsed, "dispatch-barrier") ? { dispatch_barrier: optionalOption(parsed, "dispatch-barrier") } : {}), ...(optionalOption(parsed, "role") ? { role: optionalOption(parsed, "role") } : {}), ...(optionalOption(parsed, "state-dir") ? { state_dir: optionalOption(parsed, "state-dir") } : {}), ...(optionalOption(parsed, "adapter-executable") ? { adapter_executable: optionalOption(parsed, "adapter-executable") } : {}) }
+    };
+}
+function runtimeProcessConfirmationInput(parsed) {
+    const leaseMs = optionalPositiveNumber(parsed, "lease-ms", true), processGroupId = optionalPositiveNumber(parsed, "process-group-id", true);
+    return { id: requiredOption(parsed, "id"), leaseToken: requiredOption(parsed, "lease-token"), ownerPid: optionalPositiveNumber(parsed, "owner-pid", true), pid: optionalPositiveNumber(parsed, "pid", true) ?? 0, ...(processGroupId !== undefined ? { processGroupId } : {}), ...(leaseMs !== undefined ? { leaseMs } : {}) };
+}
+function runtimeProcessHeartbeatInput(parsed) {
+    const leaseMs = optionalPositiveNumber(parsed, "lease-ms", true);
+    return { id: requiredOption(parsed, "id"), leaseToken: requiredOption(parsed, "lease-token"), ...(leaseMs !== undefined ? { leaseMs } : {}) };
+}
+function runtimeProcessFinishInput(parsed) {
+    const state = requiredOption(parsed, "state");
+    if (state !== "stopped" && state !== "failed")
+        throw new AppError("validation", "--state must be stopped or failed", 2);
+    return { id: requiredOption(parsed, "id"), leaseToken: requiredOption(parsed, "lease-token"), state, reason: optionalOption(parsed, "reason") ?? null };
+}
+export function prepareRuntimeProcess(context, key, parsed) {
+    try {
+        return prepareRuntimeProcessInput(context, key, parsed);
+    }
+    catch (error) {
+        return prepareError(error);
+    }
+}
+function prepareRuntimeProcessInput(context, key, parsed) {
+    const prepared = {};
+    if (key === "runtime process register") {
+        prepareManagedProcessRegistration(context, runtimeProcessRegistrationInput(context, parsed));
+    }
+    if (key === "runtime process heartbeat")
+        prepareManagedProcessHeartbeat(context, runtimeProcessHeartbeatInput(parsed));
+    if (key === "runtime process finish")
+        prepareManagedProcessFinish(context, runtimeProcessFinishInput(parsed));
+    if (key === "runtime process confirm")
+        prepareManagedProcessConfirmation(context, runtimeProcessConfirmationInput(parsed));
+    if (key === "runtime process stop")
+        prepareManagedProcessStopOperation(context, runtimeProcessStopInput(parsed));
+    if (key === "runtime process reconcile")
+        prepareManagedProcessReconcile(requiredOption(parsed, "owner"), optionalNumber(parsed, "grace-ms"));
+    if (key === "runtime process release-turn") {
+        prepared.providerTurnRelease = prepareProviderTurnRelease({ daemonId: requiredOption(parsed, "daemon-id"), operationId: optionalOption(parsed, "operation-id"), observationFile: optionalOption(parsed, "observation-file") });
+    }
+    return prepared;
+}
+export async function dispatchRuntimeProcess(context, action, parsed, prepared = {}) {
+    if (action === "check-admission")
+        return { ok: true, ...admitRuntimeCheck(context, requiredOption(parsed, "id"), requiredOption(parsed, "lease-token")) };
+    if (action === "stop")
+        return { ok: true, process: await stopManagedProcess(context, runtimeProcessStopInput(parsed)) };
+    if (action === "register") {
+        const process = registerManagedProcess(context, runtimeProcessRegistrationInput(context, parsed));
+        return { ok: true, process };
+    }
+    if (action === "confirm")
+        return { ok: true, process: confirmManagedProcess(context, runtimeProcessConfirmationInput(parsed)) };
+    if (action === "heartbeat") {
+        const hash = optionalOption(parsed, "registration-sha256");
+        if (hash) {
+            const record = managedProcessStatus(context).find(value => value.id === requiredOption(parsed, "id"));
+            if (!/^[a-f0-9]{64}$/.test(hash) || !record || managedProcessBinding(record, resourceHome(context)).registration_sha256 !== hash)
+                throw new AppError("process_maintenance_receipt_invalid", "Heartbeat registration changed", 1);
+        }
+        const receipt = renewManagedProcess(context, runtimeProcessHeartbeatInput(parsed));
+        return { ...receipt, ok: receipt.owned };
+    }
+    if (action === "admission") {
+        const [{ controllerHitlAdmission }, { assertCapacityOwnerAdmission }] = await Promise.all([import("../services/run-controller-adapter.js"), import("../services/provider-capacity.js")]);
+        const record = managedProcessStatus(context).find(process => process.id === requiredOption(parsed, "id"));
+        if (!record || record.lease_token !== requiredOption(parsed, "lease-token") || record.owner_id !== requiredOption(parsed, "owner") || record.state !== "running" || !record.pid || !record.pid_started_at || !processIsAlive(record))
+            throw new AppError("process_ownership_unknown", "Productive dispatch requires its current confirmed runtime owner", 1);
+        assertManagedProcessAdmission(context, record);
+        const metadata = JSON.parse(record.metadata_json);
+        if (metadata.state_dir !== requiredOption(parsed, "state-dir"))
+            throw new AppError("process_ownership_unknown", "Runtime admission belongs to another state directory", 1);
+        if (record.project_id && record.run_id) {
+            if (managedProcessRuntimeHome(record, context) !== context.ddFlowHome)
+                throw new AppError("process_runtime_scope_mismatch", "Runtime admission belongs to another or unproven flow home", 1);
+            const recovering = recoveryRuntimeAdmission(context, record, { stateDir: requiredOption(parsed, "state-dir"), daemonId: optionalOption(parsed, "daemon-id"), operationId: optionalOption(parsed, "operation-id"), operation: optionalOption(parsed, "operation"), nativeSessionId: optionalOption(parsed, "native-session-id"), promptSha256: optionalOption(parsed, "prompt-sha256") });
+            if (!recovering) {
+                if (metadata.run_admitted !== true || !Number.isSafeInteger(metadata.run_generation))
+                    throw new AppError("run_recovery_guarded", "Runtime was not admitted before the RUN fence; reconcile its launch", 1);
+                assertRunMutationAllowed(context, record.project_id, record.run_id, metadata.run_generation);
+            }
+            const run = context.db.get("SELECT status FROM runs WHERE project_id = ? AND id = ?", [record.project_id, record.run_id]);
+            const retainedHitlPrompt = recovering && ["paused", "waiting_for_user"].includes(run?.status ?? "") && ["session.prompt", "session.resume"].includes(optionalOption(parsed, "operation") ?? "") && context.db.get("SELECT 1 FROM run_recovery_bindings b JOIN run_recovery_guards g ON g.recovery_id = b.recovery_id WHERE g.project_id = ? AND g.run_id = ? AND g.generation = ? AND b.daemon_id = ? AND b.provider_session_id = ?", [record.project_id, record.run_id, metadata.run_generation, optionalOption(parsed, "daemon-id"), optionalOption(parsed, "native-session-id")]);
+            const acceptedHitlPrompt = ["paused", "waiting_for_user"].includes(run?.status ?? "") && controllerHitlAdmission(context, record, { stateDir: requiredOption(parsed, "state-dir"), operationId: optionalOption(parsed, "operation-id"), operation: optionalOption(parsed, "operation"), nativeSessionId: optionalOption(parsed, "native-session-id"), promptSha256: optionalOption(parsed, "prompt-sha256") });
+            if (!run || run.status !== "running" && !retainedHitlPrompt && !acceptedHitlPrompt && !["judge", "probe"].includes(metadata.role ?? ""))
+                throw new AppError("invalid_run_state", "Subject dispatch requires a running RUN or its retained recovery/HITL prompt", 1);
+            if (!recovering)
+                assertCapacityOwnerAdmission(context, record, optionalOption(parsed, "operation-id"), { nativeSessionId: optionalOption(parsed, "native-session-id"), promptSha256: optionalOption(parsed, "prompt-sha256") });
+        }
+        const budget = reserveProviderTurn(context, record, { operationId: optionalOption(parsed, "operation-id") ?? "", operation: optionalOption(parsed, "operation") ?? "", sessionId: optionalOption(parsed, "native-session-id"), daemonId: optionalOption(parsed, "daemon-id"), promptSha256: optionalOption(parsed, "prompt-sha256") });
+        return { ok: true, ...budget, process_id: record.id, generation: metadata.run_generation ?? null };
+    }
+    if (action === "release-turn") {
+        const record = managedProcessStatus(context).find(process => process.id === requiredOption(parsed, "id"));
+        if (!record || record.lease_token !== requiredOption(parsed, "lease-token") || record.owner_id !== requiredOption(parsed, "owner") || managedProcessRuntimeHome(record, context) !== context.ddFlowHome)
+            throw new AppError("process_ownership_unknown", "Budget release requires its retained physical owner", 1);
+        return releaseProviderTurns(context, record, { daemonId: requiredOption(parsed, "daemon-id"), operationId: optionalOption(parsed, "operation-id"), observationFile: optionalOption(parsed, "observation-file") }, prepared.providerTurnRelease);
+    }
+    if (action === "finish")
+        return { ok: finishManagedProcess(context, runtimeProcessFinishInput(parsed)) };
+    if (action === "status") {
+        const id = optionalOption(parsed, "id"), token = optionalOption(parsed, "lease-token"), hash = optionalOption(parsed, "registration-sha256");
+        if (!id && !token && !hash)
+            return { ok: true, processes: managedProcessStatus(context) };
+        if (!id || !token || !hash || !/^[a-f0-9]{64}$/.test(hash))
+            throw new AppError("usage", "Exact status requires id, lease-token and registration-sha256", 2);
+        const record = managedProcessStatus(context).find(value => value.id === id);
+        if (!record || record.lease_token !== token || managedProcessBinding(record, resourceHome(context)).registration_sha256 !== hash || record.state !== "running" || !processIsAlive(record))
+            throw new AppError("process_maintenance_receipt_invalid", "Readback binding or physical owner changed", 1);
+        assertManagedProcessAdmission(context, record);
+        const metadata = JSON.parse(record.metadata_json);
+        if (record.project_id && record.run_id) {
+            if (metadata.run_admitted !== true || !Number.isSafeInteger(metadata.run_generation))
+                throw new AppError("run_recovery_guarded", "Readback has no admitted generation", 1);
+            assertRunMutationAllowed(context, record.project_id, record.run_id, metadata.run_generation);
+            if (managedProcessRuntimeHome(record, context) !== context.ddFlowHome)
+                throw new AppError("process_runtime_scope_mismatch", "Readback belongs to another engine home", 1);
+        }
+        return { ok: true, process_id: id, lease_expires_at: record.lease_expires_at, registration_sha256: hash, readback: true };
+    }
+    if (action === "reconcile")
+        return { ok: true, processes: await reconcileExpiredManagedProcesses(context, requiredOption(parsed, "owner"), optionalNumber(parsed, "grace-ms")) };
+    throw new AppError("usage", "Usage: dd-flow runtime process <start|stop|register|confirm|heartbeat|admission|finish|status|reconcile>", 2);
+}

package/dist/cli/setup.js

@@ -0,0 +1,150 @@
+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";
+import { publishSetup } from "../harness-runtime/lib/setup-progress.mjs";
+/** 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 } : {}) }),
+                onCheckpoint: phase => {
+                    publishSetup("dependency_check_completed", `release-setup:${phase}`);
+                    if (output.progressJsonl)
+                        io.stdout.write(`${JSON.stringify({ type: "setup_progress", request_id: requestId, phase })}\n`);
+                    else if (humanProgress)
+                        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, request_installation: installed.installation,
+                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/cli.js

@@ -1,4 +1,105 @@
 #!/usr/bin/env node
-import { runCli } from "./cli/run-cli.js";
-const exitCode = await runCli(process.argv.slice(2));
+import { isNativeHookIngress } from "./cli/native-hook-ingress.js";
+import { isRuntimeMaintenanceIngress, runRuntimeMaintenanceIngress } from "./cli/runtime-maintenance-ingress.js";
+import { resolveHelp } from "./cli/help.js";
+import { errorRecord } from "./shared/errors.js";
+import { writePreparationError } from "./cli/error-output.js";
+import { publishSetup } from './harness-runtime/lib/setup-progress.mjs';
+const args = process.argv.slice(2);
+let help;
+try {
+    help = resolveHelp(args);
+}
+catch (error) {
+    const record = errorRecord(error);
+    writePreparationError({ stderr: process.stderr }, args, record);
+    process.exit(record.exitCode);
+}
+if (help) {
+    process.stdout.write(`${help.json ? JSON.stringify(help.data) : help.text}\n`);
+    process.exit(0);
+}
+if (args[0] === "completion") {
+    const { runCompletionCli } = await import("./cli/completion-cli.js");
+    process.exit(runCompletionCli(args));
+}
+if (args[0] === "profiles") {
+    const { runOperatorProfilesCli } = await import("./cli/operator-profiles.js");
+    process.exit(runOperatorProfilesCli(args, process.env));
+}
+if (args[0] === "setup") {
+    const { runSetupCli } = await import("./cli/setup.js");
+    process.exit(await runSetupCli(args, process.env));
+}
+if (args[0] === "harnesses") {
+    const { runHarnessesCli } = await import("./cli/harnesses.js");
+    process.exit(await runHarnessesCli(args, process.env));
+}
+if (args[0] === "models") {
+    const { runModelsCli } = await import("./cli/models.js");
+    process.exit(runModelsCli(args));
+}
+if (args[0] === "flow" && ["list", "show"].includes(args[1] ?? "")) {
+    const { runFlowCatalogCli } = await import("./cli/flows.js");
+    process.exit(runFlowCatalogCli(args));
+}
+if (args[0] === "init" || args[0] === "flow" && args[1] === "mb-init") {
+    publishSetup('ingress_entered');
+    const { runMemoryInitCli } = await import("./cli/memory-init.js");
+    publishSetup('imports_ready');
+    process.exit(await runMemoryInitCli(args, process.env));
+}
+if (args[0] === "upgrade" || args[0] === "flow" && args[1] === "mb-upgrade") {
+    const { runMemoryUpgradeCli } = await import("./cli/memory-upgrade.js");
+    process.exit(await runMemoryUpgradeCli(args, process.env));
+}
+if (args[0] === "review" || args[0] === "flow" && ["mb-audit", "project-review", "mb-distill", "review-fix"].includes(args[1] ?? "")) {
+    publishSetup('ingress_entered');
+    const { runDiagnosticCli } = await import("./cli/diagnostic.js");
+    publishSetup('imports_ready');
+    process.exit(await runDiagnosticCli(args, process.env));
+}
+if (args[0] === "flow" && args[1] === "mb-fix") {
+    publishSetup('ingress_entered');
+    const { runMemoryFixCli } = await import("./cli/memory-fix.js");
+    publishSetup('imports_ready');
+    process.exit(await runMemoryFixCli(args, process.env));
+}
+if (args[0] === "flow" && args[1] === "interactive") {
+    const { runInteractiveCli } = await import("./cli/interactive.js");
+    process.exit(await runInteractiveCli(args, process.env));
+}
+if (args[0] === "flow" && ["release", "deploy", "publish"].includes(args[1] ?? "")) {
+    const { runDeliveryCli } = await import("./cli/delivery.js");
+    process.exit(await runDeliveryCli(args, process.env));
+}
+if (args.slice(0, 3).join(" ") === "runtime storage admit") {
+    const { runMemoryStorageAdmissionCli } = await import("./cli/memory-storage-admission.js");
+    process.exit(runMemoryStorageAdmissionCli(args));
+}
+if (args.slice(0, 3).join(" ") === "runtime storage qualify") {
+    const { runMemoryStorageQualificationCli } = await import("./cli/memory-storage-qualification.js");
+    process.exit(runMemoryStorageQualificationCli(args));
+}
+if (args.slice(0, 3).join(" ") === "runtime storage transition") {
+    const { runMemoryStorageTransitionCli } = await import("./cli/memory-storage-transition.js");
+    process.exit(runMemoryStorageTransitionCli(args));
+}
+if (args.slice(0, 3).join(" ") === "runtime flow admit") {
+    const { runMemoryFlowAdmissionCli } = await import("./cli/memory-flow-admission.js");
+    process.exit(await runMemoryFlowAdmissionCli(args));
+}
+const codexHook = args.slice(0, 3).join(" ") === "codex hook handle";
+const exitCode = isRuntimeMaintenanceIngress(args, process.env)
+    ? await runRuntimeMaintenanceIngress(args)
+    : codexHook
+        ? await (await import("./cli/hook-ingress.js")).runHookIngress(args)
+        : isNativeHookIngress(args)
+            ? await (await import("./cli/native-hook-ingress.js")).runNativeHookIngress(args)
+            : await (async () => {
+                publishSetup('ingress_entered');
+                const cli = await import('./cli/run-cli.js');
+                publishSetup('imports_ready');
+                return await cli.runCli(args);
+            })();
 process.exitCode = exitCode;

package/dist/domain/delivery-flows.js

@@ -0,0 +1,8 @@
+export const deliveryFlowStages = {
+    release: ["preflight", "version-decision", "prepare", "verify", "publish", "finish"],
+    deploy: ["preflight", "target-decision", "prepare", "deploy", "verify", "finish"],
+    publish: ["preflight", "target-decision", "prepare", "verify", "publish", "finish"]
+};
+export function isDeliveryFlow(value) {
+    return typeof value === "string" && Object.hasOwn(deliveryFlowStages, value);
+}

package/dist/domain/diagnostic-aspects.js

@@ -0,0 +1,103 @@
+/** Registered baseline coverage; applicability remains agent-owned. */
+export const diagnosticAspects = {
+    "mb-audit": [
+        {
+            "id": "01",
+            "question": "Structure, indexes and reachability of active memory"
+        },
+        {
+            "id": "02",
+            "question": "Links, frontmatter and durable traceability"
+        },
+        {
+            "id": "03",
+            "question": "Source of truth, duplicates, freshness and factual contradictions"
+        },
+        {
+            "id": "04",
+            "question": "Delivery docs, epics/features, protocols and verification matrices"
+        },
+        {
+            "id": "05",
+            "question": "System boundaries, C4, ADRs and contracts"
+        },
+        {
+            "id": "06",
+            "question": "Scenarios, fixtures, evidence and runners"
+        },
+        {
+            "id": "07",
+            "question": "UI contracts and user guides"
+        },
+        {
+            "id": "08",
+            "question": "Engineering standards and code contracts"
+        },
+        {
+            "id": "09",
+            "question": "Operations, release policy and active named deferrals"
+        },
+        {
+            "id": "10",
+            "question": "Memory lifecycle, archives and durable promotion"
+        },
+        {
+            "id": "11",
+            "question": "Code-to-memory traceability"
+        },
+        {
+            "id": "12",
+            "question": "Project agent skills, prompts and execution guidance"
+        }
+    ],
+    "project-review": [
+        {
+            "id": "structure_navigation_review",
+            "question": "Can readers locate system truth and delivery evidence?"
+        },
+        {
+            "id": "feature_epic_layer_review",
+            "question": "Are durable capabilities and delivery layers coherent?"
+        },
+        {
+            "id": "spec_conformance_review",
+            "question": "Does actual project behavior conform to its normative specs?"
+        },
+        {
+            "id": "architecture_harmonization_review",
+            "question": "Are architecture and boundaries coherent top-down?"
+        },
+        {
+            "id": "adr_decision_review",
+            "question": "Are significant decisions, alternatives and consequences recorded?"
+        },
+        {
+            "id": "scenario_evidence_review",
+            "question": "Do actual scenarios, fixtures, checks and evidence cover capabilities?"
+        },
+        {
+            "id": "contract_traceability_review",
+            "question": "Are public contracts traced through implementation and tests?"
+        },
+        {
+            "id": "frontmatter_crosslink_review",
+            "question": "Are metadata and cross-links factual and current?"
+        },
+        {
+            "id": "engineering_standards_review",
+            "question": "Does actual code follow applicable engineering standards?"
+        },
+        {
+            "id": "operations_policy_review",
+            "question": "Are applicable Git, environment and delivery policies followed?"
+        },
+        {
+            "id": "protocol_delivery_trace_review",
+            "question": "Do protocols and RUNs factually establish delivery and closure?"
+        },
+        {
+            "id": "def_followup_review",
+            "question": "Are active DEFs visible, deduplicated and bound to future gates?"
+        }
+    ]
+};

package/dist/domain/diagnostic-flows.js

@@ -0,0 +1,8 @@
+/** Only the accepted E5 read-only slice, not a registry of future workflows. */
+export const diagnosticFlowStages = Object.freeze({
+    "mb-audit": ["preflight", "audit", "review", "report"],
+    "project-review": ["preflight", "analyze", "review", "report"]
+});
+export function isDiagnosticFlow(id) {
+    return typeof id === "string" && Object.hasOwn(diagnosticFlowStages, id);
+}