@deksden-com/dd-flow-cli 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @deksden-com/dd-flow-cli
 
+## 0.7.0
+
+### Minor Changes
+
+- Add target-driven engine routing, explicit storage migration safety, immutable RUN engine bindings, engine schema registry validation, and self-contained plan execution guidance.
+
+## 0.6.0
+
+### Minor Changes
+
+- 47cd270: Add SPC-006 bootstrap stage start/context packets and sealed stage finish, while repairing Memory Bank upgrade stage routing, Codex hook event identity, PATH-stable per-home hook installation, canonical Codex session registration, session coverage projections, terminal orchestrator closure, and safe reconciliation of runs whose legacy authority and workspace are gone.
+
 ## 0.5.0
 
 ### Minor Changes

package/README.md

@@ -75,10 +75,10 @@ dd-flow protocol register HANDSHAKE-001 --project-root "$PWD" --json
 dd-flow protocol status PRT-HANDSHAKE-001 --project-root "$PWD" --json
 ```
 
-Attach and update a plan:
+Inspect the canonical plan and update its SQLite progress projection:
 
 ```bash
-dd-flow plan set PRT-HANDSHAKE-001 --project-root "$PWD" --file plan.json --json
+dd-flow plan status PRT-HANDSHAKE-001 --project-root "$PWD" --json
 dd-flow plan item start PRT-HANDSHAKE-001 P1 --project-root "$PWD" --json
 dd-flow plan item done PRT-HANDSHAKE-001 P1 --project-root "$PWD" --summary "Implemented" --evidence "pnpm test" --json
 ```
@@ -355,9 +355,16 @@ Codex integration is explicit and auditable. Managed Codex homes and hooks are l
 ```bash
 dd-flow codex home plan --project-root "$PROJECT_ROOT" --json
 dd-flow codex hooks status --project-root "$PROJECT_ROOT" --target isolated --json
-dd-flow codex hook handle --event Stop --project-root "$PROJECT_ROOT" --json
+dd-flow codex hook handle --event Stop --json
 ```
 
+Installed Codex hooks intentionally omit `--project-root`: Codex supplies the
+session `cwd` in the hook JSON on stdin, and the handler resolves the registered
+project from that path. The option remains available as a manual override. If
+the CLI is upgraded, reinstall the hook in each active `CODEX_HOME`, verify it
+with `dd-flow codex hooks status`, and start a new Codex session;
+`--project-root` belongs to installer/status commands, not the stored handler.
+
 ## Verification
 
 Local verification for this repository:

package/dist/build-info.json

@@ -1,11 +1,11 @@
 {
   "cli_package": "@deksden-com/dd-flow-cli",
-  "cli_version": "0.5.0",
-  "cli_commit": "64b75acbb2e62c9e80eb29c501f5f3481f86cf20",
-  "built_at": "2026-08-11T10:20:58.455Z",
+  "cli_version": "0.7.0",
+  "cli_commit": "a09f6b663231d3179bea64b2fd9bb4ffa30096c2",
+  "built_at": "2026-08-13T04:31:51.147Z",
   "built_with_canon": {
-    "version": "3.0.0",
-    "commit": "1e8c39078ed7a34adde93315a9cdcf2bbfc15374",
+    "version": "3.2.0",
+    "commit": "2a1aaec84ee7d62b9f5a6549de5d1f0cb88082c0",
     "flow_contract": "dd-flow-canonical-2026-08",
     "repo_root": "/Users/deksden/Documents/_Projects/dd-memorybank",
     "memorybank_root": "/Users/deksden/Documents/_Projects/dd-memorybank/.memory-bank",

package/dist/cli/help.js

@@ -12,13 +12,13 @@ Core commands:
   version                       Print the installed dd-flow CLI package version.
   status                        Inspect dd-flow runtime, project and canon roots.
   engine install/list/info      Manage locally installed dd-flow engine snapshots.
-  engine resolve/doctor         Inspect router engine selection and health.
+  engine resolve/doctor/bind-run Inspect router selection, health, and recover a legacy RUN binding.
   canon register/status/resolve Register and resolve the canonical Memory Bank.
   project register/status/summary Register a project, inspect state, and publish project summaries.
   project resolve/archive       Resolve typed ids and archive stale project roots.
   project migrate-ids           Migrate old project ids.
   protocol register/status/transition Register, inspect, transition and repair protocol state.
-  migration impact/plan/report/verify Assess release impact and prepare mb-upgrade migration evidence.
+  migration impact/plan/report/verify/apply Assess release impact and explicitly apply mb-upgrade migration evidence.
   cleanup scan/apply            Detect and repair stale local runtime state.
   run start/status/list/timeline/usage/flags Track concrete flow executions, timing, source-aware usage and RUN-local flow flags.
   stage start/finish           Run the canonical two-command stage lifecycle and generate evidence.
@@ -28,7 +28,7 @@ Core commands:
   lane workspace/lock/status    Manage shared workspace lanes and leases.
   merge status/one-shot/bundle  Inspect, claim, or complete merge work from the current session.
   merge-worker status/start/stop Manage long-lived project merge workers.
-  merge-queue status/next       Claim, wait for, complete, or fail merge jobs.
+  merge-queue status/claim/next Claim, wait for, complete, or fail merge jobs.
   session register/status/stop  Register flow sessions and stop workers.
   dashboard data/render/open/refresh Render, refresh, open, and inspect project/global dashboards.
   schema validate             Validate canonical dd-flow JSON data contracts.
@@ -86,6 +86,7 @@ Usage:
   dd-flow engine info [--package <name>] [--version <version>] --json
   dd-flow engine resolve [--project-root <root>] --json
   dd-flow engine doctor [--project-root <root>] --json
+  dd-flow engine bind-run <RUN-ID> --project-root <root> --engine-version <version> --reason <text> [--integrity-checksum <sha256>] --json
 
 The globally invoked dd-flow command is the stable router surface. Engine snapshots live under DD_FLOW_HOME/engines and are selected by project Memory Bank compatibility data. Running an old package through npx can install that package's own engine without replacing the global router:
 
@@ -93,11 +94,14 @@ The globally invoked dd-flow command is the stable router surface. Engine snapsh
 
 Router-native engine commands never mutate project runtime data. Normal project commands are routed to a compatible engine or fail closed with a missing-engine diagnostic.
 
+engine bind-run is the one recovery command for a legacy RUN without an engine-binding sidecar. It probes the requested installed snapshot with run status before atomically writing an immutable binding; later RUN commands route through that snapshot.
+
 Examples:
   dd-flow engine install --json
   dd-flow engine list --json
   dd-flow engine resolve --project-root "$PWD" --json
-  dd-flow engine doctor --project-root "$PWD" --json`
+  dd-flow engine doctor --project-root "$PWD" --json
+  dd-flow engine bind-run RUN-193 --project-root "$PWD" --engine-version 0.4.2 --reason "legacy flow-run@1" --json`
     ],
     [
         "status",
@@ -143,7 +147,7 @@ Usage:
   dd-flow id next --type protocol|run --project-root <root> --slug <slug> --json
   dd-flow run status <RUN-ID|RUN-short-id> --project-root <root> --json
   dd-flow run list --project-root <root> --json
-  dd-flow run timeline <RUN-ID|RUN-short-id> --project-root <root> [--hide stages|events|sessions|usage|artifacts] --json
+  dd-flow run timeline <RUN-ID|RUN-short-id> --project-root <root> --json
   dd-flow run usage <RUN-ID|RUN-short-id> --project-root <root> [--group-by session|role|stage|aspect|plan-item] --json
   dd-flow run flags status <RUN-ID|RUN-short-id> --project-root <root> --json
   dd-flow run flags revise <RUN-ID|RUN-short-id> --project-root <root> --expected-revision <n> --idempotency-key <key> [--preset <name>] [--flag key=value] [--flag key=value] [--allow-downgrade --reason <text>] --json
@@ -165,9 +169,10 @@ Examples:
 
 Usage:
   dd-flow stage start <RUN-ID|RUN-short-id> --project-root <root> --stage <name> [--dir <NN-stage-slug>] --json
-  dd-flow stage finish <RUN-ID|RUN-short-id> --project-root <root> --stage <name> [--status done|blocked|failed] [--semantic-file <RUN-local-json>] --json
+  dd-flow stage start --bootstrap --project-root <root> --stage specify --subject <safe-subject> [--intake-file <path>] --json
+  dd-flow stage finish <RUN-ID|RUN-short-id> --project-root <root> --stage <name> [--outcome done|blocked|failed] [--semantic-file <RUN-local-json>] --json
 
-stage start attaches the stage, archives an earlier attempt when needed and writes one RUN-local stage-prompt.md. stage finish derives a bounded report and always generates validated JSON, Markdown, template-backed HTML and a durable protocol-summary projection. Raw intake and telemetry remain RUN-local.`
+stage start is the worker's first practical flow command. It performs deterministic setup and returns a ready-to-use, stage-specific work packet with trusted runtime facts, compatibility and permission preflight, aliases, write boundary and exact finish command. The same packet is written to RUN-local stage-prompt.md and stage-prompt.json. --bootstrap creates the initial protocol/RUN envelope and copies the supplied intake into the RUN home before starting specify. stage finish defaults to @stage/stage-input.json, accepts semantic --outcome and always generates validated JSON, Markdown, template-backed HTML and a durable protocol-summary projection. Raw intake and telemetry remain RUN-local.`
     ],
     [
         "id",
@@ -233,11 +238,12 @@ New registrations use full typed ids such as PRJ-001-dd-flow-playground and shor
         `dd-flow migration - plan and verify mb-upgrade runtime/home data migrations
 
 Usage:
-  dd-flow migration plan --project-root <root> [--source-version <version>] [--target-version <version>] [--run <RUN-ID>] [--backup-path <path>] [--backup-created-at <iso>] [--allow-active true|false] --json
-  dd-flow migration report --project-root <root> [--source-version <version>] [--target-version <version>] [--run <RUN-ID>] [--backup-path <path>] [--backup-created-at <iso>] [--allow-active true|false] --json
+  dd-flow migration plan --project-root <root> [--source-version <version>] [--target-version <version>] [--run <RUN-ID>] [--backup-path <path>] [--backup-created-at <iso>] --json
+  dd-flow migration report --project-root <root> [--source-version <version>] [--target-version <version>] [--run <RUN-ID>] [--backup-path <path>] [--backup-created-at <iso>] --json
   dd-flow migration verify --file <mb-upgrade-migration-report.json> --json
+  dd-flow migration apply --project-root <root> --file <mb-upgrade-migration-report.json> --json
 
-Migration commands are evidence and guardrail helpers for canonical mb-upgrade. They do not silently migrate runtime/home data during ordinary CLI use. Applying migrations remains an explicit mb-upgrade contour with backup, adjacent migration chain, active-state handling, derived artifact regeneration and post-upgrade verification.
+Migration commands are evidence and guardrail helpers for canonical mb-upgrade. They do not silently migrate runtime/home data during ordinary CLI use. Applying migrations is an explicit contour requiring a real verified backup, adjacent migration chain, quiescent shared home, recovery evidence and idempotent rerun.
 
 Related commands:
   dd-flow status --project-root <root> --json
@@ -353,13 +359,14 @@ start is idempotent: if a worker, claimed job, or active merge lock already exis
 Usage:
   dd-flow merge-queue status --project-root <root> --json
   dd-flow merge-queue next --project-root <root> --worker-id <id> [--path <workspace>] --json
+  dd-flow merge-queue claim <protocol-id> [--project-root <root>] --worker-id <id> [--path <workspace>] --json
   dd-flow merge-queue wait-next --project-root <root> --worker-id <id> [--path <workspace>] --timeout <seconds> --poll-interval <seconds> [--acquire-lock true] --json
   dd-flow merge-queue complete <protocol-id> [--project-root <root>] --worker-id <id> [--path <workspace>] --summary <text> --json
   dd-flow merge-queue note <protocol-id> [--project-root <root>] --worker-id <id> --summary <text> --json
   dd-flow merge-queue fail <protocol-id> [--project-root <root>] --worker-id <id> [--path <workspace>] --reason <text> --requeue true|false --json
   dd-flow merge-queue cancel <protocol-id> [--project-root <root>] --reason <text> [--worker-id <id>] [--path <workspace>] [--force] --json
 
-The worker must own the merge lane from the registered merge workspace before claiming, completing, or failing queued protocols. Outputs use queue_item/protocol/claim as the primary contract and retain job as a compatibility alias. note updates the final completion summary after post-complete cleanup and does not require a lane lock. --path defaults to the current working directory. Use --worker-id as the owner identity.
+The worker must own the merge lane from the registered merge workspace before claiming, completing, or failing queued protocols. next remains FIFO; claim <protocol-id> atomically claims only that ready/requeued job. Outputs use queue_item/protocol/claim as the primary contract and retain job as a compatibility alias. note updates the final completion summary after post-complete cleanup and does not require a lane lock. --path defaults to the current working directory. Use --worker-id as the owner identity.
 
 For branch-level integration prefer:
   dd-flow merge bundle status --project-root "$PWD" --path "$PWD" --json
@@ -526,6 +533,12 @@ Usage:
   dd-flow codex home print-env --project-root <root> [--profile <name>] --json
   dd-flow codex home remove --project-root <root> [--profile <name>] --mode keep-shared|remove-owned --json
 
+  dd-flow codex hook handle --event <HookEventName> [--project-root <root>] --json
+
+Managed hooks omit --project-root. Codex supplies cwd in the stdin payload; the
+handler resolves the registered project from cwd. The option is only a manual
+override.
+
 Managed homes isolate dd-flow hooks while sharing selected Codex state from the source home.`
     ],
     [

package/dist/cli/run-cli.js

@@ -1,12 +1,12 @@
 import fs from "node:fs";
-import { createContext } from "../runtime/context.js";
+import { createContext, createRouterContext } from "../runtime/context.js";
 import { helpForArgs } from "./help.js";
 import { AppError, isAppError } from "../shared/errors.js";
 import { writeJson } from "../shared/json.js";
 import { archiveProject, getProjectStatus, migrateProjectIds, registerProject, resolveProject } from "../services/projects.js";
 import { cancelProtocol, getProtocolBlockers, getProtocolStatus, getReadyProtocols, implementProtocol, readyForMerge, registerProtocol, requireProtocol, syncProtocolFromRun, transitionProtocol } from "../services/protocols.js";
 import { blockPlanItem, completePlanItem, getPlanStatus, skipPlanItem, startPlanItem } from "../services/plans.js";
-import { cancelMergeQueueJob, claimNextMergeJob, claimMergeBundle, completeMergeBundle, completeMergeJob, failMergeBundle, failMergeJob, getMergeBundleStatus, getMergeQueueStatus, noteMergeJob, waitNextMergeJob } from "../services/merge-queue.js";
+import { cancelMergeQueueJob, claimNextMergeJob, claimMergeJob, claimMergeBundle, completeMergeBundle, completeMergeJob, failMergeBundle, failMergeJob, getMergeBundleStatus, getMergeQueueStatus, noteMergeJob, waitNextMergeJob } from "../services/merge-queue.js";
 import { getMergeWorkerStatus, oneShotMergeClaim, startMergeWorker, stopProjectMergeWorker } from "../services/merge-worker.js";
 import { cleanupApply, cleanupScan } from "../services/cleanup.js";
 import { getCodexHomeStatus, getCodexHooksStatus, handleCodexHook, initCodexHome, installCodexHooks, planCodexHome, printCodexHomeEnv, printCodexHooks, removeCodexHome, removeCodexHooks } from "../services/hooks.js";
@@ -24,12 +24,13 @@ import { attachFlowRunStage, completeFlowRun, completeFlowRunStage, getFlowRunTi
 import { previewNextEntityId } from "../services/ids.js";
 import { validateSchema } from "../services/schema-validation.js";
 import { preflightMemoryPermissions } from "../services/memory-permissions.js";
-import { assessMigrationImpact, planMigration, verifyMigrationReport } from "../services/migrations.js";
+import { applyMigration, assessMigrationImpact, assertUpgradeRunStorageReady, planMigration, 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 { doctorEngines, engineInfo, installCurrentEngine, listEngines, resolveEngine, resolveOperationProjectRoot, routeArgsThroughEngine } from "../services/engines.js";
+import { doctorEngines, bindRunEngine, engineInfo, installCurrentEngine, listEngines, resolveEngine, resolveExplicitProjectRoot, resolveOperationProjectRoot, routeArgsThroughEngine } from "../services/engines.js";
 import { preflightCliCompatibility } from "../services/compatibility-preflight.js";
+import { classifyCliOperation, requiresExplicitUpgradeAuthorization } from "../services/cli-operation-classifier.js";
 import { renderWorkerPrompt } from "../services/prompts.js";
 import { finishStage, startStage } from "../services/stage-lifecycle.js";
 const defaultIo = {
@@ -58,20 +59,27 @@ export async function runCli(args, io = defaultIo, env = process.env) {
             io.stdout.write(`${help}\n`);
             return 0;
         }
-        const context = createContext(env);
+        const classification = classifyCliOperation(output.args, env);
+        if (requiresExplicitUpgradeAuthorization(output.args) && classification.mode !== "mb_upgrade") {
+            throw new AppError("upgrade_authorization_required", "This mb-upgrade command requires the explicit mb-upgrade authorization marker and allowlisted target context", 1, {
+                operation: classification.operation,
+                required_marker: "DD_FLOW_COMPATIBILITY_MODE=mb-upgrade"
+            });
+        }
+        const routerContext = createRouterContext(env);
         emitHumanProgress(io, output, progress, "start");
-        const scopeProjectRoot = resolveOperationProjectRoot(context, output.args);
-        const routed = await routeArgsThroughEngine(context, output.args, io, io.stdin, env, scopeProjectRoot);
+        const scopeProjectRoot = resolveProjectRootBeforeRouting(output.args, env);
+        const routed = await routeArgsThroughEngine(routerContext, output.json ? [...output.args, "--json"] : output.args, io, io.stdin, env, scopeProjectRoot);
         if (routed?.routed && !routed.inProcess) {
             emitHumanProgress(io, output, progress, "done");
             return routed.exitCode;
         }
         const dispatchContext = routed?.inProcess
-            ? createContext({ ...env, DD_FLOW_ENGINE_MODE: "1", DD_FLOW_ENGINE_HOME: "in-process", DD_FLOW_ROUTED_FROM: getCliVersionReport().cli.version })
-            : context;
+            ? createContext({ ...env, DD_FLOW_ENGINE_MODE: "1", DD_FLOW_ENGINE_HOME: "in-process", DD_FLOW_ROUTED_FROM: getCliVersionReport().cli.version }, databaseModeForCommand(output.args, classification))
+            : createContext(env, databaseModeForCommand(output.args, classification));
         preflightCliCompatibility(dispatchContext, output.args, env, scopeProjectRoot);
-        const result = await dispatch(output.args, dispatchContext, io, scopeProjectRoot);
-        const refreshWarnings = refreshDashboardsAfterMutation(context, output.args, result, scopeProjectRoot);
+        const result = await dispatch(output.args, dispatchContext, io, scopeProjectRoot, classification);
+        const refreshWarnings = refreshDashboardsAfterMutation(dispatchContext, output.args, result, scopeProjectRoot);
         const resultWithWarnings = addWarnings(result, refreshWarnings);
         emitHumanProgress(io, output, progress, "done");
         const payload = attachProgress(resultWithWarnings, progress, output);
@@ -94,6 +102,34 @@ export async function runCli(args, io = defaultIo, env = process.env) {
         return isAppError(error) ? error.exitCode : 1;
     }
 }
+function resolveProjectRootBeforeRouting(args, env) {
+    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);
+    }
+    catch {
+        return null;
+    }
+}
+function databaseModeForCommand(args, classification) {
+    const [family, command] = args;
+    if (family === "engine" ||
+        family === "version" ||
+        family === "schema" ||
+        family === "canon" && command === "resolve" ||
+        classification.mode === "read_only_diagnostics" ||
+        classification.mode === "mb_upgrade" && (family === "status" ||
+            family === "engine" ||
+            family === "migration" && ["impact", "plan", "report", "verify", "apply"].includes(command ?? "") ||
+            family === "memory" && command === "permissions" ||
+            family === "dashboard" && ["data", "open"].includes(command ?? "") ||
+            family === "session" && command === "status"))
+        return "read_existing";
+    return "initialize";
+}
 function renderHumanError(payload) {
     const lines = [`dd-flow: ${payload.error.message}`];
     const details = recordObject(payload.error.details);
@@ -380,11 +416,11 @@ function stringValue(value) {
 function shortSha(value) {
     return value ? value.slice(0, 12) : "unknown";
 }
-async function dispatch(args, context, io, scopeProjectRoot = null) {
+async function dispatch(args, context, io, scopeProjectRoot = null, classification = classifyCliOperation(args, context.env)) {
     const [family, command, ...rest] = args;
     const parsed = parseArgs(rest);
     if (family === "engine") {
-        return dispatchEngine(context, command, parsed);
+        return dispatchEngine(context, command, parsed, classification);
     }
     if (family === "status") {
         const rootParsed = parseArgs([command ?? "", ...rest]);
@@ -541,23 +577,28 @@ async function dispatch(args, context, io, scopeProjectRoot = null) {
     }
     if (family === "stage" && command === "start") {
         const dir = optionalOption(parsed, "dir");
+        const bootstrap = hasOption(parsed, "bootstrap");
+        const subject = optionalOption(parsed, "subject");
+        const intakeFile = optionalOption(parsed, "intake-file");
+        const sessionId = optionalOption(parsed, "session-id");
         return startStage(context, {
             projectRoot: requiredOption(parsed, "project-root"),
-            runId: requiredPosition(parsed, 0, "run-id"),
+            ...(bootstrap ? { bootstrap: { subject: subject ?? requiredOption(parsed, "subject"), ...(intakeFile ? { intakeFile } : {}) } } : { runId: requiredPosition(parsed, 0, "run-id") }),
             stage: requiredOption(parsed, "stage"),
+            ...(sessionId ? { sessionId } : {}),
             ...(dir ? { dir } : {})
         });
     }
     if (family === "stage" && command === "finish") {
         const dir = optionalOption(parsed, "dir");
-        const status = optionalOption(parsed, "status");
+        const outcome = optionalOption(parsed, "outcome") ?? optionalOption(parsed, "status");
         const semanticFile = optionalOption(parsed, "semantic-file") ?? optionalOption(parsed, "data");
         return finishStage(context, {
             projectRoot: requiredOption(parsed, "project-root"),
             runId: requiredPosition(parsed, 0, "run-id"),
             stage: requiredOption(parsed, "stage"),
             ...(dir ? { dir } : {}),
-            ...(status ? { status } : {}),
+            ...(outcome ? { outcome } : {}),
             ...(semanticFile ? { semanticFile } : {})
         });
     }
@@ -592,13 +633,13 @@ async function dispatch(args, context, io, scopeProjectRoot = null) {
         return dispatchDashboard(context, command, parsed);
     }
     if (family === "schema") {
-        return dispatchSchema(command, parsed);
+        return dispatchSchema(context, command, parsed);
     }
     if (family === "memory") {
         return dispatchMemory(command, parsed);
     }
     if (family === "migration") {
-        return dispatchMigration(context, command, parsed);
+        return dispatchMigration(context, command, parsed, classification);
     }
     if (family === "codex" && command === "hooks") {
         return dispatchCodexHooks(context, parsed);
@@ -614,7 +655,7 @@ async function dispatch(args, context, io, scopeProjectRoot = null) {
     }
     throw new AppError("usage", `Unknown command: ${args.join(" ") || "<empty>"}`, 2);
 }
-function dispatchEngine(context, command, parsed) {
+function dispatchEngine(context, command, parsed, classification) {
     if (command === "install") {
         return installCurrentEngine(context, { force: hasOption(parsed, "force") });
     }
@@ -625,14 +666,32 @@ function dispatchEngine(context, command, parsed) {
         return engineInfo(context, { packageName: optionalOption(parsed, "package"), version: optionalOption(parsed, "version") });
     }
     if (command === "resolve") {
-        return resolveEngine(context, { projectRoot: optionalOption(parsed, "project-root") ?? optionalOption(parsed, "root") });
+        return resolveEngine(context, {
+            projectRoot: optionalOption(parsed, "project-root") ?? optionalOption(parsed, "root"),
+            env: context.env,
+            classification
+        });
     }
     if (command === "doctor") {
-        return doctorEngines(context, { projectRoot: optionalOption(parsed, "project-root") ?? optionalOption(parsed, "root") });
+        return doctorEngines(context, {
+            projectRoot: optionalOption(parsed, "project-root") ?? optionalOption(parsed, "root"),
+            env: context.env,
+            classification
+        });
+    }
+    if (command === "bind-run") {
+        return bindRunEngine(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            runId: requiredPosition(parsed, 0, "run-id"),
+            packageName: optionalOption(parsed, "package"),
+            engineVersion: requiredOption(parsed, "engine-version"),
+            integrityChecksum: optionalOption(parsed, "integrity-checksum"),
+            reason: requiredOption(parsed, "reason")
+        });
     }
     throw new AppError("usage", `Unknown engine command: ${command ?? "<empty>"}`, 2);
 }
-function dispatchMigration(context, command, parsed) {
+function dispatchMigration(context, command, parsed, classification) {
     if (command === "impact")
         return assessMigrationImpact(context, { projectRoot: requiredOption(parsed, "project-root"), ...(optionalOption(parsed, "target-version") ? { targetVersion: optionalOption(parsed, "target-version") } : {}), ...(optionalOption(parsed, "mode") ? { mode: optionalOption(parsed, "mode") } : {}) });
     if (command === "plan" || command === "report") {
@@ -643,12 +702,26 @@ function dispatchMigration(context, command, parsed) {
             runId: optionalOption(parsed, "run"),
             backupPath: optionalOption(parsed, "backup-path"),
             backupCreatedAt: optionalOption(parsed, "backup-created-at"),
-            allowActive: parseOptionalBoolean(optionalOption(parsed, "allow-active"), "allow-active") ?? false
+            allowActive: false,
+            classification
         });
     }
     if (command === "verify") {
         return verifyMigrationReport(context, { file: requiredOption(parsed, "file") });
     }
+    if (command === "apply") {
+        return applyMigration(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            sourceVersion: optionalOption(parsed, "source-version"),
+            targetVersion: optionalOption(parsed, "target-version"),
+            runId: optionalOption(parsed, "run"),
+            backupPath: optionalOption(parsed, "backup-path"),
+            backupCreatedAt: optionalOption(parsed, "backup-created-at"),
+            reportFile: optionalOption(parsed, "file"),
+            allowActive: false,
+            classification
+        });
+    }
     throw new AppError("usage", `Unknown migration command: ${command ?? "<empty>"}`, 2);
 }
 function dispatchCanon(context, command, parsed) {
@@ -677,6 +750,14 @@ function dispatchMergeQueue(context, command, parsed, scopeProjectRoot) {
             workspacePath: workspacePathOption(parsed)
         });
     }
+    if (command === "claim") {
+        return claimMergeJob(context, {
+            protocolId: requiredPosition(parsed, 0, "protocol-id"),
+            projectRoot: requiredOptionOrScope(parsed, scopeProjectRoot, "project-root"),
+            workerId: requiredWorkerId(parsed),
+            workspacePath: workspacePathOption(parsed)
+        });
+    }
     if (command === "wait-next") {
         return waitNextMergeJob(context, {
             projectRoot: requiredOptionOrScope(parsed, scopeProjectRoot, "project-root"),
@@ -882,6 +963,9 @@ function dispatchSession(context, command, parsed) {
 }
 function dispatchRun(context, command, parsed) {
     if (command === "start") {
+        if (optionalOption(parsed, "flow-kind") === "mb-upgrade") {
+            assertUpgradeRunStorageReady(context, requiredOption(parsed, "project-root"));
+        }
         const protocolOverrides = readOptionalJsonFile(optionalOption(parsed, "protocol-override-file"));
         return startFlowRun(context, {
             projectRoot: requiredOption(parsed, "project-root"),
@@ -1139,7 +1223,7 @@ function withDashboardGuidance(action, target, result, options = {}) {
         related_commands: relatedDashboardCommands(action, target.kind)
     };
 }
-function dispatchSchema(command, parsed) {
+function dispatchSchema(context, command, parsed) {
     if (command === "validate") {
         const schemaDir = optionalOption(parsed, "schema-dir");
         const projectRoot = optionalOption(parsed, "project-root");
@@ -1147,7 +1231,8 @@ function dispatchSchema(command, parsed) {
             schemaName: requiredOption(parsed, "schema"),
             file: requiredOption(parsed, "file"),
             ...(schemaDir ? { schemaDir } : {}),
-            ...(projectRoot ? { projectRoot } : {})
+            ...(projectRoot ? { projectRoot } : {}),
+            ddFlowHome: context.ddFlowHome
         });
     }
     throw new AppError("usage", `Unknown schema command: ${command ?? "<empty>"}`, 2);
@@ -1327,11 +1412,15 @@ function dispatchCodexHome(context, parsed) {
 function dispatchCodexHook(context, parsed, stdin) {
     const action = requiredPosition(parsed, 0, "codex hook action");
     if (action === "handle") {
-        return handleCodexHook(context, {
+        const result = handleCodexHook(context, {
             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);
 }
@@ -1670,7 +1759,7 @@ function projectRootForLaneMutation(command, parsed) {
     return ["acquire", "heartbeat", "release", "wait-acquire"].includes(action) ? requiredOption(parsed, "project-root") : undefined;
 }
 function projectRootForMergeQueueMutation(context, command, parsed) {
-    if (["next", "wait-next"].includes(command ?? "")) {
+    if (["next", "wait-next", "claim"].includes(command ?? "")) {
         return requiredOption(parsed, "project-root");
     }
     if (["complete", "fail", "cancel"].includes(command ?? "")) {
@@ -1691,7 +1780,7 @@ function isScopedProtocolMutation(family, command) {
     if (family === "worktree")
         return ["create", "bootstrap", "close"].includes(command ?? "");
     if (family === "merge-queue")
-        return ["complete", "note", "fail", "cancel"].includes(command ?? "");
+        return ["claim", "complete", "note", "fail", "cancel"].includes(command ?? "");
     return false;
 }
 function projectRootFromResult(result) {

package/dist/domain/flow-contract.js

@@ -64,6 +64,17 @@ export function loadProjectFlowContract(projectRoot) {
     if (!contractPath) {
         return defaultFlowContract;
     }
+    return loadFlowContractFile(contractPath);
+}
+/**
+ * Canonical-only flows execute against the pinned canonical contract before
+ * the target project flow pack is synchronized. Keep this path explicit so a
+ * stale project-local contract cannot become the upgrade RUN authority.
+ */
+export function loadCanonicalFlowContract(flowRoot) {
+    return loadFlowContractFile(path.join(flowRoot, "flow-contract.json"));
+}
+function loadFlowContractFile(contractPath) {
     try {
         const value = readFlowContractObject(contractPath);
         validateFlowContractStructure(value);
@@ -332,7 +343,6 @@ function flagStrength(key, value, definition) {
         "subagents.route": ["self_check", "grouped_subagent", "focused_subagent", "mixed"],
         "subagents.grouping": ["off", "allowlisted"],
         "subagents.pool_fallback": ["one", "runtime"],
-        "observability.detail": ["compact", "normal", "full"],
         "knowledge.extract": ["skip", "conditional", "required"],
         "knowledge.promote": ["skip", "conditional", "required"],
         "workspace.bootstrap.mode": ["not_required", "revalidate", "required"],
@@ -362,10 +372,10 @@ function numberValue(value) {
 export function normalizeFlowContract(value) {
     const version = requireNumber(value.version, "/version");
     const id = requireString(value.id, "/id");
-    if (version === 4 || version === 5) {
+    if (version === 4 || version === 5 || version === 6) {
         return normalizeCanonicalRuntimeContract(value, id, version);
     }
-    if (version > 5)
+    if (version > 6)
         fail("/version", `unsupported flow-contract version: ${version}`);
     if (version === 3 && !/^dd-flow-canonical-[0-9]{4}-[0-9]{2}$/.test(id)) {
         fail("/id", "must identify a canonical version 3 flow contract");
@@ -462,7 +472,8 @@ function normalizeCanonicalRuntimeContract(value, id, version) {
             "flow_run_snapshot.v1",
             "session_coverage_units.v1",
             "privacy_safe_observability.v1",
-            ...(version === 5 ? ["canonical_protocol_plan.v1"] : [])
+            ...(version >= 5 ? ["canonical_protocol_plan.v1"] : []),
+            ...(version >= 6 ? ["stage_bootstrap_context_packet.v1"] : [])
         ],
         stages,
         transitions,

package/dist/domain/session-coverage.js

@@ -0,0 +1,88 @@
+export function reconcileSessionCoverageRows(sessions) {
+    const sessionCounts = countValues(sessions.map((session) => session.session_id));
+    const duplicateSessionIds = duplicates(sessionCounts);
+    const invalidSessionIds = [];
+    const parsed = sessions.map((session) => {
+        try {
+            return { session, units: normalizeCoverageUnits(JSON.parse(session.coverage_units_json || "[]")) };
+        }
+        catch {
+            invalidSessionIds.push(session.session_id);
+            return { session, units: [] };
+        }
+    });
+    const orchestrators = parsed.filter(({ session }) => session.session_kind === "orchestrator");
+    const workers = parsed.filter(({ session }) => session.session_kind !== "orchestrator");
+    const expectedCounts = countValues(orchestrators.flatMap(({ units }) => units.map((unit) => unit.unit_id)));
+    const expectedUnitIds = [...expectedCounts.keys()].sort();
+    const duplicateExpectedUnitIds = duplicates(expectedCounts);
+    const observedOwners = new Map();
+    for (const { session, units } of workers) {
+        for (const unit of units) {
+            const owners = observedOwners.get(unit.unit_id) ?? [];
+            owners.push(session.session_id);
+            observedOwners.set(unit.unit_id, owners);
+        }
+    }
+    const observedUnitIds = [...observedOwners.keys()].sort();
+    const missingUnitIds = expectedUnitIds.filter((unitId) => !observedOwners.has(unitId));
+    const duplicateUnitIds = [...observedOwners.entries()]
+        .filter(([, owners]) => new Set(owners).size > 1)
+        .map(([id]) => id)
+        .sort();
+    const diagnostics = [];
+    if (orchestrators.length === 0)
+        diagnostics.push("orchestrator_session_missing");
+    if (orchestrators.length > 1)
+        diagnostics.push("multiple_orchestrator_sessions");
+    if (workers.length > 0 && expectedUnitIds.length === 0)
+        diagnostics.push("expected_worker_units_missing");
+    if (missingUnitIds.length > 0)
+        diagnostics.push("expected_worker_units_unobserved");
+    if (duplicateUnitIds.length > 0 || duplicateExpectedUnitIds.length > 0)
+        diagnostics.push("duplicate_coverage_binding");
+    if (duplicateSessionIds.length > 0)
+        diagnostics.push("duplicate_session_binding");
+    if (invalidSessionIds.length > 0)
+        diagnostics.push("invalid_coverage_units");
+    const unavailable = orchestrators.length === 0 || invalidSessionIds.length > 0;
+    const partial = orchestrators.length !== 1
+        || (workers.length > 0 && expectedUnitIds.length === 0)
+        || missingUnitIds.length > 0
+        || duplicateUnitIds.length > 0
+        || duplicateExpectedUnitIds.length > 0
+        || duplicateSessionIds.length > 0;
+    return {
+        status: unavailable ? "unavailable" : partial ? "partial" : "complete",
+        expected_unit_ids: expectedUnitIds,
+        observed_unit_ids: observedUnitIds,
+        missing_unit_ids: missingUnitIds,
+        duplicate_unit_ids: duplicateUnitIds,
+        duplicate_expected_unit_ids: duplicateExpectedUnitIds,
+        duplicate_session_ids: duplicateSessionIds,
+        orchestrator_session_ids: orchestrators.map(({ session }) => session.session_id).sort(),
+        invalid_session_ids: [...new Set(invalidSessionIds)].sort(),
+        diagnostics
+    };
+}
+function normalizeCoverageUnits(value) {
+    if (!Array.isArray(value))
+        throw new Error("coverage_units must be an array");
+    return value.map((item) => {
+        if (!item || typeof item !== "object" || Array.isArray(item))
+            throw new Error("coverage unit must be an object");
+        const unitId = item.unit_id;
+        if (typeof unitId !== "string" || unitId.length === 0)
+            throw new Error("coverage unit requires unit_id");
+        return { unit_id: unitId };
+    });
+}
+function countValues(values) {
+    const counts = new Map();
+    for (const value of values)
+        counts.set(value, (counts.get(value) ?? 0) + 1);
+    return counts;
+}
+function duplicates(counts) {
+    return [...counts.entries()].filter(([, count]) => count > 1).map(([id]) => id).sort();
+}