Handle Telegram flood waits

[masonc15]

Summary

• retry TDesktop dialog, message, folder, and topic RPCs after Telegram FLOOD_WAIT responses
• dedupe TDesktop messages across retried history scans
• make subcommand --help print usage and exit successfully

Tests

• go test ./...
• go build -o /tmp/telecrawl-check ./cmd/telecrawl
• /tmp/telecrawl-check import --help
• bounded real import with --dialogs-limit 25 --messages-limit 100

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed June 20, 2026, 2:18 AM ET / 06:18 UTC.

Summary
The branch wraps Telegram Desktop dialog, message, folder, and topic RPCs in FLOOD_WAIT retry handling, deduplicates retried message scans, and makes subcommand help exit successfully.

Reproducibility: no. high-confidence live reproduction was established. Source inspection shows current main returns raw query errors from Telegram Desktop dialog/message/folder/topic RPCs, and the PR adds helper-level FLOOD_WAIT coverage, but no real FLOOD_WAIT transcript is present.

Review metrics: none identified.

Merge readiness
Overall: 🦪 silver shellfish
Proof: 🧂 unranked krab
Patch quality: 🐚 platinum hermit
Result: blocked until stronger real behavior proof is added.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• [P1] Add redacted terminal output, logs, or a short recording showing the real Telegram import behavior after the change, preferably including the flood-wait retry or the observed bounded import result.

Proof guidance:

• [P1] Needs stronger real behavior proof before merge: The PR needs redacted terminal/log proof of the real changed behavior; after updating the PR body, a fresh ClawSweeper review should run automatically, or a maintainer can comment @clawsweeper re-review. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Risk before merge

• [P1] The PR body says a bounded real import was run, but it does not include redacted output or logs proving the changed FLOOD_WAIT retry path or the observed import result.

Maintainer options:

1. Decide the mitigation before merge
   Land the focused retry helper after redacted real behavior proof shows the Telegram Desktop import path still completes while preserving context cancellation and duplicate suppression.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

• [P1] Contributor-facing proof is still needed; automation cannot supply evidence from the contributor's Telegram setup.

Security
Cleared: The diff adds no new dependencies, workflows, secret handling, or supply-chain surface; it reuses the existing Telegram session path and gotd dependency.

Review details

Best possible solution:

Land the focused retry helper after redacted real behavior proof shows the Telegram Desktop import path still completes while preserving context cancellation and duplicate suppression.

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

No high-confidence live reproduction was established. Source inspection shows current main returns raw query errors from Telegram Desktop dialog/message/folder/topic RPCs, and the PR adds helper-level FLOOD_WAIT coverage, but no real FLOOD_WAIT transcript is present.

Is this the best way to solve the issue?

Yes, the code direction is a narrow maintainable fix for the affected gotd RPC calls. Merge readiness still depends on contributor proof that the changed behavior was observed in a real setup.

AGENTS.md: found, but no applicable review policy affected this item.

Codex review notes: model internal, reasoning high; reviewed against 6ebb422a12aa.

Label changes

Label changes:

• add P2: This is a normal-priority Telegram import reliability fix with limited blast radius and no evidence of an urgent production regression.
• add rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🧂 unranked krab and patch quality is 🐚 platinum hermit.
• add status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs stronger real behavior proof before merge: The PR needs redacted terminal/log proof of the real changed behavior; after updating the PR body, a fresh ClawSweeper review should run automatically, or a maintainer can comment @clawsweeper re-review. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Label justifications:

• P2: This is a normal-priority Telegram import reliability fix with limited blast radius and no evidence of an urgent production regression.
• rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🧂 unranked krab and patch quality is 🐚 platinum hermit.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs stronger real behavior proof before merge: The PR needs redacted terminal/log proof of the real changed behavior; after updating the PR body, a fresh ClawSweeper review should run automatically, or a maintainer can comment @clawsweeper re-review. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Evidence reviewed

What I checked:

• Repository policy check: A parent AGENTS.md was read fully; it describes ClawSweeper operations and did not add telecrawl-specific review constraints for this PR. (../AGENTS.md:1)
• Current main lacks flood-wait retry: Current main calls GetDialogs, Messages, MessagesGetDialogFilters, folder GetDialogs, and MessagesGetForumTopics directly, with no tgerr/FLOOD_WAIT handling found by source search. (internal/telegramdesktop/tdata.go:182, 6ebb422a12aa)
• Latest release also lacks flood-wait retry: v0.3.0 has the same direct Telegram RPC calls and no FLOOD_WAIT/tgerr retry handling, so the central behavior is not already shipped. (internal/telegramdesktop/tdata.go:182, b479eccc2b82)
• PR retry implementation: The PR adds tdataWithFloodWait/tdataSleep, imports tgerr, and wraps dialog, message, folder, and topic calls while preserving context cancellation and deduplicating retried message IDs. (internal/telegramdesktop/tdata.go:651, b60380d830a0)
• PR help behavior: The PR adds a dispatch-level --help/-h check and a regression test for telecrawl import --help returning usage on stdout with no error. (internal/cli/cli.go:88, b60380d830a0)
• Proof gate: The PR body lists go test, go build, import --help, and a bounded real import, but it does not include terminal output, logs, or a transcript showing after-fix FLOOD_WAIT retry behavior. (b60380d830a0)

Likely related people:

• joshp123: GitHub commit history shows the pure-Go Telegram Desktop importer and related CLI/test surfaces were introduced through merged work on these files. (role: introduced current Go Telegram import path; confidence: high; commits: 9ef3b111c008; files: internal/telegramdesktop/tdata.go, internal/telegramdesktop/importer_test.go, internal/cli/cli.go)
• steipete: History shows the original Telegram archive CLI, folders/topics work, and recent adjacent release/dependency touches around the affected files. (role: original CLI and recent area contributor; confidence: high; commits: af7de2621dda, a44ecd99bc0a, e07a15d9b42f; files: internal/cli/cli.go, internal/telegramdesktop/tdata.go)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.