@deksden-com/dd-flow-cli 0.9.0-beta.16 → 0.9.0-beta.161

package/dist/cli/help.js

@@ -1,4 +1,393 @@
+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([
+    ["tool", `dd-flow tool ensure wt - prepare the pinned Worktrunk capability
+
+Usage:
+  dd-flow tool ensure wt --json
+
+Verifies or installs the pinned tool in explicit DD_FLOW_RESOURCE_HOME (legacy
+fallback: DD_FLOW_HOME). Uses no RUN database and starts no provider Session.
+Returns version, platform, binary/archive checksums and cache_root. Availability
+does not approve any worktree or productive action.`],
+    ...["release", "deploy", "publish"].map((flow) => [`flow ${flow}`, `dd-flow flow ${flow} - start or replay one request-bound delivery RUN
+
+Usage:
+  dd-flow flow ${flow} --project-root /absolute/project --request-id ID --intake-file /absolute/request.txt --profile ID --json
+  dd-flow flow ${flow} --project-root /absolute/project --request-id ID --detach --json
+
+Fresh execution uses the installed canon and selected frozen engine, preserves
+the original request and operates in the assigned checkout. Managed Stage
+Sessions use the ordinary controller; independent verification requires a
+different physical Session, not merely another profile name. Starting the RUN
+does not approve a version, target, publication or deployment. Each productive
+operation needs its exact retained user approval and fresh access readback.
+
+Replay the same request ID to restore the original RUN, bundle, workspace and
+profiles. Omit current selectors and intake on replay; supplied values must match.
+--prepare-only creates runtime state but launches no provider Session; --detach
+returns the controller receipt without cancelling it. Unknown productive effects
+require original-intent reconciliation, never a new request or automatic retry.
+Use --option NAME --help for each option's exact contract.`]),
+    ["delivery", `dd-flow delivery - operations inside an existing delivery RUN
+
+Usage:
+  dd-flow delivery inputs RUN --project-root /absolute/project --stage STAGE --json
+  dd-flow delivery checks RUN --project-root /absolute/project --stage prepare --result-file /absolute/artifact.json --json
+  dd-flow delivery execute RUN --project-root /absolute/project --stage publish --result-file /absolute/approval.json --json
+  dd-flow delivery reconcile RUN --project-root /absolute/project --stage publish --json
+
+inputs is read-only and grants no authority. checks, execute and reconcile must
+use the exact command issued to the current physical Stage coordinator; an
+ambient scope variable or a Work Session cannot authorize them. They never
+allocate a new RUN. Use each command's --help or --option NAME --help for inputs.
+Checks use existing project policy and runner. Execution requires separate exact
+user approval, fresh access and original intent. Reconcile reads the original
+result without new publication or implicit retry; Stage/RUN finish is separate.`],
+    ["flow interactive", `dd-flow flow interactive - start or replay one request-bound interactive RUN
+
+Usage:
+  dd-flow flow interactive --project-root /absolute/project --request-id ID --intake-file /absolute/request.txt [--profile ID] --json
+  dd-flow flow interactive --project-root /absolute/project --request-id ID --execution managed --intake-file /absolute/request.txt --detach --json
+
+The default attached route requires a unique current trusted observation of this
+exact launch argv, workspace and profile. No automatic managed fallback. Managed
+execution must be selected explicitly and uses the existing RUN-bound controller.
+
+The project-local curated pack, engine, profiles, original request and Git baseline
+are frozen before execution. Use an existing registered project/prepared Home and
+assigned checkout; this command does not create a worktree or migrate storage.
+--prepare-only retains runtime state without productive dispatch: not a dry run.
+Replay may omit selectors; supplied values must match original retained intent.
+
+Stages: preflight → interactive → consolidation → hardening → review → integration.
+Use interactive inputs/turn/finish/scope within this same RUN. Explicit finish
+closes free-turn intake, not review, Git approval or RUN completion. Hardening and
+independent critics use registered Work and actual checks. Scoped Git integration
+preserves unrelated work and never pushes. Historical RUNs keep their own engine.`],
+    ["interactive", `dd-flow interactive - operate on an existing interactive RUN
+
+Commands:
+  inputs       Read original request, turns, HITL answers and current digest.
+  turn         Retain verbatim user input with stable identity and expected digest.
+  finish       Explicitly close free-turn intake; no new RUN or automatic approval.
+  scope        Retain selected mutation scope backed by genuine delivered input.
+  git-inputs   Inspect original selected workspace/index/HEAD versions read-only.
+  register     Register the initial hardening/review Work graph, not a provider.
+  checks       Select and execute current obligations through the common runner.
+  correction   Register a separate author from the exact negative reviewer Work.
+  re-review    Register a fresh independent critic after correction and checks.
+  integrate    Perform/reconcile only the accepted scoped local Git operation.
+
+All commands require --project-root and --run. Use a command's --help or
+--option NAME --help for its exact required inputs. They do not allocate a new RUN.
+The top-level finish alias accepts exactly the same inputs as interactive finish.
+Read-only inputs/git-inputs never initialize stores. Write operations require the
+existing prepared store; they do not migrate it. Exact retries preserve original
+custody. Unknown Git effects require reconciliation, not another commit or push.
+Use ordinary run control for cancellation; observer disconnect is not stop.`],
+    ["flow review-fix", `dd-flow flow review-fix - agree diagnostic scope and retain a raw handoff
+
+Usage:
+  dd-flow flow review-fix --project-root /absolute/project --request-id ID --source-run RUN-001-audit --finding FIND-001 --intake-file /absolute/request.txt [--profile ID] --json
+
+Stages: intake → scope-review → handoff. Select exact accepted diagnostic findings;
+selection is not approval to implement. The private snapshot is read-only.
+Scope-review uses a physically independent Session and considers the original
+request plus every actual delivered answer. Deferred, declined and needs_scope
+remain distinct from a ready handoff. No code, project documents or Git are changed.
+
+CLI retains original finding evidence and raw user inputs, not an agent-authored
+replacement specification. Even ready scope grants no formalization authority:
+only a separate explicit user request may start an ordinary SPECIFY-first SDLC RUN.
+
+Profiles, engine, canon, findings and original request are frozen before dispatch.
+Replay may omit selectors; supplied values must match the retained request.
+--prepare-only creates the source snapshot and RUN without controller/provider
+Sessions; it is not a dry run. --detach returns the controller receipt.
+Default execution is managed new_session with external concurrency 1; same_session
+cannot provide independent scope-review and refuses before request allocation.`],
+    ["flow mb-distill", `dd-flow flow mb-distill - extract and promote reusable practices
+
+Usage:
+  dd-flow flow mb-distill --project-root /absolute/project --request-id ID --intake-file /absolute/request.txt [--profile ID] --json
+
+Stages: preflight → extract → review → promote → verify → finish.
+Extraction uses a read-only source snapshot, domain/process applicability and
+independent novelty/portability critics. Promotion requires a separately accepted destination
+and exact candidate/document write scope. Source selection never grants shared
+canon write authority. Verification reads original selected documents and actual
+published outputs in an independent physical Session; missing evidence refuses.
+
+Profiles, engine, canon and original request are frozen before dispatch. Exact
+replay may omit selectors; supplied selectors must match the retained request.
+--prepare-only retains the snapshot and RUN without launching provider Sessions;
+it is not a dry run. --detach returns the controller receipt. Default execution
+uses fresh stage Sessions and external Work with concurrency 1. Use existing
+run drive status and run control commands to observe or reconcile this RUN.`],
+    ["flow mb-audit", `dd-flow flow mb-audit - read-only Memory Bank audit
+
+Usage:
+  dd-flow flow mb-audit --project-root /absolute/project --request-id ID --intake-file /absolute/request.txt [--profile ID] --json
+
+Describe quick/full or focused audit scope in the original intake. Stages are
+preflight → audit → review → report. Applicable aspects use assigned read-only
+Work and independent critics. Missing evidence and active DEFs remain visible.
+Reports and runtime state live in DD_FLOW_HOME; project files are not repaired.
+The snapshot includes selected dirty/untracked source, excluding private inputs.
+
+Profiles, engine, canon and objective are frozen before dispatch. Exact replay
+may omit intake/profile selectors; supplied selectors must match the original.
+--prepare-only creates the snapshot and RUN without Sessions; --detach returns
+the controller receipt. Neither is a dry run. Default execution is managed,
+with fresh stage Sessions and external Work (concurrency 1).
+Use existing run drive status and run control commands for observation/recovery.`],
+    ["flow project-review", `dd-flow review / flow project-review - read-only project-conformance review
+
+Usage:
+  dd-flow review --project-root /absolute/project --request-id ID --intake-file /absolute/request.txt [--profile ID] --json
+
+Both spellings share validation and effects. Describe the review focus and
+constraints in the original intake. Stages are preflight → analyze → review →
+report. Compare specs, features, ADRs, scenarios and policy with actual code and
+evidence. This is not SDLC CODE-REVIEW and never implicitly repairs the project.
+All baseline aspects retain applicability and coverage; independent criticism,
+rejected findings and uncertainty remain in runtime evidence.
+
+Execution uses an isolated read-only snapshot and frozen global canon. No local
+Memory Bank installation is required. Profiles and the original request remain
+pinned on replay. --prepare-only creates runtime state without Sessions;
+--detach returns the accepted controller receipt. Default execution is managed,
+with fresh stage Sessions and external Work. Use run drive status / run control
+to observe, answer, stop or reconcile the exact retained RUN.`],
+    ["runtime storage qualify", `dd-flow runtime storage qualify - pre-probe selected-engine capability
+
+--operation memory-upgrade checks existing storage with the executing engine.
+Compatible stores use ordinary operation admission. Otherwise, drained source
+stores are copied with committed WAL to a private temporary directory; actual
+migration and target operation admission run only on those copies.
+
+Requires explicit canonical DD_FLOW_HOME and DD_FLOW_RESOURCE_HOME. The result
+is capability only: it does not authorize writes, create a RUN, publish migration
+evidence for real stores or start a model. Original storage is never migrated.
+Public upgrade still requires a separately retained plan and explicit apply.`],
+    ["runtime storage transition", `dd-flow runtime storage transition - selected-engine pre-context storage transport
+
+Normal project entry remains dd-flow upgrade. This transport executes only in
+the immutable entrypoint selected by the original retained upgrade request.
+It requires explicit DD_FLOW_HOME and DD_FLOW_RESOURCE_HOME and never initializes
+storage, chooses another engine, starts a model or allocates a RUN.
+
+--action plan retains both store snapshots and returns exact apply/status commands.
+apply requires the retained --expected-sha256 and --offline; both backups are
+verified before the first schema change. Unknown effects require exact-request
+status/reconciliation, not a new selector or replacement plan.
+
+recovery-plan requires the migration SHA, --recovery-id and --offline. Selecting
+recovery fences both stores and aborts the old apply; recover and recovery-status
+use the returned recovery SHA. Restoration is never automatic.
+
+The offline switch acknowledges external drain; logical and physical registered
+owners are checked independently. No owner is terminated by this transport.`],
+    ["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 status --scope-ids-json '["EVAL_ID","QUAL_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 +422,15 @@ 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.
+  memory distill inputs/publish Read retained input or publish an accepted scope in an already bound distill RUN.
   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.
@@ -128,7 +521,7 @@ Examples:
     ],
     [
         "canon",
-        `dd-flow canon - register and resolve the canonical Memory Bank checkout
+        `dd-flow canon - register and resolve the canonical Memory Bank source
 
 Usage:
   dd-flow canon register --root <canonical-dd-memorybank-root> --json
@@ -137,6 +530,8 @@ Usage:
 
 Discovery order is explicit --root, then DD_MEMORYBANK, then the globally registered runtime value in DD_FLOW_HOME, then known nearby dd-memorybank checkouts from the current working directory. Explicit --root is the only source considered for that command. If multiple different valid canonical checkouts are found, resolve fails closed with blockers so the caller chooses intentionally.
 
+Without an explicit, environment or registered source, the release installed by setup in DD_FLOW_HOME takes precedence over nearby checkouts. Its commit comes from the retained release manifest, not ancestor Git history. A degraded installation is reported; it never silently falls back to a nearby checkout.
+
 A valid canonical root contains dd-flow/README.md, mbb/index.md, protocol/index.md, and canonical-only entrypoints such as dd-flow/mb-init.md, dd-flow/mb-upgrade.md, and dd-flow/mb-distill.md. Current canon runs mb-upgrade review as the 05-review stage inside mb-upgrade, not as a top-level mb-upgrade-review.md entrypoint.
 
 Examples:
@@ -152,12 +547,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 <flow>] --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 +570,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 +591,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 +616,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 +918,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 +955,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 +1026,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" });
 }