#25362 acpmux: send --prompt-file says send reads stdin and which command takes the flag

The gui-push coordinator (2026-10-20-gui-push-6f, remote acpmux ergonomics), word for word:

"(2) acpmux send --no-wait --prompt-file FILE gives a bare usage line without saying --prompt-file isn't a send flag."

(Part (1), wait --print after a failed turn, is #25353. It was split out to keep each PR under 800 lines.)

Cause: clap's UnknownArgument error with its nearest-spelling tip, which suggested --prompt-id.

What changed (cli/unknown_flag.rs, cli/entry.rs): when a command gets a long flag that another (non-hidden) top-level command takes, the refusal says which commands take it and what this command does instead. The message ends with a command to run, the same shape as #25270's and #25288's refusals. It exits 2, and under --json it carries data.reason usage.unknown_flag, data.flag, data.command, data.takenBy and data.try. For send --prompt-file, the try is the same send with the file on stdin, built from the argv: value flags keep their values, the file is shell-quoted, and NAME stands in when no session was given. When there are prompt words too (send would send those instead), the try is acpmux send --help. A flag no command takes keeps clap's own error, and help and version are unchanged. It is refused before any daemon is asked.

Before:

$ acpmux send --no-wait --prompt-file brief.md lane
error: unexpected argument '--prompt-file' found

  tip: a similar argument exists: '--prompt-id'

Usage: acpmux send --no-wait --prompt-id <PROMPT_ID> [SESSION] [PROMPT]...

For more information, try '--help'.

After (a CI run of the built binary, https://github.com/manaflow-ai/cmux/actions/runs/40276666964):

$ acpmux send --no-wait --prompt-file brief.md lane      # exit 2
acpmux: usage: send takes no --prompt-file: `new` (also `new-session`, `run`, `exec`) takes it. send reads its prompt from stdin when it has no prompt words or `-`. Try: acpmux send --no-wait lane - < brief.md
$ acpmux --json send lane --prompt-file brief.md          # exit 2, on stderr
{"error":{"code":"usage","data":{"command":"send","flag":"--prompt-file","reason":"usage.unknown_flag","takenBy":["new"],"try":"acpmux send lane - < brief.md"},"detail":"unknown_flag","exit":2,"message":"send takes no --prompt-file: … Try: acpmux send lane - < brief.md", …}}
$ acpmux send --no-such-flag lane                          # unchanged: clap's own error
error: unexpected argument '--no-such-flag' found

Tests (red, then green):

• tests/send_prompt_file.rs: the real binary. Text and --json refusals, exit 2, no --prompt-id, and no daemon started. Red at 80114e83 (clap's line: https://github.com/manaflow-ai/cmux/actions/runs/40279855095). Green at fa141127: cargo fmt --check and clippy --all-targets clean, send_prompt_file 1/1, lib unknown_flag and help_contract 5/5, cmux-tui remote_cli_docs green (https://github.com/manaflow-ai/cmux/actions/runs/40279855044).
• Unit (cli/unknown_flag.rs): quoting, value flags kept, the NAME placeholder, prompt words, and unknown flags keeping clap's error.

Review: Codex gpt-6-astra (xhigh), reading the bare mirror only. SHIP at fa1411278001de821c5fd93aa210c756f4dbb154 ("No correctness findings. The isolated implementation preserves clap's help/version and unrelated error handling, returns usage exit 2, and produces correctly quoted stdin suggestions. No help/docs contract drift identified.").

No capture: CLI text only. The before and after output is above. Stop conditions: none needed; there is no timer, observer or loop.

Agent session: big-red
🤖 Generated with Claude Code