ultra-builder-pro-cli 0.16.0 → 0.17.0

package/.ultra-template/specs/research-distillate.md

@@ -8,7 +8,7 @@ specifications' prose.
 - Baseline or change id:
 - Research workflow id and mode:
 - Repository revision:
-- Completed step set:
+- Coverage dispositions and selected evidence work:
 
 ## Observed
 
@@ -24,7 +24,7 @@ specifications' prose.
 
 ## Unknowns
 
-| Unknown or gap id | Blocking | Owner or next action |
+| Unknown or gap id | Blocking | Owner and revisit condition |
 |---|---|---|
 | | | |
 
@@ -45,4 +45,5 @@ specifications' prose.
 - Accepted scope and posture:
 - Required references:
 - Blocking gaps:
-- Exact next route:
+- Allowed transitions:
+- Host recommendation and rationale:

package/CHANGELOG.md

@@ -7,6 +7,92 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.17.0] — 2026-07-24
+
+### Added
+
+- Added deterministic Git bootstrap for initialization and resume, including
+  explicit `auto`, `initialize`, and `skip` modes, persisted unborn-HEAD state,
+  and an owner-authorized first-checkpoint gate.
+- Added a source-backed compatibility crosswalk against the original
+  `rocky2431/ultra-builder-pro` workflow and a shell-free `execute-plan`
+  consumer for current completed-plan dependency waves.
+- Added schema 18 adaptive transition state, migration of active legacy
+  init/change/plan/deliver runs, Context Manifest v3 Change-authority digests,
+  and one host-specific interaction contract for every supported runtime.
+- Added research coverage dispositions (`execute`, `verify_existing`, `reuse`,
+  `not_applicable`, and accepted `deferred`) and risk-selected verification
+  profiles with rationale for every excluded dimension.
+
+### Changed
+
+- Changed plan execution into a resumable wave state machine. A wave pauses
+  until its DB tasks converge, later dependencies remain pending, and reruns
+  skip completed work.
+- Changed MCP session spawning to create the single authoritative Git worktree
+  and session record. Session close now preserves work by default, and
+  change-owned auto-merge requires current dev and review evidence.
+- Changed session worktrees to bind their ignored `.ultra` entry to the central
+  authority and pass non-overridable DB, checkout, and authority-root paths to
+  explicit workers.
+- Changed initialization to complete after classification, local Git/scaffold
+  setup, and read-back verification. It never starts research implicitly;
+  baseline research begins only through an explicit invocation.
+- Changed the workflow from a canonical next-action pipeline to an adaptive
+  capability graph. MCP exposes valid alternatives and unique hard-recovery
+  transitions; the active host owns semantic recommendations and native user
+  interaction.
+- Changed change capture to end after the accepted intent contract, made plan
+  approval conditional on a material owner decision, selected test/review work
+  by risk, and limited Ultra delivery to local convergence and archive.
+
+### Fixed
+
+- Fixed process exit zero, worker spawn errors, and daemon failures bypassing
+  task gates or losing session-linked failure and circuit-breaker evidence.
+- Fixed daemon dispatch of stale tasks, unresolved dependencies, or overlapping
+  declared files, and made explicit takeover terminate the prior worker before
+  replacing its lease.
+- Fixed initialization resume leaving corrected metadata or projections behind
+  after a late failure; DB state, generated projections, and newly bootstrapped
+  Git now roll back together.
+- Fixed cleanup paths that could remove uncommitted or unintegrated worktrees,
+  and fixed dependency waves that could start before prior task convergence.
+- Fixed change-owned auto-merge trusting task status alone; integration now
+  requires the exact completion commit, ready dev evidence, and current task review.
+- Fixed `execute-plan` accepting empty, cyclic, duplicate-task, stale, or
+  incomplete change plans. Change-owned execution now requires the exact healthy
+  completed plan workflow and current DB task graph.
+- Fixed direct MCP and daemon session creation bypassing the plan workflow.
+  Admission and spawn now share the same current task-contract, dependency, and
+  staleness gate before takeover or worktree mutation.
+- Fixed plan-authority drift between wave selection and spawn being counted as a
+  worker failure, and fixed isolated workers creating a second project DB.
+- Fixed an isolated worker recursively spawning, taking over, or prematurely
+  closing its parent-owned session; the supervising process now remains the only
+  transport-settlement authority.
+- Fixed late resume failure after a schema upgrade restoring the migrated
+  intermediate DB instead of the exact pre-migration backup.
+- Fixed the directory-only `.ultra/` Git ignore form failing to protect an
+  authority symlink from `git add -A`; fresh initialization uses the symlink-safe
+  `.ultra` rule, while legacy repositories receive a repository-local
+  `info/exclude` rule without changing their tracked baseline.
+- Fixed semantic `change.update` operations leaving derived tasks and compiled
+  contexts apparently current. A changed intent contract now marks tasks stale,
+  invalidates Context v3, and records the exact invalidation evidence.
+- Fixed stale tasks remaining usable through plan completion, dev startup,
+  verification, delivery, or orchestrator admission after semantic invalidation.
+- Fixed marker-only task reconciliation bypassing semantic invalidation. Clearing
+  `stale` now requires a complete execution-contract rebind and records the current
+  Change authority digest.
+- Fixed review convergence accepting incomplete or fabricated worker provenance;
+  every specialist is now selected or skipped with rationale, and completed workers
+  must exactly match persisted specialist artifacts.
+- Fixed MCP workflow contracts omitting public freshness, recovery, review, testing,
+  and delivery failure codes needed by host adapters.
+- Fixed runtime specification templates and workflow prompts retaining rigid-route
+  wording or omitting durable step and decision-tool handoffs.
+
 ## [0.16.0] — 2026-07-23
 
 ### Added

package/README.md

@@ -3,8 +3,8 @@
 Multi-runtime plugin suite + autonomous coding factory for the Ultra Builder Pro
 agent engineering system. It ships native plugins for **Claude Code · OpenCode ·
 Codex · Kimi Code** and orchestrates PRD →
-dependency graph → parallel session execution → auto-merge with a single
-authoritative `.ultra/state.db`.
+dependency graph → resumable dependency-wave execution → convergence-gated
+integration with a single authoritative `.ultra/state.db`.
 
 <div align="center">
 
@@ -36,14 +36,20 @@ authoritative `.ultra/state.db`.
 - **Keeps memory ownership explicit.** Ultra Builder Pro does not collect
   prompts, transcripts, observations, summaries, or cross-session memory.
   Install cloud-mem/claude-mem separately if persistent memory is wanted.
-- **Runs real PRDs end-to-end without a second model credential.** The current
-  host derives task objects; `task.parse_prd` validates them → `lib/topo.cjs` waves →
-  `.ultra/execution-plan.json` → parallel worktree sessions → auto-merge back.
+- **Runs current plans without a second model credential.** The current host
+  derives task objects; `task.parse_prd` validates them → `lib/topo.cjs` waves →
+  `.ultra/execution-plan.json` → parallel worktree sessions. Execution pauses at
+  the first wave whose tasks have not converged through Ultra gates. An explicit
+  auto-merge is accepted only for a change task with a matching completion commit,
+  ready dev evidence, and a current task review; transport success alone preserves
+  the worktree.
 - **Keeps daily work convergent.** `/ultra-change` creates a bounded delta and
   complete Change Contract, classifies risk, records whether bounded research is
-  required, and creates immutable Context Manifest v2 snapshots; the Context Spine assigns a role/gate, verifies required
-  references, reports fresh-context budget pressure as advisory warnings, exposes one DB-derived breadcrumb, and
-  routes a single next action. Research stores typed, source-digested semantic records;
+  required, and leaves planning and context compilation to their actual consumers.
+  Context Manifest v3 assigns a role/gate, verifies required references, reports
+  fresh-context budget pressure as advisory warnings, and exposes mechanically valid
+  transitions without choosing the semantic route. Research stores typed,
+  source-digested semantic records;
   planning proves Change acceptance coverage; `/ultra-deliver` requires applied specification
   learning plus docs/test/mode-bound two-axis review evidence and a schema-validated
   baseline reconciliation manifest before archive. `/ultra-doctor` reports incidents,
@@ -99,9 +105,16 @@ based on delivered-system evidence: application source, tests, deployment, or
 persisted-state/schema signals make a repository brownfield; a Git repository,
 manifest, README, or starter documentation alone remains greenfield. An empty project
 opens a `draft` greenfield baseline and an existing system opens an `adopting`
-brownfield baseline. Both execute all seventeen research steps before
-`baseline.record` and explicit `baseline.converge`; initialization never treats blank
-templates as a trusted baseline and never selects an MVP. Existing active work may
+brownfield baseline. Initialization completes after classification, local Git setup,
+scaffold creation, and read-back verification; it never starts research implicitly.
+When `ultra-research` is explicitly invoked, the host dispositions each of seventeen
+coverage areas as `execute`, `verify_existing`, `reuse`, `not_applicable`, or accepted
+`deferred`. It performs only the necessary work before `baseline.record` and explicit
+`baseline.converge`; initialization never treats blank templates as a trusted baseline
+and never selects an MVP. Auto mode preserves existing
+Git or initializes `main` and adds a symlink-safe `.ultra` ignore rule; an unborn
+repository requires an owner-approved local checkpoint commit before the baseline can
+be recorded. It never creates a remote, tag, or push. Existing active work may
 continue only when its durable change workflow was bound to a healthy ready baseline;
 the expected HEAD, worktree, spec, and source-evidence drift created by that change is
 advisory until delivery reconciliation. Loss of approved-ready status or structural
@@ -110,6 +123,8 @@ approver and leaves a blocking reconciliation gap at archive; new ordinary work
 requires a healthy ready baseline. See
 [`docs/WORKFLOW-LIFECYCLE.md`](./docs/WORKFLOW-LIFECYCLE.md) for exact write,
 transition, invalidation, and recovery semantics.
+The semantic crosswalk to the original Claude Code harness is
+[`docs/LEGACY-CLI-CROSSWALK.md`](./docs/LEGACY-CLI-CROSSWALK.md).
 
 ## Three-layer architecture
 
@@ -117,7 +132,7 @@ transition, invalidation, and recovery semantics.
 |-------|---------|----------------|
 | **skill** (`skills/ultra-*/`) | Knowledge — prompts, workflows, prose | Runtime's native skill/prompt loader picks them up after install |
 | **MCP** (`mcp-server/`) | Authoritative state — reads/writes `.ultra/state.db` via stdio JSON-RPC | Primary path for task / session / event / plan operations |
-| **CLI** (`ultra-tools`, `bin/*`) | Selected initialization, recovery, diagnostics, and orchestration surfaces | `ultra-tools task init-project`, `ultra-tools system doctor`, `ubp-orchestrator run` |
+| **CLI** (`ultra-tools`, `bin/*`) | Selected initialization, recovery, diagnostics, and orchestration surfaces | `ultra-tools task init-project`, `ultra-tools system doctor`, `ubp-orchestrator execute-plan` |
 
 The layers share one `.ultra/state.db`, but the CLI is not a mirror of every MCP
 tool: continuous change mutations are MCP-only and fail closed. See
@@ -143,7 +158,7 @@ and framework guidance belong to their original plugins.
 | Workflow hooks               | ✅ (native plugin) | ✅ (native JS plugin) | ✅ (native plugin) | ✅ with documented compact limitation |
 | Sub-agents                   | ✅          | ✅       | ✅ (9 native TOML agents) | ✅ via `Agent` / `AgentSwarm` prompt templates |
 | Session worktree isolation   | ✅ (driven by `orchestrator/session-runner.cjs`) | ✅ | ✅ | ✅ |
-| Parallel dispatch + auto-merge | ✅ (`ubp-orchestrator run`) | ✅ | ✅ | ✅ |
+| Dependency-wave dispatch + optional verified auto-merge | ✅ (`ubp-orchestrator execute-plan`) | ✅ | ✅ | ✅ |
 
 Full details in [`docs/RUNTIME-COMPAT-MATRIX.md`](./docs/RUNTIME-COMPAT-MATRIX.md)
 (10 sections, with per-runtime deviations called out).
@@ -151,20 +166,29 @@ Full details in [`docs/RUNTIME-COMPAT-MATRIX.md`](./docs/RUNTIME-COMPAT-MATRIX.m
 ## Typical workflow
 
 ```bash
-# 1. Bootstrap project state (the ultra-init skill completes adoption and approval)
+# 1. Bootstrap deterministic authority. This completes init but not research/baseline.
 ultra-tools task init-project --project-name myapp --mode auto
 
 # Projection-only projects from prior releases use one backup-first import:
 ultra-tools migrate --from=4.4 --to=4.5 --source-dir .
-ultra-tools migrate --from=4.5 --to=16.0 --source-dir .
-
-# 2. Complete all 17 research steps. When owner judgment is required, the host asks
-#    one evidence-backed decision at a time and checkpoints the accepted artifacts.
-#    Record current evidence, obtain explicit baseline approval, then open and align
-#    an initial change before persisting its task contracts.
-
-# 3. Run the plan — parallel sessions, auto-merge back to main on success
-ubp-orchestrator run
+ultra-tools migrate --from=4.5 --to=18.0 --source-dir .
+
+# 2. Invoke ultra-research explicitly. The host dispositions each coverage area,
+#    executes/verifies/reuses only what is necessary, and asks one material decision at
+#    a time through the host-native question surface. Record evidence and obtain
+#    baseline approval only after the selected coverage converges.
+
+# 3. Optional worker automation. Configure a real shell-free worker first:
+# {"orchestrator":{"command":"/absolute/path/to/ultra-worker","command_args":[]}}
+# Then resume current dependency waves until the first non-converged wave.
+# A paused result is expected while dev/test/review evidence is still open.
+# Worktrees are preserved by default. Empty, cyclic, stale, duplicate-task,
+# cross-change, and stale or unverified plans fail before a session is created.
+# Each worker checkout resolves `.ultra` to the one central authority; reserved
+# UBP_DB_PATH / UBP_ROOT_DIR / UBP_AUTHORITY_ROOT bindings cannot be overridden.
+ubp-orchestrator execute-plan
+# Add --auto-merge only when the worker records the exact completion commit,
+# ready dev steps, and a current task review before it exits.
 
 # 4. Monitor cost, progress, and runtime health
 ultra-tools status
@@ -184,12 +208,18 @@ Kimi uses the corresponding
 `/ultra-builder-pro:ultra-*` namespace. Other runtimes retain their native
 command form.
 
+The arrows above show a common capability path, not a mandatory pipeline. After
+initialization the user or host explicitly selects research. During daily work,
+`ultra-change` may hand off to bounded research, planning, an already-current task,
+thinking, or status according to intent and evidence. MCP exposes allowed transitions
+and hard recovery requirements; the active host recommends the semantic route.
+
 ## CLI surface
 
 | Binary | Purpose |
 |--------|---------|
 | `ultra-builder-pro-cli` / `ubp` | Installer — `--claude / --opencode / --codex / --kimi / --all`, `--local / --global`, `--uninstall`; read-only install checks via `--doctor [--json]` |
-| `ubp-orchestrator` | Session dispatch daemon — `run`, `start`, `stop`, `status` |
+| `ubp-orchestrator` | Current completed-plan runner (`execute-plan`) and optional explicit-worker daemon (`run`, `start`, `stop`, `status`) |
 | `ultra-tools` | State-layer CLI — `task`, `session`, `status`, `db`, `migrate`; explicit `legacy-memory` archive/prune migration |
 | `ubp-handbook` | Preview/apply the managed Ultra contract in `CLAUDE.md` / `AGENTS.md`, with backup |
 

package/adapters/_shared/codex-assets.cjs

@@ -21,6 +21,7 @@ const {
   removeTree,
   writeAtomic,
 } = require('./file-ops.cjs');
+const { interactionContract } = require('./interaction-contract.cjs');
 
 const PLUGIN_NAME = 'ultra-builder-pro';
 const MANAGED_MARKER = 'Managed by Ultra Builder Pro Codex adapter.';
@@ -54,12 +55,12 @@ const CODEX_NATIVE_MCP_REPLACEMENTS = Object.freeze({
     replacement: 'the installed plugin skill SKILL.md and agents/openai.yaml contract',
   },
   'ask.question': {
-    surface: 'direct_user_interaction',
-    replacement: 'ask the user directly, or request_user_input when that Codex surface is available',
+    surface: 'request_user_input',
+    replacement: 'use request_user_input when available, otherwise ask one concise direct question',
   },
   'ask.menu': {
-    surface: 'direct_user_interaction',
-    replacement: 'present a concise choice directly, or request_user_input when that Codex surface is available',
+    surface: 'request_user_input',
+    replacement: 'use request_user_input when available, otherwise present one concise direct choice',
   },
 });
 const COMMAND_NAMES = Object.freeze(CORE_PUBLIC_SKILLS.filter((name) => name !== 'ultra-review'));
@@ -420,6 +421,10 @@ main().catch((error) => {
   const specRoot = path.join(pluginRoot, 'spec');
   ensureDir(specRoot);
   writeAtomic(path.join(specRoot, 'mcp-tools.yaml'), yaml.dump(liveManifest, { lineWidth: -1, noRefs: true }));
+  writeAtomic(
+    path.join(specRoot, 'interaction-contract.json'),
+    JSON.stringify(interactionContract(runtime), null, 2) + '\n',
+  );
   if (runtime === 'codex') {
     fs.copyFileSync(sourceToolsFile, path.join(specRoot, 'upstream-mcp-tools.yaml'));
     writeAtomic(path.join(specRoot, 'codex-capability-map.json'), JSON.stringify({
@@ -519,7 +524,7 @@ function buildPlugin({ repoRoot, pluginRoot }) {
       defaultPrompt: [
         'Initialize this project with the Ultra Builder Pro workflow.',
         'Run the Ultra review pipeline on my current changes.',
-        'Show the current Ultra project status and next action.',
+        'Show the current Ultra project status, valid transitions, and host recommendation.',
       ],
       brandColor: '#111827',
     },

package/adapters/_shared/handbook.cjs

@@ -62,7 +62,7 @@ function renderHandbook(runtime) {
     '- Authority: `.ultra/state.db` is the only durable Ultra authority for baselines, changes, decision threads, tasks, sessions, events, incidents, projection state, telemetry, and review evidence. Generated JSON and Markdown are projections or workflow artifacts.',
     '- Baseline boundary: `task.init_project` classifies greenfield or brownfield work and records repository scope. Projection-only prior state uses the exact supported backup-first import returned by the authority check; migrated compatibility rows require explicit brownfield re-adoption. `baseline.record` owns evidence, verification, repository snapshot, and the gap ledger; `baseline.converge` requires explicit owner approval. New ordinary changes require a healthy ready baseline. Existing active work may continue with warnings, but baseline readiness blocks change convergence; normal drift reconciliation is health-checked atomically at archive. Only an explicitly approved incident break-glass may start without baseline readiness, and its archive creates a blocking reconciliation gap.',
     '- Decision boundary: project-bound owner choices use one resumable DB-backed decision thread. The host resolves observable facts autonomously, presents only the earliest unresolved decision with evidence and a recommendation, waits for the owner, and records the normalized decision rather than prompts or transcripts. A linked workflow cannot advance until blocking decisions are resolved and its owner-approved checkpoint is current.',
-    '- Context Spine boundary: `change.context` compiles role/gate readiness, required references, a fresh-context budget, public seam, verification command, and one next action. File, token, and context-share budgets are advisory attention signals, not refusal gates. Hooks inject only the DB-derived `change.breadcrumb`; missing required evidence or stale execution context must be recompiled.',
+    '- Context Spine boundary: `change.context` compiles role/gate readiness, required references, a fresh-context budget, public seam, verification command, Change/task authority digests, allowed transitions, and any unique hard-recovery transition. File, token, and context-share budgets are advisory attention signals, not refusal gates. The host owns semantic recommendations. Hooks inject only the DB-derived `change.breadcrumb`; missing required evidence or stale execution context must be recompiled.',
     '- Specification learning boundary: stable implementation discoveries use approval-gated propose/approve-or-reject/apply transitions. Unresolved learning blocks convergence; review requires independent specification-fidelity and engineering-standards evidence.',
     '- Memory and graph boundary: Ultra Builder Pro does not capture prompts, transcripts, observations, summaries, cross-session memory, or code-graph content. Separately installed providers own that data; Ultra may store only their metadata references in a change context manifest.',
     '- Hook boundary: Ultra hooks observe workflow/change lifecycle only. Health/context may run when `.ultra/state.db` exists; advisory warnings never reject work, and an incomplete workflow never traps session stop. Direct projection protection remains authoritative; compact and subagent recovery stays active-workflow scoped. Generic command blocking and post-edit policy stay in user or repository governance.',

package/adapters/_shared/interaction-contract.cjs

@@ -0,0 +1,61 @@
+'use strict';
+
+const SURFACES = Object.freeze({
+  claude: Object.freeze({
+    primary: 'AskUserQuestion',
+    fallback: 'direct_user_interaction',
+  }),
+  codex: Object.freeze({
+    primary: 'request_user_input',
+    fallback: 'direct_user_interaction',
+  }),
+  opencode: Object.freeze({
+    primary: 'question',
+    fallback: 'direct_user_interaction',
+  }),
+  kimi: Object.freeze({
+    primary: 'native_question_surface',
+    fallback: 'direct_user_interaction',
+  }),
+});
+
+function interactionContract(runtime) {
+  const question = SURFACES[runtime];
+  if (!question) throw new Error(`unsupported interaction runtime: ${runtime}`);
+  return {
+    schema_version: '1.0',
+    runtime,
+    authority: {
+      user: [
+        'product_intent',
+        'material_scope_and_tradeoffs',
+        'destructive_or_external_effect_authorization',
+      ],
+      host_model: [
+        'fact_finding_and_synthesis',
+        'reversible_implementation_judgment',
+        'coverage_risk_and_route_recommendation',
+      ],
+      ultra_mcp: [
+        'durable_state_and_evidence_refs',
+        'digests_freshness_locks_and_recovery',
+        'allowed_and_required_transitions',
+      ],
+    },
+    interaction: {
+      question_surface: question,
+      dependent_decisions: 'one_at_a_time',
+      independent_low_load_questions: { maximum: 3 },
+      explicit_current_intent: 'normalize_without_reconfirmation',
+      unavailable_native_surface: 'use_direct_interaction',
+    },
+    routing: {
+      semantic_recommendation_owner: 'host_model',
+      durable_recommendation_authority: false,
+      hard_invariant_field: 'required_transition',
+      valid_capabilities_field: 'allowed_transitions',
+    },
+  };
+}
+
+module.exports = { SURFACES, interactionContract };

package/adapters/claude.js

@@ -28,7 +28,7 @@ const PLUGIN_NAME = 'ultra-builder-pro';
 const MCP_SERVER_NAME = PLUGIN_NAME;
 const SOURCE_TAG = 'ubp';
 const SENTINEL_KEY = '_ubp_manifest';
-const COMMAND_NAMES = CORE_PUBLIC_SKILLS.filter((name) => name !== 'ultra-review');
+const COMMAND_NAMES = CORE_PUBLIC_SKILLS;
 const PROVENANCE_FILE = 'provenance.json';
 
 function resolveTarget(ctx = {}) {

package/adapters/opencode.js

@@ -36,7 +36,7 @@ const BUNDLE_DIR = '.ultra-builder-pro';
 const MANAGED_TEXT_MARKER = '<!-- ultra-builder-pro:managed -->';
 const PLUGIN_MARKER = '// Managed by Ultra Builder Pro.';
 const PROVENANCE_FILE = 'provenance.json';
-const COMMAND_NAMES = CORE_PUBLIC_SKILLS.filter((name) => name !== 'ultra-review');
+const COMMAND_NAMES = CORE_PUBLIC_SKILLS;
 
 function resolveTarget(ctx = {}) {
   if (ctx.configDir) return ctx.configDir;

package/bin/orchestrator.js

@@ -4,6 +4,7 @@
  * ubp-orchestrator — Phase 5.4 daemon CLI.
  *
  * Subcommands:
+ *   execute-plan  resume the current plan through the first unfinished dependency wave.
  *   run     foreground daemon (debug / test).
  *   start   detached background daemon, writes .ultra/orchestrator.pid.
  *   stop    reads pidfile, SIGTERM the process, deletes pidfile.
@@ -12,9 +13,8 @@
  * Opt-in gate: `start` and `run` require settings.json
  * `orchestrator.auto_dispatch: true` — default off per PLAN Phase 5.4 AC.
  *
- * The daemon never launches real runtime children in this phase — session
- * rows + git worktrees are created, external adapters (Phase 4) attach to
- * the worktree out-of-band. command/args can be passed via env for testing.
+ * Dispatch requires both explicit opt-in and an explicit executable command.
+ * A daemon may never reserve a session/worktree without a real worker process.
  */
 
 'use strict';
@@ -56,6 +56,124 @@ function parseRuntimes() {
   return runtimes;
 }
 
+function commandConfigError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function resolveDispatchCommand(settings, env = process.env) {
+  const configured = settings?.orchestrator || {};
+  const fromEnvironment = typeof env.UBP_ORCH_COMMAND === 'string'
+    && env.UBP_ORCH_COMMAND.trim() !== '';
+  const command = fromEnvironment
+    ? env.UBP_ORCH_COMMAND.trim()
+    : (typeof configured.command === 'string' ? configured.command.trim() : '');
+  if (!command) {
+    throw commandConfigError(
+      'ORCHESTRATOR_COMMAND_REQUIRED',
+      'orchestrator dispatch requires orchestrator.command or UBP_ORCH_COMMAND',
+    );
+  }
+  if (/\s/.test(command) && !fs.existsSync(command)) {
+    throw commandConfigError(
+      'ORCHESTRATOR_COMMAND_INVALID',
+      'orchestrator.command must contain only the executable; put arguments in command_args',
+    );
+  }
+
+  let commandArgs;
+  if (fromEnvironment && env.UBP_ORCH_ARGS_JSON !== undefined) {
+    try {
+      commandArgs = JSON.parse(env.UBP_ORCH_ARGS_JSON);
+    } catch (error) {
+      throw commandConfigError(
+        'ORCHESTRATOR_COMMAND_INVALID',
+        `UBP_ORCH_ARGS_JSON must be a JSON array: ${error.message}`,
+      );
+    }
+  } else {
+    commandArgs = configured.command_args === undefined ? [] : configured.command_args;
+  }
+  if (!Array.isArray(commandArgs) || commandArgs.some((arg) => typeof arg !== 'string')) {
+    throw commandConfigError(
+      'ORCHESTRATOR_COMMAND_INVALID',
+      'orchestrator command arguments must be an array of strings',
+    );
+  }
+  return {
+    command,
+    commandArgs: commandArgs.slice(),
+    source: fromEnvironment ? 'environment' : 'settings',
+  };
+}
+
+function parseExecutePlanArgs(argv = []) {
+  const options = {
+    planPath: null,
+    autoMerge: false,
+    mergeBaseBranch: 'main',
+  };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--auto-merge') {
+      options.autoMerge = true;
+      continue;
+    }
+    if (arg === '--plan' || arg === '--base-branch') {
+      const value = argv[index + 1];
+      if (!value || value.startsWith('--')) {
+        throw commandConfigError(
+          'ORCHESTRATOR_ARGUMENT_INVALID',
+          `${arg} requires a value`,
+        );
+      }
+      if (arg === '--plan') options.planPath = value;
+      else options.mergeBaseBranch = value;
+      index += 1;
+      continue;
+    }
+    throw commandConfigError(
+      'ORCHESTRATOR_ARGUMENT_INVALID',
+      `unknown execute-plan option: ${arg}`,
+    );
+  }
+  return options;
+}
+
+async function cmdExecutePlan(argv = []) {
+  const settings = readSettings();
+  const dispatch = resolveDispatchCommand(settings);
+  const options = parseExecutePlanArgs(argv);
+  const { initStateDb, closeStateDb } = require('../mcp-server/lib/state-db.cjs');
+  const parallelOrchestrator = require('../orchestrator/parallel-orchestrator.cjs');
+  const { db } = initStateDb(path.join(REPO_ROOT, '.ultra', 'state.db'));
+  try {
+    const result = await parallelOrchestrator.runPlan({
+      db,
+      repoRoot: REPO_ROOT,
+      planPath: options.planPath ? path.resolve(REPO_ROOT, options.planPath) : undefined,
+      runtimes: parseRuntimes(),
+      command: dispatch.command,
+      commandArgs: dispatch.commandArgs,
+      autoMerge: options.autoMerge,
+      mergeBaseBranch: options.mergeBaseBranch,
+      onError: (error) => process.stderr.write(`orchestrator error: ${error.message}\n`),
+    });
+    process.stdout.write(`${JSON.stringify({
+      ok: true,
+      data: {
+        ...result,
+        auto_merge: options.autoMerge,
+        merge_base_branch: options.mergeBaseBranch,
+      },
+    })}\n`);
+    return result;
+  } finally {
+    closeStateDb(db);
+  }
+}
+
 function cmdRun(opts = {}) {
   const settings = readSettings();
   if (!opts.skipOptIn && !optInAllowed(settings)) {
@@ -68,11 +186,14 @@ function cmdRun(opts = {}) {
   const { initStateDb } = require('../mcp-server/lib/state-db.cjs');
   const { runDaemon } = require('../orchestrator/daemon.cjs');
   const runtimes = parseRuntimes();
+  const dispatch = resolveDispatchCommand(settings);
   const { db } = initStateDb(path.join(REPO_ROOT, '.ultra', 'state.db'));
   const handle = runDaemon({
     db,
     repoRoot: REPO_ROOT,
     runtimes,
+    command: dispatch.command,
+    commandArgs: dispatch.commandArgs,
     pollMs: Number(process.env.UBP_ORCH_POLL_MS || 1000),
     onError: (err) => process.stderr.write(`orchestrator error: ${err.message}\n`),
   });
@@ -85,7 +206,10 @@ function cmdRun(opts = {}) {
   };
   process.on('SIGTERM', () => shutdown('SIGTERM'));
   process.on('SIGINT', () => shutdown('SIGINT'));
-  process.stderr.write(`orchestrator running (pollMs=${Number(process.env.UBP_ORCH_POLL_MS || 1000)}, runtimes=${runtimes.join(',')})\n`);
+  process.stderr.write(
+    `orchestrator running (pollMs=${Number(process.env.UBP_ORCH_POLL_MS || 1000)}, ` +
+    `runtimes=${runtimes.join(',')}, worker=${dispatch.command}, source=${dispatch.source})\n`,
+  );
   // Keep process alive while the setInterval is unref'd.
   setInterval(() => {}, 60000);
 }
@@ -96,6 +220,7 @@ function cmdStart() {
     process.stderr.write('orchestrator.auto_dispatch is not enabled; refusing to start.\n');
     process.exit(2);
   }
+  resolveDispatchCommand(settings);
   if (fs.existsSync(PIDFILE)) {
     const existing = Number(fs.readFileSync(PIDFILE, 'utf8'));
     try { process.kill(existing, 0); }
@@ -170,8 +295,9 @@ function cmdStatus() {
 
 function usage() {
   process.stderr.write(
-    'usage: ubp-orchestrator <run|start|stop|status>\n' +
+    'usage: ubp-orchestrator <execute-plan|run|start|stop|status>\n' +
     '\n' +
+    '  execute-plan  resume the first unfinished dependency wave [--plan <path>] [--auto-merge] [--base-branch <name>]\n' +
     '  run     foreground daemon (requires opt-in)\n' +
     '  start   detached background daemon (requires opt-in)\n' +
     '  stop    terminate running daemon\n' +
@@ -179,18 +305,48 @@ function usage() {
   );
 }
 
-const argv = process.argv.slice(2);
-const subcommand = argv[0];
-switch (subcommand) {
-  case 'run':    cmdRun();        break;
-  case 'start':  cmdStart();      break;
-  case 'stop':   cmdStop();       break;
-  case 'status': cmdStatus();     break;
-  case '-h':
-  case '--help':
-  case 'help':
-    usage(); process.exit(0);
-    break;
-  default:
-    usage(); process.exit(1);
+async function main(argv = process.argv.slice(2)) {
+  const subcommand = argv[0];
+  try {
+    switch (subcommand) {
+      case 'execute-plan': await cmdExecutePlan(argv.slice(1)); break;
+      case 'run':    cmdRun();        break;
+      case 'start':  cmdStart();      break;
+      case 'stop':   cmdStop();       break;
+      case 'status': cmdStatus();     break;
+      case '-h':
+      case '--help':
+      case 'help':
+        usage(); process.exit(0);
+        break;
+      default:
+        usage(); process.exit(1);
+    }
+  } catch (error) {
+    process.stderr.write(
+      `orchestrator configuration error${error.code ? ` [${error.code}]` : ''}: ${error.message}\n`,
+    );
+    process.exit(2);
+  }
+}
+
+if (require.main === module) {
+  main().catch((error) => {
+    process.stderr.write(`orchestrator fatal error: ${error.message}\n`);
+    process.exit(2);
+  });
 }
+
+module.exports = {
+  readSettings,
+  optInAllowed,
+  parseRuntimes,
+  parseExecutePlanArgs,
+  resolveDispatchCommand,
+  cmdExecutePlan,
+  cmdRun,
+  cmdStart,
+  cmdStop,
+  cmdStatus,
+  main,
+};