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.
| 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 deterministic state, bounded judgment capture, and session-start recovery |
fm-autocompact-judgment.py |
Extract transcript judgment and publish validated private-memory or backlog edits safely |
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-decision-pretool-check.sh |
Exact-identity gate that routes structured captain decisions to Lavish (docs/decision-pretool-check.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-worker-lifecycle.sh |
Queue, fence, reconcile, recover, and scale provider-neutral task workers to zero |
fm-worker-lifecycle.py |
Own the durable elastic-worker state machine and bounded provider JSON seam |
fm-worker-supervisor.py |
Execute one exactly bound command and emit one bounded digest-bound guest result |
fm-worker-authority.py |
Issue release receipts from ordinary endpoint, report, landing, account, and worktree authorities |
fm-azure-worker-provider.py |
Reconcile exact Azure worker generations through the landed private foundation |
fm-cloud-env-contract.py |
Derive the FM_AZURE_* names a cloud placement must persist for the closed monitor pane |
fm-spawn.sh |
Spawn, native-resume, or provider-neutrally continue crewmates while recording pre-metadata Treehouse acquisition ownership |
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-handoff.sh |
Refresh and present a task-owned handoff with live mutation custody |
fm-treehouse-lib.sh |
Prove Treehouse task lease presence or absence and resolve one unique leased worktree |
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 an approved local-only branch and immediately invoke terminal auto-reaping |
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-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-auto-reap.sh |
Reap proven terminal tasks and aged, owner-dead pre-metadata Treehouse acquisitions |
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-azure-pilot.sh |
Validate, preview, apply, inspect, recover, or explicitly remove the private Azure foundation |
fm-azure-runner.sh |
Run one credential-free exact repository command on one private disposable Azure VM |
fm-credential-expiry.py |
Classify one account profile's provider credential by expiry without emitting token material |
fm-pi-account-home.py |
Project one Pi profile from the pooled auth.json into the single-profile account home its consumers read |
fm-pi-refresh.py |
Renew Pi credentials before they expire, republish them into their account homes, and verify the result |
fm-pi-refresh.mjs |
Rotate one Pi credential through Pi's own OAuth refresh and its own credential lock (the actuator fm-pi-refresh.py drives) |
fm-lint-node.sh |
Parse every JavaScript tool in bin/, the lane ShellCheck's shell-only file set cannot cover |
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_bounded_io.py |
Shared Python bounds for process trees, aggregate output, JSON artifacts, and item batches |
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-lavish-board.sh |
Open a self-contained decision or annotation board and arm its profile-first bounded submission check |
fm-lavish-intake.sh |
Invoke compatible store-and-forward Lavish intake at an existing turn boundary |
fm-lavish-queue.sh |
Queue redundant visible delivery only to a session-lock-proven home-bound supervisor |
fm-lavish-version-lib.sh |
Shared Lavish store-forward minimum-version compatibility check |
fm-lavish-wake.sh |
Append a durable answer pointer, then attempt proven home-bound visible delivery |
fm-wake-drain.sh |
Intake Lavish answers, atomically drain queued 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-github-pr.py |
Adapt observed gh-axi TOON PR reads through a fail-closed read-only CLI |
fm-crosscheck.sh |
Run, verify, time, or atomically merge through the durable exact-head PR finding ledger |
fm-crosscheck.py |
Validate and execute crosscheck reviewer evidence and finding lifecycle transitions |
fm-crosscheck-slack.sh |
Run, preflight, or selftest the exact-head Slack Crosscheck lane |
fm-crosscheck-slack.py |
Serve allowlisted, metered, exact-head Slack reviews through the shared core lanes |
fm-crosscheck-slack-service.sh |
Install and operate the credential-free macOS launchd wrapper for the central listener |
fm-pr-check.sh |
Register a PR-ready task; see Crosscheck operator flow |
fm-pr-merge.sh |
Require exact-head crosscheck, record PR metadata, and atomically merge or enqueue the reviewed SHA |
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-session-lock-lib.sh |
Shared session-lock format, holder liveness, and home-bound supervisor route proof |
fm-lint.sh |
Single owner of the shell-lint definition used locally and in CI |
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 |