fix: fail closed on missing teardown dependencies

[tiago-peixoto]

Intent

Close one defect class upstream: sourcing a missing sibling library can end a script silently and successfully on the Bash that macOS ships by default, so any Firstmate user on a stock Mac is exposed wherever a script sources a sibling.

THE HAZARD, which is the point of this change. On GNU bash 3.2.57 - what /usr/bin/env bash resolves to on stock macOS - the . builtin on a file it cannot find terminates the whole script and does so with status 0. It ignores both a || return 1 written beside the source and an enclosing if !. Bash 5 returns 1 as written, which is why this repository's Linux CI lanes have never seen it. The consequence is a script that dies partway through while reporting success to its caller. That is worse than a crash: a caller records the work as done.

TWO CALL SITES, each with its own failing-test evidence.

1. fm_backend_source loading a backend adapter. A missing adapter file ended fm-teardown.sh mid-run while reporting success, so the caller recorded a task as cleaned up when nothing was cleaned up and the safety refusal never printed. tests/fm-teardown.test.sh's herdr preflight case failed only on macOS.
2. The teardown chain's own sibling sources. bin/backends/tmux.sh sources fm-session-lock-lib.sh and fm-cursor-lib.sh at its top level, and tests/fm-gotmp.test.sh builds a fake FM_ROOT that symlinked neither. Teardown therefore died inside fm_backend_kill and exited 0 with the task's temp directory still on disk. That test fails on macOS against this repository's own main today, before any change here.

These are the SAME defect at two call sites, which is why they ship as one change rather than two isolated line fixes. Diagnosis order matters for review: the second was found by tracing an unexplained CI failure to its exit point, where teardown returned status 0 with the tasktmp still present.

WHAT THIS CLOSES, stated precisely rather than generously. Every sibling source on the teardown chain now fails closed: 20 sites across fm-teardown.sh (14), bin/backends/tmux.sh (3), bin/fm-tmux-lib.sh (2) and bin/backends/orca.sh (1), each testing the file is readable and refusing by name if it is not. The repository has 216 such sibling-source sites across 69 files; this change closes the chain that demonstrably fails and that owns destructive cleanup, and the remaining sites share the hazard and are deliberately not touched here. The value to a reviewer is knowing which class is closed and where the boundary is, not a claim that all sourcing is now safe.

IMPLEMENTATION NOTES A REVIEWER WOULD NOT GUESS. The adapter guard reads and writes its once-only flag through eval rather than bash's ${!var} indirection or printf -v, because bin/fm-backend.sh is also sourced from zsh, where those constructs mean something else or nothing at all; tests/fm-backend.test.sh already exercises the zsh path and fails otherwise. Each inline guard is placed ABOVE the # shellcheck source= directive rather than between it and the source, because that directive must stay adjacent to the source line or shellcheck stops following the file.

TESTS. tests/fm-gotmp.test.sh gains the two missing symlinks so its fake root matches reality, and a new case asserting that a missing library produces a named non-zero refusal rather than a silent success. That case is not vacuous: with the guards removed the script dies with bash's own "No such file or directory" and never names what was missing, so the case fails. The case removes a library fm-teardown.sh sources directly at top level, because a library reached through a best-effort call site refuses just as loudly but that site discards stderr, which would hide the diagnostic being asserted.

PRE-EXISTING FAILURES, not introduced here. On a host whose git signs commits by default, tests/fm-backend.test.sh and tests/fm-teardown.test.sh already fail against this branch's exact base (b57c4d6) - verified on a pristine checkout of it - because tests/lib.sh does not neutralise commit.gpgsign for fixture commits. Those failures are unrelated to this change and are not addressed here.

SCOPE. This is one general fix carved out of a larger local change at the captain's direction, so each separable thing is judged as what it is. It carries nothing project-specific.

CHAIN CLOSURE, after review. The first version of this change guarded only the sites a syntax-pattern enumeration could see, and claimed the teardown chain was closed when it was not. That claim is corrected: enumeration is now by the sourcing act with shape-independent target extraction, transitively closed from fm-teardown.sh and all five backend adapters, because teardown dispatches whichever backend the task recorded. The reachable chain is 25 files and 29 sibling-source sites; all 29 now fail closed. The repository has 251 such sites across 85 files measured the same way, and the ones outside the reachable teardown chain are deliberately untouched and stated as such.

RECOVERY NOTE, for accuracy about this branch's history. A previous run of this pipeline applied the chain-closure work correctly but committed it as a sibling of the submitted head rather than a descendant, and the pipeline refused to proceed rather than lose the reviewed change - the protection worked as designed. The prior head is preserved locally as tag fm-bash32-preabort-03a7738; the current head strictly contains it, verified as 25 insertions and zero deletions, so nothing from it was dropped. No history was rewritten out-of-band by hand.

What Changed

• Make once-only backend adapter loading fail safely when adapter files are unreadable, preserving Bash 3.2 caller control and zsh compatibility.
• Guard teardown-chain sibling libraries and preflight parent and forced-descendant backends before destructive cleanup, returning named non-zero refusals while preserving task state.
• Add regression coverage for missing adapters and libraries, recursive backend preflight, zsh loading, and best-effort endpoint-kill behavior.

Risk Assessment

✅ Low: The change is fail-closed, covers the complete reachable teardown sourcing chain, and preflights parent and descendant backends before destructive cleanup without altering best-effort endpoint-kill behavior.

Testing

On stock macOS Bash 3.2.57, targeted backend, temp-cleanup, and teardown validation now succeeds with commit signing neutralized for fixtures; an initial zsh regression was reproduced, fixed test-first, and reverified, while two CLI transcripts directly demonstrate non-zero named refusals with cleanup state preserved and a final audit confirms all 29 reachable source sites are guarded.

Evidence: Stock macOS Bash missing-adapter refusal

GNU bash 3.2.57 exit_status=1 REFUSED: backend 'tmux' required by task evidence-task cannot be loaded tasktmp_preserved=yes metadata_preserved=yes

$ /bin/bash --version
GNU bash, version 3.2.57(1)-release (arm64-apple-darwin25)
$ FM_HOME=<fixture> /bin/bash <fixture>/bin/fm-teardown.sh evidence-task --force
exit_status=1
stderr:
REFUSED: backend 'tmux' required by task evidence-task cannot be loaded; nothing was changed - restore its adapter and required libraries, then rerun teardown
tasktmp_preserved=yes
metadata_preserved=yes

Evidence: Stock macOS Bash missing-sibling refusal

GNU bash 3.2.57 exit_status=1 missing required library: <fixture>/bin/fm-nm-run-lib.sh tasktmp_preserved=yes metadata_preserved=yes

$ /bin/bash --version
GNU bash, version 3.2.57(1)-release (arm64-apple-darwin25)
$ FM_HOME=<fixture> /bin/bash <fixture>/bin/fm-teardown.sh evidence-task --force
exit_status=1
stderr:
<fixture>/bin/fm-teardown.sh: missing required library: <fixture>/bin/fm-nm-run-lib.sh
tasktmp_preserved=yes
metadata_preserved=yes

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.

• Confirmed target 87cf89d36fbaf206005763ebc185f20bd949429c and GNU Bash 3.2.57.
• Initial targeted run: env GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=commit.gpgsign GIT_CONFIG_VALUE_0=false bin/fm-test-run.sh tests/fm-backend.test.sh tests/fm-gotmp.test.sh tests/fm-teardown.test.sh; exposed the zsh regression while both cleanup suites completed successfully.
• RED/GREEN verification: env GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=commit.gpgsign GIT_CONFIG_VALUE_0=false bin/fm-test-run.sh tests/fm-backend.test.sh; failed before the correction and exited 0 afterward, exercising all five adapters through zsh plus Bash 3.2 missing-adapter handling.
• Final cleanup verification: env GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=commit.gpgsign GIT_CONFIG_VALUE_0=false bin/fm-test-run.sh tests/fm-gotmp.test.sh tests/fm-teardown.test.sh; exited 0 against the final files.
• Manual /bin/bash teardown with a missing tmux adapter returned 1, named the backend, and preserved task temp data and metadata.
• Manual /bin/bash teardown with a missing sibling library returned 1, named the missing file, and preserved task temp data and metadata.
• Audited the reachable sourcing acts: 29 sites across the nine sourcing owners, with 0 invalid guard/directive/source triplets.

✅ **Document** - passed

✅ No issues found.

🔧 **Lint** - 1 issue found → auto-fixed ✅

• ⚠️ linter found issues (exit code 1)

🔧 Fix: Fix backend preflight ShellCheck scope warnings
✅ Re-checked - no issues remain.

✅ **Push** - passed

✅ No issues found.