Skip to content

fix(thread): show the thread when the channel lookup is rate limited - #94

Open
roryist wants to merge 3 commits into
mainfrom
roryist/thread-view-rate-limit
Open

roryist wants to merge 3 commits into
mainfrom
roryist/thread-view-rate-limit

Conversation

@roryist

@roryist roryist commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

TL;DR

When Comms rate limits the channel lookup, tdc thread view now shows the thread and its comments, with the channel id where the name would be. Any other error still fails as before. The rate-limit error also now says to wait a minute or two, not "a moment".

Why

Showing a thread takes four calls to Comms: the thread, its comments, the workspace's people, and the channel. Only the channel call has a per-user rate limit. In practice it's about 100 calls a minute.

On 23 October an agent read about 1,000 threads in two minutes. The channel lookups hit the limit, and every view after that failed. The thread and its comments had loaded fine. All that was missing was the channel's name.

The error then said "Wait a moment, then retry". An agent reads that as "retry now". Comms counts rejected calls against the limit too, so retrying straight away keeps the user locked out. The limit is per user, so while it lasts, that person's web app can't load channels either.

What changes

When the channel lookup gets a 429:

Output Before After
Text Fails with RATE_LIMITED Shows the thread, with [ch:CH100] in place of [General] new
--json / --ndjson Fails with RATE_LIMITED Shows the thread, with "channelName": "ch:CH100" new
Any other error (404, 403, …) Fails Fails

And the hint on every rate-limit error:

Before After
Wait a moment, then retry Wait a minute or two before retrying. Retrying sooner keeps the limit in place, because rejected calls count against it too. new

Those are the only changes. Everything else is how it already worked.

Text and JSON both show ch:<id>, the same fallback tdc inbox already uses for a channel it can't name. I first used null in JSON, but that changes what scripts get from --json, so it would have to ship as a major release. The fallback is rare, so channelName stays a string and nothing reading it breaks.

Only a rate limit is skipped over. A 404 or 403 means something is actually wrong, and hiding that would be worse than failing.

The private-channel check that runs before the name lookup still fails on any error, a 429 included. If it can't run, the CLI can't tell whether the thread is private, so carrying on could show a private thread. It also uses a different call that has no per-user limit, so it isn't the one these 429s come from.

The hint says "a minute or two" rather than "a minute". Comms adds up the current minute and the whole previous minute, so after a burst it can take up to two minutes before calls get through again.

No new metrics: the CLI has no metrics pipeline.

Three things to look at

  • Thread view no longer acts as a brake. Before, a rate limit made thread views fail, which at least told the caller something was wrong. Now the views succeed, so a sweep has no reason to slow down, and its channel lookups keep getting 429s. Those are cheap for the backend (no database work), but the user's apps still can't load channels until the sweep ends. Stopping that is backend work, like giving each route its own budget, not this PR.
  • The hint applies to every 429, not just channel lookups. It lives in the shared error handling. In the logs, every CLI 429 came from the channel lookup. I haven't checked how other Comms limits count, but waiting a minute or two is still safe advice there, if longer than needed.
  • No automatic wait or retry. I left that out on purpose. The hint tells the caller what to do. Once the backend sends a Retry-After header, the SDK could pass it on and the hint could give the exact wait.

How it relates to other PRs

It stands alone. It's one of three fixes from the same investigation. comms-cli#93 makes tdc inbox fetch channel names in one call instead of one call per channel. comms-backend#1155 sends Retry-After on 429s. The SDK doesn't expose response headers yet, so the CLI can't read that header until it does.

References

🤖 Generated with Claude Code

(Written by Rory's agent)

@roryist roryist self-assigned this Oct 23, 2026
@roryist

roryist commented Oct 23, 2026

Copy link
Copy Markdown
Contributor Author

@doistbot /review

@doistbot doistbot left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice fix — when the channel lookup hits a rate limit, tdc thread view now still renders the thread (with channel:<id> in text, null in JSON) instead of failing outright, and the 429 hint now steers agents away from immediate retries.

Few things worth tightening:

  • The default viewThread path calls assertChannelIsPublic before getChannelName, so a 429 on that separate channels.getChannels call still aborts the view before the new guard kicks in — the tests mock assertChannelIsPublic, so this path isn't exercised. Worth handling its rate limit the same way so both default and --json views actually survive the limit.
  • Minor: the updated hint is a good step, though agents may still retry instantly if nothing discourages it — the degradation itself helps a lot here.

I also included a few optional follow-up notes in the details below.

Optional follow-up notes (2)
  • P3 src/commands/thread/view.ts:54: This introduces a second channel-fallback prefix: channel:CH100 here, while src/commands/inbox.ts:152 already falls back with ch:${thread.channelId}. Consumers parsing either command's output would have to handle both spellings. Pick one prefix (probably ch:, since it shipped first) or reuse a shared helper so the fallback format stays consistent.
  • P3 src/commands/thread/thread.test.ts:882: This covers --json, but the PR also changes --ndjson thread output so the first line can carry channelName: null when the channel lookup is rate limited. That serialization contract is currently untested, so a regression in the ndjson branch would pass the suite. Add a test that parses the first ndjson line and asserts { type: 'thread', channelName: null }.

Share Feedback • Review Logs

Comment thread src/commands/thread/view.ts Resolved
roryist and others added 2 commits November 18, 2026 13:44
Channel lookups are the only call in `thread view` with a per-user rate
limit, so a bulk read of threads hits it first. The thread and comments
have already loaded by then, and the channel name is only a label. On a
429, thread view now shows the channel id instead of failing, and
--json / --ndjson output sets channelName to null. Any other error still
fails as before.

The 429 hint now says to wait a minute or two, and that retrying sooner
keeps the limit in place. The old "Wait a moment" read as "retry now".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The inbox already shows `ch:<id>` for a channel it can't name, so thread
view now uses the same prefix instead of adding `channel:<id>`. Also
covers the --ndjson shape when the channel lookup is rate limited.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@roryist
roryist force-pushed the roryist/thread-view-rate-limit branch from b3d3e09 to 059beee Compare November 18, 2026 13:46
@roryist

roryist commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

@doistbot /review

@doistbot doistbot left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This PR makes tdc thread view degrade gracefully when the channel-name lookup hits a 429: the thread still renders with ch:<id> in place of the channel name (and channelName: null in JSON/NDJSON), while all other errors keep failing, and the rate-limit hint now advises waiting a minute or two.

Few things worth tightening:

  • The new tests pass only because the module mock stubs out assertChannelIsPublic; in the real default path that helper issues its own channels.getChannels call (absent from the fake client) and would still throw RATE_LIMITED before the name lookup. Add that method to createClient and cover the case where the public-channel check itself hits the 429, otherwise the suite asserts a path the CLI doesn't actually support yet.
  • channelName changing from always-a-string to string | null is a breaking contract change for scripts reading --json/--ndjson output. As titled, semantic-release ships this as a patch; retitle to fix!(thread): ... (or add a BREAKING CHANGE: footer) so it releases as a major.

Share Feedback • Review Logs • Trace

Comment thread src/commands/thread/thread.test.ts Resolved
thread: {
...thread,
channelName: channel.name,
channelName,

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 channelName can now be null in the --json output (and in --ndjson at line 181, plus the single-comment output at line 78), so the field's contract changes from always-a-string to string | null for every script that reads tdc thread view. .agents/checks/command-surface.md calls out a changed --json field without a breaking-change PR title, and semantic-release derives the version from that title: as fix(thread): ... this ships as a patch, so consumers can break on a routine upgrade. Retitle to fix!(thread): ... (or add a BREAKING CHANGE: footer) so it releases as a major, as #111 did for the --stdin change.

@roryist
roryist marked this pull request as ready for review November 18, 2026 13:58
@roryist roryist added the 🚢 Ship PR requires passing checks before merge, but no independent human review. label Nov 18, 2026
A null channelName in --json and --ndjson would change the output contract, so it would have to ship as a major release. The fallback is rare, so the field stays a string and uses the same ch:<id> the text header and tdc inbox already show.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

🚢 Ship PR requires passing checks before merge, but no independent human review.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants