Skip to content

feat(cli/logs): announce --follow gateway reconnect and add JSON notice parity#75372

Merged
RomneyDa merged 1 commit intomainfrom
fix/logs-follow-retry
May 3, 2026
Merged

feat(cli/logs): announce --follow gateway reconnect and add JSON notice parity#75372
RomneyDa merged 1 commit intomainfrom
fix/logs-follow-retry

Conversation

@RomneyDa
Copy link
Copy Markdown
Contributor

@RomneyDa RomneyDa commented May 1, 2026 •
edited
Loading

Summary

Follow-up to #75059 (which shipped the --follow retry loop, error classification, and bounded backoff). This PR layers on the recovery signal and JSON-mode parity that #75059 left out:

  1. [logs] gateway reconnected notice on the success-after-outage transition. fix(cli): auto-reconnect logs --follow on transient gateway disconnect #74782 #75059 silently resumes after a successful retry; this surfaces the recovery so users tailing the stream can tell the loop is back on the live RPC.
  2. JSON-mode parity for both transitions. fix(cli): auto-reconnect logs --follow on transient gateway disconnect #74782 #75059's [logs] gateway disconnected, reconnecting in Xs... warning was stderr-text only — --json consumers got no signal during outages. Both the existing retry warning and the new reconnect notice now emit {"type":"notice"} records on stderr in --json mode, mirroring the pattern used elsewhere in this CLI.

Error classification, retry budget, backoff math, and the loopback-fallback short-circuit are unchanged — all owned by #75059.

Issues

Carries forward #75059. Refs #74782, #74583, #56475.

Test plan

  • pnpm test src/cli/logs-cli.test.ts (22 passed; +1 --follow --json notice-parity test, plus a gateway reconnected assertion added to the existing explicit---url retry test).
  • pnpm exec oxfmt --check --threads=1 src/cli/logs-cli.ts src/cli/logs-cli.test.ts docs/cli/logs.md CHANGELOG.md clean.
  • Reviewer: pnpm check:changed (Testbox per AGENTS.md) and pnpm build before merge.
  • Manual: openclaw logs --follow --url ws://127.0.0.1:18789 against a loopback gateway, force a brief gateway restart, confirm both notices appear (text + JSON modes).

Notes

@openclaw-barnacle openclaw-barnacle Bot added docs Improvements or additions to documentation cli CLI command changes size: M maintainer Maintainer-authored PR labels May 1, 2026
@clawsweeper
Copy link
Copy Markdown
Contributor

clawsweeper Bot commented May 1, 2026 •
edited
Loading

Codex review: needs maintainer review before merge.

Summary
The PR emits JSON notice records for follow-mode retry/reconnect transitions, prints a text reconnect notice after successful retry recovery, and updates logs docs, tests, and changelog.

Reproducibility: not applicable. as a feature/parity PR. Source inspection on current main confirms the retry path has only a text disconnect warning and no reconnect/JSON notice parity, while the PR diff adds those signals.

Next step before merge
No repair job is needed because there is no discrete automated fix to make; this active PR only needs ordinary maintainer validation before merge.

Security
Cleared: The diff only changes CLI notice emission, tests, docs, and changelog; no dependency, workflow, permission, secret, install, or release surface is touched.

Review details

Best possible solution:

Land this narrow notice-parity layer after normal changed-gate/build and optional live gateway-restart smoke validation, while keeping the larger logs.subscribe streaming work separate in #56475.

Do we have a high-confidence way to reproduce the issue?

Not applicable as a feature/parity PR. Source inspection on current main confirms the retry path has only a text disconnect warning and no reconnect/JSON notice parity, while the PR diff adds those signals.

Is this the best way to solve the issue?

Yes. The diff keeps #75059's classifier/backoff boundary intact and only adds user-facing notices plus focused docs/tests, which is the narrowest maintainable fix for the remaining parity gap.

What I checked:

  • Current main retry classifier: Current main retries logs --follow only when isTransientFollowError(err) passes; the classifier excludes pairing-required and 4xxx auth/policy failures. (src/cli/logs-cli.ts:157, 85e4ec1fb1ac)
  • Current main notice gap: The current retry warning is text-only via errorLine(...), and the retry counter resets before output with no successful-reconnect notice. (src/cli/logs-cli.ts:341, 85e4ec1fb1ac)
  • PR diff scope: The PR head changes the existing retry warning to emit {type:"notice"} on stderr in JSON mode and adds [logs] gateway reconnected after a successful retry; it does not change classifier, retry budget, or backoff math. (src/cli/logs-cli.ts:341, 7269c9fec86e)
  • PR regression coverage: The PR adds a --follow --json test that forces one transient Gateway close, then verifies JSON notice records for both the retry and reconnect transitions. (src/cli/logs-cli.test.ts:376, 7269c9fec86e)
  • Docs and changelog already track base behavior: Current main documents the fix(cli): auto-reconnect logs --follow on transient gateway disconnect #74782 #75059 retry behavior; the PR's docs/changelog patch extends that existing entry for reconnect notice and JSON parity. (CHANGELOG.md:23, 85e4ec1fb1ac)
  • Protected label: The provided PR metadata includes the protected maintainer label, so cleanup closure is not appropriate even though the review findings are now empty. (7269c9fec86e)

Likely related people:

  • shashank-poola: PR fix(cli): auto-reconnect logs --follow on transient gateway disconnect #74782 #75059 introduced the current logs --follow transient retry classifier, bounded backoff, docs, and tests that this PR layers notices onto. (role: introduced behavior; confidence: high; commits: 23fe3559e5a2; files: src/cli/logs-cli.ts, src/cli/logs-cli.test.ts, docs/cli/logs.md)
  • vincentkoc: Recently added the active changelog credit and release-window entry for the same logs follow auto-reconnect behavior. (role: recent maintainer; confidence: medium; commits: e02377f52281; files: CHANGELOG.md)

Remaining risk / open question:

  • Normal broad merge validation (pnpm check:changed in Testbox and pnpm build) was not run in this read-only pass.
  • The live manual gateway-restart smoke in the PR body remains unchecked here.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 85e4ec1fb1ac.

This was referenced May 1, 2026
Merged
Closed
@RomneyDa
Copy link
Copy Markdown
Contributor Author

RomneyDa commented May 3, 2026

Reframing this PR after a closer look at what's already on main:

The reporter's exact scenario in #74583 (implicit local-loopback openclaw logs --follow, no --url, gateway at ws://127.0.0.1:18789, gateway closed (1000) on poll) is already fixed on main by the local-file fallback shipped under #74078. fetchLogs catches closed / timeout transport errors, and for implicit local-loopback connections returns readConfiguredLogTail(...) with localFallback: true instead of throwing — so the --follow loop never reaches process.exit(1) and ClawSweeper's close-as-implemented was technically defensible for that exact repro.

What this PR covers is the remaining gap that shouldUseLocalLogsFallback deliberately skips:

  • Explicit --url (any URL — remote or loopback typed explicitly): src/cli/logs-cli.ts:109-111 short-circuits the fallback, so a transient close still hits process.exit(1) in --follow.
  • Non-loopback URLs: same — explicit external gateways with a transient drop still exit today.
  • Non-classified errors: anything outside closed / timeout / pairing-required / plain gateway closed (...) / plain gateway timeout rethrows on main → exits in --follow.
  • Live RPC vs degraded file-tail: even when the fallback works, --follow is in file-tail mode (Local Gateway RPC unavailable notice once, then silent file reads). The retry path keeps the actual logs.tail RPC stream — including truncated / reset / cursor semantics — and recovers automatically once the gateway is reachable again.

So the framing is now Refs #74583 rather than Fixes, and the changelog/PR body call out that this is the explicit-URL / non-loopback / non-classified retry path, complementary to (not a replacement for) the #74078 local-file fallback. Both new tests in src/cli/logs-cli.test.ts use --url ws://127.0.0.1:18789 precisely to exercise the non-fallback retry branch.

@RomneyDa RomneyDa force-pushed the fix/logs-follow-retry branch from ce5f125 to 7269c9f Compare May 3, 2026 09:31
@RomneyDa RomneyDa changed the title fix(cli/logs): retry --follow across transient gateway disconnects feat(cli/logs): announce --follow gateway reconnect and add JSON notice parity May 3, 2026
@RomneyDa
Copy link
Copy Markdown
Contributor Author

RomneyDa commented May 3, 2026

@clawsweeper can you review this again

@clawsweeper
Copy link
Copy Markdown
Contributor

clawsweeper Bot commented May 3, 2026

🦞🦞
ClawSweeper is taking a look at your question.

I asked ClawSweeper to answer this maintainer mention in the next review comment. Tiny claws, bounded scope: this is a read-only assist pass unless it produces one of the existing structured safe-action markers.

Request: can you review this again

@RomneyDa
Copy link
Copy Markdown
Contributor Author

RomneyDa commented May 3, 2026

verified behavior

image

@RomneyDa RomneyDa merged commit 4bb4127 into main May 3, 2026
93 of 96 checks passed
@RomneyDa RomneyDa deleted the fix/logs-follow-retry branch May 3, 2026 09:56
vincentkoc added a commit that referenced this pull request May 3, 2026
@vincentkoc
docs(changelog): move @RomneyDa logs --follow notice fix to Unreleased
9772ce6 
#75372 added `[logs] gateway reconnected` notice and JSON `notice`
records as a follow-up to #75059 and landed today, but its changelog
entry was placed under `## 2026.4.29` (already released). Move it next
to the related #75059 entry under `## Unreleased ### Fixes` so the
released section stays frozen and the credited contributor lands in the
right release window. Thanks @RomneyDa.
@github-actions github-actions Bot mentioned this pull request May 3, 2026
Open
lxe pushed a commit to lxe/openclaw that referenced this pull request May 6, 2026
@RomneyDa @lxe
feat(cli/logs): announce --follow gateway reconnect and add JSON noti…
628f9ec 
…ce parity (openclaw#75372)
lxe pushed a commit to lxe/openclaw that referenced this pull request May 6, 2026
@vincentkoc @lxe
docs(changelog): move @RomneyDa logs --follow notice fix to Unreleased
39c26d6 
openclaw#75372 added `[logs] gateway reconnected` notice and JSON `notice`
records as a follow-up to openclaw#75059 and landed today, but its changelog
entry was placed under `## 2026.4.29` (already released). Move it next
to the related openclaw#75059 entry under `## Unreleased ### Fixes` so the
released section stays frozen and the credited contributor lands in the
right release window. Thanks @RomneyDa.
github-actions Bot pushed a commit to Desicool/openclaw that referenced this pull request May 9, 2026
@RomneyDa
feat(cli/logs): announce --follow gateway reconnect and add JSON noti…
2b44f13 
…ce parity (openclaw#75372)
github-actions Bot pushed a commit to Desicool/openclaw that referenced this pull request May 9, 2026
@vincentkoc
docs(changelog): move @RomneyDa logs --follow notice fix to Unreleased
7ff4fc6 
openclaw#75372 added `[logs] gateway reconnected` notice and JSON `notice`
records as a follow-up to openclaw#75059 and landed today, but its changelog
entry was placed under `## 2026.4.29` (already released). Move it next
to the related openclaw#75059 entry under `## Unreleased ### Fixes` so the
released section stays frozen and the credited contributor lands in the
right release window. Thanks @RomneyDa.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

cli CLI command changes docs Improvements or additions to documentation maintainer Maintainer-authored PR size: S

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@RomneyDa