@tikoci/centrs 0.1.6 → 0.1.8-next.0

package/commands/retrieve/examples.md

@@ -84,6 +84,18 @@ Rejected before any network call, with `usage/conflicting-flags`.
 centrs retrieve $R /system/resource --attribute uptime --all-attributes --username $U --password $P --json
 ```
 
+### 20. Comma-list --attributes on any singleton
+
+Singletons are recognized from `/console/inspect` — their `get` takes no
+`number` argument — so every singleton validates against its `get value-name`
+properties, not against `print`'s flags (#377).
+
+```bash
+centrs retrieve $R /tool/romon --attributes enabled,id --username $U --password $P --json
+```
+
+Envelope: `data` is an object containing only `enabled` and `id`.
+
 ## --list-attributes
 
 ### 9. List attributes for a path
@@ -127,6 +139,9 @@ centrs retrieve $R /system/resource --attribute bogus --username $U --password $
 centrs retrieve $R /system/resource --username wrong --password wrong --json
 ```
 
+`meta.validation` has no `result`. Its one stage is `device: skipped` with
+`reason: "not reached: transport/auth-failed"` (GH#435).
+
 ### 13. Unreachable host
 
 `transport/connection-refused` (not the more general `transport/network`).
@@ -135,6 +150,10 @@ centrs retrieve $R /system/resource --username wrong --password wrong --json
 centrs retrieve 127.0.0.1:1 /system/resource --username $U --password $P --json
 ```
 
+The envelope still carries the resolved endpoint: `meta.via="rest-api"`,
+`meta.target.host`/`port`/`baseUrl`, and `meta.settings` with the source of
+each setting (#433).
+
 ### 14. REST timeout ceiling
 
 `--timeout 70000` against `--via rest-api` is rejected up front with
@@ -162,6 +181,41 @@ Call succeeds with a `cdb/password-not-needed` warning in `meta.warnings`.
 centrs retrieve $R /system/resource --cdb-file $CDB --cdb-password ignored --json
 ```
 
+### 16b. A refused transport still names what resolution found (#433)
+
+`$CLOSED` is a loopback port with nothing listening.
+
+```bash
+centrs retrieve $R /system/resource --cdb-file $CDB --port $CLOSED --json
+```
+
+Exit 1, `transport/connection-refused`. `meta.via="rest-api"`, and
+`meta.target` has the CDB record's host, `port=$CLOSED`, `recordIndex=0` and
+`source.kind="cdb"`. `meta.settings.port={kind:"cli",key:"port"}` and
+`meta.settings.username`/`password` have `kind:"cdb"`.
+`meta.operation.auth.passwordProvided=true`. The password itself appears
+nowhere. `meta.validation` has no `result`; its device stage is `skipped` with
+`reason: "not reached: transport/connection-refused"` (GH#435).
+
+### 16c. The gate passed, then a later step failed (GH#435)
+
+```bash
+centrs retrieve $R /system/resource --max-results 10 --username $U --password $P --json
+```
+
+Exit 1, `input/max-results-exceeded`. The read was validated and ran, and the
+answer was larger than the byte budget. `meta.validation.result="passed"`,
+because the gate did pass.
+
+### H1. `--host` stands in for `<target>` (#428)
+
+```bash
+centrs retrieve --host $R /system/identity --username $U --password $P --json
+```
+
+`ok: true`, with `data.name` the router's identity. The lone positional is the
+path, and there is no CDB lookup.
+
 ## Target selection (fan-out)
 
 These exercise the shared target-selection grammar
@@ -233,11 +287,13 @@ outputs round-trip to the same JS value.
 centrs retrieve $R /system/resource --format yaml --username $U --password $P
 ```
 
-## Out-of-scope (must surface as not-implemented)
+## Row filters
 
-### 18. --query
+### 18. --query with a regex
 
-Returns `validation/not-implemented` immediately.
+A regex has no RouterOS API query word, so it fails
+`input/unsupported-query` before anything is read. The full `--query`
+contract is in the **Query** section below.
 
 ```bash
 centrs retrieve $R /ip/address --query 'address~"192"' --username $U --password $P --json
@@ -245,10 +301,10 @@ centrs retrieve $R /ip/address --query 'address~"192"' --username $U --password
 
 ### 19. --filter
 
-Same handling as `--query`.
+`--filter` is `--query`: the router filters, and every returned row matches.
 
 ```bash
-centrs retrieve $R /ip/address --filter 'disabled=no' --username $U --password $P --json
+centrs retrieve $R /interface --filter 'type=ether' --username $U --password $P --json
 ```
 
 ## native-api (`--via native-api`)
@@ -336,6 +392,14 @@ centrs retrieve $A /system/resource --attribute bogus-attr --via native-api --po
 centrs retrieve $A /system/resource --via native-api --port $API_PORT --username wrong --password wrong
 ```
 
+### N12. Singleton `--attributes` projection (#377)
+
+```bash
+centrs retrieve $A /tool/romon --attributes enabled,id --via native-api --port $API_PORT --username $U --password $P
+```
+
+`data` is an object containing only `enabled` and `id`.
+
 ## quickchr targets (#134)
 
 `$NAME` is the machine name of a running quickchr-managed CHR
@@ -351,3 +415,376 @@ centrs retrieve --quickchr $NAME /system/resource --json
 Envelope: `ok: true`, `meta.via=rest-api` (normal default; quickchr does not
 change protocol selection), `meta.target.source.kind=provider`,
 `meta.target.identity=$NAME`, no `recordIndex` (the CDB was never consulted).
+
+## Follow (`--follow`, #396)
+
+Contract: [README → Follow](README.md#follow---follow). `$A`/`$API_PORT` as in
+the native-api section; `--via` is left unset because `--follow` infers
+native-api. Covered by `test/integration/retrieve-follow.test.ts`; the engine
+orderings a CHR cannot produce on demand (A1 replay, the sweep's
+changed-since-sent exclusion, overflow) are pinned in
+`test/unit/retrieve-follow.test.ts`.
+
+### FL1. Bootstrap: snapshot frames, one `synced`, a summary
+
+```bash
+centrs retrieve $A /ip/address --follow --duration 3s --port $API_PORT --username $U --password $P --json
+```
+
+Every line parses as an envelope. Frames before `synced` have
+`phase: "snapshot"` and `source: "print"`; exactly one `synced`; the last line
+is the summary with `stopReason: "duration-elapsed"`, `synced: true`,
+`changes: 0`. Every frame carries `meta.operation.stream.id`.
+
+### FL2. A live change, and `--count` that ignores the snapshot
+
+```bash
+centrs retrieve $A /ip/address --follow --count 1 --duration 15s --port $API_PORT --username $U --password $P --json
+```
+
+After `synced`, add an address. The follow ends with `stopReason:
+"count-reached"` after exactly one `live` `upsert` frame from `listen`, however
+many snapshot frames came first.
+
+### FL3. A removal RouterOS sends
+
+```bash
+centrs retrieve $A /ip/address --follow --sweep 0 --count 1 --duration 15s --port $API_PORT --username $U --password $P --json
+```
+
+After `synced`, remove an address that existed before the follow. One `live`
+`removed` frame, `source: "listen"`, `data: null`. `--sweep 0` keeps the sweep
+out of the race, and its `tip/follow-sweep-off` notice is the first line.
+
+### FL4. A removal RouterOS does not send (view menu → sweep)
+
+```bash
+centrs retrieve $A /interface/bridge --follow --sweep 1s --duration 15s --port $API_PORT --username $U --password $P --json
+```
+
+Create a bridge after `synced`, then remove it. Its `upsert` comes from
+`listen`; its removal comes from the sweep (`source: "sweep"`), because
+`/interface/<type>` never sends `.dead`.
+
+### FL5. `--attributes` projects `data`, identity stays in meta
+
+```bash
+centrs retrieve $A /ip/address --follow --attributes address --duration 3s --port $API_PORT --username $U --password $P --json
+```
+
+Every snapshot frame's `data` has only `address`; `meta.operation.stream.id`
+still names the row.
+
+### FL6. A menu RouterOS cannot follow
+
+```bash
+centrs retrieve $A /system/resource --follow --port $API_PORT --username $U --password $P --json
+```
+
+One envelope: `ok: false`, `validation/not-followable`, exit 1. No summary.
+
+### FL7. A pinned REST transport
+
+```bash
+centrs retrieve $R /ip/address --via rest-api --follow --username $U --password $P --json
+```
+
+One envelope: `ok: false`, `transport/capability-unsupported`. No polling
+fallback.
+
+### FL8. NDJSON is readable before the process exits; Ctrl-C ends it cleanly
+
+```bash
+centrs retrieve $A /ip/address --follow --format ndjson --port $API_PORT --username $U --password $P
+```
+
+Run as a subprocess. The first frame line parses while the process is still
+running; after `SIGINT` the last line is a successful summary with
+`stopReason: "interrupted"`, and the exit code is 0.
+
+### FL9. A1 and the sweep under churn (regression harness)
+
+```bash
+centrs retrieve $A /ip/firewall/address-list --follow --sweep 200ms --duration 8s --port $API_PORT --username $U --password $P --json
+```
+
+A second connection updates, adds and removes address-list rows while the
+follow bootstraps and runs. Applying every line in order must equal a fresh
+`print` taken after the churn settles: no stale value, no resurrected row, no
+row removed by a sweep while it still exists. #396 round 3 measured 0 errors
+over about 14.7k writes with this bootstrap; arrival-order merging failed the
+same harness.
+
+## Sample (`--sample`)
+
+Contract: [README → Sample](README.md#sample---sample). `$R` and `$A`/`$API_PORT`
+as above. Covered by `test/integration/retrieve-sample.test.ts`; cadence, the
+in-flight read at a stop, and the flag rules are pinned in
+`test/unit/retrieve-sample.test.ts`.
+
+### SA1. Three samples, one interval apart, on either transport
+
+```bash
+centrs retrieve $R /ip/address --sample 1s --count 3 --username $U --password $P --json
+centrs retrieve $A /ip/address --via native-api --sample 1s --count 3 --port $API_PORT --username $U --password $P --json
+```
+
+Each run prints three `sample` lines (`index` 1–3, `data` a row array) and a
+summary with `stopReason: "count-reached"`, `samples: 3`. Consecutive `at`
+values are at least one second apart. `meta.via` is the transport used.
+
+### SA2. Counters `listen` never reports
+
+```bash
+centrs retrieve $A /interface --via native-api --attributes name,rx-byte --sample 1s --count 3 --port $API_PORT --username $U --password $P --json
+```
+
+Every row has only `name` and `rx-byte`. `ether1`'s `rx-byte` in the third
+sample is higher than in the first, since the test's own API traffic arrives
+on `ether1`.
+
+### SA3. A singleton with one `--attribute`
+
+```bash
+centrs retrieve $R /system/resource --attribute uptime --sample 1s --count 2 --username $U --password $P --json
+```
+
+Each sample's `data` is the bare `uptime` string, and the two differ.
+
+### SA4. A removal is absence in the next sample
+
+```bash
+centrs retrieve $A /ip/firewall/address-list --via native-api --sample 500ms --count 2 --port $API_PORT --username $U --password $P --json
+```
+
+Add an address-list row before the run and remove it after the first sample.
+The first sample's rows include its `.id`; the second sample's do not.
+
+### SA5. `--follow` and `--sample` are exclusive
+
+```bash
+centrs retrieve $R /ip/address --sample 1s --follow --username $U --password $P --json
+```
+
+One envelope: `ok: false`, `usage/conflicting-flags`, exit 1. No summary.
+
+### SA6. NDJSON is readable before the process exits; Ctrl-C ends it cleanly
+
+```bash
+centrs retrieve $A /system/resource --via native-api --sample 1s --format ndjson --port $API_PORT --username $U --password $P
+```
+
+Run as a subprocess. The first `sample` line parses while the process is still
+running; after `SIGINT` the last line is a successful summary with
+`stopReason: "interrupted"`, and the exit code is 0.
+
+## Query (`--query`, #397)
+
+Contract: [README → Query](README.md#query---query). `$R` and `$A`/`$API_PORT`
+as above. Covered by `test/integration/retrieve-query.test.ts`, which seeds
+address-list, VLAN and firewall-filter rows; the grammar and compiled words are
+pinned in `test/unit/query.test.ts`.
+
+### QY1. The same rows as RouterOS's `find where`
+
+```bash
+centrs retrieve $R /ip/firewall/address-list --query 'comment and !disabled' --username $U --password $P --json
+centrs retrieve $A /interface/vlan --via native-api --query 'vlan-id>10 and vlan-id<100 or disabled' --port $API_PORT --username $U --password $P --json
+```
+
+For each of 58 expressions across three menus (equality, `!=`, numeric
+ordering, ordering on a property some rows lack, quoted values and their escapes, bare booleans, bare "is set" names, `and`/`or`
+precedence, parentheses, `!(…)`), the `.id`s returned over both transports
+equal the ids `:put [<menu> find where <expression>]` prints on the same
+router.
+
+### QY2. Where the query and the CLI differ, as documented
+
+```bash
+centrs retrieve $R /ip/firewall/filter --query 'dst-port=80' --username $U --password $P --json
+centrs retrieve $R /ip/firewall/address-list --query 'list=qa-397 and address>192.0.2.9' --username $U --password $P --json
+```
+
+The first returns the rule whose `dst-port` is `"80"`, although
+`find where dst-port=80` selects nothing on CHR 7.23.7/7.24.5 (the CLI reads
+`80` as a number). On CHR 7.25beta3, 7.25beta5, 7.25rc1 and 7.26beta1 the CLI
+also selects that rule. The test covers the same split for `protocol=tcp`
+and checks API query results over both transports. The second compares
+`address` as text, so `192.0.2.10` is not above `192.0.2.9`.
+
+### QY3. `--filter` and repeated `--query` are AND-ed
+
+```bash
+centrs retrieve $R /ip/firewall/address-list --filter list=qa-397 --query comment --query '!disabled' --attributes address --username $U --password $P --json
+```
+
+`data` is exactly `[{ "address": "192.0.2.9" }]`.
+
+### QY4. A regex fails before anything is sent
+
+```bash
+centrs retrieve $R /interface --query 'name~"^ether"' --username $U --password $P --json
+```
+
+`ok: false`, `input/unsupported-query`, exit 1.
+
+### QY5. A misspelled property fails validation
+
+```bash
+centrs retrieve $A /ip/firewall/address-list --via native-api --query 'lists=qa-397' --port $API_PORT --username $U --password $P --json
+```
+
+`validation/unknown-attribute`. Without the check RouterOS would answer with
+no rows and no error.
+
+### QY6. A singleton has no rows to filter
+
+```bash
+centrs retrieve $R /system/identity --query 'name=MikroTik' --username $U --password $P --json
+```
+
+`usage/conflicting-flags`.
+
+### QY7. `--sample` reads the filtered rows each time
+
+```bash
+centrs retrieve $R /ip/firewall/address-list --query 'list=qa-397 and disabled' --sample 500ms --count 2 --username $U --password $P --json
+```
+
+Both samples hold only the disabled `qa-397` row.
+
+## Filtered follow
+
+Covered by `test/integration/retrieve-filtered-follow.test.ts` (FQ1–FQ5).
+The harness seeds address-list rows and changes them while following, with
+validation enabled. `$A`/`$API_PORT` are the native-API target as above.
+
+### FQ1. Projection and both membership directions
+
+```bash
+centrs retrieve $A /ip/firewall/address-list --via native-api --port $API_PORT --username $U --password $P --follow --query 'list=fq1' --query 'comment=a and !disabled' --attributes address --count 2 --duration 10s --json
+```
+
+Initially only the matching row appears. Changing its comment out of the
+predicate emits a `removed` frame with `source: "membership"`; changing an
+excluded row into it emits an `upsert` with the same source. `data` contains
+only `address`, while identity remains in meta.
+
+### FQ2. Minimal deletion frames
+
+```bash
+centrs retrieve $A /ip/firewall/address-list --via native-api --port $API_PORT --username $U --password $P --follow --query 'list=fq1 and comment=a' --sweep 0 --count 1 --duration 10s --json
+```
+
+Deleting an excluded row emits nothing; deleting the held row emits one
+`removed` with `source: "listen"`. Predicate fields are absent from `.dead`.
+
+### FQ3. Silent predicate exit
+
+```bash
+centrs retrieve $A /ip/firewall/address-list --via native-api --port $API_PORT --username $U --password $P --follow --query 'list=fq3 and timeout>8s' --sweep 200ms --count 1 --duration 6s --json
+```
+
+The harness adds a row with a 10-second timeout. A sweep removes it from the
+selected set as its remaining timeout crosses 8 seconds, with
+`source: "membership"`; the row still exists in an unfiltered read.
+
+### FQ4. CLI alias and predicate validation
+
+```bash
+centrs retrieve $A /ip/firewall/address-list --port $API_PORT --username $U --password $P --follow --filter list=fq3 --attributes address --duration 500ms --json
+centrs retrieve $A /ip/firewall/address-list --port $API_PORT --username $U --password $P --follow --query lits=fq3 --json
+```
+
+The first emits projected snapshot rows and `synced`. The typo in the second
+fails `validation/unknown-attribute` before listen starts.
+
+### FQ5. Filtered bootstrap and live churn
+
+```bash
+centrs retrieve $A /ip/firewall/address-list --port $API_PORT --username $U --password $P --follow --query 'list=fq5 and comment=in' --attributes address --sweep 200ms --duration 6s --json
+```
+
+The harness changes membership during bootstrap and live operation, then
+deletes rows. Applying all frames yields exactly the ids and projected rows
+of a fresh filtered print after churn settles. Deterministic delayed-reply,
+delete, cancellation and sustained-write bootstrap orderings are anchored in
+`retrieve-follow.test.ts`; newer versions cannot starve `synced`, sweeps or
+live `--count`.
+
+## Readiness and conditions
+
+Covered by `test/integration/retrieve-wait.test.ts` (WT1–WT7) on disposable
+CHR, with validation enabled over REST and native-api. `$R` and
+`$A`/`$API_PORT` are the targets as above.
+
+### WT1. Readiness and already-true any-match
+
+```bash
+centrs retrieve $R /system/resource --wait 5s --username $U --password $P --json
+centrs retrieve $A /interface --via native-api --port $API_PORT --query name=ether1 --until '!disabled and mtu>=1500' --attributes name --wait 5s --username $U --password $P --json
+```
+
+Each succeeds with one attempt and one observation. The second returns only
+`[{ "name": "ether1" }]`, with `stopReason: "condition-met"`.
+
+### WT2. Wait for a row to match
+
+```bash
+centrs retrieve $R /ip/firewall/address-list --query list=wait-364 --until comment=ready --attributes address --wait 10s --sample 100ms --username $U --password $P --json
+```
+
+The harness adds a matching row after the wait starts. The waiter returns its
+projected address, with more than one completed observation. The same test
+runs over native-api.
+
+### WT3. Drop to zero and already empty
+
+```bash
+centrs retrieve $R /ip/firewall/address-list --query list=wait-364 --until-empty --wait 10s --sample 100ms --username $U --password $P --json
+```
+
+The harness removes the selected row after the wait starts; `data: []`,
+`stopReason: "condition-met"`. Repeating the wait on the now-empty selection
+succeeds on its first completed observation.
+
+### WT4. Condition expiry and fail-fast faults
+
+```bash
+centrs retrieve $R /interface --until name=missing --wait 500ms --sample 100ms --username $U --password $P --json
+centrs retrieve $R /interface --until unknown-property=yes --wait 5s --username $U --password $P --json
+```
+
+The first fails `wait/deadline-exceeded`, `stopReason: "deadline-elapsed"`.
+The second fails `validation/unknown-attribute` in one attempt. Incorrect
+credentials also fail in one attempt; singleton `--until-empty` is refused.
+
+### WT5. Real reboot readiness
+
+```bash
+centrs retrieve $R /system/resource --wait 60s --timeout 2s --sample 500ms --username $U --password $P --json
+```
+
+The harness reboots the CHR and starts this call while its services are down.
+The waiter succeeds with multiple attempts and exactly one completed data
+observation, without an external retry loop.
+
+### WT6. OSPF reaches Full
+
+```bash
+centrs retrieve $A /routing/ospf/neighbor --via native-api --port $API_PORT --until state=Full --wait 40s --sample 200ms --username $U --password $P --json
+```
+
+Two disposable CHRs share a point-to-point Ethernet link. After configuring
+OSPF, the waiter returns a neighbor whose state is `Full`. A REST wait on
+the established adjacency succeeds on its initial observation.
+
+### WT7. CLI failure is one final envelope
+
+```bash
+centrs retrieve $R /interface --until name=missing --wait 500ms --username $U --password $P --json
+```
+
+One envelope goes to stdout, with `stopReason: "deadline-elapsed"`; exit 1.
+No intermediate sample frames are printed. Unit anchors cover slow validation,
+unfinished reads, cancellation and narrow retry classification.

package/commands/terminal/README.md

@@ -6,10 +6,13 @@ Open an interactive RouterOS console.
 flag (`--group` / `--where` / `--all` / `--default` / `--concurrency`) is rejected
 with `usage/fanout-not-supported` — open a console to one router at a time; use
 `execute` / `api` for multi-target commands. See `docs/CONSTITUTION.md`
-(Target selection grammar).
+(Target selection grammar). With no `<router>`, the `--host` **flag** is the
+target (`terminal --host 192.0.2.10` opens an ssh console; no CDB lookup).
+`CENTRS_HOST` never stands in for `<router>`. mac-telnet still needs a MAC
+`<router>`, since its `--host` is only the UDP delivery endpoint.
 
 Status: `terminal / mac-telnet` **and** `terminal / ssh` are both **`CHR-passed`**
-(see `docs/MATRIX.md` and `examples.md` T1–T3 / TS1–TS2). The two transports take
+(see `docs/MATRIX.md` and `examples.md` T1–T3 / TS1–TS2, TS4). The two transports take
 different paths: **mac-telnet** is the in-process raw passthrough over
 `MacTelnetConsole.attachInteractive`; **ssh** execs the host `ssh` with inherited
 stdio (RouterOS grants no PTY, but `ssh user@host` opens the console and the OS
@@ -73,6 +76,12 @@ CLI/API. When no key is set, terminal delegates identity selection to system
 `ssh` config and the SSH agent; `--ssh-key` is an explicit override and must not
 silently merge with a conflicting CDB/env key.
 
+A selected key from any settings source adds `IdentitiesOnly=yes` alongside
+`-i`, preventing unrelated agent identities from authenticating instead. The
+agent can still sign for the selected key. OpenSSH continues to honor explicit
+`IdentityFile` entries in its config; this does not isolate the user's SSH
+configuration. The same selection applies to execute and SFTP.
+
 Unlike the batch sftp/execute clients, the **interactive** `terminal / ssh` argv
 omits `BatchMode=yes` (`interactive: true` in `sshCommonOptions`), so the host
 `ssh` can prompt on the inherited TTY for an encrypted key's passphrase or a
@@ -86,8 +95,9 @@ longer open for the file path: **host-key verification** rides the unified
 a changed key → `transport/host-key-mismatch`; `--insecure` →
 `StrictHostKeyChecking=no` — see `docs/CONSTITUTION.md`, Transport trust);
 **agent vs explicit-key** interplay and **algorithm negotiation** are delegated to
-the host OpenSSH (`-i <ssh-key>` when set, else the agent / `~/.ssh/config`). The
-MAC-on-file-but-SSH-pinned case is settled (see *MAC target over SSH* above):
+the host OpenSSH (`-i <ssh-key> -o IdentitiesOnly=yes` when set, else the agent /
+`~/.ssh/config`). The MAC-on-file-but-SSH-pinned case is settled (see *MAC target
+over SSH* above):
 centrs resolves a MAC for `--via ssh` CDB-first, then tips `--via mac-telnet` —
 it does **not** silently fall back to L2 (constitution: a pinned `--via` is never
 swapped). The no-pseudo-tty console reader is likewise resolved — a CHR spike

package/commands/terminal/examples.md

@@ -91,9 +91,10 @@ on the argv.
 
 Harness inputs (from `test/integration/terminal-ssh.test.ts`): `$SSH_PORT` is
 `chr.sshPort` (passed via `--port`), and `$KEY` is the ephemeral private key the
-test mints with `ssh-keygen -f <tmp>/id` and passes via `--ssh-key`. **TS1–TS2 are
-the CHR-tested set** (green via `bun run test:integration`, CHR 7.23.1) — the
-matrix's `CHR-passed` claim rests on them. **TS3 is the interactive hand-verified
+test mints with `ssh-keygen -f <tmp>/id` and passes via `--ssh-key`. **TS1, TS2,
+TS4 and TS5 are the CHR-tested set**. The matrix's `CHR-passed` claim rests on
+TS1, TS2 and TS4. TS1, TS2 and TS5 run in `test/integration/terminal-ssh.test.ts`; TS4 runs in the shared
+`test/integration/ssh-identity.test.ts`. **TS3 is the interactive hand-verified
 analog of T4** (a piped subprocess stdin cannot be a TTY), not in CI.
 
 ### TS1. Run a command over an SSH terminal (batch relay)
@@ -130,6 +131,24 @@ RouterOS console to the user; `/quit` (or `Ctrl-D`) ends the session. RouterOS's
 no-PTY limitation applies (e.g. multi-line brace blocks are not supported over
 SSH — see the SSH page); single-line commands work.
 
+### TS4. A rejected selected key cannot authenticate through another agent identity
+
+The shared [SSH identity example S5](../execute/examples.md#s5-an-explicit-rejected-key-cannot-fall-back-to-an-unrelated-agent-key)
+checks the real terminal relay against CHR with a private agent and prompts
+disabled. The rejected key preserves OpenSSH's nonzero exit and
+`Permission denied`; selecting the trusted key or leaving the key unset
+returns the device identity. Covered by `test/integration/ssh-identity.test.ts`.
+
+### TS5. `--host` stands in for `<router>` (#428)
+
+```bash
+printf '/system/identity/print\n/quit\n' | centrs terminal --host 127.0.0.1 --port $SSH_PORT --username $U --ssh-key $KEY --insecure
+```
+
+There's no `<router>` and no `--via`. The host-only target selects ssh, as a
+host `<router>` does, with no CDB lookup. stdout contains the device identity,
+checked as in TS1.
+
 ## MAC target over `--via ssh` resolution (behavior note — not a numbered CHR example)
 
 This path resolves a MAC to an IP and, on the unresolved / no-opt-in branch,