@deksden-com/dd-flow-cli 0.6.0 → 0.8.0-beta.135

package/dist/cli/help.js

@@ -12,29 +12,35 @@ Core commands:
   version                       Print the installed dd-flow CLI package version.
   status                        Inspect dd-flow runtime, project and canon roots.
   engine install/list/info      Manage locally installed dd-flow engine snapshots.
-  engine resolve/doctor         Inspect router engine selection and health.
+  engine resolve/doctor/bind-run Inspect router selection, health, and recover a legacy RUN binding.
   canon register/status/resolve Register and resolve the canonical Memory Bank.
   project register/status/summary Register a project, inspect state, and publish project summaries.
   project resolve/archive       Resolve typed ids and archive stale project roots.
   project migrate-ids           Migrate old project ids.
   protocol register/status/transition Register, inspect, transition and repair protocol state.
-  migration impact/plan/report/verify Assess release impact and prepare mb-upgrade migration evidence.
+  migration impact/plan/report/verify/apply Assess release impact and explicitly apply mb-upgrade migration evidence.
   cleanup scan/apply            Detect and repair stale local runtime state.
-  run start/status/list/timeline/usage/flags Track concrete flow executions, timing, source-aware usage and RUN-local flow flags.
-  stage start/finish           Run the canonical two-command stage lifecycle and generate evidence.
+  run start/status/list/timeline/usage/flags/vars Track concrete flow executions, timing, source-aware usage and RUN context.
+  stat usage/run sessions ls      Refresh source-backed usage and reconcile settled Sessions, or list RUN Sessions.
+  stage start/pause/resume/finish Run a stage lifecycle, including in-stage user interaction.
+  work status|add-batch|ls|show|deps|delete|start|finish|fail|retry|cancel  Manage vNext Work.
   id next                       Preview next typed ids for protocol or run allocation.
-  plan status/item              Inspect canonical plans and update SQLite progress.
+  plan status/item/reviews      Inspect plans, update SQLite progress, or dispatch vNext grouped reviews.
   prompt render                 Render one bounded, RUN-local worker launch prompt.
   lane workspace/lock/status    Manage shared workspace lanes and leases.
   merge status/one-shot/bundle  Inspect, claim, or complete merge work from the current session.
   merge-worker status/start/stop Manage long-lived project merge workers.
-  merge-queue status/next       Claim, wait for, complete, or fail merge jobs.
+  merge-queue status/claim/next Claim, wait for, complete, or fail merge jobs.
   session register/status/stop  Register flow sessions and stop workers.
   dashboard data/render/open/refresh Render, refresh, open, and inspect project/global dashboards.
   schema validate             Validate canonical dd-flow JSON data contracts.
   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.
+  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.
 
 Examples:
@@ -86,6 +92,7 @@ Usage:
   dd-flow engine info [--package <name>] [--version <version>] --json
   dd-flow engine resolve [--project-root <root>] --json
   dd-flow engine doctor [--project-root <root>] --json
+  dd-flow engine bind-run <RUN-ID> --project-root <root> --engine-version <version> --reason <text> [--integrity-checksum <sha256>] --json
 
 The globally invoked dd-flow command is the stable router surface. Engine snapshots live under DD_FLOW_HOME/engines and are selected by project Memory Bank compatibility data. Running an old package through npx can install that package's own engine without replacing the global router:
 
@@ -93,11 +100,14 @@ The globally invoked dd-flow command is the stable router surface. Engine snapsh
 
 Router-native engine commands never mutate project runtime data. Normal project commands are routed to a compatible engine or fail closed with a missing-engine diagnostic.
 
+engine bind-run is the one recovery command for a legacy RUN without an engine-binding sidecar. It probes the requested installed snapshot with run status before atomically writing an immutable binding; later RUN commands route through that snapshot.
+
 Examples:
   dd-flow engine install --json
   dd-flow engine list --json
   dd-flow engine resolve --project-root "$PWD" --json
-  dd-flow engine doctor --project-root "$PWD" --json`
+  dd-flow engine doctor --project-root "$PWD" --json
+  dd-flow engine bind-run RUN-193 --project-root "$PWD" --engine-version 0.4.2 --reason "legacy flow-run@1" --json`
     ],
     [
         "status",
@@ -143,15 +153,23 @@ Usage:
   dd-flow id next --type protocol|run --project-root <root> --slug <slug> --json
   dd-flow run status <RUN-ID|RUN-short-id> --project-root <root> --json
   dd-flow run list --project-root <root> --json
+  dd-flow run 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 snapshot bootstrap restore --snapshot <directory> --project-root <prepared-root> --json
   dd-flow run timeline <RUN-ID|RUN-short-id> --project-root <root> --json
-  dd-flow run usage <RUN-ID|RUN-short-id> --project-root <root> [--group-by session|role|stage|aspect|plan-item] --json
+  dd-flow 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
   dd-flow run flags status <RUN-ID|RUN-short-id> --project-root <root> --json
   dd-flow run flags revise <RUN-ID|RUN-short-id> --project-root <root> --expected-revision <n> --idempotency-key <key> [--preset <name>] [--flag key=value] [--flag key=value] [--allow-downgrade --reason <text>] --json
   dd-flow run attach-stage <RUN-ID|RUN-short-id> --project-root <root> --stage <name> --dir <NN-stage-slug> --status <status> [--data-schema-id <id>] --json
   dd-flow run complete-stage <RUN-ID|RUN-short-id> --project-root <root> --stage <name> --status <status> [--stage-report <path>] [--data <path>] [--data-schema-id <id>] [--report <path>] [--alias <path>] --json
-  dd-flow run complete <RUN-ID|RUN-short-id> --project-root <root> --status done|blocked|cancelled|failed [--verdict <text>] [--next-action <text>] --json
+  dd-flow run override <RUN-ID|RUN-short-id> --project-root <root> --status cancelled|failed --reason <text> [--verdict <text>] [--next-action <text>] --json
+
+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-* 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. The run usage command reconciles registered local Codex transcript counters before reporting; 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.
 
 Examples:
   dd-flow run start --project-root "$PWD" --flow-kind mb_sdlc --subject-type protocol --subject-id PRT-001-demo --slug demo --json
@@ -164,11 +182,31 @@ Examples:
         `dd-flow stage - execute one bounded stage lifecycle
 
 Usage:
-  dd-flow stage start <RUN-ID|RUN-short-id> --project-root <root> --stage <name> [--dir <NN-stage-slug>] --json
-  dd-flow stage start --bootstrap --project-root <root> --stage specify --subject <safe-subject> [--intake-file <path>] --json
-  dd-flow stage finish <RUN-ID|RUN-short-id> --project-root <root> --stage <name> [--outcome done|blocked|failed] [--semantic-file <RUN-local-json>] --json
+  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 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 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.`
+    ],
+    [
+        "work",
+        `dd-flow work - inspect or advance a beta vNext Work
+
+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 finish <WORK-ID> (--result-file <path>|--result-stdin) --project-root <root> --json
+  dd-flow work repair add --run <RUN-ID> --from-check <CHECK-ID> --origin-work <WORK-ID>... [--write-scope <path>...] --task-stdin --project-root <root> --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 finish command. The same packet is written to RUN-local stage-prompt.md and stage-prompt.json. --bootstrap creates the initial protocol/RUN envelope and copies the supplied intake into the RUN home before starting specify. stage finish defaults to @stage/stage-input.json, accepts semantic --outcome and always generates validated JSON, Markdown, template-backed HTML and a durable protocol-summary projection. Raw intake and telemetry remain RUN-local.`
+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 returns the exact failed receipt and repair command; repair add creates a new Work from the selected completed origin context plus that failure evidence. Exact existing project files named by the retained receipt output are added to its repair scope deterministically; repeat --write-scope only for an additional path not named there.`
     ],
     [
         "id",
@@ -234,11 +272,12 @@ New registrations use full typed ids such as PRJ-001-dd-flow-playground and shor
         `dd-flow migration - plan and verify mb-upgrade runtime/home data migrations
 
 Usage:
-  dd-flow migration plan --project-root <root> [--source-version <version>] [--target-version <version>] [--run <RUN-ID>] [--backup-path <path>] [--backup-created-at <iso>] [--allow-active true|false] --json
-  dd-flow migration report --project-root <root> [--source-version <version>] [--target-version <version>] [--run <RUN-ID>] [--backup-path <path>] [--backup-created-at <iso>] [--allow-active true|false] --json
+  dd-flow migration plan --project-root <root> [--source-version <version>] [--target-version <version>] [--run <RUN-ID>] [--backup-path <path>] [--backup-created-at <iso>] --json
+  dd-flow migration report --project-root <root> [--source-version <version>] [--target-version <version>] [--run <RUN-ID>] [--backup-path <path>] [--backup-created-at <iso>] --json
   dd-flow migration verify --file <mb-upgrade-migration-report.json> --json
+  dd-flow migration apply --project-root <root> --file <mb-upgrade-migration-report.json> --json
 
-Migration commands are evidence and guardrail helpers for canonical mb-upgrade. They do not silently migrate runtime/home data during ordinary CLI use. Applying migrations remains an explicit mb-upgrade contour with backup, adjacent migration chain, active-state handling, derived artifact regeneration and post-upgrade verification.
+Migration commands are evidence and guardrail helpers for canonical mb-upgrade. They do not silently migrate runtime/home data during ordinary CLI use. Applying migrations is an explicit contour requiring a real verified backup, adjacent migration chain, quiescent shared home, recovery evidence and idempotent rerun.
 
 Related commands:
   dd-flow status --project-root <root> --json
@@ -354,13 +393,14 @@ start is idempotent: if a worker, claimed job, or active merge lock already exis
 Usage:
   dd-flow merge-queue status --project-root <root> --json
   dd-flow merge-queue next --project-root <root> --worker-id <id> [--path <workspace>] --json
+  dd-flow merge-queue claim <protocol-id> [--project-root <root>] --worker-id <id> [--path <workspace>] --json
   dd-flow merge-queue wait-next --project-root <root> --worker-id <id> [--path <workspace>] --timeout <seconds> --poll-interval <seconds> [--acquire-lock true] --json
   dd-flow merge-queue complete <protocol-id> [--project-root <root>] --worker-id <id> [--path <workspace>] --summary <text> --json
   dd-flow merge-queue note <protocol-id> [--project-root <root>] --worker-id <id> --summary <text> --json
   dd-flow merge-queue fail <protocol-id> [--project-root <root>] --worker-id <id> [--path <workspace>] --reason <text> --requeue true|false --json
   dd-flow merge-queue cancel <protocol-id> [--project-root <root>] --reason <text> [--worker-id <id>] [--path <workspace>] [--force] --json
 
-The worker must own the merge lane from the registered merge workspace before claiming, completing, or failing queued protocols. Outputs use queue_item/protocol/claim as the primary contract and retain job as a compatibility alias. note updates the final completion summary after post-complete cleanup and does not require a lane lock. --path defaults to the current working directory. Use --worker-id as the owner identity.
+The worker must own the merge lane from the registered merge workspace before claiming, completing, or failing queued protocols. next remains FIFO; claim <protocol-id> atomically claims only that ready/requeued job. Outputs use queue_item/protocol/claim as the primary contract and retain job as a compatibility alias. note updates the final completion summary after post-complete cleanup and does not require a lane lock. --path defaults to the current working directory. Use --worker-id as the owner identity.
 
 For branch-level integration prefer:
   dd-flow merge bundle status --project-root "$PWD" --path "$PWD" --json
@@ -406,6 +446,16 @@ Usage:
   dd-flow session stop-worker --project-root <root> --worker-id <id> --reason <text> --json
 
 Session registration is the durable contract used by Stop hooks. Prompts register flow_kind, continuation_policy, protocol_id, worker_id, and workspace_path explicitly. Prefer --payload-file in Codex prompts because PreToolUse hooks see the raw shell command before variable expansion.`
+    ],
+    [
+        "run config",
+        `dd-flow run config - inspect and set RUN-scoped flow choices
+
+Usage:
+  dd-flow run config status <RUN-ID> --project-root <root> --json
+  dd-flow run config set <RUN-ID> --project-root <root> --key plan_review.mode --value auto|off|standard|deep --reason <text> --json
+
+PLAN review policy belongs to the RUN. It defaults to auto and is frozen once PLAN-REVIEW starts. The CLI never infers this choice from intake prose.`
     ],
     [
         "project config",
@@ -527,7 +577,47 @@ Usage:
   dd-flow codex home print-env --project-root <root> [--profile <name>] --json
   dd-flow codex home remove --project-root <root> [--profile <name>] --mode keep-shared|remove-owned --json
 
+  dd-flow codex hook handle --event <HookEventName> [--project-root <root>] --json
+
+Managed hooks omit --project-root. Codex supplies cwd in the stdin payload; the
+handler resolves the registered project from cwd. The option is only a manual
+override.
+
 Managed homes isolate dd-flow hooks while sharing selected Codex state from the source home.`
+    ],
+    [
+        "zcode event",
+        `dd-flow zcode event - ingest a zcode-acp session/update notification
+
+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.`
+    ],
+    [
+        "opencode event",
+        `dd-flow opencode event - ingest a controlled OpenCode tool hook
+
+Usage:
+  dd-flow opencode event handle --project-root <root> --json
+  dd-flow opencode usage ingest --project-root <root> --json
+
+Both payloads are read from stdin. The event adapter reuses the trusted
+lifecycle receipt; the usage adapter retains cumulative OpenCode Session and
+tool counters for RUN accounting.`
+    ],
+    [
+        "agy event",
+        `dd-flow agy event - ingest a controlled Antigravity CLI tool hook
+
+Usage:
+  dd-flow agy event handle --project-root <root> --json
+  dd-flow agy usage ingest --project-root <root> --json
+
+Both payloads are read from stdin. The event adapter records lifecycle identity;
+the usage adapter retains cumulative conversation and tool counters.`
     ],
     [
         "worktree",