@tikoci/centrs 0.1.8 → 0.1.9-next.22

package/CHANGELOG.md

@@ -6,46 +6,204 @@ The product evolves as a stream of changes; there are no alpha gates.
 Per-feature status is tracked in `docs/MATRIX.md`. Use this file for
 documenting cross-cutting shifts that affect contributors and consumers.
 
-## Unreleased
+Each stable version has one section. Work in progress goes under
+`## X.Y.Z — next`, which is what `@next` installs (`X.Y.Z-next.N`); the stable
+release dates that heading. A `-next.N` build has no section of its own.
 
-## 0.1.8 — 2026-10-12
+## 0.1.9 — next
 
-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.
+In progress on npm tag `next`. The `0.1.9-next.0` cut (2026-10-13) carried
+part of this section.
 
-### Fixed
+### Added
 
-- `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.
+- `centrs --version` / `-V` prints the package version alone; `--json` (or
+  `--format json|yaml`) returns an envelope with `data.version` (#463).
+- `execute --cmr` warns `cmr/caller-policy-not-enforced` when a write runs
+  through a controller login that lacks `write`, `test` or `reboot`. On
+  7.26beta1 RouterOS runs the client script with all four anyway, so the
+  login is not the limit (#456). MikroTik says 7.26beta2 refuses this for a
+  `read` group. The warning is also in the confirmation
+  error. centrs reads the login's own `/user` row and group once, only for a
+  write; a failed read only loses the warning.
+- The write gate of a CMR controller fleet command run with plain `execute` or
+  `api` names the devices it reaches (#453). `/cmr/device/reboot labels=all`
+  used to read as one router; centrs now reads the controller's `/cmr/device`
+  inventory first and says, for example, "2 CMR device(s) through controller
+  ctl, the controller itself among them" (`error.context.cmr`). The covered commands are
+  `/cmr/device/{reboot,upgrade,pair,run-script}`, `/cmr/upgrade/trigger` and
+  rule changes on `/cmr/vlan`, `/cmr/wifi`, `/cmr/wifi/radio` and
+  `/cmr/upgrade`. New warnings, with or without `--yes`:
+  `cmr/selection-includes-controller` and `cmr/rule-selects-every-device`
+  (a VLAN rule with no `labels` and no `port-labels` cuts the fleet's
+  management access). `cmr/empty-selection` is also a warning here.
+  `run-script` and `reboot` carry `cmr/caller-policy-not-enforced` as
+  `execute --cmr` does. The command still runs as typed, and a failed read
+  never blocks it.
+
+- `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.
+
+### Changed
+
+- Text stdout is data (#470). In text mode, single-target `execute`, `api`,
+  `retrieve` and `transfer` write only the result to stdout. Everything else
+  goes to **stderr** on success and on failure: the `--verbose` header, one
+  `warning [<code>]: <message>` line per warning, and the `Tips:` footer.
+  Plain `execute` and `api` used to drop warnings and envelope tips, so a
+  `--yes` write never showed, for example, `cmr/rule-selects-every-device` or
+  `transport/write-outcome-unknown`. `retrieve` and `transfer` used to mix
+  them into stdout. `transport/provider-trust` stays out of text output.
+  `--json` keeps everything, `api --raw` is unchanged, and fan-out text still
+  lists warnings in its report.
+- **Breaking:** shared meta is written once (#461, #462). In a fan-out
+  envelope, each target's `meta.settings` keeps only the keys whose source differs from the
+  outer `meta.settings`. Its `meta.operation` drops `request` and `auth` when
+  they equal the outer operation's. When every target agrees on `auth`, or on
+  a setting the outer `meta.settings` lacks (`api` and `transfer` had none), it
+  moves to the outer envelope. An `execute --cmr` member no longer
+  repeats the controller in `meta.target.cmr`, because the outer `meta.target`
+  is the controller. A 3-client `execute --cmr` result went from 9.8 KB to
+  5.4 KB. `expandFanoutTarget()` returns a target's full meta. A
+  `retrieve --follow` frame now carries only `meta.operation`;
+  `started`, `synced` and the summary still carry the full meta. A frame line
+  went from about 1.15 KB to 270 bytes.
+- **Breaking:** all three streams (`retrieve --follow`, `retrieve --sample`,
+  `api --stream`) open with a full-meta `started` line (`data: null`), replacing
+  `notice` where it was emitted (#473, #480). Advice is in its `tips`. Only
+  `meta.operation` remains on each `frame` or `sample`; the full meta stays
+  on `started`, `summary`, and follow's `synced`. Consumers must handle
+  `started` and read shared meta from those lines. `apiStream()` now yields
+  `ApiStreamLine`, and `retrieveSample()` yields `RetrieveStreamLine`;
+  `ApiStreamFrameEnvelope`, `StreamLineEnvelope` and `isStreamDataLine` are
+  exported for consumers. API frames also gain `observedAt` (host receipt
+  time, ISO 8601). In text mode only frame/sample rows go to stdout; status
+  lines, tips, warnings and errors go to stderr. Structured formats keep
+  every line on stdout, and `api --raw` omits `started`.
+- `retrieve --follow` frames carry `observedAt` (ISO 8601, host clock): when
+  centrs received the reply the frame is built from (#462).
+- With `--query`, a removal the follow's sweep finds is `source: "sweep"`,
+  as documented; it was labelled `membership` (#462).
+- An empty selection is an error for a write: `execute`, mutating `api` and
+  `transfer upload|remove|mkdir|copy` fan-outs (`cdb/empty-group`,
+  `cdb/empty-selection`) and `execute --cmr` (`cmr/empty-selection`) now exit 1
+  with `ok: false`, with or without `--yes`. A mistyped group or label passed
+  for a successful bulk write with exit 0 (#460). A read over an empty
+  selection is unchanged: `ok: true` with the warning.
+- The write gate treats pure script functions as reads, so a structured read
+  such as `:put [:serialize to=json [/system/resource/print as-value]]` no
+  longer needs `--yes` (#458). The added directives are `:serialize`,
+  `:deserialize`, `:convert`, `:delay`, `:find`, `:timestamp`, `:jobname`,
+  `:nothing`, `:range`, `:rndnum`, `:rndstr`, `:retry`, `:time` and the `:to*`
+  converters, all from the grounded root-command vocabulary. Commands inside
+  their arguments and `{…}` bodies are still checked; on CHR 7.24.5 and
+  7.26beta1, RouterOS refuses a quoted string as a script body. `file-name=`
+  (`:serialize`'s output file) now gates like `file=`. `api POST
+  /console/inspect` is a read.
+- CMR fleet commands (`/cmr/device/{run-script,reboot,upgrade,pair}`,
+  `/cmr/upgrade/trigger`, `/cmr/upgrade/job/run-next`) are pinned as writes in
+  every spelling, over `execute`, `api` and MCP `mcp=ro`. On 7.26beta1 a
+  controller login with only `read` + `api` can run them (#456).
+- CI, release, Pages and the Docker image run Bun 1.4.2 (was 1.3.14), the
+  version local development already used; `@types/bun` moves with it (#438).
+  `engines.bun` stays `>=1.3.11 <2`. The `typescript` peer stays `^6.0.3`:
+  the source passes `tsc --noEmit` under TypeScript 7.0.2, but typedoc 0.28 (the
+  API reference build) supports TypeScript up to 6.0.x only.
+- QA records a CHR leg in `qa-history` only when its test step passed or
+  failed. A leg cancelled by a newer push, or skipped after a setup failure,
+  was recorded as `fail` (#442).
+- CHR integration runs prefetch their selected image before tests start,
+  including direct file runs, so a cold-cache download does not consume a
+  test timeout. `bun run chr:prefetch` is the explicit entry point (#468).
+- A centrs flag written after `--` is refused before anything dials, as
+  `usage/flag-after-separator`, with the corrected command line (#459). This
+  applies to `execute` (including `--cmr`) and `explain`. Before, a trailing
+  `--json` was sent to RouterOS and failed there as `unknown-attribute`. Only
+  a command's own long flags are matched (short aliases such as `-u` stay
+  RouterOS input), and password values are not echoed.
 
-## 0.1.8-next.0 — 2026-10-12
+### Fixed
 
-Pre-release (npm tag `next`; `latest` stays on 0.1.7). Install with
-`bunx @tikoci/centrs@next`.
+- Abbreviated output-file arguments (`fi=`, `file-n=`), and the spaced
+  `file-name value` form under print/export/serialize, require write
+  confirmation in `execute`, including inside scripts, and are refused for
+  MCP `mcp=ro` records. RouterOS accepted these spellings while centrs
+  recognized only `file=` and `file-name=`, letting file creation bypass
+  both gates.
+- The suggested command in `usage/flag-after-separator` redacts credentials
+  in positional targets and `--host` values, including a host flag moved
+  before `--` and percent-encoded URL credentials. Inline value flags keep their
+  flag names in the correction. This closes error-path gaps in the target
+  redaction below; explicit URL credentials are refused before CDB lookup too.
+- Serialized error causes keep `name`, `message` and `code` and omit raw JS
+  stack traces and their local installation paths (#476, #480).
+- A target with credentials in it (`http://admin:pass@host`, `admin:pass@host`,
+  `admin@host`) is refused with `input/invalid-target`, which names
+  `--username` and `--password` (#478). centrs never used those credentials,
+  and it echoed the whole string, password included, in `meta.target.input`,
+  the fan-out selection and the `--verbose` header. The refusal covers the
+  positional, `--host`, `CENTRS_HOST`, CDB targets and fan-out literals, and
+  any displayed target has `user:pass@` replaced by `***@`, even when the
+  password holds `/`, `?` or `#`. A CDB identity containing `@` (`rtr@site`)
+  still resolves.
+
+- `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.
 
 ### Maintenance
 
-- Refresh vulnerable dependencies within existing ranges and use Bun's
-  Dependabot ecosystem for `bun.lock` (#390). Preserve the dependency group
-  and the `has-flag` major-version ignore. Remaining dependency advisories
-  and updater verification are tracked in #390.
-- Pre-release dependency alignment (#390): runtime ranges now floor at the
-  tested versions (`@modelcontextprotocol/sdk ^1.32.1`, `zod ^4.6.7`),
-  `smol-toml` is overridden past its advisories, and `@types/bun` is pinned
-  exactly to the 1.3.14 runtime (re-pin tracked in #438). The two residual
-  advisories (`braces`, `katex`) are dev-tool-only and do not ship in the
-  package.
+- Releases are one dispatch from `main` (#484, #485). `@next` publishes
+  `X.Y.Z-next.<run_number>` with no commit, PR or tag, and reuses main's QA
+  run on the commit instead of sweeping every channel again. `@latest` creates
+  the tag and a GitHub Release. A pushed `v*` tag no longer publishes. The
+  changelog keeps one section per stable version; the `0.1.8-next.0` and
+  `0.1.9-next.0` sections are folded into theirs.
+- The CodeQL workflow no longer runs the AI-findings probe job (#486). Code
+  Quality AI findings are a paid feature this repository does not enable.
+- Workflows reference actions by major tag, never by commit SHA, and
+  `SECURITY.md` records why (#266). Every `setup-bun` step reads the Bun
+  version from `packageManager`, so changing Bun is a one-line edit. Every
+  checkout except the QA history push drops its git credentials.
+- zizmor audits the workflows: in CI as `Analyze (zizmor)` in `codeql.yaml`
+  (Security tab), and locally with `bun run lint:actions` (#266). Its first
+  run found two `${{ … }}` expansions inside shell scripts, in `lab.yaml` and
+  `qa.yaml`; both now go through `env:`.
+
+## 0.1.8 — 2026-10-12
+
+Most of this section first shipped as `0.1.8-next.0` (2026-10-12).
 
 ### Added
 
@@ -83,6 +241,20 @@ Pre-release (npm tag `next`; `latest` stays on 0.1.7). Install with
 
 ### 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.
+
 - `execute` honors an explicit target URL, and native-api honors a typed port
   (#426, from #384). With no `via` pinned, an `http(s)://host[:port]` target
   selects rest-api on that scheme and port instead of silently dialing native
@@ -262,6 +434,19 @@ Pre-release (npm tag `next`; `latest` stays on 0.1.7). Install with
   unchanged apart from those remediation strings and the restored
   `context.detail`.
 
+### Maintenance
+
+- Refresh vulnerable dependencies within existing ranges and use Bun's
+  Dependabot ecosystem for `bun.lock` (#390). Preserve the dependency group
+  and the `has-flag` major-version ignore. Remaining dependency advisories
+  and updater verification are tracked in #390.
+- Pre-release dependency alignment (#390): runtime ranges now floor at the
+  tested versions (`@modelcontextprotocol/sdk ^1.32.1`, `zod ^4.6.7`),
+  `smol-toml` is overridden past its advisories, and `@types/bun` is pinned
+  exactly to the 1.3.14 runtime (re-pin tracked in #438). The two residual
+  advisories (`braces`, `katex`) are dev-tool-only and do not ship in the
+  package.
+
 ## 0.1.7 — 2026-09-27
 
 ### Added

package/GLOSSARY.txt

@@ -487,6 +487,14 @@ iff
 smol
 katex
 
+# CI tooling vocabulary
+# %zizmor: GitHub Actions static analyzer; config .github/zizmor.yml (#266).
+#   https://docs.zizmor.sh
+# artipacked: zizmor audit for git credentials persisted by checkout.
+zizmor
+zizmorcore
+artipacked
+
 # GitHub Pages build vocabulary (scripts/build-pages-site.ts, pages.yaml)
 # typedoc/pandoc: the API-reference generator and the markdown->HTML converter
 #   the Pages build chains together. gfm: GitHub-Flavored Markdown, pandoc's

package/README.md

@@ -11,13 +11,15 @@ installing centrs or connecting to a router:
 bunx @tikoci/centrs@next explain '/ip/address print' --json
 ```
 
-Use `bunx @tikoci/centrs@next --help` to inspect the full preview CLI. Since
-0.1.6 the dist-tag follows standard SemVer semantics rather than the old
-even/odd-minor rule: a plain version (`0.1.6`) publishes to `latest` and carries
-`next` forward with it, while a pre-release suffix (`0.1.7-next.0`) publishes to
-`next` only and never moves `latest`. So `@next` is the leading edge and can
-equal `@latest` between cuts — `npm view @tikoci/centrs dist-tags` is the
-authority.
+Use `bunx @tikoci/centrs@next --help` to inspect the full preview CLI, and
+`bunx @tikoci/centrs@next --version` (`-V`; `--json` for an envelope) to print
+the exact version for scripts and field reports. The dist-tag follows standard
+SemVer semantics: a plain version (`0.1.8`) publishes to `latest` and carries
+`next` forward with it, while a `next` build (`0.1.9-next.23`) publishes to
+`next` only and never moves `latest`. A `next` build is described by the
+`## 0.1.9 — next` section of [`CHANGELOG.md`](CHANGELOG.md). So `@next` is the
+leading edge and can equal `@latest` between cuts —
+`npm view @tikoci/centrs dist-tags` is the authority.
 
 The full flag reference for every command is generated from the CLI metadata
 into [`docs/CLI.md`](docs/CLI.md); per-command behavior lives in
@@ -149,6 +151,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.
@@ -207,8 +213,10 @@ GitHub issues it links are the roadmap.
 
 Requirements:
 
-- Bun 1.3.11 or newer (CI pinned to 1.3.14; Bun 2.x not yet validated).
+- Bun 1.3.11 or newer (CI runs the `packageManager` version in `package.json`;
+  Bun 2.x not yet validated).
 - Git.
+- `uv`, only for `bun run lint:actions` (zizmor workflow audit).
 - For integration tests: QEMU plus `@tikoci/quickchr` (handles CHR image
   download and boot).
 

package/SECURITY.md

@@ -14,14 +14,22 @@ Please include the affected files or workflow, reproduction details, and impact.
 
 The repository's [Security tab](https://github.com/tikoci/centrs/security) is the live source of current alerts and advisories. This section describes *what* checks run and *why*, so the doc stays meaningful even when the badge is at 0.
 
-- **CodeQL** — repo-managed workflow at [`.github/workflows/codeql.yaml`](.github/workflows/codeql.yaml) with config [`.github/codeql-config.yml`](.github/codeql-config.yml). Query suite: `security-and-quality` (security-extended + code-quality) plus a small custom pack, [`.github/codeql-house-rules/`](.github/codeql-house-rules/), that structurally checks a handful of repo-specific invariants (currently: `apiFanout` must call its named protocol/validation gates) — see `.github/instructions/github-security-quality.instructions.md` for scope and the verify-before-promote discipline for adding more rules there. Languages: `javascript-typescript`, `actions`. Schedule: push to `main`, pull requests to `main`, weekly cron, and manual dispatch.
-- **Code Quality (AI findings, preview)** — confirmed active in GitHub as of 2026-07-03 (not just "intended"; see [issue #166](https://github.com/tikoci/centrs/issues/166)). [`.github/workflows/codeql.yaml`](.github/workflows/codeql.yaml) includes a non-failing forward-compat probe for a future AI-findings API. AI findings are noisy and self-contradicting; we accept the noise because the second-opinion catches real issues that the static suite misses. Steady-state goal is 0 open findings. False positives are dismissed via the GitHub UI with a written justification — that text is the audit-log contract. Side effect: GitHub's own Code Quality scan runs in parallel with our Advanced Setup and posts a same-named `Analyze (javascript-typescript)` check, so PR checks lists show it twice — cosmetic, tracked in #166, not a required check either way (see issue #118).
+- **CodeQL** — repo-managed workflow at [`.github/workflows/codeql.yaml`](.github/workflows/codeql.yaml) with config [`.github/codeql-config.yml`](.github/codeql-config.yml). Query suite: `security-and-quality` (security-extended + code-quality) plus a small custom pack, [`.github/codeql-house-rules/`](.github/codeql-house-rules/), that structurally checks a handful of repo-specific invariants (currently: `apiFanout` must call its named protocol/validation gates) — see `.github/instructions/github-security-quality.instructions.md` for scope and the verify-before-promote discipline for adding more rules there. Languages: `javascript-typescript`, `actions`. `test/` is excluded (`paths-ignore`); it is not shipped, and its CLI argv credentials over-tainted every CLI render path. Schedule: push to `main`, pull requests to `main`, weekly cron, and manual dispatch.
+- **Code Quality** — GitHub's own scan, enabled in repository settings (not a workflow here). It runs as the separate "CodeQL - Code Quality" run on every PR and push and reports different findings from the CodeQL workflow above. Steady-state goal is 0 open findings. False positives are dismissed via the GitHub UI with a written justification — that text is the audit-log contract. Side effect: it posts a same-named `Analyze (javascript-typescript)` check, so PR checks lists show it twice — cosmetic (see [issue #166](https://github.com/tikoci/centrs/issues/166)), not a required check either way (see issue #118).
+- **Code Quality AI findings** — not used: a paid feature, not enabled for this repository.
+- **zizmor** — GitHub Actions static analysis, as the `Analyze (zizmor)` job in [`.github/workflows/codeql.yaml`](.github/workflows/codeql.yaml). Findings go to the Security tab and do not fail the job. [`.github/zizmor.yml`](.github/zizmor.yml) accepts tag refs (see GitHub Actions below) and turns off the Dependabot cooldown audit. `bun run lint:actions` runs it locally (needs `uv`); it is not part of `lint:ci`.
 - **Dependency review** — not enabled. GitHub dependency review follows dependency-graph ecosystem support, and this Bun-only repository currently does not have a supported lockfile for that gate.
 - **Dependabot security updates** — unsupported for Bun in GitHub's [ecosystem support table](https://docs.github.com/en/code-security/reference/supply-chain-security/supported-ecosystems-and-repositories). [`.github/dependabot.yaml`](.github/dependabot.yaml) configures weekly Bun **version updates** and GitHub Actions updates. Dependency security cleanup also requires `bun audit` and reviewed lockfile upgrades.
 - **Secret scanning** — enabled in GitHub, with push protection.
 - **Private vulnerability reporting** — enabled via GitHub Security Advisories.
 
-Some GitHub Security tab data, especially Code Quality AI findings, is not reachable through the default workflow `GITHUB_TOKEN` (`repos/{owner}/{repo}/code-quality/findings` 403s there even with `security-events: read`) — it does respond with an elevated/owner-scoped token, but no findings have been recorded yet to confirm the response shape end-to-end (see #166). Human review in the GitHub UI remains part of the security workflow until that's wired up.
+Human review of the Security tab in the GitHub UI is part of the security workflow; no workflow gates on Code Quality findings.
+
+## GitHub Actions
+
+- **Action refs are tags, not commit SHAs** (`actions/checkout@v7`, `oven-sh/setup-bun@v2`), for first-party and third-party actions alike. Use the major tag; an action that publishes none (`zizmorcore/zizmor-action`) gets its release tag. This is a decision ([#266](https://github.com/tikoci/centrs/issues/266)), not an oversight, so a scanner's unpinned-action finding is not a defect here: CodeQL's `actions/unpinned-tag` is excluded in [`.github/codeql-config.yml`](.github/codeql-config.yml), and zizmor's `unpinned-uses` accepts tags in [`.github/zizmor.yml`](.github/zizmor.yml). A tag picks up an action's fixes, including security fixes, on the next run. A SHA pin goes stale silently until a bot bumps it. We accept the risk of a moved tag or a compromised release in exchange. Dependabot's weekly `github-actions` updates move major and release tags.
+- **The Bun version lives in one place.** Every `setup-bun` step reads `packageManager` from `package.json` (`bun-version-file`); the Dockerfile base image is the only other copy.
+- **Checkouts drop git credentials** (`persist-credentials: false`) unless the job pushes. The only one that pushes is the QA accumulate job in `qa.yaml`, which commits to the `qa-history` branch.
 
 ## Supported versions
 

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).
@@ -165,14 +170,28 @@ the suspect.
 ## Write confirmation
 
 Read-only **iff** the method is `GET`, or the endpoint terminal verb is
-`print`/`get`, or it is `listen`. Everything else is treated as a write and needs
-confirmation (`--yes` non-interactively, or a TTY prompt) → otherwise
-`usage/confirmation-required`. Two consequences:
+`print`/`get`, or it is `listen`, or it is a POST to exactly `/console/inspect`
+(it describes and parses commands, never runs them; #458). Everything else is
+treated as a write and needs confirmation (`--yes` non-interactively, or a TTY
+prompt) → otherwise `usage/confirmation-required`. Consequences:
 
 - A `POST …/print` paged read does **not** prompt (keyed on the verb, not the
   wire HTTP method).
 - Streaming does **not** imply read-only: an async-but-mutating command like
   `/system/license/renew --stream` still confirms.
+- A controller's CMR fleet commands (`/cmr/device/{run-script,reboot,upgrade,pair}`,
+  `/cmr/upgrade/trigger`, `/cmr/upgrade/job/run-next`) are writes whatever
+  RouterOS policy the login has: on 7.26beta1 `run-script` needs only `read` +
+  `api` on the controller (#456).
+  Before the gate, `api` reads the controller's `/cmr/device` inventory and
+  names the devices the request reaches, the controller's own row included,
+  with the same warnings as plain `execute`. Where the reach cannot be
+  resolved (for example `/cmr/upgrade/job/run-next`), the gate says so and
+  why (#453; see
+  [execute → Fleet commands run directly](../execute/README.md#fleet-commands-run-directly-453)).
+  `PUT`, `PATCH` and `DELETE` on `/cmr/vlan`, `/cmr/wifi`, `/cmr/wifi/radio`
+  and `/cmr/upgrade` are the menus' `add`, `set` and `remove`, and the `*id`
+  is the rule they act on.
 
 `--raw` does not bypass this gate.
 
@@ -204,7 +223,7 @@ centrs never substitutes polling.
   `ip/address/*1/listen` follows one row (`?.id=*1`).
 - **GET menu + `--stream`** streams one literal print and completes; it does
   not follow. Its summary carries `tip/stream-print` naming the `/listen`
-  form (see the notice below). A streamed GET (or a `/listen`) rejects `-f` fields rather than
+  form (see `started` below). A streamed GET (or a `/listen`) rejects `-f` fields rather than
   silently dropping them.
 - **POST command + `--stream`** runs the literal command with its attributes:
   `api $R /tool/ping -X POST -f address=10.0.2.2 -f count=3 --stream --yes`.
@@ -214,14 +233,22 @@ centrs never substitutes polling.
   `usage/conflicting-flags` instead of being ignored. `/execute` retains
   synchronous `as-string` script semantics. Streaming never makes a command
   read-only.
-- Each wire reply emits one envelope with `meta.operation.stream.kind=frame`
-  and `reply`: **`re`** (a row; `data` is the row, device `.section`,
+- A stream that passed its preflight opens with one `started` line
+  (`meta.operation.stream.kind=started`, `data: null`). It carries the full
+  `meta` (target, settings, validation, request, auth) and any advice in
+  `tips`, and is not counted in `frames`/`rows`.
+- Each wire reply emits one envelope with `meta.operation.stream.kind=frame`,
+  `observedAt` (when centrs received it, host clock, ISO 8601; a slow reader
+  does not move it) and `reply`: **`re`** (a row; `data` is the row, device `.section`,
   `.dead`, `.nextid` and `.about` verbatim) or **`empty`** (RouterOS `!empty`:
   zero rows; `data` is `null`). RouterOS sends `!empty` for an empty finite
   read, for **each zero-row tick** of `print interval=`, and for a listen
   cancelled before it sent anything. A frame received after centrs stopped the
   stream locally carries `afterStop: true` — that cancellation `!empty` is not
-  evidence of an empty table. A terminal `!done` is not a frame: its
+  evidence of an empty table. A frame carries only `meta.operation` (`kind`,
+  `objectCount`, `stream`); the rest is on `started` and the summary
+  ([constitution](../../docs/CONSTITUTION.md#result-envelope)). A terminal
+  `!done` is not a frame: its
   attributes, when received, appear in successful summary `data.done`,
   including a terminal result received during local cancellation. The stop
   reason still reports the first local bound.
@@ -240,17 +267,19 @@ centrs never substitutes polling.
   one error envelope without starting a stream.
 - Structured streams put **all** envelopes, including errors, on stdout as
   NDJSON and exit nonzero for any failure, even after successful rows. Text
-  mode uses the same outcome/exit rules. `--raw` retains bare payloads and
-  stderr errors; it does not provide the structured stream contract.
+  mode uses the same exit rules but puts only frame rows on stdout; the
+  `started` tips, the summary, warnings and errors go to stderr. `--raw`
+  retains bare payloads and stderr errors; it does not provide the
+  structured stream contract.
 
 `api` never edits a change feed to make it safer; it says what RouterOS will
 not report as tips (CHR 7.23.7 + 7.24.5). Because that advice depends only on
-the request, it arrives **first**: a leading envelope with
-`meta.operation.stream.kind=notice`, `data: null` and the `tips`, before any
-reply — so a filtered watch that never gets a reply still shows it. A notice is
-not a reply and is not counted in `frames`/`rows`; a stream with no advice has
-no notice. The same tips are repeated on the terminal summary, successful or
-failed. `--raw` omits the notice.
+the request, it arrives **first**, in the `tips` of the leading `started`
+line, before any reply — so a filtered watch that never gets a reply still
+shows it. The same tips are repeated on the terminal summary, successful or
+failed. Advice from the live gate (such as `tip/rest-verb-mapping`) rides the
+same two lines, as it does on a one-shot call. `--raw` omits the `started`
+line.
 
 - `tip/filtered-follow` — a `listen` (or `follow`) with a query reports
   neither rows leaving the filter nor deletes. Follow unfiltered and filter

package/commands/api/examples.md

@@ -277,6 +277,18 @@ key. Contrast example 13, where bare `--raw` skips the preflight entirely. This
 pair is how you tell a RouterOS rejection from a centrs bug while staying on the
 bare-passthrough surface.
 
+### 23. POST `/console/inspect` is a read: no `--yes` needed (#458)
+
+```bash
+centrs api $R console/inspect -X POST -f request=child -f path=system,identity --username $U --password $P </dev/null
+```
+
+Envelope: `ok: true`, `data` lists the children of `/system/identity`
+(including `print`). Inspect describes and parses commands but never runs them,
+so a POST to exactly `console/inspect` skips the write gate, non-TTY and
+without `--yes`. PUT/PATCH/DELETE to it (add/set/remove) and abbreviations
+such as `con/insp` are still gated like example 15.
+
 ### H1. `--host` stands in for `<router>` (#428)
 
 ```bash
@@ -484,8 +496,8 @@ centrs api $A ip/address/listen --proplist address,.id,.dead --duration 3s --via
 ```
 
 The harness deletes a seeded address during each. With `address` alone no
-frame carries `.dead` for it, and the leading notice and the summary carry
-`tip/follow-proplist`.
+frame carries `.dead` for it, and the leading `started` line and the summary
+carry `tip/follow-proplist`.
 With `address,.id,.dead` the delete frame is `{ ".id", ".dead": "true" }` and
 there is no tip.
 
@@ -497,7 +509,7 @@ centrs api $A ip/address/listen --query interface=ether1 --duration 3s --via nat
 
 The harness deletes a seeded `ether1` address while listening. RouterOS sends
 nothing for it: the only frame is the cancellation `!empty` (`afterStop`).
-The first line is a `notice` with `tip/filtered-follow`; the summary is `ok`
+The first line, `started`, carries `tip/filtered-follow`; the summary is `ok`
 and repeats it. `--raw-query` is sent
 the same way.
 
@@ -570,8 +582,8 @@ centrs api $A ip/address --stream --via native-api --port $API_PORT --username $
 ```
 
 The print completes on its own (`stopReason=completed`) with one `re` frame
-per row (`rows` equals a one-shot GET's row count); a leading notice and the
-summary carry `tip/stream-print` naming `ip/address/listen`. It never becomes a listen.
+per row (`rows` equals a one-shot GET's row count); the leading `started` line
+and the summary carry `tip/stream-print` naming `ip/address/listen`. It never becomes a listen.
 
 ### L18. Zero-row ticks are `!empty` frames and do not use up `--count`
 
@@ -621,7 +633,7 @@ centrs api --where board=chr ip/address --cdb-file $CDB --json
 The device-class selector matches only record 0, so `data.summary = { total: 1,
 ok: 1, failed: 0 }`, one inner success. Exit code 0.
 
-### F3. An empty selection is `ok:true` with summary 0/0/0
+### F3. An empty selection is `ok:true` with summary 0/0/0 for a read
 
 ```bash
 centrs api --group no-such-group ip/address --cdb-file $CDB --json
@@ -630,6 +642,15 @@ centrs api --group no-such-group ip/address --cdb-file $CDB --json
 `ok: true`, `data.summary = { total: 0, ok: 0, failed: 0 }`, `data.targets = []`,
 and a `cdb/empty-group` warning. Exit code 0.
 
+A mutating method over the same group is an outer error, with or without
+`--yes`, so a misspelled group cannot pass for a successful bulk write (#460):
+
+```bash
+centrs api -X PUT --group no-such-group ip/address -f address=10.99.0.9/32 -f interface=ether1 --yes --cdb-file $CDB --json
+```
+
+`ok: false`, `error.code` `cdb/empty-group`. Exit code 1.
+
 ### F4. A mutating fan-out without `--yes` is rejected, naming the blast radius
 
 ```bash
@@ -691,6 +712,23 @@ target fails deterministically: inner `ok:false` with
 `error.code=target/unresolved` (never a `transport/dns` attempt on `"__default__"`).
 `data.summary = { total: 1, ok: 0, failed: 1 }`. Exit code 1 (every target failed).
 
+## CMR fleet commands (#453)
+
+`test/integration/execute-cmr.test.ts` runs these on the CMR lab described in
+[execute → CMR](../execute/examples.md#cmr-clients-through-a-controller-450),
+over both `--via native-api` and `--via rest-api`.
+
+### CMR1. `POST /cmr/device/reboot` names the devices it reaches
+
+```bash
+centrs api --quickchr $CTL -X POST /cmr/device/reboot -f labels=<client>
+```
+
+Without `--yes` (no TTY) this is `usage/confirmation-required`. Its summary
+names `1 CMR device(s)`, and `error.context.cmr` is
+`{devices: 1, controllerIncluded: false, identities: ["<client>"]}`. Nothing
+reboots.
+
 ## `--query` grammar (#397)
 
 `--query` takes the `print where` grammar shared with `retrieve --query`. The