firstmate: Skill for Claude Code

bootstrap-diagnostics

Handle each printed line as below, before dispatching work that depends on it. The line formats themselves are owned by bin/fm-bootstrap.sh's header; this playbook owns the response to actionable lines. The session-start rules in session-start-recovery still bind: detect, then consent, then install or upgrade - never change a tool the captain has not approved in this session - and no work is dispatched until the tools it needs are present and GitHub auth is good. When any diagnostic needs captain attention, report the plain consequence and requested action using AGENTS.md section 9's captain-facing translation contract; do not name the diagnostic label unless the captain needs to paste it into a command or issue.

• MISSING: <tool> (install: <command>) - the tool is absent; list the missing tools to the captain with a one-line purpose each plus the printed install commands, wait for consent (one approval may cover the list), then run bin/fm-bootstrap.sh install <approved tools...>. An installed tool below its floor, or one missing a required capability, reports OUTDATED: instead.
• OUTDATED: <tool> (installed: <version|unparseable>; requires <floor|capability>; upgrade: <command>) - the tool is present but below what this home needs, so it is an upgrade request, not an install. Report the installed version and the printed upgrade: command and wait for the same consent rule before running it; a printed command that is the tool's own installer means that tool ships no self-updater yet, so the upgrade reuses its install command. bin/fm-bootstrap.sh owns the floor policy, and never argue the floor down to whatever the home happens to have installed. For no-mistakes, the floor is 1.46.0 because this repo's PR gate requires structured pipeline attestation that older builds do not write. For treehouse, the requirement is treehouse get --lease support. For tasks-axi, the requirement also covers the separate feature probe (bin/fm-tasks-axi-lib.sh owns the definition); config/backlog-backend=manual only suppresses the verbose BOOTSTRAP_INFO: tasks-axi available fact, not this report. For quota-axi, bootstrap requires it because firstmate reads its current output directly before resolving every crew-dispatch profile array; without it, report the requirement and do not choose around an unexamined candidate.
• PRESENTATION_UNAVAILABLE: lavish-axi ... - explain that visual presentation is unavailable and continue nonvisual work with plain-text decisions and reports; do not hold unrelated dispatch for installation consent. Do not use Lavish until it satisfies the floor owned by bin/fm-bootstrap.sh; when visual work needs it, request consent for the printed install or upgrade command, then rerun bootstrap to confirm compatibility before using it. Scout briefs check the same floor when scaffolded and ask for a text report instead of a Lavish loop, so scaffold a visual scout only after that rerun confirms compatibility.
• MISSING_MANUAL: <tool> (instructions: <url>) - tell the captain why the tool is required and give them the printed instructions URL, but do not pass the tool to bin/fm-bootstrap.sh install; wait for the captain to complete the manual installation, then rerun session start to confirm the dependency is present.
• BACKEND_INVALID: <name> (known: <names>) - the resolved runtime backend has no verified dependency or lifecycle contract, so do not dispatch work until the invalid FM_BACKEND or config/backend value is corrected to one of the listed backends.
• NEEDS_GH_AUTH - ask the captain to run ! gh auth login (interactive; you cannot run it for them). This probe now arrives from the deferred network stage, so it is also how an unreachable network shows up: gh cannot validate its token offline and reports the same failure. Confirm reachability before asking the captain to re-authenticate a credential that may be fine.
• NETWORK_CHECKS: <what did not complete>; rerun <command> - the deferred network stage itself could not finish, so the checks it names are simply unknown, not failed. Rerun the printed command; it is idempotent and re-derives every finding. A hit the ...s bound line means one of those checks is slow or unreachable - most often a remote secondmate host - and the stage stopped rather than letting it wedge; a recorded fleet lock holder changed line means lock line 1 no longer names the pid that requested the sweeps, because another session took the lock or this session re-anchored it, so they were skipped and belong to whichever session holds the lock now.
• TANGLE: <remediation> - the primary checkout is stranded on a feature branch instead of its default branch; AGENTS.md section 8 explains why this guard exists and what it protects. The work is safe on that branch ref; restore the primary to its default branch with the printed git -C <root> checkout <default>, then re-validate that branch in a proper worktree. This is the only sanctioned firstmate-initiated git write to the primary, and it is a non-destructive branch switch that strands nothing.
• STARTUP_MEMORY_BUDGET: invalid config/startup-memory-budget - <reason> - the visible startup-memory budget is not a safe one-line positive decimal file; do not infer the default or propagate it. Correct the local primary file, then rerun session start so the normal convergence path can deliver the validated value to secondmate homes.
• CREW_DISPATCH: invalid config/crew-dispatch.json - <reason> - the optional dispatch profile file exists but failed low-cost bootstrap validation; stop profile-based dispatch, report the actionable error, and require correction of the malformed schema, unverified harness name, or invalid harness/effort pair rather than falling back around it or selecting a bad profile.
• FLEET_SYNC: <repo>: skipped: <reason> - a benign one-off skip (offline, no origin, local-only); bootstrap continued, investigate only if it blocks work. A skip can also report the bounded fleet-refresh timeout (FM_FLEET_SYNC_BOOTSTRAP_TIMEOUT, or a fleet-size-aware default with a 20 second floor); a timeout never blocks startup. skipped: registry entry does not resolve to a delivery posture is the one skip that is not one-off: the clone is left alone on every bootstrap until data/projects.md is corrected, so run the printed bin/fm-project-mode.sh <repo> to read the refusal and fix the entry.
• FLEET_SYNC: <repo>: recovered: <detail> - the clone had drifted onto a clean detached HEAD holding no unique commits and the sync self-healed it (re-attached the default branch and fast-forwarded); no action needed, it is reported only so the self-heal is visible.
• FLEET_SYNC: <repo>: STUCK: on <state>, N commits behind <base> - needs attention - the clone is dirty, on a non-default branch, detached with unique commits, or diverged, so the sync left it untouched (never forcing or discarding); it will keep falling behind until you look. A loud STUCK, especially a growing N across bootstraps, means that clone needs hands-on attention; dispatch a crewmate or resolve it before it strands work.
• HOME_SUMMARY: this home has never published state/home-summary.json or ... has not been republished since <stamp> - this home's structured summary publication has failed repeatedly, and the line carries the failure count and the newest recorded reason from state/.home-summary-refresh.log. Publication is deliberately best-effort, so it cannot change another session-start, spawn, teardown, or watcher-poll result, and the watcher runs it detached so a slow attempt cannot delay the liveness beacon. Read the named record for the recorded reasons, then reproduce with a direct bin/fm-home-summary-refresh.sh (no --best-effort, which is what keeps the failure quiet) so the refresh error reaches you. A recorded deadline means the complete refresh did not finish inside FM_HOME_SUMMARY_TIMEOUT, so inspect lock acquisition and producer completion before validation or publication, and fix the blocked phase rather than raising this load-bearing bound.