fix(dispatch): propagate delegated exit codes (#75)

22 top-level branches invoked a script under $BASE_DIR and then ended in an
unconditional `return 0`. A failing delegate was reported as success:

    mqlaunch repos LIST                → argparse error on stderr, exit 0
    mqlaunch skills no-such-subcommand → argparse error on stderr, exit 0

tests/delegated-exit-code-smoke.sh stubbed shell functions, which only reaches
the agent and HAL families. Those propagate correctly; the branches delegating
to external scripts were never covered, which is why this survived.

Each branch now captures `command_status` immediately after the delegate and
returns it — the idiom the `review` and `stack` routes already used. The capture
sits before `pause_enter` on the routes that call it, so the pause cannot
overwrite the status. Success paths are unchanged.

Tests first, and they fail on main: two behavioural cases through the full
launcher, plus a structural check that fails if any delegating branch reverts to
an unconditional `return 0` — verified by planting one.

Refs #74

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: MCamner

CHANGELOG.md

@@ -24,6 +24,15 @@ All notable changes to this project will be documented in this file.
 
 ### Fixed
 
+* 22 dispatch branches invoked a script under `$BASE_DIR` and then ended in an
+  unconditional `return 0`, so a failing delegate was reported as success:
+  `mqlaunch repos LIST` and `mqlaunch skills no-such-subcommand` both wrote a
+  usage error to stderr and exited 0. Every delegating branch now captures
+  `command_status` and returns it, matching the idiom the agent and HAL routes
+  already used. `pause_enter` no longer overwrites the status on the routes that
+  call it. `tests/delegated-exit-code-smoke.sh` gained the two behavioural cases
+  and a structural check that fails if any delegating branch reverts to an
+  unconditional `return 0`.
 * `mqlaunch` dispatched `memory` from two different branches. The
   `srm|memory|repo-memory` branch claims it first, so the `memory` listed in the
   brain-bridge branch below it could never match — `mqlaunch memory` has always

terminal/launchers/mqlaunch-command-mode.sh

@@ -391,7 +391,8 @@ dispatch_cli_command() {
           "$BASE_DIR/automation/workflows/workspace.sh" "$sub" "${3:-}"
           ;;
       esac
-      return 0
+      command_status=$?
+      return "$command_status"
       ;;
 
     demo)
@@ -506,7 +507,8 @@ dispatch_cli_command() {
     ask|/ask)
       shift
       "$BASE_DIR/tools/scripts/ask.sh" "$@"
-      return 0
+      command_status=$?
+      return "$command_status"
       ;;
 
     srm|memory|repo-memory)
@@ -534,49 +536,57 @@ dispatch_cli_command() {
         return "$command_status"
       fi
       "$BASE_DIR/tools/scripts/srm.sh" "$@"
-      return 0
+      command_status=$?
+      return "$command_status"
       ;;
 
     skills|skill)
       shift
       "$BASE_DIR/tools/scripts/mq-skills.py" "$@"
+      command_status=$?
       [[ "${1:-}" != "--json" ]] && pause_enter
-      return 0
+      return "$command_status"
       ;;
 
     repos)
       shift
       case "${1:-}" in
         ""|menu|hub)
           "$BASE_DIR/bin/mqlaunch" hub
+          command_status=$?
           ;;
         list|roadmaps|skills|status|wiki-status|diff-summary)
           "$BASE_DIR/tools/scripts/mq-repos.py" "$@"
+          command_status=$?
           pause_enter
           ;;
         *)
           "$BASE_DIR/tools/scripts/mq-repos.py" "$@"
+          command_status=$?
           pause_enter
           ;;
       esac
-      return 0
+      return "$command_status"
       ;;
 
     fix|/fix)
       shift
       "$BASE_DIR/tools/scripts/fix.sh" "$@"
-      return 0
+      command_status=$?
+      return "$command_status"
       ;;
 
     chat|/chat)
       "$BASE_DIR/tools/scripts/chat.sh"
-      return 0
+      command_status=$?
+      return "$command_status"
       ;;
 
     release-check|/release-check|check-release)
       "$BASE_DIR/terminal/release/mq-release-check.sh" "${@:2}"
+      command_status=$?
       pause_enter
-      return 0
+      return "$command_status"
       ;;
 
     review-brain|/review-brain)
@@ -623,14 +633,16 @@ dispatch_cli_command() {
 
     doctor|/doctor)
       "$BASE_DIR/tools/scripts/doctor.sh" "${@:2}"
+      command_status=$?
       [[ "${2:-}" != "--json" && -z "${MQ_NO_TUI:-}" ]] && pause_enter
-      return 0
+      return "$command_status"
       ;;
 
     scan|/scan)
       "$BASE_DIR/tools/scripts/scan.sh"
+      command_status=$?
       pause_enter
-      return 0
+      return "$command_status"
       ;;
 
     atlas|/atlas)
@@ -676,7 +688,8 @@ dispatch_cli_command() {
           return 2
           ;;
       esac
-      return 0
+      command_status=$?
+      return "$command_status"
       ;;
 
     git)
@@ -710,7 +723,8 @@ dispatch_cli_command() {
           return 2
           ;;
       esac
-      return 0
+      command_status=$?
+      return "$command_status"
       ;;
 
     dev)
@@ -858,17 +872,20 @@ dispatch_cli_command() {
       else
         "$BASE_DIR/tools/scripts/hal-terminal-guide.sh"
       fi
-      return 0
+      command_status=$?
+      return "$command_status"
       ;;
 
     docfunc|document-functions)
       MQ_WORK_DIR="$PWD" "$BASE_DIR/terminal/menus/mq-tools-menu.sh" docfunc
-      return 0
+      command_status=$?
+      return "$command_status"
       ;;
 
     docwrite|document-functions-write|update-comments)
       MQ_WORK_DIR="$PWD" "$BASE_DIR/terminal/menus/mq-tools-menu.sh" docwrite
-      return 0
+      command_status=$?
+      return "$command_status"
       ;;
 
     version)
@@ -982,37 +999,44 @@ dispatch_cli_command() {
       else
         "$BASE_DIR/bin/mqlaunch" hub
       fi
-      return 0
+      command_status=$?
+      return "$command_status"
       ;;
 
     git-log|gitlog|glog)
       declare -f fzf_git_log >/dev/null && fzf_git_log || "$BASE_DIR/bin/mqlaunch" git-log
-      return 0
+      command_status=$?
+      return "$command_status"
       ;;
 
     git-branch|branch-switch|gbranch)
       declare -f fzf_git_branch >/dev/null && fzf_git_branch || "$BASE_DIR/bin/mqlaunch" git-branch
-      return 0
+      command_status=$?
+      return "$command_status"
       ;;
 
     kill-process|killp|pkill-fzf)
       declare -f fzf_kill_process >/dev/null && fzf_kill_process || "$BASE_DIR/bin/mqlaunch" kill-process
-      return 0
+      command_status=$?
+      return "$command_status"
       ;;
 
     kill-port|killport|port-kill)
       declare -f fzf_kill_port >/dev/null && fzf_kill_port || "$BASE_DIR/bin/mqlaunch" kill-port
-      return 0
+      command_status=$?
+      return "$command_status"
       ;;
 
     snippets|snippet|scripts)
       declare -f fzf_run_snippet >/dev/null && fzf_run_snippet || "$BASE_DIR/bin/mqlaunch" snippets
-      return 0
+      command_status=$?
+      return "$command_status"
       ;;
 
     recent|recent-files|rf)
       declare -f fzf_recent_files >/dev/null && fzf_recent_files || "$BASE_DIR/bin/mqlaunch" recent
-      return 0
+      command_status=$?
+      return "$command_status"
       ;;
 
     brain)

tests/delegated-exit-code-smoke.sh

@@ -32,23 +32,23 @@ assert_status() {
 
 echo "SMOKE: delegated exit-code contract"
 
-echo "[1/5] missing backend is non-zero"
+echo "[1/7] missing backend is non-zero"
 unset -f run_agent_command 2>/dev/null || true
 assert_status 1 dispatch_cli_command review
 grep -q 'bridge not loaded' "$TMPDIR_TEST/stderr"
 
-echo "[2/5] usage and runtime failures propagate"
+echo "[2/7] usage and runtime failures propagate"
 run_agent_command() { return "${MQ_TEST_BACKEND_STATUS:-0}"; }
 MQ_TEST_BACKEND_STATUS=2 assert_status 2 dispatch_cli_command review
 MQ_TEST_BACKEND_STATUS=42 assert_status 42 dispatch_cli_command stack status
 
-echo "[3/5] HAL pause does not overwrite backend status"
+echo "[3/7] HAL pause does not overwrite backend status"
 mq_hal_run() { return "${MQ_TEST_BACKEND_STATUS:-0}"; }
 rm -f "$TMPDIR_TEST/pause.log"
 MQ_TEST_BACKEND_STATUS=42 assert_status 42 dispatch_cli_command hal brief
 [[ -s "$TMPDIR_TEST/pause.log" ]]
 
-echo "[4/5] JSON stdout stays clean"
+echo "[4/7] JSON stdout stays clean"
 mq_hal_run() {
   printf '{"schema":"hal.test.v1"}\n'
   return 42
@@ -59,7 +59,7 @@ assert_status 42 dispatch_cli_command hal brief --json
 [[ ! -e "$TMPDIR_TEST/pause.log" ]]
 [[ ! -s "$TMPDIR_TEST/stderr" ]]
 
-echo "[5/5] full launcher returns backend status without double dispatch"
+echo "[5/7] full launcher returns backend status without double dispatch"
 mkdir -p "$TMPDIR_TEST/bin" "$TMPDIR_TEST/agent"
 cat > "$TMPDIR_TEST/bin/uv" <<EOF
 #!/usr/bin/env bash
@@ -87,5 +87,88 @@ set -e
   exit 1
 }
 
+echo "[6/7] external script delegates propagate their status"
+# Steps 1-5 stub shell functions, which only reaches the agent and HAL families.
+# Most of the surface delegates to scripts under $BASE_DIR instead, and those
+# were never covered. Both cases below are real argparse failures.
+run_launcher() {
+  set +e
+  MACOS_SCRIPTS_HOME="$ROOT" MQ_NO_TUI=1 MQLAUNCH_HEADLESS=1 \
+    timeout 60 "$ROOT/terminal/launchers/mqlaunch.sh" "$@" \
+    </dev/null >"$TMPDIR_TEST/stdout" 2>"$TMPDIR_TEST/stderr"
+  local status=$?
+  set -e
+  return "$status"
+}
+
+for bad_case in "repos LIST" "skills no-such-subcommand"; do
+  # shellcheck disable=SC2086
+  set -- $bad_case
+  if run_launcher "$@"; then
+    echo "delegated failure reported success: mqlaunch $bad_case" >&2
+    exit 1
+  fi
+  grep -q 'usage:' "$TMPDIR_TEST/stderr" || {
+    echo "expected a delegate usage error on stderr for: mqlaunch $bad_case" >&2
+    exit 1
+  }
+done
+
+# The success path must stay 0, so the fix cannot be "always return non-zero".
+run_launcher repos list || {
+  echo "successful delegation no longer exits 0" >&2
+  exit 1
+}
+
+echo "[7/7] no delegating branch ends in an unconditional return 0"
+# The behavioural cases above pin two branches. This keeps the other nineteen
+# from drifting back, and stops new ones from being written that way.
+python3 - "$COMMAND_MODE" <<'PY'
+import re
+import sys
+
+lines = open(sys.argv[1]).read().splitlines()
+start = next(i for i, l in enumerate(lines) if l.strip() == 'case "$area" in')
+
+branch = re.compile(
+    r'((?:"[^"]*"|[A-Za-z0-9_*/.\-])+(?:\|(?:"[^"]*"|[A-Za-z0-9_*/.\-])+)*)\)'
+)
+depth = 0
+current = None
+bodies = {}
+for i in range(start, len(lines)):
+    s = lines[i].strip()
+    if s.startswith("case ") and re.match(r'case\s+"?\$', s):
+        depth += 1
+    elif s.startswith("esac"):
+        depth -= 1
+        if depth == 0:
+            break
+    elif branch.match(s):
+        if depth == 1:
+            current = (branch.match(s).group(1), i + 1)
+            bodies[current] = []
+        elif current is not None:
+            bodies[current].append(s)
+    elif current is not None:
+        bodies[current].append(s)
+
+offenders = []
+for (name, line), body in bodies.items():
+    text = "\n".join(body)
+    if not re.search(r"\$BASE_DIR/(tools|terminal|bin|automation)", text):
+        continue
+    if re.search(r"^return 0$", text, re.M):
+        offenders.append(f"  line {line}: {name}")
+
+if offenders:
+    print(
+        "these branches delegate and then discard the delegate's status:",
+        file=sys.stderr,
+    )
+    print("\n".join(offenders), file=sys.stderr)
+    sys.exit(1)
+PY
+
 bash -n "$0"
 echo "OK: delegated failures preserve their exit status"