deprecate: make ak run the canonical executor

bin/agentic-kit.mjs

@@ -51,7 +51,7 @@ Usage (ak = alias of agentic-kit):
   ak dashboard       open the local web dashboard (localhost; auto-opens browser)  [--port N] [--no-open]
   ak admin           maintainer-only telemetry admin (localhost; GitHub/npm egress)  [--port N] [--no-open]
   ak run             execute a host-neutral activity pipeline  [template "task"] [--dry-run]
-  ak dual            run a Claude+Codex collaboration swarm (dual-host)  [run <template> "task"] [--dry-run]
+  ak dual            deprecated compatibility wrapper; use ak run for new work
   ak host            manage agent hosts, routing, and provider bindings  [status|pick|refresh|off]
   ak provider        deprecated alias for ak host; removed before the stable release
   ak uninstall       leave cleanly                                      [--this-project] [--purge]
@@ -89,6 +89,7 @@ async function main() {
   let cmd = argv[0];
   let rest = argv.slice(1);
   let deprecatedProvider = cmd === 'provider';
+  const deprecatedDual = cmd === 'dual';
 
   if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
     console.log(argv.includes('--all') ? HELP_ALL : HELP);
@@ -135,6 +136,9 @@ async function main() {
     const canonical = argv[0] === 'x' ? 'ak x host' : 'ak host';
     console.error(`${legacy} is deprecated; use \`${canonical}\`. It will be removed before the stable release.`);
   }
+  if (deprecatedDual) {
+    console.error('ak dual is deprecated; use `ak run` for new execution work. It will be removed before the stable release.');
+  }
   const mod = await table[cmd]();
 
   // Per-command help — intercepted BEFORE run() so mutating commands

claude/dual-mode-reference.md

@@ -14,28 +14,29 @@ and quality gates are available whichever agent is in the driver's seat, and eac
 reach the other. Work flows complementarily — Claude and Codex are peers, not primary and
 fallback.
 
-### `ak dual run` — Claude+Codex collaboration pipelines
+### `ak run` — canonical activity pipelines
 
-`ak dual run <template> "<task>"` materializes a multi-worker pipeline from your
-per-activity routing policy (set via `ak host`) and runs it through the
-`claude-flow-codex` adapter. Each worker is assigned a host + model by the policy, so a
-single run can span both vendors.
+`ak run <template> "<task>"` materializes a multi-worker pipeline from your per-activity routing
+policy (set via `ak host`) and runs it through supervised host adapters. Each worker is assigned a
+host + model by the policy, so a single run can span Claude, Codex, and an explicitly routed
+OpenCode worker.
 
 ```bash
-ak dual run feature  "add token-bucket rate limiting"
-ak dual run security "src/auth/" --escalate
-ak dual run refactor "extract the payment module" --dry-run
-ak dual templates                     # list the pipelines
+ak run feature  "add token-bucket rate limiting"
+ak run security "src/auth/" --route 'security-scan:opencode:provider/model'
+ak run refactor "extract the payment module" --dry-run
 ```
 
 - **Templates** — `feature` (architect → coder → tester → reviewer), `security`
   (scanner → analyzer → fixer), `refactor` (architect → coder → tester → reviewer),
   `packaging` (packager → reviewer), `release` (preparer → reviewer). Each step's
   host/model comes from your routing policy, not the template.
 - **`--route 'act:host[:model]'`** — per-run routing override (repeatable, not persisted).
-- **`--parallel`** — run independent workers concurrently instead of sequentially.
-- **`--escalate`** — on failure, retry once **up the escalation ladder** (see below).
-- **`--dry-run` / `--json`** — print the materialized config + command, spawn nothing.
+- **`--max-concurrent <n>` / `--timeout <ms>`** — bound parallel work and each worker.
+- **`--dry-run` / `--json`** — print the materialized plan, spawn nothing.
+
+`ak dual` is a deprecated Claude/Codex `claude-flow-codex` compatibility wrapper. It retains its
+own `--parallel` and `--escalate` behavior for existing scripts, but new work must use `ak run`.
 
 ### The Claude ↔ Codex bridge (bidirectional MCP)
 

claude/providers-reference.md

@@ -72,7 +72,8 @@ is unchanged until you opt in.
 When **both** hosts are enabled, `ak` also seeds a **per-activity routing policy** and wires a
 **two-way Claude↔Codex MCP bridge** (Claude reaches Codex via `mcp__codex__codex`; Codex reaches
 ruflo via `[mcp_servers.ruflo]`). `--primary-host claude|codex` chooses which host leads. See the
-dual-mode reference block and `docs/PROVIDERS.md` §3.5 for the routing table and `ak dual run`.
+dual-mode reference block and `docs/PROVIDERS.md` §3.5 for the routing table and canonical `ak run`
+execution.
 
 ### Install & update (install-method-aware)
 

docs/MANAGED-TOOLS.md

@@ -52,7 +52,7 @@ them.
 | --- | --- | --- | --- | --- | --- |
 | **ruflo** | npm `ruflo@latest` | `ak sync` | disk: global `package.json` | npm `view latest` (TTL-cached) | row ✓ / upstream's own `RuFlo V<x>` header ✓ / card + banner ✓ |
 | **agentic-qe** | npm `agentic-qe@latest` | `ak sync` | disk: global `package.json` (project-local fallback) | npm `view latest` (TTL-cached) | row ✓ / `Agentic QE V<x>` chip ✓ / card + banner ✓ |
-| **hosts** (Claude, Codex, OpenCode; routing remains Claude/Codex-only) | npm `@latest` — only when npm-managed | `ak sync` if npm-installed; **explicitly disowned** if brew/mise/native | disk: global `package.json`, else `--version` probe | npm latest for npm-managed only; external → `outdated:false` | row ✓ (version + method) / n/a / card + banner (npm-managed only) ✓ |
+| **hosts** (Claude, Codex, OpenCode; OpenCode routes explicitly through `ak run`) | npm `@latest` — only when npm-managed | `ak sync` if npm-installed; **explicitly disowned** if brew/mise/native | disk: global `package.json`, else `--version` probe | npm latest for npm-managed only; external → `outdated:false` | row ✓ (version + method) / n/a / card + banner (npm-managed only) ✓ |
 | **agentdb** | npm, **pinned to ruflo's bundled version** — deliberately not latest | `ak sync` (repins on core skew) | disk: global `package.json` | ruflo's **bundled** copy (coherence), not npm latest — by design | row ✓ / n/a / card ✓; banner excluded (its authority isn't "latest") |
 | **ruvnet-brain** | npm `ruvnet-brain@latest` + `--version v<tag>` pin (never `github:` HEAD) | `ak sync`; the installer's own nightly self-updater is suppressed at install (`--no-nightly-prompt`) and disabled by sync if found (`ruvnet-brain-nightly` subsystem) | disk: KB `SOURCE.json → releaseTag`, falling back to ak's kit.json stamp for pre-stamping bundles | GitHub `releases/latest` tag (TTL-cached) | row ✓ / `V<tag>` chip ✓ / card + banner ✓ |
 | **kit (self)** | npm, **pinned to the exact version drift saw** (`@pacphi/agentic-kit@<v>`) | `ak sync` (runs last — npm replaces the running code) | disk: running copy's `package.json` | npm `latest` (+ `next` for prereleases, TTL-cached) | row ✓ / n/a / header version + card + banner ✓ |

docs/PROVIDERS.md

@@ -23,8 +23,9 @@ The full model has four separate axes:
 
 A **binding** connects a host to a provider through a projection and transport. One Ollama
 provider can therefore have independent `ollama-via-claude` and `ollama-via-codex` bindings.
-OpenRouter is a provider behind a host, never automatically a third host. OpenCode may support
-managed lifecycle surfaces while remaining ineligible as a primary or per-activity routing host.
+OpenRouter is a provider behind a host, never automatically a third host. OpenCode is an opt-in
+activity-routing host through `ak run`, while remaining ineligible as a primary host or AQE
+provider. Its configured selector does not establish provider, billing, or vendor-diversity facts.
 This Proposed capability model is
 [ADR-0016](adr/0016-capability-driven-integration-adapters.md); current controls below remain
 backward compatible while its implementation proceeds.
@@ -169,7 +170,7 @@ tool-use, long-horizon agent work) and `z-ai/glm-5` (value — 205K context, che
 the 5.x line). Both are **metered** — GLM is never an auto-seed target (seeding only ever
 routes to subscription/local providers).
 
-## Level 3.5 — per-activity routing across Claude + Codex
+## Level 3.5 — seeded Claude + Codex defaults, explicit OpenCode routes
 
 When **both** hosts are enabled and `agentic-qe ≥ 3.13.1` is installed, `ak` seeds a
 **per-activity routing policy**: each kind of work (architecture, implementation, testing,
@@ -191,6 +192,22 @@ and claude becomes the alternate/escalation target — so the experience is ambi
 regardless of which CLI drives. `ak status` marks the primary and fails (not warns) if the
 primary host is missing.
 
+**OpenCode is explicit, not seeded or AQE-projected.** Enable it, then use `ak run` with either
+a persisted route or a run-local override:
+
+```bash
+ak host pick --host claude,opencode \
+  --route 'security-scan:opencode:provider/model'  # persisted intent
+ak run security "src/auth/"                         # canonical execution command
+ak run security "src/auth/" --route 'security-scan:opencode:provider/model'  # run-local
+```
+
+Each OpenCode worker is an isolated, loopback-only supervised server session. A permission request
+is aborted and reported as `permission_required`; `ak` never auto-approves it. OpenCode routes are
+not written to AQE `agentOverrides`, cannot become `primaryHost`, and do not count as a separate
+AQE vendor. `ak dual` is deprecated and rejects OpenCode routes because it retains a Claude/Codex
+compatibility adapter; use `ak run` instead.
+
 Defaults (all overridable; your edits are marked `custom` and never re-seeded):
 
 | Activity | Host | Default model |
@@ -244,8 +261,9 @@ converges those bridges again.
 
 `dualRouting` intentionally names a host and model, not an inference provider. Provider resolution
 is a separate binding lookup; absent grounded evidence remains unknown or explicitly inferred.
-Likewise, `ak dual run` continues to mean the Claude+Codex collaboration substrate. Multiple
-providers behind those hosts do not turn it into three-host-or-more orchestration.
+`ak run` is the canonical host-neutral executor. The deprecated `ak dual run` remains a
+Claude+Codex compatibility wrapper only; multiple providers behind those hosts do not turn its
+legacy adapter into three-host-or-more orchestration.
 
 ## Level 4 — drop down to raw ruflo / agentic-qe
 

docs/TROUBLESHOOTING.md

@@ -33,7 +33,7 @@ ak sync             # apply it
 | opencode: `status` says `no ruflo catalog source` | the agent/skill catalog resolves override → `$RUFLO_REPO` → claude marketplace clone → `@claude-flow/cli` (direct, then nested under ruflo) — all missing | install ruflo (`ak setup` does), or point `providers.opencodeCatalogDir` / `$RUFLO_REPO` at a ruflo checkout |
 | `ruflo memory store` says OK but reads return nothing | Absolute-DB-path pin missing, or WAL not checkpointed, or the WASM fallback above | `ak setup` in the project re-pins + verifies a real write lands on disk |
 | `status` shows a `memory-pin` warning | `CLAUDE_FLOW_DB_PATH` is pinned to a dead or foreign path, so every memory op targets the wrong DB ("Database not initialized" beside a healthy in-repo DB). The pin may be deliberate, so `sync` never touches it | repoint (or remove) the pin in `.claude/settings.local.json` `env` |
-| `ak dual run` refuses to start ("ruflo's memory runtime lacks a native better-sqlite3 binding AND … active native WAL") | Pre-flight guard: the orchestrator's native WAL writer and the WASM `ruflo memory store` would share one DB and corrupt it. It refuses **before** spawning a worker rather than crashing mid-run | `ak sync` builds the native binding for ruflo's memory runtime, then retry the `dual run` |
+| Deprecated `ak dual run` refuses to start ("ruflo's memory runtime lacks a native better-sqlite3 binding AND … active native WAL") | Pre-flight guard: the legacy orchestrator's native WAL writer and the WASM `ruflo memory store` would share one DB and corrupt it. It refuses **before** spawning a worker rather than crashing mid-run | Prefer `ak run` for new work. If an existing dual-run workflow must continue, `ak sync` builds the native binding, then retry it. |
 | `ak provider` or `ak x provider` prints a deprecation warning | Alpha namespace correction: execution-host lifecycle and selection now belong to `host`; inference providers and bindings remain separate concepts | Use `ak host` (or `ak x host` for plumbing). The provider aliases will be removed before stable |
 | Suspicious token burn | Background automation vs interactive usage | ask Claude to run the **ruflo-token-audit** skill (deployed by `setup`) |
 | Live dashboard is empty or has no ruflo/AQE nodes | Live tails new Claude/Codex records by default; existing files start at EOF, while ruflo/AQE stores are not auto-discovered | open Live before producing activity; register a trusted JSONL file with repeatable `--live-source 'surface=path'`; see [Live Sessions](LIVE-SESSIONS.md) |

docs/USAGE-SCORECARD-METRICS.md

@@ -477,8 +477,8 @@ of exactly that kind, both in `parseCodex`.
 **What this does not model:** the by-host cards do not yet carry a separate
 inference-provider dimension. The legacy session record has exactly one `provider`
 field, currently used as host/parser identity. A
-workflow that hands off between Claude and Codex mid-task (e.g. `ak dual
-run`) produces two separate session records, one per host, each correctly
+workflow that hands off between Claude and Codex mid-task (e.g. `ak run`) produces two separate
+session records, one per host, each correctly
 aggregated under the current transcript-host schedule rather than one blended record. That
 API-equivalent estimate is not proof of the provider that actually served either execution.
 
@@ -990,7 +990,7 @@ describes.
   by synthetic regression tests, but has not yet been validated against a
   genuine `thread_source: "subagent"` file on real hardware.** Any
   maintainer whose machine accumulates such a file (most likely from heavy
-  `ak dual run` / hierarchical-mesh swarm usage routing through Codex) should
+  `ak run` / hierarchical-mesh swarm usage routing through Codex) should
   re-run this verification and update this note.
 
 **Independent, third-party verification.**

docs/adr/0004-escalation-per-projection.md

@@ -20,8 +20,8 @@ escalation as universally available would be dishonest.
 Escalation lives in the policy but its **availability is stated per projection path**:
 
 - **aqe projection** — honored **natively** by the shipped `auto-escalation-tracker` / `QEModelRoutingAdapter`.
-- **`ak dual run` wrapper** — ak implements **retry-with-next-rung** on a worker's non-zero exit (wrapper
-  logic ak owns, added in Slice 3).
+- **deprecated `ak dual run` wrapper** — ak implements **retry-with-next-rung** on a worker's
+  non-zero exit (wrapper logic ak owns, added in Slice 3).
 - **raw `claude-flow-codex dual run`** — **no escalation** (materialize-only users). Stated plainly in docs
   and `--help`, never implied.
 
@@ -33,7 +33,8 @@ vendor both improves the odds of recovery and preserves the qe-court vendor-dive
 
 - Honest capability boundaries — no hidden magic; each surface's behavior is documented.
 - Cross-vendor ladders double as diversity insurance.
-- The `ak dual run` wrapper carries retry/escalation state; the raw path stays a thin pass-through.
+- The deprecated `ak dual run` wrapper carries retry/escalation state; the raw path stays a thin
+  pass-through. New execution work uses `ak run`.
 - Escalation config validated the same way as primary routes (constructible provider, enabled host).
 
 ## References

docs/adr/0016-capability-driven-integration-adapters.md

@@ -128,8 +128,10 @@ Commands ask the registry what an adapter can do instead of comparing its ID:
 - verification selects host, provider, binding, projection, and observation proof contracts by
   capability.
 
-Consequently, adding OpenCode to the host registry does not make it primary or routable. Adding
-OpenRouter to the provider registry does not make it a host.
+Consequently, adding OpenCode to the host registry alone does not make it primary or routable.
+ADR-0018 subsequently enables explicit `ak run` routes after adding a supervised execution adapter;
+it remains non-primary and outside AQE projection. Adding OpenRouter to the provider registry does
+not make it a host.
 
 ### 3. Use one lifecycle contract for managed projections
 
@@ -363,13 +365,13 @@ model. The two evidence streams describe one execution only when correlation is
 normalized fact/resolution seam is the integration point for issue #59; this ADR does not absorb
 that issue's full parser, ingestion, pricing, or scorecard delivery.
 
-#### OpenCode as a non-routable host
+#### OpenCode at initial adoption
 
 OpenCode uses the same host lifecycle, normalized facts, projections, and observability contracts
-for its supported surfaces. Its initial adapter declares `primary: false` and
-`activityRouting: false`. Tests prove that it appears in applicable management/status choices but
-not in primary-host or activity-routing choices. A later change may enable those capabilities only
-after a separate grounded routing design.
+for its supported surfaces. Its initial adapter declared `primary: false` and
+`activityRouting: false`. ADR-0018 is the subsequent grounded routing design: it enables explicit
+`ak run` activity routes while retaining `primary: false`, no AQE-provider projection, and no
+provider inference from the configured model selector.
 
 ### 9. Deliver in compatibility-preserving slices
 
@@ -394,10 +396,10 @@ not write real home/global configuration.
 
 ## Compatibility and non-goals
 
-- Existing Claude/Codex behavior, `kit.json`, routing defaults, primary-host mirroring, and
-  `ak dual` projections remain valid.
-- This decision does not rename `ak dual`; provider count does not change the number of routed
-  execution hosts.
+- Existing Claude/Codex behavior, `kit.json`, routing defaults, and primary-host mirroring remain
+  valid. ADR-0018 keeps `ak dual` as a deprecated compatibility projection and makes `ak run` the
+  canonical executor.
+- Provider count does not change host identity or create an inference-provider execution host.
 - It does not implement every provider, a public adapter SDK, or arbitrary third-party code
   loading.
 - It does not persist credentials.