bootstrap-diagnostics

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 inline rules in AGENTS.md section 3 still bind: detect, then consent, then install - never install anything 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>) - 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...>. For treehouse, this also covers an installed version whose treehouse get lacks --lease; treat it as an upgrade request. For no-mistakes, this also covers an installed version older than 1.46.0, because this repo's PR gate requires structured pipeline attestation that older builds do not write. For any axi-family tool - gh-axi, lavish-axi, tasks-axi, quota-axi - an installed version below its floor is a plain upgrade request; bin/fm-bootstrap.sh owns the floor policy, and never argue the floor down to whatever the home happens to have installed. For tasks-axi, this additionally covers an installed build that fails 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 missing-tool 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 missing requirement and do not choose around an unexamined candidate.
• 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 lock was no longer held line means the session that asked for the sweeps no longer owns them, so leave them to the session that does.
• 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.
• 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.