fix(composer): read an NBSP-padded empty composer as empty and fail unshown herdr wedge alarms

[sbracewell64]

Intent

Fix the root cause of firstmate's away-mode escalation delivery wedge: buffered captain-relevant escalations sat undelivered for ~9.5 hours in each of three separate stretches, and steers into an idle pane reported false "delivery unconfirmed" errors.

This implements recommendations R1 and R3 of a completed, already-reviewed diagnosis (private report at data/away-injection-wedge-diagnosis/report.md). The design was reviewed and motivated before this work started; the task was explicitly to implement it, not to redesign it. Do not propose an alternative architecture for the fix.

R1 (the fix). Real Claude Code 2.1.220 pads its EMPTY composer row with U+00A0 NBSP, so the captured row is exactly ❯ + \xc2\xa0. bash's [[:space:]] does not match U+00A0, so no trim could remove it, the leading-glyph strip left a lone NBSP behind, and the shared classifier concluded "real, unsubmitted content remains" -> pending on a genuinely idle pane, stably, on every poll. Away-mode injection and verified submit both proceed only on an affirmative empty, which is why delivery wedged. fm_composer_classify_content now normalizes the non-ASCII blanks a TUI can use as padding before its trims (U+00A0, U+2007, U+202F -> ASCII space; U+200B, U+FEFF dropped).

Deliberate decisions in R1, so they are not mistaken for oversights:

• The normalization lives in bin/fm-composer-lib.sh, the ONE fleet-wide owner of the empty|pending|unknown verdict, specifically so both ANSI readers (tmux capture-pane -e and herdr pane read) and all four adapters (tmux, herdr, Orca, cmux) are covered at once and cannot drift back into per-adapter copies. Per-adapter normalization was rejected for exactly that reason.
• Callers already trim ASCII whitespace before calling, and that is deliberately NOT sufficient - the whole defect is that their trims cannot see U+00A0. The classifier re-trims both content and plain_content after normalizing so the rest of the function keeps the trimmed inputs its contract comment documents.
• The safety property is load-bearing and asserted in tests: every character normalized here renders as blank and nothing else is touched, so the change can only ever make an OTHERWISE-BLANK row read as blank. It is impossible for real typed text to become empty - a row holding any visible glyph keeps that glyph byte for byte, NBSP-joined text stays pending, and an NBSP-padded dead-shell prompt stays non-empty (it becomes the documented unknown rather than pending).
• The helper uses explicit \x byte escapes rather than literal characters or \u escapes, deliberately: they are locale-independent and express the exact UTF-8 bytes the live captures carry. Please do not "clean these up" into literal characters.

Regression fixtures. tests/fm-composer-lib.test.sh and tests/fm-backend-herdr.test.sh gain fixtures carrying the LITERAL \xc2\xa0 byte pair captured from real Claude Code 2.1.220 (the herdr fixture includes the trailing CR from the real capture). The absence of that byte pair anywhere under tests/ is precisely why all three 9.5-hour delivery failures passed CI, so the literal bytes in these fixtures are the point of the change, not an accident. Each new fixture is paired with a real-text counterpart so the safety property is tested in both directions rather than only asserted in prose.

R3 (hardening in the same subsystem, same incident). herdr notification show exits 0 even when it showed nothing: with [ui.toast] delivery off (herdr's default) it answers {"shown":false,"reason":"disabled"}. wedge_alarm_via_herdr read exit 0 as success, so a captain who configured the away-mode wedge alarm's herdr channel would get a healthy log line and be reached by nobody. It now parses the payload and treats an explicit "shown":false as a channel failure with the reported reason logged.

Deliberate decisions in R3:

• A payload with no shown field keeps its exit-status verdict rather than being treated as a failure. This is intentional backward compatibility with a herdr build that reports no outcome, not a missed case; it is covered by a test.
• The payload is captured through a temp file rather than a command substitution on purpose: a command substitution would put the notifier in a subshell, so wedge_alarm_run_bounded would lose its process-group timeout and its WEDGE_ALARM_NOTIFIER_PID cleanup. The no-mktemp branch preserves the previous behavior.
• The logged reason is sanitized to a bounded safe character class. herdr's reason is its own short token (not captain config), so it is logged rather than redacted - unlike the command: channel, which deliberately redacts.
• tests/fm-daemon.test.sh's shared make_wedge_case herdr fake gained FM_FAKE_HERDR_PAYLOAD and FM_FAKE_HERDR_EXIT knobs; both are used by the new tests, and the existing tests keep their previous behavior when the knobs are unset.

Explicitly out of scope, by decision, and not to be added here: R2 (a max-defer fallback delivery route that does not depend on composer content - queued as separate work), R4 (choosing an OS alert channel for this Windows/WSL host - a pending captain decision, since it governs how firstmate interrupts the captain on their own machine), and R5 (fast-forwarding the operational home - not a code change).

Documentation placement follows this repo's knowledge-placement rules: the mechanism and its rationale live in the changed script's own comments; the one fleet-wide behavioral sentence went into docs/architecture.md, which already owns the shared-classifier statement, rather than being duplicated into the per-backend docs; and docs/verification/supervision.md records the newly observed herdr payload. That verification entry is real observed output - the exact command already recorded there was re-run on this host today (herdr 0.7.5, Linux 6.18 WSL2) and returned {"reason":"disabled","shown":false} with exit 0, displaying nothing.

Verification already performed locally: the reproduction was reproduced and inverted (pre-fix pending, post-fix empty, real text pending both ways) on both readers, including through fm_tmux_composer_row_state for the tmux path. All 171 pre-existing composer and herdr tests stay green (composer-lib 9, composer-ghost 30, herdr 132), the daemon suite goes 99 -> 101, and cmux (55), orca (50), tmux-submit-busy (8), send-strict (6), crew-state (47), backend (29), afk-return (5) and afk-launch (48) all pass. bin/fm-lint.sh (pinned ShellCheck 0.11.0) and bin/fm-doc-audience-check.sh are both clean. Five failures in a broader changed-file run were each attributed elsewhere: fm-backend-tmux-smoke needs a real tmux server, and fm-pi-watch-extension, fm-turnend-guard and fm-calm-pi-extension were proven to fail identically with this change reverted; fm-watcher-lock has no source-graph dependency on either changed file.

What Changed

• fm_composer_classify_content in bin/fm-composer-lib.sh — the single fleet-wide owner of the empty|pending|unknown verdict — now normalizes non-ASCII blank padding before its trims (U+00A0, U+2007, U+202F → ASCII space; U+200B, U+FEFF dropped), so the ❯ + U+00A0 row that real Claude Code 2.1.220 emits for an idle composer classifies as empty instead of permanently pending. Rows with any visible glyph are untouched: NBSP-joined text stays pending, and an NBSP-padded dead-shell prompt becomes unknown, never empty.
• wedge_alarm_via_herdr in bin/fm-supervise-daemon.sh now captures the herdr notification show payload (via a temp file, preserving the bounded-run process-group timeout) and treats an explicit "shown":false as a channel failure with the sanitized reason logged, instead of trusting the always-0 exit code; a payload without a shown field keeps the exit-status verdict for older herdr builds.
• Regression fixtures carrying the literal \xc2\xa0 bytes (with trailing CR on the herdr path) land in tests/fm-composer-lib.test.sh and tests/fm-backend-herdr.test.sh, each paired with a real-text counterpart; tests/fm-daemon.test.sh covers the unshown/shown/payload-less herdr outcomes via new fake-herdr knobs, and docs (architecture.md, verification/supervision.md, wedge-alarm.md) record the shared-classifier behavior and the observed exit-0 {"shown":false,"reason":"disabled"} payload. All four affected suites pass in the pipeline, including manual before/after demos of both fixes.

Risk Assessment

✅ Low: A tightly-bounded two-part fix that matches its reviewed design exactly: the blank-normalization can only make otherwise-blank rows read blank (verified in code and pinned by byte-literal regression fixtures in both directions), and the herdr payload check only converts a previously-false success into an explicit failure, with backward-compatible fallbacks covered by tests.

Testing

Ran the four targeted suites covering the changed files (composer-lib, herdr backend, daemon, composer-ghost — all green, including the six new regression tests), then demonstrated both fixes end-to-end with a base-vs-fixed transcript: the byte-exact real-claude ❯+U+00A0 idle capture flips from a stable false pending (the delivery wedge) to empty through both the herdr and tmux readers while real typed text and NBSP-padded dead shells stay non-empty, and the herdr wedge-alarm channel now fails loudly with the reason logged on the real exit-0 "shown":false payload where the base silently reported success. No rendered UI surface exists for this daemon/TUI-classifier change, so the CLI transcript is the reviewer-visible evidence.

Evidence: Base-vs-fixed transcript: NBSP wedge inversion (both readers) and herdr alarm payload hardening

=== R1: the NBSP wedge — real captured bytes: ❯ + U+00A0 (+CR in the pane capture) === composer row bytes: e2 9d af c2 a0 (e2 9d af = ❯, c2 a0 = U+00A0 NBSP) --- herdr reader end-to-end (fm_backend_herdr_composer_state on the full pane capture) --- idle NBSP-padded composer : BASE(a2d5f26) -> pending FIXED(c995389) -> empty same row + real typed text : BASE(a2d5f26) -> pending FIXED(c995389) -> pending --- tmux reader (fm_tmux_composer_row_state on the raw row) --- idle NBSP-padded row : BASE(a2d5f26) -> pending FIXED(c995389) -> empty same row + real typed text : BASE(a2d5f26) -> pending FIXED(c995389) -> pending NBSP-padded dead-shell '$' : BASE(a2d5f26) -> pending FIXED(c995389) -> unknown (must never be empty) === R3: herdr wedge-alarm channel vs the real exit-0 {"shown":false,"reason":"disabled"} payload === BASE(a2d5f26) : rc=0 daemon log: <empty> — exit 0 read as delivery: healthy log, captain reached by NOBODY FIXED(c995389): rc=1 daemon log: wedge alarm: herdr accepted the notification but did not show it (reason: disabled); this channel reached nobody

=== R1: the NBSP wedge — real captured bytes: `❯` + U+00A0 (+CR in the pane capture) ===
composer row bytes: e2 9d af c2 a0 (e2 9d af = ❯, c2 a0 = U+00A0 NBSP)

--- herdr reader end-to-end (fm_backend_herdr_composer_state on the full pane capture) ---
idle NBSP-padded composer   : BASE(a2d5f26) -> pending   FIXED(c995389) -> empty
same row + real typed text  : BASE(a2d5f26) -> pending   FIXED(c995389) -> pending

--- tmux reader (fm_tmux_composer_row_state on the raw row) ---
idle NBSP-padded row        : BASE(a2d5f26) -> pending   FIXED(c995389) -> empty
same row + real typed text  : BASE(a2d5f26) -> pending   FIXED(c995389) -> pending
NBSP-padded dead-shell '$'  : BASE(a2d5f26) -> pending   FIXED(c995389) -> unknown   (must never be empty)

Away-mode injection and verified submit proceed ONLY on an affirmative 'empty':
at BASE the genuinely idle pane reads 'pending' forever -> delivery wedges;
at FIXED it reads 'empty' -> escalations inject, while real text still blocks injection.

=== R3: herdr wedge-alarm channel vs the real exit-0 {"shown":false,"reason":"disabled"} payload ===
BASE(a2d5f26) : rc=0  daemon log: 
               ^ exit 0 was read as delivery: healthy log, captain reached by NOBODY
FIXED(c995389): rc=1  daemon log: wedge alarm: herdr accepted the notification but did not show it (reason: disabled); this channel reached nobody

Evidence: Reproducible demo script (runs real reader/daemon code paths at base and fixed)

#!/usr/bin/env bash
# Before/after demonstration of the composer-NBSP wedge fix (R1) and the herdr
# wedge-alarm "shown":false hardening (R3), run against the REAL code paths:
#  - R1 end-to-end through the herdr backend reader (fm_backend_herdr_composer_state)
#    with a fake `herdr` CLI returning the byte-exact live capture
#    (U+276F '❯' + U+00A0 NBSP + CR), and through the tmux path
#    (fm_tmux_composer_row_state).
#  - R3 through wedge_alarm_via_herdr sourced from the daemon, with a fake herdr
#    answering the real observed payload {"reason":"disabled","shown":false} at exit 0.
# BASE  = a2d5f26 (pre-fix), extracted read-only via `git archive`.
# FIXED = the current worktree (c995389).
set -u
WORKTREE=$1
SCRATCH=$2   # ephemeral work area
BASE_ROOT="$SCRATCH/base-root"
mkdir -p "$BASE_ROOT"
git -C "$WORKTREE" archive a2d5f26 bin | tar -x -C "$BASE_ROOT"

hex() { printf '%s' "$1" | od -An -tx1 | tr -s ' ' | sed 's/^ //'; }

# The byte-exact idle composer row captured from live Claude Code 2.1.220 panes.
IDLE_ROW=$'\xe2\x9d\xaf\xc2\xa0'                       # ❯ + NBSP
IDLE_CAPTURE=$'  20\n  21\n\n\xe2\x9c\xbb Worked for 2s\n\n\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80\n\xe2\x9d\xaf\xc2\xa0\r\n\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80\n  Opus 4.8 (1M context)\n'
TEXT_CAPTURE=$'  20\n  21\n\n\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80\n\xe2\x9d\xaf\xc2\xa0land pr 1234 now\r\n\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80\n'

herdr_state() {  # <root> <capture-bytes> -> verdict
  local root=$1 cap=$2 dir fb
  dir=$(mktemp -d "$SCRATCH/herdr-demo.XXXXXX"); fb="$dir/fakebin"
  mkdir -p "$fb" "$dir/responses"
  printf '%s' "$cap" > "$dir/responses/1.out"
  cat > "$fb/herdr" <<'SH'
#!/usr/bin/env bash
set -u
RESP="${FM_HERDR_RESPONSES:?}"
if [ "${1:-}" = status ] && [ "${2:-}" = --json ]; then
  printf '{"client":{"version":"0.7.1","protocol":14},"server":{"running":true}}\n'; exit 0
fi
n=$(( $(cat "$RESP/.count" 2>/dev/null || echo 0) + 1 )); echo "$n" > "$RESP/.count"
[ -f "$RESP/$n.out" ] && cat "$RESP/$n.out"
exit 0
SH
  chmod +x "$fb/herdr"
  PATH="$fb:$PATH" FM_HERDR_RESPONSES="$dir/responses" FM_HERDR_LOG="$dir/log" \
    bash -c '. "$0/bin/backends/herdr.sh"; fm_backend_herdr_composer_state default:w1:p2' "$root"
}

tmux_row_state() {  # <root> <raw-row> -> verdict
  bash -c '. "$0/bin/fm-tmux-lib.sh"; fm_tmux_composer_row_state "$1"' "$1" "$2"
}

wedge_alarm() {  # <root> <logfile> -> rc; logs to <logfile>
  local root=$1 lf=$2 fb
  fb=$(mktemp -d "$SCRATCH/wedge-demo.XXXXXX")
  cat > "$fb/herdr" <<'SH'
#!/usr/bin/env bash
printf '%s\n' '{"id":"cli:notification:show","result":{"reason":"disabled","shown":false,"type":"notification_show"}}'
exit 0
SH
  chmod +x "$fb/herdr"
  # Source first (the library-mode guard forces the seam to "discard"), then
  # clear the seam per-call exactly as tests/fm-daemon.test.sh does, so the
  # channel really invokes the fake herdr.
  PATH="$fb:$PATH" LOG="$lf" \
    bash -c '. "$0/bin/fm-supervise-daemon.sh"; FM_WEDGE_ALARM_EXEC= wedge_alarm_via_herdr "away-mode escalations WEDGED 900s"' "$root"
}

echo "=== R1: the NBSP wedge — real captured bytes: \`❯\` + U+00A0 (+CR in the pane capture) ==="
echo "composer row bytes: $(hex "$IDLE_ROW") (e2 9d af = ❯, c2 a0 = U+00A0 NBSP)"
echo
echo "--- herdr reader end-to-end (fm_backend_herdr_composer_state on the full pane capture) ---"
b=$(herdr_state "$BASE_ROOT" "$IDLE_CAPTURE");  f=$(herdr_state "$WORKTREE" "$IDLE_CAPTURE")
echo "idle NBSP-padded composer   : BASE(a2d5f26) -> $b   FIXED(c995389) -> $f"
bt=$(herdr_state "$BASE_ROOT" "$TEXT_CAPTURE"); ft=$(herdr_state "$WORKTREE" "$TEXT_CAPTURE")
echo "same row + real typed text  : BASE(a2d5f26) -> $bt   FIXED(c995389) -> $ft"
echo
echo "--- tmux reader (fm_tmux_composer_row_state on the raw row) ---"
b=$(tmux_row_state "$BASE_ROOT" "$IDLE_ROW"); f=$(tmux_row_state "$WORKTREE" "$IDLE_ROW")
echo "idle NBSP-padded row        : BASE(a2d5f26) -> $b   FIXED(c995389) -> $f"
b=$(tmux_row_state "$BASE_ROOT" $'\xe2\x9d\xaf\xc2\xa0land pr 1234 now')
f=$(tmux_row_state "$WORKTREE"  $'\xe2\x9d\xaf\xc2\xa0land pr 1234 now')
echo "same row + real typed text  : BASE(a2d5f26) -> $b   FIXED(c995389) -> $f"
b=$(tmux_row_state "$BASE_ROOT" $'$\xc2\xa0'); f=$(tmux_row_state "$WORKTREE" $'$\xc2\xa0')
echo "NBSP-padded dead-shell '\$'  : BASE(a2d5f26) -> $b   FIXED(c995389) -> $f   (must never be empty)"
echo
echo "Away-mode injection and verified submit proceed ONLY on an affirmative 'empty':"
echo "at BASE the genuinely idle pane reads 'pending' forever -> delivery wedges;"
echo "at FIXED it reads 'empty' -> escalations inject, while real text still blocks injection."
echo
echo "=== R3: herdr wedge-alarm channel vs the real exit-0 {\"shown\":false,\"reason\":\"disabled\"} payload ==="
bl="$SCRATCH/base-daemon.log"; fl="$SCRATCH/fixed-daemon.log"; : > "$bl"; : > "$fl"
wedge_alarm "$BASE_ROOT" "$bl"; brc=$?
wedge_alarm "$WORKTREE" "$fl"; frc=$?
echo "BASE(a2d5f26) : rc=$brc  daemon log: $(cat "$bl" 2>/dev/null || echo '<empty>')"
[ -s "$bl" ] || echo "               ^ exit 0 was read as delivery: healthy log, captain reached by NOBODY"
echo "FIXED(c995389): rc=$frc  daemon log: $(sed 's/^[^]]*] //' "$fl" 2>/dev/null)"

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-composer-lib.test.sh — 11 pass (includes new test_nbsp_padded_blank_rows_are_empty and test_non_ascii_blanks_never_hide_real_text)
• bash tests/fm-backend-herdr.test.sh — 128 pass (includes new NBSP-padded empty/pending fixtures end-to-end through fm_backend_herdr_composer_state)
• bash tests/fm-daemon.test.sh — 101 pass (includes new test_wedge_alarm_herdr_unshown_payload_is_a_failure and test_wedge_alarm_herdr_shown_payload_succeeds)
• bash tests/fm-composer-ghost.test.sh — pass (guards the changed shared classifier file)
• Manual before/after demo at base a2d5f26 vs fixed c995389: byte-exact ❯+U+00A0(+CR) capture through fm_backend_herdr_composer_state (fake herdr CLI) and fm_tmux_composer_row_state — idle row pending→empty, real-text row pending→pending, NBSP dead-shell $ never empty (pending→unknown)
• Manual before/after demo of wedge_alarm_via_herdr against the real exit-0 {"shown":false,"reason":"disabled"} payload — base rc=0 silent success, fixed rc=1 with the reason logged
• git status --porcelain — worktree clean, no transient test artifacts left behind

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.