Three more arguments that were reported as the radio's fault

`4` promises a caller that the node answered and a retry is worth
trying. An unknown admin node, an unknown courier contact and an `--at`
that is not a clock time are all decided before a word goes over the
air, so a caller retrying on `4` would retransmit nothing, forever.
`tx-optimize` had already answered the identical question the identical
way for a missing password; these had not caught up.

A refused admin login stays `4`. The node was reached and answered no,
the password may simply have changed, and that is exactly the case a
retry exists for — the line is whether anything was transmitted, not
whether the command worked.

The manual documented the old behaviour and called the inconsistency
out; it now documents the rule instead.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Jean-Pierre MartineauandClaude Opus 5 committed 2026-09-08 05:03:17 -04:00
1 parent c920f50584
commit b76a93808f
4 files changed
+49 -10

No files matched your search

+6 -4
View File
@@ -1186,8 +1186,9 @@ of `delivered`, `no ack`, `gave up`, `unknown contact`, `busy`, `gone` — kept
spaces and all, so the two faces say the same word.
`list` returns `5` on an empty outbox; `cancel` and `clear` return `5` when there was
nothing to act on. A contact the device does not know is a **device error** (`4`), not a
usage one.
nothing to act on. A contact the device does not know, a contact with no key to address,
and an `--at` that is not a clock time are all **usage errors** (`2`): the argument is
wrong, nothing was queued, and nothing went out over the air.
---
@@ -1365,8 +1366,9 @@ landed), but there is nothing to report, so it returns `5`.
Logging in happens automatically from the remembered password; run the interactive flow
once to store one, or pass `--password`. A refused login clears the saved password and
fails with `4`. **An absent password also fails with `4` here**, where `tx-optimize` calls
the same condition a usage error — worth knowing if you branch on the status.
fails with `4` — the node answered, and answered no. An **absent** password, and a node
name no contact matches, are usage errors (`2`): nothing was transmitted in either case,
which is the line `3` and `4` are drawn on.
**`--json`:**
+5 -4
View File
@@ -23,7 +23,6 @@ import typer
from ..context import AppContext
from ..core import exitcodes
from ..core.connection import DeviceCommandError
from .base import Tool, ToolResult, register
if TYPE_CHECKING: # pragma: no cover - typing only
@@ -102,17 +101,19 @@ class CourierTool(Tool):
name = str(params["contact"])
needle = name.casefold()
contact = next((c for c in contacts if c.name.casefold() == needle), None)
# The named contact, not the radio: nothing is queued and nothing is sent, so
# these are bad arguments (2) rather than device failures (4).
if contact is None:
raise DeviceCommandError(f"unknown contact: {name!r}")
raise typer.BadParameter(f"unknown contact: {name!r}")
key = contact_watch_key(contact)
if key is None:
raise DeviceCommandError(f"{name!r} has no usable key to address")
raise typer.BadParameter(f"{name!r} has no usable key to address")
not_before = None
if params.get("at"):
not_before = parse_clock(str(params["at"]))
if not_before is None:
raise DeviceCommandError(
raise typer.BadParameter(
f"--at wants a clock time like 07:00, not {params['at']!r}"
)
message = ctx.courier_store.queue(
+6 -2
View File
@@ -71,12 +71,16 @@ class RepeaterAdminTool(Tool):
contacts = await device.get_contacts()
name = str(params["node"])
node = next((c for c in contacts if c.name == name), None)
# Both of these are the *argument* being wrong, and nothing has gone out over
# the air when either fires — so they are usage errors (2), not device failures
# (4), whose promise to a caller is that a retry is worth trying. `tx-optimize`
# already answered the identical question this way for the identical condition.
if node is None:
raise DeviceCommandError(f"unknown contact: {name!r}")
raise typer.BadParameter(f"unknown contact: {name!r}")
password = params.get("password") or ctx.admin_store.get(node)
if not password:
raise DeviceCommandError(
raise typer.BadParameter(
f"no admin password for {name!r}; pass --password or run the "
"interactive flow once to store it."
)
+32
View File
@@ -556,6 +556,38 @@ def test_a_port_that_will_not_open_is_no_device_not_a_device_failure(run) -> Non
assert "lost" not in result.stderr
@pytest.mark.parametrize(
"args",
[
("repeater-admin", "Nobody", "get", "name"),
("courier", "queue", "Nobody", "hi"),
("courier", "queue", "Alice", "hi", "--at", "25:99"),
],
ids=["unknown-admin-node", "unknown-courier-contact", "bad-at-time"],
)
def test_a_bad_argument_is_never_reported_as_a_device_failure(run, args) -> None: # noqa: ANN001
"""``4`` promises a caller that the radio answered and a retry is worth trying.
Each of these is the *argument* being wrong, decided before a word goes over the air —
so a caller that retried on ``4`` would retransmit nothing, forever. ``tx-optimize``
already answered the identical question the identical way for a missing password;
these three were the ones that had not caught up.
"""
result = run(*args)
assert result.exit_code == exitcodes.USAGE, result.output
assert result.stdout == ""
def test_a_node_that_answers_no_is_still_a_device_failure(run) -> None: # noqa: ANN001
"""The other side of the line: the radio was reached, so a retry is a real option.
A refused admin login is not a bad argument — the password may simply have changed —
and reclassifying the arguments above must not drag this one along with them.
"""
result = run("repeater-admin", "Yagi-Repeater", "get", "name", "--password", "wrongpw")
assert result.exit_code == exitcodes.DEVICE, result.output
def test_an_empty_result_writes_nothing_to_stdout_at_all(run) -> None: # noqa: ANN001
"""Not a "no channels configured" line: the status carries it, so the pipe stays clean."""
result = run("channels", "list")