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 20, 2026, 2:09 PM ET / 18:09 UTC.

Summary
The branch guards sag speak output-extension format inference behind whether --format was explicitly set and adds a command-level regression test.

Reproducibility: yes. by source inspection. Current main overwrites opts.outputFmt from a recognized output extension before request construction, matching the linked issue's --output out.mp3 --format mp3_44100_192 scenario; I did not run the live ElevenLabs command in this read-only review.

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 searches found no merged replacement for the same format-precedence problem.

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 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 but no after-fix real sag speak output, terminal transcript, logs, audio artifact, or ffprobe result; contributors should redact private details and update the PR body so ClawSweeper re-reviews automatically.

Risk before merge

• [P1] Contributor proof is still absent; tests and mocked server coverage do not show after-fix behavior against a real sag speak run or the expected bitrate.

Maintainer options:

1. Decide the mitigation before merge
   Merge the narrow precedence guard and regression test after redacted real behavior proof is added, 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] The remaining blocker is contributor proof and maintainer review, which an automated repair branch cannot supply.

Security
Cleared: The diff only changes Go command logic and a Go test; it does not touch dependencies, workflows, secrets, install scripts, or release automation.

Review details

Best possible solution:

Merge the narrow precedence guard and regression test after redacted real behavior proof is added, 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, matching the linked issue's --output out.mp3 --format mp3_44100_192 scenario; I did not run the live ElevenLabs command in this read-only review.

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 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 but no after-fix real sag speak output, terminal transcript, logs, audio artifact, or ffprobe result; contributors should redact private details and update the PR body so ClawSweeper re-reviews automatically.

Evidence reviewed

What I checked:

• Current main overwrites explicit format: On current main, sag speak calls inferFormatFromExt(opts.outputPath) whenever an output path is present and assigns the result to opts.outputFmt without checking whether the format flag was explicitly changed. (cmd/speak.go:111, ad9b1d3013b4)
• Request construction uses the overwritten value: The ElevenLabs request is built from opts.outputFmt, so the extension-inferred value is the value sent as OutputFormat. (cmd/speak.go:399, ad9b1d3013b4)
• Docs define explicit format as higher precedence: The format docs describe extension inference and then state that explicit --format <string> always wins. (docs/formats.md:8, ad9b1d3013b4)
• PR applies the narrow guard: The PR diff wraps extension inference in !cmd.Flags().Changed("format") while leaving output playback behavior unchanged. (cmd/speak.go:111, ead6eff7464f)
• PR adds focused regression coverage: The added command-level test asserts that output_format remains mp3_44100_192 when --output out.mp3 --format mp3_44100_192 are both provided. (cmd/speak_integration_test.go:117, ead6eff7464f)
• Real behavior proof is still absent: The PR body lists go test ./... and go build ./..., and the comments do not include after-fix terminal output, logs, an audio artifact, or an ffprobe bitrate result from a real setup. (ead6eff7464f)

Likely related people:

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

[steipete]

Post-merge live proof on current main (01b43135f786640e8d0e13dac6e80f62a4c9804c):

• built the current CLI from source
• ran real ElevenLabs synthesis with a fixed public test phrase, --format mp3_44100_192, mismatched --output /tmp/sag-explicit-format-proof.wav, --no-play, and --no-stream
• command exited 0; 37 characters produced 50,826 bytes
• file detected MPEG Layer III, 192 kbps, 44.1 kHz mono despite the .wav filename
• ffprobe: format_name=mp3, duration=2.043356, bit_rate=198990
• artifact SHA-256: 3254cf1b0b66f170afdaa5adc1c5b0128f99f252987f95bf7970e4b859d65cde

No private text, credential value, speaker playback, or persistent setting was used. This closes the real-behavior proof gap identified before merge.