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 used by every directly invocable mutating control-plane entrypoint is summarized in architecture.md; fm-gate-refuse-lib.sh's header owns its exact guarded and excluded scope.
| Script | Purpose |
|---|---|
fm-session-start.sh |
Compose lock, bootstrap, and wake drain into the single ordered session-start digest |
fm-autocompact.sh |
Bridge Claude context compaction through a durable anchor and session-start recovery |
fm-bootstrap.sh |
Detect toolchain and fleet problems, run the locked session-start sweeps, and install approved tools |
fm-checkout-refresh.sh |
Discover worktree seed checkouts, react to live upstream-default changes, surface untracked skill drafts, enforce the timed backstop, and manage the home-scoped scheduler |
fm-fleet-sync.sh |
Serialize live-default-proven project refreshes with safe fast-forwards, STUCK: reports, branch pruning, and orphaned-lock recovery |
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 secondmate homes from origin |
fm-backlog-handoff.sh |
Validate and delegate queued backlog-item moves into a secondmate home |
fm-brief.sh |
Scaffold ship, scout, secondmate-charter, and Herdr-lab briefs |
fm-herdr-lab.sh |
Provision and guardedly operate an isolated, never-default Herdr lab session |
fm-ensure-agents-md.sh |
Ensure a project's real AGENTS.md, its CLAUDE.md symlink, and the canonical self-governance section |
fm-guard.sh |
Warn on primary-checkout tangles, pending queued wakes, and stale watcher liveness |
fm-turnend-guard.sh |
Shared primary turn-end guard predicate so no turn ends blind (docs/turnend-guard.md) |
fm-turnend-guard-grok.sh |
Grok Stop-hook adapter for the primary turn-end guard |
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-cd-pretool-check.sh |
Stable PreToolUse transport for the primary cd-guard command policy (docs/cd-guard.md) |
fm-cd-command-policy.mjs |
Semantic owner of the cd-guard's persistent-directory-change decision (docs/cd-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 secondmate home and maintain data/secondmates.md |
fm-spawn.sh |
Spawn, native-resume, or provider-neutrally continue crewmates on the resolved account and runtime backend |
fm-dispatch-select.sh |
Resolve a matched crew-dispatch rule through quota or the deferred legacy pool-summary branch |
fm-account-directory.sh |
Select a direct Claude/Codex account directory and install its per-profile Herdr hook |
fm-account-routing-lib.sh |
Own routing mode plus legacy Agent Fleet lease, exec, resume, and release recovery |
fm-account-session-sync.sh |
Reconcile real Agent Fleet provider-session mappings into managed task metadata |
fm-account-continuation.sh |
Build a verified task-owned packet for fresh cross-profile continuation |
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/herdr-eventwait.py |
Raw AF_UNIX wire transport for herdr's native pane.agent_status_changed stream |
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 inheritable local config to live secondmate homes mid-session |
fm-project-mode.sh |
Resolve a project's delivery mode and +yolo flag from data/projects.md |
fm-merge-local.sh |
Fast-forward a local-only project's local default branch after approval |
fm-review-diff.sh |
Review a crewmate branch or recorded PR head against the authoritative base |
fm-marker-lib.sh |
Shared from-firstmate request marker, detector, and idempotent transformation |
fm-gate-refuse-lib.sh |
Shared no-mistakes gate-context refusal for fleet lifecycle entrypoints |
fm-watch-arm.sh |
Verified home-scoped watcher arm wrapper with honest status reporting |
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-supervisor-target-lib.sh |
Resolve the compatibility injection target and backend for the daemon and launcher |
fm-supervise-daemon.sh |
Presence-gated away-mode sub-supervisor: self-handle routine wakes, complete native tasks or inject compatibility digests |
fm-crew-state.sh |
Print one deterministic current-state line for a crewmate |
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-checkout-lock-lib.sh |
Shared common-Git-directory lock identity and ownership for checkout mutation |
fm-process-tree-lib.sh |
Shared bounded command runner that terminates and reaps complete process trees |
fm-config-inherit-lib.sh |
Shared primary-to-secondmate inheritable-config propagation |
fm-tasks-axi-lib.sh |
Shared backlog-backend selector and tasks-axi compatibility probe |
fm-wake-drain.sh |
Atomically drain queued watcher wakes, then assert watcher liveness |
fm-wake-lib.sh |
Shared durable wake queue, portable locks, and watcher identity/health helpers |
fm-classify-lib.sh |
Shared captain-relevant and declared-external-wait wake classification vocabulary |
fm-transition-lib.sh |
Shared backend-neutral transition record shape and single-owner status->action policy table |
fm-send.sh |
Send one verified literal line or supported key through the target's recorded backend |
fm-tmux-lib.sh |
Shared tmux pane primitives for busy detection, composer capture, and verified submit |
fm-peek.sh |
Print a bounded tail of a crewmate endpoint |
fm-pr-check.sh |
Record pr= and pr_head= for a PR-ready task, then arm the watcher's merge poll |
fm-pr-merge.sh |
Record PR metadata, then merge a task's PR from its full GitHub URL |
fm-promote.sh |
Promote a scout task in place to a protected ship task |
fm-report-contract-lib.sh |
Render the shared ship completion-report contract inserted into briefs and continuation prompts |
fm-report-stack.mjs |
Publish and browse machine-global, account-independent completion reports |
fm-report-retention.sh |
Maintain bounded, interruption-safe 30-day report retention independently of tasks |
fm-teardown.sh |
Fail-closed teardown of worktrees, endpoints, secondmate homes, and managed account leases |
fm-harness.sh |
Detect the running harness and resolve crewmate or secondmate harness, model, and effort |
fm-lock.sh |
Per-home firstmate session lock |
fm-lint.sh |
Single owner of the shell-lint definition that CI and the no-mistakes gate both run |
fm-install-shellcheck.sh |
Install CI's pinned, checksum-verified ShellCheck build |
fm-x-lib.sh |
Shared X-mode config, relay, and reply-threading helpers |
fm-x-poll.sh |
One bounded X relay poll: stash pending mentions, print x-mention <request_id> |
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 |