@zerwiz/ymir 0.1.3 → 0.1.5

package/.agents/backend/fm-cursor-lib.sh

@@ -0,0 +1,243 @@
+#!/usr/bin/env bash
+# Cursor executable resolution and Cursor process identity.
+# Sourced by bin/fm-spawn.sh, bin/fm-harness.sh, bin/fm-busy-lib.sh, and
+# bin/backends/tmux.sh. This file is sourced by scripts and has no side effects
+# on source.
+#
+# Why one owner: cursor ships TWO executable names - `cursor-agent`, plus the
+# legacy alias `agent` it installs on every platform. `agent` is far too
+# generic to trust on its name alone, so every spawn, ancestry, and liveness
+# caller has to agree on the same narrowed rule or an unrelated `/opt/agent`,
+# an unrelated `agent` on PATH, or a path that merely contains an `agent/`
+# directory component silently classifies as this harness. That widening would
+# let firstmate launch an unrelated executable with Cursor flags.
+#
+# Two independent kinds of Cursor evidence are accepted, and either alone
+# carries a positive verdict, so no single vendor string is load-bearing:
+#
+#   Structural (no subprocess, safe during a process scan): the canonical path
+#   is named cursor-agent or lives under Cursor's versioned install tree.
+#   Cursor's installer places both names as symlinks into
+#   ~/.local/share/cursor-agent/versions/<version>/cursor-agent (verified
+#   2026-08-11, cursor-agent 2026.08.11-e8db854), so the alias resolves to
+#   Cursor's own name and install tree.
+#
+#   Probe (a bounded `--help` run, used only when resolving an executable to
+#   launch, never during a process scan): Cursor's own CLI banner and its
+#   CURSOR_API_ENDPOINT / api2.cursor.sh option text. Fails closed on a
+#   timeout, a non-zero exit, or missing markers - a bare zero exit is never
+#   accepted as proof.
+#
+# Process detection deliberately uses the structural signal only. Probing an
+# arbitrary pid's executable during an ancestry walk or a liveness poll would
+# execute a stranger's binary, which is exactly the hazard this file exists to
+# close.
+#
+# Cursor's composer shape is deliberately NOT here. Its reverse-video
+# placeholder remnant is taught to the ONE fleet-wide screen classifier in
+# bin/fm-composer-lib.sh, which every backend already delegates to; an
+# adapter-local composer normalizer would be the second copy that owner exists
+# to prevent.
+
+# Bounded probe budget in seconds. Cursor's --help is local and returns
+# immediately; the bound exists so a hung or interactive impostor cannot wedge
+# a spawn or a readiness check.
+FM_CURSOR_PROBE_TIMEOUT=${FM_CURSOR_PROBE_TIMEOUT:-10}
+
+# Canonical absolute path for $1, or the input unchanged when it cannot be
+# resolved. Symlink resolution is what makes the structural signal work, since
+# both installed names are symlinks into Cursor's versioned install tree.
+fm_cursor_canonical_path() {  # <path>
+  local path=$1 dir base
+  [ -n "$path" ] || return 1
+  dir=$(CDPATH='' cd -- "$(dirname -- "$path")" 2>/dev/null && pwd -P) || { printf '%s\n' "$path"; return 0; }
+  base=$(basename -- "$path")
+  # Follow the symlink chain by hand: readlink -f is GNU-only and realpath is
+  # not guaranteed on macOS, and this needs no new dependency.
+  local hops=0 target
+  while [ -L "$dir/$base" ] && [ "$hops" -lt 16 ]; do
+    target=$(readlink -- "$dir/$base") || break
+    case "$target" in
+      /*) dir=$(CDPATH='' cd -- "$(dirname -- "$target")" 2>/dev/null && pwd -P) || break
+          base=$(basename -- "$target") ;;
+      *)  dir=$(CDPATH='' cd -- "$dir/$(dirname -- "$target")" 2>/dev/null && pwd -P) || break
+          base=$(basename -- "$target") ;;
+    esac
+    hops=$((hops + 1))
+  done
+  printf '%s\n' "$dir/$base"
+}
+
+# True when path $1 carries Cursor's own structural evidence: its canonical
+# name is cursor-agent, or it is inside Cursor's
+# cursor-agent/versions/<version>/ install tree. A directory component merely
+# named `agent` or `cursor-agent` is NEVER enough.
+fm_cursor_path_is_cursor() {  # <path>
+  local path=$1 canonical
+  [ -n "$path" ] || return 1
+  canonical=$(fm_cursor_canonical_path "$path") || return 1
+  case "${canonical##*/}" in cursor-agent) return 0 ;; esac
+  case "$canonical" in */cursor-agent/versions/*/*) return 0 ;; esac
+  return 1
+}
+
+# True when running `$1 --help` produces Cursor's own CLI identity. Bounded and
+# fail-closed: a timeout, a non-zero exit, or output without a Cursor-specific
+# marker is a refusal. Never called during a process scan.
+fm_cursor_bounded_output() {  # <path> <args...>
+  local path=$1 runner=
+  shift
+  [ -n "$path" ] && [ -x "$path" ] || return 1
+  if command -v timeout >/dev/null 2>&1; then runner=timeout
+  elif command -v gtimeout >/dev/null 2>&1; then runner=gtimeout
+  fi
+  [ -n "$runner" ] || return 1
+  "$runner" "$FM_CURSOR_PROBE_TIMEOUT" "$path" "$@" 2>/dev/null
+}
+
+fm_cursor_probe_is_cursor() {  # <path>
+  local path=$1 out
+  out=$(fm_cursor_bounded_output "$path" --help) || return 1
+  [ -n "$out" ] || return 1
+  case "$out" in
+    *"Start the Cursor Agent"*) return 0 ;;
+    *CURSOR_API_ENDPOINT*) return 0 ;;
+    *api2.cursor.sh*) return 0 ;;
+  esac
+  return 1
+}
+
+# True when executable $1 may be launched as Cursor.
+#
+# An executable whose own name is cursor-agent is accepted on the ordinary
+# executable check: the name is Cursor's and is specific enough to stand alone.
+# Anything else - which in practice means the legacy `agent` alias - must first
+# prove itself Cursor, structurally or by the bounded probe.
+fm_cursor_verify_executable() {  # <path>
+  local path=$1
+  [ -n "$path" ] && [ -x "$path" ] || return 1
+  case "${path##*/}" in cursor-agent) return 0 ;; esac
+  fm_cursor_path_is_cursor "$path" && return 0
+  fm_cursor_probe_is_cursor "$path"
+}
+
+fm_cursor_list_models() {  # <path>
+  fm_cursor_bounded_output "$1" --list-models
+}
+
+fm_cursor_catalog_has_model() {  # <model>
+  local wanted=$1
+  awk -v wanted="$wanted" '
+    BEGIN { ansi = sprintf("%c\\[[0-9;]*[A-Za-z]", 27) }
+    {
+      line = $0
+      gsub(ansi, "", line)
+      separator = index(line, " - ")
+      if (!separator) next
+      id = substr(line, 1, separator - 1)
+      sub(/^[[:space:]]+/, "", id)
+      sub(/[[:space:]]+$/, "", id)
+      if (id == wanted) found = 1
+    }
+    END { exit found ? 0 : 1 }
+  '
+}
+
+# Print the stable absolute launcher path for the Cursor executable, or return 1
+# with a diagnostic on stderr.
+#
+# Resolution order, shared by bin/fm-spawn.sh and bin/fm-remote-doctor.sh:
+# cursor-agent on PATH, `agent` on PATH, then the ~/.local/bin installs of
+# both. cursor-agent is preferred over the alias at every stage. The
+# ~/.local/bin fallbacks exist because Cursor's user-local install is routinely
+# absent from a non-interactive login PATH. Every `agent` candidate passes
+# fm_cursor_verify_executable before it is accepted, so an unrelated executable
+# named agent is rejected rather than launched with Cursor's flags.
+#
+# The STABLE path is printed, not the canonical one. Identity is proven THROUGH
+# canonicalization (that is what makes the `agent` alias safe), but cursor's
+# installer points both stable names at
+# ~/.local/share/cursor-agent/versions/<version>/cursor-agent, so the canonical
+# path carries a version that the CLI replaces on its own auto-update. Printing
+# the stable launcher keeps a recorded launch command valid across an upgrade;
+# printing the canonical one would pin a task to a version that can vanish.
+fm_cursor_resolve_binary() {
+  local name candidate
+  for name in cursor-agent agent; do
+    candidate=$(command -v "$name" 2>/dev/null || true)
+    [ -n "$candidate" ] && [ -x "$candidate" ] || continue
+    if fm_cursor_verify_executable "$candidate"; then
+      printf '%s\n' "$candidate"
+      return 0
+    fi
+  done
+  for name in cursor-agent agent; do
+    [ -n "${HOME:-}" ] || break
+    candidate="$HOME/.local/bin/$name"
+    [ -x "$candidate" ] || continue
+    if fm_cursor_verify_executable "$candidate"; then
+      printf '%s\n' "$candidate"
+      return 0
+    fi
+  done
+  echo "error: no verified cursor executable found; searched PATH for 'cursor-agent' and 'agent', plus '${HOME:-}/.local/bin/cursor-agent' and '${HOME:-}/.local/bin/agent'. A file named 'agent' is accepted only when it resolves into Cursor's install tree or its --help identifies the Cursor Agent CLI." >&2
+  return 1
+}
+
+# Read argv[0] without flattening it into a whitespace-delimited command line.
+fm_cursor_argv0_for_pid() {  # <pid> [comm-fallback]
+  local pid=$1 fallback=${2:-} proc_root=${FM_PROC_ROOT_OVERRIDE:-/proc} argv0=
+  if [ -r "$proc_root/$pid/cmdline" ]; then
+    IFS= read -r -d '' argv0 < "$proc_root/$pid/cmdline" || true
+    [ -n "$argv0" ] && { printf '%s\n' "$argv0"; return 0; }
+  fi
+  if [ -z "$fallback" ]; then
+    fallback=$(LC_ALL=C ps -p "$pid" -o comm= 2>/dev/null || true)
+  fi
+  [ -n "$fallback" ] || return 1
+  printf '%s\n' "$fallback"
+}
+
+fm_cursor_argv0_is_cursor() {  # <argv0>
+  local argv0=$1
+  [ -n "$argv0" ] || return 1
+  case "$argv0" in
+    ''|MainThread) return 1 ;;
+    cursor-agent) return 0 ;;
+  esac
+  fm_cursor_path_is_cursor "$argv0"
+}
+
+# True when the process described by command name $1 and structured argv0 $3 is
+# Cursor. The single owner of Cursor process identity for the ancestry walk
+# (bin/fm-session-lock-lib.sh), harness detection (bin/fm-harness.sh), pane
+# liveness (bin/backends/tmux.sh), and worker-server discovery (bin/fm-spawn.sh).
+#
+# Accepted: an exact cursor-agent command name; a MainThread or bare
+# interpreter whose structured argv[0] carries Cursor's install path; a legacy
+# `agent` whose argv[0] resolves into Cursor's install tree.
+#
+# Rejected: a bare MainThread with no Cursor evidence; any executable whose
+# basename merely happens to be `agent`; any path with an `agent/` directory
+# component that is running something else.
+fm_cursor_process_matches() {  # <comm> <args> [argv0]
+  local comm=$1 argv0=${3:-} base
+  [ -n "$comm" ] || [ -n "$argv0" ] || return 1
+  argv0=${argv0:-$comm}
+  base=$(basename -- "$comm")
+  base=${base#-}
+  case "$base" in
+    cursor-agent) return 0 ;;
+    agent|MainThread|node|node-*|node[0-9]*|python|python[0-9]*|python[0-9].[0-9]*)
+      fm_cursor_argv0_is_cursor "$argv0" && return 0
+      # A legacy alias may also be reported by its own path in comm.
+      fm_cursor_path_is_cursor "$comm" && return 0
+      return 1
+      ;;
+  esac
+  # A version-named or otherwise renamed executable still identifies through
+  # its install path.
+  case "$comm" in */*) fm_cursor_path_is_cursor "$comm" && return 0 ;; esac
+  return 1
+}
+

package/.agents/backend/fm-decision-hold.sh

@@ -0,0 +1,232 @@
+#!/usr/bin/env bash
+# fm-decision-hold.sh - transitional compatibility shim over bin/fm-captain-hold.sh.
+#
+# The separate "decision" concept collapsed into the one primitive the captain
+# cares about: a task held for the captain. bin/fm-captain-hold.sh owns every
+# surviving behavior; this shim only maps the retired command surface onto it so
+# in-flight work briefed before the collapse keeps working for one release, and
+# it will be removed in the release after the collapse lands.
+#
+# Mapping (old -> new):
+#   id <origin> <key>                      -> prints the legacy <origin>-decision-<key> identity
+#   hold <origin> <key> --title --reason [--repo]
+#                                          -> hold <origin>-decision-<key> --origin <origin> ...
+#   complete <origin> (--none | <key>...)  -> complete <origin> (--none | <origin>-decision-<key>...)
+#   verify <origin>                        -> verify <origin>
+#   resolve <origin> <key> --decision-file <f> --routed-to <id>...
+#                                          -> answer <origin>-decision-<key> with the routed ids
+#                                             appended to the decision text, then clear the
+#                                             recorded blocked-by edges through tasks-axi; an
+#                                             exact replay of a pre-collapse routed record reuses
+#                                             its historical digest and text before clearing edges
+#   answer|decline|repair <origin> <key> --decision-file <f>
+#                                          -> answer <origin>-decision-<key> --decision-file <f>
+#   answers (<origin> | --any-origin) --source <p>
+#                                          -> answers with the same positional (the intake resolves
+#                                             task ids first and legacy identities second)
+#   bind <source> (<origin> | --any-origin) -> bind <source> [<origin>]
+#   unbind | binding <source>              -> unchanged
+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}}"
+CAPTAIN_HOLD="$SCRIPT_DIR/fm-captain-hold.sh"
+
+usage() {
+  awk '
+    NR == 1 { next }
+    /^#/ { sub(/^# ?/, ""); print; next }
+    { exit }
+  ' "$0"
+}
+
+fail() {
+  printf 'fm-decision-hold: %s\n' "$*" >&2
+  exit 1
+}
+
+validate_slug() {  # <label> <value>
+  case "$2" in
+    ''|*[!A-Za-z0-9._-]*) fail "$1 must be a non-empty privacy-safe slug: $2" ;;
+  esac
+}
+
+compose() {  # <origin> <key>
+  validate_slug origin-id "$1"
+  validate_slug decision-key "$2"
+  printf '%s-decision-%s' "$1" "$2"
+}
+
+task_show() {
+  (cd "$FM_HOME" && tasks-axi show "$1" --full) 2>/dev/null
+}
+
+show_field() {
+  local output=$1 field=$2
+  printf '%s\n' "$output" | sed -n "s/^  $field: //p" | head -1
+}
+
+normalized_blocked_by() {
+  local blocked
+  blocked=$(show_field "$1" blocked_by | tr -d '[:space:]')
+  blocked=${blocked#\"}
+  blocked=${blocked%\"}
+  [ "$blocked" != - ] || blocked=''
+  printf '%s' "$blocked"
+}
+
+list_has_key() {
+  case ",$1," in
+    *",$2,"*) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+sha256_text() {
+  if command -v shasum >/dev/null 2>&1; then
+    printf '%s' "$1" | shasum -a 256 | awk '{print $1}'
+  elif command -v sha256sum >/dev/null 2>&1; then
+    printf '%s' "$1" | sha256sum | awk '{print $1}'
+  else
+    fail "shasum or sha256sum is required"
+  fi
+}
+
+recorded_field() {
+  local rest=$1 label=$2
+  case "$rest" in
+    *"$label: "*) rest=${rest#*"$label: "} ;;
+    *) return 1 ;;
+  esac
+  rest=${rest%%\\n*}
+  rest=${rest%%$'\n'*}
+  printf '%s' "$rest"
+}
+
+command_resolve() {
+  local origin=${1:-} key=${2:-} decision_file='' routed='' routed_csv id dep tmp answer_file show state blocked hold_show hold_body
+  local resolution_recorded=0 legacy_replay=0 decision_text decision_digest recorded_digest recorded_routes
+  [ "$#" -ge 2 ] || { usage >&2; exit 2; }
+  shift 2
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --decision-file) shift; decision_file=${1:-} ;;
+      --routed-to) shift; validate_slug routed-task "${1:-}"; routed="${routed}${routed:+ }${1:-}" ;;
+      *) usage >&2; exit 2 ;;
+    esac
+    shift
+  done
+  id=$(compose "$origin" "$key")
+  [ -n "$decision_file" ] || fail "--decision-file is required"
+  [ -f "$decision_file" ] || fail "decision file does not exist: $decision_file"
+  [ -n "$routed" ] || fail "at least one --routed-to task is required; use answer when the captain's answer routes no work"
+  routed=$(printf '%s\n' "$routed" | tr ' ' '\n' | sed '/^$/d' | LC_ALL=C sort -u | paste -sd' ' -)
+  routed_csv=$(printf '%s' "$routed" | tr ' ' ',')
+  decision_text=$(cat "$decision_file")
+  [ -n "$decision_text" ] || fail "decision file must not be empty"
+  decision_digest=$(sha256_text "$decision_text")
+  hold_show=$(task_show "$id") || fail "captain decision $id does not exist in the active home"
+  hold_body=$(show_field "$hold_show" body)
+  case "$hold_body" in
+    *"Resolution recorded by fm-decision-hold."*"Routed identities: "*)
+      recorded_digest=$(recorded_field "$hold_body" "Decision digest" || true)
+      recorded_routes=$(recorded_field "$hold_body" "Routed identities" || true)
+      [ "$recorded_digest" = "$decision_digest" ] \
+        || fail "captain decision $id records a different captain decision"
+      [ "$recorded_routes" = "$routed_csv" ] \
+        || fail "captain decision $id records different routed work"
+      resolution_recorded=1
+      legacy_replay=1
+      ;;
+    *"Resolution recorded by fm-captain-hold."*)
+      resolution_recorded=1
+      ;;
+  esac
+  for dep in $routed; do
+    show=$(task_show "$dep") || fail "routed task $dep does not exist in the active home"
+    state=$(show_field "$show" state)
+    [ "$state" != "done" ] || [ "$resolution_recorded" = 1 ] \
+      || fail "routed task $dep is already done"
+    blocked=$(normalized_blocked_by "$show")
+    list_has_key "$blocked" "$id" || [ "$resolution_recorded" = 1 ] \
+      || fail "routed task $dep is not durably blocked by $id"
+  done
+  tmp=$(umask 077; mktemp "${TMPDIR:-/tmp}/fm-decision-hold-resolve.XXXXXX") \
+    || fail "cannot stage the captain decision"
+  if ! { cat "$decision_file" && printf '\n\nRouted work:\n' \
+    && printf '%s\n' "$routed" | tr ' ' '\n' | sed 's/^/- /'; } > "$tmp"; then
+    rm -f -- "$tmp"
+    fail "cannot stage the captain decision for $id"
+  fi
+  answer_file=$tmp
+  [ "$legacy_replay" = 0 ] || answer_file=$decision_file
+  if ! "$CAPTAIN_HOLD" answer "$id" --decision-file "$answer_file"; then
+    rm -f -- "$tmp"
+    exit 1
+  fi
+  rm -f -- "$tmp"
+  for dep in $routed; do
+    show=$(task_show "$dep") || fail "routed task $dep disappeared before routing"
+    if list_has_key "$(normalized_blocked_by "$show")" "$id"; then
+      (cd "$FM_HOME" && tasks-axi unblock "$dep" --by "$id" >/dev/null) \
+        || fail "could not route the recorded decision to $dep"
+    fi
+  done
+  printf 'resolved: %s -> %s\n' "$id" "$routed"
+}
+
+command_complete() {
+  local origin=${1:-} mapped=''
+  [ "$#" -ge 2 ] || { usage >&2; exit 2; }
+  validate_slug origin-id "$origin"
+  shift
+  if [ "$#" -eq 1 ] && [ "$1" = --none ]; then
+    exec "$CAPTAIN_HOLD" complete "$origin" --none
+  fi
+  for key in "$@"; do
+    [ "$key" != --none ] || fail "--none cannot be combined with decision keys"
+    mapped="${mapped}${mapped:+ }$(compose "$origin" "$key")"
+  done
+  # shellcheck disable=SC2086  # mapped is a validated space-separated slug list.
+  exec "$CAPTAIN_HOLD" complete "$origin" $mapped
+}
+
+command_close() {  # <origin> <key> <flag-args...>
+  local origin=${1:-} key=${2:-} id
+  [ "$#" -ge 2 ] || { usage >&2; exit 2; }
+  id=$(compose "$origin" "$key")
+  shift 2
+  local decision_file=''
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --decision-file) shift; decision_file=${1:-} ;;
+      *) usage >&2; exit 2 ;;
+    esac
+    shift
+  done
+  exec "$CAPTAIN_HOLD" answer "$id" --decision-file "$decision_file"
+}
+
+command_hold() {
+  local origin=${1:-} key=${2:-} id
+  [ "$#" -ge 2 ] || { usage >&2; exit 2; }
+  id=$(compose "$origin" "$key")
+  shift 2
+  exec "$CAPTAIN_HOLD" hold "$id" --origin "$origin" "$@"
+}
+
+case "${1:-}" in
+  id) shift; [ "$#" -eq 2 ] || { usage >&2; exit 2; }; compose "$1" "$2"; printf '\n' ;;
+  hold) shift; command_hold "$@" ;;
+  complete) shift; command_complete "$@" ;;
+  verify) shift; exec "$CAPTAIN_HOLD" verify "$@" ;;
+  resolve) shift; command_resolve "$@" ;;
+  answer|decline|repair) shift; command_close "$@" ;;
+  answers) shift; exec "$CAPTAIN_HOLD" answers "$@" ;;
+  bind) shift; exec "$CAPTAIN_HOLD" bind "$@" ;;
+  unbind) shift; exec "$CAPTAIN_HOLD" unbind "$@" ;;
+  binding) shift; exec "$CAPTAIN_HOLD" binding "$@" ;;
+  -h|--help) usage ;;
+  *) usage >&2; exit 2 ;;
+esac