@deksden-com/dd-flow-cli 0.9.0-beta.123 → 0.9.0-beta.127

package/dist/cli/run-cli.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
+import { requiredOption, optionalOption, optionalNumber, optionalPositiveNumber } from "./argument-values.js";
 import { resolveCommandPaths, resolveCommandProjectRoot } from "../services/command-context.js";
-import { assertAuxiliaryCommandScope } from "../services/lifecycle-invocations.js";
+import { assertAuxiliaryCommandScope, cliManagedInvocationScope, manualRecoveryInvocationScope, assertManualRecoveryInvocationTarget } from "../services/lifecycle-invocations.js";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
 import { quote } from "shell-quote";
@@ -9,11 +10,12 @@ import { verifyCodexHookDelivery } from "../services/codex-hook-delivery.js";
 import { assertLifecycleInvocationCurrent, awaitLifecycleInvocation, bindLifecyclePublishedPacket, expandLifecycleInvocationArgs, issueLifecycleInvocation, prepareLifecycleIssuance, lifecycleInvocationScope, observedLifecycleDiagnostic, observedLifecycleInvocation, resolveObservedLifecycleArgs, retainObservedLifecycleSemantics, settleLifecycleInvocation, settleLifecyclePreparationRejection, settleLifecycleRejection, validateLifecyclePathAliases } from "../services/lifecycle-invocations.js";
 import { createContext, createRouterContext } from "../runtime/context.js";
 import { dispatchNativeHook, isNativeHookIngress } from "./native-hook-ingress.js";
+import { isRuntimeMaintenance, runtimeMaintenanceDiagnostics, withMaintenanceDiagnosticScope } from "./runtime-maintenance-diagnostics.js";
 import { migrateStoreWriter } from "../storage/writer-migration.js";
 import { helpForArgs } from "./help.js";
-import { AppError, isAppError } from "../shared/errors.js";
+import { AppError, errorRecord, isAppError } from "../shared/errors.js";
 import { entityReferenceVariants } from "../shared/entity-references.js";
-import { writeJson } from "../shared/json.js";
+import { writeJson, parseJsonObject } from "../shared/json.js";
 import { archiveProject, prepareProjectArchive, getProjectStatus, migrateProjectIds, registerProject, resolveProject } from "../services/projects.js";
 import { cancelProtocol, getProtocolBlockers, getProtocolStatus, getReadyProtocols, implementProtocol, readyForMerge, registerProtocol, prepareProtocolRegistration, requireProtocol, syncProtocolFromRun, prepareProtocolTransition, transitionProtocol } from "../services/protocols.js";
 import { getPlanStatus, preparePlanItemMutation, updatePlanItem } from "../services/plans.js";
@@ -41,7 +43,7 @@ import { ingestDroidUsage, ingestAgyUsage, ingestGrokUsage, ingestOpenCodeUsage,
 import { applyMigration, assessMigrationImpact, assertUpgradeRunStorageReady, planMigration, prepareMigrationApply, verifyMigrationReport } from "../services/migrations.js";
 import { publishProjectSummary } from "../services/project-summary.js";
 import { requireProjectByRoot } from "../services/projects.js";
-import { resolveProjectRoot } from "../storage/paths.js";
+import { resolveProjectRoot, resolveDdFlowHome } from "../storage/paths.js";
 import { doctorEngines, bindRunEngine, prepareRunEngineBind, engineInfo, installCurrentEngine, listEngines, resolveEngine, resolveExplicitProjectRoot, resolveOperationProjectRoot, routeArgsThroughEngine } from "../services/engines.js";
 import { preflightCliCompatibility } from "../services/compatibility-preflight.js";
 import { finishVnextSpecifyStage, getVnextWorkStatus, isVnextSpecifyFlow, isVnextSpecifyRun, launchVnextSpecify, prepareVnextSpecifyStart } from "../services/vnext-specify.js";
@@ -62,20 +64,17 @@ import { addWorkBatch, prepareWorkBatch, prepareWorkDeps, prepareWorkDelete, pre
 import { launchExternalWork } from "../services/external-work-launch.js";
 import { createEvalBootstrapSnapshot, prepareEvalBootstrapSnapshot, createEvalRunSnapshot, prepareEvalRunSnapshotCreation, prepareVnextSpecifyRun, prepareEvalRunRestore, prepareEvalBootstrapRestore, restoreEvalBootstrapSnapshot, restoreEvalRunSnapshot } from "../services/eval-snapshots.js";
 import { forkRunFromSnapshot, prepareRunFork } from "../services/run-fork.js";
-import { acceptRunRecovery, assertRunMutationAllowed, beginRunRecovery, inspectRunRecovery, prepareRecoveryCapture, prepareRecoveryPayload, prepareRunRecoveryResume, recordRecoveryCapture, recoveryGuard, resumeRunRecovery, sealRunRecovery } from "../services/run-recovery.js";
-import { recoveryRuntimeAdmission } from "../services/run-recovery-runtime.js";
+import { acceptRunRecovery, beginRunRecovery, inspectRunRecovery, prepareRecoveryCapture, prepareRecoveryPayload, prepareRunRecoveryResume, recordRecoveryCapture, resumeRunRecovery, sealRunRecovery } from "../services/run-recovery.js";
 import { loadExternalStageContext, prepareExternalStageContext } from "../services/stage-context.js";
 import { vnextStageDirectory } from "../domain/stage-catalog.js";
 import { prepareCommandRoute } from "./command-inputs.js";
 import { parseLifecycleCommand } from "../services/lifecycle-command.js";
-import { prepareManagedProcessRegistration, prepareManagedProcessConfirmation, prepareManagedProcessHeartbeat, prepareManagedProcessFinish, prepareManagedProcessStopOperation, prepareManagedProcessReconcile, stopManagedProcess, confirmManagedProcess, finishManagedProcess, heartbeatManagedProcess, managedProcessRuntimeHome, managedProcessStatus, processIsAlive, reconcileExpiredManagedProcesses, registerManagedProcess } from "../services/managed-processes.js";
-import { fenceRuntimeBudget, runtimeBudgetStatus, admitRuntimeCheck, parseRuntimeBudget, prepareRuntimeScopeControl, prepareRuntimeScopeFence, reserveProviderTurn, releaseProviderTurns, prepareProviderTurnRelease } from "../services/runtime-budget.js";
+import { dispatchRuntimeProcess, prepareRuntimeProcess } from "./runtime-process.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";
 import { prepareRuntimeScopeResumeRequest } from "../services/runtime-scope-resume.js";
 import { launchRunController, prepareRunControllerLaunch, resumeRunController, serveRunController, runControllerStatus, answerRunController, prepareRunControllerAnswer, supplyRunControllerContext, prepareRunControllerContext } from "../services/run-controller.js";
-import { controllerHitlAdmission } from "../services/run-controller-adapter.js";
-import { assertCapacityOwnerAdmission } from "../services/codex-capacity.js";
 import { controlLifecycleReply, runControlStatus } from "../services/run-control.js";
 import { reconcileRunControl, requestRunControl, serveRunControl } from "../services/run-control-worker.js";
 import { startRuntimeService, prepareRuntimeService } from "../services/runtime-service.js";
@@ -86,6 +85,9 @@ const defaultIo = {
 };
 const flagValue = "__dd_flow_flag__";
 export async function runCli(args, io = defaultIo, env = process.env) {
+    return withMaintenanceDiagnosticScope(() => runCliRequest(args, io, env));
+}
+async function runCliRequest(args, io, env) {
     let output;
     try {
         output = parseOutputOptions(args);
@@ -94,7 +96,10 @@ export async function runCli(args, io = defaultIo, env = process.env) {
         const rejection = isAppError(error) ? error : new AppError("usage", error instanceof Error ? error.message : String(error), 2);
         Object.assign(rejection.details, { phase: "prepare", effect: "no_effect", recoverable: true, ...rejection.details });
         try {
-            const command = quote(["dd-flow", ...args]), event = observedLifecycleNativeEvent(createRouterContext(env), command, env.DD_FLOW_DAEMON_ID);
+            const command = quote(["dd-flow", ...args]);
+            const analysis = parseLifecycleCommand(command);
+            const event = analysis.kind !== "none" || analysis.auxiliary
+                ? observedLifecycleNativeEvent(createRouterContext(env), command, env.DD_FLOW_DAEMON_ID) : null;
             if (event) {
                 const context = createContext({ ...env }, "hook");
                 try {
@@ -108,7 +113,7 @@ export async function runCli(args, io = defaultIo, env = process.env) {
         catch (persistence) {
             rejection.details.lifecycle_diagnostic_error = String(persistence);
         }
-        writeJson(io.stderr, { ok: false, error: { code: rejection.code, message: rejection.message, details: rejection.details } });
+        writeJson(io.stderr, { ok: false, error: errorRecord(rejection) });
         return rejection.exitCode;
     }
     const progress = progressForCommand(output.args);
@@ -116,6 +121,7 @@ export async function runCli(args, io = defaultIo, env = process.env) {
     let invocationSettlement;
     let settleHook;
     let diagnosticHome;
+    let maintenanceDiagnostics;
     try {
         if (output.args.length === 1 && output.args[0] === "--version") {
             const payload = getCliVersionReport();
@@ -135,6 +141,36 @@ export async function runCli(args, io = defaultIo, env = process.env) {
             writeJson(io.stdout, await dispatchNativeHook(output.args, await readStdin(io.stdin), env));
             return 0;
         }
+        if (output.args.slice(0, 3).join(" ") === "codex hook handle") {
+            const parsed = prepareCommandRoute(output.args).parsed;
+            const stdin = await readStdin(io.stdin);
+            const payload = parseJsonObject(stdin || "{}", "codex hook stdin");
+            const event = requiredOption(parsed, "event");
+            const isolatedHome = event === "PreToolUse" ? isolatedDdFlowHomeFromHookStdin(stdin) : null;
+            const hookEnv = isolatedHome ? { ...env, DD_FLOW_HOME: isolatedHome } : env;
+            const proof = await verifyCodexHookDelivery(hookEnv, payload);
+            let opened;
+            const mode = databaseModeForCommand(output.args, classifyCliOperation(output.args, hookEnv));
+            const context = {
+                env: hookEnv, ddFlowHome: resolveDdFlowHome(hookEnv), now: () => new Date().toISOString(),
+                get db() { return (opened ??= createContext(hookEnv, mode)).db; }
+            };
+            try {
+                // Retired events retain the explicit startup/migration path. PreToolUse
+                // only opens its selected prepared store when the handler needs it.
+                if (mode !== "hook")
+                    opened = createContext(hookEnv, mode);
+                if (proof)
+                    context.codexHookProof = proof;
+                const result = handleCodexHook(context, { event, projectRoot: optionalOption(parsed, "project-root"), stdin });
+                writeJson(io.stdout, result && typeof result === "object" && !Array.isArray(result) && "hookSpecificOutput" in result
+                    ? { hookSpecificOutput: result.hookSpecificOutput } : {});
+                return 0;
+            }
+            finally {
+                opened?.db.close?.();
+            }
+        }
         if (output.args[0] === "run" && ["drive", "control"].includes(output.args[1] ?? "")) {
             const controlArgs = parseArgs(output.args.slice(2));
             requiredOption(controlArgs, "run");
@@ -151,22 +187,45 @@ export async function runCli(args, io = defaultIo, env = process.env) {
                 required_marker: "DD_FLOW_COMPATIBILITY_MODE=mb-upgrade"
             });
         }
-        const routerContext = createRouterContext(env);
+        // Registration may bootstrap the resource registry, but never the unrelated
+        // RUN store. Its caller's absolute deadline also bounds that first open.
+        const maintenanceOptions = isRuntimeMaintenance(output.args) ? { resourceDatabaseMode: output.args[2] === "register" ? "initialize" : output.args[2] === "status" ? "read_existing" : "prepared_existing", ...(env.DD_FLOW_HOOK_DEADLINE_AT ? { databaseDeadlineAt: Number(env.DD_FLOW_HOOK_DEADLINE_AT) } : {}) } : {};
+        // Keep ordinary CLI JSON/stderr compatibility; bounded maintenance callers
+        // provide this request's deadline and consume its structured phase evidence.
+        if (maintenanceOptions.databaseDeadlineAt !== undefined)
+            maintenanceDiagnostics = runtimeMaintenanceDiagnostics(output.args, maintenanceOptions.databaseDeadlineAt, line => io.stderr.write(line));
+        const routerContext = createRouterContext(env, maintenanceOptions.databaseDeadlineAt);
         const publicCommand = quote(["dd-flow", ...output.args]);
         const nativeCommand = quote(["dd-flow", ...args]);
         const lifecycleCommand = parseLifecycleCommand(publicCommand);
         if (lifecycleCommand.kind === "standalone")
             validateLifecyclePathAliases(output.args, lifecycleCommand.invocation.operation);
-        const observedInvocation = observedLifecycleInvocation(routerContext, publicCommand, env.DD_FLOW_DAEMON_ID);
+        const managedScope = lifecycleCommand.kind === "standalone" && env.DD_FLOW_DAEMON_ID ? cliManagedInvocationScope({ ...routerContext, env }) : null;
         const nativeEvent = env.DD_FLOW_DAEMON_ID && lifecycleCommand.kind === "standalone"
             ? observedLifecycleNativeEvent(routerContext, nativeCommand, env.DD_FLOW_DAEMON_ID) : null;
+        const nativeEventKey = nativeEvent && routerContext.db.get("SELECT event_key FROM hook_events WHERE project_id = ? AND id = ?", [nativeEvent.project_id, nativeEvent.id])?.event_key;
+        const observedInvocation = managedScope ? observedLifecycleInvocation(routerContext, publicCommand, managedScope, nativeEventKey ? { eventKey: nativeEventKey } : undefined) : null;
+        if (managedScope && suppliedInvocationId
+            && routerContext.db.get("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'lifecycle_invocations'")
+            && routerContext.db.get("SELECT id FROM lifecycle_invocations WHERE id = ?", [suppliedInvocationId])) {
+            const suppliedScope = lifecycleInvocationScope({ ...routerContext, env }, suppliedInvocationId);
+            if (["projectRoot", "daemonId", "rootSessionId", "runId", "generation"].some(key => suppliedScope[key] !== managedScope[key])) {
+                throw new AppError("invocation_scope_mismatch", "Explicit lifecycle assignment differs from the current physical native owner", 1, { effect: "no_effect", recoverable: false });
+            }
+        }
         const diagnostic = env.DD_FLOW_DAEMON_ID && lifecycleCommand.kind === "standalone"
             ? observedLifecycleDiagnostic(routerContext, publicCommand, env.DD_FLOW_DAEMON_ID, observedInvocation?.id) : null;
         if (diagnostic && (!nativeEvent || Number(diagnostic.hook_event_id) > nativeEvent.id)) {
             throw new AppError("lifecycle_shell_syntax_invalid", `Native observer rejected the shell form: ${String(diagnostic.reason ?? "unsupported shell composition")}. Write structured input to a file and run the returned dd-flow command separately.`, 2, { ...diagnostic, phase: "prepare", effect: "no_effect", recoverable: true });
         }
+        let manualRecoveryHookEventKey;
         if (!observedInvocation && !suppliedInvocationId && env.DD_FLOW_DAEMON_ID && lifecycleCommand.kind === "standalone") {
-            throw new AppError(nativeEvent ? "invocation_assignment_missing" : "invocation_receipt_missing", nativeEvent ? "Native call was observed, but its arguments do not match an issued lifecycle assignment" : "Managed lifecycle command has no committed native receipt", 1, { effect: "no_effect", recoverable: false });
+            const receipt = nativeEvent && routerContext.db.get("SELECT event_key,harness,provider_session_id,parent_session_id,daemon_id,status FROM hook_events WHERE id = ? AND project_id = ?", [nativeEvent.id, nativeEvent.project_id]);
+            const manual = managedScope && receipt?.status === "observed" ? manualRecoveryInvocationScope({ ...routerContext, env }, managedScope.projectRoot, { daemonId: receipt.daemon_id, rootSessionId: receipt.provider_session_id, sessionId: receipt.provider_session_id, parentSessionId: receipt.parent_session_id, toolCallId: String(nativeEvent.id) }, receipt.harness) : null;
+            if (!manual || JSON.stringify(manual) !== JSON.stringify(managedScope))
+                throw new AppError(nativeEvent ? "invocation_assignment_missing" : "invocation_receipt_missing", nativeEvent ? "Native call was observed, but its arguments do not match an issued lifecycle assignment" : "Managed lifecycle command has no committed native receipt", 1, { effect: "no_effect", recoverable: false });
+            assertManualRecoveryInvocationTarget({ ...routerContext, env }, manual, publicCommand);
+            manualRecoveryHookEventKey = receipt.event_key;
         }
         const invocationId = observedInvocation?.id ?? suppliedInvocationId;
         let boundInvocationArgs;
@@ -207,7 +266,7 @@ export async function runCli(args, io = defaultIo, env = process.env) {
         }
         // Route by retained authority, so a mistyped project path reaches the CLI
         // validator instead of selecting a different engine or failing preflight.
-        const scopeProjectRoot = invocationScope?.projectRoot ?? resolveCommandProjectRoot(routerContext, output.args, resolveProjectRootBeforeRouting(output.args, env));
+        const scopeProjectRoot = invocationScope?.projectRoot ?? resolveCommandProjectRoot(routerContext, output.args, resolveProjectRootBeforeRouting(output.args, env, maintenanceOptions.databaseDeadlineAt));
         assertAuxiliaryCommandScope({ ...routerContext, env }, publicCommand, scopeProjectRoot);
         invocationArgs = resolveCommandPaths(routerContext, invocationArgs, scopeProjectRoot);
         const routedArgs = output.responseFile ? [...invocationArgs, "--response-file", output.responseFile] : invocationArgs;
@@ -223,7 +282,7 @@ export async function runCli(args, io = defaultIo, env = process.env) {
         let preparedInput;
         let preparedRoute;
         if (!invocationId) {
-            const preparationContext = createContext({ ...env }, "read_existing");
+            const preparationContext = createContext({ ...env }, "read_existing", undefined, maintenanceOptions);
             try {
                 preparedInput = await prepareCliInput(invocationArgs, preparationContext, io, scopeProjectRoot, output.responseFile);
             }
@@ -232,8 +291,8 @@ export async function runCli(args, io = defaultIo, env = process.env) {
             }
         }
         const dispatchContext = routed?.inProcess
-            ? createContext({ ...env, DD_FLOW_ENGINE_MODE: "1", DD_FLOW_ENGINE_HOME: "in-process", DD_FLOW_ROUTED_FROM: getCliVersionReport().cli.version }, databaseModeForCommand(invocationArgs, classification))
-            : createContext({ ...env }, databaseModeForCommand(invocationArgs, classification));
+            ? createContext({ ...env, DD_FLOW_ENGINE_MODE: "1", DD_FLOW_ENGINE_HOME: "in-process", DD_FLOW_ROUTED_FROM: getCliVersionReport().cli.version }, databaseModeForCommand(invocationArgs, classification), undefined, maintenanceOptions)
+            : createContext({ ...env }, databaseModeForCommand(invocationArgs, classification), undefined, maintenanceOptions);
         diagnosticHome = dispatchContext.ddFlowHome;
         dispatchContext.env.DD_FLOW_INVOCATION_READONLY = classification.mode === "read_only_diagnostics" ? "1" : undefined;
         let dispatchArgs = invocationArgs;
@@ -271,6 +330,13 @@ export async function runCli(args, io = defaultIo, env = process.env) {
                 dispatchContext.env.DD_FLOW_CURRENT_INVOCATION = invocationId;
             }
         }
+        if (!invocationId && manualRecoveryHookEventKey) {
+            // Keep the physically scoped receipt selected by admission; a service must
+            // not rediscover a different daemon's matching command event.
+            if (!invocationArgs.includes("--hook-event-id"))
+                dispatchArgs = [...invocationArgs, "--hook-event-id", manualRecoveryHookEventKey];
+            preparedInput?.route?.parsed.options.set("hook-event-id", [manualRecoveryHookEventKey]);
+        }
         if (retainedOutcome?.error) {
             const error = retainedOutcome.error;
             throw new AppError(error.code, error.message, error.exitCode, error.details);
@@ -313,6 +379,9 @@ export async function runCli(args, io = defaultIo, env = process.env) {
         emitHumanProgress(io, output, progress, "done");
         const payload = attachProgress(resultWithWarnings, progress, output);
         const visible = writeResponseFile(payload, output);
+        const maintenanceReceipt = payload;
+        const maintenanceExpiry = maintenanceReceipt?.lease_expires_at ?? maintenanceReceipt?.process?.lease_expires_at;
+        maintenanceDiagnostics?.phase("ack", { ...(typeof maintenanceExpiry === "string" && Number.isFinite(Date.parse(maintenanceExpiry)) ? { lease_expires_at: maintenanceExpiry } : {}) });
         if (output.json)
             writeJson(io.stdout, visible);
         else
@@ -320,19 +389,24 @@ export async function runCli(args, io = defaultIo, env = process.env) {
         return completedCommandExitCode(payload);
     }
     catch (caught) {
-        const error = isAppError(caught) ? caught : new AppError("unexpected", caught instanceof Error ? caught.message : String(caught), 1, { effect: "unknown", cause: { code: caught?.code ?? null, sqlite_extended_code: caught?.errcode ?? null } });
+        const record = errorRecord(caught);
+        maintenanceDiagnostics?.failure(caught);
+        const error = isAppError(caught) ? caught : Object.assign(new AppError(record.code, record.message, record.exitCode, { effect: "unknown", ...record.details, ...(caught?.errcode !== undefined ? { sqlite_extended_code: caught.errcode } : {}) }), { ...(record.cause ? { cause: record.cause } : {}), ...(record.cleanup_error ? { cleanup_error: record.cleanup_error } : {}), ...(record.retryable !== undefined ? { retryable: record.retryable } : {}) });
         if (!settleHook && !invocationSettlement) {
             let earlyContext;
             try {
                 const command = quote(["dd-flow", ...args]);
-                const router = createRouterContext(env);
-                const event = observedLifecycleNativeEvent(router, command, env.DD_FLOW_DAEMON_ID);
+                const analysis = parseLifecycleCommand(command);
+                // Maintenance failures must not start an unrelated, unbounded hook
+                // lookup after their own request deadline has already expired.
+                const router = analysis.kind !== "none" || analysis.auxiliary ? createRouterContext(env) : null;
+                const event = router ? observedLifecycleNativeEvent(router, command, env.DD_FLOW_DAEMON_ID) : null;
                 // A correctable prepare rejection precedes the terminal command's
                 // single-use claim. Correlate its unique hook by the same lifecycle
                 // match key used at dispatch, including compound provider tool shells;
                 // otherwise a repaired retry sees two fresh, unclaimed events.
-                if (event || (error.details.phase === "prepare" && error.details.effect === "no_effect"
-                    && fs.existsSync(path.join(router.ddFlowHome, "db.sqlite")))) {
+                if (router && (event || (error.details.phase === "prepare" && error.details.effect === "no_effect"
+                    && fs.existsSync(path.join(router.ddFlowHome, "db.sqlite"))))) {
                     earlyContext = createContext({ ...env }, "hook");
                     observeLifecycleCommand(earlyContext, command, event ?? undefined)({ error });
                 }
@@ -360,8 +434,13 @@ export async function runCli(args, io = defaultIo, env = process.env) {
             clearInterval(heartbeat);
         if (invocationSettlement && error.details.effect !== "committed") {
             try {
-                if (isAppError(error))
-                    settleLifecycleRejection(invocationSettlement.context, invocationSettlement.id, { code: error.code, message: error.message, exitCode: error.exitCode, details: error.details });
+                if (isAppError(error)) {
+                    const settled = errorRecord(error);
+                    settleLifecycleRejection(invocationSettlement.context, invocationSettlement.id, settled);
+                    // Serialization owns a copy. Publish the committed settlement, not
+                    // the original rejection which has no successor authority.
+                    Object.assign(error.details, settled.details);
+                }
                 else
                     settleLifecycleInvocation(invocationSettlement.context, invocationSettlement.id, { error: { code: "unexpected", message: String(error), exitCode: 1, details: {} } });
             }
@@ -377,9 +456,7 @@ export async function runCli(args, io = defaultIo, env = process.env) {
                 io.stderr.write(`${JSON.stringify({ primary: String(error), lifecycle_persistence_error: String(persistence) })}\n`);
             }
         }
-        const payload = isAppError(error)
-            ? { ok: false, error: { code: error.code, message: error.message, details: error.details } }
-            : { ok: false, error: { code: "unexpected", message: String(error) } };
+        const payload = { ok: false, error: errorRecord(error) };
         progress.splice(0, progress.length, ...progress.filter(event => event.phase !== "done"));
         if (progress.length)
             progress.push({ phase: "failed", message: payload.error.message, at: new Date().toISOString() });
@@ -403,14 +480,23 @@ export async function runCli(args, io = defaultIo, env = process.env) {
             io.stderr.write(renderHumanError(payload));
         return isAppError(error) ? error.exitCode : 1;
     }
+    finally {
+        maintenanceDiagnostics?.close();
+    }
 }
-function resolveProjectRootBeforeRouting(args, env) {
+function resolveProjectRootBeforeRouting(args, env, deadlineAt) {
     const explicit = resolveExplicitProjectRoot(args);
     if (explicit)
         return explicit;
     try {
         // Router identity lookup is read-only; it must not initialize or migrate runtime storage.
-        return resolveOperationProjectRoot(createContext(env, "read_existing"), args);
+        const context = createContext(env, "read_existing", undefined, deadlineAt === undefined ? {} : { databaseDeadlineAt: deadlineAt });
+        try {
+            return resolveOperationProjectRoot(context, args);
+        }
+        finally {
+            context.db.close?.();
+        }
     }
     catch {
         return null;
@@ -419,6 +505,8 @@ function resolveProjectRootBeforeRouting(args, env) {
 function databaseModeForCommand(args, classification) {
     if (isNativeHookIngress(args))
         return "hook";
+    if (isRuntimeMaintenance(args))
+        return "read_existing";
     const [family, command] = args;
     // Managed attempts are issued only from a prepared store. Opening that
     // existing writer must not run migrations before their input is admitted.
@@ -1005,22 +1093,8 @@ async function prepareCliInputValue(args, context, io, scopeProjectRoot, respons
             return prepareError(error, { parameter: "scope-id/request-id/manifest-json" });
         }
     }
-    if (route.key === "runtime process register") {
-        prepareManagedProcessRegistration(context, runtimeProcessRegistrationInput(context, parsed));
-    }
-    if (route.key === "runtime process heartbeat")
-        prepareManagedProcessHeartbeat(context, runtimeProcessHeartbeatInput(parsed));
-    if (route.key === "runtime process finish")
-        prepareManagedProcessFinish(context, runtimeProcessFinishInput(parsed));
-    if (route.key === "runtime process confirm")
-        prepareManagedProcessConfirmation(context, runtimeProcessConfirmationInput(parsed));
-    if (route.key === "runtime process stop")
-        prepareManagedProcessStopOperation(context, runtimeProcessStopInput(parsed));
-    if (route.key === "runtime process reconcile")
-        prepareManagedProcessReconcile(requiredOption(parsed, "owner"), optionalNumber(parsed, "grace-ms"));
-    if (route.key === "runtime process release-turn") {
-        prepared.providerTurnRelease = prepareProviderTurnRelease({ daemonId: requiredOption(parsed, "daemon-id"), operationId: optionalOption(parsed, "operation-id"), observationFile: optionalOption(parsed, "observation-file") });
-    }
+    if (family === "runtime" && command === "process")
+        Object.assign(prepared, prepareRuntimeProcess(context, route.key, parsed));
     if (route.key === "runtime process start") {
         try {
             prepareRuntimeService(context, runtimeServiceInput(parsed));
@@ -1990,7 +2064,8 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
         return dispatchCodexHome(context, parsed, prepared);
     }
     if (family === "codex" && command === "hook") {
-        return dispatchCodexHook(context, parsed, await readStdin(io.stdin));
+        // `handle` is owned by the pre-context ingress above, never generic dispatch.
+        throw new AppError("usage", "Use: dd-flow codex hook handle --event EVENT", 2);
     }
     if (family === "zcode" && command === "hook") {
         return dispatchZcodeHook(context, parsed, await readStdin(io.stdin));
@@ -2383,14 +2458,14 @@ function snapshotCreateInput(parsed) {
     return { projectRoot: requiredOption(parsed, "project-root"), runId: requiredPosition(parsed, 1, "run-id"), output: requiredOption(parsed, "output"), candidate: parsed.options.has("candidate"), incomplete: parsed.options.has("incomplete"), ...(recoveryId !== undefined ? { recoveryId } : {}), ...(stageEntry !== undefined ? { stageEntry } : {}) };
 }
 function snapshotRestoreInput(parsed) {
-    return { snapshot: requiredOption(parsed, "snapshot"), projectRoot: requiredOption(parsed, "project-root"), executionRoutingFile: optionalOption(parsed, "execution-routing-file"), ...(optionalOption(parsed, "recovery-id") ? { recoveryId: requiredOption(parsed, "recovery-id") } : {}) };
+    return { snapshot: requiredOption(parsed, "snapshot"), projectRoot: requiredOption(parsed, "project-root"), executionRoutingFile: optionalOption(parsed, "execution-routing-file"), operationalDecisionFile: optionalOption(parsed, "operational-decision-file"), ...(optionalOption(parsed, "recovery-id") ? { recoveryId: requiredOption(parsed, "recovery-id") } : {}) };
 }
 function runStartInput(parsed) {
     const protocolOverrides = readOptionalJsonFile(optionalOption(parsed, "protocol-override-file"));
     return { projectRoot: requiredOption(parsed, "project-root"), workspaceRoot: optionalOption(parsed, "workspace-root"), flowKind: requiredOption(parsed, "flow-kind"), subjectType: requiredOption(parsed, "subject-type"), subjectId: requiredOption(parsed, "subject-id"), slug: requiredOption(parsed, "slug"), nextAction: optionalOption(parsed, "next-action"), preset: optionalOption(parsed, "preset"), taskProfile: readOptionalJsonFile(optionalOption(parsed, "task-profile-file")), executionRoutingFile: optionalOption(parsed, "execution-routing-file"), ...(protocolOverrides !== undefined ? { protocolOverrides } : {}), runOverrides: parseFlowFlagOverrides(allOptions(parsed, "flag")) };
 }
 function runForkInput(parsed) {
-    return { snapshot: requiredOption(parsed, "from"), output: requiredOption(parsed, "output"), engineVersion: requiredOption(parsed, "engine-version"), requestId: requiredOption(parsed, "request-id"), ...(optionalOption(parsed, "integrity-checksum") ? { integrityChecksum: optionalOption(parsed, "integrity-checksum") } : {}) };
+    return { snapshot: requiredOption(parsed, "from"), output: requiredOption(parsed, "output"), engineVersion: requiredOption(parsed, "engine-version"), requestId: requiredOption(parsed, "request-id"), ...(optionalOption(parsed, "integrity-checksum") ? { integrityChecksum: optionalOption(parsed, "integrity-checksum") } : {}), ...(optionalOption(parsed, "operational-decision-file") ? { operationalDecisionFile: optionalOption(parsed, "operational-decision-file") } : {}) };
 }
 function recoveryCaptureInput(parsed) {
     return { projectRoot: requiredOption(parsed, "project-root"), runId: requiredPosition(parsed, 1, "run-id"), recoveryId: requiredOption(parsed, "recovery-id"), capturePath: requiredOption(parsed, "capture-path") };
@@ -2542,44 +2617,9 @@ function stageCompletionInput(parsed) {
 function runtimeServiceInput(parsed) {
     return { projectRoot: requiredOption(parsed, "project-root"), runId: requiredOption(parsed, "run"), command: requiredOption(parsed, "command"), ports: requiredOption(parsed, "ports").split(","), readyPort: requiredOption(parsed, "ready-port"), readyPath: optionalOption(parsed, "ready-path") ?? "/", timeoutMs: optionalPositiveNumber(parsed, "ready-timeout-ms", true) ?? 30_000 };
 }
-function runtimeProcessStopInput(parsed) {
-    const graceMs = optionalNumber(parsed, "grace-ms");
-    return { id: requiredOption(parsed, "id"), leaseToken: requiredOption(parsed, "lease-token"), ...(graceMs !== undefined ? { graceMs } : {}) };
-}
 function runtimeScopeResumeInput(parsed) {
     return { scopeId: requiredOption(parsed, "scope-id"), requestId: requiredOption(parsed, "request-id"), generation: Number(requiredOption(parsed, "generation")), captureKey: requiredOption(parsed, "capture-key") };
 }
-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 {
-        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 };
-}
 async function dispatchRuntime(context, command, parsed, progress, prepared = {}) {
     if (command === "scope") {
         if (parsed.positional.length === 1 && parsed.positional[0] === "reconcile") {
@@ -2622,60 +2662,9 @@ async function dispatchRuntime(context, command, parsed, progress, prepared = {}
     if (command !== "process")
         throw new AppError("usage", "Usage: dd-flow runtime <scope|process>; see dd-flow runtime scope --help", 2);
     const action = requiredPosition(parsed, 0, "runtime process action");
-    if (action === "check-admission")
-        return { ok: true, ...admitRuntimeCheck(context, requiredOption(parsed, "id"), requiredOption(parsed, "lease-token")) };
     if (action === "start")
         return await startRuntimeService(context, { ...runtimeServiceInput(parsed), progress });
-    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")
-        return { ok: heartbeatManagedProcess(context, runtimeProcessHeartbeatInput(parsed)) };
-    if (action === "admission") {
-        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);
-        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"));
-        }
-        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") });
-        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")
-        return { ok: true, processes: managedProcessStatus(context) };
-    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);
+    return await dispatchRuntimeProcess(context, action, parsed, prepared);
 }
 function dispatchStat(context, command, parsed) {
     if (command === "usage") {
@@ -3048,26 +3037,6 @@ function dispatchCodexHome(context, parsed, prepared) {
     }
     throw new AppError("usage", `Unknown codex home action: ${action}`, 2);
 }
-async function dispatchCodexHook(context, parsed, stdin) {
-    const action = requiredPosition(parsed, 0, "codex hook action");
-    if (action === "handle") {
-        const isolatedHome = isolatedDdFlowHomeFromHookStdin(stdin);
-        const hookContext = isolatedHome ? createContext({ ...context.env, DD_FLOW_HOME: isolatedHome }, "hook") : context;
-        const proof = await verifyCodexHookDelivery(hookContext.env, JSON.parse(stdin || "{}"));
-        if (proof)
-            hookContext.codexHookProof = proof;
-        const result = handleCodexHook(hookContext, {
-            event: requiredOption(parsed, "event"),
-            projectRoot: optionalOption(parsed, "project-root"),
-            stdin
-        });
-        if (result && typeof result === "object" && !Array.isArray(result) && "hookSpecificOutput" in result) {
-            return { hookSpecificOutput: result.hookSpecificOutput };
-        }
-        return {};
-    }
-    throw new AppError("usage", `Unknown codex hook action: ${action}`, 2);
-}
 function dispatchZcodeEvent(context, parsed, stdin) {
     const action = requiredPosition(parsed, 0, "zcode event action");
     if (action === "handle") {
@@ -3214,25 +3183,9 @@ function requiredPosition(parsed, index, label) {
     }
     return value;
 }
-function optionalOption(parsed, key) {
-    const values = parsed.options.get(key);
-    const value = values?.[values.length - 1];
-    if (value === flagValue)
-        throw new AppError("usage", `--${key} requires a value`, 2);
-    if (value !== undefined && !value.trim())
-        throw new AppError("usage", `--${key} requires a non-empty value`, 2);
-    return value;
-}
 function allOptions(parsed, key) {
     return (parsed.options.get(key) ?? []).filter((value) => value !== flagValue);
 }
-function requiredOption(parsed, key) {
-    const value = optionalOption(parsed, key);
-    if (!value) {
-        throw new AppError("usage", `Missing required option: --${key}`, 2);
-    }
-    return value;
-}
 function requiredScopeProjectRoot(root, operation) {
     if (root)
         return root;
@@ -3272,26 +3225,6 @@ function parseBoolean(value, key) {
 function parseOptionalBoolean(value, key) {
     return typeof value === "string" ? parseBoolean(value, key) : undefined;
 }
-function optionalNumber(parsed, key) {
-    const value = optionalOption(parsed, key);
-    if (typeof value === "undefined") {
-        return undefined;
-    }
-    const parsedNumber = Number(value);
-    if (!Number.isFinite(parsedNumber)) {
-        throw new AppError("validation", `--${key} must be a number`, 2);
-    }
-    return parsedNumber;
-}
-function optionalPositiveNumber(parsed, key, integer = false) {
-    const value = optionalNumber(parsed, key);
-    if (typeof value === "undefined")
-        return undefined;
-    if (value <= 0 || (integer && !Number.isInteger(value))) {
-        throw new AppError("validation", `--${key} must be a positive${integer ? " integer" : ""} number`, 2);
-    }
-    return value;
-}
 function requiredWorkerId(parsed) {
     return requiredOption(parsed, "worker-id");
 }

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")), 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) };
+}