fix(bin): derive --help usage output from header content instead of hard-coded line ranges

[pramendra]

Intent

Fix bin/fm-afk-launch.sh --help, which silently truncates its own Usage block. The usage function prints help by slicing its own file header with a hard-coded line range (sed -n '2,34p'); the header has grown past line 34, so --help cuts the stop entry off mid-sentence and never shows the reconcile entry. This is pre-existing at the base commit, not introduced by any branch.

Acceptance criteria:

1. bin/fm-afk-launch.sh --help prints the complete Usage block, with stop whole and reconcile present.
2. The fix must not be another hard-coded line number; derive the range from content (print from the header start until the first line that is no longer part of the comment block) so the help stays correct when a maintainer adds a header line.
3. Add a check/test that fails if printed help ever stops containing every entry the header declares - it must catch a future truncation, not merely match today's output.
4. Check sibling scripts in bin/ for the same help pattern; fix those that share the exact defect only when the fix is mechanically identical and adds no risk, and say which were fixed.
5. Repo conventions: bash with set -euo pipefail, 2-space indent, shellcheck-clean, one sentence per line in prose, no agent co-author trailer.

Decisions made while implementing: I used the awk idiom already established elsewhere in the repo (print the header comment until the first non-comment line) to derive the range from content. I fixed the four siblings that share the exact truncation defect - fm-afk-start.sh, fm-afk-return.sh, fm-herdr-lab.sh, and fm-procevent-when.sh - with the identical mechanical change, and left fm-procevent.sh and fm-procevent-lavish.sh untouched because their hard-coded ranges are still in sync with their headers. The regression test derives the declared subcommands from the header's Usage block and asserts --help prints each one, so any future truncation fails the suite.

Delivery: push through the no-mistakes gate (fork pramendra/firstmate, PR against origin kunchenguid/firstmate); do not hand-open a PR and do not merge.

What Changed

• bin/fm-afk-launch.sh's fm_afk_launch_usage replaced its hard-coded sed -n '2,34p' slice with an awk idiom that prints the header comment block from line 2 until the first non-comment line, so --help prints the full Usage block (including the stop and reconcile entries) regardless of header length.
• Applied the identical mechanical fix to 13 sibling scripts whose usage/-h|--help handlers had the same hard-coded-range defect: fm-afk-return.sh, fm-afk-start.sh, fm-herdr-lab.sh, fm-inactive-reconcile.sh, fm-kimi-turnend-hook.sh, fm-on.sh, fm-procevent-remote-reply.sh, fm-procevent-when.sh, fm-remote-delta-read.sh, fm-remote-doctor.sh, fm-remote-home-seed.sh, fm-remote-secondmate-control.sh, and fm-startup-memory-budget.sh.
• Added unit_usage_prints_complete_header to tests/fm-afk-launch.test.sh, which derives the declared subcommands and final header line from the script's own header and asserts --help output contains all of them, catching future truncation instead of pinning today's output.
• Added .serena/ to .gitignore.

Risk Assessment

✅ Low: The fix correctly replaces hard-coded sed line-ranges with a content-derived awk idiom in fm-afk-launch.sh and 13 sibling scripts, all of which were verified to have had a genuine header/range mismatch before the fix; a scan of the remaining bin/ scripts using the same sed pattern (fm-remote-file.sh, fm-lint.sh, fm-lint-workflows.sh, fm-remote-inherit.sh, fm-backlog-receive.sh, fm-stow-cascade.sh, fm-procevent.sh, fm-procevent-lavish.sh) confirms their ranges are still in sync with their headers, so no further sibling was missed; the new regression test executes the real --help output and derives expectations from the header via the same boundary rule, correctly reproducing the reported truncation before the fix and passing after; shellcheck shows only pre-existing, unrelated SC1091/SC2034 notices; a follow-on commit expanded the sibling-fix scope beyond the four originally named and a further commit cleaned up an accidentally committed .serena config, both of which are net improvements consistent with the stated acceptance criteria.

Testing

Ran the targeted fm-afk-launch.test.sh suite (57/57 pass) and manually exercised bin/fm-afk-launch.sh --help end-to-end, confirming the previously truncated stop entry now prints whole and reconcile now appears; also proved the new regression test genuinely catches the original defect by re-running it against the base commit's unfixed script (it failed exactly as expected) before restoring the fix (it passed). Spot-checked two of the additional sibling scripts fixed by the automated review pass and confirmed their --help output is no longer truncated. No findings — all acceptance criteria are satisfied and the working tree is clean of test artifacts.

Evidence: fm-afk-launch.sh --help full output (post-fix)

Usage:
fm-afk-launch.sh start ...
fm-afk-launch.sh start-native ...
fm-afk-launch.sh stop Correct-ordered exit: SIGTERM the daemon so its
cleanup flushes WHILE state/.afk is still present,
wait for it, close the recorded terminal by exact
id, then clear state/.afk last.
fm-afk-launch.sh reconcile Close a recorded-but-dead daemon terminal by exact
id and drop the record (recovery after a crash).
...
Test seam: FM_AFK_LAUNCH_ENTRY overrides the command run in the created
terminal (default bin/fm-afk-start.sh) ... FM_SUPERVISOR_TARGET/FM_SUPERVISOR_BACKEND
override the captured captain pane/backend (an isolated lab pane in tests).
EXIT:0

Evidence: Regression proof: test fails against pre-fix sed -n '2,34p' script, passes after fix

Against base commit's script:
not ok - usage: declared subcommand 'reconcile' missing from --help (truncated header)
not ok - usage: header truncated before its final line (override the captured captain pane/backend (an isolated lab pane in tests).)

After restoring target commit's fix:
ok - usage: declared subcommand 'reconcile' present in --help
ok - usage: header prints through its final line

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

✅ **Review** - passed

✅ No issues found.

✅ **Test** - passed

✅ No issues found.

• bash tests/fm-afk-launch.test.sh — 57/57 pass, 0 failures, exit 0, including the 5 new usage-completeness assertions
• Manual: FM_HOME=<tmp> FM_STATE_OVERRIDE=<tmp>/state bin/fm-afk-launch.sh --help — confirmed full header prints, stop entry ends whole, reconcile entry present (both were previously cut off by the sed -n '2,34p' slice)
• Regression proof: swapped in the base commit's fm-afk-launch.sh (pre-fix sed -n '2,34p') and reran the test suite — the two new usage assertions failed as expected (reconcile missing, header truncated), then restored the target commit's file and reran to confirm they pass — proves the test is a real regression catch, not a tautology
• Manual spot-check of two of the newly-fixed siblings from the review commit: bin/fm-startup-memory-budget.sh --help and bin/fm-on.sh --help both print their full header text without truncation
• Reviewed full diff (8714c9a..aa9dbb7) across all 3 commits to confirm every sibling fix uses the identical awk idiom, the cleanup commit correctly removes accidentally-committed .serena/ config unrelated to the fix, and the final test hardening removed a previously hard-coded content match (the literal 'stop' sentence) in favor of deriving expectations from the header content itself

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge, with no concrete changed-code defect identified.

The new awk implementation correctly reads each changed script’s contiguous leading comment block, preserves existing help control flow, and the targeted regression test covers the reported truncation.

_{Reviews (1): Last reviewed commit: "no-mistakes(document): Document new --he..." | Re-trigger Greptile}