diagnostics: support redacted diagnose output files

[Yuxin-Qiao]

Summary

• add explicit codexbar diagnose --redact --output <path> support for writing the already-redacted provider diagnostic JSON to a file
• include safe platform and appVersion fields in provider diagnostic exports for issue triage
• update diagnose help and focused CLI/export tests

Real CLI proof

Ran the PR branch locally with a fake SYNTHETIC_API_KEY value to verify the output-file path detects API auth without writing the raw token:

$ SYNTHETIC_API_KEY=<fake-token> GIT_OPTIONAL_LOCKS=0 swift run CodexBarCLI diagnose --provider synthetic --format json --redact --output /tmp/codexbar-diagnose-proof.json
[0/1] Planning build
Building for debugging...
Build of product 'CodexBarCLI' complete!\n\n$ ls -l /tmp/codexbar-diagnose-proof.json\n-rw-r--r--@ 1 yuxinqiao  wheel  423 Jun 21 10:30 /tmp/codexbar-diagnose-proof.json\n\n$ python3 -m json.tool /tmp/codexbar-diagnose-proof.json | sed -n '1,32p'\n{\n    "auth": {\n        "configured": true,\n        "modes": [\n            "api"\n        ]\n    },\n    "displayName": "Synthetic",\n    "error": {\n        "category": "auth",\n        "safeDescription": "Authentication or setup issue - check provider credentials"\n    },\n    "fetchAttempts": [\n        {\n            "errorCategory": "auth",\n            "kind": "api",\n            "wasAvailable": true\n        }\n    ],\n    "platform": "macOS",\n    "provider": "synthetic",\n    "schemaVersion": "1.0",\n\n$ rg -n "<fake-token>|SYNTHETIC_API_KEY|Bearer|Authorization|Cookie|password|secret" /tmp/codexbar-diagnose-proof.json\n# no matches\n```\n\nThis confirms `diagnose --redact --output` writes the diagnostic JSON to disk and the file keeps only safe auth metadata, not the raw token or sensitive headers.\n\n## Test\n- `swift test --filter 'CLIArgumentParsingTests|CLIDiagnoseCommandTests|ProviderDiagnosticExportTests'`

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed June 20, 2026, 10:35 PM ET / 02:35 UTC.

Summary
The PR adds codexbar diagnose --redact --output <path>, writes the already-redacted diagnostic JSON to disk, adds platform/appVersion diagnostic metadata, and updates help plus focused tests.

Reproducibility: not applicable. this is a feature PR for a new CLI output-file path, not a bug report with a failing current-main reproduction path. Source review confirms current main does not expose the requested --output option.

Review metrics: 2 noteworthy metrics.

• Changed surface: 7 files, +88/-5. The patch is small but touches public CLI flags, help text, diagnostic export schema, and tests.
• CLI options added: 2 added. --redact and --output become public command-line behavior that maintainers should intentionally accept.

Merge readiness
Overall: 🦞 diamond lobster
Proof: 🦞 diamond lobster
Patch quality: 🦞 diamond lobster
Result: ready for maintainer review.

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

Risk before merge

• [P1] This adds new public diagnose CLI surface (--redact and --output), so maintainers still need to accept that behavior even though no code defect was found.

Maintainer options:

1. Decide the mitigation before merge
   Land the narrow CLI/export change with its real CLI proof and focused tests if maintainers accept the new diagnose flags and safe metadata fields.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

• No automated repair is needed; the remaining action is maintainer review and acceptance of a small public CLI diagnostics surface.

Security
Cleared: No concrete security or supply-chain issue was found; the diff writes the already-redacted diagnostic export and does not add dependencies, workflow changes, or secret-handling broadening beyond the explicit output path.

Review details

Best possible solution:

Land the narrow CLI/export change with its real CLI proof and focused tests if maintainers accept the new diagnose flags and safe metadata fields.

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

Not applicable: this is a feature PR for a new CLI output-file path, not a bug report with a failing current-main reproduction path. Source review confirms current main does not expose the requested --output option.

Is this the best way to solve the issue?

Yes: the implementation is narrow and keeps the existing diagnostics pipeline redacting JSON before writing it. The remaining question is maintainer acceptance of the new public CLI flags, not an identified code defect.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 3f3e2f4a112a.

Label changes

Label changes:

• add proof: sufficient: Contributor real behavior proof is sufficient. The PR body now includes copied terminal proof showing the new CLI command writing a diagnostic JSON file and an rg check that the fake token and sensitive header names are absent.
• add rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The PR body now includes copied terminal proof showing the new CLI command writing a diagnostic JSON file and an rg check that the fake token and sensitive header names are absent.
• remove rating: 🧂 unranked krab: Current PR rating is rating: 🦞 diamond lobster, so this older rating label is no longer current.
• remove status: 📣 needs proof: Current PR status label is status: 👀 ready for maintainer look.

Label justifications:

• P3: This is a low-risk diagnostics/ergonomics improvement with no evidence of a user-blocking regression.
• rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The PR body now includes copied terminal proof showing the new CLI command writing a diagnostic JSON file and an rg check that the fake token and sensitive header names are absent.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body now includes copied terminal proof showing the new CLI command writing a diagnostic JSON file and an rg check that the fake token and sensitive header names are absent.

Evidence reviewed

What I checked:

• Repository policy read: AGENTS.md was read fully; its guidance favors focused CLI/parser tests for CLI-testable provider behavior and avoiding live provider probes that could trigger Keychain prompts. (AGENTS.md:23, 3f3e2f4a112a)
• Current main lacks the new diagnose flags: Current main's diagnose options expose provider, format, and pretty, but no --redact or --output option, so the PR is not obsolete. (Sources/CodexBarCLI/DiagnoseOptions.swift:18, 3f3e2f4a112a)
• Current main only prints redacted diagnostics to stdout: The existing command encodes diagnostics, runs LogRedactor.redact, and prints the JSON string directly instead of supporting file output. (Sources/CodexBarCLI/CLIDiagnoseCommand.swift:73, 3f3e2f4a112a)
• PR diff is narrow diagnostics work: The patch adds output-path handling and a writer helper, two diagnose options, help text, diagnostic metadata fields, and parser/export tests across 7 files with +88/-5 lines. (Sources/CodexBarCLI/CLIDiagnoseCommand.swift:33, 00b214a7fce7)
• Contributor proof now covers the previous blocker: The PR body includes copied terminal output for a real swift run CodexBarCLI diagnose --provider synthetic --format json --redact --output ... run, an ls proof that the file was written, a JSON excerpt, and an rg check showing no fake token or sensitive header names. (00b214a7fce7)
• CI is green for the current head: GitHub reports successful lint, Linux CLI builds, macOS test shards, lint-build-test, and GitGuardian checks for the PR head. (00b214a7fce7)

Likely related people:

• steipete: Local blame ties the current diagnose command and diagnostic export builder in main to the v0.37.0 snapshot, and the merged diagnostics foundation PR includes follow-up commits from this handle around diagnose help/output behavior. (role: recent diagnostics area contributor; confidence: high; commits: 33a5f4362eab, a1fd47aaf4cf, 64901f939686; files: Sources/CodexBarCLI/CLIDiagnoseCommand.swift, Sources/CodexBarCLI/CLIHelp.swift, Sources/CodexBarCore/Providers/ProviderDiagnosticExport.swift)
• Yuxin-Qiao: This handle authored the merged redacted MiniMax diagnostic export foundation and CLI export commits in Add redacted MiniMax diagnostic export foundation #1128, which is the closest prior implementation history for this PR's diagnose/export surface. (role: prior diagnostics feature contributor; confidence: high; commits: c1a8d4a72b77, 352fdc25f6d6, 7819edf8431b; files: Sources/CodexBarCLI/CLIDiagnoseCommand.swift, Sources/CodexBarCLI/DiagnoseOptions.swift, Tests/CodexBarTests/CLIDiagnoseCommandTests.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.

[Yuxin-Qiao]

Added real CLI proof to the PR body.

What I ran on the PR branch:

• SYNTHETIC_API_KEY=<fake-token> GIT_OPTIONAL_LOCKS=0 swift run CodexBarCLI diagnose --provider synthetic --format json --redact --output /tmp/codexbar-diagnose-proof.json
• verified /tmp/codexbar-diagnose-proof.json was written
• verified the JSON reports safe auth metadata (configured: true, modes: ["api"])
• verified sensitive patterns / fake token / auth header names do not appear in the output file

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.