@tikoci/centrs 0.1.8-next.0 → 0.1.9-next.0

package/CHANGELOG.md

@@ -8,6 +8,75 @@ documenting cross-cutting shifts that affect contributors and consumers.
 
 ## Unreleased
 
+## 0.1.9-next.0 — 2026-10-13
+
+Pre-release (npm tag `next`; `latest` stays on 0.1.8). Install with
+`bunx @tikoci/centrs@next`. First cut of `execute --cmr`; expect another
+`next` after the next round of CMR work.
+
+### Added
+
+- `execute <controller> --cmr --labels <expr> -- '<command>'` runs one
+  validated command on CMR clients through their controller (RouterOS
+  7.26beta1+; #450, #451). Only the controller is dialed, with its own
+  credentials. Each selected client validates the command with `:parse`
+  first, and a client whose answer is incomplete or rejected is not sent it.
+  The command then goes to each client in its own `run-script` call, bound to
+  the `/cmr/device` row and key it was validated on, and is never retried; a
+  timeout, cancellation or lost call is `cmr/outcome-unknown`. One `--yes`
+  covers the whole selection. Native API (default) and REST to the controller
+  are both CHR-tested. Raw `run-script` through `api` or plain `execute` warns
+  `cmr/client-script-not-validated`. Not on MCP yet.
+- `cmr/policy-denied`: a statement CMR scripts may not run (`/user add`,
+  `/tool sniffer`: the client allows only `read`, `write`, `test` and
+  `reboot`) is reported as such instead of a generic RouterOS failure, also
+  after earlier output. `:parse` accepts these commands, so validation cannot
+  catch them, and statements before the refused one have already run.
+- `cmr/console-only`: `execute` and `api` refuse `/cmr/device/dashboard`. A
+  plain path is refused before dialing; any other spelling (a relative menu
+  change, a block, an `/execute` script) is found in the controller's `:parse`
+  return. On 7.26beta1 it closed a native API session, and over REST it held
+  the controller's REST service for every caller for 10–30 s.
+- `execute --cmr` against a router with no `/cmr/device` says why. RouterOS
+  older than 7.26beta1 (CMR is beta-only) is `routeros/version-unsupported`
+  with `capability: cmr-controller`. A 7.26beta1+ router without the `cmr`
+  package stays `cmr/not-a-controller`, now naming its version and, for a CMR
+  client, its controller.
+- `execute --cmr` accepts a command that opens with a relative menu change
+  (`/system; identity/print`); its `:parse` return was read as incomplete.
+
+### Fixed
+
+- `execute` and `api` never replay a write that was sent (#448). Fan-out
+  retried every `transport/network` and `transport/connection-closed` failure
+  up to twice, so a write whose connection dropped after the router had run
+  it could be applied up to three times. A write is now retried only when one
+  of those failures came before it was sent, for example during validation or
+  a native API login. A write that failed after it was sent, in single-target
+  or fan-out mode, carries the new warning `transport/write-outcome-unknown`,
+  because it may have run. Reads keep the retry.
+
+## 0.1.8 — 2026-10-12
+
+Release (npm tag `latest`; `next` moves forward to 0.1.8). Everything in
+0.1.8-next.0 below, plus two fixes from field-testing it.
+
+### Fixed
+
+- `retrieve --wait` with no deadline value names `--wait` (#445). Written as a
+  bare switch, `--wait --until 'expr'` read `--until` as the deadline and
+  shifted the predicate into a second target, so the CLI reported
+  `usage/fanout-not-supported`. It now fails `settings/invalid-timeout`
+  ("Received the flag: --until"), and every deadline without a unit gets the
+  `--wait`-specific message. A real multi-target `--wait` still gets the
+  fanout refusal.
+- MCP accepts a registered device by its `identity=`, `mac=` or `ip=` comment
+  key, as the CLI does (#444). The allowlist gate now matches with the same
+  resolver the call dials with, so the `mcp=` write policy checked is the
+  policy of the record the call runs against. A name on more than one record
+  fails `identity/ambiguous` with the candidates in `context.matches` and an
+  MCP remediation, instead of resolving to the first.
+
 ## 0.1.8-next.0 — 2026-10-12
 
 Pre-release (npm tag `next`; `latest` stays on 0.1.7). Install with

package/README.md

@@ -149,6 +149,10 @@ so you can always see *why* a given port or transport was chosen.
   metadata) with a granular exit code (`0` all ok / `2` partial / `1` all failed);
   a multi-target write is gated once by `--yes` naming the blast radius. See
   `docs/CONSTITUTION.md` (Target selection grammar).
+- **CMR fleets** (RouterOS 7.26beta1+) are selected on the controller instead:
+  `execute <controller> --cmr --labels <expr> -- '<command>'` validates the
+  command on each client through CMR and runs it there, using only the
+  controller's credentials. See `commands/execute/README.md` (CMR).
 - **Discovery** writes back into the CDB: `discover --save` records MNDP
   neighbors as new entries tagged `group=discovered` with a `source=mndp`
   marker — hints to curate, not authoritative inventory.

package/commands/api/README.md

@@ -110,6 +110,11 @@ vs `--query` distinction.
 - **Writes fan out under `--yes`**, confirmed once up front (not per target).
   Without `--yes`, the error names the blast radius (how many routers) and that
   `--yes` is required.
+- **A sent write is never retried** (#448). Reads, and writes that failed
+  before they were sent, keep the `transport/network` /
+  `transport/connection-closed` retry. A mutating request that failed after it
+  was sent carries the warning `transport/write-outcome-unknown`, in single-target
+  and fan-out mode alike.
 - **`--stream` (or a `/listen` endpoint) is single-session** → `usage/fanout-not-supported` in
   fan-out mode. **`--raw` strips the envelope** → `usage/conflicting-flags` in
   fan-out mode (per-target envelopes can't be bare).

package/commands/execute/README.md

@@ -265,6 +265,123 @@ the command alone (`canonicalizeExecuteCommand` + `isWriteShaped`), so the gate
 fires before any target is dialed. Per-target validation still runs because
 RouterOS schemas can differ by version.
 
+A sent write is **never retried** (#448). Fan-out retries a target only for
+`transport/network` and `transport/connection-closed`, and for a write only
+when the failure came before the request was sent (for example while it was
+being validated). A write that failed after it was sent may have run, so its
+error envelope, single-target or fan-out, carries the warning
+`transport/write-outcome-unknown`.
+
+## CMR clients through their controller (`--cmr`)
+
+`execute <controller> --cmr --labels <expr> -- '<command>'` runs one command on
+the CMR clients (RouterOS 7.26beta1+) that a RouterOS label expression selects
+on the controller (#450). The `<controller>` is an ordinary single target: a
+positional or CDB identity, one `--quickchr`, or `--host`. It is resolved and
+authenticated as usual, and **only the controller's credentials are used**. A
+client is never dialed, so a client behind NAT or reachable only through its
+controller works the same way. CMR is a selection source, not a protocol:
+`--via` pins the **controller** transport (native-api, the default, or
+rest-api). A CMR failure never falls back to dialing a client directly.
+
+CMR is beta-only: it first shipped in 7.26beta1, and the controller also needs
+the optional `cmr` package. When the target has no `/cmr/device`, centrs reads
+its version to say why. A router older than 7.26beta1 is
+`routeros/version-unsupported` (`capability: cmr-controller`). A newer one
+without the package is `cmr/not-a-controller`, which also names the controller
+when the target is itself a CMR client.
+
+- `--labels` is required and passed to RouterOS unchanged: a comma list where
+  plain labels are OR, `+label` must match, `-label` excludes, and `all` also
+  selects the controller. CDB selectors (`--group`/`--where`/`--all`/
+  `--default`/geo), several targets, and `--via mac-telnet|ssh` are
+  `usage/conflicting-flags`. `--labels` without `--cmr` is refused the same way.
+  Labels that no device has are accepted silently by RouterOS; an empty
+  selection is `ok: true` with the warning `cmr/empty-selection`. A device's
+  identity selects it only while the controller's `/cmr auto-labels` includes
+  `identity` (the default `all` does). On 7.26beta1, after `auto-labels=version`
+  a client's row still *showed* its identity label but no longer matched it.
+- **One `run-script` call per device.** On 7.26beta1, `run-script` result rows
+  carry no device id, and their `device` key (`identity@address`) changed
+  *during* a call when a client dropped. So centrs never matches rows to
+  devices by name. Every controller call selects exactly one `/cmr/device` row
+  with `numbers=<.id>`, together with `labels=<expr>`, so a device that left
+  the labels is refused up front instead of run.
+- **Preflight, per inventory row:** the call sends `:put [:parse <command>]`
+  followed by `:put "<nonce>"`, or the nonce alone with `--no-validate`.
+  - A refusal (`no devices selected`) means the device is not a member.
+  - Any row means it is a member; its validation result must be **complete**
+    before it is classified:
+    - status `success`;
+    - the nonce as the last line;
+    - no `...(+N B)` clip marker;
+    - a non-empty return that is IL.
+  - A device with no answer at all (timeout, lost connection) makes the
+    selection incomplete: `cmr/selection-incomplete`, and nothing runs. A
+    partial selection is never run as if it were the whole one.
+- **Binding:** `/cmr/device` is read before preflight, between preflight and
+  the write gate, again for each member just before its own call (the prompt
+  and the fan-out queue can both wait), and after dispatch. A device whose row
+  is gone or whose `ids` key changed is not sent the command
+  (`cmr/membership-changed`); a replacement row is never adopted, even when it
+  matches the labels. If that per-member read fails, the member is not sent the
+  command and its error says so (`context.dispatched: false`). The per-member
+  read is host-side, not atomic with the call: on 7.26beta1 a client script
+  cannot check its own key (`/cmr/client get local-id` reads `*****` inside
+  `run-script`) and `numbers=` does not take `ids`. After dispatch, a sent result is reported
+  as `cmr/outcome-unknown` if the key changed during the call, or if the
+  inventory cannot be re-read (cancelled or unreadable) to confirm which client
+  answered. A CMR `skipped` stays `cmr/client-disconnected`, because nothing was
+  sent.
+- **Write gate:** one `--yes`/TTY confirmation, naming how many clients will run
+  it, how many were excluded, and through which controller. Clients that failed
+  validation are never sent the command.
+- **Dispatch:** one call per validated member, sending the input unchanged with
+  `timeout=` set from `--timeout` (capped at 55 s, under CMR's ~60 s per-call
+  ceiling). Every call pins `strategy=parallel fail-policy=continue
+  freeze-frame-interval=20ms`. **Never retried.**
+- **Outcomes** are a `FanoutData` envelope in inventory order, with exit codes
+  0/2/1. Each member's `meta.target.cmr` carries `{controller, id, deviceKey,
+  address}`. `success` → `data.ret` holds the client's output; a clipped
+  output adds `cmr/output-truncated` and `meta.truncated`. `--max-results`
+  applies per member, as in plain execute fan-out: a member whose rendered
+  envelope exceeds it (UTF-8 bytes) becomes `input/max-results-exceeded`, and
+  that error says the command already ran (`context.dispatched: true`). A `failed` runtime
+  error maps through the usual `routeros/*` table. `skipped` →
+  `cmr/client-disconnected`.
+- **What a client script may do:** CMR runs it with only the `read`, `write`,
+  `test` and `reboot` policies and no user session. A command that needs
+  another policy (`/user add`, `/tool sniffer`) passes `:parse` on the client
+  and is refused when it runs: `cmr/policy-denied`. The script stops at that
+  statement, but statements before it already ran and are not rolled back;
+  their output is in `context.output`. Sensitive
+  values read back as `*` or empty. Multi-line commands run every line (the
+  manual says single-line; 7.26beta1 ran both LF and CRLF scripts in full), and
+  `/export` works.
+- **Unknown outcomes:** a CMR timeout (`timed out (6)`, `std failure: timeout
+  (13)`), a local deadline, a cancellation, or a lost call after sending all
+  give `cmr/outcome-unknown`. A cancellation before anything is sent, including
+  one that makes an inventory read fail, is `cmr/cancelled`. On 7.26beta1 the client script **kept running**
+  in each of these cases.
+- **Validation metadata** reports what ran: `source: ":put [:parse ...] via cmr
+  run-script"`, the same claim the console gate makes. There is no client
+  `/console/inspect` stage.
+- **Not on MCP** until delegated authorization is designed (#449). `retrieve
+  --cmr` is deferred (#441).
+
+`/cmr/device/dashboard` is an interactive console view, refused as
+`cmr/console-only`. A plain path, abbreviated or not (`/cmr/dev/dash`), is
+refused before dialing. Any other spelling is found in the `:parse` return
+during validation, which resolves console spacing, a relative menu change
+(`/cmr/device; dashboard`), blocks and `api POST /execute` scripts, and ignores
+strings and comments. With `--validate=false` only the plain path is refused.
+On 7.26beta1 it closed a native API session, and over REST it held the
+controller's REST service for every caller for 10–30 s.
+
+Calling `/cmr/device/run-script` yourself, through `api` or plain `execute`,
+validates only the controller request. The envelope then carries the warning
+`cmr/client-script-not-validated`.
+
 ## mac-telnet L2 validation
 
 Decided (2026-06-06): the real-L2 integration path is `@tikoci/quickchr`'s

package/commands/execute/examples.md

@@ -769,3 +769,165 @@ centrs execute --quickchr $NAME --quickchr no-such-machine -- ':put 1' --json
 Envelope: outer `ok: true`, `data.summary = { total: 2, ok: 1, failed: 1 }`;
 the unknown machine's inner error is `quickchr/machine-not-found`. Exit code 2
 (partial).
+
+## CMR clients through a controller (#450)
+
+`test/integration/execute-cmr.test.ts` runs these on a two-CHR CMR lab
+(`test/integration/cmr-lab.ts`): `$CTL` is a 7.26beta1 controller with the
+`cmr` package, paired with one client over a socket link. Examples CMR1–CMR7
+and CMR10–CMR14 run over **both** `--via native-api` and `--via rest-api` to
+the controller, with validation on. The same test first asserts the device
+behaviour the design depends on (CMR-D1–D8 in the test file).
+
+### CMR0. A router without CMR
+
+```bash
+centrs execute <router> --cmr --labels all -- ':put x'
+```
+
+On RouterOS older than 7.26beta1 this is `routeros/version-unsupported` with
+`context.capability` `cmr-controller` and the running version. On 7.26beta1 or
+later without the `cmr` package it is `cmr/not-a-controller` with the version.
+Nothing is dispatched. `test/integration/execute.test.ts` runs this on the
+channel's CHR and expects the code its version calls for.
+
+### CMR1. A read on every client
+
+```bash
+centrs execute --quickchr $CTL --cmr --labels all -- ':put [/system/identity/get name]'
+```
+
+`data.summary` is `{total: 2, ok: 2}`. Each target's `data.ret` is that
+device's own identity. `meta.validation.source` is `:put [:parse ...] via cmr
+run-script` with `result: passed`, and `meta.target.cmr.id` is its
+`/cmr/device` row.
+
+### CMR2. Per-client validation: a controller-only menu
+
+```bash
+centrs execute --quickchr $CTL --cmr --labels all -- /cmr/device/print
+```
+
+The controller runs it. The client has no `cmr` package and is rejected on
+the client itself with `validation/package-missing`, so it is not sent the
+command (`meta.operation.cmr.dispatched` is 1). Exit code 2.
+
+### CMR3. A confirmed write
+
+```bash
+centrs execute --quickchr $CTL --cmr --labels all --yes -- '/system/note/set note="centrs-cmr3"'
+```
+
+Both targets are `ok`, and both routers' `/system/note` reads `centrs-cmr3`.
+
+### CMR4. An unconfirmed write is refused before dispatch
+
+```bash
+centrs execute --quickchr $CTL --cmr --labels all -- '/system/note/set note="centrs-cmr4"'
+```
+
+Outer `usage/confirmation-required` naming the client count and the
+controller. No note changes.
+
+### CMR5. A command every client rejects is never sent
+
+```bash
+centrs execute --quickchr $CTL --cmr --labels all --yes -- '/system/note/set note="x" bogus-arg=1'
+```
+
+Both targets are `validation/unknown-attribute`, `dispatched` is 0, and no note
+changes.
+
+### CMR6. A CMR timeout is an unknown outcome
+
+```bash
+centrs execute --quickchr $CTL --cmr --labels <client> --timeout 2s --yes -- ':delay 4s; :log info "<marker>"'
+```
+
+The target is `cmr/outcome-unknown`, and `<marker>` still appears in the
+client's log afterwards.
+
+### CMR7. Labels that match nothing
+
+```bash
+centrs execute --quickchr $CTL --cmr --labels no-such-label -- ':put x'
+```
+
+`ok: true`, `data.summary.total` is 0, warning `cmr/empty-selection`, exit
+code 0.
+
+### CMR8. CLI exit code for a mixed result
+
+CMR2 through `runCli` exits `2`.
+
+### CMR9. A client that is down
+
+With the client VM stopped and the controller showing it `connected=false`:
+
+```bash
+centrs execute --quickchr $CTL --cmr --labels <client> -- ':put x'
+```
+
+The target is `cmr/client-disconnected` and `dispatched` is 0.
+
+### CMR10. Cancelling after dispatch is an unknown outcome
+
+A library caller aborts `signal` two seconds into:
+
+```bash
+centrs execute --quickchr $CTL --cmr --labels <client> --timeout 20s --yes -- ':delay 6s; :log info "<marker>"'
+```
+
+The target is `cmr/outcome-unknown` with `dispatched` 1. `<marker>` is not in
+the client's log when the call returns, and appears afterwards: cancelling
+the controller call did not stop the client script.
+
+### CMR11. A command needing a policy CMR scripts lack
+
+```bash
+centrs execute --quickchr $CTL --cmr --labels <client> --yes -- '/user/add name=<user> group=read password=<x>'
+```
+
+Validation passes on the client (`:parse` accepts it), then the client refuses
+it when it runs: the target is `cmr/policy-denied`, and `<user>` does not exist
+on the client afterwards.
+
+### CMR12. A multi-line command
+
+```bash
+centrs execute --quickchr $CTL --cmr --labels <client> -- $':put centrs-l1\n:put centrs-l2'
+```
+
+The target is `ok` and `data.ret` holds both lines.
+
+### CMR11b. A refused statement after others have run
+
+```bash
+centrs execute --quickchr $CTL --cmr --labels <client> --yes -- $':put before\n/system/note/set note="<m>-before"\n/user/add name=<user> group=read password=<x>\n/system/note/set note="<m>-after"'
+```
+
+The target is `cmr/policy-denied`, and its `context.output` starts with
+`before` followed by the `not enough permissions (9)` line. The client's note
+is `<m>-before`: the statement before the refused one ran and stays, and the
+script stopped at the refused one. `<user>` does not exist.
+
+### CMR14. `--cmr` pointed at a client
+
+```bash
+centrs execute --quickchr <client> --cmr --labels all -- ':put x'
+```
+
+`cmr/not-a-controller`: the client runs 7.26beta1 but has no `cmr` package.
+`context.controllerIdentity` names the controller it is paired to.
+
+### CMR13. The dashboard behind a relative menu change
+
+```bash
+centrs execute --quickchr $CTL -- '/cmr/dev; dash'
+centrs execute --quickchr $CTL -- ':put "CMR device dashboard"'
+```
+
+The first is `cmr/console-only`: the controller's `:parse` resolves it to
+`/cmr/device/;(evl /cmr/device/dashboard)`, so it is refused before it runs.
+The second is `ok` with `data.ret` `CMR device dashboard`: a string that spells
+the words is not a command.

package/commands/mcp/README.md

@@ -149,7 +149,11 @@ The authorization boundary is the WinBox CDB (constitution: identity and CDB),
 which is already centrs's device registry **and** native credential store. The
 MCP server applies it as a hard allowlist:
 
-- **Targets resolve through the CDB only** — by name, MAC, or `group`. Inline
+- **Targets resolve through the CDB only** — by record target, by the
+  `identity=`/`mac=`/`ip=` comment keys (the same matcher the CLI dials with, so
+  the write policy checked belongs to the record the call runs against), or by
+  `group`. A name on
+  more than one record fails `identity/ambiguous` rather than picking one. Inline
   ad-hoc `host` + `username` + `password` are **rejected by default** with
   `cdb/target-not-registered`, whose `fix` points at `centrs_devices add`. An
   agent therefore cannot reach an arbitrary router with arbitrary credentials.

package/commands/mcp/examples.md

@@ -37,10 +37,27 @@ Envelope: `ok: true`, `data.path = "/ip/route"`, `data.verb = "add"`,
 
 Envelope: `ok: false`, `error.code = "cdb/target-not-registered"`, and
 `error.fix`/`remediation` names `centrs_devices add`. No connection is attempted.
-RouterOS-facing MCP tools accept only a CDB `target` (name/MAC/URL) — there is
+RouterOS-facing MCP tools accept only a CDB-registered `target` — the record's
+address (IP/URL/MAC) or its `identity=`/`mac=`/`ip=` comment key — and there is
 no inline `host`/`username`/`password` executor parameter, so RouterOS actions
 use credentials already stored in the CDB.
 
+### 2b. A record's `identity=` name passes the allowlist
+
+The harness registers `$NAME` with the comment `identity=mcp-lab mcp=rw
+via=rest-api`.
+
+```json
+{ "name": "centrs_retrieve",
+  "arguments": { "target": "mcp-lab", "path": "/system/resource" } }
+```
+
+Envelope: `ok: true`, and `meta.target` names the record the call dialed:
+`identity = "mcp-lab"`, `recordIndex = 0`, and `baseUrl` is `$NAME`'s REST URL.
+The allowlist gate and the dialing resolver use the same matcher, so a name on
+more than one record fails `identity/ambiguous` instead of picking one (asserted
+offline in `test/unit/mcp-safety.test.ts`; the CHR test registers one record).
+
 ### 3. `centrs_validate` accepts the bare `blackhole` flag
 
 ```json

package/commands/retrieve/README.md

@@ -513,7 +513,8 @@ retrieve-specific behavior on top of the shared engine:
   `transport/connection-closed` (REST 5xx is mapped to
   `transport/connection-closed`). It does **not** retry `routeros/*`,
   `validation/*`, `auth/*`, `cdb/*`, `target/*`, timeouts, DNS, TLS, or refused
-  connections.
+  connections. (`execute` and `api` share this engine but never replay a write
+  that was sent.)
 
 ## Definition of done
 

package/docs/CLI.md

@@ -87,6 +87,8 @@ Usage: centrs execute <target> <command> [flags] | centrs execute <target...> --
 | `--default` |  | Select the reserved `__default__` record. |
 | `--quickchr` | `<name>` | Target a running quickchr-managed CHR VM by name (repeatable; fans out when repeated). Exclusive of positional targets and CDB selectors; conflicts with direct connection overrides (--host/--port/--username/--password, and --ssh-key where the command has it). |
 | `--concurrency` | `<n>` | Max in-flight targets during fan-out (transport-aware default: rest-api 8, native-api 4). |
+| `--cmr` |  | Run on CMR clients through their controller: the `<target>` is the controller (RouterOS 7.26beta1+, `cmr` package). Needs `--labels`; native-api or rest-api only. |
+| `--labels` | `<expr>` | With `--cmr`: RouterOS label expression selecting clients (comma list; plain = OR, `+` AND, `-` AND NOT, `all`). |
 | `--host` | &lt;host\|url&gt; | Host or base URL to dial. With no `<target>` it is the target (no CDB lookup); with one it overrides the resolved host. |
 | `--port` | `<port>` | Override the resolved management port. |
 | `--username / --user / -u` | `<name>` | RouterOS username (aliases `--user`, `-u`). Falls back to `CENTRS_USERNAME`. |

package/docs/CONSTITUTION.md

@@ -309,7 +309,9 @@ orchestration error or every target failed.
 
 A multi-target **RouterOS write** (e.g. `execute` / `api` add/set/remove across a
 selection) is gated by **`--yes`**, confirmed **once** up front; when it is missing
-the error names the blast radius (how many routers). The separate **`--force`**
+the error names the blast radius (how many routers). A write that was **sent** is
+never retried, because it may already have run; it fails with the warning
+`transport/write-outcome-unknown` instead (#448). The separate **`--force`**
 gate is scoped to destructive **`devices` CDB mutations** (e.g. `devices remove`
 across a group), not RouterOS writes. `terminal`, `api --stream`,
 `retrieve --follow` and `retrieve --sample` are single-session, not fan-out
@@ -365,6 +367,32 @@ single host/port: that shape is the contract quickchr's descriptor and TikTOML's
 exists to prevent. A `--via` whose service key a provider does not supply is a
 typed unsupported-provider error, never a silent fallback.
 
+#### Controller-mediated selection (CMR)
+
+A **CMR controller** (RouterOS 7.26beta1+) is a third kind of source: a live
+inventory whose members centrs never dials. `execute <controller> --cmr
+--labels <expr>` (#450) resolves the **controller** as an ordinary single
+target, and only its credentials are used. RouterOS's label expression selects
+the members, and the command runs on each through the controller's
+`run-script`. Normative:
+
+- CMR is a selection source, **not a protocol**. `--via` pins the controller
+  transport, and a CMR failure never falls back to dialing a client.
+- A member is bound by the controller's row id, never by its display name. A
+  result that cannot be bound to the member it was validated on is not run, or
+  is reported as an unknown outcome.
+- Validation runs **on each client** (`:parse` through CMR) and must be complete
+  before it counts. A client that fails validation is never sent the command,
+  and an incomplete selection runs nothing.
+- A CMR dispatch is **never retried**. A timeout, cancellation or lost call
+  after sending is `cmr/outcome-unknown`, because the client script may still
+  be running.
+- CMR mode is not on MCP until delegated authorization is designed (#449).
+  Registering a controller must not authorize its clients.
+
+The contract and its device evidence are in
+[`commands/execute/README.md` → CMR](../commands/execute/README.md#cmr-clients-through-their-controller---cmr).
+
 ### MCP surface: the CDB is the allowlist
 
 The MCP frontend (`commands/mcp/`) is an adapter over this core, not a new set of

package/docs/MATRIX.md

@@ -56,6 +56,11 @@ and implementation sequencing in the linked issues.
 - `retrieve`, `api`, `execute`, and `transfer` share the target-selection and
   fan-out contracts from `docs/CONSTITUTION.md`; command-specific boundaries and
   evidence are in their command READMEs and integration tests.
+- `execute --cmr` (#450) is not a grid column: CMR is a selection source, and
+  its controller transports are the `execute` rest-api/native-api cells.
+  CMR1–CMR7 and CMR10–CMR14 pass on a 7.26beta1 CHR lab over both, and
+  CMR8–CMR9 over native-api (`test/integration/execute-cmr.test.ts`). CMR0 (a
+  router without CMR) runs on the channel's CHR in `execute.test.ts`.
 - There is no `update` command. RouterOS CLI-shaped writes ride `execute`; the
   structured operation surface is `api`.
 - `api --stream` absorbs the former `stream`/`tail` surface; native-api stream
@@ -177,15 +182,26 @@ Wire, auth, TCP/UDP, and CI caveats live in `commands/btest/README.md` and the
 
 ## Current priority
 
-**First: the native-api / NDJSON line** (maintainer decision on
+**First: the CMR track** (maintainer decision 2026-10-12 on
+[#441](https://github.com/tikoci/centrs/issues/441)). Done: `execute --cmr`
+(#450), which runs one validated command on CMR clients through their
+controller. The contract is in
+[`commands/execute/README.md` → CMR](../commands/execute/README.md#cmr-clients-through-their-controller---cmr),
+with examples CMR0–CMR14. The CMR-vs-centrs feature map is on #441
+(2026-10-13). Next, in order: the fleet blast-radius gate for controller fleet
+commands (#453), then #449's read-only slice (a `devices` view of members and a
+default controller). Deferred: CDB linkage (#449) and `retrieve --cmr` (#441).
+Live `explain` resumes after this.
+
+**The native-api / NDJSON line** (maintainer decision on
 [#396](https://github.com/tikoci/centrs/issues/396), 2026-10-07): agents in the
 field poll with `sleep` where a native follow would answer. In order:
 (1) done: #402, literal `api --stream` with `!empty` frames and
 `--format ndjson`; (2) done: `retrieve --follow` (#396, unfiltered);
 (3) done: `retrieve --sample`; (4) #397: one-shot `retrieve --query` done,
 filtered `--follow` done; #364 (`--wait`/`--until`, same grammar) done;
-(5) #398 and #401. Each slice's contract lives in its command
-README. Live `explain` (below) resumes after this line.
+(5) #398 and #401 remain open. Each slice's contract lives in its command
+README.
 
 **Tightening validation as a whole** is the next track, in the three-step
 order agreed on [#236](https://github.com/tikoci/centrs/issues/236):

package/docs/errors/cmr/cancelled.md

@@ -0,0 +1,15 @@
+# `cmr/cancelled`
+
+The operation was cancelled before the command was sent to this CMR client, so
+nothing ran on it.
+
+## Typical trigger
+
+The caller aborted (Ctrl-C, or an `AbortSignal` in the library) during
+preflight or before this member's dispatch. Members that had already been sent
+the command are reported as [`cmr/outcome-unknown`](./outcome-unknown.md)
+instead, because cancelling does not stop a client script that has started.
+
+## Fix
+
+Re-run when ready.

package/docs/errors/cmr/client-disconnected.md

@@ -0,0 +1,19 @@
+# `cmr/client-disconnected`
+
+CMR skipped the client because it is not connected to the controller. The
+command was **not** sent to it.
+
+## Typical trigger
+
+The controller answered `run-script` for this client with status `skipped` and
+output `disconnected`. The client is down, unpaired, or cannot reach the
+controller on TCP/54321. A client that has just gone down may instead stall
+until the controller notices; that case surfaces as
+[`cmr/validation-incomplete`](./validation-incomplete.md) or
+[`cmr/outcome-unknown`](./outcome-unknown.md).
+
+## Fix
+
+- On the client, `/cmr/client print` should show `status: paired,connected`.
+- Check its route and firewall towards the controller (TCP/54321).
+- Re-run once it reconnects; the other members' results are unaffected.

package/docs/errors/cmr/client-script-not-validated.md

@@ -0,0 +1,22 @@
+# `cmr/client-script-not-validated`
+
+A warning: a caller-addressed `/cmr/device/run-script`, sent through `api` or
+plain `execute`, passed validation **as a controller request**. The `script=`
+it carries was not validated on any CMR client.
+
+## Typical trigger
+
+```sh
+centrs api ctl /cmr/device/run-script -X POST -f labels=all -f 'script=…' --yes
+centrs execute ctl --yes -- '/cmr/device/run-script labels=all script="…"'
+```
+
+`/console/inspect` on the controller checks `labels=` and `script=` as
+arguments. To the controller's `:parse`, the script is an opaque string, so a
+`passed` gate says nothing about whether each client accepts it.
+
+## Fix
+
+Use `centrs execute <controller> --cmr --labels <expr> -- '<command>'`. It runs
+`:parse` on every selected client through CMR and sends the command only to the
+clients that accepted it.

package/docs/errors/cmr/console-only.md

@@ -0,0 +1,29 @@
+# `cmr/console-only`
+
+The command is one of CMR's interactive console views, so centrs refused it
+before running it.
+
+## Typical trigger
+
+`/cmr/device/dashboard` through `execute` or `api`. On RouterOS 7.26beta1:
+
+- over the **native API** it closed the API session;
+- over **REST** it never returned, and every other REST request to the
+  controller then waited 10–30 s until it timed out.
+
+A plain path, abbreviated or not (`/cmr/dev/dash`), is refused before any
+connection opens. Every other spelling is found in the controller's `:parse`
+return during validation, which resolves it to one invocation: console
+spacing, a relative menu change (`/cmr/device; dashboard`), a `:do`/`:if`
+block, a `[...]` substitution, or an `api POST /execute` script. Strings and
+comments that only spell the words are not refused.
+
+With `--validate=false` there is no `:parse` return, so only the plain path is
+refused.
+
+## Fix
+
+- Open the dashboard in WinBox 4 or WebFig, or run it in
+  `centrs terminal <controller>`.
+- For the data behind it, read the menus directly: `centrs retrieve
+  <controller> /cmr/device`, `/cmr/alert` or `/cmr/upgrade/job`.

package/docs/errors/cmr/empty-selection.md

@@ -0,0 +1,19 @@
+# `cmr/empty-selection`
+
+A warning: the `--labels` expression matched no device in the controller's
+`/cmr/device` inventory, so nothing ran. The result is an empty selection with
+exit code 0, the same as an empty CDB group.
+
+## Typical trigger
+
+- A misspelled label. RouterOS label names are case-sensitive, and an unknown
+  label is accepted silently rather than rejected.
+- A missing comma: `labels=office+ap` is one label named `office+ap`; use
+  `office,+ap`.
+- Every matching device was removed from the controller.
+
+## Fix
+
+Check the labels on the controller (`/cmr/device print` shows `labels` and
+`auto-labels`) and re-run. `--labels all` selects every device, including the
+controller.