refactor(cli): one daemon-unreachable message; only cmd_wings JSON says less (#476)

[jphein]

One message, four variants removed; no call site reports less than it did.

palace daemon unreachable at was written out by hand at 22 places. This routes 20 of them through _fail_daemon and leaves 2 deliberately.

The premise was wrong, and reading the sites is what found it

They were never 22 copies of one block. There are four distinct messages:

variant	sites	text
A	12	… — see mempalace status for diagnostics ({e})
B	5	… — see mempalace status for diagnostics — no exception interpolated
C	2	… — /cypher returned {status} (see mempalace status for diagnostics)
F	1	cmd_wings, via _read_family_fail: leading blank line, ERROR: prefix, no diagnostics clause

Functions holding two occurrences hold an A and a B, not two copies of one thing.

⭐ B is not a degraded copy of A — it is the no-exception case

if data is None:
    # _call_daemon_rest returns None on 404/401/403 — endpoint
    # missing on an older daemon, or auth mismatch. …
    if want_json:
        _emit_json({"error": "daemon /list unavailable", "source": "daemon"})
    else:
        print(f"palace daemon unreachable at {_daemon_url()} — "
              "see mempalace status for diagnostics", file=sys.stderr)

Nothing was raised, so there is no exception to interpolate. Those five sites instead name the failing route in JSON — the only identifying information a 404 leaves behind.

The five B prose sites are exactly the five route-naming JSON sites. That correspondence is design, not drift, and it is why the helper needed a wider signature than "take the exception".

The helper

def _fail_daemon(err, want_json: bool, *, route: str | None = None, **extra) -> None

• err=None → prose drops the parenthetical instead of printing (None); route supplies the JSON error
• route= → preserves the per-route JSON error (daemon /list unavailable) that five sites emitted
• **extra → carries structured fields a site already published — today status from the two /cypher sites

⚠️ A helper that could not express what the call sites already said would make the CLI report less than it does — the defect this wave exists to remove, wearing the costume of a cleanup. Dropping a JSON field is a breaking change to a machine interface and is invisible to a prose diff: a script reading .status simply starts getting null.

Before / after — 20 sites across 12 functions

Captured with the real binary against a closed port, on pre-change main and again after.

function	sites	variants	outcome
cmd_list	2	A, B	identical (prose + JSON)
cmd_move	2	A, B	identical
_gather_bulk_move_matches	2	A, B	identical
cmd_graph	2	A, B	identical
cmd_stats	2	A, B	identical
cmd_why	2	A, A	identical
cmd_tags	1	A	identical
cmd_tunnels	1	A	identical
_drawer_call_or_exit	1	A	identical
cmd_cypher	2	A, C	A identical; C prose rearranged, JSON identical
cmd_overlap	2	A, C	A identical; C prose rearranged, JSON identical
cmd_wings	1	F	normalised (declared)

17 of 20 byte-identical on both channels. Every entry point now answers the same way:

exit=1  palace daemon unreachable at <url> — see mempalace status for diagnostics (<e>)

The three declared changes

1. C ×2 — prose rearranged, JSON identical.

before  palace daemon unreachable at <url> — /cypher returned 502 (see mempalace status for diagnostics)
after   palace daemon unreachable at <url> — see mempalace status for diagnostics (daemon /cypher returned 502)

The status is still in the sentence and still in {"status": 502}.

2. cmd_wings — normalised. This site had drifted furthest:

before  <blank line>
          ERROR: palace daemon unreachable at <url> (<e>)           ← prefix, no diagnostics clause
        JSON: {"error": "palace daemon unreachable at <url> (<e>)"} ← a pre-rendered sentence
after   palace daemon unreachable at <url> — see mempalace status for diagnostics (<e>)
        JSON: {"error": "<e>"}                                      ← the bare exception, like the other 19

Its JSON error no longer embeds the daemon URL. That is the one place the machine output says less, and it is deliberate: every other site emits the bare exception, and the URL remains in the prose and in the caller's own config.

3. All 20 sites gain the "rejected the call" branch. _fail_daemon distinguishes a transport failure from a JSON-RPC error the daemon itself returned, so a server-side error that used to print "unreachable" now prints "palace daemon at <url> rejected the call — …". This is a behaviour change, and it is a fix of the #499 class: an error named for the layer that noticed rather than the layer that failed.

What is deliberately not touched

_daemon_tool_or_fail keeps its own copy of the literal. It is not a duplicate — it is a better helper:

sys.exit(1 if unreachable else 2)

transport failure → exit 1 · JSON-RPC error from a daemon that answered → exit 2, "because the operator response differs and the sibling commands' single 'unreachable' message is actively wrong for the second" — its own docstring

That is the same answered-vs-unreachable distinction #499 exists to make, already implemented. _fail_daemon exits 1 for both, so folding it in would have destroyed a deliberate distinction in six commands and shipped it as a cleanup. The two converge in the exit-code PR — in the other direction, with _fail_daemon learning the discrimination.

cmd_wings appears in both lists because it calls _daemon_tool_or_fail and carried its own copy; only the copy is touched here.

Verification

• Full suite green; ruff check + ruff format --check clean.
• Literal count 22 → 2, asserted by a test rather than a grep.
• 9 new tests, pinning the machine-facing half per route — the half a prose diff cannot see.
• Three mutations, each killing a specific test (and each asserted to have applied before the run was believed):
  • drop every route= → the 3 route tests die
  • drop payload.update(extra) → test_extra_fields_survive dies
  • remove the err is not None guard → the bogus-(None) test dies
• Before/after captured with the real binary against a closed port, pre-change and post-change.

Part of #476

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[coderabbitai]

Warning

Review limit reached

Next included review available in 2 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 33a18153-ade0-45f2-85f6-aad8c1ecb64d

📥 Commits

Reviewing files that changed from the base of the PR and between 95a9385 and 0f2c2d6.

📒 Files selected for processing (6)

• FORK_CHANGELOG.md
• README.md
• docs/fork-changes/2026-09-17-one-daemon-unreachable-message.yaml
• mempalace/cli.py
• tests/test_cli_fail_daemon_one_message.py
• website/public/llms-full.txt

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}