feat(beads): Add lifecycle labels to dispatch and claim flow for mg badge rendering

AGENTS.md

@@ -259,6 +259,7 @@ Write the task-specific brief under section 11 before spawning.
 Spawn only through `bin/fm-spawn.sh` after the profile and backend checks in section 4.
 The spawn must resolve a genuine isolated task worktree distinct from the primary checkout; a failed isolation assertion stops the task.
 After spawning, confirm the worker is processing the brief, handle any trust dialog through `harness-adapters`, and record ship or scout work as under way.
+When spawning with `--beads <id>`, the task is linked to an external bead item for progress tracking on `mg` or similar tools; `fm-bead-stamp.sh` stamps the bead's `dispatch=sent` and `lifecycle=sent` state dimensions, and the generated brief includes instructions for the worker to confirm `dispatch=claimed` and `lifecycle=claimed` after reading, and to close the bead on completion.
 A persistent secondmate is recorded in the secondmate registry and runtime state, never as a backlog work item.
 
 Steer a worker with short single-line messages through fail-closed `fm-send`; put long instructions in a file.
@@ -455,6 +456,7 @@ Every ship brief must retain the worktree-isolation assertion and stop if launch
 If a ship task touches firstmate's shared tracked material, explicitly require `firstmate-coding-guidelines` before editing.
 If a task will drive Herdr lifecycle behavior, scaffold with `--herdr-lab`; if that need appears after an unguarded scaffold, stop and regenerate rather than adding commands by hand.
 The generated Herdr contract must use a named non-`default` isolated lab and its guarded helper for every lifecycle action.
+When a task is linked to an external bead (via `--beads <id>` at spawn), set `FM_HOOK_BEADS_ID=<id>` before scaffolding so the brief receives Bead Receipt and Bead Closure sections that guide the worker's interaction with the tracking system.
 
 Load `secondmate-provisioning` before creating or using a charter brief and preserve its idle-by-default and marked-return-channel contracts.
 Status appends are sparse supervisor-actionable events, not routine progress; `bin/fm-classify-lib.sh` owns keyed open and resolved semantics.

bin/fm-bead-stamp.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# Stamp a linked bead as dispatched: sets its dispatch=sent state dimension and
+# assigns it to the launched agent. Called by fm-spawn.sh after a successful
+# spawn when the task was launched with --beads <id>.
+# Fail-open by design: a missing `task` CLI, an empty beads id, or a bead the
+# CLI cannot find warns on stderr and exits 0 so a bead-tracking problem never
+# blocks or fails a spawn.
+# Usage: fm-bead-stamp.sh <beads_id> <agent_name>
+set -u
+
+BEADS_ID=${1-}
+AGENT=${2-}
+
+if [ -z "$BEADS_ID" ]; then
+  echo "warning: no bead id given, skipping stamp" >&2
+  exit 0
+fi
+
+if ! command -v task >/dev/null 2>&1; then
+  echo "warning: task CLI not found on PATH, skipping stamp for $BEADS_ID" >&2
+  exit 0
+fi
+
+if [ -z "$AGENT" ]; then
+  echo "warning: no agent name given, skipping stamp for $BEADS_ID" >&2
+  exit 0
+fi
+
+if ! task show "$BEADS_ID" >/dev/null 2>&1; then
+  echo "warning: bead $BEADS_ID not found, skipping stamp" >&2
+  exit 0
+fi
+
+if ! task set-state "$BEADS_ID" dispatch=sent --reason "dispatched: agent=$AGENT" >/dev/null 2>&1; then
+  echo "warning: could not set dispatch=sent on bead $BEADS_ID" >&2
+fi
+
+if ! task set-state "$BEADS_ID" lifecycle=sent --reason "dispatched: agent=$AGENT" >/dev/null 2>&1; then
+  echo "warning: could not set lifecycle=sent on bead $BEADS_ID" >&2
+fi
+
+if ! task assign "$BEADS_ID" "$AGENT" >/dev/null 2>&1; then
+  echo "warning: could not assign bead $BEADS_ID to $AGENT" >&2
+fi
+
+exit 0

bin/fm-brief-hooks.d/beads.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# fm-brief.sh hook: when FM_HOOK_BEADS_ID is set, emit the Bead Receipt and
+# Bead Closure brief sections. Sourced by fm-brief.sh inside a subshell, which
+# captures this script's stdout and prepends it to the generated brief.
+# A bare `exit 0` below only ends that subshell, never fm-brief.sh itself.
+set -u
+
+[ -n "${FM_HOOK_BEADS_ID:-}" ] || exit 0
+
+cat <<SECTION
+# Bead Receipt
+This task is linked to bead \`$FM_HOOK_BEADS_ID\`.
+Before anything else - your first action, before the setup below - prove you received and read this brief:
+\`\`\`
+task set-state $FM_HOOK_BEADS_ID dispatch=claimed --reason 'brief read and accepted'
+task set-state $FM_HOOK_BEADS_ID lifecycle=claimed --reason 'brief read and accepted'
+\`\`\`
+
+# Bead Closure
+Before appending \`done:\` to the status file, close this bead: \`task close $FM_HOOK_BEADS_ID\`.
+That closure is what a registered watcher check uses to trigger your cleanup - do this as the last step before reporting done.
+SECTION

bin/fm-brief.sh

@@ -26,6 +26,12 @@
 #   The flag must be explicit because {TASK} is filled after scaffolding and the
 #   caller-supplied repo string cannot reliably identify this repo. Briefs made
 #   without it carry a loud declaration so an omitted contract cannot be silent.
+# Hook system: when environment variables like FM_HOOK_BEADS_ID are set, executable
+# scripts in fm-brief-hooks.d/ are sourced in a subshell during scaffolding, and their
+# stdout is prepended to the generated brief. The beads hook (fm-brief-hooks.d/beads.sh)
+# is automatically invoked when FM_HOOK_BEADS_ID is set, adding Bead Receipt and
+# Bead Closure sections that ask the worker to confirm dispatch/lifecycle state changes
+# and close the bead on completion.
 # For ship tasks, the definition of done is shaped by the project's delivery mode
 # (data/projects.md via fm-project-mode.sh; see the project-management skill
 # and AGENTS.md task lifecycle):

bin/fm-spawn.sh

@@ -81,6 +81,11 @@
 #   --scout records kind=scout in the task's meta (report deliverable, scratch worktree;
 #   see AGENTS.md task lifecycle); --secondmate records kind=secondmate and launches in a
 #   provisioned firstmate home; the default is kind=ship.
+#   --beads <id> links this task to an external bead item for lifecycle tracking: the
+#   dispatch=sent and lifecycle=sent state dimensions are stamped via fm-bead-stamp.sh
+#   after spawn, and the brief includes Bead Receipt/Closure sections (when FM_HOOK_BEADS_ID
+#   is set) asking the worker to confirm dispatch=claimed/lifecycle=claimed and close the
+#   bead on completion.
 #   Before a secondmate launch, the home is locally fast-forwarded to the primary
 #   default-branch commit when safe; skipped syncs warn and launch unchanged.
 #   Ship/scout spawns refuse to launch unless the resolved task path is a real

docs/scripts.md

@@ -18,7 +18,8 @@ The shared no-mistakes gate refusal for fleet lifecycle entrypoints is summarize
 | `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-decision-hold.sh`    | Create, verify, complete, and resolve durable captain-held decisions                 |
-| `fm-brief.sh`            | Scaffold ship, scout, secondmate-charter, and Herdr-lab briefs                       |
+| `fm-brief.sh`            | Scaffold ship, scout, secondmate-charter, and Herdr-lab briefs; load hooks when FM_HOOK_BEADS_ID or other hook env vars are set |
+| `fm-bead-stamp.sh`       | Stamp a linked bead's dispatch and lifecycle state when a task is spawned with --beads |
 | `fm-herdr-lab.sh`        | Provision and guardedly operate an isolated, never-default Herdr lab session         |
 | `fm-install-herdr.sh`    | Install CI's exact-version Herdr pin with official asset URL, SHA-256, and protocol checks |
 | `fm-install-treehouse.sh`| Install CI's exact-version Treehouse pin for real-Herdr E2E that needs spawn worktrees |