refactor: clear readability pauses in the client, orchestrator, and entrypoint

[aliasunder]

Summary

Two stranger reads of src/openrouter/client.ts, src/orchestrate.ts, and src/main.ts found places where a reader new to the code had to stop and trace. This PR fixes the ones in code these files own: comments that didn't match the code, names that meant two things, duplicated logic, silent branches, and a production branch that existed only for test stubs.

One review output changes: a finding re-posted after GitHub rejects the inline review no longer says it sits beyond the diff. Log output changes are listed below.

Changes

src/openrouter/client.ts

• ModelAttempt.model doc. It defines the ladder (the primary model, then the fallback), and says the routed model is reported only for the accepted attempt, as StructuredReviewResult.modelUsed.
• One name for the key-rejected fact. "Abort" also named the AbortSignal that cancels an HTTP call, so the fact an auth or credit status (401, 402, 403) ended the ladder is now keyRejected everywhere:
  • the failed attempt's flag (was abort)
  • ReviewRequestError's field (was aborted)
  • the status set, KEY_REJECTED_STATUSES
  • the stage runner's check, isKeyRejected (was isAbortedRequest)
• getCallTimeout. It computes a call's timeout and its timeout summary once. The chat request and the cost lookup used to compute both separately.
• Cost lookup. lookupGenerationCost logs at debug when the review deadline has already passed, where it used to return silently.
• OpenRouterLike.generations is required. The real SDK always has it, so the optional member and its no-client skip existed only for test stubs.
• Counter names. The per-model counter is now modelAttemptNumber, and the total across the ladder is now totalAttemptCount. Before, attemptNumber and attemptCount sat side by side and were easy to confuse.
• Comments now state:
  • that Promise.try forwards the abort signal to start
  • why a context overflow continues to the fitted-ceiling retry
  • that requestReview checks the review budget before each attempt
  • which variables are reassigned across attempts

src/orchestrate.ts

• Comments. Step-numbered comments ("Step 4", "Step 12.5") pointed to a list that doesn't exist. They are now plain sentences, and the ones that only restated the next line are gone.
• Diff budget comment. It said the diff "gets half the budget", but half is only the diff's cap: context files get whatever the diff leaves. budgetHalf is now diffTokenLimit.
• changedPaths. A deleted file returns nothing, instead of a null that a later filter removed. A rename returns its new and old paths.
• Findings posted as issue comments. These are beyond-diff findings plus every in-diff finding when GitHub rejects the inline review. The group was called "standalone", "unanchored", and "beyond-diff" in different places, and its log lines called every member "beyond-diff". It is now issueCommentPosts, which pairs each finding with its rendered body, and the log text matches.
• Smaller changes:
  • The related-files token total uses sumBy.
  • describePipelineFailure takes includeCostSummary.
  • renderCostSummary sits beside the other return values.
  • Comments state that the anchored/unanchored split compares object identity, and that the GitHub client already logs a 422.

src/config.ts and src/main.ts

• An empty fallback_model parses to null in config.ts. It used to be normalized in two different ways, in main.ts and in the settings log.
• main.ts uses describeError for unhandled rejections.
• Its comments now agree that at most one cancellation cleanup is registered, and name the priority_docs exception to "empty selects the default".
• The cancellation warning no longer claims to close a check run that doesn't exist.

src/github/client.ts: its doc for the issue-comment group now names both members.

src/review/comment-mapping.ts

• renderBeyondDiffFinding and renderReroutedFinding replace renderStandaloneFinding. They share one body and differ only in the location line.
• A re-routed in-diff finding used to say it sat beyond the diff's line ranges. It now says it is at or near a changed line, posted as its own comment because GitHub rejected the inline review.

Log output changes

Line	Before	After
review attempt failed	attemptNumber	modelAttemptNumber
review response accepted, review phase completed	attemptCount	totalAttemptCount
Issue-comment post summary	beyond-diff findings posted	findings posted as issue comments, with locations
Inline review post	findings review posted with inlineCount, reviewUrl	adds locations
Issue-comment post failure	failed to post beyond-diff finding — …	failed to post finding as an issue comment — …
Cancellation	cancellation signal received — closing the check run	cancellation signal received — closing any open check run before exit, with checkRunOpen
Cost lookup after the deadline	(nothing)	generation cost lookup skipped at debug, with reason

Tests

• The existing log assertions follow the renamed fields and messages.
• New or strengthened tests:
  • changedPaths is asserted as the exact ordered path list, which catches a dropped rename path or a dropped /dev/null guard.
  • The issue-comment summary logs the count of posts that landed, excluding a failed one, and is absent when none land.
  • The stage runner skips later stages only when keyRejected is true.
  • The key-rejection skip warning names the skipped phases.
  • The deadline cost-lookup skip asserts its debug line.
  • A configured fallback_model keeps its value, and an empty one parses to null.
  • The failure summary leaves out the cost table when cost_summary is off.
  • Both findings-post summaries assert their locations.
  • A re-routed finding renders with the in-diff location line, and a 422 run with mixed findings keeps the beyond-diff line only on the beyond-diff finding.
• One test, which covered only the removed no-generations-client branch, is deleted.
• Mutation checks were run on each new behavior and reverted, and each broke the intended test.

Verification

• npm test: 810 passed
• npm run lint and npm run build are clean.

🤖 Generated with Claude Code

[umm-actually]

umm-actually re-reviewed at 47f5106

1 new finding(s) posted (6 tracked finding(s) across all runs).

---

umm-actually · deepseek/deepseek-v4.1-flash