fix(bin): refuse unknown flags and stray --key arguments in fm-send

[twilwa]

Intent

Make bin/fm-send.sh refuse an unrecognised flag instead of silently delivering it as the message body.

This is Linear TES-60 in team Test, project Firstmate Software Factory. It is the top-ranked finding of the lint and directory-convention audit recorded at ~/firstmate/data/fw-lint-convention-audit/report.md (section 7), selected for implementation under the standing policy that agents may originate and prioritise small, evidence-backed work.

The defect, verified twice: bin/fm-send.sh:475-510 is the option loop. It handles --resolve-key, --resolve-key=, --fire-and-forget and --fire-and-forget=, and then ends in *) break ;; at line 509. Any other token - including one obviously shaped as a flag - breaks out of the loop and becomes the positional message text. The script's own documented contract at bin/fm-send.sh:4 is <target> [--resolve-key <key>]... [--fire-and-forget <id>] <text...>, so an unrecognised ---prefixed token is unambiguously a caller error, not text.

The recorded consequence, dated 2026-09-19 in the fleet learnings record and verified at the time by reading the resulting inbox record: a steer invoked with a flag that does not exist was durably written into a live worker's steering inbox as the literal flag string, and the script exited 0. The worker was mis-steered, and the caller got a success code and no diagnostic. This is the only entry in that whole record where the failure mode is silent, durable, and reaches a live worker; everything else in it fails loudly.

There is a trap, and it is the reason this task exists as a task rather than a one-line change. --key is a real, supported, in-use flag and it is parsed AFTER that loop, at bin/fm-send.sh:720, not inside it. The key plane deliberately relies on *) break ;; to reach itself. Cross-checks at lines 611, 720 and 723 reject --key in combination with --resolve-key and --fire-and-forget, so it is a first-class surface, not a legacy accident; it was used on 2026-09-20 to answer a blocking confirmation prompt in a running worker's session. A blanket "starts with -- and matched no case arm, therefore refuse" rule would break it. The refusal must be an allowlist of the flags this script genuinely accepts.

Boundaries. Change bin/fm-send.sh only, plus its tests. Do not sweep the other scripts that use the same *) break ;; shape - several of them take legitimate positional paths or URLs where the break is correct, and a blanket sweep is out of scope. Do not change the documented contract to fit the fix: if the regression guard for a legitimately leading-dash message conflicts with documented behaviour, stop and report that conflict instead. No new dependency, no CI change, no new scheduler or timer. One bounded session on existing subscription quota; no paid call, no purchase, no new account.

Follow-up round, decided after the first validation reached a PR. The pipeline's document step had added an 8-line block to the bin/fm-send.sh header and a 5-line rationale comment above the option loop, both recording the new no-end-of-flags-separator limitation in the source. Remove exactly those 13 lines and nothing else. The reason is deliberate and is not a style preference: the header block is that script's documented contract, and these instructions said not to amend that contract to fit the fix. Recording the limitation there amends it, and turns a deliberate narrow behaviour change into a documented guarantee the project would then owe. The rationale comment goes for the same reason the limitation was kept out of the source in the first place: it belongs in the PR description, where it describes a decision, not in the source, where it reads as a promise. The limitation is already stated in the PR description and stays there.

Everything else is already correct and must be preserved exactly: the pure allowlist in the option loop, the --key) break arm, the --*) refusal with no escape-hatch sentence in its message, the final *) break arm, no end-of-flags handling of any kind, both post-loop --key dispatch sites left unguarded with no new state variable, the unchanged usage line, and the single-dash case as the only leading-dash test. Do not re-document the limitation anywhere in the script, do not add a replacement comment explaining why the comment was removed, and do not widen the change to other scripts that share the same option-loop shape.

Third round, after a reviewer finding on the open pull request that is valid and was verified against the head it was raised on. The unknown-flag refusal was incomplete: it closed the silent-delivery hole in flag position but left an identical one on the --key path. Because the option loop breaks at --key without consuming what follows, and the key path reads only the key itself, every remaining argument was discarded in silence while the key was still delivered and the command still exited 0 - so fm-send.sh lane --key Enter --not-a-real-flag sent Enter and reported success. That is the same class of defect this whole change exists to remove, so the change contradicted its own contract on that one path. The same ordering also bypassed the --fire-and-forget incompatibility, because FIRE_AND_FORGET_ID is only set when that flag precedes --key and the adjacent guard globbed only for --resolve-key, so --key Enter --fire-and-forget x passed both checks.

Required result for this round: the key path validates or rejects every trailing argument before delivering the key, using the same refusal wording style already used for an unknown flag in flag position, and the --fire-and-forget/--key incompatibility holds regardless of argument order. Behavioral test coverage is required for both orderings, alongside the tests already added. Both new tests were confirmed to fail before the fix and pass after it, which is the intended regression shape and not an accident.

Scope is otherwise unchanged and must stay unchanged: bin/fm-send.sh and tests/fm-send-strict.test.sh only, no sweep of sibling scripts that share the same option-loop shape, no new dependency, no CI change. Everything established in the earlier rounds stays exactly as it is - the pure allowlist, the --key) break arm, the --*) refusal with no escape-hatch sentence, the final *) break arm, no end-of-flags separator or handling of any kind, the unchanged usage line, and the single-dash case as the only leading-dash test. Do not re-document the bare--- limitation in the script; it belongs in the pull request description, where it already is. A missing key argument (--key with nothing after it) already fails loudly under set -eu as an unbound-variable error and is deliberately left alone as out of scope for this round.

What Changed

• bin/fm-send.sh's option loop now matches an allowlist: --key breaks out to its existing post-loop parser, and any other ---prefixed token exits 1 with a diagnostic naming the token and the flags fm-send accepts, instead of falling through *) break ;; and being delivered as the message body. There is no end-of-flags separator, so a message whose first word starts with -- cannot be sent; a single-dash word is still plain text.
• The --key path now validates everything after the key instead of silently discarding it: a trailing argument is refused by name, and --fire-and-forget in that position is refused with the existing incompatibility error, so the --fire-and-forget/--key guard holds regardless of argument order.
• tests/fm-send-strict.test.sh gains five behavioral cases covering the unknown-flag refusal, --key still reaching the key plane with its --resolve-key and --fire-and-forget cross-checks intact, a leading single-dash message, trailing arguments after --key, and both --fire-and-forget/--key orderings — each asserting that no inbox record and no keystroke was produced, not just the exit code.

Risk Assessment

✅ Low: A 23-line, well-bounded tightening of one script's argument handling that satisfies every required intent criterion, refuses before any durable write on both traced orderings, breaks no in-repo call site, and carries behavioral regression tests for each new path.

Testing

Drove bin/fm-send.sh live against a real tmux server on a private socket with a real FM_HOME and real agent-classified pane occupants, running each scenario on twin panes against both the pre-fix base tree and the fixed HEAD so the contrast is observable rather than asserted. The original defect reproduced exactly as reported at base: an unrecognised flag exited 0, wrote the literal flag string into a live worker's steering inbox, and rang the doorbell into its pane; at HEAD the same command refuses with a named diagnostic and leaves no inbox record and no doorbell. The --key trap holds - --key Enter still delivers a genuine Enter into the live pane - while the trailing-argument hole and the --key-before---fire-and-forget bypass both now refuse and deliver no keystroke, each confirmed by pane echo-back counts rather than exit codes alone. Adversarial probes on near-miss flag spellings, --key=Enter, buried incompatible flags, both cross-check orderings, a non-flag trailing word, and the out-of-scope bare --key all refuse without delivering anything, and legitimate dash-bearing text, flag-shaped tokens in text position, --resolve-key and --fire-and-forget all still deliver verbatim. The repository's targeted tests/fm-send-strict.test.sh passes at HEAD, and running each new test individually against the base tree confirms the three defect-closing tests fail before the fix and pass after it. Only the tmux backend was driven, which is sufficient because both refusals run before backend validation and dispatch, so the parsing behaviour is backend-independent and no Herdr session or fleet pane was touched. This is a CLI change with no rendered UI, HTML or browser surface, so there is no screenshot or visual artifact; the closest end-user-visible surface is the worker's terminal pane, captured from the running tmux server into a dedicated evidence file. The lab tmux server and throwaway FM_HOME were torn down in the same turn and the worktree is clean.

• Live validation: ✅ go - 8 of 8 scenarios driven live against the product

Scenario	Result	Live	Evidence
unknown-flag-refused-not-delivered: an operator steers a worker with a flag that does not exist and gets a loud refusal instead of a silent mis-steer	✅ pass	live	fm-send-live-transcript.txt section S1. Base 9a0e566: fm-send.sh lane-ufA --not-a-real-flag steer the worker exited 0, wrote --not-a-real-flag steer the worker into state/lane-ufA.inbox/001.msg, a…
key-flag-still-reaches-the-live-pane: --key Enter still delivers a real keystroke and is not swallowed by the new allowlist	✅ pass	live	fm-send-live-transcript.txt section S2. Pane primed with an unsubmitted line (1 occurrence); fm-send.sh lane-kx --key Enter exited 0 and the occurrence count became 2, meaning the agent process rece…
trailing-argument-after-key-refused: --key Enter followed by an extra argument refuses instead of delivering the key and discarding the argument	✅ pass	live	fm-send-live-transcript.txt section S3. Base: lane-ktA --key Enter --not-a-real-flag exited 0 with pane echo count 2 - Enter delivered, extra argument silently discarded. HEAD: same command on twin…
fire-and-forget-with-key-refused-in-either-order: the --fire-and-forget/--key incompatibility holds regardless of argument order	✅ pass	live	fm-send-live-transcript.txt section S4. --fire-and-forget 0123456789abcdef --key Enter refuses with "error: --fire-and-forget cannot accompany --key" (exit 1). Reverse order at base: `--key Enter --…
legitimate-dash-text-still-delivers: a message whose text begins with a single dash, or contains a flag-shaped token in text position, is still sent verbatim	✅ pass	live	fm-send-live-transcript.txt section S5. lane-ld1 "-1 means failure, check the exit code" exited 0 and the inbox record holds the text verbatim. lane-ld2 please run the build --verbose and report e…
supported-flags-unaffected: --resolve-key and --fire-and-forget still deliver end to end	✅ pass	live	fm-send-live-transcript.txt section S6. lane-rk --resolve-key deploy yes, ship it exited 0 and recorded "yes, ship it" against the needs-decision key. `sm-ok --fire-and-forget 0123456789abcdef repor…
allowlist-boundary-probes: near-miss flag spellings and a bare -- are refused rather than slipping through as message text (adversarial)	✅ pass	live	fm-send-live-transcript.txt section S7. --resolve-keys, --key=Enter, --fire-and-forget-please and --Key each refuse with exit 1. The deliberate PR-documented limitation also holds: a message beginning…
key-path-adversarial-trailing-arguments: non-flag trailing words, buried incompatible flags and both cross-check orderings all refuse without delivering a keystroke (adversarial)	✅ pass	live	fm-send-live-transcript.txt section S8. --key Enter oops refuses a plain non-flag trailing word. An incompatible flag buried past the first trailing argument is caught in both spellings (`--key Ente…

Evidence: Live CLI transcript of all eight scenarios, with before/after contrast against the base commit

Source: Live CLI transcript of all eight scenarios, with before/after contrast against the base commit

fm-send unknown-flag refusal - live product transcript
worktree HEAD : 967427d   base: 9a0e566
product driven: bin/fm-send.sh against a real tmux server on a private socket,
                a real FM_HOME, and real agent-classified pane occupants.
======================================================================

\### S1  unknown-flag-refused-not-delivered
--- BEFORE (base 9a0e566): the reported defect, reproduced live ---
$ fm-send.sh lane-ufA --not-a-real-flag steer the worker
  exit=0
  durable record left in the live worker's steering inbox:
    schema=fm-task-inbox.v1
    at=2026-09-20T20:54:20Z
    --
    --not-a-real-flag steer the worker  doorbell lines rung into the live worker pane: 2

--- AFTER (HEAD): identical command, twin pane ---
$ fm-send.sh lane-ufB --not-a-real-flag steer the worker
error: unknown flag '--not-a-real-flag'; fm-send accepts --resolve-key, --fire-and-forget, and --key. Nothing was sent.
  exit=1
  steering inbox:
    (no steering record exists for lane-ufB)
  doorbell lines rung into the live worker pane: 0

\### S2  key-flag-still-reaches-the-live-pane  (the allowlist trap)
  priming the live pane with an unsubmitted line, so a real Enter is observable
  occurrences before the send: 1  (1 = typed, not yet submitted)
$ fm-send.sh lane-kx --key Enter
  exit=0
  occurrences after the send : 2  (2 = the agent received a real Enter and echoed the line back)

\### S3  trailing-argument-after-key-refused
--- BEFORE (base 9a0e566) ---
$ fm-send.sh lane-ktA --key Enter --not-a-real-flag
  exit=0
  pane echo count: 2  (2 = Enter delivered, extra argument silently discarded)
--- AFTER (HEAD) ---
$ fm-send.sh lane-ktB --key Enter --not-a-real-flag
error: unexpected argument '--not-a-real-flag' after '--key Enter'; --key takes exactly one key and nothing else. Nothing was sent.
  exit=1
  pane echo count: 1  (1 = no keystroke was delivered)

\### S4  fire-and-forget-with-key-refused-in-either-order
--- order: --fire-and-forget before --key (guard pre-existed) ---
$ fm-send.sh sm-ffB --fire-and-forget 0123456789abcdef --key Enter
error: --fire-and-forget cannot accompany --key
  exit=1
--- order: --key before --fire-and-forget (the bypass this round closes) ---
  BEFORE (base 9a0e566):
$ fm-send.sh sm-ffA --key Enter --fire-and-forget 0123456789abcdef
  exit=0
  pane echo count: 2  (2 = Enter delivered despite the incompatible flag)
  AFTER (HEAD):
$ fm-send.sh sm-ffB --key Enter --fire-and-forget 0123456789abcdef
error: --fire-and-forget cannot accompany --key
  exit=1
  pane echo count: 1  (1 = nothing delivered)

\### S5  legitimate-dash-text-still-delivers
$ fm-send.sh lane-ld1 -1 means failure, check the exit code
  exit=0
  delivered record:
    schema=fm-task-inbox.v1
    at=2026-09-20T20:54:32Z
    --
    -1 means failure, check the exit code$ fm-send.sh lane-ld2 please run the build --verbose and report
  exit=0
  delivered record (a flag-shaped token in text position stays text):
    schema=fm-task-inbox.v1
    at=2026-09-20T20:54:35Z
    --
    please run the build --verbose and report
\### S6  supported-flags-unaffected
$ fm-send.sh lane-rk --resolve-key deploy yes, ship it
  exit=0
  delivered record:
    schema=fm-task-inbox.v1
    at=2026-09-20T20:54:37Z
    --
    yes, ship it$ fm-send.sh sm-ok --fire-and-forget 0123456789abcdef report your findings
  exit=0
  delivered record:
    schema=fm-task-inbox.v1
    at=2026-09-20T20:54:39Z
    delivery=fire-and-forget
    --
    [fm-from-firstmate]⁣delivery=0123456789abcdef report your findings
\### S7  allowlist-boundary-probes  (adversarial)
--- near-miss spellings of real flags must not slip through as message text ---
$ fm-send.sh lane-ld3 --resolve-keys deploy answer
error: unknown flag '--resolve-keys'; fm-send accepts --resolve-key, --fire-and-forget, and --key. Nothing was sent.
  exit=1
$ fm-send.sh lane-ld3 --key=Enter
error: unknown flag '--key=Enter'; fm-send accepts --resolve-key, --fire-and-forget, and --key. Nothing was sent.
  exit=1
$ fm-send.sh lane-ld3 --fire-and-forget-please 0123456789abcdef hello
error: unknown flag '--fire-and-forget-please'; fm-send accepts --resolve-key, --fire-and-forget, and --key. Nothing was sent.
  exit=1
$ fm-send.sh lane-ld3 --Key Enter
error: unknown flag '--Key'; fm-send accepts --resolve-key, --fire-and-forget, and --key. Nothing was sent.
  exit=1
--- deliberate, PR-documented limitation: text beginning with -- is refused ---
$ fm-send.sh lane-ld3 -- please treat this as text
error: unknown flag '--'; fm-send accepts --resolve-key, --fire-and-forget, and --key. Nothing was sent.
  exit=1
  (no steering record exists for lane-ld3)

\### S8  key-path-adversarial-trailing-arguments
$ fm-send.sh lane-kx --key Enter oops
error: unexpected argument 'oops' after '--key Enter'; --key takes exactly one key and nothing else. Nothing was sent.
  exit=1
$ fm-send.sh lane-kx --key Enter one two --fire-and-forget 0123456789abcdef
error: --fire-and-forget cannot accompany --key
  exit=1
$ fm-send.sh lane-kx --key Enter one two --fire-and-forget=0123456789abcdef
error: --fire-and-forget cannot accompany --key
  exit=1
$ fm-send.sh lane-kx --resolve-key deploy --key Enter
error: --resolve-key cannot accompany --key; answering a decision requires a text answer
  exit=1
$ fm-send.sh lane-kx --key Enter --resolve-key deploy
error: --resolve-key cannot accompany --key; answering a decision requires a text answer
  exit=1
--- out-of-scope boundary: --key with no key must still fail loudly, not deliver ---
$ fm-send.sh lane-kx --key
~/.no-mistakes/worktrees/8be14fbb8fb5/01M308WHWJ1496H3CECCZ8RHZM/bin/fm-send.sh: line 795: $2: unbound variable
  exit=1
  pane echo count for PROBE-ALPHA: 2  (still 2 from S2: no adversarial call delivered a further keystroke)

======================================================================
end of transcript

Evidence: Captures of the live tmux worker panes, showing the mis-steer doorbell that reached the worker at base and the untouched pane at HEAD

Source: Captures of the live tmux worker panes, showing the mis-steer doorbell that reached the worker at base and the untouched pane at HEAD

Live worker panes after the evidence run
========================================

The steering inbox and the doorbell are what actually reach a worker, so
these are the panes themselves, captured from the running tmux server.

--- S1 BEFORE (base 9a0e566): fm-send.sh lane-ufA --not-a-real-flag steer the worker
    the worker was rung, and the record it was told to read is the literal flag string
    | : Firstmate instruction waiting: list '/tmp/fmsend-evidence-777998/home/state/la
    | ne-ufA.inbox'/*.msg and, in numeric order, read and act on each, then mv each ha
    | ndled file to '/tmp/fmsend-evidence-777998/home/state/lane-ufA.inbox'/handled/.
    | : Firstmate instruction waiting: list '/tmp/fmsend-evidence-777998/home/state/la
    | ne-ufA.inbox'/*.msg and, in numeric order, read and act on each, then mv each ha
    | ndled file to '/tmp/fmsend-evidence-777998/home/state/lane-ufA.inbox'/handled/.

--- S1 AFTER (HEAD): identical command against the twin pane fm-lane-ufB
    the pane is untouched; nothing was rung and nothing was recorded
    | (empty - no doorbell was ever typed)

--- S3 BEFORE (base): fm-send.sh lane-ktA --key Enter --not-a-real-flag
    the primed line is echoed back, so a real Enter was submitted while the extra argument vanished
    | PROBE-BETA-unsubmitted-line
    | PROBE-BETA-unsubmitted-line

--- S3 AFTER (HEAD): identical command against the twin pane fm-lane-ktB
    the primed line appears once only, so no keystroke was delivered
    | PROBE-BETA-unsubmitted-line

Evidence: The reported defect reproduced live at base and closed at HEAD

$ fm-send.sh lane-ufA --not-a-real-flag steer the worker # base 9a0e566
exit=0
durable record left in the live worker's steering inbox:
schema=fm-task-inbox.v1
--
--not-a-real-flag steer the worker
doorbell lines rung into the live worker pane: 2

$ fm-send.sh lane-ufB --not-a-real-flag steer the worker # HEAD 967427d
error: unknown flag '--not-a-real-flag'; fm-send accepts --resolve-key, --fire-and-forget, and --key. Nothing was sent.
exit=1
steering inbox:
(no steering record exists for lane-ufB)
doorbell lines rung into the live worker pane: 0

Evidence: The --key trailing-argument hole this round closes, observed by keystroke echo-back in the live pane

$ fm-send.sh lane-ktA --key Enter --not-a-real-flag # base 9a0e566
exit=0
pane echo count: 2 (Enter delivered, extra argument silently discarded)

$ fm-send.sh lane-ktB --key Enter --not-a-real-flag # HEAD 967427d
error: unexpected argument '--not-a-real-flag' after '--key Enter'; --key takes exactly one key and nothing else. Nothing was sent.
exit=1
pane echo count: 1 (no keystroke was delivered)

Evidence: The --fire-and-forget/--key ordering bypass, before and after

$ fm-send.sh sm-ffA --key Enter --fire-and-forget 0123456789abcdef # base 9a0e566
exit=0
pane echo count: 2 (Enter delivered despite the incompatible flag)

$ fm-send.sh sm-ffB --key Enter --fire-and-forget 0123456789abcdef # HEAD 967427d
error: --fire-and-forget cannot accompany --key
exit=1
pane echo count: 1 (nothing delivered)

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

⚠️ **Review** - 4 infos

• ℹ️ bin/fm-send.sh:787 - The --fire-and-forget/--key incompatibility now refuses on both orderings, as the intent requires, but the diagnostic differs. Key-first (lane --key Enter --fire-and-forget 0123456789abcdef) reaches the new scan at :784 and reports 'error: --fire-and-forget cannot accompany --key'. Flag-first against a target whose meta kind is not secondmate (lane --fire-and-forget 0123456789abcdef --key Enter) never gets that far: FIRE_AND_FORGET_ID is set by the option loop, so the validation block at :603 runs first and exits at :611 with 'error: --fire-and-forget requires a recorded secondmate task selector'. Both refuse before delivery and both exit 1, so the required invariant holds; only the wording is asymmetric, and the :603 ordering is pre-existing and untouched by this change. Noted for awareness, not for action.
• ℹ️ bin/fm-send.sh:768 - The literal 'error: --fire-and-forget cannot accompany --key' now exists twice, at :768 (flag consumed by the option loop, detected via FIRE_AND_FORGET_ID) and :787 (flag left unparsed after --key, detected by scanning "${@:3}"). That is a parallel copy of one rule, but it is required: the two sites see different state because --key) break deliberately leaves everything after it unconsumed, and the intent requires the incompatibility to hold on both orderings with a test asserting this exact wording. No narrower form preserves both. Flagged only so a future edit to either message keeps them in sync; the test at tests/fm-send-strict.test.sh:361-369 pins both.
• ℹ️ tests/fm-send-strict.test.sh:339 - The second case of test_trailing_arguments_after_key_are_refused (lane-kt --key Enter stray) asserts only a nonzero exit and the absence of 'literal=0 arg=Enter' in the tmux log. Any unrelated early failure on this invocation would satisfy both, so the case can pass without proving the trailing-argument refusal ran. The first case of the same test pins the refusal via its '--not-a-real-flag' assertion, so the gap is narrow. Concrete remedy: add assert_contains "$(cat "$err")" "unexpected argument 'stray'" after line 341, matching the message emitted at bin/fm-send.sh:792.
• ℹ️ bin/fm-send.sh:777 - Recorded for transparency because source commentary in this file has been the subject of two explicit user decisions. The change adds a 6-line rationale comment at :777-782. It explains why the trailing-argument check exists (the option loop breaks at --key without consuming what follows, and this path reads only the key) and why --fire-and-forget is named again there. It does not mention the bare--- limitation, the flag allowlist, the absent end-of-flags separator, or the removal of the earlier comment, so it does not re-document what round 2 required removing and does not amend the header contract at :4, which is byte-identical to the base. No action proposed.

✅ **Test** - passed

✅ No issues found.

• Live validation: ✅ go - 8 of 8 scenarios driven live against the product

Scenario	Result	Live	Evidence
unknown-flag-refused-not-delivered: an operator steers a worker with a flag that does not exist and gets a loud refusal instead of a silent mis-steer	✅ pass	live	fm-send-live-transcript.txt section S1. Base 9a0e566: fm-send.sh lane-ufA --not-a-real-flag steer the worker exited 0, wrote --not-a-real-flag steer the worker into state/lane-ufA.inbox/001.msg, a…
key-flag-still-reaches-the-live-pane: --key Enter still delivers a real keystroke and is not swallowed by the new allowlist	✅ pass	live	fm-send-live-transcript.txt section S2. Pane primed with an unsubmitted line (1 occurrence); fm-send.sh lane-kx --key Enter exited 0 and the occurrence count became 2, meaning the agent process rece…
trailing-argument-after-key-refused: --key Enter followed by an extra argument refuses instead of delivering the key and discarding the argument	✅ pass	live	fm-send-live-transcript.txt section S3. Base: lane-ktA --key Enter --not-a-real-flag exited 0 with pane echo count 2 - Enter delivered, extra argument silently discarded. HEAD: same command on twin…
fire-and-forget-with-key-refused-in-either-order: the --fire-and-forget/--key incompatibility holds regardless of argument order	✅ pass	live	fm-send-live-transcript.txt section S4. --fire-and-forget 0123456789abcdef --key Enter refuses with "error: --fire-and-forget cannot accompany --key" (exit 1). Reverse order at base: `--key Enter --…
legitimate-dash-text-still-delivers: a message whose text begins with a single dash, or contains a flag-shaped token in text position, is still sent verbatim	✅ pass	live	fm-send-live-transcript.txt section S5. lane-ld1 "-1 means failure, check the exit code" exited 0 and the inbox record holds the text verbatim. lane-ld2 please run the build --verbose and report e…
supported-flags-unaffected: --resolve-key and --fire-and-forget still deliver end to end	✅ pass	live	fm-send-live-transcript.txt section S6. lane-rk --resolve-key deploy yes, ship it exited 0 and recorded "yes, ship it" against the needs-decision key. `sm-ok --fire-and-forget 0123456789abcdef repor…
allowlist-boundary-probes: near-miss flag spellings and a bare -- are refused rather than slipping through as message text (adversarial)	✅ pass	live	fm-send-live-transcript.txt section S7. --resolve-keys, --key=Enter, --fire-and-forget-please and --Key each refuse with exit 1. The deliberate PR-documented limitation also holds: a message beginning…
key-path-adversarial-trailing-arguments: non-flag trailing words, buried incompatible flags and both cross-check orderings all refuse without delivering a keystroke (adversarial)	✅ pass	live	fm-send-live-transcript.txt section S8. --key Enter oops refuses a plain non-flag trailing word. An incompatible flag buried past the first trailing argument is caught in both spellings (`--key Ente…

• bin/fm-send.sh lane-ufB --not-a-real-flag steer the worker against a live tmux worker pane, compared with the same command run from a git archive 9a0e566 base tree on a twin pane
• bin/fm-send.sh lane-kx --key Enter with a primed unsubmitted pane line to observe real keystroke delivery via echo-back
• bin/fm-send.sh lane-ktB --key Enter --not-a-real-flag and the base-tree equivalent on twin panes
• bin/fm-send.sh sm-ffB --key Enter --fire-and-forget 0123456789abcdef and bin/fm-send.sh sm-ffB --fire-and-forget 0123456789abcdef --key Enter, plus the base-tree reverse-order bypass
• bin/fm-send.sh lane-ld1 "-1 means failure, check the exit code" and bin/fm-send.sh lane-ld2 please run the build --verbose and report
• bin/fm-send.sh lane-rk --resolve-key deploy yes, ship it and bin/fm-send.sh sm-ok --fire-and-forget 0123456789abcdef report your findings
• Adversarial probes: --resolve-keys, --key=Enter, --fire-and-forget-please, --Key, bare --, --key Enter oops, --key Enter one two --fire-and-forget[=]x, both --resolve-key/--key orderings, and bare --key
• bash tests/fm-send-strict.test.sh at HEAD (13 ok, exit 0)
• Each new test run individually against the base tree to confirm regression shape: test_unknown_flag_is_refused_before_anything_is_recorded, test_trailing_arguments_after_key_are_refused and test_fire_and_forget_with_key_is_refused_in_either_order fail at base and pass at HEAD

⚠️ **Document** - 1 info

• ℹ️ bin/fm-send.sh:464 - Recorded as a judgment call, not proposed for action. docs/scripts.md:4 makes each script's header the authoritative owner of its flags and contracts, and this round's new strictness (a trailing argument after --key is refused, and --fire-and-forget/--key is incompatible in either order) is not described there, so the authoritative owner again under-describes current behaviour. That is the standing user decision on this branch: the earlier document commit's 13 header/comment lines were removed by c5ae283 precisely so a narrow behaviour change does not become a documented guarantee, and the intent for this round repeats 'do not re-document ... in the script'. Relatedly, the pre-existing comment at bin/fm-send.sh:463-465 ('everything after the last flag is the message exactly as before, so ordinary sends are byte-identical') became over-broad with the allowlist in b45538e, since a message token beginning with -- is now refused rather than treated as text. Correcting that clause would state the bare--- limitation in the source, which the recorded decision forbids, so it was left exactly as it is. No documentation edit was made and none is proposed; if the project later wants the flag contract documented, the header is the single owner to update. Everything else audited clean: the header's --key usage line (:14) and --resolve-key refusal list (:207) remain accurate, docs/scripts.md:115's purpose row is unaffected, every documented fm-send invocation across docs/, AGENTS.md and .agents/skills/ uses only --resolve-key, --fire-and-forget or a single-key --key (AGENTS.md:335, docs/agent-control.md:23, docs/captain-hold-lifecycle.md:59, docs/remote-secondmates.md:178, docs/pi-supervision-branch.md:61,173, docs/verification/runtime-backends.md:1640), README.md and CONTRIBUTING.md never mention fm-send, docs/fm-test-isolation-proof.md/.json are dated 2026-08-20 verification evidence, and the tests/fm-send-strict.test.sh shard weight at bin/fm-test-run.sh:520 is code and explicitly drift-tolerant per docs/fm-test-portable-shards.md:65.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

[sourcery-ai]

Reviewer's Guide

This PR hardens fm-send.sh option parsing with an allowlist that refuses unknown double-dash flags before any durable or terminal delivery side effects, while explicitly preserving the later --key parsing plane and existing accepted-flag behavior. It updates the CLI contract and adds strict regression tests covering refusal side effects, cross-check diagnostics, and single-dash text handling; reviewers should note the intentional incompatibility with messages whose first word begins with --.

Sequence diagram for refusing an unknown fm-send flag

sequenceDiagram
    actor Operator
    participant FmSend as fm-send.sh
    participant Inbox
    participant Worker as Worker terminal

    Operator->>FmSend: fm-send.sh target --dry-run message
    FmSend->>FmSend: Inspect option loop
    FmSend-->>Operator: error: unknown flag '--dry-run'
    FmSend-->>Operator: Exit 1
    Note over Inbox,Worker: No inbox record and no doorbell ring

Loading

Sequence diagram for preserved --key delivery

sequenceDiagram
    actor Operator
    participant FmSend as fm-send.sh
    participant KeyPlane as --key parsing plane
    participant Worker as Worker terminal

    Operator->>FmSend: fm-send.sh target --key Enter
    FmSend->>KeyPlane: Break from option loop
    KeyPlane->>Worker: Submit Enter
    Worker-->>Operator: Exit 0

Loading

State diagram for fm-send argument interpretation

stateDiagram-v2
    [*] --> FlagPosition
    FlagPosition --> FlagPosition: --resolve-key / --fire-and-forget
    FlagPosition --> KeyPlane: --key
    FlagPosition --> Refused: Other --token
    FlagPosition --> MessageStarted: Text or single-dash word
    KeyPlane --> [*]
    Refused --> [*]
    MessageStarted --> MessageStarted: Additional tokens, including --token
    MessageStarted --> Delivered: Write record and ring doorbell
    Delivered --> [*]

Loading

Flow diagram for strict fm-send flag parsing

flowchart TD
    A[fm-send target and arguments] --> B{Option loop token}
    B -->|--resolve-key or --fire-and-forget| C[Consume accepted flag]
    C --> B
    B -->|--key| D[Break to key plane]
    D --> E[Parse --key and run key delivery]
    B -->|Other --token| F[Print unknown-flag error]
    F --> G[Exit 1 with no record or doorbell]
    B -->|Message text or single-dash word| H[Build message]
    H --> I[Write inbox record and ring doorbell]

Loading

File-Level Changes

Change	Details	Files
Changed option parsing from permissive fall-through to an explicit allowlist for flags encountered before message text.	Preserve --key as a deliberate fall-through to the later key-parsing plane. Reject other ---prefixed tokens with a nonzero status and an error listing the accepted flags. Ensure rejection occurs before inbox persistence or terminal doorbell delivery.	bin/fm-send.sh
Documented the revised flag and message parsing behavior.	Identify --resolve-key, --fire-and-forget, and --key as the supported flags. Clarify that single-dash words remain text and flag-shaped tokens after message text remain part of the message. Document that a message beginning with -- is intentionally not sendable because there is no end-of-flags separator.	bin/fm-send.sh
Added regression coverage for refusal behavior and preservation of existing CLI surfaces.	Verify unknown flags fail, name the offending token, create no inbox record, and ring no doorbell. Verify --key remains functional and its incompatibility diagnostics with other control flags are preserved. Verify single-dash message text is sent and recorded verbatim.	tests/fm-send-strict.test.sh

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-20T21:16:30.452906Z	967427d	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8367b9ee51

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Reject trailing options after --key

When an invocation puts another option after the key, such as fm-send.sh lane --key Enter --not-a-real-flag, this arm immediately stops option parsing; the key path later reads only $2, silently ignores the remaining arguments, sends Enter, and exits successfully. The same ordering also bypasses the intended --fire-and-forget/--key incompatibility. This contradicts the new contract that unknown flags in flag position are refused, so the --key path should validate or reject all trailing arguments before delivering the key.

Useful? React with 👍 / 👎.

[twilwa]

Review disposition for head c5ae2836, under this repository's low/high-stakes review and merge policy.

Classification: low stakes. Bounded, additive argument validation in one script plus tests; no security, data-loss, public-interface, or production impact; fully reversible.

Reviews inspected: Sourcery (id 5260853510) and Codex (id 5260856373), both submitted against 8367b9ee51. The single commit between that SHA and the current head is comment-only (0 additions, 13 deletions, no test changes), so both reviews do cover the live code.

• Sourcery: no findings.
• Codex, inline on bin/fm-send.sh:518, P2 "Reject trailing options after --key": valid, accepted, being fixed. Verified against c5ae2836: fm-send.sh <target> --key Enter --not-a-real-flag hits the --key) break arm, the key path reads only $2, the remaining arguments are discarded, Enter is sent, and the command exits 0. That is the same silent-delivery class this PR removes, so the change currently contradicts its own contract on that path. The same ordering also bypasses the --fire-and-forget/--key incompatibility, since FIRE_AND_FORGET_ID is set only when that flag precedes --key and the case "$*" guard checks only --resolve-key.

Not merging on this head. The fix and its behavioural coverage for both argument orderings are in progress. The resulting code change invalidates the checks and reviews that were green on c5ae2836; validation runs again and reviewers get their time on the new head before any merge decision.

[twilwa]

@codex review

Requesting a fresh review on the current head 967427d9. Your earlier review was against 8367b9ee51, two heads back, and does not cover the change made in response to it.

Context for the re-review: the P2 finding you raised was reproduced before anything was changed, and confirmed valid on head c5ae2836 — fm-send.sh lane --key Enter --not-a-real-flag exited 0 and delivered the key while silently discarding the trailing token, and --key Enter --fire-and-forget x passed both guards because the fire-and-forget guard only fires when the flag precedes --key and the sibling guard tested only for --resolve-key. The --key path now refuses any trailing argument before delivering, names the offending token in the same wording as the unknown-flag refusal, and names --fire-and-forget explicitly so the incompatibility holds in either argument order. Both regression tests were written first and verified to fail on the unfixed script.

The specific thing worth your attention is whether the refusal is now complete in both argument orderings, and whether any legitimate caller shape is now rejected that should not be.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Hooray!

Reviewed commit: 967427d903

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[twilwa]

Final review disposition for head 967427d90326fd409cec6c3a1237a23a6bb75b02.

Risk classification: low stakes. The change is 167 additions and 0 deletions across two files — 23 lines of argument validation in bin/fm-send.sh and a 144-line test file. It is purely additive, tightens input handling rather than loosening it, and its failure mode is a refusal that sends nothing. No security, data-loss, public-interface, or production-infrastructure surface is touched.

Reviewer coverage of this exact head:

• Sourcery: review check completed 2026-09-20T21:12:28Z, no blocking security issues.
• Codex: review completed 2026-09-20T21:16:29Z against 967427d903, no major issues found.

Findings: the earlier P2 finding on head 8367b9ee51 was reproduced before anything was changed and confirmed valid on c5ae2836. The fix refuses a trailing argument on the --key path before delivering and names --fire-and-forget explicitly so the incompatibility holds in either argument order. Both regression tests were written first and verified to fail against the unfixed script. No findings were rejected, so there is no rejected-finding evidence to record.

Checks: 22 of 22 completed successfully at this head, including the PR must be raised via no-mistakes gate and the portable behavior shards. Merge state is clean with no conflicts.

Merging under the standing low-stakes authorization. The head is verified immediately before the merge and bound to it, so any push landing in between fails the merge rather than landing unverified commits.