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

package/dist/cli/executor-onboarding.js

@@ -0,0 +1,76 @@
+import { createInterface } from "node:readline";
+import { AppError } from "../shared/errors.js";
+import { prepareOperatorProfile, prepareProfileCreation, readOperatorProfileInput } from "../services/operator-profiles.js";
+/** One explicit choice; prompts go to stderr so stdout remains machine-readable. */
+export async function askExecutorChoice(settings, io, policy = {}) {
+    const ids = settings.profiles.map(entry => entry.id);
+    io.stderr.write(`Executor profiles: ${ids.length ? ids.join(", ") : "none configured"}\n`);
+    io.stderr.write(`Choose a profile ID/alias, file:/absolute/profile.json, create${policy.allowSkip === false ? "" : ", or skip"}. No model is selected automatically.\n`);
+    const terminal = createInterface({ input: io.stdin, output: io.stderr });
+    const lines = terminal[Symbol.asyncIterator]();
+    const cancelled = () => new AppError("onboarding_cancelled", "Executor onboarding was cancelled", 1, { effect: "no_effect" });
+    terminal.on("SIGINT", () => terminal.close());
+    const ask = async (prompt) => {
+        io.stderr.write(prompt);
+        const line = await lines.next();
+        if (line.done)
+            throw cancelled();
+        const answer = line.value.trim();
+        if (answer.length > 4096)
+            throw new AppError("usage", "Executor choice exceeds the input limit", 2, { effect: "no_effect" });
+        return answer;
+    };
+    try {
+        const answer = await ask("Executor: ");
+        if (answer === "skip") {
+            if (policy.allowSkip === false)
+                throw new AppError("agent_profile_missing", "This flow requires an executor profile", 1, { effect: "no_effect" });
+            return { skip: true };
+        }
+        if (answer === "create") {
+            io.stderr.write("Enter explicit profile settings; this does not probe providers or verify model access. Nothing is saved by this dialog.\n");
+            const input = { schema_id: "dd-flow/agent-profile@1" };
+            for (const [key, prompt] of [
+                ["id", "Profile ID: "], ["harness", "Harness (codex/zcode/agy/opencode/grok/droid): "],
+                ["provider", "Provider ID: "], ["model", "Model ID: "], ["reasoning", "Reasoning setting: "],
+                ["mode", "Mode setting: "], ["permission", "Permission (allow/deny): "]
+            ])
+                input[key] = await ask(prompt);
+            const profile = prepareOperatorProfile(input);
+            if (settings.profiles.some(entry => entry.id === profile.id) || Object.hasOwn(settings.aliases, profile.id)) {
+                throw new AppError("profile_id_conflict", "New profile ID collides with an existing profile or alias", 2, { effect: "no_effect" });
+            }
+            if (await ask("Use this profile for this operation? Type yes: ") !== "yes")
+                throw cancelled();
+            if (policy.allowSave === false)
+                return { profile };
+            const save = await ask("Save this profile globally during installation? Type yes or no: ");
+            if (save !== "yes" && save !== "no")
+                throw cancelled();
+            if (save === "yes") {
+                const defaultChoice = await ask("Set it as global default? Type yes or no: ");
+                if (defaultChoice !== "yes" && defaultChoice !== "no")
+                    throw cancelled();
+                return { profile, profileCreation: prepareProfileCreation(settings, profile, defaultChoice === "yes") };
+            }
+            return { profile };
+        }
+        if (answer.startsWith("file:")) {
+            const file = answer.slice(5);
+            if (!file.startsWith("/") && !/^[A-Za-z]:[\\/]/.test(file))
+                throw new AppError("usage", "Profile file must be an absolute path", 2, { effect: "no_effect" });
+            return { profile: readOperatorProfileInput(file) };
+        }
+        if (!answer)
+            throw new AppError("agent_profile_missing", "An explicit executor choice is required", 1, { effect: "no_effect" });
+        return { profileId: answer };
+    }
+    catch (error) {
+        if (error instanceof AppError)
+            throw error;
+        throw cancelled();
+    }
+    finally {
+        terminal.close();
+    }
+}

package/dist/cli/flows.js

@@ -0,0 +1,29 @@
+import { prepareCommandRoute } from "./command-inputs.js";
+import { parseOutputOptions } from "./output-options.js";
+import { prepareResponseDestination, writeResponseFile } from "./response-file.js";
+import { listBundledFlows, showBundledFlow } from "../services/flow-catalog.js";
+import { AppError, errorRecord } from "../shared/errors.js";
+import { writePreparationError } from "./error-output.js";
+/** Catalog inspection never creates an AppContext or executes a flow. */
+export function runFlowCatalogCli(args, io = process) {
+    try {
+        const output = parseOutputOptions(args);
+        const route = prepareCommandRoute(output.args);
+        let result;
+        if (route.key === "flow list")
+            result = { flows: listBundledFlows() };
+        else if (route.key === "flow show")
+            result = { flow: showBundledFlow(route.parsed.positional[0]) };
+        else
+            throw new AppError("usage", "Use dd-flow flow list or flow show <id>", 2, { effect: "no_effect" });
+        if (output.responseFile)
+            prepareResponseDestination(output.responseFile);
+        io.stdout.write(`${JSON.stringify(writeResponseFile({ ok: true, action: route.key.replaceAll(" ", "_"), ...result }, output), null, output.json ? undefined : 2)}\n`);
+        return 0;
+    }
+    catch (error) {
+        const record = errorRecord(error);
+        writePreparationError(io, args, record);
+        return record.exitCode;
+    }
+}

package/dist/cli/harnesses.js

@@ -0,0 +1,84 @@
+import { prepareCommandRoute } from "./command-inputs.js";
+import { writePreparationError } from "./error-output.js";
+import { parseOutputOptions } from "./output-options.js";
+import { optionalOption, optionalPositiveNumber } from "./argument-values.js";
+import { discoverHarnesses, harnessCatalog } from "../services/harness-discovery.js";
+import { AppError, errorRecord } from "../shared/errors.js";
+import { probeHarnessVersion } from "../services/harness-version-probe.js";
+import { probeHarnessDoctor } from "../services/harness-doctor.js";
+import { prepareResponseDestination, writeResponseFile } from "./response-file.js";
+import path from "node:path";
+import { validateModelScope } from "../services/model-discovery.js";
+/** Home-free ingress: process diagnostics require explicit effect admission. */
+export async function runHarnessesCli(args, env, io = { stdout: process.stdout, stderr: process.stderr }) {
+    let json = false;
+    try {
+        const output = parseOutputOptions(args);
+        json = output.json;
+        if (output.responseFile)
+            prepareResponseDestination(output.responseFile);
+        const route = prepareCommandRoute(output.args);
+        const family = route.key === "harnesses show" ? route.parsed.positional[0] : optionalOption(route.parsed, "harness");
+        if (family && !harnessCatalog.entries.some(entry => entry.id === family))
+            throw new AppError("usage", "Unknown harness; see dd-flow harnesses --help", 2, { effect: "no_effect" });
+        const provider = optionalOption(route.parsed, "provider"), account = optionalOption(route.parsed, "account-sha256");
+        const observationFile = optionalOption(route.parsed, "model-observation-file");
+        let modelScope;
+        if (provider !== undefined || account !== undefined || observationFile !== undefined) {
+            if (!provider || !account)
+                throw new AppError("usage", "Doctor model observations require both --provider and --account-sha256", 2, { effect: "no_effect", help: "harnesses doctor" });
+            modelScope = { harness: family, provider, account_sha256: account };
+            validateModelScope(modelScope);
+            if (observationFile) {
+                if (output.responseFile && path.resolve(observationFile) === path.resolve(output.responseFile))
+                    throw new AppError("usage", "Model observation and command response destinations must differ", 2, { effect: "no_effect" });
+                prepareResponseDestination(observationFile);
+            }
+        }
+        const discovery = discoverHarnesses({ env, ...(family ? { harness: family } : {}),
+            ...(optionalOption(route.parsed, "executable") ? { executable: optionalOption(route.parsed, "executable") } : {}) });
+        let probe;
+        let modelObservation;
+        let observationPublication;
+        if (route.key === "harnesses doctor") {
+            const selected = discovery.entries[0]?.candidates.find(candidate => candidate.selected);
+            if (!selected)
+                throw new AppError("harness_selection_required", "Doctor requires one installed executable; use --executable for ambiguous installations", 1, { effect: "no_effect" });
+            const stateDir = optionalOption(route.parsed, "state-dir"), nativeExecutable = optionalOption(route.parsed, "native-executable");
+            const timeoutMs = optionalPositiveNumber(route.parsed, "timeout-ms", true);
+            probe = await probeHarnessDoctor({ harness: family, executable: selected.path, env,
+                ...(stateDir !== undefined ? { stateDir } : {}), ...(nativeExecutable !== undefined ? { nativeExecutable } : {}),
+                ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+                scope: { processes: route.parsed.options.has("allow-processes"), services: route.parsed.options.has("allow-services"),
+                    credentials: route.parsed.options.has("allow-credentials"), writes: route.parsed.options.has("allow-writes") } });
+            if (modelScope) {
+                modelObservation = { scope: modelScope, observed_at: new Date().toISOString(),
+                    status: probe.reported_models.length ? "listed" : "unavailable", complete: false, models: [...probe.reported_models] };
+                if (observationFile) {
+                    const published = writeResponseFile(modelObservation, { responseFile: observationFile });
+                    observationPublication = { path: observationFile, status: published.response_file_error ? "unknown" : "published",
+                        ...(published.response_file_error ? { error: published.response_file_error } : {}) };
+                }
+            }
+        }
+        else if (route.key === "harnesses probe-version") {
+            const selected = discovery.entries[0]?.candidates.find(candidate => candidate.selected);
+            if (!selected)
+                throw new AppError("harness_selection_required", "Version probe requires one installed executable; use --executable for ambiguous installations", 1, { effect: "no_effect" });
+            probe = await probeHarnessVersion({ harness: family, executable: selected.path, env,
+                ...(optionalPositiveNumber(route.parsed, "timeout-ms", true) === undefined ? {} : { timeoutMs: optionalPositiveNumber(route.parsed, "timeout-ms", true) }),
+                scope: { processes: route.parsed.options.has("allow-processes"), services: false,
+                    credentials: route.parsed.options.has("allow-credentials"), writes: route.parsed.options.has("allow-writes") } });
+        }
+        const result = { ok: true, action: route.key.replaceAll(" ", "_"), catalog: harnessCatalog, discovery, ...(probe ? { probe } : {}),
+            ...(modelObservation ? { model_observation: modelObservation, observation_scope_binding: "operator_declared_unverified" } : {}),
+            ...(observationPublication ? { model_observation_publication: observationPublication } : {}) };
+        io.stdout.write(`${JSON.stringify(writeResponseFile(result, output), null, json ? undefined : 2)}\n`);
+        return 0;
+    }
+    catch (error) {
+        const record = errorRecord(error);
+        writePreparationError(io, args, record);
+        return record.exitCode;
+    }
+}

package/dist/cli/help.js

@@ -1,4 +1,204 @@
+import { AppError } from "../shared/errors.js";
+import { commandInputs, commandAliases } from "./command-inputs.js";
+import { commandKeyForPositions, globalOptionDocumentation, optionsForCommandTree, routerNativeRoute } from "./command-metadata.js";
 const helpPages = new Map([
+    ["flow mb-init", `dd-flow init / flow mb-init - managed project Memory Bank initialization
+
+Usage:
+  dd-flow init --project-root /absolute/project --workspace-root /absolute/workspace --request-id ID --intake-file /absolute/intake.txt --intake-sha256 SHA256 --git-route integration_branch_direct --integration-branch main [--profile ID-or-alias] [--detach] --json
+  dd-flow flow mb-init --project-root /absolute/project --workspace-root /absolute/workspace --request-id ID [--detach] --json
+
+Both spellings share one command definition and dispatcher. Fresh execution
+requires the original bounded UTF-8 intake bytes and explicit Git policy.
+setup installs the computer-level canon; init initializes the specified project.
+Missing executor defaults or prerequisites refuse before project publication.
+Profiles, descriptor, engine and original request are frozen before dispatch.
+
+Replay uses the exact retained request, not current defaults, aliases or canon.
+Omitted selectors reuse original choices; supplied selectors must match them.
+The original intake file need not survive replay: its supplied hash must match
+the retained bytes. --stage-profile stage=profile and --work-profile profile
+are repeatable approved overrides, frozen before launch.
+
+--profile-file /absolute/profile.json is exclusive with --profile and supplies
+one complete validated operation-only profile. It never saves a global profile
+or changes defaults; a conflicting saved ID/alias refuses. Replay may omit this
+file after removal; if supplied, its admitted profile must match the original.
+When no default or explicit profile exists, an interactive terminal uses the
+shared executor dialog. Creation is operation-only here; skip is not allowed.
+--non-interactive, JSON and non-terminal input never ask and missing choices
+refuse before project effects. Use profiles commands for explicit global saves.
+
+The existing managed controller owns Sessions and execution. The default waits
+for completion, recovery or a user/context boundary; --detach returns its
+accepted receipt. Observer disconnection does not stop the controller.
+--prepare-only publishes the normal project bootstrap and frozen RUN, but does
+not launch a controller or provider Session. It is not a dry run and is exclusive
+with --detach. A runner may then use run drive launch with its own context and
+bounded stop/capture policy. Exact preparation replay never stops or replaces
+an existing controller.
+Use existing scoped run drive status / run control commands to observe,
+answer, pause, stop or reconcile the retained RUN. Native/attached public
+selection is not yet exposed; no failed route silently becomes native.`],
+    ["flow", `dd-flow flow - engine-owned workflow catalog
+
+Usage:
+  dd-flow flow list --json
+  dd-flow flow show <id> --json
+
+Inspection never opens a runtime database, initializes a home or runs agents.
+The catalog reports handler registration separately from RUN readiness. A
+pending handler set cannot execute; registered handlers still require selected
+canon, frozen descriptor/schema admission, workspace and execution readiness.
+These inspection commands do not start init or qualify an installed route.`],
+    ["models", `dd-flow models - reviewed seed and scoped offline observations
+
+Usage:
+  dd-flow models list --json
+  dd-flow models show <model> --harness family --provider provider --json
+  dd-flow models list --harness family --provider provider --account-sha256 <digest> --observation-file /absolute/listing.json --json
+
+No database, credentials, network, executable discovery or provider process is
+opened. --seed-file selects reviewed seed-only catalog data; otherwise the
+bundled adapter-derived seed is used. Families not yet curated are explicit.
+Unknown seed settings are not profile defaults or model recommendations.
+
+Observations require an exact harness/provider/account scope. A matching listed
+model remains unknown for account access and flow qualification. Missing or
+unavailable listing retains seed entries; a foreign scope is ignored. show
+refuses an absent model rather than inventing availability. Exit 2 is invalid
+input; exit 1 is missing/unreadable input or an absent selected model.`],
+    ["completion", `dd-flow completion - shell completion from the accepted command grammar
+
+Usage:
+  dd-flow completion bash
+  dd-flow completion zsh
+  dd-flow completion fish
+
+Prints a shell script to stdout; it does not modify shell configuration. Load
+the script in your shell after reviewing it. Zsh requires compinit first.
+Scripts query completion candidates with literal argv; they do not initialize
+a home, open a database, inspect profiles or invoke harness processes.`],
+    ["harnesses", `dd-flow harnesses - static installation discovery
+
+Usage:
+  dd-flow harnesses list --json
+  dd-flow harnesses show <family> --json
+  dd-flow harnesses discover [--harness family --executable /absolute/path] --json
+  dd-flow harnesses probe-version --harness family --allow-processes --allow-credentials --allow-writes [--executable /absolute/path --timeout-ms 3000] --json
+  dd-flow harnesses doctor --harness family --allow-processes --allow-credentials [--allow-services --allow-writes --executable /absolute/path] --json
+
+Lists all six supported families, including missing installations. Multiple
+installations require explicit selection. Presence does not establish version,
+protocol, auth, model access or qualification. list/show/discover never launch a
+process, inspect credentials, create a home or open a runtime database.
+probe-version is an explicit diagnostic exception: it runs installed code only
+after all three effect permissions are supplied. It bounds time/output and does
+not establish protocol compatibility, account access or flow qualification.
+doctor invokes the existing bundled adapter only after its classified effects
+are admitted: Codex/OpenCode/Droid require services and writes; Agy requires
+writes; ZCode/Grok require processes and credentials. ZCode also requires
+--native-executable. OpenCode requires --state-dir for an existing daemon whose
+executable binding matches; doctor never starts or stops that daemon.
+For Droid, the OS ps utility must be available on PATH before doctor starts;
+missing physical-settlement tooling refuses without launching a provider.
+Reports are bounded/redacted observations, not native qualification or account access.
+Use --timeout-ms 1..60000 to bound the diagnostic, not productive work.
+Optional --provider and --account-sha256 must be supplied together. They bind
+reported model names to an operator-declared, unverified scope, not an observed
+credential identity. --model-observation-file explicitly publishes a standalone
+snapshot usable by models list --observation-file. Listings are incomplete;
+an absent adapter list is unavailable, never an empty verified inventory. No
+account access or qualification is inferred; publication failure does not rerun
+the admitted diagnostic. The destination must differ from --response-file.`],
+    ["setup", `dd-flow setup - global installation readiness
+
+Usage:
+  dd-flow setup --canon-source /path/to/release-bundle --trust-file operator-trust.json --request-id ID --skip-agent-setup --non-interactive --json
+  dd-flow setup update --canon-source /path/to/release-bundle --trust-file operator-trust.json --request-id ID --skip-agent-setup --json
+  dd-flow setup status --json
+
+The local bundle contains release-envelope.json, canon.tgz and engine.tgz.
+Trust uses dd-flow/release-trust@1 and must be selected independently of the
+envelope. Stable is the default channel; preview/development require --channel.
+Without --skip-agent-setup, select --profile or an existing global default.
+--profile-file supplies a complete validated profile for headless onboarding;
+it is mutually exclusive with --profile and --skip-agent-setup. Profile files
+never import credentials or silently change operator defaults.
+No missing profile is replaced by an automatically selected model.
+In an interactive terminal, a missing profile opens an explicit executor choice
+only after the authenticated installation is committed:
+profile ID/alias, file:/absolute/profile.json, create or skip. create asks for
+every profile field and explicit confirmation, without probing providers.
+Separate yes/no questions authorize saving and global default selection; no
+settings are written by the dialog itself. JSON/JSONL output,
+--non-interactive and non-terminal input never prompt. Cancellation leaves the
+installation committed and onboarding pending; replay the same request to resume
+or explicitly skip onboarding. The separate onboarding receipt freezes the
+selected profile and save/default consent before profile effects. A completed
+onboarding replay never restores later settings. Existing request-bound profile
+choices keep their original identity and recovery semantics.
+--save-profile-intent supplies explicit frozen profile creation/default consent
+for persistence. The selected profile must match; skip conflicts. Setup retains
+the complete intent in its request and uses a profiles_saved checkpoint. A
+committed replay never restores settings changed after the original installation.
+Without a new explicit executor choice, an exact request retry reuses its retained
+executor and save/default consent rather than asking again or choosing a new default.
+Status inspects the selected installation and retained cache without opening or
+migrating SQLite, registering a project, discovering providers or running agents.
+Installation readiness and runtime qualification are separate facts.
+`],
+    ["profiles", `dd-flow profiles - home-only executor settings
+
+Usage:
+  dd-flow profiles list --json
+  dd-flow profiles show <ID-or-alias> --json
+  dd-flow profiles create --file profile.json --expected-revision SHA256 [--set-default] --json
+  dd-flow profiles edit --file profile.json --expected-revision SHA256 --json
+  dd-flow profiles remove <ID> --expected-revision SHA256 --json
+  dd-flow profiles alias <alias> (--target ID | --remove) --expected-revision SHA256 --json
+  dd-flow profiles set-default [ID-or-alias | --clear] --expected-revision SHA256 --json
+
+Read the current revision with profiles list before changing settings. Writes
+are atomic and reject concurrent/stale changes. Aliases point directly to IDs,
+not other aliases. Profile files use dd-flow/agent-profile@1 and reject secret
+fields. Existing legacy IDs are imported on the first successful write without
+editing their files. Thereafter profile-settings.json is the sole owner.
+Existing RUNs use frozen snapshots, not mutable profile settings. This command
+never registers a project, selects a model automatically or creates a runtime DB.`],
+    ["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 +233,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 +355,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 snapshot bootstrap create --project-root <root> --output <directory> --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> [--flow sdlc|mb-init] --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 +378,13 @@ 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 snapshot restore and run fork accept --operational-decision-file for an explicitly accepted decision bound to the new stage-entry experiment. Store the input outside fork output; its bytes are bound to the idempotent request. A snapshot with a scoped decision cannot grant it to another execution implicitly. Recovery retains the original decision and rejects replacement.
+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
@@ -184,16 +399,22 @@ Examples:
 Usage:
   dd-flow stage start <RUN-ID|RUN-short-id> --project-root <root> --stage <name> [--dir <NN-stage-slug>] [--require-session-binding] --json
   dd-flow stage start --bootstrap --project-root <root> --stage specify --subject <safe-subject> (--intake-file <path>|--intake-stdin) [--require-session-binding] --json
-  dd-flow stage pause <RUN-ID|RUN-short-id> --project-root <root> --stage <name> --work <WORK-ID> --question-stdin --json
-  dd-flow stage resume <RUN-ID|RUN-short-id> --project-root <root> --stage <name> --work <WORK-ID> --answer-stdin --json
-  dd-flow stage block <RUN-ID|RUN-short-id> --project-root <root> --stage <name> --work <WORK-ID> --kind engine|harness|environment --code <code> --summary-stdin [--retryable] --json
+  dd-flow stage pause <RUN-ID|RUN-short-id> --project-root <root> --stage <name> --work <WORK-ID> (--question-file <path>|--question-stdin) --json
+  dd-flow stage resume <RUN-ID|RUN-short-id> --project-root <root> --stage <name> --work <WORK-ID> (--answer-file <path>|--answer-stdin) --json
+
+Managed resume commands restore the accepted answer file from runtime state. Execute the returned command without adding an answer path or recreating the answer. The explicit answer flags above are for unmanaged calls.
+Path aliases @project, @workspace and @run are supported only in declared CLI path parameters and require a uniquely bound context. File-writing tools use physical paths. Both --option value and --option=value are accepted; quoted or escaped aliases are normalized identically. Pre-RUN bootstrap paths and external schema directories require physical paths.
+An aggregate CODE/CODE-REVIEW failure may return continuation.kind=repair_required: its repair Work is already registered. End the coordinator turn and let the controller dispatch the fresh child; do not recreate the repair. A recovery retry uses --retry-check <receipt> --reason-file <recovery.json>, containing only {"reason":"actual environment recovery evidence"}. Legacy --reason remains accepted, but cannot be combined with --reason-file. A needs_input continuation is not yet executable: write its requested file first, then use command_after_input.
+  dd-flow stage block <RUN-ID|RUN-short-id> --project-root <root> --stage <name> --work <WORK-ID> --kind engine|harness|environment --code <code> (--summary-file <path>|--summary-stdin) [--retryable] --json
   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,8 +424,9 @@ 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
+  dd-flow work repair add --run <RUN-ID> (--from-check <CHECK-ID>|--from-unresolved <gap> --verification-file <file>) --origin-work <WORK-ID>... (--task-file <path>|--task-stdin) --project-root <root> --json
 
 CODE workers receive their full accepted packet from work start. work finish validates the result and executes the packet's focused checks before completion. A failed aggregate CODE gate or unresolved semantic verification creates a repair Work from the selected completed origin context and retained evidence. Its planned write areas are coordination hints only; the repair may change any necessary project file inside its RUN workspace.`
     ],
@@ -504,8 +726,12 @@ Examples:
 
 Usage:
   dd-flow memory permissions preflight --root <project-root> --memory-bank <path> [--tasks <path>] --flow <flow> --mode <mode> --json
+  dd-flow memory finish integrate --run <run-id> --project-root <project-root> --json
+  dd-flow memory finish evidence --run <run-id> --project-root <project-root> --json
 
-permissions preflight checks project, Memory Bank, and optional .tasks read/write permissions before memory flows mutate files. It never runs privileged repair commands. A completed assessment returns JSON on stdout with exit_code 0 when the flow can continue and exit_code 1 when permission blockers are found. Runtime/configuration mistakes exit 2 as structured errors.`
+permissions preflight checks project, Memory Bank, and optional .tasks read/write permissions before memory flows mutate files. It never runs privileged repair commands. A completed assessment returns JSON on stdout with exit_code 0 when the flow can continue and exit_code 1 when permission blockers are found. Runtime/configuration mistakes exit 2 as structured errors.
+
+finish integrate commits only the accepted Memory Bank and owned lint configuration, then performs the retained local integration route. It preserves unrelated files and never pushes or changes Git identity/configuration. An uncertain original Git effect must be observed, not blindly repeated. finish evidence then publishes actual coverage, integration and ordinary-entry preparation references; neither command accepts the finish result or completes the RUN.`
     ],
     [
         "memory permissions",
@@ -537,17 +763,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",
@@ -587,10 +834,73 @@ worktree plan suggests a project-scoped service checkout under DD_FLOW_HOME/proj
     ]
 ]);
 export function helpForArgs(args) {
-    const helpIndex = args.findIndex((arg) => arg === "--help" || arg === "-h");
-    if (helpIndex === -1) {
+    return resolveHelp(args)?.text;
+}
+export function hasHelpIntent(args) {
+    const end = args.indexOf("--");
+    return args.slice(0, end < 0 ? args.length : end).some(arg => arg === "--help" || arg === "-h");
+}
+/** Pure early resolver: no filesystem, runtime context, process dispatch or output-file access. */
+export function resolveHelp(args) {
+    if (!hasHelpIntent(args))
         return undefined;
+    const end = args.indexOf("--"), tokens = args.slice(0, end < 0 ? args.length : end);
+    const positions = [], selectors = [], supplied = [];
+    let json = false;
+    const switches = new Set([...globalOptionDocumentation.filter(o => o.kind === "switch").map(o => o.name),
+        ...Object.values(commandInputs).flatMap(input => input.switches)]);
+    for (let index = 0; index < tokens.length; index++) {
+        const token = tokens[index];
+        if (token === "--help" || token === "-h")
+            continue;
+        if (token === "--option" || token.startsWith("--option=")) {
+            const value = token.startsWith("--option=") ? token.slice(9) : tokens[++index];
+            if (!value || value === "--help" || value === "-h")
+                throw helpUsage("--option requires one option selector");
+            selectors.push(value.replace(/^--/, ""));
+            continue;
+        }
+        if (token.startsWith("--")) {
+            const name = token.slice(2).split("=", 1)[0];
+            supplied.push(name);
+            if (token === "--json")
+                json = true;
+            if (!token.includes("=") && !switches.has(name) && tokens[index + 1] && !tokens[index + 1].startsWith("-"))
+                index++;
+        }
+        else if (token.startsWith("-"))
+            throw helpUsage(`Unknown short option: ${token}`);
+        else
+            positions.push(token);
     }
-    const path = args.slice(0, helpIndex).filter((arg) => !arg.startsWith("--")).join(" ");
-    return helpPages.get(path) ?? helpPages.get(path.split(" ").slice(0, 2).join(" ")) ?? helpPages.get("");
+    if (selectors.length > 1)
+        throw helpUsage("--option must occur once");
+    const selected = commandKeyForPositions(positions);
+    const command = selected ?? positions.join(" ");
+    const commands = Object.keys(commandInputs).filter(key => !command || key === command || key.startsWith(`${command} `));
+    if (command && commands.length === 0)
+        throw helpUsage(`Unknown help command: ${command}`);
+    const optionMap = new Map(optionsForCommandTree(command).map(option => [option.name, option]));
+    // Invalid response transport is intentionally irrelevant to help, including missing/repeated values.
+    for (const name of supplied)
+        if (!optionMap.has(name))
+            throw helpUsage(`Unknown option --${name} for ${command || "root"}`);
+    const option = selectors.length ? optionMap.get(selectors[0]) : null;
+    if (selectors.length && !option)
+        throw helpUsage(`Unknown option selector: ${selectors[0]}`);
+    const options = [...optionMap.values()].sort((a, b) => a.name.localeCompare(b.name, "en"));
+    const input = selected ? commandInputs[selected] : undefined;
+    const canonical = commandAliases[command] ?? command;
+    const pageKey = [...helpPages.keys()].filter(key => key && (canonical === key || canonical.startsWith(`${key} `)))
+        .sort((a, b) => b.length - a.length)[0] ?? "";
+    const detail = (value) => `--${value.name}${value.kind === "value" ? " <value>" : ""}${value.required ? " (required)" : ""}${value.repeatable ? " (repeatable)" : ""}\n  ${value.description}${value.choices.length ? `\n  Allowed: ${value.choices.join(", ")}` : ""}`;
+    const usage = input ? `\nExact command: dd-flow ${command}${input.positions[0] ? ` <argument>${input.positions[0] > 1 ? ` × ${input.positions[0]}` : ""}` : ""}\n` : "";
+    return { json,
+        text: option ? `dd-flow ${command} --option ${option.name} --help\n\n${detail(option)}`
+            : `${helpPages.get(pageKey)}${usage}\n${input?.retired ? `Retired: ${input.retired}\n` : ""}\n${command ? "" : "Command paths:\n"}${input ? "" : commands.map(key => `  ${key}`).join("\n")}\n\nOptions:\n${options.map(detail).join("\n")}`,
+        data: { schema_id: "dd-flow/cli-help@1", command, alias_of: commandAliases[command] ?? null, commands, options, option: option ?? null,
+            router_native: selected ? routerNativeRoute(selected) : true, retired: input?.retired ?? null } };
+}
+function helpUsage(message) {
+    return new AppError("usage", `${message}; use dd-flow --help`, 2, { phase: "help", effect: "no_effect", recoverable: true, help_topic: "dd-flow --help" });
 }