docs(cli): document serve request timeout

[enieuwy]

Summary\n- Include --request-timeout in codexbar serve help output\n- Add a regression test covering serve/root help text\n\n## Testing\n- swift test --filter CLIServeRouterTests

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed June 2, 2026, 9:42 AM ET / 13:42 UTC.

Summary
The branch adds --request-timeout <seconds> to the custom serve/root help text and adds a focused help-string regression test.

Reproducibility: not applicable. as a bug reproduction. Source inspection on current main shows ServeOptions declares --request-timeout while the custom serve/root help strings omit it, and the PR adds a string-level regression test.

Review metrics: none identified.

Merge readiness
Overall: 🦪 silver shellfish
Proof: 🦪 silver shellfish
Patch quality: 🐚 platinum hermit
Result: blocked until real behavior proof from a real setup 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 or a terminal screenshot from the changed CLI help after running the branch.

Proof guidance:

• [P1] Needs real behavior proof before merge: The PR body only reports a unit test; before merge the contributor should add redacted terminal output or a terminal screenshot showing the changed codexbar serve --help/root help, then update the PR body to trigger a fresh review or ask for @clawsweeper re-review.

Risk before merge

• [P1] The PR body only reports a focused unit test command; it does not include terminal output or a screenshot showing the changed CLI help from a real run.
• [P1] This review did not run Swift tests because the cleanup review was required to keep the checkout read-only.

Maintainer options:

1. Decide the mitigation before merge
   Land the narrow help/test update after the contributor adds real terminal proof of the changed CLI help, or after a maintainer intentionally waives that proof for this low-risk docs/help change.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

• [P1] No repair PR is needed; the remaining blocker is contributor real-behavior proof or an explicit maintainer waiver.

Security
Cleared: The diff only changes help strings and a Swift test; it does not touch secrets, dependencies, scripts, networking behavior, or code execution paths.

Review details

Best possible solution:

Land the narrow help/test update after the contributor adds real terminal proof of the changed CLI help, or after a maintainer intentionally waives that proof for this low-risk docs/help change.

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

Not applicable as a bug reproduction. Source inspection on current main shows ServeOptions declares --request-timeout while the custom serve/root help strings omit it, and the PR adds a string-level regression test.

Is this the best way to solve the issue?

Yes, the proposed direction is the narrow maintainable fix for the observed docs/help gap. It updates the custom help strings and covers them with a focused test without changing serve runtime behavior.

AGENTS.md: found and applied where relevant.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 0ebb5043a071.

Label changes

Label changes:

• add P3: This is a low-risk CLI help/documentation polish PR with focused test coverage and no runtime behavior change.
• add rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🐚 platinum hermit.
• add status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR body only reports a unit test; before merge the contributor should add redacted terminal output or a terminal screenshot showing the changed codexbar serve --help/root help, then update the PR body to trigger a fresh review or ask for @clawsweeper re-review.

Label justifications:

• P3: This is a low-risk CLI help/documentation polish PR with focused test coverage and no runtime behavior change.
• rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🐚 platinum hermit.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR body only reports a unit test; before merge the contributor should add redacted terminal output or a terminal screenshot showing the changed codexbar serve --help/root help, then update the PR body to trigger a fresh review or ask for @clawsweeper re-review.

Evidence reviewed

What I checked:

• Repository policy read: Read the full target AGENTS.md and applied its read-only review constraint plus its preference for focused CLI tests over bundle-level UI validation. (AGENTS.md:1, 0ebb5043a071)
• Current option exists: Current main already defines the serve --request-timeout Commander option and default request timeout decoding, so the PR is documenting an existing CLI capability rather than adding a new flag. (Sources/CodexBarCLI/CLIServeCommand.swift:21, 0ebb5043a071)
• Current custom help omits the flag: Current main's serveHelp and rootHelp usage blocks list --port and --refresh-interval but not --request-timeout, matching the PR's targeted docs gap. (Sources/CodexBarCLI/CLIHelp.swift:80, 0ebb5043a071)
• Docs already mention timeout: The longer CLI docs on current main already document --request-timeout, so this branch narrows the remaining gap to the runtime/root help strings. (docs/cli.md:50, 0ebb5043a071)
• PR diff is narrow: The PR changes two files, adding the missing help text and a focused regression test that checks serveHelp and rootHelp contain the timeout option. (Sources/CodexBarCLI/CLIHelp.swift:80, bda43895c91c)
• Whitespace check clean: The proposed diff produced no git diff --check output for the changed range. (bda43895c91c)

Likely related people:

• enieuwy: Previously added the configurable serve request timeout and related cache/deadline behavior now being documented by this PR. (role: recent area contributor; confidence: high; commits: 06b7de126f1a; files: Sources/CodexBarCLI/CLIServeCommand.swift, Tests/CodexBarTests/CLIServeRouterTests.swift, docs/cli.md)
• ThiagoCAltoe: GitHub file history attributes the original localhost codexbar serve command and its router/cache tests to this contributor path. (role: introduced serve command; confidence: medium; commits: 74a019c4aa65; files: Sources/CodexBarCLI/CLIServeCommand.swift, Tests/CodexBarTests/CLIServeRouterTests.swift, docs/cli.md)
• steipete: Recent CLI help and serve-adjacent history includes direct changes to custom help, host-header validation, release/appcast entries, and current main updates. (role: recent CLI area contributor; confidence: high; commits: e5eb944d8e88, 83ed8e405541, 0ebb5043a071; files: Sources/CodexBarCLI/CLIHelp.swift, Sources/CodexBarCLI/CLIServeCommand.swift, Tests/CodexBarTests/CLIServeRouterTests.swift)

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.