🤖 docs: clarify log follow end and Unchanged, document the Coder rate limit for logs

[ThomasK33]

Summary

The parts of #193 (workspace log follow-ups) that need no product decision: the two how-to wording fixes (item 2), and the Coder rate limit documented next to the log limits (the documentation half of item 3). Two new test assertions pin the documented request counts and the missing Retry-After. Also one carry-over from the #247 assessment: the "Coder timeouts" summary row now mentions the 500 on a create.

Refs #193

Changes

1. docs/how-to/start-stop-workspaces.md (item 2):
   • "The follow ends when the build ends" now adds: or earlier, at the size or time limit of a log request. Then send the request again. It links the log limits in the reference.
   • "Unchanged: the workspace is already started or stopped" now says: only when the latest build of that kind succeeded. After a failed or canceled build, the request queues a new build (decideTransition in internal/aggregated/storage/workspace_transition.go:264-282).
2. docs/reference/aggregated-api-behavior.md:
   • The same two fixes in the start/stop section (the Unchanged bullet and the 409 hint).
   • Item 3: a new paragraph under the log-limits table. Every log request uses the Coder rate limit of the operator token: 512 requests per minute for each user and request path by default, CODER_API_RATE_LIMIT. A snapshot makes 2 Coder requests (workspace lookup, log read), and follow=true makes 1 more that opens the live stream and then sends no further requests. A Coder 429 reaches the client with Coder's message and without Retry-After.
   • Summary row "Coder timeouts": "After a 504 on a write, or a 500 on a create, re-read before you retry."
3. Tests:
   • TestWorkspaceLogSnapshot asserts that a snapshot makes exactly 2 Coder requests (1 lookup, 1 log read). The fake Coder now counts all requests.
   • TestWorkspaceLogFollowStreamsLiveEntries asserts 3 requests for a follow.
   • The 429 case of TestMapCoderError asserts that the mapped error keeps Coder's message and suggests no client delay (apierrors.SuggestsClientDelay), so no Retry-After is sent.

Not in this PR (product decisions)

• Item 1, tailLines on coderworkspaces/log. This is new API surface. It needs decisions on how tailLines combines with limitBytes and follow=true, and on what a cut snapshot means for "the last N lines". Coder returns the log from the start, so the server must read up to the 4 MiB snapshot cap and keep a bounded ring buffer. The issue's trigger is user demand.
• Item 3, second half: pass Coder's Retry-After on. *codersdk.Error does not expose response headers, so the server cannot read Coder's Retry-After without bypassing the SDK. client-go also retries a response with Retry-After on its own, up to 10 times (vendor/k8s.io/client-go/rest/request.go:483). Every Kubernetes client shares the one operator token, so automatic retries could make the rate limiting worse. Whether that is wanted is a product decision. Today the 429 has no Retry-After, and the new docs and test say so.

#215 item 2 (an unconfigured standalone server returns 503 on a namespaced LIST) is not touched.

Validation

make verify-vendor, make test, make test-integration, make build, make lint, make docs-check, GOFLAGS=-mod=vendor go tool govulncheck ./..., go test -race on internal/aggregated/coder and internal/aggregated/storage, and the CI versions of markdownlint-cli2 (0.18.1) and cspell (8.19.4) on docs/**/*.md.

---

Generated with mux • Model: anthropic:claude-opus-5-5 • Thinking: high

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-13T15:38:54.475033Z	b508ad1	Manual request
🔒 Security Review	✅ Completed 2026-10-13T15:38:06.719613Z	b508ad1	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[ThomasK33]

@codex security review

[chatgpt-codex-connector]

🛡️ Codex Security Review

Security review completed. No security issues were found in this pull request.

Reviewed commit: 80c823b086

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

• You comment "@codex security review"
• A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 80c823b086

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[ThomasK33]

@codex review

[ThomasK33]

@codex security review

[chatgpt-codex-connector]

🛡️ Codex Security Review

Security review completed. No security issues were found in this pull request.

Reviewed commit: 772fcd285e

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

• You comment "@codex security review"
• A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 772fcd285e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[ThomasK33]

@codex review

[ThomasK33]

@codex security review

[chatgpt-codex-connector]

🛡️ Codex Security Review

Security review completed. No security issues were found in this pull request.

Reviewed commit: b508ad13ac

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

• You comment "@codex security review"
• A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Breezy!

Reviewed commit: b508ad13ac

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".