feat(leg): `leg exchange` — one `baton.message/v1` round-trip with nested `baton.exchange/v1`

[shukebeta]

feat(leg): leg exchange — one baton.message/v1 round-trip with nested baton.exchange/v1

Problem

leg must be drivable as an ExternalAgentParticipant by baton serve --agent-cmd "leg exchange" without adaptation.

Approach

• leg exchange: one baton.message/v1 round-trip with nested baton.exchange/v1 provider record, same envelope as baton.
• Keep the infallible Participant contract (delivery error → kind:"error" envelope, never Err).
• Prove end-to-end under baton serve --agent-cmd "leg exchange".

Acceptance

1. leg exchange round-trips a baton.message/v1 envelope with a nested provider record.
2. Consumable by baton serve --agent-cmd "leg exchange" without adaptation (cross-repo integration proof).
3. Delivery errors surface as kind:"error" envelopes, never Err.

Part of

SHUKE-LABS/baton#338 (umbrella). Depends on leg#2.

[shukebeta]

[developer Plan]

Goal

Add leg exchange [--in <path>] [--out <path>]: one baton.message/v1 request/response round-trip (nested baton.exchange/v1 on success), usable both as a file-based envelope round-trip (mirroring baton exchange) and as the program baton serve --agent-cmd drives.

Context

• GitHub issue: feat(leg): leg exchange — one baton.message/v1 round-trip with nested baton.exchange/v1 #4
• Key files: src/cli.rs (command enum/parse/dispatch, USAGE), src/participant.rs (LocalParticipant/Participant — reused as-is), src/message.rs (MessageEnvelope — reused as-is)
• Reference (read-only, not vendored): SHUKE-LABS/baton src/cli.rs Command::Exchange/read_request_envelope/write_response_envelope, and src/participant.rs ExternalAgentParticipant/capture_child_output, plus docs/external-agent.md
• Docs impact: none (README/architecture doc pointer is leg#6's scope)

Design note (the part worth flagging before I implement)

Baton has two distinct consumers of a leg exchange-shaped command, and they disagree on stdin shape:

1. baton exchange's own contract: a whole JSON MessageEnvelope in, a whole JSON MessageEnvelope out (--in/--out, default stdin/stdout).
2. baton serve --agent-cmd's ExternalAgentParticipant: feeds only the plain-text request body on stdin (no envelope), reads reply text from stdout (whole stdout by default, or a JSON line's <result_key> field with --agent-output json --agent-result-key <key>).

AC1 ("round-trips a baton.message/v1 envelope") matches contract 1; AC2 ("consumable by baton serve --agent-cmd without adaptation") requires contract 2. One command satisfies both via a small, deterministic heuristic on the input bytes:

• Try to parse the whole input as a MessageEnvelope (serde_json::from_str). If it parses, use it as the request directly (contract 1).
• If it does not parse, treat the raw input (trailing newline trimmed) as the plain-text prompt body and synthesize a request envelope (from: "external", to: "leg", fixed conversation_id/message_id, kind: Request) (contract 2).

Output is always the full response MessageEnvelope as one JSON line — for contract 2, the operator pairs --agent-output json --agent-result-key body on the baton side (leg's own envelope field is literally named body, so no baton-side special-casing is needed — this is the "without adaptation" part). A prompt that accidentally parses as a MessageEnvelope is not a realistic risk: the struct requires exact required fields (schema, message_id, conversation_id, from, to, kind as one of 5 fixed enum strings, body, ts_ms).

Delivery/provider errors already surface as kind: "error" envelopes purely because Participant::respond (already ported, unchanged) is infallible by contract — AC3 falls out of reusing it, not new code.

No event-log (LEG_EVENT_LOG) recording for exchange — out of the issue's stated 3-bullet approach, and ask's recording is documented as ask/fresh session only; adding a third writer is a separate concern I'm not folding in here.

Steps

1. src/cli.rs: add Command::Exchange { in_path: Option<String>, out_path: Option<String> }; add parse_exchange (accepts --in <path> / --out <path>, any other token is a usage error), wire "exchange" => parse_exchange(iter).map(Some) into parse_args, update USAGE.
2. src/cli.rs: add open_input(Option<&str>) -> Result<Box<dyn Read>> / open_output(Option<&str>) -> Result<Box<dyn Write>> (file when Some, else stdin/stdout — mirrors the existing open_append_sink/read_log file-vs-fallback style already in this file).
3. src/cli.rs: add a pure parse_exchange_request(raw: &str) -> MessageEnvelope implementing the try-JSON/else-synthesize heuristic above, and execute_exchange(in_path, out_path) -> Result<()> (loads LegConfig, builds LocalParticipant, reads via open_input, calls parse_exchange_request, calls participant.respond, writes the response envelope as one JSON line via open_output). Split out a testable core parameterized over impl Participant + impl Write (same shape as run_ask), so tests avoid the network.
4. Wire Some(Command::Exchange { in_path, out_path }) => execute_exchange(in_path.as_deref(), out_path.as_deref()) into run().
5. Tests in src/cli.rs's existing #[cfg(test)] mod tests: parse_args cases for exchange (no flags, --in/--out, missing value, unexpected extra arg); parse_exchange_request cases (valid envelope JSON round-trips as-is; non-JSON plain text synthesizes a request with that body); the testable-core execute_exchange-equivalent cases (success → response envelope with nested Ok exchange; provider failure → kind: "error" envelope, execute_exchange itself still returns Ok(())).

Acceptance Criteria

• leg exchange reads a baton.message/v1 request envelope (via --in/stdin) and writes a response envelope (via --out/stdout) with a nested baton.exchange/v1 record on a successful provider call.
• leg exchange fed a plain-text prompt on stdin (the ExternalAgentParticipant shape) synthesizes a request, runs one exchange, and writes a response envelope whose body field holds the reply.
• A provider/delivery failure surfaces as a delivered kind: "error" response envelope; execute_exchange never returns Err for that reason (only true I/O failures on --in/--out do).
• cargo test green; cargo clippy clean.

(developer)

[shukebeta]

[reviewer Review]

Context

• GitHub issue: feat(leg): leg exchange — one baton.message/v1 round-trip with nested baton.exchange/v1 #4
• Reviewed plan: leg exchange envelope round-trip and external-agent compatibility

Verdict

CHANGES REQUESTED

Acceptance criteria check

• AC1 — The planned parser/dispatch, LocalParticipant::respond, and JSONL response writer cover the envelope round-trip and nested exchange shape; the proposed unit tests exercise the provider success path.
• AC2 — The plan does not yet satisfy or prove the stated baton serve --agent-cmd "leg exchange" contract; see Must fix items below.
• AC3 — Reusing the infallible Participant boundary preserves delivered kind: "error" responses; the planned fake-provider test covers this.
• AC4 — The listed parser/core tests and cargo test/cargo clippy cover the planned in-repo implementation, but they do not replace the missing cross-repo proof for AC2.

Issues

Must fix

• The plan's output contract conflicts with AC2. It says leg exchange always writes a full response envelope and requires --agent-output json --agent-result-key body on baton. Baton defaults external-agent output to raw (baton/docs/external-agent.md:35-53), so the literal baton serve --agent-cmd "leg exchange" path receives the JSON envelope as the reply body, not the reply text. Also, baton parses --agent-cmd as the executable token and passes subcommand arguments separately (baton/src/cli.rs:2639-2653); a quoted leg exchange is not the supported program-plus-argument form. Resolve the contract explicitly: either make the plain-text invocation produce the raw reply expected by the default adapter, or revise the required baton invocation to the supported --agent-cmd leg --agent-arg exchange form (and justify any output-adapter flags against the issue's “without adaptation” wording).
• Add an actual cross-repository integration proof to the implementation steps. The current tests are all local parser/core tests and never launch baton serve/ExternalAgentParticipant, so they cannot establish AC2. The proof must use the supported baton argument shape, feed a plain-text request, assert the resulting reply body, and cover the response/error behavior selected by the resolved contract. A reproducible hermetic harness or an explicitly documented runnable proof is sufficient; a plan-level assertion is not.
• Docs impact: none is not adequate for a new public CLI/workflow contract. The issue decomposition can defer README/architecture prose to leg#6, but the plan must record that concrete deferral/dependency (while still updating USAGE/--help here) rather than declaring no docs impact.

Nits

• Consider preserving prompt whitespace with a newline-only trim (\\r/\\n) rather than a broad trim_end, and add a test if that distinction is intentional.

Hygiene

• No implementation diff exists at plan stage; hygiene review is deferred to the implementation review.

(reviewer)

[shukebeta]

[reviewer Review]

GitHub issue: #4

Context

• Reviewed revision: plan-leg-exchange-v2.md
• The revision resolves the earlier command-shape, raw-output success path, integration-proof, and docs-impact gaps.

Verdict

CHANGES REQUESTED

Acceptance criteria check

• AC1 — Envelope input remains envelope output with the nested provider exchange; the planned CLI/core tests cover the success path.
• AC2 — Plain-text success output now matches baton's default raw adapter, and the supported --agent-cmd <path> --agent-arg exchange form is named. The hermetic process test plus the manual baton proof address the integration claim.
• AC3 — The planned plain-text provider-failure behavior still loses the required delivered kind: "error" envelope; see Must fix.
• AC4 — The revised unit, integration, script, and cargo validation steps cover the stated implementation surfaces.

Issues

Must fix

• src/cli.rs plain-text mode is specified to write only response.body even when LocalParticipant returned a MessageKind::Error; the planned process test consequently expects only raw error text. That cannot prove AC3 and is semantically a success to baton: with OutputAdapter::Raw, any non-empty child output is returned as Ok(body) and ExternalAgentParticipant constructs a MessageKind::Response (baton/src/participant.rs:553-571), while only a child machinery failure reaches synthesize_error_response. The issue requires provider/delivery failures to surface as delivered kind: "error" envelopes. Reconcile the contracts before implementation: either scope the envelope-error guarantee explicitly to envelope mode and document that plain external-agent failures are delegated to baton's machinery-error boundary, or make plain-mode failure emit a protocol signal compatible with baton's default raw adapter (for example, no stdout plus a stderr diagnostic so baton synthesizes its error envelope). Update the unit test, hermetic test, and scripts/external-agent-proof.sh to assert the chosen kind: "error" behavior; do not leave the current raw error-text test as the AC3 proof.

Nits

• Keep the mode discriminator shared with request construction (for example, return a small mode/request pair) so execute_exchange does not repeat the envelope parse independently of parse_exchange_request.

Hygiene

• No implementation diff exists at plan stage; hygiene review is deferred to implementation review.

(reviewer)

[shukebeta]

[developer Plan]

Goal

Add leg exchange [--in <path>] [--out <path>]: one baton.message/v1 request/response round-trip, drivable both as a file-based envelope round-trip and as the literal program baton serve --agent-cmd <path-to-leg> --agent-arg exchange spawns, with zero output-adapter flags required on the baton side, and provider/delivery failures observably surfacing as delivered kind: "error" envelopes in both modes.

Context

• GitHub issue: feat(leg): leg exchange — one baton.message/v1 round-trip with nested baton.exchange/v1 #4
• Key files: src/cli.rs, src/participant.rs (LocalParticipant/Participant — reused as-is), src/message.rs (MessageEnvelope — reused as-is), src/error.rs (new LegError variant, see below), src/transport/claude.rs (response-shape reference for the mock server)
• Reference (read-only, not vendored): SHUKE-LABS/baton src/cli.rs:2639-2653 (--agent-cmd is one executable token; args via repeated --agent-arg), src/participant.rs:503-573 (ExternalAgentParticipant::try_respond/capture_child_output: a non-zero exit or empty stdout is the only path to synthesize_error_response's delivered kind: "error"; any non-empty stdout on exit 0 is unconditionally wrapped as kind: "response"), docs/external-agent.md:35-53 (default output adapter raw)
• Docs impact: USAGE/--help updated here (step 1). README/architecture prose deferred to leg#6, which should link leg exchange and scripts/external-agent-proof.sh from the architecture doc.

Revision from v2 (addressing review — AC3 gap)

Reviewer's must-fix: writing response.body (the error text) to stdout on a kind: "error" participant response is, from baton's side, indistinguishable from a normal reply — ExternalAgentParticipant only reaches synthesize_error_response on a machinery failure (spawn error, non-zero exit, empty stdout, timeout), never by inspecting stdout content. So plain-text-mode success and failure need different process-level signals, not just different text:

• Plain-text mode, success (MessageKind::Response): unchanged — write response.body to stdout, exit 0.
• Plain-text mode, failure (MessageKind::Error): write nothing to stdout, print the error message to stderr, and execute_exchange returns Err(LegError::Delivery(response.body.clone())) — a new minimal variant (kind() → "delivery", Display → "delivered error response: {msg}") that exists solely to carry this one case through the existing main.rs plumbing (Err → stderr diagnostic + ExitCode::FAILURE, already implemented, no new mechanism). Both signals (non-zero exit and empty stdout) independently satisfy capture_child_output's existing Err path, so ExternalAgentParticipant reliably synthesizes its own delivered kind: "error" envelope — which is where AC3 becomes observable end-to-end for the external-agent path, since a leg exchange subprocess itself never emits baton.message/v1 JSON in plain-text mode to phrase its own error envelope.
• Envelope mode: unchanged from v2 — the full response envelope (including a kind: "error" response, nested Outcome::Error) is written to stdout and execute_exchange returns Ok(()) regardless of response.kind, exactly mirroring baton exchange's own Command::Exchange handling (write_response_envelope runs unconditionally). This is where the Participant trait's own "never Err, always a delivered envelope" guarantee is directly visible, since here leg is speaking the full protocol itself rather than delegating to baton's machinery-error boundary.

This resolves the "must fix" by explicitly scoping the delivered-envelope guarantee to envelope mode (as the reviewer offered as option 1) and making plain-mode failure a machinery-shaped signal baton already knows how to reconcile (option 2) — both, since they're cheap and reinforcing here.

Nit taken (mode-discriminator sharing)

parse_exchange_request(raw: &str) -> (MessageEnvelope, ExchangeMode) where enum ExchangeMode { Envelope, PlainText } — parsed once; execute_exchange's testable core takes the same ExchangeMode to choose the output/error-signalling path, instead of re-detecting independently.

Steps

1. src/cli.rs: add Command::Exchange { in_path: Option<String>, out_path: Option<String> }; parse_exchange (--in <path> / --out <path>, any other token a usage error); wire "exchange" => parse_exchange(iter).map(Some); update USAGE/--help.
2. src/cli.rs: add open_input(Option<&str>) -> Result<Box<dyn Read>> / open_output(Option<&str>) -> Result<Box<dyn Write>> (file when Some, else stdin/stdout — same shape as open_append_sink/read_log).
3. src/error.rs: add LegError::Delivery(String) (kind() → "delivery"; Display → "delivered error response: {msg}"), used only by plain-text-mode failure below.
4. src/cli.rs: add ExchangeMode enum and parse_exchange_request(raw: &str) -> (MessageEnvelope, ExchangeMode) (envelope mode when raw parses as MessageEnvelope; else plain-text mode, synthesizing a request with raw trimmed only of trailing \r/\n as the body). Add execute_exchange(in_path, out_path) -> Result<()>: loads LegConfig, builds LocalParticipant, reads via open_input, parses via parse_exchange_request, calls participant.respond, then per ExchangeMode: Envelope → write the full response envelope as one JSON line, return Ok(()) regardless of response.kind; PlainText + Response → write response.body, return Ok(()); PlainText + Error → write nothing to --out/stdout, eprintln the message, return Err(LegError::Delivery(..)). Split a testable core (impl Participant + impl Write, run_ask's shape) so all four branches are unit-testable without a network.
5. Wire Some(Command::Exchange { in_path, out_path }) => execute_exchange(in_path.as_deref(), out_path.as_deref()) into run().
6. Unit tests in src/cli.rs: parse_args cases for exchange (bare, --in/--out, missing value, unexpected extra arg); parse_exchange_request cases (valid envelope JSON passes through unchanged + ExchangeMode::Envelope; non-JSON text synthesizes a request + ExchangeMode::PlainText, trailing newline trimmed, trailing spaces preserved); testable-core cases for all four branches above (envelope-mode success/error both Ok(()) with the right stdout shape; plain-text success Ok(()) with raw body only; plain-text failure Err(LegError::Delivery(..)) with empty stdout and the message on stderr).
7. New tests/exchange_agent_cmd.rs: hermetic mock-HTTP-server proof (spawns the compiled leg binary per capture_child_output's mechanics — write stdin, close it, drain stdout to EOF, check exit code — against a hand-rolled std::net::TcpListener mock, no new dependency). Cases: (a) success → exit 0, stdout is exactly the mocked reply text; (b) mocked 401 → non-zero exit, empty stdout, stderr carries the diagnostic — proving the machinery-failure signal ExternalAgentParticipant depends on, not just leg-internal text.
8. New scripts/external-agent-proof.sh (mirrors baton's own convention: not part of CI, real credentials, requires a local baton checkout): runs baton serve --agent-cmd <path-to-leg> --agent-arg exchange against a throwaway mailbox for both a normal turn and a deliberately-bad-credential turn, asserting the second lands in baton's own outbox as a delivered kind: "error" envelope — the literal cross-repo AC3 proof.

Acceptance Criteria

• leg exchange reads a baton.message/v1 request envelope (--in/stdin) and writes a response envelope (--out/stdout) with a nested baton.exchange/v1 record on success, or a kind: "error" envelope on failure — both exiting 0.
• leg exchange fed a plain-text prompt writes only the raw reply text to stdout on success (consumable by baton serve --agent-cmd <path> --agent-arg exchange with the default raw adapter, no extra flags) — and on a provider/delivery failure writes nothing to stdout, diagnoses to stderr, and exits non-zero, so baton's own machinery-error path delivers the kind: "error" envelope.
• tests/exchange_agent_cmd.rs hermetically proves both the success and machinery-failure signal in CI; scripts/external-agent-proof.sh documents the real cross-repo kind: "error" proof.
• cargo test green; cargo clippy clean.

(developer)

[shukebeta]

[reviewer Review]

GitHub issue: #4

Context

• Reviewed revision: plan-leg-exchange-v3.md
• The revision resolves the raw-output/error-boundary ambiguity by proposing an empty-stdout signal for baton, but it now violates the issue's infallible execute_exchange contract by returning a new LegError::Delivery.

Verdict

CHANGES REQUESTED

Acceptance criteria check

• AC1 — Envelope mode still writes a complete response/error envelope and keeps the nested provider exchange on the participant response.
• AC2 — Plain-text success and the supported --agent-cmd <path> --agent-arg exchange invocation match baton's default raw adapter.
• AC3 — Plain-text provider failure is planned to return Err(LegError::Delivery) and exit non-zero, which conflicts with the issue's “delivery errors ... never Err” contract; see Must fix.
• AC4 — The revised unit, process-boundary, manual cross-repo, and cargo validation steps cover the listed surfaces once AC3 is reconciled.

Issues

Must fix

• src/cli.rs step 4 and src/error.rs step 3 turn a provider failure that Participant::respond already delivered into Err(LegError::Delivery(...)) in plain-text mode. main.rs maps every Err to a failure exit, so this directly contradicts issue feat(leg): leg exchange — one baton.message/v1 round-trip with nested baton.exchange/v1 #4's acceptance (“Delivery errors surface as kind: "error" envelopes, never Err”) and the original plan's explicit “only true --in/--out I/O failures” rule. The new variant is a process-exit workaround, not a delivered envelope. Keep the infallible execute_exchange contract: for plain-text failure, emit the diagnostic on stderr, leave stdout empty, and return Ok(()); baton's existing ExternalAgentParticipant treats empty stdout as machinery failure and synthesizes the delivered kind: "error" envelope. Keep envelope mode's full kind: "error" JSON response unchanged. Update the plain-failure unit/process tests and the script's assertions to reflect exit 0 from leg plus the baton-level error envelope.
• The plan says the plain-failure unit test should assert a stderr message, but the proposed testable core is parameterized only over the response Write and calls eprintln! directly. Capture stderr at the child-process integration boundary (where it is already observable), or add an explicit diagnostic writer parameter; do not claim the current core shape can unit-test global stderr.

Nits

• If the implementation keeps an error marker type for internal control flow, it must not escape execute_exchange as LegError for a provider response; prefer a mode/result enum or an empty-output branch so LegError remains reserved for actual command failures.

Hygiene

• No implementation diff exists at plan stage; hygiene review is deferred to implementation review.

(reviewer)

[shukebeta]

[developer Plan]

Goal

Add leg exchange [--in <path>] [--out <path>]: one baton.message/v1 request/response round-trip, drivable both as a file-based envelope round-trip and as the literal program baton serve --agent-cmd <path-to-leg> --agent-arg exchange spawns, with zero output-adapter flags required on the baton side, execute_exchange itself staying infallible with respect to provider/delivery failures in both modes.

Context

• GitHub issue: feat(leg): leg exchange — one baton.message/v1 round-trip with nested baton.exchange/v1 #4
• Key files: src/cli.rs, src/participant.rs (LocalParticipant/Participant — reused as-is), src/message.rs (MessageEnvelope — reused as-is), src/transport/claude.rs (response-shape reference for the mock server)
• Reference (read-only, not vendored): SHUKE-LABS/baton src/cli.rs:2639-2653 (--agent-cmd is one executable token; args via repeated --agent-arg), src/participant.rs:503-526 (ExternalAgentParticipant::try_respond: exit 0 with empty stdout is already, on its own, a machinery failure — if stdout.trim().is_empty() { return Err(...) } runs after capture_child_output has already confirmed exit 0; a non-zero exit is a separate, not required, path to the same Err), docs/external-agent.md:35-53 (default output adapter raw)
• Docs impact: USAGE/--help updated here (step 1). README/architecture prose deferred to leg#6, which should link leg exchange and scripts/external-agent-proof.sh from the architecture doc.

Revision from v3 (correcting the AC3 fix)

v3 over-corrected: making execute_exchange return Err(LegError::Delivery(..)) on a plain-text provider failure directly contradicts AC3's "never Err" and the plan's own "only true --in/--out I/O failures return Err" rule — dropped entirely, no new LegError variant.

The actual fix needs no exit-code trick at all: ExternalAgentParticipant::try_respond checks stdout.trim().is_empty() after confirming exit 0 — so exit 0 with empty stdout already routes to baton's synthesize_error_response, independent of exit code. So:

• Plain-text mode, failure (MessageKind::Error): print the error message to stderr (diagnostic only, not a delivered envelope — that's baton's job downstream), write nothing to --out/stdout, and execute_exchange returns Ok(()) — exactly like every other outcome. No new error variant, no non-zero exit.
• Plain-text mode, success: unchanged — write response.body to stdout, Ok(()).
• Envelope mode: unchanged from v2/v3 — full response envelope (any response.kind) written to stdout, Ok(()).

This keeps execute_exchange uniformly infallible for every participant outcome, in both modes, matching AC3 literally; the empty-stdout signal alone is what lets baton's already-existing machinery-error path deliver its own kind: "error" envelope for the external-agent case.

Nit taken (unit-testability of the stderr diagnostic)

The eprintln! diagnostic writes to the process's real stderr, not to any writer the testable core takes — so it is not asserted in the in-process unit tests. Unit tests for the plain-text-failure branch assert only what the core's signature actually exposes: the function returns Ok(()), and the response Write receives zero bytes. The stderr diagnostic's actual content is verified once, at the process boundary, in tests/exchange_agent_cmd.rs (step 7), where real child stderr is captured. No new writer parameter — avoids threading a diagnostic-output abstraction through the core for one branch.

Steps

1. src/cli.rs: add Command::Exchange { in_path: Option<String>, out_path: Option<String> }; parse_exchange (--in <path> / --out <path>, any other token a usage error); wire "exchange" => parse_exchange(iter).map(Some); update USAGE/--help.
2. src/cli.rs: add open_input(Option<&str>) -> Result<Box<dyn Read>> / open_output(Option<&str>) -> Result<Box<dyn Write>> (file when Some, else stdin/stdout — same shape as open_append_sink/read_log).
3. src/cli.rs: add ExchangeMode enum (Envelope/PlainText) and parse_exchange_request(raw: &str) -> (MessageEnvelope, ExchangeMode) (envelope mode when raw parses as MessageEnvelope; else plain-text mode, synthesizing a request whose body is raw trimmed only of trailing \r/\n). Add execute_exchange(in_path, out_path) -> Result<()>: loads LegConfig, builds LocalParticipant, reads via open_input, parses via parse_exchange_request, calls participant.respond, then per (ExchangeMode, response.kind): Envelope (either kind) → write the full response envelope as one JSON line; PlainText + Response → write response.body; PlainText + Error → write nothing, eprintln! the message. All four branches return Ok(()); Err is reserved for genuine --in/--out I/O failures. Split a testable core (impl Participant + impl Write, run_ask's shape) covering the three stdout-producing branches plus the empty-stdout branch's return value.
4. Wire Some(Command::Exchange { in_path, out_path }) => execute_exchange(in_path.as_deref(), out_path.as_deref()) into run().
5. Unit tests in src/cli.rs: parse_args cases for exchange (bare, --in/--out, missing value, unexpected extra arg); parse_exchange_request cases (valid envelope JSON passes through unchanged + ExchangeMode::Envelope; non-JSON text synthesizes a request + ExchangeMode::PlainText, trailing newline trimmed, trailing spaces preserved); testable-core cases (envelope-mode success/error both Ok(()), response envelope on the output writer either way; plain-text success Ok(()) with raw body on the output writer; plain-text failure Ok(()) with zero bytes on the output writer — no stderr assertion here, see the nit above).
6. New tests/exchange_agent_cmd.rs: hermetic mock-HTTP-server proof (spawns the compiled leg binary per capture_child_output's mechanics — write stdin, close it, drain stdout to EOF, check exit code — against a hand-rolled std::net::TcpListener mock, no new dependency). Cases: (a) success → exit 0, stdout is exactly the mocked reply text; (b) mocked 401 → exit 0, empty stdout, non-empty stderr carrying the diagnostic — this is the actual machinery-failure signal ExternalAgentParticipant checks, and the one place the stderr diagnostic's content is asserted.
7. New scripts/external-agent-proof.sh (mirrors baton's own convention: not part of CI, real credentials, requires a local baton checkout): runs baton serve --agent-cmd <path-to-leg> --agent-arg exchange against a throwaway mailbox for both a normal turn and a deliberately-bad-credential turn, asserting the second lands in baton's own outbox as a delivered kind: "error" envelope (baton's own synthesis, triggered by leg's exit-0-empty-stdout signal) — the literal cross-repo AC3 proof.

Acceptance Criteria

• leg exchange reads a baton.message/v1 request envelope (--in/stdin) and writes a response envelope (--out/stdout) with a nested baton.exchange/v1 record on success, or a kind: "error" envelope on failure — both exiting 0, both Ok(()).
• leg exchange fed a plain-text prompt writes only the raw reply text to stdout on success (consumable by baton serve --agent-cmd <path> --agent-arg exchange with the default raw adapter, no extra flags); on a provider/delivery failure it writes nothing to stdout, diagnoses to stderr, exits 0, and still returns Ok(()) — the empty stdout is what lets baton's own machinery-error path deliver the kind: "error" envelope.
• execute_exchange never returns Err for a participant-delivered outcome (success or error) in either mode — only genuine --in/--out I/O failures do.
• tests/exchange_agent_cmd.rs hermetically proves both the success and empty-stdout machinery-failure signal, including the real stderr diagnostic, in CI; scripts/external-agent-proof.sh documents the real cross-repo kind: "error" proof.
• cargo test green; cargo clippy clean.

(developer)

[shukebeta]

[developer Implementation]

GitHub issue: #4
PR: #10
Branch: feat/issue-4-leg-exchange @ f6a1ccc

Design (matches approved plan v4)

leg exchange [--in <path>] [--out <path>] detects mode by attempting to
parse the whole input as a MessageEnvelope:

• Envelope mode (input parses as baton.message/v1): output is always
  the full JSON response/error envelope, including the nested
  baton.exchange/v1 provider record. Mirrors baton exchange.
• Plain-text mode (input is not a MessageEnvelope): the raw input
  becomes the request body of a synthesized Request envelope. On success,
  stdout is exactly response.body — matching baton's default raw output
  adapter, so baton serve --agent-cmd <leg-bin> --agent-arg exchange needs
  no extra flags. On provider/transport failure, stdout stays empty,
  the diagnostic goes to stderr, and execute_exchange still returns
  Ok(()) — no new LegError variant, no non-zero exit. This is
  sufficient: ExternalAgentParticipant::try_respond already treats
  exit-0-with-empty-stdout as a machinery failure and synthesizes its own
  kind: "error" envelope, independent of process exit code.

execute_exchange/execute_exchange_core remain uniformly infallible,
satisfying AC3 ("delivery errors ... never Err") in both modes.

Test coverage

• 11 new unit tests in src/cli.rs (mode detection, both output paths,
  --in/--out plumbing, arg-parsing errors) using existing FakeTransport
  test helpers.
• tests/exchange_agent_cmd.rs: hermetic process-boundary integration test.
  Spawns the compiled leg binary against a hand-rolled TcpListener
  HTTP/1.1 mock (no new crate deps), driving it exactly as
  capture_child_output does (write stdin, close, drain to EOF). Asserts
  plain-text success writes only the raw body, and plain-text provider
  failure exits 0 with empty stdout + diagnostic on stderr.
• scripts/external-agent-proof.sh: documented, non-CI, real-baton +
  real-credentials cross-repo proof (skips cleanly if BATON_BIN/creds are
  absent). Round A: real creds, asserts baton's outbox delivers
  kind:"response". Round B: deliberately bad API key, asserts baton's
  outbox delivers kind:"error" — proving the empty-stdout signal drives
  baton's own synthesized error path across the process boundary, not just
  leg's exit code.

Validation

cargo build, cargo test (118 lib + 2 integration + 0 doc, all green),
cargo clippy --all-targets -- -D warnings (clean), cargo fmt --check
(clean). Manually smoke-tested both modes against an unreachable endpoint:
envelope mode emits a full JSON error envelope (exit 0); plain-text mode
emits zero stdout bytes + stderr diagnostic (exit 0).

Tradeoffs / notes

• Envelope mode is proven only by unit tests, not the hermetic subprocess
  test — the hermetic test targets AC2 (the ExternalAgentParticipant
  path), which only exercises plain-text mode. Envelope-mode round-tripping
  through a real subprocess is exercised manually via the plan's own
  leg exchange < envelope.json walkthrough, not automated.
• scripts/external-agent-proof.sh requires a real baton checkout/binary
  and live credentials; it is intentionally excluded from CI, matching
  baton's own convention for this class of proof.
• Docs (README/architecture prose) are explicitly deferred to leg#6; only
  USAGE/--help were updated here, per the reviewer-accepted plan.

(developer)

[shukebeta]

[reviewer Review]

GitHub issue: #4

Context

• PR: feat(leg): add leg exchange command for baton external-agent integration #10
• Head: f6a1ccc
• Diff: scripts/external-agent-proof.sh (147 lines, executable), src/cli.rs (+314/-3), tests/exchange_agent_cmd.rs (160 lines)

Verdict

CHANGES REQUESTED

Acceptance criteria check

• AC1 — Envelope mode is covered by the in-memory core tests, but the actual --in/--out file plumbing and CLI process path are not tested; see Must fix.
• AC2 — Plain-text success emits the raw reply body, and plain-text failure leaves stdout empty while preserving the diagnostic, matching the approved baton raw machinery-error contract.
• AC3 — Participant outcomes remain Ok(()); envelope errors are emitted as full kind: "error" envelopes and plain-mode errors use the baton-compatible empty-stdout signal.
• AC4 — cargo test --all-targets passes (118 library + 2 integration tests), cargo clippy --all-targets -- -D warnings passes, and formatting/diff checks are clean.

Issues

Must fix

• src/cli.rs:427-439 adds the acceptance-critical --in/--out file path behavior, but every new process-boundary test in tests/exchange_agent_cmd.rs:47-159 invokes leg exchange with stdin/stdout only, and the unit tests only exercise argument parsing plus an in-memory Vec<u8> core. There is no test that reads a valid envelope from --in and writes the response envelope to --out, so AC1's file-based round-trip and the actual CLI wiring can regress unnoticed. Add a hermetic test using a unique temporary directory (and the existing mock provider) that runs the compiled binary with both flags, then parses the output file and asserts the response kind/body and nested baton.exchange/v1 schema; include the corresponding input/output I/O error assertion if the chosen test structure makes that path explicit.

Nits

• The process helper waits for the child to exit before draining stdout/stderr (tests/exchange_agent_cmd.rs:81-123), unlike the comment's claim that it drains while the child runs. The current fixtures are tiny, so this is non-blocking, but draining concurrently would make the helper robust against pipe-buffer deadlocks.

Hygiene

• No hygiene findings. The diff contains only the three expected files, the proof script is executable, git diff --check is clean, and no build artifacts, secret-shaped files, or debug residue were added.

(reviewer)

[shukebeta]

[developer Implementation]

GitHub issue: #4
PR: #10
Branch: feat/issue-4-leg-exchange @ 88f3665

Addresses review-exchange-impl-v1's Must fix + Nit:

• Must fix (AC1 file plumbing untested): added
  envelope_mode_round_trips_through_in_and_out_files to
  tests/exchange_agent_cmd.rs — runs the compiled binary with real
  --in/--out file paths (unique temp dir per run, no tempfile dep),
  writes a full baton.message/v1 request envelope to the input file,
  and asserts the output file's schema/kind/in_reply_to/body plus
  the nested baton.exchange/v1 outcome discriminator.
• Nit (drain-after-exit deadlock risk): WaitTimeoutOrKill now spawns a
  reader thread per pipe at process start, draining stdout/stderr
  concurrently with the wait loop instead of only after wait() returns.

Validation: cargo test --all-targets (118 lib + 3 integration, all
green), cargo clippy --all-targets -- -D warnings clean, cargo fmt --check clean.

(developer)