@zerwiz/ymir 0.1.4 → 0.1.7

package/.agents/backend/fm-lease.sh

@@ -0,0 +1,189 @@
+#!/usr/bin/env bash
+# fm-lease.sh - claim, release, inspect, and sweep per-task supervision leases.
+#
+# The lease contract itself (file format, actors, staleness, guard semantics)
+# is owned by bin/fm-lease-lib.sh; this is the command surface the two
+# supervision actors use around the overlap set (steering, stopping, cleanup,
+# backlog status, stuck-worker recovery). "backlog" is the reserved resource
+# the branch prompt claims around its own backlog writes; main's tasks-axi path
+# is deliberately unguarded in this scope.
+#
+# Usage:
+#   fm-lease.sh claim <task> [--actor main|branch]
+#       Take the lease for the calling actor. Idempotent for the holder (the
+#       claim refreshes its own lease). Refuses with exit 6 while the other
+#       actor holds a live lease. A stale lease (dead pid, or a torn record)
+#       is cleared and re-claimed.
+#   fm-lease.sh release <task> [--actor main|branch]
+#       Drop the calling actor's lease. Releasing a lease the actor does not
+#       hold is a silent no-op, so a retry after a partial failure is safe.
+#       Naming the other actor is refused loudly.
+#   fm-lease.sh check <task>
+#       Print "<actor> <pid> <epoch> <live|stale>" for a held lease, or
+#       nothing (exit 1) when the task is unleased.
+#   fm-lease.sh release-actor --actor main|branch
+#       Drop every lease the named actor holds; the Pi branch extension runs
+#       this at generation activation so a replaced branch conversation's
+#       leases never outlive it.
+#   fm-lease.sh sweep
+#       Remove every provably stale lease in this home. Run at session start
+#       (a lease held by a dead actor is cleared at session start); safe to
+#       run any time - a live lease is never touched.
+#
+# The default actor is $FM_SUPERVISION_ACTOR (else main); when --actor is
+# supplied for a mutation, it must name that calling actor. Exit codes: 0 ok,
+# 1 check-miss, 2 usage, 6 refused (other actor holds or actor mismatch).
+set -eu
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+FM_ROOT="${FM_ROOT_OVERRIDE:-${FM_ROOT:-$(cd "$SCRIPT_DIR/.." && pwd)}}"
+FM_HOME="${FM_HOME:-${FM_ROOT_OVERRIDE:-$FM_ROOT}}"
+STATE="${FM_STATE_OVERRIDE:-$FM_HOME/state}"
+# shellcheck source=bin/fm-lease-lib.sh
+. "$SCRIPT_DIR/fm-lease-lib.sh"
+# shellcheck source=bin/fm-wake-lib.sh
+. "$SCRIPT_DIR/fm-wake-lib.sh"
+
+mkdir -p "$STATE"
+LEASE_COMMAND_LOCK="$STATE/.fm-lease-command.lock"
+fm_lock_acquire_wait "$LEASE_COMMAND_LOCK"
+trap 'fm_lock_release "$LEASE_COMMAND_LOCK"' EXIT
+
+usage() {
+  echo "usage: fm-lease.sh claim|release <task> [--actor main|branch] | release-actor --actor main|branch | check <task> | sweep" >&2
+  exit 2
+}
+
+CMD=${1:-}
+shift 2>/dev/null || true
+
+case "$CMD" in
+  claim|release)
+    TASK=${1:-}
+    shift 2>/dev/null || true
+    fm_lease_valid_id "$TASK" || usage
+    ACTOR=
+    while [ "$#" -gt 0 ]; do
+      case "$1" in
+        --actor)
+          ACTOR=${2:-}
+          shift 2 || usage
+          ;;
+        *) usage ;;
+      esac
+    done
+    if [ -z "$ACTOR" ]; then
+      ACTOR=$(fm_lease_actor) || exit 2
+    fi
+    case "$ACTOR" in main|branch) ;; *) usage ;; esac
+    ;;
+  check)
+    TASK=${1:-}
+    [ "$#" -le 1 ] || usage
+    fm_lease_valid_id "$TASK" || usage
+    ;;
+  release-actor)
+    ACTOR=
+    while [ "$#" -gt 0 ]; do
+      case "$1" in
+        --actor)
+          ACTOR=${2:-}
+          shift 2 || usage
+          ;;
+        *) usage ;;
+      esac
+    done
+    case "$ACTOR" in main|branch) ;; *) usage ;; esac
+    ;;
+  sweep)
+    [ "$#" -eq 0 ] || usage
+    ;;
+  *) usage ;;
+esac
+
+case "$CMD" in
+  claim)
+    # Loud accidental-override guard: a claim naming the OTHER actor than the
+    # caller's own injected identity is a wiring mistake, never a role change.
+    # Release and bulk release enforce the same caller authorization below.
+    CALLER=$(fm_lease_actor) || exit "$FM_LEASE_REFUSE_EXIT"
+    if [ "$ACTOR" != "$CALLER" ]; then
+      echo "error: claim refused - the $CALLER supervision actor cannot claim a lease as $ACTOR on '$TASK'" >&2
+      exit "$FM_LEASE_REFUSE_EXIT"
+    fi
+    LEASE=$(fm_lease_path "$TASK")
+    if fm_lease_live "$TASK" && [ "$FM_LEASE_ACTOR" != "$ACTOR" ]; then
+      echo "error: claim refused - task '$TASK' is leased to the $FM_LEASE_ACTOR supervision actor (state/.lease-$TASK)" >&2
+      exit "$FM_LEASE_REFUSE_EXIT"
+    fi
+    # The lease outlives this CLI call, so its liveness pid must be the
+    # long-lived supervising process: FM_LEASE_HOLDER_PID when the caller
+    # provides one (the Pi branch extension passes the session-lock holder),
+    # else the session-lock holder (state/.lock is the harness pid), else this
+    # shell; without a matching session lock the resulting lease is stale.
+    HOLDER_PID=${FM_LEASE_HOLDER_PID:-}
+    case "$HOLDER_PID" in *[!0-9]*) HOLDER_PID= ;; esac
+    if [ -z "$HOLDER_PID" ]; then
+      HOLDER_PID=$(head -n 1 "$STATE/.lock" 2>/dev/null | tr -cd '0-9' || true)
+    fi
+    [ -n "$HOLDER_PID" ] || HOLDER_PID=$$
+    TMP=$(mktemp "$STATE/.fm-lease-tmp.XXXXXX")
+    printf '%s\t%s\t%s\n' "$ACTOR" "$HOLDER_PID" "$(date +%s)" > "$TMP"
+    if [ -e "$LEASE" ]; then
+      # Same-actor refresh, or a stale/torn record: replace atomically.
+      mv -f -- "$TMP" "$LEASE"
+    elif ! ln -- "$TMP" "$LEASE" 2>/dev/null; then
+      # Lost the create race to the sibling actor; re-check who won.
+      rm -f -- "$TMP"
+      if fm_lease_live "$TASK" && [ "$FM_LEASE_ACTOR" != "$ACTOR" ]; then
+        echo "error: claim refused - task '$TASK' was just leased to the $FM_LEASE_ACTOR supervision actor" >&2
+        exit "$FM_LEASE_REFUSE_EXIT"
+      fi
+      TMP=$(mktemp "$STATE/.fm-lease-tmp.XXXXXX")
+      printf '%s\t%s\t%s\n' "$ACTOR" "$HOLDER_PID" "$(date +%s)" > "$TMP"
+      mv -f -- "$TMP" "$LEASE"
+    else
+      rm -f -- "$TMP"
+    fi
+    ;;
+  release)
+    CALLER=$(fm_lease_actor) || exit "$FM_LEASE_REFUSE_EXIT"
+    if [ "$ACTOR" != "$CALLER" ]; then
+      echo "error: release refused - the $CALLER supervision actor cannot release a lease as $ACTOR on '$TASK'" >&2
+      exit "$FM_LEASE_REFUSE_EXIT"
+    fi
+    if fm_lease_read "$TASK" && { [ "$FM_LEASE_ACTOR" = "$ACTOR" ] || [ -z "$FM_LEASE_ACTOR" ]; }; then
+      rm -f -- "$(fm_lease_path "$TASK")"
+    fi
+    ;;
+  check)
+    fm_lease_read "$TASK" || exit 1
+    if fm_lease_live "$TASK"; then LIVENESS=live; else LIVENESS=stale; fi
+    printf '%s %s %s %s\n' "${FM_LEASE_ACTOR:-unreadable}" "${FM_LEASE_PID:-0}" "${FM_LEASE_EPOCH:-0}" "$LIVENESS"
+    ;;
+  release-actor)
+    CALLER=$(fm_lease_actor) || exit "$FM_LEASE_REFUSE_EXIT"
+    if [ "$ACTOR" != "$CALLER" ]; then
+      echo "error: release-actor refused - the $CALLER supervision actor cannot release leases as $ACTOR" >&2
+      exit "$FM_LEASE_REFUSE_EXIT"
+    fi
+    for LEASE in "$STATE"/.lease-*; do
+      [ -e "$LEASE" ] || continue
+      case "$LEASE" in *.lock) continue ;; esac
+      TASK=${LEASE##*/.lease-}
+      fm_lease_valid_id "$TASK" || continue
+      if fm_lease_read "$TASK" && [ "$FM_LEASE_ACTOR" = "$ACTOR" ]; then
+        rm -f -- "$LEASE"
+      fi
+    done
+    ;;
+  sweep)
+    for LEASE in "$STATE"/.lease-*; do
+      [ -e "$LEASE" ] || continue
+      case "$LEASE" in *.lock) continue ;; esac
+      TASK=${LEASE##*/.lease-}
+      fm_lease_valid_id "$TASK" || continue
+      fm_lease_clear_stale "$TASK"
+    done
+    ;;
+esac

package/.agents/backend/fm-line-cap-lib.sh

@@ -0,0 +1,51 @@
+# shellcheck shell=bash
+# Shared per-line cap for agent-facing digest lines.
+# Usage: . bin/fm-line-cap-lib.sh; fm_cap_line "<line>" [<max>]
+#
+# ONE OWNER for the bounded-line shape both digests use. The wake digest's
+# OPEN DECISIONS section (bin/fm-wake-drain.sh) and the session-start digest's
+# per-task status tails (bin/fm-session-start.sh) render the same kind of
+# content - an agent-written status line, which AGENTS.md section 8 treats as a
+# wake EVENT rather than current state - into a size-bounded view. An agent
+# reading both must recognize one truncation marker, and the two caps must not
+# drift apart, so the cut and its marker live here.
+#
+# Callers keep their own composite policy: fm-wake-drain.sh still owns the
+# OPEN DECISIONS global byte cap and its "N more omitted" disclosure, and
+# fm-session-start.sh still owns how many tail lines it prints per task. This
+# file owns only the per-line cut.
+#
+# The cap counts characters, so a plain-ASCII line - what status lines are in
+# practice - is bounded to the same number of bytes, and a multibyte character
+# is never cut in half into an invalid sequence.
+# Truncation stays recoverable because the session-start digest prints each
+# task's full status log path, while every OPEN DECISIONS entry begins with the
+# task id that identifies its durable state/<id>.status source.
+
+FM_LINE_CAP_DEFAULT=220
+FM_LINE_CAP_SUFFIX=' [truncated]'
+
+# fm_cap_line_var <line> [<max>]: put <line> in FM_LINE_CAP_LINE, cut to <max>
+# characters with FM_LINE_CAP_SUFFIX in place of the tail when it is longer. A
+# line at or under the cap is kept unchanged, marker and all bytes intact.
+# This is the rule itself. It assigns rather than prints so a caller that needs
+# the value - the wake digest builds its section in a variable to weigh each
+# item against a global budget - never pays a command substitution per item on
+# a path that runs at the top of every wake-handling turn.
+fm_cap_line_var() {
+  local line=$1 max=${2:-$FM_LINE_CAP_DEFAULT} keep
+  if [ "${#line}" -le "$max" ]; then
+    FM_LINE_CAP_LINE=$line
+    return 0
+  fi
+  keep=$((max - ${#FM_LINE_CAP_SUFFIX}))
+  [ "$keep" -ge 0 ] || keep=0
+  FM_LINE_CAP_LINE="${line:0:$keep}$FM_LINE_CAP_SUFFIX"
+}
+
+# fm_cap_line <line> [<max>]: the same cut, printed on stdout, for a caller that
+# is streaming lines rather than accumulating them.
+fm_cap_line() {
+  fm_cap_line_var "$@"
+  printf '%s\n' "$FM_LINE_CAP_LINE"
+}

package/.agents/backend/fm-lint-workflows.sh

@@ -0,0 +1,137 @@
+#!/usr/bin/env bash
+# fm-lint-workflows.sh - owner of firstmate's GitHub workflow lint.
+#
+# Runs pinned actionlint on every .github/workflows/*.{yml,yaml} so a malformed
+# workflow, including a self-broken ci.yml, fails in the local and no-mistakes
+# lint lane before merge. A broken ci.yml cannot report its own breakage, so
+# this check must not live only as a step inside that workflow. bin/fm-lint.sh
+# invokes this owner on its default (no explicit-path) path, which CI and
+# commands.lint both use.
+#
+# Usage:
+#   fm-lint-workflows.sh                 lint workflows under this repo
+#   fm-lint-workflows.sh --root <dir>    lint workflows under <dir>
+#   fm-lint-workflows.sh <path>...       lint explicit workflow files
+#   fm-lint-workflows.sh --required-version
+#   fm-lint-workflows.sh --help
+set -eu
+
+REQUIRED_ACTIONLINT=1.7.12
+SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SELF="$SELF_DIR/fm-lint-workflows.sh"
+ROOT="$(cd "$SELF_DIR/.." && pwd)"
+
+if [ "${1:-}" = "--required-version" ]; then
+  printf '%s\n' "$REQUIRED_ACTIONLINT"
+  exit 0
+fi
+
+fm_lint_workflows_usage() {
+  sed -n '2,16{s/^# \{0,1\}//;p;}' "$SELF"
+}
+
+EXPLICIT_ROOT=
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --root)
+      [ "$#" -ge 2 ] || {
+        printf 'fm-lint-workflows.sh: --root requires a directory.\n' >&2
+        exit 2
+      }
+      EXPLICIT_ROOT=$2
+      shift 2
+      ;;
+    --root=*)
+      EXPLICIT_ROOT=${1#*=}
+      shift
+      ;;
+    --help|-h)
+      fm_lint_workflows_usage
+      exit 0
+      ;;
+    --)
+      shift
+      break
+      ;;
+    -*)
+      printf 'fm-lint-workflows.sh: unknown option: %s\n' "$1" >&2
+      exit 2
+      ;;
+    *)
+      break
+      ;;
+  esac
+done
+
+if [ -n "$EXPLICIT_ROOT" ]; then
+  [ -d "$EXPLICIT_ROOT" ] || {
+    printf 'fm-lint-workflows.sh: --root is not a directory: %s\n' "$EXPLICIT_ROOT" >&2
+    exit 2
+  }
+  ROOT="$(cd "$EXPLICIT_ROOT" && pwd)"
+fi
+
+collect_workflow_files() {
+  local dir=$1
+  [ -d "$dir" ] || return 0
+  find "$dir" -maxdepth 1 \( -name '*.yml' -o -name '*.yaml' \) -type f \
+    | LC_ALL=C sort
+}
+
+FILES=()
+if [ "$#" -gt 0 ]; then
+  for path in "$@"; do
+    case "$path" in
+      *.yml|*.yaml) ;;
+      *)
+        printf 'fm-lint-workflows.sh: not a workflow YAML file: %s\n' "$path" >&2
+        exit 2
+        ;;
+    esac
+    [ -f "$path" ] || {
+      printf 'fm-lint-workflows.sh: workflow file not found: %s\n' "$path" >&2
+      exit 2
+    }
+    FILES+=("$path")
+  done
+else
+  workflow_dir="$ROOT/.github/workflows"
+  while IFS= read -r path; do
+    [ -n "$path" ] || continue
+    FILES+=("$path")
+  done < <(collect_workflow_files "$workflow_dir")
+  if [ "${#FILES[@]}" -eq 0 ]; then
+    printf 'fm-lint-workflows.sh: no GitHub workflow files found under %s\n' \
+      "$workflow_dir" >&2
+    exit 1
+  fi
+fi
+
+if ! command -v actionlint >/dev/null 2>&1; then
+  printf 'fm-lint-workflows.sh: actionlint not found; install actionlint %s with bin/fm-install-actionlint.sh <destination-directory> and put that directory on PATH.\n' \
+    "$REQUIRED_ACTIONLINT" >&2
+  exit 1
+fi
+ACTIONLINT_BIN=$(command -v actionlint)
+resolved=$("$ACTIONLINT_BIN" -version | awk 'NR==1 {print; exit}')
+printf 'fm-lint-workflows.sh: actionlint %s (pinned %s)\n' "$resolved" "$REQUIRED_ACTIONLINT" >&2
+if [ "$resolved" != "$REQUIRED_ACTIONLINT" ]; then
+  printf 'fm-lint-workflows.sh: actionlint %s required for CI parity, found %s. Install %s with bin/fm-install-actionlint.sh <destination-directory>.\n' \
+    "$REQUIRED_ACTIONLINT" "$resolved" "$REQUIRED_ACTIONLINT" >&2
+  exit 1
+fi
+
+# fm-lint.sh owns ShellCheck of the canonical shell set. Disable actionlint's
+# extra shell and Python subprocess linters so this gate is the named workflow
+# linter, not a second shell lint of `run:` blocks.
+set +e
+"$ACTIONLINT_BIN" -no-color -shellcheck= -pyflakes= -- "${FILES[@]}"
+rc=$?
+set -e
+
+if [ "$rc" -ne 0 ]; then
+  exit "$rc"
+fi
+
+printf 'fm-lint-workflows.sh: %s workflow files valid\n' "${#FILES[@]}"
+exit 0