mosaicstack/stack
1
0
Fork 0
Code Issues 42 Pull Requests Actions Packages Projects Releases 15 Wiki Activity

git wrappers: -h/--help prints help but exits 1 (7 scripts) — phantom tool errors fleet-wide #701

New Issue
Closed
opened 2026-07-11 08:53:33 +00:00 by jason.woltje · 0 comments
jason.woltje commented 2026-07-11 08:53:33 +00:00
Owner
Copy Link

Defect

usage() in 7 framework git wrappers hard-codes exit 1 (one deployed-only script exits 2), so the documented -h / --help flags print correct help text but return a failure exit code.

Affected (verified on stack main @ 4df38f7e, packages/mosaic/framework/tools/git/):

script usage() exit
issue-assign.sh 1
issue-create.sh 1
issue-list.sh 1
milestone-create.sh 1
pr-create.sh 1
pr-list.sh 1
pr-merge.sh 1
lane-brief.sh (deployed-only, NOT in SSOT) 2

All other wrappers in the directory already exit 0 on -h/--help.

Evidence (fleet impact, 2026-07-11 nightly digest)

3 worker sessions (pi runtime, coder lanes restarted 2026-07-10 18:00) ran ~/.config/mosaic/tools/git/pr-create.sh --help as due diligence before first use. Help printed correctly, exit was 1, so the runtime recorded isError:true — 7 phantom tool-error records in one night attributed to a wrapper that behaved exactly as documented. Transcript proof: /home/hermes/.pi/agent/sessions/--src-jarvis-brain--/2026-07-10T18-00-27-202Z_019f4d30-1f42-*.jsonl (calls at 20:19:01Z, 21:22:54Z).

Why it matters (blast radius)

  • Every fleet lane is told "wrappers first" (AGENTS.md rule 27) and reasonably checks --help before first use → each check logs a failure.
  • Pollutes nightly fleet-enhancement digests with false error signal (this is how it was found).
  • Nonzero exits can trigger agent retry/second-guess behavior mid-delivery (wasted wall-clock, the thing we optimize for).
  • Any script composing wrappers under set -e dies on a help call.

Proposed fix (trivial, mechanical)

In each affected script: give usage() a parameterized exit — usage() { cat <<EOF ... EOF; exit "${1:-1}"; } — and change the help branch to -h|--help) usage 0 ;; while error paths keep usage (defaults to 1). Same convention several sibling wrappers already use. lane-brief.sh needs the same treatment in its deployed copy (no SSOT home — flagging separately to Mos; candidate for import like auto-submit-drafts.sh in #697).

Effort: ~8 two-line edits + a smoke loop (for s in *.sh; do bash $s --help; done asserting exit 0). No behavior change for error paths.

Found by enhance nightly pass 2026-07-11 (digest-20260711T084859Z).

## Defect `usage()` in 7 framework git wrappers hard-codes `exit 1` (one deployed-only script exits 2), so the documented `-h` / `--help` flags print correct help text **but return a failure exit code**. Affected (verified on stack `main` @ 4df38f7e, `packages/mosaic/framework/tools/git/`): | script | `usage()` exit | |---|---| | issue-assign.sh | 1 | | issue-create.sh | 1 | | issue-list.sh | 1 | | milestone-create.sh | 1 | | pr-create.sh | 1 | | pr-list.sh | 1 | | pr-merge.sh | 1 | | lane-brief.sh (deployed-only, NOT in SSOT) | 2 | All other wrappers in the directory already exit 0 on `-h`/`--help`. ## Evidence (fleet impact, 2026-07-11 nightly digest) 3 worker sessions (pi runtime, coder lanes restarted 2026-07-10 18:00) ran `~/.config/mosaic/tools/git/pr-create.sh --help` as due diligence before first use. Help printed correctly, exit was 1, so the runtime recorded `isError:true` — **7 phantom tool-error records in one night** attributed to a wrapper that behaved exactly as documented. Transcript proof: `/home/hermes/.pi/agent/sessions/--src-jarvis-brain--/2026-07-10T18-00-27-202Z_019f4d30-1f42-*.jsonl` (calls at 20:19:01Z, 21:22:54Z). ## Why it matters (blast radius) - Every fleet lane is told "wrappers first" (AGENTS.md rule 27) and reasonably checks `--help` before first use → each check logs a failure. - Pollutes nightly fleet-enhancement digests with false error signal (this is how it was found). - Nonzero exits can trigger agent retry/second-guess behavior mid-delivery (wasted wall-clock, the thing we optimize for). - Any script composing wrappers under `set -e` dies on a help call. ## Proposed fix (trivial, mechanical) In each affected script: give `usage()` a parameterized exit — `usage() { cat <<EOF ... EOF; exit "${1:-1}"; }` — and change the help branch to `-h|--help) usage 0 ;;` while error paths keep `usage` (defaults to 1). Same convention several sibling wrappers already use. `lane-brief.sh` needs the same treatment in its deployed copy (no SSOT home — flagging separately to Mos; candidate for import like auto-submit-drafts.sh in #697). Effort: ~8 two-line edits + a smoke loop (`for s in *.sh; do bash $s --help; done` asserting exit 0). No behavior change for error paths. Found by enhance nightly pass 2026-07-11 (digest-20260711T084859Z).
jason.woltje added the fleet-enhancement label 2026-07-11 08:53:33 +00:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
fleet-enhancement
Fleet-wide reliability/speed/cost improvements surfaced by the nightly enhance pass
No Label fleet-enhancement
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
jason.woltje
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mosaicstack/stack#701
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?