john/firstmate
Watch
1
0
Fork
You've already forked firstmate
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Remove macOS support: both macOS-only backends, the alert channel, the launchd path, and every reference to them #13

Merged
john merged 25 commits from fm/fm-drop-macos-support-cont into main 2026-08-20 15:42:13 +00:00
Conversation 0 Commits 25 Files changed 63 +397 -6289
john commented 2026-08-20 15:35:02 +00:00
Owner
Copy link

Removes macOS from this fork: both macOS-only backends, the macOS alert channel, the launchd remote-job path, and every reference that pointed at them. 63 files, 397 insertions, 6,289 deletions.

The captain's instruction was direct: this fork targets Arch Linux only, and carrying macOS surface is wasted cycles on something being redesigned for our own use.

What went

  • The Orca backend, entirely — script, doc, skill and tests.
  • The cmux backend, entirely — script, doc and tests.
  • The macOS wedge-alarm notification channel (osascript), with its docs and tests. Where auto resolved to it on Darwin, that branch is gone rather than left resolving to nothing unexplained.
  • The launchd remote-job path, in its own commit — see below.
  • Every remaining reference across AGENTS.md, docs/, .agents/skills/, bin/ and the test suite. A repo-wide search for orca, cmux, osascript, launchctl and LaunchAgent now returns nothing.

That last part mattered most. A dangling reference to a deleted backend is worse than the backend was: it is an instruction pointing at something that no longer exists, and the person who follows it wastes their time before discovering that.

What deliberately stayed

  • BSD-versus-GNU portability shims. Portability is not macOS support. Stripping code because it names Darwin would have broken things unrelated to this decision.
  • The Arch-only rationale text, which explains the decision and is correct.
  • Verification provenance recording that something was proven on a macOS host — historical evidence, not a support claim. Erasing the host would make an old test look generally applicable when it was not.

Two over-removals the review caught, both restored

Worth calling out because they are the real risk in a deletion sweep — not the obvious references, but accurate content sitting next to them:

  1. A platform-neutral requirement was collapsed out of docs/remote-secondmates.md along with a macOS keychain note: that each worker runtime still needs its own login on a remote account. True, useful, nothing to do with macOS. Restored.
  2. An alarm message still blamed "this platform" for having no alert channel. After the osascript removal the real cause is simply that a tool is not installed — a closeable gap the old wording disguised as an unfixable limitation. In the alarm path that difference is the whole point, since the message exists to make someone act. Reworded.

The launchd removal is its own commit, deliberately

The captain named the two backends and the notification channel. They did not name the launchd remote-job path — firstmate extended the ruling to it on the same dead-weight reasoning, since no macOS host is a supported remote target any more. It is isolated in 45d094a so it can be reverted alone if that extension was wrong.

Validation

no-mistakes passed: review, test, document and lint. Note that the pipeline cannot reach this forge, so its PR and CI steps skip — real CI runs here, on this pull request, and that is the verification that counts.

One finding was deliberately left: the portable-serial shard table in docs/fm-test-portable-shards.md has drifted (69 documented against 104 derived). That drift predates this work and is far larger than the three removed suites explain. Refreshing it correctly needs duration data from a green CI run rather than hand-patched numbers, so it is filed separately — a stale table that is visibly stale is safer than a fresh-looking one built from guesses.

Removes macOS from this fork: both macOS-only backends, the macOS alert channel, the launchd remote-job path, and every reference that pointed at them. 63 files, 397 insertions, 6,289 deletions. The captain's instruction was direct: this fork targets Arch Linux only, and carrying macOS surface is wasted cycles on something being redesigned for our own use. ## What went - **The Orca backend**, entirely — script, doc, skill and tests. - **The cmux backend**, entirely — script, doc and tests. - **The macOS wedge-alarm notification channel** (`osascript`), with its docs and tests. Where `auto` resolved to it on Darwin, that branch is gone rather than left resolving to nothing unexplained. - **The launchd remote-job path**, in its own commit — see below. - **Every remaining reference** across `AGENTS.md`, `docs/`, `.agents/skills/`, `bin/` and the test suite. A repo-wide search for `orca`, `cmux`, `osascript`, `launchctl` and `LaunchAgent` now returns nothing. That last part mattered most. A dangling reference to a deleted backend is worse than the backend was: it is an instruction pointing at something that no longer exists, and the person who follows it wastes their time before discovering that. ## What deliberately stayed - **BSD-versus-GNU portability shims.** Portability is not macOS support. Stripping code because it names `Darwin` would have broken things unrelated to this decision. - **The Arch-only rationale text**, which explains the decision and is correct. - **Verification provenance** recording that something was proven on a macOS host — historical evidence, not a support claim. Erasing the host would make an old test look generally applicable when it was not. ## Two over-removals the review caught, both restored Worth calling out because they are the real risk in a deletion sweep — not the obvious references, but accurate content sitting next to them: 1. **A platform-neutral requirement was collapsed out of `docs/remote-secondmates.md`** along with a macOS keychain note: that each worker runtime still needs its own login on a remote account. True, useful, nothing to do with macOS. Restored. 2. **An alarm message still blamed "this platform"** for having no alert channel. After the osascript removal the real cause is simply that a tool is not installed — a closeable gap the old wording disguised as an unfixable limitation. In the alarm path that difference is the whole point, since the message exists to make someone act. Reworded. ## The launchd removal is its own commit, deliberately The captain named the two backends and the notification channel. They did **not** name the launchd remote-job path — firstmate extended the ruling to it on the same dead-weight reasoning, since no macOS host is a supported remote target any more. It is isolated in `45d094a` so it can be reverted alone if that extension was wrong. ## Validation `no-mistakes` passed: review, test, document and lint. Note that the pipeline cannot reach this forge, so its PR and CI steps skip — **real CI runs here, on this pull request, and that is the verification that counts.** One finding was deliberately left: the portable-serial shard table in `docs/fm-test-portable-shards.md` has drifted (69 documented against 104 derived). That drift predates this work and is far larger than the three removed suites explain. Refreshing it correctly needs duration data from a green CI run rather than hand-patched numbers, so it is filed separately — a stale table that is visibly stale is safer than a fresh-looking one built from guesses.
john added 25 commits 2026-08-20 15:35:02 +00:00 
The fork targets Arch Linux only (AGENTS.md section 1 is the durable record), but the shields.io platform badge still advertised 'macOS | Linux', a stale support claim. Narrow it to 'Linux'.

Every other macOS reference was reviewed and intentionally kept: the Arch-only rationale (AGENTS.md/CONTRIBUTING/ci.yml), the macOS-only Orca and cmux backends, BSD-vs-GNU portability shims, cross-platform installers, macOS mechanisms inside cross-platform features (wedge-alarm osascript, remote-job launchd), and verification provenance records.
Badge is a support claim and now matches the Arch-only stance in AGENTS.md exactly (macOS|Linux -> Arch Linux), per firstmate.

tests/fm-brief.test.sh comments pointed cross-version Bash 3.2 enforcement at the macos-stock-bash CI job, which no longer exists. Re-point the owner to the structural heredoc-free builder construction pinned by test_no_heredoc_in_command_substitution; the safety claim is kept and nothing is deleted. brew install hints in bin/fm-bootstrap.sh remain a deliberate keep (hedged, upstream-sync-sensitive).
Captain ruling 2026-08-19: pull the Orca backend entirely (code + docs), same as the macOS backends. Deleted bin/backends/orca.sh, docs/orca-backend.md, .agents/skills/firstmate-orca/, tests/fm-backend-orca.test.sh. Reference strips in bin/docs/skills/tests/AGENTS.md follow in this same C1 stage (see sweep-notes.md inventory).
Captain ruling 2026-08-19: pull the cmux backend entirely (code + docs). Deleted bin/backends/cmux.sh, docs/cmux-backend.md, tests/cmux-test-safety.sh, tests/fm-backend-cmux.test.sh, tests/fm-backend-cmux-smoke.test.sh. Reference strips in bin/docs/skills/tests/AGENTS.md follow (see sweep-notes.md inventory).
Preserved as a patch after the previous worker's agent became unresponsive
mid-sweep (see data/fm-drop-macos-support/RECOVERY-NOTE.md). Reviewed and
applied unmodified: bin/backends/zellij.sh, bin/fm-afk-launch.sh,
bin/fm-backend-hometag-lib.sh, bin/fm-backend.sh, bin/fm-bootstrap.sh,
bin/fm-composer-lib.sh, bin/fm-spawn.sh, bin/fm-supervise-daemon.sh,
bin/fm-test-isolation-proof.sh, bin/fm-test-run.sh.
Removes the Orca-specific worktree-removal path (require_orca_worktree_id,
require_orca_worktree_path_match(_if_present), T_ORCA/ORCA_WORKTREE_ID/
ORCA_PATH_MATCH_VERIFIED state, and every orca-conditional branch in the
task and secondmate-children cleanup paths), leaving the generic
treehouse-backed worktree teardown as the only path.
Strips remaining orca/cmux mentions from docs/architecture.md (backend
lists, OMP applicability, busy-primitive and worktree-provider prose) and
the dead orca/cmux verification records in docs/verification/{runtime-backends,
public-followup}.md, plus incidental single-line orca mentions in
bin/fm-brief.sh, bin/fm-gate-refuse-lib.sh, and bin/fm-send.sh.
Strips orca/cmux from the runtime-backend selection order, task selector
vocabulary, required-tools delta, harness support matrix, and env-var
reference; the treehouse durable-lease upgrade check note now reflects
that every remaining backend uses treehouse.
Strips remaining orca/cmux mentions from AGENTS.md (config/backend and
config/cmux-socket-password entries, the firstmate-orca skill-trigger
bullet), README.md (features, backend list, ASCII diagram, documentation
links), CONTRIBUTING.md, the afk and stuck-crewmate-recovery skills, and
the remaining backend docs (herdr, codex-app, trace-context,
remote-secondmates, tmux, calm-mode-feasibility, scripts). Also removes
the now-dangling docs/orca-backend.md, docs/cmux-backend.md, and
firstmate-orca SKILL.md entries from docs/documentation-audiences.json,
which the doc-audience-check test caught as broken links.
Removes the cmux runtime-auto-detection fallback test suite (bundle-id and
process-ancestry signals, all deleted with fm_backend_detect_cmux_fallback),
the orca/cmux branches of the detect-precedence, name-autodetect, and
explicit-beats-detection matrices, orca's terminal= selector-resolution
case, and the orca/cmux backend-validate acceptance checks. All 21 cases
pass.
Removes the orca-only tool-gating test, the cmux bundled-CLI-resolution
test, and orca/cmux rows from the session-provider and jq-dependency
matrices; updates the BACKEND_INVALID known-backends assertion to the
current tmux/herdr/zellij set. All 25 cases pass.
Removes the orca-specific persistent-stale terminal= resolution test; the
generic and herdr persistent-stale tests already cover the same
escalation path, and the terminal= metadata special case it exercised
was removed with the orca backend. All 99 cases pass.
Removes the orca terminal= and cmux workspace/surface endpoint-validation
cases, both deleted with their backends, and drops them from the
empty-target kill-refusal matrix. All 5 cases pass.
Renames the cmux-backend missing-worktree fixture row to zellij (a still-
supported backend); the row's purpose was only to exercise a non-tmux
backend with a missing worktree file, not cmux-specific behavior. All
16 cases pass.
Strips a stale comment pointer to the deleted tests/fm-backend-cmux.test.sh
in fm-backend-zellij.test.sh, drops orca/cmux from the backend-agnosticism
token list in fm-trace-context-lib.test.sh, and removes the deleted
tests/fm-backend-cmux-smoke.test.sh from the serial-class exclusion list
in fm-test-isolation-proof.test.sh. All cases pass.
Removes the orca composer_state dispatch case from the backend-routing
matrix; orca no longer has a named classifier to dispatch to (it falls
through to the same unknown verdict as an unrecognized backend now). All
189 cases pass.
Drops the deleted fm-backend-cmux.test.sh and fm-backend-orca.test.sh
from the synthetic fixture's fake test-script list. All 17 cases pass.
Drops orca and cmux from the OMP-unverified-backend refusal matrix: both
are no longer known backends at all, so fm-spawn would now refuse them
with an unknown-backend error rather than the OMP-specific allowlist
message this test asserts. Zellij remains the one backend that is known
but OMP-unverified. All 36 cases pass.
Captain-directed dead-weight removal: strip the osascript Notification
Center channel from the away-mode wedge alarm, keeping the wedge-alarm
feature itself and its remaining herdr and command: channels intact.

- bin/fm-supervise-daemon.sh: delete wedge_alarm_via_osascript and its
  dispatch cases; `auto`/`default` now resolves to `herdr` when its CLI
  is present instead of resolving to osascript on Darwin, so `auto`
  never silently resolves to nothing unexplained (the existing "no
  OS-level alert channel" log line already covers the no-herdr case).
- docs/wedge-alarm.md, docs/configuration.md, docs/examples/wedge-alarm,
  AGENTS.md: drop the osascript directive and macOS-specific auto
  wording; document auto -> herdr instead.
- docs/verification/supervision.md: drop the dead macOS notification
  proof from the wedge-alarm-channels verification record, keeping the
  herdr proof.
- tests/fm-daemon.test.sh: remove the osascript-only test, replace
  osascript with herdr/command: in the multi-channel and failure-fallback
  matrices, and rewrite the two `auto` resolution tests for the new
  herdr-or-nothing default (herdr CLI present vs. a restricted PATH that
  excludes it). All 98 cases pass.
Firstmate extended the captain's ruling to this path: the captain named
orca, cmux, and the macOS notification channel as dead weight on this
Arch-only fork, not launchd specifically, but the same dead-weight
reasoning applies to the launchd remote-job mechanism now that no
macOS host is a supported remote-secondmate target. This is its own
commit so it can be reverted alone if that extension turns out wrong.

- bin/fm-remote-job-lib.sh: delete the LaunchAgent renderer, contract
  matcher, GUI-availability probe, and launchctl bootstrap/kickstart
  helpers; fm_remote_job_ensure_worker now always starts the detached
  Linux-style worker, with the same bounded single retry it already had
  for a supervisor ownership race.
- bin/fm-remote-doctor.sh: remove the Aqua login-session check, the
  Firstmate-owned herdr LaunchAgent check, and their write/reload/wait
  repair helpers; the herdr-server and remote-job-worker checks no
  longer branch on platform, since starting each directly is now the
  only path.
- bin/fm-remote-job-worker.sh, bin/fm-remote-entrypoint.sh: drop the
  now-dead platform dispatch and stale header prose; refresh the
  entrypoint's pinned DOCTOR_SHA256 to match the edited doctor.
- docs/remote-secondmates.md, docs/scripts.md: describe the worker and
  herdr server as detached background processes with no GUI-session or
  launch-agent layer.
- tests/fm-remote-doctor.test.sh: rewrite the fixture to drop the fake
  launchctl/uname-platform harness and every launch-agent test case,
  keeping only the herdr-CLI, herdr-server, remote-job-worker,
  version-manager-wrapper, stale-identity, and entrypoint-symlink
  coverage. tests/fm-on.test.sh and
  tests/fm-remote-secondmate-lifecycle-e2e.test.sh drop incidental
  launchagent/gui-session example text.

All touched suites pass (fm-remote-job-lib, fm-remote-doctor,
fm-remote-job.test.sh, fm-remote-entrypoint.test.sh,
fm-remote-secondmate-lifecycle-e2e.test.sh, fm-remote-backlog-handoff,
fm-remote-secondmate-parent-binding, fm-remote-secondmate-trace-context);
one pre-existing fm-on.test.sh assertion and one wrapper-fallback case in
fm-remote-doctor.test.sh are environment-coupled to this sandbox having
opencode pre-installed system-wide (confirmed failing identically on
unmodified HEAD) and are expected to pass on the plain Arch CI image.
no-mistakes(lint): Silence SC2034 detect-signal, unroll single-item backend loop
All checks were successful
CI / Test coverage guard (pull_request) Successful in 13s
Details
CI / Behavior portable parallel 2 (pull_request) Successful in 3m5s
Details
CI / Behavior portable parallel 1 (pull_request) Successful in 3m11s
Details
CI / Lint shell scripts (pull_request) Successful in 4m12s
Details
CI / Behavior portable serial 1 (pull_request) Successful in 12m33s
Details
CI / Behavior portable serial 4 (pull_request) Successful in 10m19s
Details
CI / Repo invariants (pull_request) Successful in 4s
Details
CI / Behavior portable serial 3 (pull_request) Successful in 13m23s
Details
CI / Behavior portable serial 2 (pull_request) Successful in 14m39s
Details
CI / Behavior tests (Herdr) (pull_request) Successful in 7m26s
Details
10f82dd507
john merged commit 7c8e17fe6a into main 2026-08-20 15:42:13 +00:00
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
john/firstmate!13
No description provided.