Honor explicit --format over output extension

[100yenadmin]

Fixes #21.

Summary

When sag speak gets both:

• --output out.mp3
• --format mp3_44100_192

it currently re-infers the format from the output extension and silently resets the request back to the default .mp3 profile (mp3_44100_128). That makes the explicit --format value ineffective for common save-to-file usage.

This patch keeps the existing extension inference, but only when --format was not explicitly provided.

What changed

• guard output-extension inference behind !cmd.Flags().Changed("format")
• add a command-level regression test that exercises --output out.mp3 --format mp3_44100_192

Verification

• go test ./...
• go build ./...

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed June 19, 2026, 3:59 AM ET / 07:59 UTC.

Summary
The PR guards sag speak output-extension format inference behind whether --format was explicitly changed and adds a command-level regression test for --output out.mp3 --format mp3_44100_192.

Reproducibility: yes. By source inspection, current main overwrites opts.outputFmt from a recognized output extension before request construction, and the linked issue provides a concrete sag speak --output out.mp3 --format mp3_44100_192 reproduction path.

Review metrics: none identified.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #21
Summary: This PR is the candidate fix for the linked open issue, and no other canonical or superseding item was found in search.

Members:

• canonical: Explicit --format is ignored when --output has a recognized extension #21 - The issue reports the same explicit-format precedence bug and this PR uses closing syntax for it.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🧂 unranked krab
Proof: 🧂 unranked krab
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 logs showing an after-fix sag speak --output out.mp3 --format mp3_44100_192 run and an ffprobe bitrate check; update the PR body so ClawSweeper re-reviews automatically, or ask a maintainer to comment @clawsweeper re-review if needed.

Proof guidance:

• [P1] Needs real behavior proof before merge: The PR includes test/build claims and a mocked regression test, but no after-fix real sag speak output, terminal transcript, logs, or artifact. 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 lists go test ./... and go build ./..., but it does not include after-fix real behavior proof from a real sag speak run; contributor proof is still needed before merge.

Maintainer options:

1. Decide the mitigation before merge
   Land this narrow precedence fix with the regression test after contributor-supplied real behavior proof, then let the linked issue close from the merge.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

• [P1] This PR should stay in normal maintainer review because the remaining blocker is contributor-provided real behavior proof, not an automated code repair.

Security
Cleared: The diff only changes Go command logic and a Go test; no dependency, workflow, secret, install, or release surface is introduced.

Review details

Best possible solution:

Land this narrow precedence fix with the regression test after contributor-supplied real behavior proof, then let the linked issue close from the merge.

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

Yes. By source inspection, current main overwrites opts.outputFmt from a recognized output extension before request construction, and the linked issue provides a concrete sag speak --output out.mp3 --format mp3_44100_192 reproduction path.

Is this the best way to solve the issue?

Yes for the code path. Guarding extension inference with !cmd.Flags().Changed("format") is the narrow maintainable fix that matches the docs, though merge readiness still needs real behavior proof.

AGENTS.md: not found in the target repository.

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

Label changes

Label changes:

• add P2: This fixes a normal CLI behavior bug with limited blast radius: explicit audio format selection is ignored for common save-to-file usage.
• add rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; 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 real behavior proof before merge: The PR includes test/build claims and a mocked regression test, but no after-fix real sag speak output, terminal transcript, logs, or artifact. 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 fixes a normal CLI behavior bug with limited blast radius: explicit audio format selection is ignored for common save-to-file usage.
• rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; 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 real behavior proof before merge: The PR includes test/build claims and a mocked regression test, but no after-fix real sag speak output, terminal transcript, logs, or artifact. 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:

• Current main overwrites explicit format from extension: On current main, sag speak calls inferFormatFromExt(opts.outputPath) whenever an output path is present and assigns it to opts.outputFmt without checking whether the format flag was explicitly changed. (cmd/speak.go:111, ad9b1d3013b4)
• Docs define explicit format as higher precedence: The format docs describe extension inference first and then state that explicit --format <string> always wins. (docs/formats.md:8, ad9b1d3013b4)
• PR applies the narrow guard: The PR commit adds !cmd.Flags().Changed("format") around extension inference while leaving playback disabling behavior unchanged. (cmd/speak.go:111, ead6eff7464f)
• PR adds focused regression coverage: The added command-level test asserts that output_format stays mp3_44100_192 when --output out.mp3 --format mp3_44100_192 are both provided. (cmd/speak_integration_test.go:117, ead6eff7464f)
• Linked issue is the canonical remaining report: GitHub search found the paired open issue describing this exact --format and output-extension precedence bug, and the PR body lists it as a closing issue.
• Feature history points to current speak implementation owner: Blame and log history show the current speak command, format inference, docs, and integration tests entering the current tree through the v0.4.0 60db synthesis commit. (cmd/speak.go:111, c451f4673401)

Likely related people:

• Peter Steinberger: Blame and git log -S tie the current speak command, extension inference, docs, and command integration tests to the v0.4.0 commit and later main maintenance commits. (role: introduced behavior and recent area contributor; confidence: high; commits: c451f4673401, 9661f690bad8, ad9b1d3013b4; files: cmd/speak.go, cmd/speak_integration_test.go, docs/formats.md)
• derspotter: A prior merged commit changed output format handling for Opus/OGG in cmd/speak.go, related tests, and the ElevenLabs client. (role: adjacent output-format contributor; confidence: medium; commits: 8e44324fb455; files: cmd/speak.go, cmd/speak_integration_test.go, cmd/speak_test.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.

[100yenadmin]

@steipete tldr is anyone using eleven labs or any output should have ability per docs to set the format. currently users are paying for and should get the best audio format but sag is limiting them and ignoring ouput that works fine on API.