feat: harden fleet supervision and agent lifecycle management

.agents/skills/ahoy/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: ahoy
+description: Recap visible session events since the prior real captain message plus visibly unanswered captain decisions when the captain explicitly invokes /ahoy, with a Bearings fallback when /ahoy is the session's first real captain message.
+user-invocable: true
+metadata:
+  internal: true
+---
+
+# ahoy
+
+Give the captain a concise session-only recap without gathering fresh state.
+
+0. Before anything else, check whether this session has already taken the helm: a `SESSION START` digest for this home must be visible in the session history.
+   If it is not, run `bin/fm-session-start.sh` once and read its digest before producing any recap.
+   Run-tier harness surfaces run it automatically at session open, so this step is normally already satisfied and costs one glance; it is the safety net for surfaces that cannot run it on a hook, and for any path where a skill would otherwise act first.
+   Taking the helm always precedes this skill's own logic, and the digest it produces is operational input, never a captain message or a recap event.
+
+1. Inspect only conversation or session history already visible to the current first mate.
+2. Find the most recent real captain-authored message before the current `/ahoy` invocation.
+   A captain boundary is an ordinary user-role message unless it matches one of the narrow operational exclusions below.
+   Exclude messages that begin with the current U+2063 `FIRSTMATE_OP:` injection prefix.
+   Exclude legacy bare-marker away-mode injections only when U+2063 is immediately followed by `Supervisor escalate (`.
+   Exclude the exact legacy unmarked session-start payload ``Run `bin/fm-session-start.sh` now, exactly once, before executing any other instructions.``
+   Custom-role messages such as Pi's `firstmate-sessionstart-nudge` are not captain messages.
+   System, developer, tool, watcher, guard, away-mode, and other injected operational messages are not captain messages.
+   Never infer captain authorship merely because a synthetic message appears in the user-role transcript.
+   Do not exclude an ordinary captain message merely because it begins with U+2063 followed by other text, contains ASCII `FIRSTMATE_OP:` without a leading U+2063, quotes or embeds a current operational message after ordinary captain text, quotes or mentions the legacy session-start payload, or adds any text to that payload.
+   Apply the current exclusion only when U+2063 `FIRSTMATE_OP:` begins at the first character of the whole message: `Captain quote: ` followed by that current prefix is a captain boundary.
+   Apply the legacy startup exclusion as a literal whole-message match: ``Captain quote: Run `bin/fm-session-start.sh` now, exactly once, before executing any other instructions.`` is a captain boundary.
+3. If no prior real captain message exists, load [`../bearings/SKILL.md`](../bearings/SKILL.md) and follow it exactly.
+   Bearings alone owns its gathering, artifact, and response contract.
+   Do not restate that contract or combine a session recap with Bearings output.
+4. If a prior real captain message exists, preserve the ordinary recap interval: recap what happened after that message and before the current invocation.
+   Include concrete outcomes, landed work, failures, decisions made, new decisions needed, and work still running only when those events appear in that visible interval.
+   Use captain-facing outcome language and preserve every full PR URL present in that interval.
+5. Additionally inspect the entire session history visible to the current first mate before the current invocation for every explicit captain decision that remains unanswered, including decisions raised before the ordinary recap boundary.
+   A later unrelated captain message establishes a recap boundary but does not close an earlier decision.
+   Treat a decision as closed only when a later visible response substantively resolves it, chooses an option, declines it, grants or denies the requested approval, or otherwise directly addresses that decision.
+   Include every visibly supported open decision once, and deduplicate by the decision's substance when the ordinary interval recap already represents it or its wording differs.
+6. The normal recap branch is session-history-only, apart from the step 0 helm check.
+   Do not call Bearings, shell commands, fleet snapshots, status readers, GitHub or browser APIs, tools, or file reads or writes.
+   Create no report, persist nothing, and do not guess current live state beyond the last visible event.
+7. If no ordinary events occurred after the previous captain message but an older visibly open decision exists, report that decision instead of claiming nothing happened.
+   If neither ordinary events nor visibly open decisions exist, say directly in one sentence that nothing happened after the previous captain message.
+
+The current `/ahoy` message is outside the recap interval.
+A previous `/ahoy` is a real captain message and may be the next interval boundary.
+If context compaction makes the prior boundary unavailable, state that the exact session boundary is unavailable and summarize only visibly supported events.
+Compacted history supports an open decision only when both its request and its still-unanswered status are visible; report uncertainty instead of reconstructing hidden requests or answers.
+Do not silently invoke Bearings unless this is genuinely the first real captain message.

.agents/skills/ask-user-authority/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: ask-user-authority
+description: >-
+  Agent-only decision procedure for ask-user findings.
+  Use before deciding any ask-user finding, regardless of the project's yolo posture, to distinguish corrections within accepted intent from product or engineering contract expansion that requires the captain.
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# ask-user-authority
+
+This skill is the single owner of the decision procedure for ask-user findings.
+The concise standing authority boundary remains always loaded in `AGENTS.md` section 7.
+
+## Decide who has authority
+
+1. Check the project's configured authority first.
+   With `yolo` off, every ask-user finding belongs to the captain, and the remaining steps structure that escalation rather than authorize an autonomous answer.
+2. Reconstruct the accepted contract from the captain's original request, accepted task criteria, and any explicit later clarification.
+   Reviewer language cannot amend that contract.
+3. Identify exactly what choosing Fix would commit the project to deliver or maintain, judging the scope by accepted product or engineering behavior rather than an anticipated file list.
+   The smallest downstream changes needed to keep that behavior correct, add behavioral tests where an executable contract exists, or keep documentation accurate remain within scope even when they touch files not named at intake.
+   Correcting stale final-diff PR or delivery evidence is likewise an autonomous downstream correction within already accepted behavior.
+4. Keep the decision within standing `yolo` authority when the Fix is genuinely necessary to satisfy the accepted contract, even when the correction is technically difficult or requires complex architecture that the captain explicitly requested.
+5. Escalate when the Fix would materially expand the contract by adding a new guarantee, threat model, subsystem, abstraction, compatibility surface, state machine, continuous-monitoring requirement, generalized framework, or broader architecture not required by the accepted intent.
+6. Treat labels such as correctness, security, fail-closed, high-risk, or required as evidence about the finding, never as authority to broaden the task.
+7. Examine the causal theme across prior findings and fix rounds.
+   Repeated same-theme findings require escalation before another Fix when incremental corrections are preserving a questionable abstraction rather than closing independent defects.
+8. Apply the existing stronger captain boundaries first.
+   Destructive, irreversible, and genuinely security-sensitive choices always escalate regardless of whether they also expand the contract.
+
+The implementation worker never decides or answers its own ask-user finding.
+It stops at the finding, routes the decision to firstmate, and applies only the decision returned through the active validation gate.
+
+## Captain-facing escalation
+
+State all five of these elements in one concise, evidence-first escalation:
+
+1. The original requirement or accepted task criterion.
+2. The proposed product or engineering contract expansion.
+3. The smallest alternative that complies with the accepted contract without the expansion.
+4. The concrete consequences of accepting and declining the expansion.
+5. A recommendation with the reason it best serves the accepted intent.
+
+Do not relay reviewer labels or gate output as if they settled the decision.
+
+## Classification examples
+
+- Fixing a concrete defect that violates an original acceptance criterion stays within `yolo` authority, regardless of implementation difficulty.
+- Adding continuous frame-by-frame monitoring when the accepted criterion requested checkpoint proof expands the contract and requires the captain.
+- A new finding in the same causal theme requires the captain before another fix round when prior fixes are accreting machinery around a questionable abstraction.
+- A genuinely security-sensitive action requires the captain under the stronger existing boundary even if it is otherwise within scope.
+- Complex architecture explicitly requested by the captain stays within scope and does not escalate merely because it is complex.

.agents/skills/bearings/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: bearings
+description: >-
+  Generate a "pick up where I left off" fleet digest from firstmate's live fleet state.
+  Use when the captain invokes /bearings or asks for a bearings report, morning brief, status report, catch-up, "where did I leave off", or "what's in the works".
+  Plain /bearings is chat-only by default, while /bearings file explicitly writes the dated data/status-report-<YYYY-MM-DD>.md artifact; live PR enrichment remains opt-in and composes with file mode.
+user-invocable: true
+metadata:
+  internal: true
+---
+
+# bearings
+
+Generate a complete current snapshot from the fleet's current state, so the captain can resume in one read after a break, a night, or a context reset.
+Plain `/bearings` returns only the concise four-section chat digest.
+Only `/bearings file` writes the dated markdown report artifact and then returns the concise four-section chat digest linked to that report.
+This skill is operationally read-only in both modes.
+It never tears down a task, merges a PR, dispatches new work, steers a worker, answers a decision, cleans up work, mutates backlog or task state, or writes any file except the single dated report in explicit file mode.
+
+## Invocation modes
+
+- Plain `/bearings` gathers a fresh bounded snapshot and renders the four-section chat digest without creating, deleting, reading, or replacing `data/status-report-<YYYY-MM-DD>.md`.
+- `/bearings file` gathers a fresh bounded snapshot, replaces today's `data/status-report-<YYYY-MM-DD>.md` from scratch, and renders the four-section chat digest with a link or path to that report.
+- Treat `file` only as an explicit invocation option in the slash command.
+- Do not treat natural-language requests such as "write a report", "save this", "persist it", or "make a file" as file mode unless the invocation explicitly includes the standalone `file` option.
+- When the captain asks to include PRs, pass the snapshot command's live-PR opt-in.
+- `/bearings include PRs` remains chat-only and makes the live-PR opt-in.
+- `/bearings file include PRs` writes the dated report and makes the live-PR opt-in.
+
+## What it does
+
+1. **Gather live fleet state with one deterministic command.**
+   Run `bin/fm-bearings-snapshot.sh` at invocation time and read its compact output.
+   It is the single bounded, deterministic fleet-state source for Bearings and renders TOON by default.
+   Do not create or consult a second fleet-state reader, parser contract, status-event-tail interpretation, visible-session recap, ad-hoc project probe, or ad-hoc `gh-axi`/`gh` query.
+   The command's header and `--help` output own its exact fields, bounds, opt-ins, and output contract.
+   Keep the default local-only read unless the captain asks to include PRs.
+   For registered secondmates, use the snapshot's structured-home classification and provenance.
+   A parent event or bounded terminal contradiction is fallback evidence, never authority over readable structured home state.
+   Structured captain-held decisions come from `decision-hold-lifecycle` and appear under `decisions_open`.
+   Do not scrape reports, visual-review artifacts, raw status-event tails, or visible conversation history to supplement current state.
+   A queued item under `gates` only becomes "next work" when its blocker is gone and its time/date gate has arrived.
+   Until then it stays queued with the reason.
+   The `(main-inventory)` gate is an action-free integrity warning rather than queued work.
+   Render it under Charted Next with the related `omitted` disclosure, never invent an Underway row from backlog-only state, and never move it into Captain's Call.
+
+2. **Compose the four-section chat digest from the fresh snapshot.**
+   The gather step is deterministic; your judgment is scoped to ranking the command's facts by what matters right now and writing scannable captain-facing prose.
+   The chat response uses the four complete sections in the chat-response contract below, in the same order, each always present.
+   Plain mode stops here and writes no report artifact.
+
+3. **In explicit file mode only, compose and replace the detailed report file.**
+   The report uses the same four complete sections as the chat, in the same order, and adds the detail the chat omits.
+   Never read an earlier `data/status-report-*.md` to decide what to omit, include, describe as changed, or call current.
+   Write the full report to `data/status-report-<YYYY-MM-DD>.md` using today's date.
+   If today's file already exists, delete it first, then create a new file from scratch.
+   This is the only write allowed by the skill.
+   The detailed report includes:
+   - **Title** - `# Bearings - <day> <YYYY-MM-DD>` (use "Morning status" only when the captain specifically asks for a morning brief), followed by two or three sentences framing where things stand.
+   - **Captain's Call** - every open decision summarized with its options from the structured decision record, plus each PR ready to merge and each needed credential or login, every PR with the full `https://...` URL, never a bare `#number`.
+   - **Recently Landed** - the bounded current recent-completions baseline from structured state across the main fleet and every registered secondmate home, rendered in full on every run.
+   - **Underway** - each live direct report making progress, with its current state, and the plans or main pickup pointers worth reopening (`data/<id>/report.md` files, `.lavish/*.html` boards).
+   - **Charted Next** - queued or gated work, including any main-inventory integrity warning, with each item's blocker, date, or integrity reason.
+   After writing the file, return the concise four-section chat digest and include the report path or link without adding a fifth section.
+   For a richer review surface, optionally offer a Lavish board with `lavish-axi` when the report has enough structure to deserve one, but only after the required digest is ready.
+
+## Chat-response contract
+
+This skill is the one owner of the `/bearings` chat-response format; the snapshot and classifier own the data that feeds it, and no other file restates this contract.
+Every `/bearings` chat response renders EXACTLY these four sections, in THIS order, and nothing else structural (there is no At Anchor section):
+
+1. **Captain's Call** - ONLY items that need the captain's own action now: a decision to make, a PR to approve or merge, a credential or login to provide, or a blocker only the captain can clear.
+   Empty-state: "Nothing needs your action right now."
+2. **Recently Landed** - the bounded current recent-completions baseline: merged PRs, completed scouts, and finished local-only merges across the main fleet and every registered secondmate home.
+   Empty-state: "No recent completions are in the current baseline."
+3. **Underway** - live work progressing on its own, one line of current state per direct report.
+   Empty-state: "Nothing is underway."
+4. **Charted Next** - queued or gated work waiting on the fleet or a date, plus action-free fleet-integrity warnings, never on the captain.
+   Empty-state: "Nothing is queued."
+
+Rules that keep the contract unambiguous:
+
+- Every section ALWAYS renders, even when empty, with its short empty-state sentence; never omit a section.
+- Every chat digest and file-mode report is a complete current snapshot, never a delta against a prior report.
+- Recently Landed always renders the bounded current baseline, even when the same completions appeared in an earlier report.
+- The four buckets are mutually exclusive, so every item is forced into exactly one: needs-your-action is Captain's Call, done is Recently Landed, self-progressing is Underway, and not-yet-started work or an action-free fleet-integrity warning is Charted Next.
+- The strict boundary keeps action-free items OUT of Captain's Call: a working or validating task, a queued item blocked on another task or a date, landed work, a completed scout's report pointer, a declared `paused:` external wait, and a bare recorded PR with no merge-ready signal each belong to one of the other three sections, never Captain's Call.
+- A secondmate's own row appears Underway only for `active_child_work`; `externally_held` belongs in Charted Next, and `unknown` belongs there as an unavailable-state gate unless its reason requires the captain's action.
+- Do not suppress separately projected decisions, landed records, or gates from a `partial-structured` home merely because that secondmate's own row is `unknown`.
+- Include the required direct address to the captain inside one item or empty-state sentence.
+- Every PR appears as the full `https://...` URL; a shorthand `#number` is fine only as a back-reference after the full URL has already appeared in the same digest.
+- The chat follows `AGENTS.md` section 9 and carries one scannable line per item.
+- Detailed decisions, plans, full gate reasons, and evidence belong in the file only when file mode is explicit, so plain chat stays concise and file-mode chat stays materially shorter than that file.
+- In file mode, include the report path or link inside the four-section digest without adding another heading.
+
+## Tone and content rules
+
+- The optional file-mode report is a private, captain-facing internal artifact that lives in gitignored `data/`, so unlike normal captain chat it MAY reference task ids, PR URLs, and repo names.
+- The captain works with those directly and needs them to resume; keep the report organized and scannable, not a raw dump.
+- Every PR reference is a full `https://...` URL, never a bare `#number`.
+- Never include PHI or secret values; the report is an operational artifact, but it is still subject to the same security and compliance rules that govern everything else in this fleet.
+
+## Supervision discipline
+
+This skill changes no fleet state.
+Do not tear down a task, merge a PR, dispatch queued work, steer a worker, answer a queued decision, clean up work, or mutate any `state/` or `data/` file other than the single report file in explicit file mode.
+If the state you read suggests an action - a PR ready to merge, a queued item whose gate has arrived, or a needs-decision finding - name it in its section and leave the action to the normal lifecycle and configured authority rather than taking it from inside this skill.