@deksden-com/dd-flow-cli 0.9.0-beta.14 → 0.9.0-beta.140

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,149 @@
+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, 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,73 @@
 #!/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.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 flow admit") {
+    const { runMemoryFlowAdmissionCli } = await import("./cli/memory-flow-admission.js");
+    process.exit(await runMemoryFlowAdmissionCli(args));
+}
+const managedHook = Boolean(process.env.DD_FLOW_CODEX_STATE_DIR) && args.slice(0, 3).join(" ") === "codex hook handle";
+const exitCode = isRuntimeMaintenanceIngress(args, process.env)
+    ? await runRuntimeMaintenanceIngress(args)
+    : managedHook
+        ? 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/stage-catalog.js

@@ -3,7 +3,7 @@ export const vnextStages = [
     { id: "specify", directory: "01-specify", result: "specify.json", schema: "dd-flow/vnext-specify-result@4", next: ["protocolize"] },
     { id: "protocolize", directory: "02-protocolize", result: "protocolize-result.json", schema: "dd-flow/vnext-protocolize-result@3", next: ["plan"] },
     { id: "plan", directory: "03-plan", result: "stage-report.json", schema: "dd-flow/stage-report@2", next: ["plan-review", "code"] },
-    { id: "plan-review", directory: "04-plan-review", result: "decision.json", schema: "dd-flow/plan-review-decision@3", next: ["code"] },
+    { id: "plan-review", directory: "04-plan-review", result: "decision.json", schema: "dd-flow/plan-review-decision@4", next: ["code"] },
     { id: "code", directory: "05-code", result: "code-verification.json", schema: "dd-flow/code-verification@2", next: ["code-review", "merge"] },
     { id: "code-review", directory: "06-code-review", result: "decision.json", schema: "dd-flow/code-review-decision@3", next: ["merge"] },
     { id: "merge", directory: "07-merge", result: "stage-report.json", schema: "dd-flow/stage-report@2", next: [] }

package/dist/domain/stage-handler-identities.js

@@ -0,0 +1,20 @@
+/** Engine-owned identities shared by inspection and executable registration.
+ * Keep this module dependency-free: catalog inspection must not load handlers.
+ */
+export const sdlcHandlerIdentities = Object.freeze({
+    specify: Object.freeze({ stage: "specify", entryId: "sdlc-specify-entry", finishId: "sdlc-specify-finish" }),
+    protocolize: Object.freeze({ stage: "protocolize", entryId: "sdlc-protocolize-entry", finishId: "sdlc-protocolize-finish" }),
+    plan: Object.freeze({ stage: "plan", entryId: "sdlc-plan-entry", finishId: "sdlc-plan-finish" }),
+    "plan-review": Object.freeze({ stage: "plan-review", entryId: "sdlc-plan-review-entry", finishId: "sdlc-plan-review-finish" }),
+    code: Object.freeze({ stage: "code", entryId: "sdlc-code-entry", finishId: "sdlc-code-finish" }),
+    "code-review": Object.freeze({ stage: "code-review", entryId: "sdlc-code-review-entry", finishId: "sdlc-code-review-finish" }),
+    merge: Object.freeze({ stage: "merge", entryId: "sdlc-merge-entry", finishId: "sdlc-merge-finish" })
+});
+export const memoryInitHandlerIdentities = Object.freeze({
+    preflight: Object.freeze({ stage: "preflight", entryId: "memory-stage-entry", finishId: "memory-stage-finish" }),
+    discover: Object.freeze({ stage: "discover", entryId: "memory-stage-entry", finishId: "memory-stage-finish" }),
+    compose: Object.freeze({ stage: "compose", entryId: "memory-stage-entry", finishId: "memory-stage-finish" }),
+    verify: Object.freeze({ stage: "verify", entryId: "memory-stage-entry", finishId: "memory-stage-finish" }),
+    review: Object.freeze({ stage: "review", entryId: "memory-stage-entry", finishId: "memory-stage-finish" }),
+    finish: Object.freeze({ stage: "finish", entryId: "memory-stage-entry", finishId: "memory-stage-finish" })
+});

package/dist/harness-runtime/DD-ZCODE.md

@@ -0,0 +1,112 @@
+# dd-zcode integration boundary
+
+`bin/dd-zcode.mjs`, `lib/dd-zcode.mjs` and `lib/dd-zcode-daemon.mjs` implement the
+dd-flow adapter over ACP. The maintained bridge is
+[deksden-com/zcode-acp](https://github.com/deksden-com/zcode-acp), based on upstream
+[william0wang/zcode-acp](https://github.com/william0wang/zcode-acp).
+
+| Owner | Responsibility |
+| --- | --- |
+| Upstream bridge | ZCode protocol compatibility, ACP transport, native event translation and general session mechanics. |
+| Downstream bridge extensions | Expose native identity, evidence and control primitives missing upstream; preserve native errors and side-effect semantics. |
+| dd-zcode | Requested/observed profile checks, native-to-dd-flow identity mapping, event normalization, lifecycle forwarding, execution daemon ownership, cancellation/settlement verification and usage forwarding. |
+| dd-flow services | Durable lifecycle decisions, Work/RUN state and usage ingestion/accounting. |
+| dd-eval | Qualify the complete tuple, pin profiles/artifacts and run/monitor evaluations. |
+
+Native turn completion is evidence, not proof of semantic Work success. A
+closed transport is not proof that its native descendants stopped. The adapter
+must retain causal errors, missing observations and usage completeness rather
+than turn them into successful/zero-valued results.
+
+## Retained child observations
+
+Daemon capability `retained_child_observation` enables `session observe-children`
+for its registered root. It reads retained topology and exact terminal metadata,
+never loads/resumes a child or performs semantic work. During fanout the controller
+records failed child facts before dispatching anything else; healthy in-flight
+siblings may settle normally. Observation polling is not productive model activity.
+Ordinary `session inspect` is not a substitute for this read-only operation.
+
+Native attribution is a reported fact, not proof that an HTTP request reached a
+provider. If the native store discarded the causal exception, retain unknown;
+do not scrape ambient logs or infer overload/retry authority from an error message.
+
+The bridge marks heuristic ACP completion with
+`_meta.zcodeCompletionEvidence: "inferred"` and exhausted failed turns with
+`"failed"`. dd-zcode rejects these before any post-turn materializing read:
+inferred means `native_outcome_unknown` (not retryable automatically), failed
+means `zcode_turn_not_completed`. This additive evidence does not change the
+acceptance of already-qualified immutable older tuples. Native allocation
+notifications are causal identity evidence, not authorization to replay a turn.
+
+## Bridge contract
+
+The identity check uses `--dd-harness-version` (`dd-zcode-harness@1` for existing
+qualified builds, `dd-zcode-harness@2` for the qualified v0.46.7 bridge) and
+`--dd-harness-commit`, alongside native and bridge versions. This is the current
+mechanism, not a general capability negotiation protocol. `zcodeLifecycleQualification`
+also admits exact native-binary SHA / bridge-commit tuples; a new tuple requires
+behavioral evidence before admission. Merely changing an allowlist is not that
+evidence.
+
+The adapter consumes `zcode/session/resolve`, `read`, `subagents`, `usage`,
+`close`, `resident` and `retainedSubagents`, plus standard/existing session
+operations. Resolution must preserve the session's trusted workspace.
+Residency and retained-tree reads after close must not implicitly resume it.
+Cancellation must target owned sessions and verify resulting tree state.
+Profile facts must come from native readback. Session updates supply tool events.
+The adapter forwards a standalone public lifecycle command to `dd-flow zcode
+event handle`; native Session/tool identity binds it to the one exact issued
+assignment in that daemon scope. The command never exposes the runtime-owned
+invocation ID. Its shell inherits `DD_FLOW_DAEMON_ID`, finds the assignment and
+waits for the committed receipt before any lifecycle mutation can execute.
+
+The execution-scoped daemon preserves the live native handles needed for
+background children. Inspection remains available during productive operations;
+a lost owner cannot be repaired by pretending retained topology is a live tree.
+Keep process identity, native identity and adapter control locator distinct.
+
+## Usage and contract @2
+
+The @2 bridge returns native usage unchanged. `lib/zcode-usage.mjs` reads native
+session evidence and computes request counters in the adapter. It deduplicates
+identified requests, rejects conflicting/invalid measurements and records read
+failures as incomplete evidence. Full history is required for cumulative usage;
+turn-liveness history limits must not be applied here. Immutable @1 bridges
+remain supported through their existing measured projection. All adapter usage
+paths use the same helper; dd-flow services still own accounting deltas.
+
+Contract support does not admit a new binary/commit tuple automatically. The
+v0.46.7 @2 tuple is admitted for native SHA `500ae84f…f466` or the ZCode
+Desktop 3.14.3 SHA `b1df2ef3…dad529`, with bridge commit `f4d47b5…2833`.
+The latter passed the published beta.99 public-command probe on 2026-09-23:
+root and two concurrent child Work starts/finishes, plus same-child continuation,
+all with durable native identity receipts. Preserve that
+fail-closed distinction when preparing later evals.
+
+Future consumer-only retry, recovery, readiness and accounting rules belong
+here or in the owning dd-flow service. Bridge changes are justified when native
+access or protocol mechanics cannot be implemented through its public interface.
+Review existing patches individually; do not claim that all policy has already
+been extracted from the bridge.
+
+## Verification and operations
+
+Relevant adapter regressions include `test/zcode-invocation-observer.test.ts`;
+select the additional daemon, usage and lifecycle tests affected by a change.
+Bridge tests check transport facts; adapter tests check their interpretation;
+live qualification checks the actual installed tuple. Release the adapter with
+dd-flow when adapter code or qualification admission changes. A bridge-only
+update does not inherently require an adapter release, but current exact-commit
+admission may require one.
+
+Follow the [ZCode upgrade runbook](https://github.com/deksden-com/dd-eval/blob/main/runbooks/update-zcode.md)
+for release discovery, qualification, rollout and rollback. Fork patch maintenance
+is documented in the fork itself. Neither procedure is duplicated here.
+
+Adapter changes use short-lived `feat/`, `fix/` or `docs/` branches from `main`,
+reviewed with affected checks before integration (normally squash merge).
+Releases identify verified immutable artifacts, not moving main HEAD. See the
+[cross-repository Git workflow](https://github.com/deksden-com/dd-eval/blob/main/runbooks/git-workflow.md)
+for upgrade ordering, candidate acceptance and hotfixes. Branch-protection
+configuration is separate from this documented policy.