@tikoci/centrs 0.1.8 → 0.1.9-next.22

package/commands/execute/README.md

@@ -47,12 +47,23 @@ selection**, examples F1–F5). `romon` and `winbox-terminal` remain
   write-shaped operation. In script mode every command head in a statement
   (the statement start and each `[…]` or `{…}` body) must be a read: its verb
   is the first word past the known menu prefix, so `/ip address print` is a
-  read and `/user expire-password print` is not (examples W3). Root mutators such as `/import` and indirect
-  execution through `:execute` are write-shaped too, and so is any command
-  carrying `file=`: RouterOS redirects command output into a device file, so
-  `/ip/address/export file=address` creates `address.rsc` and
-  `/file/print file=test` creates `test.txt` even though `export` and `print`
-  are read verbs. The shared
+  read and `/user expire-password print` is not (examples W3). Script
+  directives that only output, branch or compute a value are reads, including
+  the pure functions `:serialize`, `:deserialize`, `:convert`, `:delay`,
+  `:find`, `:timestamp`, `:rndnum`/`:rndstr` and the `:to*` converters, and the
+  `{…}`-bodied `:retry` and `:time` (example W4, #458). The absolute
+  `/serialize` spelling counts too; a bare `serialize` keeps the menu-verb rule,
+  because after navigation it could name a menu command. RouterOS runs only a
+  `{…}` block in a script-typed argument, so every body is visible to the gate.
+  Root mutators such as `/import` and indirect
+  execution through `:execute` are write-shaped too, as are `:global`, `:set`
+  and `:parse`, and so is any command carrying `file=` or `file-name=`
+  (including argument prefixes such as `fi=` and `file-n=`, and the spaced
+  `file-name value` spelling under print/export/serialize, example W5):
+  RouterOS redirects output into a device file, so
+  `/ip/address/export file=address` creates `address.rsc`,
+  `/file/print file=test` creates `test.txt` and `:serialize … file-name=x`
+  creates `x`, even though `export`, `print` and `:serialize` are reads. The shared
   `rosetta`/`lsp-routeros-ts`
   canonicalizer is for canonicalization only — never the structured predicate
   (widening `structured` is a product regression). Pinned by
@@ -180,7 +191,9 @@ duplicate that table. Behavior notes the generated reference cannot carry:
 - `--` — use it when the command contains tokens that would otherwise be
   claimed as centrs flags; otherwise the command must be quoted as a single
   argument. In fan-out, positional targets come BEFORE `--` and the command
-  AFTER it (see **Target selection**).
+  AFTER it (see **Target selection**). centrs flags go before `--` too: one of
+  execute's own long flags after it (a trailing `--json`) is refused before
+  dialing as `usage/flag-after-separator`, with the corrected line (#459).
 
 ### Designed, not implemented
 
@@ -265,6 +278,204 @@ 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` for a read,
+  and the outer error `cmr/empty-selection` for a write-shaped command, with
+  or without `--yes` (#460), as RouterOS refuses it (`no devices selected`). A
+  mistyped label then exits 1 instead of looking like a successful bulk write.
+  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.
+- **The controller login is not the limit (#456).** On 7.26beta1, RouterOS
+  does not check the caller's policy against a CMR script. `run-script`
+  needed only `read` + `api` on the controller login, and
+  `/cmr/device/reboot` only `read` + `test` + `api`. A login refused a direct
+  write (`not enough permissions (9)`) still wrote to clients and to the
+  controller's own row through `run-script`, and rebooted a client through
+  both. So a "reader" login on a 7.26beta1 controller is not read-only, and
+  centrs' write gate (and `mcp=ro` on MCP) is the only gate. MikroTik
+  [says](https://forum.mikrotik.com/t/7-26beta-development-is-released/273582/139) 7.26beta2 refuses this for a `read` group; that is not yet
+  checked on a beta2 build. For a write,
+  centrs reads the login's own `/user` row and `/user/group` once (both are
+  readable with just `read` + `api`). When the login lacks `write`, `test` or
+  `reboot`, the result and the confirmation error carry
+  `cmr/caller-policy-not-enforced` naming what it lacks. A failed read only
+  loses the warning.
+- **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. The outer `meta.target` is the controller, and the settings,
+  request and login every member shares are written once on the outer
+  envelope ([constitution](../../docs/CONSTITUTION.md#result-envelope)). Each
+  member's `meta.target.cmr` carries `{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 (with its full meta, as it would render alone) 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.
+- **No progress stream.** `run-script` returns a client's output only when its
+  script ends, and no `/cmr` menu records a running script. To watch a long
+  CMR job, follow what it changes on a client:
+  `centrs retrieve <client> /ip/address --follow` while
+  `execute <controller> --cmr` adds addresses. That only works when the client
+  can also be reached directly; otherwise re-run a read through `--cmr`.
+- **Not on MCP** until delegated authorization is designed (#449). That design
+  must not assume RouterOS refuses a fleet write for a `!write` login (see
+  above). `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`.
+
+### Fleet commands run directly (#453)
+
+A controller's fleet commands are one request to one router that act on many
+devices: `/cmr/device/{reboot,upgrade,pair,run-script}`,
+`/cmr/upgrade/trigger`, `/cmr/upgrade/job/run-next`, and `add`, `set`,
+`remove`, `enable` or `disable` on `/cmr/vlan`, `/cmr/wifi`,
+`/cmr/wifi/radio` and `/cmr/upgrade`. They are write-shaped, so they need
+`--yes`. Before that gate, plain `execute` (and `api`) reads the controller's
+`/cmr/device` inventory, read-only, and resolves which rows the command
+reaches, where it can (see "Not resolved" below). The command still runs
+exactly as typed.
+
+- **The gate names the reach.** The prompt and the `usage/confirmation-required`
+  summary say how many CMR devices the command reaches and whether the
+  controller's own row (`controller=true`) is one of them. `error.context.cmr`
+  has `devices`, `connected`, `controllerIncluded`, `identities` and
+  `inventory`.
+- **How the selection is resolved.** `numbers` matches a row's `.id` or
+  identity. `labels` follows the manual's rules over the row's `labels` and
+  `auto-labels`: plain labels are OR, `+label` must match, `-label` excludes,
+  `all` selects every row, and an expression with only exclusions starts from
+  every row. On a 7.26beta1 lab this matched the device's own selection
+  (a `run-script` probe per row) for every expression tried; the lab test
+  re-checks it (CMR-D9). It is the controller's current view: a disconnected
+  device's `auto-labels` can be stale. `/cmr/upgrade/trigger` reaches the rows
+  whose `upgrade-rule` it names. A rule's `set`, `remove`, `enable` or
+  `disable` reads the rule's own `labels`; a `set` that changes `labels`
+  reaches the old and the new devices. WiFi band labels (`+2ghz`, `+5ghz`,
+  `+6ghz`) pick radios, not devices, so they are left out.
+- **Warnings, with or without `--yes`:**
+  - `cmr/selection-includes-controller`: the selection includes the
+    controller's own row (`labels=all` does, per the manual).
+  - `cmr/rule-selects-every-device`: a rule command with no device `labels`
+    (for `/cmr/vlan`, no `port-labels` either). The manual warns that such a
+    VLAN rule provisions every port of every connected device, the controller
+    included, and cuts the fleet's management access.
+  - `cmr/empty-selection`: by the controller's inventory now, nothing is
+    selected. RouterOS refuses this for a `/cmr/device` command; it accepts
+    a rule whose labels match nothing.
+  - `cmr/caller-policy-not-enforced` for `run-script` and `reboot`, as for
+    `--cmr` above (#456).
+- **Not resolved:** an abbreviated selector argument (`lab=all`),
+  `--via ssh` or `mac-telnet`, `/cmr/upgrade/job/run-next` (a job's devices
+  are not in the inventory), and a failed read. The gate still names the
+  fleet command and says why its reach is unknown, for example `would reach
+  the CMR devices it selects through controller ctl (not resolved: an upgrade
+  job's devices are not in the inventory)`, and `error.context.cmr` has
+  `unresolved` instead of the counts. A failed read never blocks the command,
+  and after a transport or login failure the policy read is skipped. Two
+  cases are not recognized as fleet commands at all and keep the plain
+  wording: script-shaped input (a positional id or `[find …]`) and CDB fan-out
+  to several controllers, which has its own gate.
+
 ## mac-telnet L2 validation
 
 Decided (2026-06-06): the real-L2 integration path is `@tikoci/quickchr`'s

package/commands/execute/examples.md

@@ -573,6 +573,47 @@ argument happens to be `print`, so it returns `usage/confirmation-required`.
 Every command head in a statement is checked, including `[…]` and `do={…}`
 bodies.
 
+### W4. Pure script functions are reads; an output file is not (#458)
+
+```bash
+centrs execute $R ':put [:serialize to=json [/system/resource/print as-value]]' --via rest-api --username $U --password $P </dev/null
+```
+
+Envelope: `ok: true` without `--yes`; `data.ret` parses as JSON whose
+`version` is the router's. `:delay`, `:convert`, `:deserialize`, `:find`,
+`:timestamp`, `:rndnum`, `:rndstr`, the `:to*` converters, `:retry` and `:time` are reads
+too; any command inside their arguments or `{…}` bodies is still checked.
+RouterOS runs only a `{…}` block in a script-typed argument and refuses a quoted
+string there, so no body hides in text. `:serialize … file-name=centrs-w4`
+creates a device file, so it returns `usage/confirmation-required`, as `file=`
+does under a read verb. `:global`, `:set`, `:execute` and `:parse` stay writes.
+
+### W5. Abbreviated output-file arguments keep the write gate
+
+```bash
+centrs execute $R '/system identity export fi=centrs-w5' --via rest-api --username $U --password $P </dev/null
+centrs execute $R ':serialize to=json value=1 file-n=centrs-w5.json' --via rest-api --username $U --password $P </dev/null
+```
+
+Both return `usage/confirmation-required` and create no file. The same
+commands with `--yes` pass validation and create `centrs-w5.rsc` and
+`centrs-w5.json`, respectively. Native API has the same result. Through
+`centrs_execute`, an `mcp=ro` record returns `cdb/write-not-permitted` with or
+without `confirm: true`, and creates no file.
+
+RouterOS also accepts `fi "centrs-w5"` and `file-n "centrs-w5.json"`, without
+`=`. They keep the same confirmation and MCP policy gates, including when
+serialize's file argument follows a nested value expression.
+
+`test/integration/execute-write-gate.test.ts` proves the refusal, absence and
+confirmed creation. The export control runs on the selected channel; the
+serialize control pins CHR 7.26beta1, where its file output was reproduced.
+The export uses CLI script spelling: structured attribute validation requires
+full argument names and rejects `fi` as `validation/unknown-attribute`.
+This is a grounding version, not an introduction boundary. Unknown or
+ambiguous output-file prefixes stay write-shaped until the device resolves
+them.
+
 ### R1. A post-validation `/execute` rejection fails the overall envelope
 
 ```bash
@@ -622,6 +663,16 @@ centrs execute --group no-such-group --via rest-api --cdb-file $CDB --json -- /s
 `ok: true`, `data.summary = { total: 0, ok: 0, failed: 0 }`,
 `warnings` include `cdb/empty-group`. Exit `0`.
 
+The same group with a write is an outer error, with or without `--yes`, so a
+misspelled group cannot pass for a successful bulk write (#460):
+
+```bash
+centrs execute --group no-such-group --via rest-api --cdb-file $CDB --yes --json -- '/system/identity/set name=x'
+```
+
+`ok: false`, `error.code` `cdb/empty-group`, `error.context.write` `true`.
+Exit `1`. Nothing is dialed.
+
 ### F3. `--where` device-class selector (subset)
 
 ```bash
@@ -763,9 +814,235 @@ transport.
 ### Q3. Repeated `--quickchr` fans out; an unknown machine is an inner failure
 
 ```bash
-centrs execute --quickchr $NAME --quickchr no-such-machine -- ':put 1' --json
+centrs execute --quickchr $NAME --quickchr no-such-machine --json -- ':put 1'
 ```
 
 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–CMR18 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–D9 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.
+
+The same labels with a write are an outer error, with or without `--yes`, as
+RouterOS itself refuses an empty selection (#460):
+
+```bash
+centrs execute --quickchr $CTL --cmr --labels no-such-label --yes -- '/system/note/set note="x"'
+```
+
+`ok: false`, `error.code` `cmr/empty-selection`, `error.context.write` `true`,
+exit code 1. No note changes.
+
+### 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.
+
+### CMR15. A controller login without `write` or `reboot`
+
+The controller has a group with `read,test,api,rest-api,!write,!reboot,!sensitive,!policy`
+and a user `$READER` in it. That login cannot write on the controller
+directly, but:
+
+```bash
+centrs execute 127.0.0.1 --port $API --username $READER --password $PW --cmr --labels <client> --yes -- '/system/note/set note="<marker>"'
+```
+
+The target is `ok`, the client's note reads `<marker>`, and the envelope warns
+`cmr/caller-policy-not-enforced` with `context.missing` `["write", "reboot"]`:
+CMR ran the script with `read,write,test,reboot` (#456). The same write as the
+lab's admin login has no such warning.
+
+### 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.
+
+### CMR16. A fleet command names the devices it reaches (#453)
+
+```bash
+centrs execute --quickchr $CTL -- '/cmr/device/reboot labels=all'
+```
+
+Without `--yes` (no TTY) this is `usage/confirmation-required`. Its summary
+says it would reach 2 CMR devices, the controller itself among them, and
+`error.context.cmr` is `{devices: 2, controllerIncluded: true}` with both
+identities. The envelope warns `cmr/selection-includes-controller`.
+Nothing reboots.
+
+### CMR17. A rule with no labels
+
+```bash
+centrs execute --quickchr $CTL --yes -- '/cmr/vlan/add vlan-ids=4001 disabled=yes comment=<marker>'
+```
+
+`ok: true` with the warning `cmr/rule-selects-every-device`: the rule has no
+`labels` and no `port-labels`. It is added disabled, so nothing is
+provisioned. Removing it by its `.id` warns the same way, read from the rule:
+
+```bash
+centrs execute --quickchr $CTL --yes -- '/cmr/vlan/remove numbers=<id>'
+```
+
+### CMR18. `run-script` called directly by a login without `write` or `reboot`
+
+With CMR15's restricted login:
+
+```bash
+centrs execute 127.0.0.1 --port $API --username $READER --password $PW --yes -- '/cmr/device/run-script labels=<client> script=":put centrs-cmr18"'
+```
+
+`ok: true`, with the warnings `cmr/caller-policy-not-enforced`
+(`context.missing` `["write", "reboot"]`) and
+`cmr/client-script-not-validated`. The same command as the lab's admin login
+has neither the policy warning nor `cmr/selection-includes-controller`.

package/commands/explain/README.md

@@ -392,7 +392,8 @@ bare menu path. The positional grammar stays **target-first like every other
 router-taking command** (amended in PR review — the shared resolver/selection
 helpers assume it): one positional means offline and it *is* the input; two
 positionals mean live with the router first; `--` is accepted before the
-input; **`--file` replaces the input positional in either form**, so with it
+input, and one of explain's own long flags after it is refused as
+`usage/flag-after-separator` (#459); **`--file` replaces the input positional in either form**, so with it
 every positional is a target. Adding a
 router therefore never reinterprets a previously valid offline invocation.
 

package/commands/mcp/README.md

@@ -178,6 +178,17 @@ MCP server applies it as a hard allowlist:
   regardless of `confirm`; a local CDB mutation through `centrs_devices` or
   `centrs_discover` `save` fails with `usage/confirmation-required` unless
   explicitly confirmed.
+- **`mcp=ro` does not rest on RouterOS policy.** On a 7.26beta1 CMR
+  controller, a login without `write` or `reboot` wrote to a client and to the
+  controller's own row through `/cmr/device/run-script`, and rebooted a client
+  through `run-script` and `/cmr/device/reboot`. That is the CHR reproduction
+  on #456; the integration test re-proves the `run-script` write (CMR15).
+  MikroTik [says](https://forum.mikrotik.com/t/7-26beta-development-is-released/273582/139) 7.26beta2 will refuse this for a `read` group, but
+  centrs' classification does not depend on it: every CMR fleet command
+  (`run-script`, `reboot`, `upgrade`, `pair`, `/cmr/upgrade/trigger`, …) is
+  write-shaped over every path, pinned by `test/unit/write-gate-tables.test.ts`,
+  and `mcp=ro` refuses them whatever the controller login's group is. Any
+  future MCP route to CMR clients (#449) must keep that assumption.
 - **`--allow-adhoc-targets`** (off by default) is reserved for one-off lab/power
   user flows. Current RouterOS-facing tools expose no inline host+credential
   schema, so the CDB allowlist remains the only active target source.

package/commands/mcp/examples.md

@@ -131,6 +131,12 @@ With `$NAME` registered `mcp=ro` (default):
 Envelope: `ok: false`, `error.code = "cdb/write-not-permitted"`. The router is not
 mutated even though `confirm` is true — the CDB policy is authoritative.
 
+Output-file arguments count as writes even when abbreviated:
+`:serialize to=json value=1 file-n=out.json` and
+`/system identity export fi=out` are refused with or without `confirm`.
+The CHR refusal and file read-back controls are
+[execute example W5](../execute/examples.md#w5-abbreviated-output-file-arguments-keep-the-write-gate).
+
 ### 8. Write against an `mcp=rw` target succeeds with `confirm: true`
 
 With `$NAME` registered `mcp=rw`: