@khoavu882/doflow 2.0.0-beta.5 → 2.0.0

package/src/cli/index.js

@@ -2,7 +2,7 @@
 // doflow CLI — argument parsing, the installer command table, and dispatch.
 //
 // bin/doflow.js is only a forwarder into main() here. This module owns: parseArgs (verbatim from
-// the pre-extraction monolith), the ONE table mapping the nine installer command names to their
+// the pre-extraction monolith), the ONE table mapping the ten installer command names to their
 // handlers under commands/, and the runtime verbs' forwarding via ./runtime-commands — whose
 // implementations stay one-per-module in src/runtime/. Adding an installer command means a new
 // file in src/cli/commands/, an entry in COMMANDS, and an edit to test/guards/cli-boundary.test.js,
@@ -12,10 +12,11 @@ const {
   handleCapabilitiesCommand, handleReadinessCommand, handleEvidenceCommand,
   EVIDENCE_SCORE_FIELDS, scoreFieldRefusal,
 } = require('../runtime/cli.js');
-const { pkg } = require('./shared.js');
+const { pkg, REPO_ROOT } = require('./shared.js');
 const { VALID: VALID_TARGETS, DEFAULT_TARGETS } = require('../install/targets.js');
 const { dispatchRuntimeCommand } = require('./runtime-commands.js');
 const { usageError } = require('../runtime/cli-result.js');
+const { printSafe } = require('../runtime/mask.js');
 
 const cmdInstall = require('./commands/install.js');
 const cmdUpdate = require('./commands/update.js');
@@ -26,6 +27,7 @@ const cmdTools = require('./commands/tools.js');
 const cmdListBackups = require('./commands/list-backups.js');
 const cmdRollback = require('./commands/rollback.js');
 const cmdSelfUpdate = require('./commands/self-update.js');
+const cmdUi = require('./commands/ui.js');
 
 /** The installer command surface, written down once. The runtime verbs are dispatched separately
  * (see ./runtime-commands) because their namespace is owned by the doflow-run verb table. */
@@ -39,6 +41,8 @@ const COMMANDS                                  = {
   'list-backups': cmdListBackups,
   rollback: cmdRollback,
   'self-update': cmdSelfUpdate,
+  // The launcher takes the core root as an argument so it loads nothing but three built-ins (092 IC-008).
+  ui: (o     ) => cmdUi(o, REPO_ROOT),
 };
 
 /** "skip all backup protection" must be an explicit, deliberate choice, never a default combo. */
@@ -51,28 +55,62 @@ function assertNoBackupRequiresForce(o     )       {
 
 function parseArgs(argv          )      {
   const o      = { cmd: null, positional: [], targets: [], mcp: null, dryRun: false, force: false, adopt: false,
+    otlpHttp: false,
     noBackup: false, prune: null, global: false, json: false, help: false, version: false,
     tools: null, action: 'status', days: null, slug: null,
     // Explicitly null, not absent. `handleReadinessCommand` declares defaults of `'feature'` and
     // `'default'`, and a JavaScript default parameter fires on `undefined` — so an *absent* key
     // silently reinstated exactly the identity defect readiness.ts fixed by failing closed.
-    taskClass: null, taskId: null };
+    taskClass: null, taskId: null,
+    flagsGiven: [] };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
-    switch (a) {
+    if (a.startsWith('-')) o.flagsGiven.push(a);
+    // `--commit` is the roadmap verb's own flag: anywhere else it must reach the default branch and get
+    // that verb's unknown-flag answer, as it did before it was added. '' matches no case.
+    switch (a === '--commit' && o.cmd !== 'roadmap' ? '' : a) {
       case '-h': case '--help': o.help = true; break;
-      case '-v': case '--version': o.version = true; break;
+      case '-v': o.version = true; break;
+      case '--version':
+        if (o.cmd === 'package' && argv[i + 1] !== undefined && !argv[i + 1].startsWith('-')) {
+          o.packageVersion = argv[++i];
+        } else o.version = true;
+        break;
       case '-n': case '--dry-run': o.dryRun = true; break;
+      case '--otlp-http': o.otlpHttp = true; break;
       case '-f': case '--force': o.force = true; break;
       case '--adopt': o.adopt = true; break;
+      // task-attempt --action cancel (run): a switch, so it cannot go through parseRuntimeFlag,
+      // which reads only flags that take a value (IC-017).
+      case '--adopt-unowned': o.adoptUnowned = true; break;
+      // worker --action run: wait for the run to end. A switch, like --adopt-unowned (081 IC-026).
+      case '--wait': o.wait = true; break;
+      // slot --action run: refuse at once instead of queueing (115 IC-008). A switch, so key `noWait`.
+      case '--no-wait': o.noWait = true; break;
+      // slot --action run -- <command> [args...]: everything after the first `--` is the command's
+      // own argv, never parsed here (115 IC-008). Any other verb still refuses a bare `--` below.
+      case '--':
+        if (o.cmd === 'slot') { o.slotCommand = argv.slice(i + 1); i = argv.length; break; }
+        if (o.cmd === 'plan-check') break;
+        console.error(unknownFlagMessage(a)); process.exit(unknownFlagExit(o.cmd));
+        break;
+      // worker --action run|describe|select: the isolated-edit recipe and baseline (082 IC-014).
+      case '--edit': o.edit = true; break;
       case '-g': case '--global': o.global = true; break;
       case '--no-backup': o.noBackup = true; break;
       case '--permissions': o.permissions = true; break;
       case '--statusline': o.statusline = true; break;
       case '--json': o.json = true; break;
+      case '--show-origin': o.showOrigin = true; break;
       case '--bare': o.bare = true; break;
       case '--no-record': o.noRecord = true; break;
+      // context-emit: decide and render without taking a claim or writing a ledger line.
+      case '--peek': o.peek = true; break;
       case '--check': o.check = true; break;
+      // roadmap --action init-policy: commit the policy onto local develop by plumbing instead of only writing it.
+      case '--commit': o.commit = true; break;
+      // package --action verify: rewrite an unreadable state.json (never widens, 122 IC-009).
+      case '--repair': o.repair = true; break;
       // decision --action list: every decision by id, not just the live ones.
       case '--all': o.all = true; break;
       // lifecycle --action overview: the /do maintain view, with a larger list and a pending count.
@@ -84,6 +122,8 @@ function parseArgs(argv          )      {
       // advise --action configure: these are deliberately presence-only switches.
       case '--off': o.off = true; break;
       case '--project': o.project = true; break;
+      // evidence --action retire: retire every item the ledger classes stale.
+      case '--stale': o.stale = true; break;
       // goal --action check: record the item as not met (evidence is still required, as the reason).
       case '--unmet': o.unmet = true; break;
       // goal --action link: move a feature that already serves another goal.
@@ -109,12 +149,13 @@ function parseArgs(argv          )      {
       }
       case '--action': {
         const val = argv[i + 1];
-        if (val === undefined || val.startsWith('-')) { console.error(`doflow: ${a} requires a value`); process.exit(1); }
+        // `review`, `protocol`, `config`, `primary` and `package` answer a missing value as usage, exit 2; other verbs keep exit 1.
+        if (val === undefined || val.startsWith('-')) { console.error(`doflow: ${a} requires a value`); process.exit(o.cmd === 'review' || o.cmd === 'protocol' || o.cmd === 'config' || o.cmd === 'primary' || o.cmd === 'fleet' || o.cmd === 'transcript' || o.cmd === 'package' ? 2 : 1); }
         o.action = val; o.actionGiven = true; i++; break;
       }
       case '--task-class': {
         const val = argv[i + 1];
-        if (val === undefined || val.startsWith('-')) { console.error(`doflow: ${a} requires a value`); process.exit(1); }
+        if (val === undefined || val.startsWith('-')) { console.error(`doflow: ${a} requires a value`); process.exit(o.cmd === 'protocol' || o.cmd === 'rules' ? 2 : 1); }
         o.taskClass = val; i++; break;
       }
       case '--task-id': {
@@ -193,20 +234,45 @@ function parseArgs(argv          )      {
         // its validation subtly wrong.
         const runtime = parseRuntimeFlag(a, argv, i, o);
         if (runtime !== null) { i = runtime; break; }
-        if (a.startsWith('-')) { console.error(`doflow: unknown flag '${a}'`); process.exit(1); }
+        // slot, primary, fleet and transcript report an unknown flag as their own usage error (exit 2, 115 IC-008, 120 IC-008).
+        if (a.startsWith('-') && (o.cmd === 'slot' || o.cmd === 'primary' || o.cmd === 'fleet' || o.cmd === 'transcript')) (o.extraFlags = o.extraFlags || []).push(a);
+        else if (a.startsWith('-') && o.cmd !== 'plan-check') { console.error(unknownFlagMessage(a)); process.exit(unknownFlagExit(o.cmd)); }
         else if (!o.cmd) o.cmd = a;
         else o.positional.push(a);
       }
     }
   }
+  if (o.cmd === 'plan-check') o.extraFlags = o.flagsGiven;
   return o;
 }
 
+/** Verbs that answer an unrecognised flag as a usage error (exit 2); every other verb keeps exit 1. */
+function unknownFlagExit(cmd               )         {
+  return cmd === 'protocol' || cmd === 'config' || cmd === 'rules' || cmd === 'review' ? 2 : 1;
+}
+
+/** Longest part of an unrecognised argument echoed back; the rest is cut and marked. */
+const UNKNOWN_FLAG_ECHO_CHARS = 80;
+
+/** The unknown-flag error: the argument is untrusted text, so it is made print-safe (no control
+ * characters, one line) and cut to a bounded length (FU-8eqytg). */
+function unknownFlagMessage(arg        )         {
+  const safe = printSafe(String(arg));
+  const shown = safe.length > UNKNOWN_FLAG_ECHO_CHARS ? `${safe.slice(0, UNKNOWN_FLAG_ECHO_CHARS)}...` : safe;
+  return `doflow: unknown flag '${shown}'`;
+}
+
 /** Single-value arguments of the runtime verbs → the option key each one writes. */
 const RUNTIME_STRING_FLAGS = new Map([
   // `scaffold`. The resolver's own ambiguous-feature error tells the caller to "re-run with
   // --slug=<chosen>"; without this flag that hint would name an argument this CLI rejects.
   ['--slug', 'slug'],
+  ['--listen-address', 'listenAddress'], // ui: explicit private interface for TLS phone access
+  ['--tls-cert', 'tlsCert'],             // ui: absolute PEM certificate chain
+  ['--tls-key', 'tlsKey'],               // ui: absolute PEM private key
+  // `--reason <text>` is parsed by its own case above; this entry is the `--reason=<text>` spelling
+  // of the same flag (FU-8eqytg), so the two forms mean the same on every verb that accepts it.
+  ['--reason', 'reason'],
   ['--rationale', 'rationale'],        // classify: why this class was proposed · decision --action add: why it was decided
   ['--request', 'request'],            // classify: request text for an advisory second opinion
   ['--request-file', 'requestFile'],   // classify: request text read from a file
@@ -216,6 +282,7 @@ const RUNTIME_STRING_FLAGS = new Map([
   ['--supersedes', 'supersedes'],      // comma-separated DEC-### ids this decision replaces
   ['--refs', 'refs'],                  // comma-separated ids the decision touches, e.g. FR-001,IC-002
   ['--source', 'source'],              // where the decision was stated, e.g. design/design-02-question.md#question-1
+  ['--index', 'index'],                // package add: local pinned package index
   // followup and lifecycle (feature 046). `--statement`, `--stage`, `--slug`, `--batch`, `--reason`,
   // `--channel`, `--state`, `--source`, `--intent`, `--task-class` and `--task-id` above are shared.
   ['--ids', 'ids'],                    // followup: comma-separated FU-xxxxxx ids to take, settle or promote
@@ -264,6 +331,18 @@ const RUNTIME_STRING_FLAGS = new Map([
   ['--mandatory-file', 'mandatoryFile'], // context-pack: caller-supplied mandatory fields
   ['--max-bytes', 'maxBytes'],         // context-pack: per-call cap in bytes
   ['--expand', 'expand'],              // context-pack: pointer id to expand
+  // 078 context-emit (IC-005). Identity is read from the environment only; no flag sets it.
+  ['--event', 'event'],                // context-emit: launch | prompt | delta
+  ['--cwd', 'cwd'],                    // context-emit: the working directory the emission is for
+  ['--session', 'session'],            // context-emit: the harness session id
+  ['--nudge', 'nudge'],                // context-emit: nudge | suppress | none
+  // 078 context-grant (IC-013). `--max-bytes` above is shared.
+  ['--summary', 'summary'],            // context-grant: a summary id, or pending
+  ['--to-run', 'toRun'],               // context-grant: the recipient run id
+  ['--to-lineage', 'toLineage'],       // context-grant: the recipient lineage id
+  ['--from-worktree', 'fromWorktree'], // context-grant: source scope worktree (default DOFLOW_WORKTREE or cwd)
+  ['--from-run', 'fromRun'],           // context-grant: source scope run (default DOFLOW_RUN_ID or local)
+  ['--from-lineage', 'fromLineage'],   // context-grant: source scope lineage (default DOFLOW_LINEAGE_ID or main)
   ['--stage-id', 'stageId'],           // research-request: active feature stage
   ['--question', 'question'],           // research-request: external question
   ['--blocking', 'blocking'],           // research-request: true | false
@@ -289,7 +368,10 @@ const RUNTIME_STRING_FLAGS = new Map([
   ['--tier', 'tier'],                  // brief-tools: the task line's tier (light | standard | frontier)
   ['--harness', 'harness'],            // brief-tools: the harness the brief is for
   ['--policy', 'policy'],              // enforcement: lifecycle policy id
-  ['--profile', 'profile'],             // enforcement: coverage profile filter
+  ['--profile', 'profile'],             // enforcement profile; retrieve --scope code: lexical-only|hybrid
+  ['--root', 'root'],                    // retrieve --scope code: project root (never harness-home)
+  ['--index-action', 'indexAction'],    // retrieve --scope code: explicit build|refresh
+  ['--model-path', 'modelPath'],         // retrieve --scope code: verified existing local Semble model
   ['--heading-level', 'headingLevel'], // brief-tools: 2 (default) or 3
   ['--tasks', 'tasks'],               // brief-tools: comma-separated plan task ids for tier advice
   ['--plan-path', 'planPath'],         // verify: a feature plan.md whose doflow-verification
@@ -298,10 +380,64 @@ const RUNTIME_STRING_FLAGS = new Map([
   ['--verification-input', 'verificationInput'], // verify: manifest JSON file for explicit structuralChecks/requirements (IC-022)
   ['--verification-phase', 'verificationPhase'], // verify: postimplementation (IC-022)
   ['--baseline-ref', 'baselineRef'],             // verify: explicit ancestor commit or ref to measure change against (IC-022)
+  ['--base', 'base'],                  // review --action start: the commit or ref the changed paths are measured from (095b IC-001)
+  ['--preset', 'preset'],              // review --action start: a review preset id to run with, never looser than the decided one (119 IC-005)
+  ['--layer', 'layer'],                // config validate|set|unset: user | project | local, checked in handleConfigCommand (119 IC-008)
+  ['--prepared-run', 'preparedRun'],   // config validate: a prepared-run file to check, writes nothing (119 IC-010)
   ['--error', 'errorMessage'],         // recover: the failure text to classify
   ['--agent', 'agent'],                // recover: which agent produced the failure
   ['--task', 'task'],                  // task-attempt: the plan task id, e.g. A.1
   ['--token', 'token'],                // task-attempt finish|release: the fencing token claim returned
+  // 080 task-attempt (IC-017). Read as text and validated in handleTaskAttemptCommand, so an
+  // integer is digits only (`5abc` and `-1` are usage) rather than what parseInt makes of it.
+  ['--owner-override', 'ownerOverride'], // claim: why someone other than the declared owner takes the task
+  ['--epoch', 'epoch'],                // claim: the run epoch the caller was handed
+  ['--reserve-tokens', 'reserveTokens'], // claim: tokens held against the run's budget while active
+  ['--exec-worktree', 'execWorktree'], // claim: the worktree the attempt executes in
+  ['--tokens', 'tokens'],              // finish|release|report-usage: tokens the attempt used, as reported
+  ['--tokens-basis', 'tokensBasis'],   // finish|release|report-usage: measured | estimated
+  ['--budget-attempts', 'budgetAttempts'], // start: the run's attempt limit
+  ['--budget-tokens', 'budgetTokens'], // start: the run's token limit
+  ['--by', 'by'],                      // start|pause|cancel|reopen|resume: who acts on the run
+  ['--ack', 'ack'],                    // resume: the digest the unacknowledged resume reported
+  // 081 worker (IC-025, IC-026). Read as text and validated in handleWorkerCommand.
+  // `--need`, `--harness`, `--budget-tokens`, `--task`, `--token`, `--by` and `--reason` are shared.
+  ['--prompt-file', 'promptFile'],     // worker run: the brief the worker receives
+  ['--timeout-seconds', 'timeoutSeconds'], // worker run: 1 to 14400
+  ['--worker-run', 'workerRun'],       // worker status|cancel: a w-<12 hex> run id
+  ['--checks', 'checks'],              // worker evidence: checks file
+  ['--out', 'out'],                    // worker evidence: output record path
+  ['--model-check', 'modelCheck'],     // worker probe: a declared model-check id
+  // 082 dispatch (IC-001, IC-038) and worker --child-of (IC-015). Read as text and validated in
+  // executeDispatchCommand / handleWorkerCommand. `--slug`, `--by`, `--reason`, `--mode`,
+  // `--reserve-tokens`, `--budget-attempts`, `--budget-tokens`, `--harness`, `--need`, `--status`,
+  // `--summary`, `--tokens`, `--tokens-basis`, `--prompt-file`, `--request-id`, `--task`, `--token`,
+  // `--ack`, `--request` and `--exec-worktree` are shared.
+  ['--concurrency', 'concurrency'],    // dispatch start: 1 to 4
+  ['--billing-cap', 'billingCap'],     // dispatch start: free-only worker billing ceiling
+  ['--fallback', 'fallback'],         // dispatch start|resume: quota fallback mode off | ask | auto (106 IC-005)
+  ['--ladder', 'ladder'],             // dispatch start: worker rungs, comma-separated harness ids (106 IC-005)
+  ['--verify-argv', 'verifyArgv'],     // dispatch start: the verification argv as a JSON array
+  ['--verify-seconds', 'verifySeconds'], // dispatch start: 1 to 14400
+  ['--attempt-seconds', 'attemptSeconds'], // dispatch start: 1 to 14280
+  ['--max-seconds', 'maxSeconds'],     // dispatch run: 1 to 14400
+  ['--spawn-grant', 'spawnGrant'],     // dispatch start: the spawn grant declaration as JSON
+  ['--dispatch', 'dispatch'],          // dispatch submit: a d-<12 hex> dispatch id
+  ['--child-of', 'childOf'],           // worker run: the granter's w-<12 hex> run id
+  ['--run', 'run'],                    // trace spans, trace analyze, trace export: keep one run key or run id (088 IC-011, 091 IC-001, 091 IC-006)
+  ['--emit', 'emit'],                  // trace analyze: print a batch for an existing verb, evidence | followups (091 IC-001)
+  ['--row', 'row'],                    // roadmap: restricts the step to one in-flight row (108 IC-001)
+  ['--draft', 'draft'],                // roadmap seed: the draft file to check, apply or amend (113 IC-001)
+  ['--id', 'id'],                      // package --action list|show|update: the package id
+  ['--plan', 'planId'],                // package --action add|update: apply the plan file with this 16-hex plan id (122 IC-006)
+  ['--points', 'points'],             // package --action new: point[:local] entries, comma-separated
+  ['--dir', 'dir'],                   // package --action new: authored package target directory
+  ['--name', 'name'],                  // slot: the slot's name, 1 to 64 characters of a-z, 0-9 and - (115 IC-008)
+  ['--label', 'label'],                // slot --action run: the holder's label, at most 80 characters (115 IC-008)
+  ['--cursor', 'cursor'],              // transcript --action read: the cursor an earlier read returned (093 IC-022)
+  ['--limit', 'limit'],                // transcript --action read: at most this many events, validated in the verb (093 IC-022)
+  ['--window', 'window'],              // transcript --action stats: minutes, 1 to 60, validated in the verb (093 IC-023)
+  ['--port', 'port'],                  // ui: the Console's port, 0 to 65535, checked in commands/ui.ts (092 IC-008)
 ]);
 
 /** Repeatable arguments — each occurrence appends rather than replaces. */
@@ -314,14 +450,17 @@ const RUNTIME_LIST_FLAGS = new Map([
   ['--need', 'need'],
   ['--path', 'paths'],                 // leak-scan: the files to scan, one per occurrence
   ['--exclude', 'exclude'],            // leak-scan: extra path segments to skip · lifecycle --action release: slugs left out
+  ['--exclude-family', 'excludeFamily'], // model-role: model family to exclude from review candidates
   ['--feature', 'feature'],            // lifecycle --action release: a feature slug to add, one per occurrence
   ['--item', 'item'],                  // goal --action add: a checklist item, one per occurrence · goal --action check: the one item id (C3)
+  ['--blocker', 'blocker'],            // dispatch submit: one blocker line per occurrence, at most 20
 ]);
 
 /** Non-negative integer arguments. */
 const RUNTIME_INT_FLAGS = new Map([
   ['--iteration', 'iteration'],        // recover: retries already spent, bounding the retry budget
   ['--observed-exit', 'observedExit'], // evidence --action add: exit status of the observed command (0 is meaningful)
+  ['--timeout', 'timeout'],            // slot --action run: seconds to wait for the slot; the verb checks 1 to 86400 (115 IC-008)
 ]);
 
 /**
@@ -345,6 +484,7 @@ function parseRuntimeFlag(arg        , argv          , i        , o     )
   const inline = eq === -1 ? null : arg.slice(eq + 1);
   const key = RUNTIME_STRING_FLAGS.get(name) || RUNTIME_LIST_FLAGS.get(name) || RUNTIME_INT_FLAGS.get(name);
   if (!key) return null;
+  if ((name === '--listen-address' || name === '--tls-cert' || name === '--tls-key') && o.cmd !== 'ui') return null;
 
   let value      = inline;
   let next = i;
@@ -366,13 +506,11 @@ function parseRuntimeFlag(arg        , argv          , i        , o     )
     if (!Number.isFinite(parsed) || parsed < 0) { console.error(`doflow: ${name} expects a non-negative integer, got '${value}'`); process.exit(2); }
     o[key] = parsed;
   } else if (RUNTIME_LIST_FLAGS.has(name)) {
-    // --exclude alone also accepts a comma-joined value (`--exclude bin,src,core`), not just the
-    // repeatable form (`--exclude bin --exclude src`) every other list flag uses — the two used to
-    // be parsed by two separate code paths (a dedicated switch case handling only the space
-    // spelling's comma-splitting, this generic path handling both spellings but never splitting),
-    // so `--exclude=bin,src` silently excluded nothing while `--exclude bin,src` worked. One path,
-    // both spellings, same behavior now.
-    const parts = name === '--exclude' ? value.split(',').map((s        ) => s.trim()).filter(Boolean) : [value];
+    // --exclude and --exclude-family both accept comma lists or repeated flags. Keep --exclude's
+    // existing trimming, empty-item filtering, and split behavior unchanged for its callers.
+    const parts = name === '--exclude' || name === '--exclude-family'
+      ? value.split(',').map((s        ) => s.trim()).filter(Boolean)
+      : [value];
     (o[key] = o[key] || []).push(...parts);
   } else if (name === '--evidence-id' && o.cmd === 'research-request') {
     (o.evidenceIds = o.evidenceIds || []).push(value);
@@ -396,6 +534,7 @@ Commands:
   list-backups         List available backups
   self-update          git pull + reinstall
   tools                Inspect or manage registered external tools
+  ui [<project>]       Run the DoFlow Console, a separately installed package (--port N; exit 2 when it is not installed)
   capabilities         Show registered abstract capabilities and resolved providers
   enforcement          Report lifecycle policy enforcement coverage (--harness, --policy)
   doctor               System health and capability smoke check diagnostics
@@ -403,26 +542,39 @@ Commands:
   evidence             Record a stage's evidence batch, or inspect what is recorded (--task-id)
   claim                Record a claim, link evidence to it, or list them (--task-id, --action)
   context-pack         Compile a task's evidence and claims into a context block (--task-id)
+  context-emit         Decide and render one launch, prompt or delta emission (--event, --cwd)
+  context-grant        Grant one compacted summary to a launched run and lineage (--summary, --to-run, --to-lineage)
   retrieval-plan       Declare a stage's information needs, attempt retrieval, then report every declared item
   outcome              Record a task's terminal state with its basis, or show it (--task-id)
   classify             Validate a proposed task class and return its workflow (--task-class)
   workflow             Resolve a task class to its stages, gates and readiness templates
   orchestrate          Start or resume a run: complete stages, decide gates (--action)
   research-request     Open, list or resolve a feature-stage research question (--task-id)
-  task-attempt         Claim, finish, release or read the attempts on a plan's tasks (--action, --slug)
-  retrieve             BM25 search over the installed guidance tree (--query)
-  model-role           Resolve a model role to ranked provider candidates (--role)
+  task-attempt         Claim, finish, release, run controls, resume, inspect, reopen or report usage on a plan's task attempts (--action, --slug)
+  worker               Discover, probe, describe, select, run, status or cancel an external headless worker on a claimed task (--action)
+  dispatch             Run a feature's task graph: start, step, run, submit, spawn, pause, inspect, cancel, takeover or resume (--action)
+  retrieve             BM25 guidance search by default; use --scope code for scoped project retrieval (--query)
+  model-role           Resolve a model role to ranked provider candidates (--role, --exclude-family)
   advise               Route decision questions to the configured local model (--action)
   brief-tools          Tier, tools and report-format block for a dispatch brief (--owner)
   route                Resolve an information need to a healthy provider (--intent)
   verify               Compile the verification contract and report against it (--task-id)
   recover              Classify a verification failure and plan the bounded retry (--error)
-  trace                Trajectory of the current or most recent workflow (run ledger)
+  trace                Trajectory of the current or most recent workflow (run ledger).
+                       trace spans [<project>] the span view; trace analyze [<project>] its detectors (exit 1 on a finding);
+                       trace export --otlp-http [<project>] export spans via OTLP/HTTP
   stats                Aggregate local run-ledger usage
   indicators           Per-stage and per-gate timings from the orchestration record
   discover             Missed capability opportunities in recorded runs
   inventory            Shadowed copies, drift and unmanaged files across both install scopes
   storage              Report stored data and retention bounds (--action report|prune|upkeep)
+  config               Show each setting's effective value and where it came from, print the settings schema, or validate, set or unset one (exit 0 ok, 1 refused, 2 usage).
+                       config [list] [--show-origin] [--json] [-g] [<project path>]   read-only
+                       config schema [--json]   every key with its type, values, default, scope and whether config set may write it, the locked invariants and the presets
+                       config validate <key> <json-value> [--layer user|project|local] [--json]   check a value, writes nothing
+                       config validate --prepared-run <file> [--json]   check a prepared-run file (task class, settings, presets), one entry per fault, writes nothing
+                       config set <key> <json-value> --layer user|project|local [--json]   validate, then write that layer's file; refuses security-relevant and invariant.* keys
+                       config unset <key> --layer user|project|local [--json]   remove the key from that layer's file
   scaffold             Emit the reviewable code scaffold the active feature's artifacts imply
   decision             Register, list or compact the active feature's decisions (--action init|add|list|compact)
   followup             Record, list, take, settle, promote or report what a feature left unfinished (--action add|list|take|settle|promote|report)
@@ -430,6 +582,47 @@ Commands:
   goal                 Add, check, link, list or close a goal and its checklist (--action add|item|check|link|list|done)
   failure              List, settle or switch off the failures DoFlow captured on this machine (--action list|settle|capture)
                        (a value beginning with '-' must be written --flag=value)
+  roadmap              Session-driven autopilot runner (--action render|status|next|audit|init-policy [--check] [--row <id>] [--run <id>]).
+                       roadmap --action init-policy [--commit] writes the gate policy for review, or with --commit commits it onto local develop when develop is not checked out in a worktree (otherwise it prints the commands to run there; never pushes);
+                       roadmap seed --action check|apply|amend --draft <path> [--json] validates and writes new rows;
+                       rows written while autopilot is on land proposed; roadmap promote <id...> [--json] (person, autopilot off) makes them ready
+  plan-check           Check a plan's task lines the way the task-attempt ledger reads them: plan-check <plan path> [--json]
+  review               Validate a feature's review/findings.json; print errors, advisories and counts (exit 0 valid, 1 invalid, 2 usage).
+                       review --action check [--slug <name> | --path <findings.json>] [--json]
+                       review --action start [--slug <name>] [--base <ref>] [--json] [--preset <id>]   verify precondition and review protocol; --base must be the review's base (exit 0 ok or not applicable, 1 refused, 2 usage)
+  protocol             Print the review and debate protocol presets, or the one a run would use (read-only, writes nothing).
+                       protocol --action list [--kind review|debate] [--json]
+                       protocol --action resolve --kind review|debate [--task-class <id>] [--risk <level>] [--preset <id>] [--json]   (exit 0 resolved, 1 refused, 2 usage)
+  rules                Print the values the runtime owns for this project, each with its source (read-only, writes nothing).
+                       rules [--task-class <id>] [-g] [--json] [<project>]   review protocol per class (attended and unattended), gate floors and loop limits, tiers and worker models, review and autopilot settings (exit 0, 2 usage)
+  primary              Resolve which harness and model the main session runs (read-only).
+                       primary --action resolve [--json]   (exit 0, 1 refused, 2 usage)
+                       primary --action observed [--json]   checkouts and session hook records (exit 0, 1 cannot list checkouts, 2 usage)
+  fleet                List the projects this machine knows (read-only).
+                       fleet --action projects [--json]   from the user-state upkeep-roots and the hook project directories (exit 0, 1 cannot list projects, 2 usage)
+                       fleet --action tree [--json]   one project's agent hierarchy as nodes and edges (exit 0, 1 cannot list checkouts, 2 usage)
+  transcript           Read an agent's recent events, or the project's traffic (read-only, run in a project).
+                       transcript --action read --agent <key> [--cursor <c>] [--limit <n>] [--json]   masked events and DoFlow's record events (exit 0, 1 agent-not-in-project or session-not-in-project, 2 usage)
+                       transcript --action stats [--window <minutes 1..60>] [--json]   events per minute, tool calls, tokens, who works with whom (exit 0, 2 usage)
+  package              List the contribution points a package may fill, check a package directory, show the packages, add and update a local package, or turn it on and off.
+                       package --action points [--json]
+                       package --action check --path <dir> [--json]   (read-only; exit 0 clean, 1 findings, 2 usage)
+                       package --action list [--id <id>] [--json]   (read-only; exit 0, 1 when a package is neither active nor disabled)
+                       package --action show --id <id> [--json]   (read-only; exit 0, 1 unknown id, 2 no --id)
+                       package --action add --source <spec> [--json]   (plans a local or granted remote source; exit 0, 1 refused, 2 usage)
+                       package --action add --index <file> --id <id> [--version <v>] [--json]   (selects a pinned source; needs a fetch grant)
+                       package --action add --plan <planId> [--json]   (stores the package and records it disabled; exit 0, 1 refused, e.g. digest-mismatch)
+                       package --action update --id <id> | --plan <planId> [--json]   (plan a new copy from the recorded source, or apply the plan; a changed digest above inert prints the new trust line)
+                       package --action new --id <id> --points <point[:local],...> [--dir <path>] [--json]   (writes an authored package folder only; exit 0 created, 1 refused, 2 usage)
+                       package --action enable|disable --id <id> [--json]   (sets the lock bit; enable prints the resulting state, and for needs-trust the exact grant line and file; exit 0, 1 incompatible or unknown, 2 no --id)
+                       package --action trust|exempt --id <id> [--json]   (prints the grant line a person appends to grants.jsonl and writes nothing; exempt exits 1 while the host is inside the range)
+                       package --action revoke --id <id> [--json]   (records a revocation in state.json; only a later trust line counts)
+                       package --action remove --id <id> [--json]   (disables, deletes the store entry and lock row, records a revocation and a removed tombstone, then lists the settings, records and grant lines that still name the package and rewrites none; exit 0, 1 unknown id or the bundled package, 2 no --id)
+                       package --action verify [--repair] [--json]   (re-hashes enabled third-party entries and records suspensions; exit 0 intact, 1 findings; --repair rewrites an unreadable state.json)
+  slot                 Named machine-wide queue, one holder at a time (--action run|list|peek|release).
+                       slot --action run --name <name> [--label <text>] [--timeout <s>] [--no-wait] -- <command> [args...]
+                       slot --action release --name <name> --by <who> --reason <text>
+  models               Synchronize, list, or inspect observed models across workers (--action sync|list|describe)
   leak-scan            Report DoFlow-internal identifiers in shipped files (--path, repeatable)
 
 Scope (mutually exclusive — global wins if both given):
@@ -444,7 +637,7 @@ Scope (mutually exclusive — global wins if both given):
 Options:
   -t, --target <list>  Comma-separated: ${VALID_TARGETS.join(',')} (default: ${DEFAULT_TARGETS.join(',')})
       --mcp <list>     Comma-separated MCP server names, or all or none, for every targeted
-                       harness that takes MCP servers (all but gemini). Default: none, or the
+                       harness that takes MCP servers (all of them). Default: none, or the
                        selection a harness has recorded in doflow.lock, or the servers an
                        installed harness already has; a real terminal prompts on install.
                        Recorded per harness.
@@ -455,25 +648,56 @@ Options:
                        the file is still a conflict. For a tree installed before the neutral
                        ledger existed, which nothing else can re-adopt
       --no-backup      Skip backup (requires --force; ignored by rollback's safety snapshot)
-      --prune <N>      Keep the N newest backups after install or update (default 3; 0 keeps all)
+      --prune <N>      Keep the N newest backups after install, update or reconcile (default 3; 0 keeps all)
       --days <N>       Run-ledger window in calendar days (trace, stats, discover)
+      --run <key|id>   trace spans, trace analyze, trace export: keep the traces of one run key or run id
+      --emit evidence|followups
+                       trace analyze: print only the batch for evidence --action add --batch -,
+                       or for followup --action add --batch <file> (with --task-id, cites its evidence)
+      --otlp-http      trace export: export spans to an OpenTelemetry collector via OTLP/HTTP JSON
       --slug <name>    Scaffold this feature instead of the branch-resolved active one
 
 Runtime verb arguments (accept --flag value or --flag=value):
-      --task-class     classify, workflow, readiness, context-pack, outcome --action record
-      --task-id        readiness, evidence, claim, context-pack, retrieval-plan, outcome, verify, advise
-      --action         claim: list|add|link|retract|supersede · evidence: list|add|supersede
+      --task-class     classify, workflow, readiness, context-pack, outcome --action record, protocol --action resolve
+      --task-id        readiness, evidence, claim, context-pack, retrieval-plan, outcome, verify, advise, retrieve,
+                       trace analyze --emit followups (the ledger read for evidence ids)
+      --action         claim: list|add|link|retract|supersede · evidence: list|add|supersede|retire
                        verify: report|contract · retrieval-plan: declare|report|attempt
                        outcome: record|show · advise: ask|outcome|configure · tools: see above
                        followup: add|list|take|settle|promote|report
-                       task-attempt: claim|finish|release|status
+                       task-attempt: claim|finish|release|status|start|pause|cancel|resume|inspect|reopen|report-usage
+                       worker: discover|probe|describe|select|run|status|cancel|evidence
+                       dispatch: start|step|run|submit|spawn|pause|inspect|cancel|takeover|resume
                        lifecycle: overview|init|release|status|merged
                        goal: add|item|check|link|list|done
                        failure: list|settle|capture
+                       roadmap: render|status|next|audit|init-policy (seed: check|apply|amend; promote <id...>)
+                       slot: run|list|peek|release
+                       models: sync|list|describe
+                       review: check|start
+                       protocol: list|resolve
+                       primary: resolve|observed
+                       fleet: projects|tree
+                       transcript: read|stats
+                       package: points|check|list|show|add|update|enable|disable|trust|exempt|revoke|verify|remove
       --task, --token, --owner, --mode,
-      --result, --evidence-id, --reason     task-attempt (claim: --task --owner --mode manual|sequential|subagent;
-                                            finish: --task --token --result COMPLETED|BLOCKED|ABANDONED|INCONCLUSIVE
-                                            [--evidence-id]; release: --task --token --reason)
+      --result, --evidence-id, --reason     task-attempt (claim: --task --owner --mode manual|sequential|subagent
+                                            [--owner-override <reason>] [--epoch <n>=1+] [--reserve-tokens <n>]
+                                            [--exec-worktree <path>];
+                                            finish: --task --token --result COMPLETED|BLOCKED|ABANDONED|INCONCLUSIVE|FAILED
+                                            [--evidence-id] [--reason, required with FAILED];
+                                            release: --task --token --reason; finish and release also
+                                            [--tokens <n> --tokens-basis measured|estimated];
+                                            start: --by [--budget-attempts <n>=1+] [--budget-tokens <n>=1+];
+                                            pause: --by --reason; cancel: --by --reason, one attempt with
+                                            --task --token, else the run [--adopt-unowned];
+                                            reopen: --task --token --by --reason;
+                                            report-usage: --task --token --tokens <n> --tokens-basis
+                                            measured|estimated, once on an ended attempt with no usage;
+                                            resume: report and digest, then --ack sha256:<hex> --by [--reason];
+                                            inspect: graph, task states, budgets and run totals.
+                                            Exit 0 applied or read; 1 refused, stale or ack-required, the
+                                            disposition in the JSON; 2 usage or an unreadable store or plan)
       --rationale, --proposed-by, --calling-skill    classify
       --request <text>, --request-file <file>  classify (mutually exclusive; optional second opinion)
       --intent, --query, --check            route
@@ -483,14 +707,25 @@ Runtime verb arguments (accept --flag value or --flag=value):
       --capability, --locator, --content,
       --absence                             evidence --action add (one item)
       --need <intent>                       evidence --action add (bind evidence to retrieval needs)
+      --scope code --profile lexical-only|hybrid,
+      --root <project>, --index-action build|refresh,
+      --model-path <local-dir>              retrieve code scope (guidance remains the default)
       --batch <file|->                      evidence --action add (a stage's JSON batch)
       --evidence-id, --replaced-by          evidence --action supersede (retire one item, point
                                             forward to the item that replaces it)
+      --stale                               evidence --action retire (retire every item the ledger
+                                            classes stale, with no replacement; fresh items stay)
       --verification-plan, --scope,
       --invariants,
       --user-decision-pending               readiness: inputs the caller states rather than
                                             evidence establishes; reported back as such
       --objective                           context-pack
+      --event, --cwd, --session, --harness,
+      --nudge, --max-bytes, --task-id,
+      --slug, --peek                        context-emit (identity comes from the environment only)
+      --summary, --to-run, --to-lineage,
+      --from-worktree, --from-run,
+      --from-lineage, --max-bytes           context-grant
       --need <intent[,intent]>,
       --stage, --status                     retrieval-plan (--need is repeatable), outcome
       --mcp-outcome <server>=<outcome>      orchestrate --action handoff, repeatable: used | nothing-usable |
@@ -511,6 +746,20 @@ Runtime verb arguments (accept --flag value or --flag=value):
       --model, --endpoint, --project,
       --off                              advise --action configure
       --path, --exclude (repeatable)        leak-scan
+      --slug | --path                       review --action check (at most one; with neither, the active feature)
+      --path <dir>                          package --action check (exactly one package directory)
+      --id <id>                             package --action list (one package), show, update (required unless --plan), enable, disable, trust, exempt, revoke and remove
+      --source <spec>                       package --action add (local dir, git:https://<host>/<repo>[#<subdir>]@<ref>, npm:<name>@<version or range>)
+      --index <file>, --version <v>          package --action add --id <id> (local pinned index; default highest compatible stable version)
+      --plan <planId>                       package --action add and update (apply the plan; it is kept for 24 hours)
+      --points <point[:local],...>           package --action new (open points and optional local ids)
+      --dir <path>                          package --action new (default: <project>/.doflow/package/<id>/)
+      --repair                              package --action verify (rewrite an unreadable state.json; every grant line present is revoked, never widened)
+      --base <ref>                          review --action start (measure the changed paths from this commit, which must be the review's base; --path is refused)
+      --preset <id>                         review --action start, protocol --action resolve (run this preset; refused when looser than the decided protocol)
+      --prepared-run <file>                 config validate (check a prepared-run file instead of one key; exit 2 with a key, value or --layer)
+      --layer user|project|local            config validate, set, unset (which settings file; project and local are the current project's .doflow/settings.json and settings.local.json)
+      --kind review|debate, --risk <level>  protocol (--kind filters list and selects what resolve decides; --risk is the change's risk level)
       --ids, --as, --evidence, --title,
       --release, --source, --channel        followup (add, list, take, settle, promote)
       --file <path|->, --stdin, --text,
@@ -523,8 +772,50 @@ Runtime verb arguments (accept --flag value or --flag=value):
       --tag, --confirm, --feature,
       --exclude (repeatable), --reason      lifecycle (release, merged)
       --fp, --as, --reason, --set, --all    failure (list, settle, capture)
+      --harness, --need (repeatable),
+      --model-check, --budget-tokens,
+      --task, --token, --prompt-file,
+      --timeout-seconds, --wait, --edit,
+      --child-of, --request, --exec-worktree,
+      --worker-run, --by, --reason,
+      --checks, --out                       worker (probe: [--model-check <id> --budget-tokens <n>];
+                                            describe: --harness [--edit]; select: [--edit];
+                                            run: --harness --task --token
+                                            --prompt-file [--timeout-seconds 1-14400] [--wait] [--edit]
+                                            [--child-of <w-id> --request <d-id.cN> --exec-worktree <path>];
+                                            status, cancel: --worker-run or --task --token;
+                                            cancel also --by --reason;
+                                            evidence: --harness --out and exactly one of --checks <file>
+                                            (free CLI checks) or --worker-run <w-id> (an ended run).
+                                            Exit 0 done; 1 refused or
+                                            none-eligible, the disposition in the JSON; 2 usage)
+      --slug, --by, --reason, --concurrency,
+      --mode, --verify-argv, --verify-seconds,
+      --attempt-seconds, --reserve-tokens,
+      --budget-attempts, --budget-tokens,
+      --spawn-grant, --harness, --need,
+      --max-seconds, --dispatch, --status,
+      --summary, --blocker (repeatable),
+      --tokens, --tokens-basis, --prompt-file,
+      --request-id, --task, --ack           dispatch (start: --by [--concurrency 1-4] [--mode auto|sequential|manual]
+                                            [--verify-argv <json>] [--verify-seconds <n>] [--attempt-seconds <n>]
+                                            [--reserve-tokens <n>] [--budget-attempts <n>] [--budget-tokens <n>]
+                                            [--spawn-grant <json>] [--harness <id>] [--need <id>];
+                                            step: [--by]; run: [--by] [--max-seconds 1-14400];
+                                            submit: --dispatch <d-id> --status success|failure --summary <text>
+                                            [--blocker <text>] [--tokens <n> --tokens-basis measured|estimated];
+                                            spawn: --prompt-file --reserve-tokens <n>, or --request-id;
+                                            pause, cancel: --by --reason; takeover: --task --by --reason;
+                                            resume: report and digest, then --ack sha256:<hex> --by [--reason];
+                                            inspect. Exit 0 done; 1 refused, stale or ack-required, the
+                                            disposition in the JSON; 2 usage or an unreadable store or plan)
       --error, --failed-check,
       --iteration, --agent                  recover
+      --name, --label, --timeout,
+      --no-wait, --by, --reason             slot (run: --name [--label <text>] [--timeout 1-86400] [--no-wait] -- <command> [args...],
+                                            everything after -- is the command's own argv; list; release: --name --by
+                                            --reason. Exit: run passes the command's code, 75 when busy or timed out;
+                                            release 1 while the holder is alive; 2 usage)
       --json           Machine-readable output (status)
 
 External tools:
@@ -559,6 +850,8 @@ async function main(argv          )               {
     if (handler) return handler(o);
     return await dispatchRuntimeCommand(o);
   } catch (error     ) {
+    // A repeated `remove` with nothing left is a finished job, not a failure (FU-0wgcyt).
+    if (error?.code === 'DOFLOW_NOTHING_TO_REMOVE') { console.log(`[INFO] ${error.message}`); return; }
     // Recorded silently when it is a programming error (IC-016); the output and exit status below
     // are the same whether or not anything was written.
     // Required here, not at load, so a CLI whose failure modules cannot be loaded still runs as today.