@zerwiz/ymir 0.1.4 → 0.1.5

package/.agents/backend/fm-fleet-sync.sh

@@ -0,0 +1,458 @@
+#!/usr/bin/env bash
+# Refresh project clones: fast-forward the checked-out local default branch to
+# origin/<default> when safe, and prune local branches whose upstream tracking
+# branch is gone (the remote branch was deleted, i.e. its PR merged) and that no
+# worktree still needs.
+# Self-heals the one unambiguously safe drift: a clean, detached HEAD that holds
+# no unique commits (it is an ancestor of origin/<default>) and whose <default>
+# branch is free to check out is re-attached and then fast-forwarded ("recovered:").
+# Every other off-default state - a non-default named branch, a detached HEAD with
+# unique commits, a dirty tree, or a diverged default - may hold real work, so it
+# is left untouched and reported as a quantified, loud "STUCK: ... N commits behind
+# ... - needs attention" warning rather than a quiet drift. Nothing is ever forced,
+# stashed, or discarded.
+# Still skips (benignly) local-only/no-origin projects, missing remotes/branches,
+# and fetch failures.
+# A candidate under projects/ must be the root of its own work tree: git discovery
+# walks up, so a plain nested directory would otherwise resolve to the enclosing
+# repository (the firstmate checkout) and be synced under that directory's label.
+# Anything else is reported as "skipped: not a clone root" naming the repository
+# that would have been touched.
+# Pruning never deletes the checked-out branch or a branch that still has a
+# worktree, so it cannot discard unlanded work; set FM_FLEET_PRUNE=0 to disable it.
+# When the fetch fails on an orphaned .git/packed-refs.lock (left by a ref rewrite
+# killed mid-write - e.g. a timed-out bootstrap sync or a teardown process kill),
+# it is retried with a bounded wait and removed only when provably stale; see
+# fetch_with_packed_refs_lock_guard and the FM_FLEET_SYNC_PACKED_REFS_LOCK_* knobs.
+# Usage: fm-fleet-sync.sh [<project-dir-or-name>]
+# The single-project form accepts either a path (absolute, or relative to the
+# caller's cwd) or a bare "<name>"/"projects/<name>" form, resolved against
+# this home's projects dir ($FM_HOME/projects, or $FM_PROJECTS_OVERRIDE).
+# Bare names and "projects/<name>" forms prefer this home's projects dir before
+# falling back to an explicit path. Example: from anywhere,
+# `fm-fleet-sync.sh dotfiles-private` syncs just that one clone, same as
+# passing its full projects/dotfiles-private path.
+set -eu
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+FM_ROOT="${FM_ROOT_OVERRIDE:-$(cd "$SCRIPT_DIR/.." && pwd)}"
+FM_HOME="${FM_HOME:-${FM_ROOT_OVERRIDE:-$FM_ROOT}}"
+PROJECTS="${FM_PROJECTS_OVERRIDE:-$FM_HOME/projects}"
+# shellcheck source=bin/fm-lock-lib.sh
+. "$SCRIPT_DIR/fm-lock-lib.sh"
+# Inert unless FM_TIMING_LOG names a file; only the deferred network stage sets it.
+# shellcheck source=bin/fm-timing-lib.sh
+. "$SCRIPT_DIR/fm-timing-lib.sh"
+FM_LOCK_LOG_PREFIX=fleet-sync
+"$FM_ROOT/bin/fm-guard.sh" || true
+
+# Bounded recovery for an orphaned .git/packed-refs.lock. A git ref rewrite
+# (fetch --prune, branch -D, pack-refs) killed after creating the lock but before
+# renaming it - e.g. bootstrap's fleet-sync timeout kill, or teardown's process
+# kills - leaves a lock that makes the next sync's fetch fail with Git's
+# "Unable to create '...packed-refs.lock': File exists". These knobs bound the
+# patience-then-provably-stale-clear recovery; see fetch_with_packed_refs_lock_guard.
+FLEET_SYNC_PACKED_REFS_LOCK_RETRIES=${FM_FLEET_SYNC_PACKED_REFS_LOCK_RETRIES:-3}
+FLEET_SYNC_PACKED_REFS_LOCK_RETRY_WAIT_SECS=${FM_FLEET_SYNC_PACKED_REFS_LOCK_RETRY_WAIT_SECS:-1}
+FLEET_SYNC_PACKED_REFS_LOCK_AGE_SECS=${FM_FLEET_SYNC_PACKED_REFS_LOCK_AGE_SECS:-30}
+case "$FLEET_SYNC_PACKED_REFS_LOCK_RETRIES" in ''|*[!0-9]*) FLEET_SYNC_PACKED_REFS_LOCK_RETRIES=3 ;; esac
+case "$FLEET_SYNC_PACKED_REFS_LOCK_AGE_SECS" in ''|*[!0-9]*) FLEET_SYNC_PACKED_REFS_LOCK_AGE_SECS=30 ;; esac
+if ! [[ "$FLEET_SYNC_PACKED_REFS_LOCK_RETRY_WAIT_SECS" =~ ^([0-9]+([.][0-9]*)?|[.][0-9]+)$ ]]; then
+  echo "fleet-sync: invalid packed-refs lock retry wait '$FLEET_SYNC_PACKED_REFS_LOCK_RETRY_WAIT_SECS'; using 1s" >&2
+  FLEET_SYNC_PACKED_REFS_LOCK_RETRY_WAIT_SECS=1
+fi
+
+usage() {
+  echo "usage: fm-fleet-sync.sh [<project-dir-or-name>]" >&2
+}
+
+if [ "${1:-}" = "--help" ] || [ "${1:-}" = "-h" ]; then
+  usage
+  exit 0
+fi
+[ $# -le 1 ] || { usage; exit 1; }
+
+project_label() {
+  case "$PROJ" in
+    "$PROJECTS"/*) basename "$PROJ" ;;
+    projects/*) basename "$PROJ" ;;
+    *) printf '%s\n' "$PROJ" ;;
+  esac
+}
+
+# resolve_project_arg <arg>: accept a path (used as-is when it already exists)
+# or a bare/"projects/<name>" project name, resolved against $PROJECTS. Falls
+# back to the original argument unresolved so a genuinely bad path still hits
+# sync_project's existing "not a directory" skip.
+resolve_project_arg() {
+  local arg=$1 candidate
+  case "$arg" in
+    projects/*)
+      candidate="$PROJECTS/${arg#projects/}"
+      if [ -d "$candidate" ]; then
+        printf '%s\n' "$candidate"
+        return 0
+      fi
+      ;;
+    */*)
+      if [ -d "$arg" ]; then
+        printf '%s\n' "$arg"
+        return 0
+      fi
+      ;;
+    *)
+      candidate="$PROJECTS/$arg"
+      if [ -d "$candidate" ]; then
+        printf '%s\n' "$candidate"
+        return 0
+      fi
+      if [ -d "$arg" ]; then
+        printf '%s\n' "$arg"
+        return 0
+      fi
+      ;;
+  esac
+  printf '%s\n' "$arg"
+}
+
+default_branch() {
+  local ref branch
+  ref=$(git -C "$PROJ" symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null || true)
+  if [ -n "$ref" ]; then
+    echo "${ref#origin/}"
+    return 0
+  fi
+  for branch in main master; do
+    if git -C "$PROJ" show-ref --verify --quiet "refs/heads/$branch"; then
+      echo "$branch"
+      return 0
+    fi
+  done
+  return 1
+}
+
+first_line() {
+  printf '%s\n' "$1" | sed -n '1s/[[:space:]]\{1,\}/ /g;1p'
+}
+
+# True when git stderr shows the packed-refs.lock "File exists" race. The lock
+# path can appear anywhere in the message (git prefixes it with the failed ref op,
+# e.g. "could not delete reference ...:"). Other "File exists" errors must not match.
+is_packed_refs_lock_error() {
+  printf '%s\n' "$1" | grep -Eq "Unable to create ['\"].*packed-refs\\.lock['\"]: File exists"
+}
+
+# Absolute path to $PROJ's packed-refs.lock, or empty when it cannot be resolved.
+packed_refs_lock_path() {
+  local lock abs
+  lock=$(git -C "$PROJ" rev-parse --git-path packed-refs.lock 2>/dev/null) || return 1
+  [ -n "$lock" ] || return 1
+  case "$lock" in
+    /*) printf '%s\n' "$lock" ;;
+    *)
+      abs=$(cd "$PROJ" && pwd -P) || return 1
+      printf '%s/%s\n' "$abs" "$lock"
+      ;;
+  esac
+}
+
+# Run `git -C "$PROJ" fetch origin --prune --quiet`, tolerating an orphaned
+# packed-refs.lock left by a killed ref rewrite. Sets FETCH_OUTPUT to the git
+# command's combined output and returns its exit status. On the packed-refs.lock
+# signature ONLY: retry up to FLEET_SYNC_PACKED_REFS_LOCK_RETRIES times (a
+# transient lock self-clears as the owning process exits), then - only if the lock
+# is provably stale per fm-lock-lib.sh (still present, mtime age past the
+# threshold, no lsof holder of the lock or the clone worktree $PROJ) - remove it
+# and retry once more. A live lock, an unprovable one, or any other failure keeps
+# today's behavior. Every wait, retry, and removal prints to stderr, and a
+# successful recovery also prints one "$label: recovered: ..." summary to stdout so
+# a session-start refresh (which discards fleet-sync stderr) still surfaces it.
+fetch_with_packed_refs_lock_guard() {
+  local rc attempt=0 lock lock_desc
+  FETCH_OUTPUT=$(git -C "$PROJ" fetch origin --prune --quiet 2>&1); rc=$?
+  [ "$rc" -eq 0 ] && return 0
+  is_packed_refs_lock_error "$FETCH_OUTPUT" || return "$rc"
+
+  lock=$(packed_refs_lock_path) || lock=""
+  lock_desc=${lock:-packed-refs.lock}
+  while [ "$attempt" -lt "$FLEET_SYNC_PACKED_REFS_LOCK_RETRIES" ]; do
+    attempt=$(( attempt + 1 ))
+    echo "$label: fetch blocked by packed-refs lock ($lock_desc); waiting ${FLEET_SYNC_PACKED_REFS_LOCK_RETRY_WAIT_SECS}s and retrying ($attempt/${FLEET_SYNC_PACKED_REFS_LOCK_RETRIES}) (owning process may be exiting)" >&2
+    sleep "$FLEET_SYNC_PACKED_REFS_LOCK_RETRY_WAIT_SECS"
+    FETCH_OUTPUT=$(git -C "$PROJ" fetch origin --prune --quiet 2>&1); rc=$?
+    if [ "$rc" -eq 0 ]; then
+      echo "$label: fetch succeeded on retry; packed-refs lock cleared on its own" >&2
+      # One stdout summary so a session-start refresh (which discards fleet-sync
+      # stderr and relays only stdout) still surfaces the recovery.
+      echo "$label: recovered: packed-refs lock cleared on its own during retry"
+      return 0
+    fi
+    is_packed_refs_lock_error "$FETCH_OUTPUT" || return "$rc"
+  done
+
+  # Retries exhausted and still the lock signature. Clear ONLY if provably stale.
+  # The companion liveness dir is $PROJ (the clone worktree): a live `git -C "$PROJ"`
+  # keeps its cwd there even in the narrow window after it closes packed-refs.lock
+  # and before it exits, so lsof on $PROJ still catches a holder the lock-file check
+  # alone would miss.
+  lock=$(packed_refs_lock_path) || lock=""
+  if [ -n "$lock" ] && [ -e "$lock" ]; then
+    if fm_lock_is_provably_stale "$lock" "$PROJ" "$FLEET_SYNC_PACKED_REFS_LOCK_AGE_SECS"; then
+      if ! rm -f "$lock"; then
+        echo "$label: failed to remove provably-stale packed-refs lock $lock; leaving it in place" >&2
+        return "$rc"
+      fi
+      echo "$label: removed provably-stale packed-refs lock $lock (age >= ${FLEET_SYNC_PACKED_REFS_LOCK_AGE_SECS}s, no live holder) and retrying fetch" >&2
+      FETCH_OUTPUT=$(git -C "$PROJ" fetch origin --prune --quiet 2>&1); rc=$?
+      if [ "$rc" -eq 0 ]; then
+        echo "$label: fetch succeeded after stale packed-refs lock cleanup" >&2
+        echo "$label: recovered: removed a stale packed-refs lock (no live holder)"
+        return 0
+      fi
+      return "$rc"
+    fi
+    echo "$label: fetch blocked by packed-refs lock $lock that persisted across ${FLEET_SYNC_PACKED_REFS_LOCK_RETRIES} retries and is not provably stale (may belong to a live process); leaving it in place" >&2
+    return "$rc"
+  fi
+  echo "$label: fetch packed-refs lock signature persisted across ${FLEET_SYNC_PACKED_REFS_LOCK_RETRIES} retries even after the lock file disappeared" >&2
+  return "$rc"
+}
+
+prune_gone_branches() {
+  # Delete local branches whose upstream tracking branch is gone - the remote
+  # branch was deleted, which in this fleet means its PR merged - as long as
+  # nothing still needs them. Never the checked-out branch, and never a branch
+  # that still has a worktree (a live or not-yet-torn-down task). "Gone" plus
+  # "no worktree" already proves the work landed: teardown removes a branch's
+  # worktree only after confirming the work reached the remote. We deliberately
+  # do NOT also require the branch to be an ancestor of origin/<default> - PRs in
+  # this fleet are squash-merged, so a merged branch is never an ancestor and
+  # such a check would prune nothing. The no-worktree guard is the real safety
+  # net. Set FM_FLEET_PRUNE=0 to skip pruning entirely.
+  [ "${FM_FLEET_PRUNE:-1}" != "0" ] || return 0
+
+  local worktree_branches current refline branch track
+  worktree_branches=$(git -C "$PROJ" worktree list --porcelain 2>/dev/null \
+    | sed -n 's#^branch refs/heads/##p')
+  current=$(git -C "$PROJ" symbolic-ref --quiet --short HEAD 2>/dev/null || true)
+
+  while IFS= read -r refline; do
+    branch=${refline%% *}
+    track=${refline#* }
+    [ "$track" = "[gone]" ] || continue
+    [ -n "$branch" ] || continue
+    [ "$branch" != "$current" ] || continue
+    if printf '%s\n' "$worktree_branches" | grep -Fxq -- "$branch"; then
+      continue
+    fi
+    if git -C "$PROJ" branch -D -- "$branch" >/dev/null 2>&1; then
+      echo "$label: pruned $branch"
+    fi
+  done < <(git -C "$PROJ" for-each-ref \
+    --format='%(refname:short) %(upstream:track)' refs/heads 2>/dev/null)
+}
+
+# True when some worktree of $PROJ has $DEFAULT checked out (so we cannot attach
+# to it here). The current worktree is detached when this is consulted, so any
+# match is necessarily another worktree.
+default_checked_out_elsewhere() {
+  git -C "$PROJ" worktree list --porcelain 2>/dev/null \
+    | sed -n 's#^branch refs/heads/##p' \
+    | grep -Fxq -- "$DEFAULT"
+}
+
+local_default_safe_for_recovery() {
+  ! git -C "$PROJ" rev-parse --verify --quiet "$DEFAULT^{commit}" >/dev/null \
+    || git -C "$PROJ" merge-base --is-ancestor "$DEFAULT" "$BASE" 2>/dev/null
+}
+
+# Human-readable name for the unsafe state the clone is in, used in the STUCK
+# warning. Reads $cur (current branch, empty when detached), $dirty, and the
+# HEAD-vs-$BASE ancestry to pick the most informative description.
+stuck_state() {
+  local s
+  if [ -n "$cur" ]; then
+    s="branch $cur"
+  elif [ "$dirty" = yes ]; then
+    s="detached HEAD"
+  elif ! git -C "$PROJ" merge-base --is-ancestor HEAD "$BASE" 2>/dev/null; then
+    s="detached HEAD with unique commits"
+  elif default_checked_out_elsewhere; then
+    s="detached HEAD ($DEFAULT checked out in another worktree)"
+  elif ! local_default_safe_for_recovery; then
+    s="detached HEAD (local $DEFAULT diverged from $BASE)"
+  else
+    s="detached HEAD"
+  fi
+  [ "$dirty" = no ] || s="$s with uncommitted changes"
+  printf '%s\n' "$s"
+}
+
+# Loud, quantified report for a clone we deliberately leave untouched. Includes
+# how far behind origin/<default> it is, so a chronically-stuck clone is visibly
+# distinct from a benign one-off skip.
+report_stuck() {
+  local state=$1 behind
+  behind=$(git -C "$PROJ" rev-list --count "HEAD..$BASE" 2>/dev/null) || behind="?"
+  echo "$label: STUCK: on $state, $behind commits behind $BASE - needs attention"
+}
+
+sync_project() {
+  PROJ=$1
+  label=$(project_label)
+
+  if [ ! -d "$PROJ" ]; then
+    echo "$label: skipped: not a directory"
+    return 0
+  fi
+  # Git repository discovery walks UP from $PROJ, so a plain directory merely
+  # nested inside a repository - a worktree container left under projects/, say -
+  # resolves to the ENCLOSING repository, which in a firstmate home is the
+  # firstmate checkout itself. Every later `git -C "$PROJ"` would then read, prune
+  # and fast-forward that repository under this project's label, turning a routine
+  # refresh into an unrequested self-update reported as a project sync. Require
+  # $PROJ to be the root of its own work tree before any other git command runs.
+  proj_top=$(git -C "$PROJ" rev-parse --show-toplevel 2>/dev/null) || proj_top=""
+  if [ -z "$proj_top" ]; then
+    echo "$label: skipped: not a git repo"
+    return 0
+  fi
+  # Both sides are physical paths (git resolves --show-toplevel through symlinks),
+  # so a symlinked clone dir still compares equal to its own root.
+  proj_abs=$(cd "$PROJ" && pwd -P) || proj_abs=""
+  if [ "$proj_top" != "$proj_abs" ]; then
+    echo "$label: skipped: not a clone root (git would act on $proj_top)"
+    return 0
+  fi
+  mode_line=$("$FM_ROOT/bin/fm-project-mode.sh" "$label" 2>/dev/null || echo "no-mistakes off")
+  mode=${mode_line%% *}
+  if [ "$mode" = "local-only" ]; then
+    echo "$label: skipped: local-only project"
+    return 0
+  fi
+  if ! git -C "$PROJ" remote get-url origin >/dev/null 2>&1; then
+    echo "$label: skipped: no origin remote"
+    return 0
+  fi
+
+  if ! fetch_with_packed_refs_lock_guard; then
+    reason="fetch failed"
+    if [ -n "$FETCH_OUTPUT" ]; then
+      reason="$reason: $(first_line "$FETCH_OUTPUT")"
+    fi
+    echo "$label: skipped: $reason"
+    return 0
+  fi
+
+  prune_gone_branches || true
+
+  DEFAULT=$(default_branch) || {
+    echo "$label: skipped: cannot determine default branch"
+    return 0
+  }
+  BASE="origin/$DEFAULT"
+  if ! git -C "$PROJ" rev-parse --verify --quiet "$BASE^{commit}" >/dev/null; then
+    echo "$label: skipped: $BASE does not exist"
+    return 0
+  fi
+
+  cur=$(git -C "$PROJ" symbolic-ref --short HEAD 2>/dev/null || echo "")
+  dirty=no
+  [ -z "$(git -C "$PROJ" status --porcelain 2>/dev/null | head -1)" ] || dirty=yes
+  recovered=no
+
+  if [ "$cur" != "$DEFAULT" ]; then
+    # Off the default branch. Auto-recover only the one unambiguously safe drift:
+    # a clean, detached HEAD that holds no unique commits (it is an ancestor of
+    # origin/<default>) and whose <default> branch is free to check out here.
+    # Re-attaching to an already-published commit strands nothing, and the
+    # fast-forward path below then catches the clone up. Anything else - a
+    # non-default named branch, a detached HEAD with unique commits, a dirty tree,
+    # or <default> already checked out elsewhere - may hold real work, so it is
+    # reported loudly and left untouched.
+    if [ -z "$cur" ] && [ "$dirty" = no ] \
+        && git -C "$PROJ" merge-base --is-ancestor HEAD "$BASE" 2>/dev/null \
+        && ! default_checked_out_elsewhere \
+        && local_default_safe_for_recovery; then
+      if ! git -C "$PROJ" checkout --quiet "$DEFAULT" 2>/dev/null; then
+        report_stuck "$(stuck_state)"
+        return 0
+      fi
+      recovered=yes
+      cur=$DEFAULT
+    else
+      report_stuck "$(stuck_state)"
+      return 0
+    fi
+  elif [ "$dirty" = yes ]; then
+    # On the default branch but with uncommitted changes we must not disturb.
+    report_stuck "$(stuck_state)"
+    return 0
+  fi
+
+  if ! git -C "$PROJ" rev-parse --verify --quiet "$DEFAULT^{commit}" >/dev/null; then
+    echo "$label: skipped: local $DEFAULT does not exist"
+    return 0
+  fi
+
+  local_rev=$(git -C "$PROJ" rev-parse "$DEFAULT") || {
+    echo "$label: skipped: cannot read local $DEFAULT"
+    return 0
+  }
+  remote_rev=$(git -C "$PROJ" rev-parse "$BASE") || {
+    echo "$label: skipped: cannot read $BASE"
+    return 0
+  }
+  if [ "$local_rev" = "$remote_rev" ]; then
+    if [ "$recovered" = yes ]; then
+      echo "$label: recovered: re-attached $DEFAULT (already current)"
+    else
+      echo "$label: already current"
+    fi
+    return 0
+  fi
+  if ! git -C "$PROJ" merge-base --is-ancestor "$DEFAULT" "$BASE"; then
+    report_stuck "diverged $DEFAULT"
+    return 0
+  fi
+
+  before=$(git -C "$PROJ" rev-parse --short "$DEFAULT") || {
+    echo "$label: skipped: cannot read local $DEFAULT"
+    return 0
+  }
+  if ! merge_output=$(git -C "$PROJ" merge --ff-only "$BASE" 2>&1); then
+    reason="fast-forward failed"
+    if [ -n "$merge_output" ]; then
+      reason="$reason: $(first_line "$merge_output")"
+    fi
+    echo "$label: skipped: $reason"
+    return 0
+  fi
+  after=$(git -C "$PROJ" rev-parse --short "$DEFAULT") || {
+    echo "$label: skipped: fast-forward completed but cannot read local $DEFAULT"
+    return 0
+  }
+  if [ "$recovered" = yes ]; then
+    echo "$label: recovered: re-attached $DEFAULT, synced $before..$after"
+  else
+    echo "$label: synced $before..$after"
+  fi
+  return 0
+}
+
+if [ $# -eq 1 ]; then
+  sync_project "$(resolve_project_arg "$1")"
+  exit 0
+fi
+
+[ -d "$PROJECTS" ] || exit 0
+for proj in "$PROJECTS"/*; do
+  [ -e "$proj" ] || continue
+  [ -d "$proj" ] || continue
+  # Per-clone elapsed, so a fleet refresh that runs long names WHICH clone cost
+  # the time instead of only its total. Recording is a no-op unless the deferred
+  # network stage asked for it.
+  __fm_timing_stamp=$(fm_timing_now_ms)
+  sync_project "$proj"
+  fm_timing_record clone sync "$__fm_timing_stamp" "$(basename "$proj")"
+done

package/.agents/backend/fm-fleet-view.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# fm-fleet-view.sh - human renderer over fm-fleet-snapshot.sh.
+#
+# This command intentionally does not parse fleet state itself.
+# It shells out to fm-fleet-snapshot.sh --json and renders that stable
+# structured contract for humans.
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+usage() {
+  cat <<'EOF'
+usage: fm-fleet-view.sh [--json]
+
+Render a human fleet view from fm-fleet-snapshot.sh.
+Use --json to print the underlying snapshot.
+EOF
+}
+
+case "${1:-}" in
+  -h|--help) usage; exit 0 ;;
+  --json) "$SCRIPT_DIR/fm-fleet-snapshot.sh" --json; exit $? ;;
+  "") ;;
+  *) usage >&2; exit 2 ;;
+esac
+
+command -v jq >/dev/null 2>&1 || { echo "fm-fleet-view: jq not found" >&2; exit 1; }
+
+SNAPSHOT=$("$SCRIPT_DIR/fm-fleet-snapshot.sh" --json) || exit $?
+
+printf '%s\n' "$SNAPSHOT" | jq -r '
+  def dash($v): if $v == null or $v == "" then "-" else $v end;
+  def endpoint_exists($t):
+    if $t.endpoint.exists == null then "unknown"
+    elif $t.endpoint.exists then "present"
+    else "absent" end;
+  def endpoint_of($t):
+    if $t.kind == "secondmate" then "\(endpoint_exists($t)) / \($t.endpoint.agent_alive)"
+    else endpoint_exists($t) end;
+  def artifact($t):
+    if $t.pr.url != null then $t.pr.url
+    elif $t.paths.report.present then $t.paths.report.path
+    else "-" end;
+  def path_of($t):
+    if $t.paths.home.present then $t.paths.home.path
+    elif $t.paths.home.path != null then $t.paths.home.path + " (absent)"
+    elif $t.paths.worktree.present then $t.paths.worktree.path
+    elif $t.paths.worktree.path != null then $t.paths.worktree.path + " (absent)"
+    else "-" end;
+  def action_of($t):
+    if $t.kind == "secondmate" then "\($t.actions.send) - \($t.actions.watch)"
+    else $t.actions.watch end;
+  def task_row($t):
+    "| \($t.id) | \($t.current_state.state) / \($t.current_state.source) | \($t.kind) | \(dash($t.backlog.repo // $t.project)) | \($t.backend) | \(endpoint_of($t)) | \(artifact($t)) | \(path_of($t)) | \(action_of($t)) |";
+  def blocker($r):
+    if ($r.blocked_by // "") == "" then "-"
+    elif ($r.blocked_reason // "") == "" then $r.blocked_by
+    else "\($r.blocked_by) - \($r.blocked_reason)" end;
+  def backlog_row($r):
+    "| \($r.id // "-") | \(dash($r.title // $r.raw)) | \(dash($r.repo)) | \(dash($r.kind)) | \(blocker($r)) | \(dash($r.pr_url // $r.report_path // $r.local_note)) |";
+
+  "# Fleet View",
+  "",
+  "Schema: \(.schema)",
+  "Home: \(.fm_home)",
+  "",
+  "## Under Way",
+  (if (.tasks | length) == 0 then
+    "No live task metadata found."
+   else
+    "| ID | Current | Kind | Repo/Project | Backend | Endpoint | Artifact | Path | Watch / return channel |",
+    "| --- | --- | --- | --- | --- | --- | --- | --- | --- |",
+    (.tasks[] | task_row(.))
+   end),
+  "",
+  "## Queued",
+  (if ([.backlog.records[]? | select(.state == "queued")] | length) == 0 then
+    "No queued backlog records found."
+   else
+    "| ID | Title | Repo | Kind | Blocked By | Artifact |",
+    "| --- | --- | --- | --- | --- | --- |",
+    (.backlog.records[] | select(.state == "queued") | backlog_row(.))
+   end),
+  "",
+  "## Done",
+  (if ([.backlog.records[]? | select(.state == "done")] | length) == 0 then
+    "No done backlog records found."
+   else
+    "| ID | Title | Repo | Kind | Blocked By | Artifact |",
+    "| --- | --- | --- | --- | --- | --- |",
+    (.backlog.records[] | select(.state == "done") | backlog_row(.))
+   end),
+  "",
+  "## Secondmates",
+  .secondmate_guidance.note
+'

package/.agents/backend/fm-gate-refuse-lib.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+# fm-gate-refuse-lib.sh - fail-closed refusal that keeps a no-mistakes GATE agent
+# out of firstmate's fleet lifecycle.
+#
+# The hazard (data/nm-gate-ambient-authority-containment-c3/report.md): a
+# no-mistakes gate agent runs inside a firstmate checkout with a free shell, so
+# it auto-loads firstmate's AGENTS.md, adopts the captain identity, and - seeing
+# crew "in flight" - reaches for fm-spawn.sh/fm-send.sh/fm-teardown.sh to
+# "delegate" and "reconcile" the shared worktree. It has real capability because
+# those entrypoints self-locate their home and never knew a gate context existed.
+#
+# no-mistakes owns the authority-removal half (it neutralizes the project
+# instructions and stamps NO_MISTAKES_GATE into the gate agent's environment).
+# THIS is the firstmate capability-removal half: an enforceable script refusal,
+# not a prose rule the neutralized agent would never read. It is sourced at the
+# top of the three fleet-lifecycle entrypoints and called before any fleet
+# mutation, so a gate agent that still reaches for the fleet is stopped cold.
+#
+# Two independent signals, either of which refuses (fail closed):
+#
+#   1. NO_MISTAKES_GATE set - the durable env marker no-mistakes stamps into every
+#      gate agent. This is the primary signal and covers a relocated NM_HOME.
+#   2. The current worktree's git-common-dir resolves under a no-mistakes gate
+#      repo (.../.no-mistakes/repos/*.git) - the UNSPOOFABLE backstop. It derives
+#      from the checkout's real filesystem location, which the agent cannot
+#      relocate without breaking the gate's own git operations, so it still
+#      refuses even if the agent tampered NO_MISTAKES_GATE away. Its limit: the
+#      literal-path match only fires for the default NM_HOME (~/.no-mistakes); a
+#      relocated NM_HOME is covered by signal 1.
+#
+# A NORMAL firstmate session - a real primary checkout, a real treehouse/Orca
+# crew worktree - has NEITHER signal and is COMPLETELY unaffected: the function
+# returns 0 and the lifecycle proceeds exactly as before.
+#
+# This mirrors the unspoofable-marker precedent in bin/fm-marker-lib.sh: a signal
+# the agent cannot forge, keyed on at a chokepoint, keeping the pattern familiar
+# to firstmate maintainers. It layers ABOVE no-mistakes' separately-shipping
+# HEAD-continuity guard, which remains the adversarial/residual backstop.
+#
+# TEST-HARNESS ESCAPE HATCH (FM_GATE_REFUSE_BYPASS=1): firstmate's own test suite
+# must exercise the REAL fm-spawn/fm-send/fm-teardown, but the no-mistakes gate
+# runs that suite FROM a gate worktree (cwd git-common-dir under
+# .no-mistakes/repos/*.git, and possibly NO_MISTAKES_GATE set) - the exact
+# environment this guard refuses. So both signals would fire during firstmate's
+# own validation and break unrelated tests. FM_GATE_REFUSE_BYPASS=1 makes the
+# guard a no-op; firstmate's shared test helpers (tests/lib.sh and the backend
+# safety helpers) export it, so every test that drives these scripts against its
+# temp-sandbox fleet is exempt. This does NOT weaken the boundary against the
+# real hazard: the threat is a CONFUSED-not-adversarial gate agent that runs
+# bin/fm-spawn.sh directly after adopting firstmate's identity - it never sources
+# firstmate's test helpers, so it never carries the bypass; and the adversarial
+# case (an agent that would deliberately set it) is covered by no-mistakes'
+# neutral-execution-context and the HEAD-continuity guard. The dedicated
+# tests/fm-gate-refuse.test.sh strips the bypass so it still verifies real refusal.
+#
+# Sourced by bin/fm-spawn.sh, bin/fm-send.sh, bin/fm-teardown.sh,
+# bin/fm-sessionstart-nudge.sh, and the tests.
+# No side effects on source. set -u / set -e safe. The refusal is a hard exit,
+# not a return, because there is no safe way to continue a fleet mutation from a
+# gate context.
+
+# The exit code every refusal uses, distinct enough to recognize in a caller or
+# test as "the gate refusal fired" rather than an ordinary usage error.
+FM_GATE_REFUSE_EXIT=3
+
+# fm_is_gate_agent: return 0 without output when this process looks like a
+# no-mistakes gate agent. An optional root anchors the git-common-dir check;
+# callers that omit it retain the historical current-worktree behavior.
+fm_is_gate_agent() {
+  local anchor=${1:-.} common
+  if [ "${FM_GATE_REFUSE_BYPASS:-}" = 1 ]; then
+    return 1
+  fi
+  if [ "${NO_MISTAKES_GATE+x}" = x ]; then
+    FM_GATE_REFUSE_REASON='env'
+    return 0
+  fi
+  common=$(cd "$anchor" 2>/dev/null \
+    && cd "$(git rev-parse --git-common-dir 2>/dev/null || echo /nonexistent)" 2>/dev/null \
+    && pwd -P || true)
+  case "$common" in
+    */.no-mistakes/repos/*.git)
+      FM_GATE_REFUSE_REASON='path'
+      FM_GATE_REFUSE_COMMON=$common
+      return 0 ;;
+  esac
+  return 1
+}
+
+# fm_refuse_if_gate_agent: exit FM_GATE_REFUSE_EXIT with a clear stderr message if
+# this process looks like a no-mistakes gate agent. Call before any fleet
+# mutation. No-ops (returns 0) for a normal firstmate session, or when firstmate's
+# own test harness sets FM_GATE_REFUSE_BYPASS=1 (see the header).
+fm_refuse_if_gate_agent() {
+  fm_is_gate_agent "${1:-.}" || return 0
+  if [ "$FM_GATE_REFUSE_REASON" = env ]; then
+    echo "error: no-mistakes gate agent must not drive the fleet (NO_MISTAKES_GATE set)" >&2
+  else
+    echo "error: refusing fleet lifecycle from inside a no-mistakes gate worktree ($FM_GATE_REFUSE_COMMON)" >&2
+  fi
+  exit "$FM_GATE_REFUSE_EXIT"
+}