The first mate drives these; interactive entrypoints work by hand too, while *-lib.sh files are sourced helpers.
Each row is one purpose clause only: the script's own header comment is the authoritative description of its behavior, flags, and contracts, so read the header before first use.
If you have changed away from the firstmate home in an interactive shell, invoke these scripts by absolute path through the repo's bin/ directory; the scripts self-locate internally after they start.
The shared no-mistakes gate refusal for fleet lifecycle entrypoints is summarized in architecture.md, while docs/sessionstart-nudge.md covers the silent hook-nudge use; fm-gate-refuse-lib.sh's header owns its exact contract.
| Script | Purpose |
|---|---|
fm-session-start.sh |
Compose lock, bootstrap, and wake drain into the single ordered session-start digest |
fm-sessionstart-nudge.sh |
Print the native session-start hook nudge when the primary has not already run the digest |
fm-operational-input.sh |
Construct and parse the canonical cross-language operational-input protocol |
fm-bootstrap.sh |
Detect toolchain and fleet problems, run the locked session-start sweeps, and install approved tools |
fm-fleet-sync.sh |
Refresh project clones with safe fast-forwards, self-heals, STUCK: reports, branch pruning, and bounded recovery from an orphaned .git/packed-refs.lock |
fm-fleet-snapshot.sh |
Print the read-only structured fleet snapshot JSON (schema fm-fleet-snapshot.v1) |
fm-fleet-view.sh |
Render the fleet snapshot as a human Markdown view |
fm-bearings-snapshot.sh |
Project the fleet snapshot to the compact TOON bearings view; local-only unless --include-prs |
fm-update.sh |
Fast-forward-only self-update of firstmate and local or remote secondmate homes, classifying every live mate left on the target commit for restart or fallback nudge |
fm-secondmate-restart.sh |
Persist open conversational work, then restart eligible second mates or report the fallback outcome |
fm-secondmate-restart-lib.sh |
Shared second-mate restart capability and persistence-request contract |
fm-omp-update.sh |
Update the machine-wide omp executable only after a stopped-fleet proof; --check is detect-only |
fm-on.sh |
Execute one tracked Firstmate command in a configured remote secondmate home, using its job worker except for the doctor bootstrap |
fm-remote-job-lib.sh |
Shared bounded remote job queue, worker readiness, LaunchAgent contract, and filesystem-composed PATH |
fm-remote-job-worker.sh |
Long-lived remote queue worker for tracked fm-*.sh commands in the account runtime |
fm-remote-doctor.sh |
Check, and with --fix repair, one remote account's second-mate readiness (remote job worker, Herdr, Aqua launch agents, PATH, and required tools) |
fm-todo-project.sh |
Project the board into session-todo JSON (--emit) or check board drift (--check, optionally --reconcile); the script header owns mutation limits |
fm-backlog-handoff.sh |
Validate and delegate queued backlog-item moves into a secondmate home |
fm-backlog-receive.sh |
Idempotently ingest one confined remote handoff outbox through tasks-axi |
fm-decision-hold.sh |
Create, verify, complete, answer, and resolve durable captain-held decisions |
fm-brief.sh |
Scaffold ship (explicit --mode), scout, secondmate-charter, and Herdr-lab briefs |
fm-herdr-lab.sh |
Provision and guardedly operate an isolated, never-default Herdr lab session |
fm-install-herdr.sh |
Install CI's exact-version Herdr pin with official asset URL, SHA-256, and protocol checks |
fm-install-treehouse.sh |
Install CI's exact-version Treehouse pin for real-Herdr E2E that needs spawn worktrees |
fm-herdr-ci-cleanup.sh |
Snapshot and tear down only job-owned fm-lab-* sessions in the Herdr CI lane |
fm-test-run.sh |
Behavior-test runner: selection, portable lanes, proven-isolated --jobs, coverage guard, timing/JSON |
fm-test-isolation-proof.sh |
Concurrent isolation proof and proven-isolated candidate set owner |
fm-ensure-agents-md.sh |
Ensure a project's real AGENTS.md, its CLAUDE.md @AGENTS.md pointer, and the canonical self-governance section |
fm-guard.sh |
Warn on primary-checkout tangles, pending queued wakes, and unhealthy supervision |
fm-primary-scope-lib.sh |
Shared marker-or-plain-checkout primary-home predicate for tracked hooks |
fm-session-lock-lib.sh |
Shared session-lock harness identity (ancestry walk and holder liveness) for fm-lock.sh and the Claude Stop auto-arm |
fm-claude-stop-autoarm.sh |
Claude Stop asyncRewake hook owning tokenless watcher continuity with single-flight exit-2 rewake (docs/watcher-continuity.md) |
fm-turnend-guard.sh |
Shared primary turn-end guard predicate so no turn ends blind (docs/turnend-guard.md) |
fm-turnend-signal.sh |
Lock-free publisher of the per-generation task turn-end marker state/.turn-ended.; the consumer (fm-wake-lib.sh) fires only the live gen |
fm-turnend-guard-grok.sh |
Grok Stop-hook adapter for the primary turn-end guard |
fm-kimi-turnend-hook.sh |
Surgically install or remove Kimi's guarded global crew turn-end hook |
fm-hermes-turnend-hook.sh |
Surgically install or remove Hermes' guarded shell-hook and persistent-TUI lifecycle plugin bridge |
fm-arm-pretool-check.sh |
Stable PreToolUse transport for the watcher-arm command policy (docs/arm-pretool-check.md) |
fm-arm-command-policy.mjs |
Semantic owner of the watcher-arm PreToolUse policy (docs/arm-pretool-check.md) |
fm-subagent-pretool-check.sh |
Primary-home delegation-shape PreToolUse guard (docs/subagent-guard.md) |
fm-supervision-instructions.sh |
Render the session-start primary-harness supervision block or the one-line repair instruction |
fm-home-seed.sh |
Transactionally provision a local secondmate home and maintain data/secondmates.md |
fm-remote-home-seed.sh |
Register and provision a whole secondmate home on an SSH-reachable host |
fm-remote-readiness-lib.sh |
Shared remote second-mate readiness gate: check and, when needed, repair then re-check through fm-remote-doctor.sh |
fm-runpod.sh |
Optional RunPod compute lifecycle for one whole-home remote second mate: provision, wake, guarded stuck recovery and sleep, status, cost, and destroy |
fm-runpod-lib.sh |
Dependency-free RunPod placement predicate read by supervision, convergence, and delivery |
fm-runpod-pod-boot.sh |
Tracked container boot contract sent to every RunPod pod; see runpod-secondmates.md |
fm-runpod-omp-auth.sh |
Workstation OMP auth-broker, read-only facade, and per-pod SSH reverse-tunnel lifecycle |
fm-omp-auth-broker-readonly-proxy.mjs |
Credential-read-only HTTP boundary between RunPod OMP clients and the canonical workstation broker |
fm-spawn.sh |
Spawn crewmates, scouts, id=repo batches, and secondmates on the resolved harness and runtime backend |
fm-omp-capabilities.sh |
Verify the selected OMP executable's required lifecycle and exact process-ownership surface before a launch |
fm-spawn-herdr-reclaim-lib.sh |
Reclaim authority for a task whose herdr presentation journal is already published |
fm-backend.sh |
Runtime-backend selection, meta helpers, selector resolution, and operation dispatch |
fm-backend-hometag-lib.sh |
Shared per-installation home-tag derivation for zellij tab and cmux workspace titles |
fm-composer-lib.sh |
Single fleet-wide owner of composer-content classification for all backends |
backends/tmux.sh |
Verified tmux session-provider adapter |
backends/herdr.sh |
Experimental herdr session-provider adapter |
backends/zellij.sh |
Experimental zellij session-provider adapter |
backends/orca.sh |
Experimental Orca backend adapter owning both worktree and terminal |
backends/cmux.sh |
Experimental cmux session-provider adapter |
fm-config-push.sh |
Push declared inherited local material to live local or remote secondmates and send the placement-specific config reread when changed |
fm-project-mode.sh |
Resolve a project's registered delivery posture from data/projects.md for fleet sync and home seeding |
fm-merge-local.sh |
Fast-forward a local-only project's local default branch after approval |
fm-local-default.sh |
Resolve the local default branch shared by readiness and guarded landing |
fm-review-diff.sh |
Review a crewmate branch or resolved PR head against the authoritative base |
fm-receipt.sh |
Append one validated acceptance-criterion evidence receipt to a ship task |
fm-receipt-check.sh |
Check ship evidence and own risk-based validation planning and completion |
fm-receipt-schema.sh |
Validate the single receipt JSON schema used by append and read paths |
fm-receipt-store.sh |
Own pinned ship contracts, evidence, metadata updates, and promotion storage |
fm-marker-lib.sh |
Compatibility entry point for the from-firstmate carrier owned by fm-operational-input.sh |
fm-pending-reply-lib.sh |
Parent-owned secondmate pending-reply expectations, recovery, and one-shot escalation |
fm-secondmate-parent-lib.sh |
Parse durable secondmate parent-route binding records |
fm-secondmate-report.sh |
Optional helper to append a correlated parent status or document-pointer report |
fm-procevent-remote-reply.sh |
Relay non-destructive remote-secondmate lifecycle deltas and resolve exact correlated pending replies through process events |
fm-procevent-when.sh |
Fire a trust-bound deterministic action at most once when its registered condition holds, then wake with the outcome |
fm-timeout-lib.sh |
Shared bounded command runner that terminates the entire process group on timeout |
fm-gate-refuse-lib.sh |
Shared no-mistakes gate-context refusal for fleet lifecycle entrypoints |
fm-primary-watch-core.ts |
Harness-neutral watcher lifecycle core bound by the Pi and OMP primary extensions (docs/watcher-continuity.md) |
fm-primary-watch-version-lib.sh |
The one definition of a primary watcher marker version, hashing that adapter plus the shared core |
fm-watch-arm.sh |
Verified home-scoped watcher arm wrapper with loud cycle endings and bounded lifecycle ledger |
fm-watch-checkpoint.sh |
Run one bounded foreground watcher checkpoint for Codex-style supervision |
fm-watch.sh |
Singleton-safe always-on watcher: absorb benign wakes, queue and exit on actionable ones |
fm-afk-start.sh |
Run the common sourceable away-mode daemon entry in the foreground |
fm-afk-launch.sh |
Own away-mode entry, exit, rollback, and any backend terminal lifecycle |
fm-afk-return.sh |
Own deterministic return shutdown, catch-up evidence, and the firstmate-actionable blocker gate |
fm-supervisor-target-lib.sh |
Resolve the shared supervisor target and backend for the daemon and launcher |
fm-supervise-daemon.sh |
Presence-gated away-mode sub-supervisor: self-handle routine wakes, guard injection by the detected primary harness, escalate batched digests, alert on failed delivery |
fm-crew-state.sh |
Print one deterministic current-state line for a crew |
fm-nm-run-lib.sh |
Single owner of shared no-mistakes run-attribution primitives and rules |
fm-tangle-lib.sh |
Shared default-branch resolution and primary-checkout tangle classification |
fm-supervision-lib.sh |
Shared in-flight-work-without-fresh-watcher-beacon predicate |
fm-ff-lib.sh |
Shared guarded fast-forward helper for origin pulls and local secondmate syncs |
fm-lock-lib.sh |
Shared "is this git lock provably abandoned?" proof used by teardown and fleet-sync |
fm-config-inherit-lib.sh |
Shared primary-to-secondmate inherited local-material propagation and config-reread delivery |
fm-tasks-axi-lib.sh |
Shared backlog-backend selector and tasks-axi compatibility probe |
fm-quota-axi-lib.sh |
Shared quota-axi compatibility floor for the bootstrap diagnostic |
fm-vendor-auth-probe.sh |
Run one hard-bounded, non-destructive authentication probe of a named vendor CLI and report the fact |
fm-wake-drain.sh |
Present durable watcher wakes, unread informational status lines, OPEN DECISIONS, and the main-actor status-outcome backstop, consume acknowledged rows through their sequence, retire only the matching recovery generation, then assert supervision health |
fm-wake-lib.sh |
Shared durable wake queue, recovery generations, portable locks, and watcher identity/health helpers |
fm-classify-lib.sh |
Shared wake and status-span classification, ship evidence gate, durable keyed-decision folds, status cursors, and unread informational status-line selection |
fm-send.sh |
Enqueue ordinary local task text durably, or type remote task text, slash commands, Codex dollar invocations, explicit targets, and keys through the recorded backend |
fm-task-inbox-lib.sh |
Own sequenced steering records, handled-file acknowledgement, the constant doorbell, and the watcher retry ladder |
fm-busy-lib.sh |
Single owner of the semantic busy-state contract: verdicts, source attribution, and per-harness sources |
fm-busy-event.sh |
The only writer of a task's semantic busy-state record; arms an incarnation and applies lifecycle events |
fm-tmux-lib.sh |
Shared tmux pane primitives for composer capture, verified submit, and the submit-time busy check |
fm-peek.sh |
Print a bounded tail of a crewmate endpoint |
fm-check-register.sh |
Bind an intentional custom watcher check to its current bytes |
fm-check-unregister.sh |
Retire a custom watcher check and its trust binding by validated task id |
fm-check-lib.sh |
Validate custom-check registrations and prepare private execution snapshots |
fm-pr-lib.sh |
Own canonical task and PR validation plus private atomic PR-poll publication and identity-bound retirement |
fm-pr-poll.sh |
Provide the byte-static watcher program for validated PR/MR-poll sidecars |
fm-pr-check.sh |
Publish a static merge poll and atomically record validated PR-path metadata |
fm-pr-merge.sh |
Record PR metadata, merge a task's canonical full GitHub URL, and verify the real outcome |
fm-merge-outcome-lib.sh |
Publish a confirmed merge's durable, role-routed supervision outcome |
fm-promote.sh |
Promote a scout task in place to a protected ship task with an explicit delivery mode |
fm-promote-transaction.sh |
Execute the pinned store's recoverable scout-to-ship promotion phases |
fm-worktree-clean-lib.sh |
Own the shared fail-closed worktree cleanliness predicate |
fm-teardown.sh |
Fail-closed teardown: return landed ship worktrees, require completed scout deliverables, retire secondmate homes |
fm-harness.sh |
Detect the running harness and resolve crew or secondmate harness, model, and effort |
fm-pi-compatible-lib.sh |
Shared membership predicate for the verified Pi-compatible harness family |
fm-pi-compatible-runtimes |
The tracked single owner of that closed family allowlist |
fm-omp-process-lib.sh |
Exact OMP process identity shared by primary ancestry and backend liveness probes |
fm-lock.sh |
Per-home firstmate session lock |
fm-x-lib.sh |
Shared X-mode config, relay, and reply-threading helpers |
fm-x-poll.sh |
One bounded X relay poll: stash newly offered mentions and emit their once-only wake |
fm-x-reply.sh |
Post or dry-run preview a composed X-mode reply or follow-up |
fm-x-dismiss.sh |
Dismiss a skipped X-mode mention at the relay without replying |
fm-x-link.sh |
Link a spawned task to its originating X-mode mention in task meta |
fm-x-followup.sh |
Detect, post, and cap completion follow-ups for an X-mode-linked task |
fm-public-followup-lib.sh |
Shared relay-activation gate, O(1) presence checks, and private transport paths for promised public replies |
fm-public-followup.sh |
Reconcile typed terminal work results into a public commitment and deliver its final reply once |
fm-public-followup-emit.sh |
Report one typed terminal work result into the home that owes the public reply |