fix(cli): accept --flag=value and reordered options in pane read/wait-output

[KyleCo76]

Problem

herdr pane read --help and herdr pane wait-output --help (clap-generated)
advertise herdr pane read [OPTIONS] <PANE_ID>, but the hand-rolled parsers
only accept space-separated options after the pane id:

$ herdr pane read w1:p1 --source=recent --lines=5
unknown option: --source=recent            (exit 2)

$ herdr pane read --source recent --lines 5 w1:p1
unknown option: recent                     (exit 2; "--source" was consumed as the pane id)

$ herdr pane wait-output w1:p1 --match ready --timeout=5000
unknown option: --timeout=5000             (exit 2)

Failures are loud (exit 2), but the error can point at the wrong token, and
scripts written against --help or the usual --flag=value convention break.

Fix

• expand_equals_args (shared helper) splits --flag=value into two tokens
  for value-taking options only; boolean and unknown options keep their
  attached value and still reach the unknown-option branch.
• Both parsers extracted into pure parse_*_args functions (same pattern as
  parse_pane_split_args) that accept the pane id positional in any order and
  return the schema params directly.

Unlike the worktree --json compatibility no-op removed from public help in
#2174, these pane options already populate supported API fields and work in
the existing pane-id-first form; only the hand parser disagrees with the
generated syntax.

Previously valid invocations keep the same defaults and wire requests.
Invalid source/format/numeric values now print the underlying parser message
directly and return CLI-usage exit 2 instead of bubbling an io::Error
through main (exit 1). A second positional now reports
unexpected argument: X instead of unknown option: X. Server and protocol
are untouched; no docs changes needed.

Tests

• Unit tests cover both value spellings, pane-id order, attached values on
  boolean flags, and representative success/error cases; cargo nextest run --locked is green.
• CLI-level test: one invalid value per command exits 2 with the plain parser
  message instead of the old Error: Custom { ... } wrapper.
• Verified live against a dev server: every rejected form above now returns
  the expected output/match.

Hit this running herdr across two machines with claude/codex/kimi agent
fleets, scripting output gates on pane read / wait-output.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 5ec0d505-7f09-49cd-9e07-2a1619e96caa

📥 Commits

Reviewing files that changed from the base of the PR and between bf2afe4 and 1a48ef8.

📒 Files selected for processing (3)

• src/cli.rs
• src/cli/pane.rs
• tests/cli/panes.rs

🚧 Files skipped from review as they are similar to previous changes (3)

• tests/cli/panes.rs
• src/cli.rs
• src/cli/pane.rs

---

📝 Walkthrough

Walkthrough

The CLI now supports --key=value syntax for configured value options. Pane read and wait-output use dedicated parsers that validate argument order, values, positionals, unknown options, and matcher rules before request dispatch.

Changes

Pane argument parsing

Layer / File(s)	Summary
Equals-style option normalization src/cli.rs	Adds expand_equals_args for recognized value options. Boolean and unknown options remain unchanged.
Pane read parser src/cli/pane.rs	Parses pane IDs and options in either order, rejects invalid arguments, and returns structured errors. Tests cover supported forms and validation failures.
Pane wait-output parser src/cli/pane.rs	Parses timeout and matcher options, validates required and conflicting matchers, and rejects invalid positionals. Tests cover supported forms and validation failures.
CLI error validation tests/cli/panes.rs	Verifies invalid source and timeout values return exit code 2 with plain parser errors and no wrapped I/O error.

Estimated code review effort: 3 (Moderate) | ~25 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main CLI parsing changes for pane read and wait-output.
Description check	✅ Passed	The description accurately explains the parsing fixes, behavior changes, tests, and unchanged server protocol.
Docstring Coverage	✅ Passed	Docstring coverage is 83.78% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

The PR updates the hand-written pane read and pane wait-output parsers to match their advertised CLI syntax.

• Supports --flag=value for value-taking options.
• Allows the pane ID before or after options.
• Converts invalid argument values into CLI usage errors with exit code 2.
• Adds parser-level and CLI-level regression coverage.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
src/cli.rs	Adds a shared helper that expands recognized long-option assignments while preserving boolean and unknown options for rejection.
src/cli/pane.rs	Extracts pure argument parsers for pane read and wait-output, supporting reordered and equals-form options while preserving request defaults.
tests/cli/panes.rs	Verifies invalid values produce plain usage errors with exit code 2 before server contact.

_{Reviews (2): Last reviewed commit: "fix(cli): accept --flag=value and reorde..." | Re-trigger Greptile}

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 684731a2-0815-4d90-bd64-fa152da178b7

📥 Commits

Reviewing files that changed from the base of the PR and between 9a4ce5e and bf2afe4.

📒 Files selected for processing (3)

• src/cli.rs
• src/cli/pane.rs
• tests/cli/panes.rs

[KyleCo76]

Changes done for pane read — its generated help advertises both detection and --raw (read_source_option(true) + flag("raw") in spec.rs), so the fallback usage now lists both. Left wait-output unchanged: its help deliberately omits detection (read_source_option(false)), and the usage string mirrors the generated help.