@tikoci/centrs 0.1.0

package/commands/retrieve/examples.md

@@ -0,0 +1,306 @@
+# retrieve — examples
+
+Each numbered example is an executable spec. The integration test under
+`test/integration/rest-retrieve.test.ts` runs every example against a CHR
+booted by `@tikoci/quickchr`. If a line here is not exercised by a test, the
+test file is wrong; if a line passes only with `validate=false`, the
+**implementation** is wrong (see `docs/CONSTITUTION.md`).
+
+`$R` is `<host>:<rest-port>` resolved by quickchr.
+`$U` / `$P` are CHR credentials provided by the test harness.
+Examples that assert envelope fields pass `--json`; plain text is the default
+for human CLI use.
+
+## Singletons (read a single record)
+
+### 1. /system/resource
+
+Must succeed with `validate=true` (default).
+
+```bash
+centrs retrieve $R /system/resource --username $U --password $P --json
+```
+
+Envelope: `ok: true`, `data` is an object, `meta.via=rest-api`,
+`meta.validation.source=/console/inspect`.
+
+### 2. /system/identity
+
+Same shape, different menu.
+
+```bash
+centrs retrieve $R /system/identity --username $U --password $P --json
+```
+
+## Lists (read an array of rows)
+
+### 3. /ip/address
+
+Empty or populated, both must succeed with `validate=true`.
+
+```bash
+centrs retrieve $R /ip/address --username $U --password $P --json
+```
+
+Envelope: `ok: true`, `data` is an array.
+
+### 4. /interface
+
+List of interfaces present on a default CHR.
+
+```bash
+centrs retrieve $R /interface --username $U --password $P --json
+```
+
+## Attribute projection
+
+### 5. Single --attribute on a singleton
+
+```bash
+centrs retrieve $R /system/resource --attribute uptime --username $U --password $P --json
+```
+
+Envelope: `data` is the bare value, not an object.
+
+### 6. Comma-list --attributes on a list
+
+```bash
+centrs retrieve $R /interface --attributes name,type --username $U --password $P --json
+```
+
+Envelope: `data` is an array of objects each containing only `name` and `type`.
+
+### 7. --all-attributes (RouterOS details=true)
+
+```bash
+centrs retrieve $R /system/resource --all-attributes --username $U --password $P --json
+```
+
+### 8. Conflict: --attribute + --all-attributes
+
+Rejected before any network call, with `usage/conflicting-flags`.
+
+```bash
+centrs retrieve $R /system/resource --attribute uptime --all-attributes --username $U --password $P --json
+```
+
+## --list-attributes
+
+### 9. List attributes for a path
+
+Without running `print`/`get`.
+
+```bash
+centrs retrieve $R /system/resource --list-attributes --username $U --password $P --json
+```
+
+Envelope: `data` is `string[]`. No `meta.timing.request` (no transport call).
+
+## Validation surface
+
+### 10. Unknown path
+
+Must fail with `validation/unknown-path` (not `routeros/unsupported-path`
+from a server round-trip; the validator catches it first). The error
+envelope must include suggested alternatives from `/console/inspect` when
+available.
+
+```bash
+centrs retrieve $R /not/a/real/path --username $U --password $P --json
+```
+
+### 11. Unknown attribute
+
+`validation/unknown-attribute` with suggestions.
+
+```bash
+centrs retrieve $R /system/resource --attribute bogus --username $U --password $P --json
+```
+
+## Transport / error contract
+
+### 12. Bad credentials
+
+`transport/auth-failed`, `details_url` populated.
+
+```bash
+centrs retrieve $R /system/resource --username wrong --password wrong --json
+```
+
+### 13. Unreachable host
+
+`transport/connection-refused` (not the more general `transport/network`).
+
+```bash
+centrs retrieve 127.0.0.1:1 /system/resource --username $U --password $P --json
+```
+
+### 14. REST timeout ceiling
+
+`--timeout 70000` against `--via rest-api` is rejected up front with
+`usage/timeout-out-of-range` (REST hard cap is 60s).
+
+```bash
+centrs retrieve $R /system/resource --via rest-api --timeout 70000 --username $U --password $P --json
+```
+
+## CDB resolution
+
+### 15. Name resolution
+
+`<router>` matches a CDB-stored target; user/password are filled from CDB.
+
+```bash
+centrs retrieve $R /system/resource --cdb-file $CDB --json
+```
+
+### 16. Unused --cdb-password on an unencrypted CDB
+
+Call succeeds with a `cdb/password-not-needed` warning in `meta.warnings`.
+
+```bash
+centrs retrieve $R /system/resource --cdb-file $CDB --cdb-password ignored --json
+```
+
+## Group fanout
+
+These are exercised by `test/integration/fanout-retrieve.test.ts` when CHR
+integration is enabled.
+
+### F1. Group fanout with one inner success and one inner failure
+
+`$CDB` contains two records in group `fanout-chr`: record 0 is the live CHR and
+record 1 is an unreachable REST URL.
+
+```bash
+centrs retrieve --group fanout-chr /system/resource --cdb-file $CDB --json
+```
+
+Outer envelope: `ok: true`, `data.summary = { total: 2, ok: 1, failed: 1 }`,
+`data.targets` is ordered by CDB `recordIndex`, and `meta.operation.kind` is
+`fanout`. The unreachable target is an inner `ok: false` envelope with
+`transport/connection-refused`.
+
+### F2. Empty / unknown group
+
+```bash
+centrs retrieve --group no-such-group /system/resource --cdb-file $CDB --json
+```
+
+Envelope: `ok: true`, `data.summary = { total: 0, ok: 0, failed: 0 }`,
+`data.targets = []`, and warnings include `cdb/empty-group`.
+
+## Format
+
+### 17. --format yaml
+
+`text` is the default; `--json` (or `--format json`) emits the structured
+envelope, and `--format yaml` renders the same envelope. The two structured
+outputs round-trip to the same JS value.
+
+```bash
+centrs retrieve $R /system/resource --format yaml --username $U --password $P
+```
+
+## Out-of-scope (must surface as not-implemented)
+
+### 18. --query
+
+Returns `validation/not-implemented` immediately.
+
+```bash
+centrs retrieve $R /ip/address --query 'address~"192"' --username $U --password $P --json
+```
+
+### 19. --filter
+
+Same handling as `--query`.
+
+```bash
+centrs retrieve $R /ip/address --filter 'disabled=no' --username $U --password $P --json
+```
+
+## native-api (`--via native-api`)
+
+The same retrieve contract over the RouterOS binary API (TCP 8728, or TLS 8729
+when `--port 8729`). `$A` is `<host>` and `--port` is the resolved api port
+from quickchr (`chr.ports.api`). Validation still runs through
+`/console/inspect`, issued as a native-API command rather than over REST.
+
+These are exercised by `test/integration/native-api-retrieve.test.ts`.
+
+One transport-specific note: native-API attribute values are **strings**
+(the binary API does not carry JSON scalar types), so `data` scalars are
+strings even where the REST path returns a number/boolean. The envelope shape
+(object vs array vs bare value, projection, validation source) is identical.
+
+### N1. Singleton over native-api
+
+```bash
+centrs retrieve $A /system/resource --via native-api --port $API_PORT --username $U --password $P
+```
+
+Envelope: `ok: true`, `data` is an object, `meta.via=native-api`,
+`meta.validation.source` contains `/console/inspect`.
+
+### N2. Second singleton
+
+```bash
+centrs retrieve $A /system/identity --via native-api --port $API_PORT --username $U --password $P
+```
+
+### N3. List menu → array
+
+```bash
+centrs retrieve $A /interface --via native-api --port $API_PORT --username $U --password $P
+```
+
+### N4. Possibly-empty list
+
+```bash
+centrs retrieve $A /ip/address --via native-api --port $API_PORT --username $U --password $P
+```
+
+### N5. Singleton single `--attribute` → bare value
+
+```bash
+centrs retrieve $A /system/resource --attribute uptime --via native-api --port $API_PORT --username $U --password $P
+```
+
+### N6. List `--attributes` projection
+
+```bash
+centrs retrieve $A /interface --attributes name,type --via native-api --port $API_PORT --username $U --password $P
+```
+
+`data` is an array of objects each containing only `name` and `type`.
+
+### N7. `--all-attributes` (native `print detail`)
+
+```bash
+centrs retrieve $A /system/resource --all-attributes --via native-api --port $API_PORT --username $U --password $P
+```
+
+### N8. `--list-attributes` (inspect only, no data call)
+
+```bash
+centrs retrieve $A /system/resource --list-attributes --via native-api --port $API_PORT --username $U --password $P
+```
+
+### N9. Unknown path → `validation/unknown-path`
+
+```bash
+centrs retrieve $A /not/a/real/path --via native-api --port $API_PORT --username $U --password $P
+```
+
+### N10. Unknown attribute → `validation/unknown-attribute`
+
+```bash
+centrs retrieve $A /system/resource --attribute bogus-attr --via native-api --port $API_PORT --username $U --password $P
+```
+
+### N11. Bad credentials → `transport/auth-failed`
+
+```bash
+centrs retrieve $A /system/resource --via native-api --port $API_PORT --username wrong --password wrong
+```

package/commands/settings/README.md

@@ -0,0 +1,69 @@
+# settings
+
+Read and write centrs's own settings — the global `centrs.env` preferences and
+the `__default__` fallback record — and run first-time setup.
+
+Status: `designed`. This file describes intent and flags; no implementation yet.
+See `docs/MATRIX.md` for the cell state. `settings` is the front-end to the
+settings the constitution defines (Settings precedence: the `centrs.env` config
+file at tier 2; `__default__` fallback creds): it does not invent new settings,
+only edits the ones already specified.
+
+## Why
+
+centrs deliberately has no store of its own for *inventory* — that is the CDB.
+But it does have **global, centrs-only preferences** (default discovery window,
+default `--format`, concurrency, …) that have no per-device home, and a
+**`__default__` fallback record** for credentials. Today both are hand-edited
+(`centrs.env`, or `devices add __default__`). `settings` makes that ergonomic and
+is where onboarding flows steer the user.
+
+## Surface
+
+```text
+centrs settings                                # interactive setup (TTY)
+centrs settings print [<attr>]                 # show resolved settings + sources
+centrs settings get <attr>                     # read one value
+centrs settings set <attr> <value>             # write one value to centrs.env
+centrs settings reset [<attr>]                 # clear one/all back to built-in default
+```
+
+- **Interactive (`centrs settings`, TTY):** prompts (clack-style, like
+  `@tikoci/quickchr`) to optionally collect a default `user`/`password` (written
+  to the `__default__` record so a fresh CDB "starts useful"), confirm/update
+  global preferences, and report where the `centrs.env` lives. Non-TTY runs of
+  bare `settings` print the resolved settings instead of prompting.
+- **Non-interactive (`set`/`get`/`reset`/`print`):** scriptable edits to
+  `centrs.env`. `print` shows each resolved setting with its winning source
+  (`default` / `centrs.env` / `env` / `cli`), mirroring `meta.settings`.
+- Credentials collected for `__default__` route through the `devices` write
+  layer (the only CDB writer) and are redacted from any structured output.
+
+## Boundaries
+
+- `settings` edits **global** preferences (`centrs.env`) and the **`__default__`**
+  record only. Per-device settings stay in `devices` (CDB comment-kv).
+- It writes no RouterOS device; it is local-only, like `devices`.
+- `--skip-env-file` / `CENTRS_SKIP_ENV_FILE=1` makes a run ignore `centrs.env`
+  (tests, dev-agent usage); `settings` still reports what *would* apply.
+
+## Onboarding
+
+`settings` is the steering target for "centrs starts useful": an empty CDB plus a
+first `retrieve`/`devices` should tip toward `centrs settings` (collect default
+creds) and `centrs devices discover` (populate the registry). See
+`commands/discover/README.md` (save-implied `devices discover`) and
+`docs/CONSTITUTION.md` (Default-device record).
+
+## Settings keys
+
+`centrs.env` holds **canonical `CENTRS_*=value` lines** — identical to the
+environment-variable spellings, prefix included (`CENTRS_FORMAT=json`,
+`CENTRS_DISCOVER_TIMEOUT=15s`, `CENTRS_CONCURRENCY=8`). One vocabulary across
+file / env / CLI: the file *is* "just default env vars," so `set -a && source
+centrs.env` works and the loader applies each key as a default **only when the
+same `CENTRS_*` is not already in the process environment** (it never injects
+into `process.env`). `settings set <attr>` accepts the setting name with or
+without the prefix for convenience but always writes the canonical prefixed
+line. It is **user-global only** — the single XDG path above; there is no
+project-local config file discovered from the working directory.

package/commands/stream/README.md

@@ -0,0 +1,70 @@
+# stream
+
+Follow live RouterOS output — `print follow`, `monitor`-style commands, and
+sniffer feeds — as a stream of envelopes.
+
+Status: `designed`. This file describes intent and flags; no implementation yet.
+See `docs/MATRIX.md` for the cell states. `stream` lands with a transport that
+can hold an open read (native-api first, then ssh); it is **not** a REST cell.
+
+## Why a separate verb
+
+`stream` exists because open-ended follow is a different I/O contract than a
+one-shot read, and conflating it into `retrieve` would force every retrieve
+consumer to handle "maybe this is a stream." A caller that picks `stream` knows
+it is getting a sequence of frames, not a single envelope. Bounded, finite
+captures stay on `retrieve` (`--once`); interactive PTY stays on `terminal`
+(constitution: protocol selection).
+
+## Intent
+
+- **Read-only**, validated like `retrieve` (path-shaped commands gate through
+  `/console/inspect`). `stream` never writes.
+- Wraps RouterOS follow semantics: `once`, `follow`, `duration=`,
+  `freeze-frame-interval=`. Targets are the `monitor`/`print follow`/sniffer
+  family of menus.
+- **Transport:** true follow cannot ride REST (RouterOS REST has a 60s hard
+  cap), so `stream` is **native-api / ssh-first**. `--via rest-api` is
+  bounded-or-rejected, never a silent open-ended poll.
+- Not a fan-out surface in single-session mode: a single `stream` rejects N>1
+  targets with `usage/fanout-not-supported` (constitution: target selection).
+
+## Output contract (NDJSON stream of envelopes)
+
+- Each frame is **one envelope** (`{ ok, data?, warnings?, error?, meta }`),
+  emitted as one NDJSON line under `--format json`. Text mode renders
+  human-readable frames.
+- The stream is terminated by a final **summary envelope**: frame count,
+  duration, and stop reason (`duration-elapsed`, `interrupted`, `eof`,
+  `transport-error`).
+- A mid-stream RouterOS or transport error is itself a frame with `ok: false`;
+  the **process exit code** reflects whether the stream *started* cleanly, not
+  whether every frame was `ok`.
+- `--duration` / `--count` bound an otherwise open-ended follow; Ctrl-C stops it
+  and still emits the summary envelope.
+
+## Flags (planned)
+
+| Flag | Behavior |
+| ---- | -------- |
+| `--via <protocol>` | Pin transport (`native-api` or `ssh`). REST is bounded-or-rejected. |
+| `--duration <dur>` | Stop after this wall-clock window (maps to RouterOS `duration=`). |
+| `--count <n>` | Stop after N frames. |
+| `--freeze-frame-interval <dur>` | RouterOS `freeze-frame-interval=` passthrough. |
+| `--format <text\|json>` | `json` is NDJSON (one envelope per line); `text` is human frames. |
+
+`tail` is a log-scoped alias: `centrs tail <router> /log` ≈ `tail -f` over
+`/log print follow`.
+
+## Open questions
+
+- Whether `stream` over ssh shells out to the RouterOS CLI follow or rides a
+  structured channel; settle during the SSH transport work.
+- Backpressure / max-buffered-frames policy for a fast producer.
+
+Sequencing (decided): do **not** start `stream` until (1) a native-api
+*streaming* spike confirms the reader is solid as a long-lived follow channel
+(not just request/response), and (2) `retrieve` is further along and re-reviewed
+for UX — `stream` should inherit a settled retrieve shape, not race it. The
+native-api streaming reader already exists (`src/protocols/native-api.ts`) and is
+the first follow consumer.

package/commands/terminal/README.md

@@ -0,0 +1,177 @@
+# terminal
+
+Open an interactive RouterOS console.
+
+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
+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
+relays the already-clean stream — no screen emulation; a host target defaults to
+ssh, a MAC target to mac-telnet). The mac-telnet path is described below;
+`src/terminal.ts` is the raw passthrough over `MacTelnetConsole.attachInteractive`,
+driven through an injectable `TerminalIo` (real stdin/stdout/`SIGWINCH` in
+`src/cli/terminal.ts`). Two input modes by whether stdin is a TTY: interactive
+(raw-mode keystrokes, real size) and batch (pipe a command, close on EOF after an
+output drain). The pipe integration test does not exercise raw-mode/real-TTY-size
+(a piped subprocess stdin is not a TTY); a full-TTY test would need a PTY and is
+deferred.
+
+`terminal` is also the documentation home for SSH as a centrs transport. **Re-scoped
+(decided with the user): SSH lands transfer-first, not as one monolithic unit.**
+The SSH transport *base* shipped as the **SFTP transfer client** (`transfer / ssh`,
+`src/protocols/sftp.ts` over the host OpenSSH `sftp` subsystem); the `ssh-key` and
+`insecure` settings landed **with** it (so no setting is half-wired without a
+working transport — the rule still holds). `execute / ssh` and `terminal / ssh`
+then followed and are both `CHR-passed`. **A CHR spike corrected the earlier "no
+exec channel, needs an interactive-shell reader" framing:** RouterOS's SSH server
+has **no pseudo-tty**, but a single-line `ssh user@host "<command>"` runs on the
+console and returns clean output — so `execute / ssh` is a per-command batch client
+and `terminal / ssh` is a thin inherited-stdio exec of `ssh`. Neither needed a
+`MacTelnetConsole`-style screen-emulating reader. The one no-PTY limitation is the
+device's, not centrs's: multi-line brace blocks (`{ … }`) do not work over
+`terminal / ssh` — reach for `mac-telnet` when you need them.
+
+## Intent
+
+- `ssh` is the default. It honors system `ssh` config and the user's SSH agent;
+  `--ssh-key` overrides with an explicit private key path. CDB metadata may carry
+  the path to a per-router private key.
+- `mac-telnet` is the right transport when `<router>` is a MAC address, or
+  when SSH is unreachable but a MAC is on file (Layer-2 emergency access).
+- REST and native API have no terminal capability; `--via rest-api` for
+  `terminal` must error with `transport/capability-unsupported`.
+- RoMON and WinBox Terminal are execute protocol surfaces in centrs, not
+  terminal routes, unless future matrix cells explicitly add terminal support.
+
+## MAC target over SSH (`--resolve`)
+
+A MAC `<router>` defaults to `mac-telnet`, which addresses the device by MAC —
+no IP, no resolution. Pinning `--via ssh` asks for the IP-level console, so the
+MAC must first resolve to an IP. That resolution follows the shared `--resolve`
+policy (CDB record → `--resolve arp` host-ARP opt-in → error; never a silent ARP
+or transport swap) — see `docs/CONSTITUTION.md`, *Target selection grammar* and
+*Protocol selection*.
+
+Terminal-specific: when no IP resolves, the `target/mac-unresolved` (and
+`target/mac-not-in-arp`) tip **leads with `--via mac-telnet`**, since for terminal
+reaching the device over L2 needs no IP at all — it is the first thing to try.
+`--resolve` is a no-op for the `mac-telnet` default (the MAC is the target).
+
+## SSH key selection
+
+Signed off (settings names): terminal uses the same `sshKey` setting as
+`execute`: `--ssh-key <path>`, `CENTRS_SSH_KEY`, and CDB comment-kv
+`ssh-key=<path>`. Precedence is defaults → config → CDB comment-kv → env →
+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.
+
+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
+password. centrs does not forward `--password` to ssh — OpenSSH accepts no
+password on the argv — so password auth is satisfied by that interactive prompt,
+not by the centrs-resolved credential.
+
+Resolved by the sftp transfer client (`src/protocols/sftp.ts`), so they are no
+longer open for the file path: **host-key verification** rides the unified
+`--insecure` knob (default `StrictHostKeyChecking=accept-new` trust-on-first-use;
+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):
+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
+proved `ssh user@host` opens a clean console with no screen emulation.
+
+The setting stores a key path only. Private key material, passphrases, and agent
+contents are always sensitive and belong in `error.redactable_fields` if an
+error carries them; the selected key path may appear in `meta.settings.sshKey`
+with its source unless the caller marks paths sensitive.
+
+## RouterOS SSH surface (device-side option alignment)
+
+What RouterOS's SSH server exposes (`/ip/ssh`, grounded on the
+[SSH](https://help.mikrotik.com/docs/spaces/ROS/pages/132350014/SSH) and
+[User](https://help.mikrotik.com/docs/spaces/ROS/pages/8978504/User) pages,
+RouterOS 7.x) and how the centrs client (host OpenSSH) lines up — so there are no
+gaps between what the device offers and what centrs can negotiate:
+
+| RouterOS `/ip/ssh` | Values (default) | How centrs aligns |
+| ------------------ | ---------------- | ----------------- |
+| `host-key-type` | `ed25519` \| `rsa` (**rsa**) | Host OpenSSH accepts both; the default device host key is RSA, so the client must offer `rsa-sha2-256/512` and `ssh-ed25519`. TOFU pins whichever the device presents. |
+| `strong-crypto` | `yes` \| `no` (**no**) | `yes` disables ssh-rsa/SHA1, null ciphers, and MD5, and uses sha256 MACs + a 2048-bit DH prime. OpenSSH already prefers `rsa-sha2-*` / curve25519, so a strong-crypto device negotiates cleanly with no client change. |
+| `ciphers` | `3des-cbc`\|`aes-cbc`\|`aes-ctr`\|`aes-gcm`\|`auto`\|`null` (**auto**) | Per-cipher control added ~7.17. OpenSSH's default cipher set covers `aes-ctr`/`aes-gcm`; `null` (no encryption) is never offered by the client. |
+| `password-authentication` | `yes-if-no-key` \| `yes` \| `no` (**yes-if-no-key**) | The default refuses password login once a user has an imported SSH key, so centrs's normal path is key auth (`--ssh-key` / agent). No password is ever placed on the `sftp` argv. |
+| `publickey-authentication-options` | `none`\|`touch-required`\|`verify-required` (**none**) | FIDO touch/verify is handled by the host ssh-agent when the key is a FIDO key; transparent to centrs. |
+| `forwarding-enabled` | `both`\|`local`\|`remote`\|`no` (**no**) | centrs does not use SSH forwarding; no dependency. |
+| — (subsystem) | SFTP subsystem | The reliable **file** channel (no pseudo-tty; a single-line `ssh host "cmd"` exec runs, but it's for `execute`, not files); `transfer --via sftp` speaks it. scp would ride the same subsystem on modern OpenSSH. **CHR-confirmed (7.23.1):** `put`/`get`/`ls`/`mkdir`/`rm` all work over the subsystem. |
+| `/user` group policy | `ftp` (+ `ssh`, `read`/`write`) | SFTP file access needs the user group's `ftp` policy. **CHR-confirmed:** the `full`-group admin (which includes `ftp`) authenticates and transfers; a restricted user must be granted `ftp`. |
+
+**CHR finding (7.23.1):** RouterOS's sftp `ls -l` does **not** report a reliable
+byte size (the long-name size column is unpopulated / server-format-specific). So
+centrs's sftp client treats `ls` as an existence + name probe only, and
+`transfer --verify size` over sftp trusts the **SFTP transfer guarantee** (a
+partial `put`/`get` errors) rather than re-reading a size. REST/native keep their
+JSON `/file` size cross-check. See `src/protocols/sftp.ts` (`parseLsOutput`) and
+`src/transfer.ts` (`SftpFileBackend.findFile`).
+
+These are device facts the host OpenSSH negotiates for us; the alignment table is
+the audit trail that the centrs file path has no hole versus what RouterOS offers.
+
+## mac-telnet L2 validation
+
+Decided (2026-06-06): terminal/mac-telnet uses the same `@tikoci/quickchr`
+host-side L2 capture path as execute/mac-telnet — a host TCP server with the CHR
+on a `socket-connect` NIC (QEMU streams guest frames length-prefixed; a frame
+written back injects L2). Loopback-only, cross-platform, no root. Prefer
+`socket-connect` over `socket-mcast` (macOS-broken — `SO_REUSEPORT`). That
+harness is wired and `execute / mac-telnet` is **`CHR-passed`** over it
+(`test/integration/mac-telnet-console.test.ts`): MTWEI login, the console reader,
+clean command output, writes, and the `:parse` validation gate all work end to
+end. The bridge also relays UDP both ways (`udpPort`), so the production UDP
+transport is exercised, not just the in-process callbacks. See
+`commands/execute/README.md` (mac-telnet L2 validation) for the console wiring and
+auth findings (MTWEI required, MD5 refused, `END_AUTH` ≠ success).
+
+The unresolved-MAC default remains load-bearing: a MAC target chooses
+mac-telnet for terminal unless an IP-level resolution path is explicitly
+requested. Covered with resolver/selection tests plus packet/session coverage in
+`test/unit/mac-telnet.test.ts` and EC-SRP coverage in `test/unit/mtwei.test.ts`.
+
+## Interactive-console work (advances terminal/mac-telnet to CHR-passed)
+
+The console reader landed with `execute / mac-telnet` (`CHR-passed`): it answers
+the login terminal-size probe, auto-clears the first-login license, syncs on the
+prompt, and emulates the CR/LF screen — grounded on CHR 7.23.1 (the login probe
+is actually a multi-step ANSI cursor probe; `ESC[6n` DSR is the operative query,
+answered with `ESC[rows;colsR`). `terminal / mac-telnet` reuses that reader; what
+it adds on top is **interactive relay**, not protocol work:
+
+- **PTY relay**: wire local stdin → `session.sendInput` and console output →
+  stdout in raw mode, instead of the `run(cli)` capture path `execute` uses.
+- **Real terminal size**: report the actual PTY rows/cols to the probe (and on
+  `SIGWINCH`), where `execute` reports an oversized screen to avoid paging/wrap.
+- **Idle keepalive + retransmit (already landed):** `MacTelnetSession.tick(now)`
+  (driven by `MacTelnetConsole` on a ~200ms interval) sends an empty-ACK keepalive
+  after ~8s idle and retransmits the last unacked frame on the reference backoff
+  schedule. So a held-open `terminal` is already kept alive; the relay just needs
+  to keep `tick` running (it does, via the console reader).
+- **~10s prime stall (optional polish):** every mac-telnet login waits ~10s for
+  terminal negotiation before the prompt; answering the DSR sets the width but
+  does not remove the stall. A cursor-tracking emulator (track row/col, answer
+  each `ESC[6n` with the real clamped position) would likely kill it. Latency
+  only — not a blocker.
+
+Protocol facts to honor: **MTWEI does not encrypt the terminal stream** — treat
+it as management-plane traffic on a trusted L2 segment.
+
+## Open questions
+
+- How to surface keystroke recording / replay for tests.
+
+The transport, auth, console reader, and data path are all grounded; only the
+interactive-relay layer above remains for terminal/mac-telnet.