feat(backend): add Superset as an experimental runtime backend

[AviPeltz]

What Changed

• Add bin/backends/superset.sh, a new adapter implementing capture, send-key, send-text-submit, kill, composer-state, and worktree create/remove/path against the superset CLI, addressing terminals via a composite <workspace_id>:<terminal_id> target.
• Wire superset into the backend registry as experimental, spawn-capable, and worktree-owning (never auto-detected) across bin/fm-backend.sh, bin/fm-spawn.sh, bin/fm-teardown.sh, bin/fm-bootstrap.sh, bin/fm-composer-lib.sh, bin/fm-control.sh, bin/fm-control-lib.sh, bin/fm-supervise-daemon.sh, bin/fm-afk-launch.sh, and bin/fm-tmux-lib.sh, including new meta fields, endpoint validation, and abort/teardown cleanup paths.
• Add docs/superset-backend.md and the .agents/skills/firstmate-superset/SKILL.md skill documenting the adapter's verified behavior and limits (no secondmate spawns, no Escape/Ctrl-U, no true Enter-only submit — a bare Enter always injects a leading space), update related docs/README/AGENTS/CONTRIBUTING/VISION references, and add tests/fm-backend-superset.test.sh plus updates to existing backend/bootstrap/teardown tests; a follow-up review pass removed a dead project-id JSON-parsing branch from the adapter.

Risk Assessment

✅ Low: This is a well-bounded, explicit-opt-in-only experimental backend that closely mirrors the already-established Orca adapter pattern throughout every touched file (spawn, teardown safety gates, endpoint validation, abort cleanup, control-key capability tables); the fix round correctly and precisely resolved both prior findings (removed the dead project-id branch, and strengthened documentation of the Enter-key space-injection limitation exactly per the user's explicitly authorized containment decision, without altering behavior), and a fresh full pass over the entire diff found no new correctness, security, or test-quality issues — all new tests exercise real functions against a fake CLI and assert observable behavior rather than grepping source text.

Testing

All targeted tests for the Superset backend feature and its review-commit cleanup pass (27/27 in the dedicated suite, 7/7 in teardown-endpoint-safety, the 3 relevant cases in fm-backend.test.sh, and the isolated bootstrap gating case); the one test failure encountered (fm-backend.test.sh's unrelated teardown-conformance case) was verified to pre-exist on the base commit in an isolated scratch worktree, so it's an environment/tooling gap (missing/incompatible axi) rather than a regression from this change.

Pipeline

Updates from git push no-mistakes

⏭️ **intent** - skipped

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

🔧 **Review** - 2 issues found → auto-fixed ✅

• ⚠️ bin/backends/superset.sh:280 - fm_backend_superset_send_key's Enter case has no true 'press Enter only' primitive: it sends a literal space via --text on every invocation (the CLI rejects empty --text and has no dedicated enter-only flag). This differs materially from Orca's fm_backend_orca_send_key, which sends --text "" --enter (a genuine empty-text-plus-enter primitive that types nothing) and from cmux/zellij, which use a dedicated send-key primitive, not text typing. Because bin/fm-composer-lib.sh's fm_composer_submit_retry_core (reused unmodified here) calls the adapter's send-key function on every retry without retyping the original text, each retry after a swallowed/ineffective first Enter injects ANOTHER space character into whatever is still staged in the composer, rather than being a no-op. The header comment and docs/verification/runtime-backends.md only verify that a single trailing space is inert once; they do not show this was tested across the exact multi-Enter flow the code explicitly targets ('a slash-command popup placeholder fill gets the required second Enter'). If an intermediate Enter is consumed by a popup/autocomplete rather than submitting, the accumulated stray space(s) could alter a live-filtered popup selection or land mid-argument, silently submitting a different or malformed command instead of erroring.
• ℹ️ bin/backends/superset.sh:129 - fm_backend_superset_json_get's 'project-id' field branch (v = data.id || "") is never invoked by any caller in this change; project id resolution for fm_backend_superset_project_id_for_path uses its own separate inline node script instead. This branch is unreachable dead code and can be removed.

🔧 Fix: Remove dead project-id branch, document Enter-key space injection
✅ Re-checked - no issues remain.

✅ **Test** - passed

✅ No issues found.

• bash tests/fm-backend-superset.test.sh — 27/27 pass (capture, runtime-check, send-key incl. the reviewed Enter/space-injection path, send-text-submit, composer-state, kill, remove-worktree, worktree-path, parse-target, project-id lookup/ensure, and fm-spawn.sh --backend superset integration)
• bash tests/fm-backend.test.sh — confirmed the 3 superset-specific cases (test_backend_validate_refuses_unknown, test_backend_validate_spawn_accepts_orca, test_backend_of_selector_matches_explicit_target_meta) pass; run halted afterward on an unrelated pre-existing failure (test_teardown_conformance_old_vs_new, an axi-tooling/environment gap) reproduced identically on the pre-change base commit 1cb900c in a scratch worktree, confirming it's not a regression from this branch
• bash tests/fm-teardown-endpoint-safety.test.sh — 7/7 pass, including the new Superset endpoint-record validation and generic-kill-refuses-empty-target case
• isolated run of test_superset_backend_gates_superset_tool_only_when_selected from fm-bootstrap.test.sh (extracted to avoid the full suite's slow, unrelated cases) — pass: bootstrap gates the Superset CLI only when backend=superset is selected
• grepped tests/fm-backend-superset.test.sh and bin/backends/superset.sh for 'project-id' to confirm the dead branch removed in the review commit had no test coverage depending on it

✅ **Document** - passed

✅ No issues found.

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

• ⚠️ linter found issues (exit code 127)

🔧 Fix: {"summary": "No lint fixes needed; ShellCheck/actionlint now on PATH pass clean"}
✅ Re-checked - no issues remain.

✅ **Push** - passed

✅ No issues found.

[kunchenguid]

Speaking as Kun's firstmate:

Reviewed the full diff. Superset is wired as an experimental, never-auto-detected backend (opt-in at the registry), with a new adapter, tests, and docs. It also amends VISION.md to name Superset as a session manager. That charter line is a product decision, not something I will auto-merge.

I approved fork CI. Waiting on green checks including no-mistakes.