scripts.md

The bin/ toolbelt

The first mate drives these; interactive entrypoints work by hand too, while *-lib.sh files are sourced helpers. Each file also starts with a short header comment. 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	Description
fm-session-start.sh	The one command AGENTS.md sections 3 and 5 run at every session start: composes fm-lock.sh, fm-bootstrap.sh (its three mutating sweeps gated on holding the lock via FM_BOOTSTRAP_DETECT_ONLY), and fm-wake-drain.sh, then prints a full context digest (data/projects.md, data/secondmates.md, data/captain.md, data/learnings.md, each ABSENT-marked when missing) and fleet-state digest (data/backlog.md, every state/*.meta, a bounded state/*.status tail, state/.afk, and a cheap per-task endpoint-liveness read); prints a loud read-only banner and skips every mutating step when the lock is held elsewhere; never arms the watcher itself
fm-bootstrap.sh	Detect required toolchain and version problems, dispatch profile JSON errors or active-rule blocks, default backlog-backend status, primary-checkout TANGLE: problems, and actionable clone refresh outcomes; refresh project clones best-effort; locally sync live secondmate homes and propagate declared inheritable config; set up opt-in X mode; install tools only after consent; FM_BOOTSTRAP_DETECT_ONLY=1 skips the three mutating sweeps and prints advisory-only TANGLE: wording without a checkout command
fm-fleet-sync.sh	Fetch clones, fast-forward safe default-branch states, self-heal clean detached ancestor drift, report unsafe drift as STUCK:, and safely prune branches whose remote is gone
fm-update.sh	Self-update the running firstmate repo and registered secondmate homes with fast-forward-only pulls from origin
fm-backlog-handoff.sh	Move already-judged in-scope queued backlog items from the main home into a seeded secondmate home
fm-brief.sh	Scaffold a ship brief with a worktree-isolation assertion, a report-only scout brief with --scout, or a secondmate charter with --secondmate
fm-ensure-agents-md.sh	Ensure project AGENTS.md is the real memory file and CLAUDE.md symlinks to it
fm-guard.sh	Warn when the primary checkout is tangled, when queued wakes are pending, or when a stale or missing watcher needs a prominent banner; FM_GUARD_READ_ONLY=1 keeps the alarms but suppresses drain, arm, and checkout repair commands
fm-turnend-guard.sh	Claude Code Stop hook, primary-scoped only: blocks (exit 2, exact reason) a primary turn end when work is in flight without a live identity-matched watcher lock and fresh beacon, using Claude Code's own stop_hook_active field so it never blocks twice in one turn (docs/turnend-guard.md)
fm-home-seed.sh	Lease/provision a secondmate home transactionally, clone projects, initialize gates, and maintain data/secondmates.md
fm-spawn.sh	Spawn one task, several id=repo pairs, or a persistent secondmate with --secondmate; accepts concrete --harness, --model, --effort, and --backend axes; ship/scout spawns require an explicit resolved harness when dispatch profiles are active and an isolated worktree, install per-harness turn-end signaling, and secondmate spawns resolve the secondmate harness plus optional config/secondmate-harness model/effort tokens, locally sync the home, propagate declared inheritable config, land herdr tabs in the target home's workspace, land home-scoped zellij tabs in the selected shared zellij session, land cmux workspaces in the shared cmux app, or create Orca worktrees/terminals before launch
fm-backend.sh	Runtime session-provider backend selector with explicit/env/config/runtime auto-detection precedence, meta helper, selector resolver, spawn-capability validation, operation dispatcher, and shell-portable backend-name membership for bash-sourced scripts or zsh-sourced diagnostics; defaults absent backend= meta to tmux; fm_backend_target_exists is a cheap read-only alive/dead endpoint check that never starts a server or session; fm_backend_composer_state exposes backend composer checks for guarded submit paths
fm-backend-hometag-lib.sh	Shared home-tag derivation for zellij tab titles and cmux workspace titles, using the active FM_HOME label plus a short hash of the resolved FM_ROOT path
backends/tmux.sh	Verified tmux session-provider adapter used by fm-backend.sh; owns create, send, capture, current-path, live-window, and kill primitives
backends/herdr.sh	Experimental herdr session-provider adapter used by fm-backend.sh; owns version/tool gating, per-home workspace/tab creation, created-vs-adopted default-tab prune safety, restored-layout husk respawn replacement, session-scoped CLI calls, send with structural composer-state verification, capture, native busy-state, current-path, label-based live discovery, and kill primitives
backends/zellij.sh	Experimental zellij session-provider adapter used by fm-backend.sh; owns version/tool gating, one-session/tab-per-task creation with home-scoped titles, session-scoped CLI calls, send, capture, active current-path probing, label-checked target safety, scoped live discovery, legacy-title fallback, and tab cleanup primitives
backends/orca.sh	Experimental Orca backend used by fm-backend.sh; owns repo registration, worktree creation/removal, terminal creation, capture, send text, Enter/Ctrl-C interrupt keys, and close; Escape is unsupported
backends/cmux.sh	Experimental cmux session-provider adapter used by fm-backend.sh; owns version/tool/socket-access gating, home-scoped workspace creation, current-path probing, title-based recovery, send/capture, structural composer-state verification, Enter/Escape/Ctrl-C keys, and workspace cleanup primitives
fm-config-push.sh	Config-only mid-session push of declared inheritable local config into live secondmate homes; reports each item as pushed, unchanged, skipped, or error without fast-forwarding tracked files or nudging agents
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, warning and falling back to the local branch when an expected PR head cannot be resolved, with optional --stat output
fm-marker-lib.sh	Shared from-firstmate request marker and detector sourced by fm-send.sh, fm-brief.sh, and tests
fm-watch-arm.sh	Verified per-home watcher re-arm; reports started, healthy, or FAILED; --restart relaunches only this home's watcher
fm-watch.sh	Singleton-safe always-on watcher and default pull-based event source; uses backend-native busy state when available before the shared regex fallback, absorbs no-verb signal and stale wakes only when the crew is provably working, checks that evidence before trusting stale status-log terminality, queues and exits for actionable wakes, and reverts to daemon-owned one-shot behavior while state/.afk exists
fm-supervise-daemon.sh	Presence-gated sub-supervisor for walk-away (/afk) supervision: wraps fm-watch.sh, uses the shared wake classifier, backend-aware stale rechecks, and tmux/herdr supervisor injection, self-handles routine wakes in bash, and escalates only captain-relevant events as one verified, batched, single-line digest prefixed with a sentinel marker
fm-crew-state.sh	Print one stable current-state line for a crew by reconciling its matching no-mistakes run-step, including coarse cross-branch attribution from no-mistakes runs, even when the pane has closed, with backend-aware pane fallback that corroborates native idle/unknown verdicts before the status log
fm-tangle-lib.sh	Shared default-branch resolution and primary-checkout tangle classification sourced by bootstrap and guard
fm-supervision-lib.sh	Shared grace-based "in-flight work exists but no watcher has a fresh beacon" status and predicate used by fm-guard.sh; fm-turnend-guard.sh uses it for banner fields and relies on fm-wake-lib.sh for live watcher lock health
fm-ff-lib.sh	Shared guarded fast-forward helper for /updatefirstmate origin pulls and no-fetch local secondmate syncs
fm-config-inherit-lib.sh	Shared primary->secondmate inheritable-config propagation (a declared, extensible item list - currently config/crew-dispatch.json, config/crew-harness, and config/backlog-backend) sourced by spawn, bootstrap, and config push
fm-tasks-axi-lib.sh	Shared backlog-backend selector and tasks-axi compatibility probe sourced by bootstrap and teardown
fm-wake-drain.sh	Atomically drain queued watcher wakes before handling supervision work, then run the watcher-liveness guard
fm-wake-lib.sh	Shared durable wake queue, portable lock helpers, and watcher identity/health helpers sourced by the watcher, drain, arm, guard, turn-end guard, and daemon
fm-classify-lib.sh	Shared captain-relevant wake classifier sourced by the watcher and daemon, plus the watcher's provably-working predicate
fm-send.sh	Send one verified literal line or backend-supported --key through the target's recorded runtime backend; exits non-zero on confirmed swallowed Enter; bare kind=secondmate targets are marked as from-firstmate; slash commands and codex $... skill invocations get popup-settle before backend-specific submit verification; text sends pause FM_SEND_SETTLE seconds after success
fm-tmux-lib.sh	Shared tmux pane primitives for busy detection, dim-ghost-aware and border-aware composer detection, and verified submit retry
fm-peek.sh	Print a bounded tail of a crewmate endpoint through the target's recorded runtime backend
fm-pr-check.sh	Record pr= and GitHub's pr_head= when available for a PR-ready task, then arm the watcher's merge poll
fm-pr-merge.sh	Require a full GitHub PR URL, record pr= and available pr_head= via fm-pr-check.sh, parse it into gh-axi pr merge <n> --repo <owner>/<repo>, default to --squash unless a merge method is forwarded, and reject malformed URLs or repo overrides
fm-promote.sh	Promote a scout task in place so it becomes a protected ship task
fm-teardown.sh	Return a clean, landed ship worktree or retire/release a secondmate home; requires scout reports, checks child work, removes firstmate-owned hook artifacts, closes recorded backend endpoints under their owning home context, releases Orca worktrees through orca worktree rm, and prints the backlog-backend reminder
fm-harness.sh	Detect the running harness; resolve the effective crewmate (crew) or secondmate-launch (secondmate) harness; expose optional config/secondmate-harness model and effort tokens with secondmate-model and secondmate-effort
fm-lock.sh	Per-home firstmate session lock
fm-x-lib.sh	Shared X-mode .env, alternate env-file, relay, dry-run config, reply-thread splitting, outbound image payloads, and task-to-X-request meta-link helpers
fm-x-poll.sh	Do one bounded X relay poll; without FMX_PAIRING_TOKEN it is silent, with a pending mention it stashes the full inbox JSON, including in_reply_to, and prints x-mention <request_id>
fm-x-reply.sh	Post or dry-run preview a composed public-safe X answer or --followup, auto-splitting long text into {request_id,text,texts} threads and optionally attaching --image <path> to the opener; reads text from an argument, stdin, or --text-file
fm-x-dismiss.sh	Dismiss or dry-run preview a skipped X mention without replying by sending {request_id} to the relay's connector/dismiss endpoint
fm-x-link.sh	Link a spawned task to its originating X mention by recording x_request=, x_request_ts=, and a follow-up counter x_followups= in state/<id>.meta; paired --carry-count <n> --carry-ts <epoch> preserves the original counter and timestamp when re-linking onto a successor task
fm-x-followup.sh	Detect, post, and manage up to three completion follow-ups (within a 7-day window) for an X-linked task, forwarding optional --image <path>, incrementing the counter on a non-final success, clearing the link on --final/cap/window/relay-rejection, and retrying only on a generic post failure