@deksden-com/dd-flow-cli 0.9.0-beta.8 → 0.9.0-beta.80

package/dist/cli/command-inputs.js

@@ -0,0 +1,300 @@
+import { AppError } from "../shared/errors.js";
+import { parseCommandArgs } from "../services/lifecycle-command.js";
+import { isUpgradeAllowlisted } from "../services/cli-operation-classifier.js";
+const words = (value) => value.split(" ").filter(Boolean);
+const route = (positions, required = "", values = "", switches = "", repeatable = "", enums = {}) => ({
+    positions: typeof positions === "number" ? [positions, positions] : positions,
+    required: words(required), values: words(`${required} ${values}`), switches: words(switches), repeatable: words(repeatable), enums
+});
+const project = "project-root";
+const scoped = "project-root"; // Optional when the router resolves a unique retained scope.
+const lifecycle = "invocation-id hook-event-id";
+const worker = "worker-id";
+const control = "project-root run";
+export const commandInputs = {
+    "version": route(0),
+    "status": route(0, "", "root project-root", "check-registry"),
+    "project register": route(0, "root"),
+    "project status": route(0, "root"),
+    "project summary": route(0, project, "write"),
+    "project resolve": route(1),
+    "project archive": route([0, 1], "reason", "root"),
+    "project migrate-ids": route(0, "root", "", "apply"),
+    "project config status": route(0, project),
+    "project config set": route(0, `${project} key value`),
+    "protocol register": route(1, project, "workspace-path"),
+    "protocol status": route(1, "", scoped),
+    "protocol branch-status": route([0, 1], "", `${scoped} path`),
+    "protocol ready": route(0, project),
+    "protocol blockers": route(1, project),
+    "protocol implement": route(1, "", `${scoped} reason`, "force"),
+    "protocol ready-for-merge": route(1, "", scoped),
+    "protocol transition": route(1, "to", `${scoped} payload-file json-file reason`, "force"),
+    "transition": route(1, "to", `${scoped} payload-file json-file reason`, "force"),
+    "protocol sync-from-run": route(1, "run", `${scoped} target`),
+    "protocol cancel": route(1, "reason", `${scoped} close-sessions cancel-queue release-locks worktree`, "force"),
+    "plan status": route(1, "", scoped),
+    "plan reviews": { ...route(0), retired: "PLAN review dispatch moved to: dd-flow plan-review dispatch <RUN>" },
+    "plan item start": route(2, "", scoped),
+    "plan item done": route(2, "summary", `${scoped} evidence`, "", "evidence"),
+    "plan item block": route(2, "reason user-required", scoped),
+    "plan item skip": route(2, "reason", scoped),
+    "plan-review dispatch": route(1, "", scoped),
+    "prompt render": route(0, `${project} run stage profile`, "workspace-root task-file plan-item"),
+    "stage start": { ...route([0, 1], `${project} stage`, `${lifecycle} dir subject intake-file context-file context-sha256`, "bootstrap intake-stdin require-session-binding"), contextualPaths: words("project-root intake-file context-file") },
+    "stage finish": { ...route(1, `${project} stage`, `${lifecycle} dir semantic-file data result-file outcome decision-file verification-file retry-check reason request work`, "result-stdin"), contextualPaths: words("project-root semantic-file result-file decision-file verification-file") },
+    "stage pause": { ...route(1, `${project} stage work`, lifecycle, "question-stdin"), contextualPaths: ["project-root"] },
+    "stage resume": { ...route(1, `${project} stage work`, lifecycle, "answer-stdin"), contextualPaths: ["project-root"] },
+    "stage block": route(1, `${project} stage work kind code`, "", "summary-stdin retryable", "", { kind: ["engine", "harness", "environment"] }),
+    "stage unblock": route(1, `${project} stage work`),
+    "stage fanout status": route(1, "stage", scoped),
+    "stage fanout dispatch": route(1, "stage", scoped),
+    "stage fanout reconcile": route(1, "stage observations-file", scoped),
+    "stage native observe": route(1, "stage observations-file", scoped),
+    "work status": route(1, project),
+    "work add-batch": route(0, "parent file", scoped),
+    "work ls": route(0, "", `${scoped} run parent status limit`, "ready include-results", "", { status: ["created", "running", "paused", "completed", "failed", "cancelled"] }),
+    "work show": route(1, "", scoped),
+    "work repair add": route(0, "run", `${scoped} origin-work from-check from-finding from-unresolved check-ref verification-file`, "task-stdin", "origin-work from-finding from-unresolved check-ref"),
+    "work deps add": route(1, "on", scoped, "", "on"),
+    "work deps remove": route(1, "on", scoped, "", "on"),
+    "work deps list": route(1, "", scoped),
+    "work deps clear": route(1, "", scoped),
+    "work delete": route(1, "", scoped),
+    "work launch": route(1, "", `${scoped} stage`),
+    "work start": { ...route(1, "", `${scoped} ${lifecycle} recovery-id`), contextualPaths: ["project-root"] },
+    "work finish": { ...route(1, "", `${scoped} ${lifecycle} result-file retry-check reason`, "result-stdin"), contextualPaths: words("project-root result-file") },
+    "work fail": { ...route(1, "reason", `${scoped} ${lifecycle}`), contextualPaths: ["project-root"] },
+    "work cancel": route(1, "reason", scoped),
+    "work retry": route(1, "reason", scoped),
+    "session register": { ...route(0, "", `${scoped} ${lifecycle} payload-base64 payload-json payload-file session-id`), contextualPaths: words("project-root payload-file") },
+    "session status": route(0, project, "session-id worker-id"),
+    "session stop": route(0, `${project} session-id reason`),
+    "session stop-worker": route(0, `${project} worker-id reason`),
+    "session usage sync": route(0, project, "session-id"),
+    "run start": route(0, `${project} flow-kind subject-type subject-id slug`, "workspace-root next-action preset task-profile-file execution-routing-file protocol-override-file flag", "", "flag"),
+    "run prepare-vnext-specify": route(0, `${project} slug`, "execution-routing-file"),
+    "run status": route(1, project),
+    "run list": route(0, project),
+    "run timeline": route(1, project, "hide", "", "hide"),
+    "run config status": route(1, project),
+    "run config set": route(1, `${project} key value reason`),
+    "run vars ls": route(1, project),
+    "run vars get": route(1, `${project} key`),
+    "run vars set": route(1, `${project} key value`),
+    "run flags status": route(1, project),
+    "run flags revise": route(1, `${project} expected-revision idempotency-key`, "flag preset reason", "allow-downgrade", "flag"),
+    "run attach-stage": route(1, `${project} stage dir status`, "data-schema-id"),
+    "run complete-stage": route(1, `${project} stage status`, "stage-report dashboard data data-schema-id report alias", "", "alias"),
+    "run complete": { ...route(0), retired: "run complete is retired; only an operator may use run override" },
+    "run override": route(1, `${project} status reason`, "verdict next-action", "", "", { status: ["cancelled", "failed"] }),
+    "run capacity record": route(1, `${project} available-slots`),
+    "run recovery inspect": route(1, project),
+    "run recovery begin": route(1, `${project} interruption-json`),
+    "run recovery seal": route(1, `${project} recovery-id settlement-json`),
+    "run recovery capture": route(1, `${project} recovery-id capture-path`),
+    "run recovery resume": route(1, `${project} recovery-id daemon-id harness native-session-id`),
+    "run recovery accept": { ...route(1, `${project} recovery-id`, lifecycle), contextualPaths: ["project-root"] },
+    "run snapshot bootstrap create": route(0, `${project} output`),
+    "run snapshot bootstrap restore": route(0, `${project} snapshot`),
+    "run snapshot create": route(1, `${project} output`, "recovery-id stage-entry", "candidate incomplete"),
+    "run snapshot restore": route(0, `${project} snapshot`, "execution-routing-file recovery-id"),
+    "run fork": route(0, "from output engine-version request-id", "integrity-checksum"),
+    "run drive status": route(0, control, "after"),
+    "run drive launch": route(0, `${control} request-id context-file context-sha256`, "stop-after capture-root"),
+    "run drive serve": route(0, `${control} controller-id`),
+    "run drive answer": route(0, `${control} request-id pause-id answer-file`),
+    "run drive context": route(0, `${control} controller-id request-id stage context-file context-sha256`),
+    "run control status": route(0, control),
+    "run control reconcile": route(0, `${control} control-id request-id`),
+    "run control resume": route(0, `${control} request-id from`, "wait-ms"),
+    "run control serve": route(0, `${control} control-id`),
+    "run control pause": route(0, `${control} request-id`, "grace-ms wait-ms escalate", "force"),
+    "run control stop": route(0, `${control} request-id`, "grace-ms wait-ms escalate", "force"),
+    "runtime scope fence": route(0, "scope-id request-id"),
+    "runtime scope status": route(0, "scope-id"),
+    "runtime scope stop": route(0, "scope-id request-id"),
+    "runtime scope control": route(0, "scope-id request-id mode", "manifest-json", "", "", { mode: ["pause", "stop"] }),
+    "runtime scope serve": route(0, "scope-id generation"),
+    "runtime scope resume": route(0, "scope-id request-id generation capture-key"),
+    "runtime scope reconcile": route(0, "scope-id generation request-id"),
+    "runtime process check-admission": route(0, "id lease-token"),
+    "runtime process start": route(0, `${control} command ports ready-port`, "ready-path ready-timeout-ms"),
+    "runtime process stop": route(0, "id lease-token", "grace-ms"),
+    "runtime process register": route(0, "kind owner", "lease-ms budget-json project-id run pid process-group-id owner-pid work check operation stdout stderr harness dispatch-barrier role state-dir adapter-executable"),
+    "runtime process confirm": route(0, "id lease-token pid", "owner-pid lease-ms process-group-id"),
+    "runtime process heartbeat": route(0, "id lease-token", "lease-ms"),
+    "runtime process admission": route(0, "id lease-token owner state-dir", "daemon-id operation-id operation native-session-id prompt-sha256"),
+    "runtime process release-turn": route(0, "id lease-token owner daemon-id", "operation-id observation-file"),
+    "runtime process finish": route(0, "id lease-token state", "reason", "", "", { state: ["stopped", "failed"] }),
+    "runtime process status": route(0),
+    "runtime process reconcile": route(0, "owner", "grace-ms"),
+    "lane status": route(0, project, "lane"),
+    "lane waiters": route(0, project, "lane"),
+    "lane waiter cancel": route(0, `${project} lane ${worker} reason`),
+    "lane workspace set": route(0, `${project} lane path`, "branch"),
+    "lane workspace check": route(0, `${project} lane path`),
+    "lane lock acquire": route(0, `${project} lane ${worker} reason`, "path ttl"),
+    "lane lock heartbeat": route(0, `${project} lane ${worker}`, "path lease-token ttl"),
+    "lane lock release": route(0, `${project} lane ${worker} reason`, "path lease-token"),
+    "lane lock status": route(0, `${project} lane`),
+    "lane lock wait": route(0, `${project} lane ${worker}`, "path timeout poll-interval"),
+    "lane lock wait-acquire": route(0, `${project} lane ${worker} reason`, "path timeout poll-interval ttl"),
+    "merge-queue status": route(0, "", scoped),
+    "merge-queue next": route(0, worker, `${scoped} path`),
+    "merge-queue claim": route(1, worker, `${scoped} path`),
+    "merge-queue wait-next": route(0, worker, `${scoped} path timeout poll-interval acquire-lock`),
+    "merge-queue complete": route(1, `${worker} summary`, `${scoped} path`),
+    "merge-queue fail": route(1, `${worker} reason requeue`, `${scoped} path`),
+    "merge-queue note": route(1, `${worker} summary`, scoped),
+    "merge-queue cancel": route(1, "reason", `${scoped} worker-id path`, "force"),
+    "merge serve": route(0, "agent-profile", "poll-seconds max-parallel-projects", "once"),
+    "merge server status": route(0),
+    "merge server stop": route(1),
+    "merge apply": route(1, `${project} work`),
+    "merge repair": route(1, project),
+    "merge request status": route(1, project),
+    "merge request route": route(1, `${project} mode reason`, "", "", "", { mode: ["same_session", "server"] }),
+    "merge status": route(0, project, "path"),
+    "merge bundle status": route(0, project, "path"),
+    "merge bundle claim": route(0, `${project} ${worker}`, "path"),
+    "merge bundle complete": route(0, `${project} ${worker} summary`, "path"),
+    "merge bundle fail": route(0, `${project} ${worker} reason requeue`, "path"),
+    "merge one-shot": route(0, `${project} ${worker}`, "path"),
+    "merge-worker status": route(0, project),
+    "merge-worker start": route(0, `${project} ${worker}`, "path branch"),
+    "merge-worker stop": route(0, `${project} reason`, worker),
+    "engine install": route(0, "", "", "force"),
+    "engine list": route(0),
+    "engine info": route(0, "", "package version"),
+    "engine resolve": route(0, "", "root project-root"),
+    "engine doctor": route(0, "", "root project-root"),
+    "engine bind-run": route(1, `${project} engine-version reason`, "package integrity-checksum"),
+    "canon register": route(0, "root"),
+    "canon status": route(0, "", "root"),
+    "canon resolve": route(0, "", "root"),
+    "migration impact": route(0, project, "target-version mode"),
+    "migration plan": route(0, project, "source-version target-version run backup-path backup-created-at"),
+    "migration report": route(0, project, "source-version target-version run backup-path backup-created-at"),
+    "migration verify": route(0, "file"),
+    "migration apply": route(0, project, "source-version target-version run backup-path backup-created-at file"),
+    "storage migrate-writer": route(0, "database backup", "", "offline"),
+    "cleanup scan": route(0, project),
+    "cleanup apply": route(0, `${project} plan-file reason`, "", "force"),
+    "worktree plan": route(0, "protocol-id", scoped),
+    "worktree create": route(0, "protocol-id branch base path", scoped),
+    "worktree status": route(0, "protocol-id", scoped),
+    "worktree bootstrap": route(0, "protocol-id", scoped),
+    "worktree close": route(0, "protocol-id mode", scoped, "", "", { mode: ["keep", "remove"] }),
+    "codex home plan": route(0, project, "profile source-home target-home"),
+    "codex home init": route(0, project, "profile source-home target-home"),
+    "codex home status": route(0, project, "profile"),
+    "codex home print-env": route(0, project, "profile"),
+    "codex home remove": route(0, `${project} mode`, "profile"),
+    "codex hooks print": route(0, project, "target profile"),
+    "codex hooks status": route(0, project, "target profile"),
+    "codex hooks install": route(0, project, "target profile", "yes"),
+    "codex hooks remove": route(0, project, "target profile", "yes"),
+    "codex hook handle": route(0, "event", scoped),
+    "zcode hook handle": route(0, project),
+    "zcode invocation prepare": route(0),
+    "zcode event handle": route(0, project),
+    "zcode usage ingest": route(0, project),
+    "grok event handle": route(0, project),
+    "grok usage ingest": route(0, project),
+    "opencode event handle": route(0, project),
+    "opencode usage ingest": route(0, project),
+    "droid event handle": route(0, project),
+    "droid usage ingest": route(0, project),
+    "agy event handle": route(0, project),
+    "agy usage ingest": route(0, project),
+    "stat usage": route(0, `${project} run`, "group-by session stage"),
+    "stat run sessions ls": route(0, `${project} run`),
+    "id next": route(0, `${project} type slug`, "", "", "", { type: ["protocol", "prt", "run", "work", "wrk"] }),
+    "integration cmux status": route(0, project),
+    "dashboard data": route(0, "", "project project-root protocol", "global"),
+    "dashboard render": route(0, "", "project project-root protocol output format"),
+    "dashboard render-global": route(0, "", "output format"),
+    "dashboard open": route(0, "", "project project-root protocol viewer format"),
+    "dashboard refresh": route(0, "", "project project-root protocol open format output", "all"),
+    "dashboard refresh-global": route(0, "", "output format"),
+    "schema validate": route(0, "schema file", "schema-dir project-root run"),
+    "memory permissions preflight": route(0, "root memory-bank flow mode", "tasks")
+};
+export function contextualPathOptionsForLifecycle(operation) {
+    const key = operation === "recovery_accept" ? "run recovery accept" : operation.replaceAll("_", " ");
+    return new Set(commandInputs[key]?.contextualPaths ?? []);
+}
+const flag = "__dd_flow_flag__";
+const positiveInteger = new Set(words("limit lease-ms pid owner-pid process-group-id ready-timeout-ms max-parallel-projects expected-revision"));
+const nonnegativeInteger = new Set(words("after generation wait-ms grace-ms available-slots"));
+const positiveNumber = new Set(words("ttl poll-interval poll-seconds"));
+const booleans = new Set(words("write close-sessions cancel-queue release-locks user-required requeue acquire-lock"));
+export function prepareCommandRoute(args) {
+    const parsed = parseCommandArgs(args);
+    const key = Object.keys(commandInputs).filter(key => key.split(" ").every((part, index) => parsed.positional[index] === part))
+        .sort((a, b) => b.split(" ").length - a.split(" ").length)[0];
+    const reject = (message, parameter) => { throw new AppError("usage", message, 2, { phase: "prepare", effect: "no_effect", recoverable: true, ...(parameter ? { parameter } : {}) }); };
+    if (!key)
+        return reject("Unknown command; use dd-flow --help");
+    const contract = commandInputs[key];
+    if (contract.retired)
+        reject(contract.retired);
+    const prefixLength = key.split(" ").length;
+    const positionCount = parsed.positional.length - prefixLength;
+    if (positionCount < contract.positions[0] || positionCount > contract.positions[1])
+        reject(`${key} expects ${contract.positions[0] === contract.positions[1] ? contract.positions[0] : `${contract.positions[0]}..${contract.positions[1]}`} positional argument(s)`);
+    for (const [name, values] of parsed.options) {
+        if (key.startsWith("merge-queue ") && name === "session-id")
+            reject("--session-id is no longer accepted on merge-queue commands; use --worker-id", name);
+        const upgrade = ["compatibility-mode", "mb-upgrade-mode"].includes(name);
+        if (upgrade && !isUpgradeAllowlisted(args))
+            reject(`${key} does not support explicit upgrade mode`, name);
+        if (!upgrade && !contract.values.includes(name) && !contract.switches.includes(name))
+            reject(`${key} does not accept --${name}`, name);
+        if (values.length > 1 && !contract.repeatable.includes(name))
+            reject(`--${name} must occur once`, name);
+        for (const value of values) {
+            if (contract.switches.includes(name) || name === "mb-upgrade-mode") {
+                if (value !== flag)
+                    reject(`--${name} is a switch and does not take a value`, name);
+                continue;
+            }
+            if (value === flag || !value.trim())
+                reject(`--${name} requires a non-empty value`, name);
+            if (name === "compatibility-mode" && value !== "mb-upgrade")
+                reject("--compatibility-mode must be mb-upgrade", name);
+            const choices = contract.enums[name];
+            if (choices && !choices.includes(key === "id next" && name === "type" ? value.toLowerCase() : value))
+                reject(`--${name} must be ${choices.join(" or ")}`, name);
+            if (booleans.has(name) && !["true", "false"].includes(value))
+                reject(`--${name} must be true or false`, name);
+            const number = Number(value);
+            if (positiveInteger.has(name) && (!/^[0-9]+$/.test(value) || !Number.isSafeInteger(number) || number <= 0)
+                || nonnegativeInteger.has(name) && (!/^[0-9]+$/.test(value) || !Number.isSafeInteger(number) || number < 0)
+                || positiveNumber.has(name) && (!Number.isFinite(number) || number <= 0)
+                || name === "timeout" && (!Number.isFinite(number) || number < 0)
+                || name === "available-slots" && number > 15)
+                reject(`Invalid numeric value for --${name}`, name);
+        }
+    }
+    for (const name of contract.required)
+        if (!parsed.options.has(name))
+            reject(`Missing required option: --${name}`, name);
+    for (const aliases of [
+        ["root", "project-root"], ["payload-file", "json-file"],
+        ["payload-file", "payload-json", "payload-base64"], ["semantic-file", "data", "result-file", "result-stdin"],
+        ["stage-report", "dashboard"], ["task-file", "plan-item"], ["project", "project-root"],
+        ["intake-file", "intake-stdin", "context-file"]
+    ]) {
+        const present = aliases.filter(name => parsed.options.has(name));
+        if (present.length > 1)
+            reject(`Use only one of ${present.map(name => `--${name}`).join(", ")}`);
+    }
+    if (contract.values.includes("retry-check") && parsed.options.has("retry-check") !== parsed.options.has("reason"))
+        reject("--retry-check and --reason must be supplied together");
+    // Retain the dispatcher's historic offsets for nested action positions.
+    const family = parsed.positional[0];
+    const singleWord = ["status", "version", "transition"].includes(family);
+    return { key, family, command: singleWord ? undefined : parsed.positional[1], parsed: { options: parsed.options, positional: parsed.positional.slice(singleWord ? 1 : 2) } };
+}

package/dist/cli/help.js

@@ -1,4 +1,37 @@
 const helpPages = new Map([
+    ["runtime scope", `Usage:
+  dd-flow runtime scope fence --scope-id EVAL_ID --request-id ID --json
+  dd-flow runtime scope status --scope-id EVAL_ID --json
+  dd-flow runtime scope stop --scope-id EVAL_ID --request-id ID --json
+  dd-flow runtime scope control --scope-id EVAL_ID --request-id ID --mode pause|stop [--manifest-json JSON] --json
+  dd-flow runtime scope resume --scope-id EVAL_ID --request-id ID --generation N --capture-key SHA256 --json
+  dd-flow runtime scope reconcile --scope-id EVAL_ID --generation N --request-id ID --json
+
+Use the EVAL manifest's retained DD_FLOW_RESOURCE_HOME. Commands select exactly
+one scope across its registered runtime homes; neighboring scopes are untouched.
+fence durably blocks new provider turns and owned baseline checks. It does not
+stop existing work. status reports retained ownership, not proof of settlement.
+stop fences first and requests owned daemon-tree and baseline-process cleanup.
+Inspect settled and each node's evidence: ok alone does not prove cleanup.
+Unproven ownership or cleanup remains pending; repeat stop to observe settlement.
+The fence/stop route is terminal cancellation and has no resume command.
+control records recoverable scope intent and starts a detached drain owner.
+The EVAL resolver supplies a runtime-scope-manifest@1 declaration with the source
+manifest path, SHA-256 and execution IDs, including queued executions. Declaration
+changes are rejected. resume accepts the exact captured generation and starts
+detached recovery preparation. It does not yet release scope admission: inspect
+dispatch_blocked and pending reasons; accepted preparation is not resumed work.
+RUN pause/stop/resume uses dd-flow run control.`],
+    ["storage", `Usage:
+  dd-flow storage migrate-writer --database ABSOLUTE_DB --backup NEW_ABSOLUTE_FILE --offline --json
+
+Drain all local and external runtime owners before using --offline. This command
+migrates one existing database, not a whole runtime or retained provider Session.
+It refuses unresolved ownership rows, preserves a verified WAL-safe backup, and
+fences unaware old writers. It does not initialize the default DD_FLOW_HOME.
+The backup path must be new; existing backups are never overwritten. An exact
+retry of a committed migration returns its receipt after verifying the backup.
+If no committed receipt exists, retain the failed backup and choose a new path.`],
     [
         "",
         `dd-flow - mechanical control layer for dd-flow workflows
@@ -33,11 +66,14 @@ Core commands:
   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.
+  storage migrate-writer      Explicitly back up and fence a drained SQLite store.
+  runtime scope fence/status/stop Fence, inspect, or cancel one retained EVAL scope.
   memory permissions preflight Check Memory Bank write/read permissions.
   integration cmux status       Inspect optional cmux integration.
   codex home/hooks/hook         Manage Codex homes, hooks, and hook events.
   zcode event/usage             Ingest trusted zcode-acp lifecycle and usage evidence.
   grok event/usage              Ingest trusted Grok Build lifecycle and usage evidence.
+  droid event/usage             Ingest trusted Factory Droid lifecycle and physical usage evidence.
   opencode event/usage          Ingest trusted OpenCode lifecycle and usage evidence.
   agy event/usage               Ingest trusted Antigravity CLI lifecycle and usage evidence.
   worktree plan/create/status   Record Worktrunk-backed feature worktrees.
@@ -152,12 +188,18 @@ Usage:
   dd-flow run start --project-root <root> [--workspace-root <checkout>] --flow-kind <kind> --subject-type <type> --subject-id <id> --slug <slug> [--preset compact|normal|full] [--task-profile-file <file>] [--protocol-override-file <file>] [--flag key=value] [--next-action <text>] --json
   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 control status --run <RUN-ID> --project-root <root> --json
+  dd-flow run control reconcile --run <RUN-ID> --project-root <root> --control-id <ID> --request-id <ID> --json
+  dd-flow run drive launch --run <RUN-ID> --project-root <root> --request-id <id> --context-file <file> --context-sha256 <sha256> [--stop-after <stage>] [--capture-root <directory>] --json
+  dd-flow run drive status --run <RUN-ID> --project-root <root> [--after <sequence>] --json
   dd-flow run list --project-root <root> --json
-  dd-flow run prepare-vnext-specify --project-root <root> --slug <slug> --json
-  dd-flow run snapshot create <RUN-ID|RUN-short-id> (--stage-entry <stage>|--candidate) --project-root <root> --output <directory> --json
-  dd-flow run snapshot restore --snapshot <directory> --project-root <prepared-root> --json
+  dd-flow run prepare-vnext-specify --project-root <root> --slug <slug> [--execution-routing-file <file>] --json
+  dd-flow run recovery inspect|begin|seal|capture|resume <RUN-ID|RUN-short-id> --project-root <root> --json
+  dd-flow run snapshot create <RUN-ID|RUN-short-id> (--stage-entry <stage>|--candidate|--incomplete|--recovery-id <RCV-ID>) --project-root <root> --output <directory> --json
+  dd-flow run snapshot restore --snapshot <directory> --project-root <prepared-root> [--recovery-id <RCV-ID>] --json
   dd-flow run snapshot bootstrap create --project-root <root> --output <directory> --json
   dd-flow run snapshot bootstrap restore --snapshot <directory> --project-root <prepared-root> --json
+  dd-flow run fork --from <sealed-stage-entry-snapshot> --output <empty-directory> --engine-version <exact-version> --request-id <id> [--integrity-checksum <sha256>] --json
   dd-flow run timeline <RUN-ID|RUN-short-id> --project-root <root> --json
   dd-flow stat usage --run <RUN-ID|RUN-short-id> --project-root <root> [--stage <stage[,stage...]>] [--session <session-id>] --json
   dd-flow stat run sessions ls --run <RUN-ID|RUN-short-id> --project-root <root> --json
@@ -169,7 +211,12 @@ Usage:
 
 RUN-* is the execution envelope for one concrete flow launch. Semantic truth remains in protocol, experiment, DEF, scenario, evidence, and Memory Bank documents. New run artifacts are stored under DD_FLOW_HOME/projects/<PRJ-ID-slug>/runs/<RUN-ID-slug>/ with one run.json projection and an append-only timeline.jsonl. Timeline is the compact full run report: summary is always present, while --hide may suppress bulky sections. Use \`dd-flow stat usage --run …\` to reread registered local Codex transcript counters and tool-call facts and refresh the current usage projection; unavailable data is explicit rather than zero.
 
-run prepare-vnext-specify allocates an otherwise unstarted vNext RUN for the canonical SPECIFY entry checkpoint. run snapshot is the eval-only checkpoint boundary: it snapshots one quiescent RUN, its dedicated DD_FLOW_HOME, and the exact project tree including its Git repository, then restores them into a fresh dedicated runtime. It is not a general runtime backup command and fails closed for a shared runtime.
+run start and prepare-vnext-specify accept --execution-routing-file for vNext RUNs: dd-flow/execution-routing@1 with an execution object selects the complete routing policy from existing agent-profiles. RUN creation freezes the input and selected profiles without changing project settings.
+run snapshot restore also accepts --execution-routing-file for a new stage-entry experiment. Its fresh DD_FLOW_HOME may contain only agent-profiles and the empty database; selected profiles are read before import, previous RUN policy is archived, and existing Work overrides must resolve against the selected frozen profiles. Recovery imports reject this option.
+run fork restores one sealed stage-entry snapshot to an isolated project and DD_FLOW_HOME, archives source authority, then binds an exact engine only in that copy. It is idempotent by request ID and output receipt; it never resumes a provider session or changes its source RUN.
+run prepare-vnext-specify allocates an otherwise unstarted vNext RUN for the canonical SPECIFY entry checkpoint. run recovery makes an interrupted RUN read-only, requires an explicit settled-tree receipt, captures immutable recovery evidence, then explicitly returns delegated Work to the ready graph. run snapshot is the eval-only checkpoint boundary: it snapshots one quiescent RUN, its dedicated DD_FLOW_HOME, and the exact project tree including its Git repository, then restores them into a fresh dedicated runtime. It is not a general runtime backup command and fails closed for a shared runtime.
+
+Managed drive is not yet native-provider qualified. With --capture-root, its detached controller fences RUN writers and captures each completed Stage before dispatching its successor. The capture root must be outside the runtime, project and workspace. Status events expose boundary_captured receipts; capturing means writers are still fenced, and capture_failed retains the fence for operator reconciliation. External snapshot creation is rejected while a managed controller owns a live RUN.
 
 Examples:
   dd-flow run start --project-root "$PWD" --flow-kind mb_sdlc --subject-type protocol --subject-id PRT-001-demo --slug demo --json
@@ -190,10 +237,12 @@ Usage:
   dd-flow stage unblock <RUN-ID|RUN-short-id> --project-root <root> --stage <name> --work <WORK-ID> --json
   dd-flow stage fanout status <RUN-ID|RUN-short-id> --project-root <root> --stage <name> --json
   dd-flow stage fanout dispatch <RUN-ID|RUN-short-id> --project-root <root> --stage <name> --json
+  dd-flow stage fanout reconcile <RUN-ID> --project-root <root> --stage <name> --observations-file <native-observations.json> --json
+  dd-flow stage native observe <RUN-ID> --project-root <root> --stage <name> --observations-file <native-observations.json> --json
   dd-flow stage finish <RUN-ID|RUN-short-id> --project-root <root> --stage <name> [--semantic-file <RUN-local-json>] --json
   dd-flow stage finish <RUN-ID|RUN-short-id> --project-root <root> --stage specify (--result-file <RUN-local-specify.json>|--result-stdin) --outcome <specified|failed|cancelled> --json
 
-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 lifecycle commands. A material user question uses stage pause, not stage finish: pause leaves the same stage, Work, Session and attempt open and returns the exact resume command. Engine, harness and environment failures use stage block and never create HITL. On the next Turn, pass a complete user answer to stage resume, or repair an external blocker and call its returned stage unblock command. stage fanout is read-only orchestration state plus the stage's deterministic Work materialization action for an external runner; it never makes product decisions. stage finish is reserved for actual stage completion and generates the final deterministic reports. Generated lifecycle commands include DD_FLOW_HOME when the RUN uses a non-default runtime.`
+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 lifecycle commands. Managed commands use scoped RUN/Work aliases and @project; their internal invocation UUID is bound by the native hook and is intentionally not model-facing. @ aliases apply only to declared dd-flow path arguments, not to shell tools. A material user question uses stage pause, not stage finish: pause leaves the same stage, Work, Session and attempt open and returns the exact resume command. Engine, harness and environment failures use stage block and never create HITL. On the next Turn, pass a complete user answer to stage resume, or repair an external blocker and call its returned stage unblock command. stage fanout is read-only orchestration state plus the stage's deterministic Work materialization action for an external runner; it never makes product decisions. stage finish is reserved for actual stage completion and generates the final deterministic reports. Unmanaged operator calls retain explicit project and runtime selection.`
     ],
     [
         "work",
@@ -203,6 +252,7 @@ Usage:
   dd-flow work ls (--run <RUN-ID>|--parent <WORK-ID>) [--ready] --json
   dd-flow work show <WORK-ID> --json
   dd-flow work start <WORK-ID> --project-root <root> --json
+  dd-flow work launch <WORK-ID> [--stage <name>] --json
   dd-flow work finish <WORK-ID> (--result-file <path>|--result-stdin) --project-root <root> --json
   dd-flow work repair add --run <RUN-ID> (--from-check <CHECK-ID>|--from-unresolved <gap> --verification-file <file>) --origin-work <WORK-ID>... --task-stdin --project-root <root> --json
 
@@ -369,11 +419,12 @@ Usage:
   dd-flow merge request status <MRG-ID> --project-root <root> --json
   dd-flow merge request route <MRG-ID> --mode same_session|server --reason <text> --project-root <root> --json
   dd-flow merge apply <MRG-ID> --work <WRK-ID> --project-root <root> --json --progress-jsonl
+  dd-flow merge repair <MRG-ID> --project-root <root> --json
   dd-flow merge serve --agent-profile <id> [--once] [--poll-seconds <n>] [--max-parallel-projects <n>] --progress-jsonl
   dd-flow merge server status --json
   dd-flow merge server stop <MSV-ID> --json
 
-CODE or CODE-REVIEW creates one MRG request and child MERGE Work. stage start waits in the shared project FIFO, reports progress, locks the execution target baseline and returns the exact apply/finish commands. merge apply is the only supported initial Git mutation. merge serve is a deterministic dispatcher: it launches a fresh Session through the configured harness adapter but does not perform agent work itself. It preserves FIFO inside each project and may serve different projects concurrently up to the explicit bound.`
+CODE or CODE-REVIEW creates one MRG request and child MERGE Work. stage start waits in the shared project FIFO, reports progress, locks the execution target baseline and returns the exact apply/finish commands. merge apply is the only supported initial Git mutation. If its integration gate fails, merge repair restores the target baseline and creates a source CODE → independent CODE-REVIEW → replacement-MRG cycle; it never patches product code in the integration workspace. merge serve is a deterministic dispatcher: it launches a fresh Session through the configured harness adapter but does not perform agent work itself. It preserves FIFO inside each project and may serve different projects concurrently up to the explicit bound.`
     ],
     [
         "cleanup",
@@ -536,17 +587,38 @@ 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.`
+    ],
+    [
+        "zcode hook",
+        `dd-flow zcode hook - handle a synchronous native ZCode PreToolUse callback
+
+Usage:
+  dd-flow zcode hook handle --project-root <root> --json
+
+The managed ZCode native hook supplies the callback on stdin. It records the
+receipt before returning a rewritten tool input with --hook-event-id.`
     ],
     [
         "zcode event",
-        `dd-flow zcode event - ingest a zcode-acp session/update notification
+        `dd-flow zcode event - ingest a zcode-acp session/update notification as evidence
 
 Usage:
   dd-flow zcode event handle --project-root <root> --json
   dd-flow zcode usage ingest --project-root <root> --json
 
-Both payloads are read from stdin. The event adapter retains lifecycle identity;
-the usage adapter retains cumulative provider counters for RUN accounting.`
+Both payloads are read from stdin. Native hooks own lifecycle admission; ACP
+events and usage retain secondary evidence for RUN accounting.`
+    ],
+    [
+        "droid event",
+        `dd-flow droid event - ingest a controlled Factory Droid Execute hook
+
+Usage:
+  dd-flow droid event handle --project-root <root> --json
+  dd-flow droid usage ingest --project-root <root> --json
+
+Reads trusted adapter JSON from stdin. Usage requires physical_session scope and explicit completeness.
+`
     ],
     [
         "opencode event",

package/dist/cli/hook-ingress.js

@@ -0,0 +1,82 @@
+import { fileURLToPath } from "node:url";
+import { performance } from "node:perf_hooks";
+import { parseCommandArgs, parseLifecycleCommand, lifecycleCommandFromPayload } from "../services/lifecycle-command.js";
+import { errorRecord, AppError } from "../shared/errors.js";
+import { parseJsonObject } from "../shared/json.js";
+const workerFile = fileURLToPath(import.meta.url);
+const ingressBudgetMs = 20_000; // Native host timeout is 30s; this includes cold module/DB open.
+/** Lightweight entry: unrelated hooks never load the router or open storage. */
+export async function runHookIngress(args) {
+    try {
+        const parsed = parseCommandArgs(args.slice(3));
+        for (const [key, values] of parsed.options)
+            if (!["event", "project-root", "json"].includes(key) || values.length !== 1)
+                throw new AppError("usage", `Invalid hook option: ${key}`, 2);
+        const event = parsed.options.get("event")?.[0];
+        if (!event?.trim() || event === "__dd_flow_flag__" || parsed.positional.length)
+            throw new AppError("usage", "Hook ingress requires --event with a value", 2);
+        const root = parsed.options.get("project-root")?.[0];
+        if (root !== undefined && (!root.trim() || root === "__dd_flow_flag__"))
+            throw new AppError("usage", "--project-root requires a value", 2);
+        if (parsed.options.has("json") && parsed.options.get("json")?.[0] !== "__dd_flow_flag__")
+            throw new AppError("usage", "--json does not take a value", 2);
+        let stdin = "";
+        for await (const chunk of process.stdin) {
+            stdin += String(chunk);
+            if (Buffer.byteLength(stdin) > 1_048_576)
+                throw new AppError("native_hook_response_invalid", "Hook input exceeds 1 MiB", 1);
+        }
+        const payload = parseJsonObject(stdin || "{}", "native hook stdin");
+        const command = lifecycleCommandFromPayload(payload);
+        if (event !== "PreToolUse" || !command || parseLifecycleCommand(command).kind === "none") {
+            process.stdout.write("{}\n");
+            return 0;
+        }
+        const started = performance.now();
+        const { invokeNativeHook } = await import("../harness-runtime/lib/native-hook-command.mjs");
+        const result = await invokeNativeHook({ bin: workerFile, args, payload, home: process.env.DD_FLOW_HOME, timeoutMs: ingressBudgetMs });
+        const { timing, ...output } = result;
+        process.stderr.write(`${JSON.stringify({ kind: "hook_ingress", total_ms: Math.round(performance.now() - started), ...timing })}\n`);
+        process.stdout.write(`${JSON.stringify(output)}\n`);
+        return 0;
+    }
+    catch (error) {
+        const record = errorRecord(error);
+        process.stderr.write(`${JSON.stringify({ ok: false, error: record })}\n`);
+        return record.exitCode;
+    }
+}
+// A bounded CLI subprocess, not a detached writer: its successful reply follows COMMIT.
+if (process.argv[1] === workerFile) {
+    try {
+        let stdin = "";
+        for await (const chunk of process.stdin)
+            stdin += String(chunk);
+        const payload = parseJsonObject(stdin, "native hook stdin");
+        const started = performance.now();
+        const { verifyCodexHookDelivery } = await import("../services/codex-hook-delivery.js");
+        const proof = await verifyCodexHookDelivery(process.env, payload);
+        const verified = performance.now();
+        const [{ createContext }, { handleCodexHook }] = await Promise.all([import("../runtime/context.js"), import("../services/hooks.js")]);
+        const loaded = performance.now();
+        const context = createContext(process.env, "hook");
+        const opened = performance.now();
+        try {
+            if (proof)
+                context.codexHookProof = proof;
+            const parsed = parseCommandArgs(process.argv.slice(5));
+            const projectRoot = parsed.options.get("project-root")?.[0];
+            const result = handleCodexHook(context, { event: "PreToolUse", ...(projectRoot ? { projectRoot } : {}), stdin });
+            process.stdout.write(`${JSON.stringify({ ...(result.hookSpecificOutput ? { hookSpecificOutput: result.hookSpecificOutput } : {}), timing: {
+                    verify_ms: Math.round(verified - started), load_ms: Math.round(loaded - verified), open_ms: Math.round(opened - loaded), receipt_ms: Math.round(performance.now() - opened)
+                } })}\n`);
+        }
+        finally {
+            context.db.close?.();
+        }
+    }
+    catch (error) {
+        process.stderr.write(`${JSON.stringify({ ok: false, error: errorRecord(error) })}\n`);
+        process.exitCode = 1;
+    }
+}