@zerwiz/ymir 0.1.3 → 0.1.5

package/.agents/backend/fm-push-transition-lib.sh

@@ -0,0 +1,168 @@
+#!/usr/bin/env bash
+# Shared owner of the watcher's native push-transition escalation.
+#
+# The watcher and event-wait smoke tests source this library instead of loading
+# the whole watcher to obtain handle_push_transition. Its source list is limited
+# to the four production boundaries the transition handler actually calls.
+
+FM_PUSH_TRANSITION_LIB_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# shellcheck source=bin/fm-wake-lib.sh
+. "$FM_PUSH_TRANSITION_LIB_DIR/fm-wake-lib.sh"
+# shellcheck source=bin/fm-classify-lib.sh
+. "$FM_PUSH_TRANSITION_LIB_DIR/fm-classify-lib.sh"
+# shellcheck source=bin/fm-backend.sh
+. "$FM_PUSH_TRANSITION_LIB_DIR/fm-backend.sh"
+# shellcheck source=bin/fm-transition-lib.sh
+. "$FM_PUSH_TRANSITION_LIB_DIR/fm-transition-lib.sh"
+
+TRIAGE_LOG="$STATE/.watch-triage.log"
+TRIAGE_LOG_MAX_BYTES=${FM_WATCH_TRIAGE_LOG_MAX_BYTES:-262144}
+FM_WAKE_POST_OUTPUT_ACTION=
+# Set only after this watcher has printed a durable actionable reason. The
+# watcher's EXIT cleanup uses it to distinguish an ordinary delivered close from
+# an interruption that leaves a recovery gap before the next arm.
+FM_WATCH_DELIVERED_REASON=
+FM_WATCH_DELIVERY_PID=
+FM_WATCH_DELIVERY_IDENTITY=
+WATCH_DELIVERY_LOG="$STATE/.watch-deliveries.log"
+WATCH_DELIVERY_LOCK="$STATE/.watch-deliveries.lock"
+WATCH_DELIVERY_MAX_BYTES=${FM_WATCH_DELIVERY_MAX_BYTES:-65536}
+WATCH_DELIVERY_KEEP_LINES=${FM_WATCH_DELIVERY_KEEP_LINES:-64}
+case "$WATCH_DELIVERY_MAX_BYTES" in ''|*[!0-9]*|0) WATCH_DELIVERY_MAX_BYTES=65536 ;; esac
+case "$WATCH_DELIVERY_KEEP_LINES" in ''|*[!0-9]*|0) WATCH_DELIVERY_KEEP_LINES=64 ;; esac
+
+watch_delivery_clean_identity() {
+  printf '%s' "$1" | tr '\t\r\n' '   '
+}
+
+watch_delivery_clean_reason() {
+  printf '%s' "$1" | tr '\t\r\n' '   ' | cut -c1-4096
+}
+
+watch_delivery_publish() {
+  local reason=$1 i size tmp raw
+  [ -n "$FM_WATCH_DELIVERY_PID" ] || return 0
+  [ -n "$FM_WATCH_DELIVERY_IDENTITY" ] || return 0
+  i=0
+  while ! fm_lock_try_acquire "$WATCH_DELIVERY_LOCK"; do
+    [ "$i" -lt 20 ] || return 0
+    sleep 0.02
+    i=$((i + 1))
+  done
+  printf '%s\t%s\t%s\n' \
+    "$FM_WATCH_DELIVERY_PID" \
+    "$(watch_delivery_clean_identity "$FM_WATCH_DELIVERY_IDENTITY")" \
+    "$(watch_delivery_clean_reason "$reason")" >> "$WATCH_DELIVERY_LOG" 2>/dev/null || true
+  size=$(wc -c < "$WATCH_DELIVERY_LOG" 2>/dev/null | tr -d '[:space:]')
+  case "$size" in
+    ''|*[!0-9]*) ;;
+    *)
+      if [ "$size" -ge "$WATCH_DELIVERY_MAX_BYTES" ]; then
+        tmp="$WATCH_DELIVERY_LOG.tmp.$FM_WATCH_DELIVERY_PID"
+        raw="$tmp.raw"
+        tail -n "$WATCH_DELIVERY_KEEP_LINES" "$WATCH_DELIVERY_LOG" 2>/dev/null \
+          | tail -c "$WATCH_DELIVERY_MAX_BYTES" > "$raw" 2>/dev/null \
+          && awk 'NR > 1 || /^[0-9]+\t/' "$raw" > "$tmp" 2>/dev/null \
+          && mv -f "$tmp" "$WATCH_DELIVERY_LOG" 2>/dev/null
+        rm -f "$tmp" "$raw" 2>/dev/null || true
+      fi
+      ;;
+  esac
+  fm_lock_release "$WATCH_DELIVERY_LOCK"
+}
+
+# Append one bounded best-effort line for an absorbed supervision event.
+triage_log() {
+  local sz
+  printf '[%s] %s\n' "$(date '+%Y-%m-%dT%H:%M:%S%z')" "$1" >> "$TRIAGE_LOG" 2>/dev/null || return 0
+  sz=$(wc -c < "$TRIAGE_LOG" 2>/dev/null | tr -d '[:space:]')
+  case "$sz" in ''|*[!0-9]*) return 0 ;; esac
+  if [ "$sz" -ge "$TRIAGE_LOG_MAX_BYTES" ]; then
+    tail -n 2000 "$TRIAGE_LOG" > "$TRIAGE_LOG.tmp" 2>/dev/null && mv -f "$TRIAGE_LOG.tmp" "$TRIAGE_LOG" 2>/dev/null
+    rm -f "$TRIAGE_LOG.tmp" 2>/dev/null || true
+  fi
+}
+
+# Exit after reporting one actionable wake. Tests override this callback.
+wake() {
+  local output_status=0
+  case "$1" in
+    heartbeat*) echo $(( $(cat "$STATE/.heartbeat-streak" 2>/dev/null || echo 0) + 1 )) > "$STATE/.heartbeat-streak" ;;
+    *) echo 0 > "$STATE/.heartbeat-streak" ;;
+  esac
+  trap '' HUP INT TERM
+  [ -z "$FM_WAKE_POST_OUTPUT_ACTION" ] || trap '' PIPE
+  if echo "$1"; then
+    output_status=0
+    watch_delivery_publish "$1" || true
+    # shellcheck disable=SC2034 # Read by bin/fm-watch.sh's EXIT cleanup.
+    FM_WATCH_DELIVERED_REASON=$1
+  else
+    output_status=1
+  fi
+  if [ -n "$FM_WAKE_POST_OUTPUT_ACTION" ]; then
+    "$FM_WAKE_POST_OUTPUT_ACTION" "$output_status" || true
+  fi
+  [ "$output_status" -eq 0 ] || exit "$output_status"
+  exit 0
+}
+
+_hb_surfaced_path() {
+  status_heartbeat_seen_marker_path "$STATE" "$1"
+}
+
+# The byte offset in <task>'s status log that the heartbeat backstop has already
+# classified, or 0 when it has no usable position. A position rather than an
+# event line lets the backstop catch an event the per-wake path missed,
+# and comparing the last line cannot see an event a later routine append moved
+# past - exactly the masking fm-classify-lib.sh's span read exists to stop. An
+# absent or malformed marker (including one an older watcher wrote as a status
+# line) reads 0, so the log is re-classified and the backstop errs toward
+# surfacing rather than swallowing.
+hb_surfaced_offset() {  # <task>
+  status_presentation_marker_offset "$(_hb_surfaced_path "$1")" "$STATE/$1.status"
+}
+
+# Record a status log as successfully classified through the captured endpoint.
+mark_surfaced() {  # <status-file> <captured-end-offset> <captured-identity>
+  local f=$1 task
+  case "$f" in *.status) ;; *) return 0 ;; esac
+  task=$(basename "$f"); task="${task%.status}"
+  status_presentation_marker_commit "$(_hb_surfaced_path "$task")" "$f" "$2" "$3"
+}
+
+mark_surface_reported() {  # <status-file> <reported-signature>
+  local f=$1 task
+  task=$(basename "$f"); task="${task%.status}"
+  status_presentation_marker_report "$(_hb_surfaced_path "$task")" "$2"
+}
+
+# Act on a fresh actionable transition from a push-capable backend.
+handle_push_transition() {  # <backend> <session> <record>
+  local backend=$1 session=$2 record=$3 pane_id to window task reason span_record rest surface_end='' surface_ident=''
+  pane_id=$(fm_transition_pane_id "$record")
+  to=$(fm_transition_to_status "$record")
+  [ -n "$pane_id" ] || { sleep 1; return; }
+  window="$session:$pane_id"
+  task=$(window_to_task "$window" "$STATE")
+  # A declared wait already names the human this transition would report: an
+  # external dependency, or the captain a verified hold transferred the work to.
+  # Either way the wait is durably recorded, so absorb the immediate escalation
+  # and leave the bounded re-surface to the watcher's own pause cadence.
+  if status_is_paused_or_captain_held "$(last_status_line "$STATE/$task.status")"; then
+    triage_log "absorbed push $to (declared wait, awaiting external or captain): $window"
+    fm_backend_commit_transition "$backend" "$STATE" "$session" "$record" || exit 1
+    return
+  fi
+  span_record=$(status_span_first_actionable_record "$STATE/$task.status" \
+    "$(hb_surfaced_offset "$task")")
+  case $? in
+    0|1) surface_end=${span_record%%$'\t'*}; rest=${span_record#*$'\t'}; surface_ident=${rest%%$'\t'*} ;;
+  esac
+  reason="stale: $window (herdr: agent $to - waiting on human, escalated immediately, not via wedge timer)"
+  fm_wake_append stale "$window" "$reason" || exit 1
+  fm_backend_commit_transition "$backend" "$STATE" "$session" "$record" || exit 1
+  mark_surfaced "$STATE/$task.status" "$surface_end" "$surface_ident"
+  wake "$reason"
+}

package/.agents/backend/fm-quota-axi-lib.sh

@@ -0,0 +1,93 @@
+# shellcheck shell=bash
+# Shared quota-axi compatibility floor for the bootstrap diagnostic.
+# Usage: . bin/fm-quota-axi-lib.sh
+#
+# FM_QUOTA_AXI_MIN follows the axi-family floor policy owned beside the floor
+# constants in bin/fm-bootstrap.sh.
+#
+# This file is the single owner of that version number. bin/fm-bootstrap.sh
+# turns a failing check into the operator-facing MISSING diagnostic, which is
+# what keeps an older build from reaching a dispatch intake at all.
+
+FM_QUOTA_AXI_MIN=0.1.29
+
+fm_quota_axi_compatible() {
+  local timeout=${1:-} output parts major minor patch extra
+  local min_major min_minor min_patch min_extra
+  command -v quota-axi >/dev/null 2>&1 || return 1
+  if [ -n "$timeout" ]; then
+    case "$timeout" in
+      ''|*[!0-9]*|0) return 1 ;;
+    esac
+    [ "$(type -t fm_run_timed)" = function ] || return 1
+    output=$(fm_run_timed "$timeout" quota-axi --version 2>/dev/null </dev/null) || return 1
+  else
+    output=$(quota-axi --version 2>/dev/null </dev/null) || return 1
+  fi
+  parts=$(printf '%s\n' "$output" |
+    sed -n 's/.*\([0-9][0-9]*\)\.\([0-9][0-9]*\)\.\([0-9][0-9]*\).*/\1 \2 \3/p' |
+    head -1)
+  IFS=' ' read -r major minor patch extra <<< "$parts"
+  # An unparseable version is incompatible, never assumed current, so a
+  # development or vendored build cannot pass a floor it was never checked against.
+  [ -n "$major" ] && [ -n "$minor" ] && [ -n "$patch" ] && [ -z "$extra" ] || return 1
+  # The floor is compared from FM_QUOTA_AXI_MIN so bumping it needs one edit.
+  IFS='.' read -r min_major min_minor min_patch min_extra <<< "$FM_QUOTA_AXI_MIN"
+  [ -n "$min_major" ] && [ -n "$min_minor" ] && [ -n "$min_patch" ] && [ -z "$min_extra" ] || return 1
+  [ "$major" -gt "$min_major" ] && return 0
+  [ "$major" -eq "$min_major" ] || return 1
+  [ "$minor" -gt "$min_minor" ] && return 0
+  [ "$minor" -eq "$min_minor" ] || return 1
+  [ "$patch" -ge "$min_patch" ]
+}
+
+fm_quota_json_valid() {
+  jq -se '
+    length == 1 and
+    (.[0] | type) == "object" and
+    (.[0] |
+      .schemaVersion == 5 and
+      (.providers | type) == "array" and
+      (([.providers[].provider] | length) == ([.providers[].provider] | unique | length)) and
+      all(.providers[];
+      (.provider | type) == "string" and
+      (.provider | test("^[a-z0-9]+(-[a-z0-9]+)*$")) and
+      (.quotaSemantics | type) == "object" and
+      (.quotaSemantics.status as $semantics_status |
+        (["known", "partial", "unknown"] | index($semantics_status)) != null and
+        (.quotaSemantics.effectiveAvailability | type) == "array" and
+        (if $semantics_status == "known" then
+           ((.quotaSemantics.effectiveAvailability | length) > 0 and
+            all(.quotaSemantics.effectiveAvailability[];
+              .status == "known" or .status == "unknown"
+            ))
+         elif $semantics_status == "unknown" then
+           all(.quotaSemantics.effectiveAvailability[]; .status == "unknown")
+         else true
+         end) and
+        all(.quotaSemantics.effectiveAvailability[];
+          type == "object" and
+          (.scope | type) == "string" and
+          (.scope | length) > 0 and
+          ((.scope | test("^\\s|\\s$")) | not) and
+          ((.status == "known" and
+            (.runway.status as $runway_status |
+            ((.effectivePercentRemaining | type) == "number" and
+             .effectivePercentRemaining >= 0 and
+             .effectivePercentRemaining <= 100 and
+             (.runway | type) == "object" and
+             ($runway_status | type) == "string" and
+             (["through_reset", "projected_exhaustion", "exhausted_now", "unknown"] |
+               index($runway_status)) != null))) or
+           (.status == "unknown" and
+            (has("effectivePercentRemaining") | not) and
+            ((has("runway") | not) or
+             ((.runway | type) == "object" and
+              (.runway.status as $unknown_runway_status |
+               (["unknown", "exhausted_now"] | index($unknown_runway_status)) != null)))))
+        )
+      )
+    )
+    )
+  ' >/dev/null 2>&1
+}

package/.agents/backend/fm-quota-choose.sh

@@ -0,0 +1,384 @@
+#!/usr/bin/env bash
+# Choose the first quota-eligible candidate from a ranked list.
+#
+# Usage:
+#   fm-quota-choose.sh [--snapshot <path>] [--candidate <harness:model>]...
+#
+# Reads one already-captured quota-axi default TOON or JSON snapshot from the
+# provided file, or from stdin when --snapshot is omitted. For each --candidate
+# in order, it maps <harness> to its primary provider family, then applies the
+# provider-wide scopes and exact model or product scopes for <model>. A candidate
+# is eligible only when no applicable runway is `exhausted_now` and its known
+# effective percent remaining is greater than zero. The first eligible
+# candidate is printed as "<harness> <model>" and the script exits 0.
+# If no candidate is quota-eligible, it prints "none" and exits 1.
+#
+# Candidates are accepted as `--candidate <harness:model>` or as positional
+# colon-separated arguments, with earlier candidates preferred.
+# This script is deterministic and safe: it performs no side effects and exits
+# nonzero when the environment would lead to an unsafe dispatch.
+#
+# The helper is the canonical worker-side selection used after the agent has
+# already run `quota-axi` for its model selection. It never replaces the agent's
+# reasoning-class or runway-feasibility gates; it only answers which ordered
+# candidate remains eligible under the captured quota evidence.
+#
+# Multi-provider limitation: this helper maps each harness to ONE primary
+# provider family (see provider_for_harness below) and checks quota for that
+# family only. Some harnesses can run models from several providers - for
+# example, Pi and OpenCode may dispatch xAI, Anthropic, or other models - so a
+# candidate whose established provider differs from the harness's primary family
+# is checked against the wrong quota row. This is an accepted limitation of the
+# optional helper. Authoritative multi-provider routing - including provider
+# discovery from the harness catalog and quota matching by that explicit
+# provider - is owned by AGENTS.md section 4 and the quota-array-dispatch skill,
+# not by this helper. Use this helper only when the brief already fixed the
+# candidate order and every candidate's provider is the harness's primary family.
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# shellcheck source=bin/fm-quota-axi-lib.sh
+. "$SCRIPT_DIR/fm-quota-axi-lib.sh"
+# shellcheck source=bin/fm-control-lib.sh
+. "$SCRIPT_DIR/fm-control-lib.sh"
+
+die() { printf 'error: %s\n' "$1" >&2; exit 2; }
+usage() {
+  awk '
+    NR == 1 { next }
+    /^#/ { sub(/^# ?/, ""); print; next }
+    { exit }
+  ' "${BASH_SOURCE[0]}"
+  exit 2
+}
+
+CANDIDATES=()
+SNAPSHOT_SOURCE=
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --snapshot)
+      [ -n "${2-}" ] || die "--snapshot needs a path"
+      SNAPSHOT_SOURCE=$2
+      shift 2
+      ;;
+    --candidate)
+      [ -n "${2-}" ] || die "--candidate needs a value"
+      CANDIDATES+=("$2")
+      shift 2
+      ;;
+    -h|--help|help) usage ;;
+    --) shift; break ;;
+    -*) die "unknown option: $1" ;;
+    *) CANDIDATES+=("$1") ; shift ;;
+  esac
+done
+
+# Positional args after an explicit -- are also candidates.
+while [ "$#" -gt 0 ]; do
+  CANDIDATES+=("$1"); shift
+done
+
+[ "${#CANDIDATES[@]}" -gt 0 ] || die "no candidates supplied"
+
+# A candidate is <harness>:<model>. A bare harness with no colon means the
+# default model. Reject empty harnesses and characters that cannot form a safe
+# token. A colon-separated model is legal (e.g. model:codex_bengalfox).
+for c in "${CANDIDATES[@]}"; do
+  case "$c" in
+    ''|:*|*[!A-Za-z0-9._/:-]*) die "invalid candidate: $c" ;;
+  esac
+done
+
+if [ -n "$SNAPSHOT_SOURCE" ]; then
+  [ -f "$SNAPSHOT_SOURCE" ] && [ ! -L "$SNAPSHOT_SOURCE" ] || die "snapshot is not a regular file: $SNAPSHOT_SOURCE"
+  QUOTA_SNAPSHOT=$(cat -- "$SNAPSHOT_SOURCE") || die "cannot read snapshot: $SNAPSHOT_SOURCE"
+else
+  [ ! -t 0 ] || die "quota snapshot is required on stdin or with --snapshot"
+  QUOTA_SNAPSHOT=$(cat) || die "cannot read quota snapshot from stdin"
+fi
+[ -n "$QUOTA_SNAPSHOT" ] || die "empty quota snapshot"
+
+if printf '%s\n' "$QUOTA_SNAPSHOT" | jq -e 'type == "object"' >/dev/null 2>&1; then
+  QUOTA_JSON=$QUOTA_SNAPSHOT
+  schema=$(printf '%s\n' "$QUOTA_JSON" | jq -r '.schemaVersion // empty' 2>/dev/null) || schema=
+  case "$schema" in
+    5) ;;
+    '') die "quota-axi json missing schemaVersion" ;;
+    *) die "unsupported quota-axi schema version: $schema" ;;
+  esac
+else
+  QUOTA_JSON=$(printf '%s\n' "$QUOTA_SNAPSHOT" | jq -Rse '
+    def valid_preamble:
+      ((length == 2) and
+       (.[0] | test("^bin: (quota-axi|.*/quota-axi)$")) and
+       (.[1] | test("^generatedAt: .+$"))) or
+      ((length == 3) and
+       (.[0] | test("^bin: (quota-axi|.*/quota-axi)$")) and
+       (.[1] | test("^description: .+$")) and
+       (.[2] | test("^generatedAt: .+$")));
+    def valid_zero_head:
+      (length == 0) or valid_preamble;
+    def valid_help_tail:
+      if length == 0 then true
+      else
+        (.[0] | capture("^help\\[(?<count>[0-9]+)\\]:$").count | tonumber) as $count |
+        (.[1:] | length) == $count and all(.[1:][]; startswith("  "))
+      end;
+    def decoded_fields:
+      def parse($remaining; $fields):
+        if $remaining == "" then $fields
+        elif ($remaining | startswith("\"")) then
+          ($remaining | capture("^(?<field>\"(?:\\\\.|[^\"])*\")(?<rest>,.*|)$")) as $match |
+          ($match.field | fromjson) as $field |
+          if $match.rest == "," then $fields + [$field, ""]
+          else parse(($match.rest | sub("^,"; "")); $fields + [$field])
+          end
+        else
+          ($remaining | capture("^(?<field>[^,\"]*)(?<rest>,.*|)$")) as $match |
+          if $match.rest == "," then $fields + [$match.field, ""]
+          else parse(($match.rest | sub("^,"; "")); $fields + [$match.field])
+          end
+        end;
+      parse(.; []);
+    def decoded_row:
+      sub("^  "; "") | decoded_fields;
+    def valid_rows($field_count):
+      all(.[];
+        startswith("  ") and
+        ((decoded_row | length) == $field_count) and
+        all(decoded_row[]; length > 0)
+      );
+    def valid_attention_entries:
+      type == "array" and
+      all(.[];
+        type == "object" and
+        (.provider | type) == "string" and
+        (.provider | test("^[a-z0-9]+(-[a-z0-9]+)*$")) and
+        (.scope | type) == "string" and
+        (.scope | length) > 0 and
+        ((.scope | test("^\\s|\\s$")) | not) and
+        (.kind | type) == "string" and (.kind | length) > 0 and
+        (.detail | type) == "string" and (.detail | length) > 0 and
+        (.remedy | type) == "string" and (.remedy | length) > 0
+      );
+    def attention_availability:
+      if .kind == "headroom_unknown" and (.detail | contains("exhausted_now")) then
+        if (.detail | test("(^| · )exhausted_now limited by .+$")) then
+          {scope: .scope, status: "unknown", runway: {status: "exhausted_now"}}
+        else error("invalid exhausted headroom attention")
+        end
+      else empty
+      end;
+    def unknown_providers($entries):
+      $entries |
+      group_by(.provider) |
+      map({
+        provider: .[0].provider,
+        quotaSemantics: {
+          status: "unknown",
+          effectiveAvailability: [.[] | attention_availability]
+        }
+      });
+    def exhaustion_count:
+      if . == "exhaustion[0]:" or . == "exhaustion: []" then 0
+      else
+        capture("^exhaustion\\[(?<count>[1-9][0-9]*)\\]\\{provider,scope,usableRunwaySeconds,projectedExhaustedAt,limitingWindowId\\}:$").count |
+        tonumber
+      end;
+    def attention_count:
+      if . == "attention[0]:" or . == "attention: []" then 0
+      else
+        capture("^attention\\[(?<count>[1-9][0-9]*)\\]\\{provider,scope,kind,detail,remedy\\}:$").count |
+        tonumber
+      end;
+    (split("\n") | map(select(length > 0))) as $lines |
+    ($lines | map(. == "quota[0]:" or . == "quota: []") | index(true)) as $zero_index |
+    if $zero_index != null then
+      ($lines[:$zero_index]) as $head |
+      if ($head | valid_zero_head) then
+        ($lines[($zero_index + 1):]) as $tail |
+        if ($tail | length) >= 2 and
+             ($tail[0] == "exhaustion[0]:" or $tail[0] == "exhaustion: []") then
+          if ($tail[1] == "attention[0]:" or $tail[1] == "attention: []") and
+             ($tail[2:] | valid_help_tail) then
+            {schemaVersion: 5, providers: []}
+          elif ($tail[1] | test("^attention\\[[1-9][0-9]*\\]\\{provider,scope,kind,detail,remedy\\}:$")) then
+            ($tail[1] | attention_count) as $attention_count |
+            ($tail[2:(2 + $attention_count)]) as $attention_rows |
+            if ($attention_rows | length) == $attention_count and
+               ($attention_rows | valid_rows(5)) and
+               ($tail[(2 + $attention_count):] | valid_help_tail) then
+              ($attention_rows | map(decoded_row | {
+                provider: .[0], scope: .[1], kind: .[2], detail: .[3], remedy: .[4]
+              })) as $entries |
+              if ($entries | valid_attention_entries) then
+                {schemaVersion: 5, providers: unknown_providers($entries)}
+              else error("invalid zero-row attention identities")
+              end
+            else error("invalid zero-row attention section")
+            end
+          elif ($tail[1] | startswith("attention: ")) then
+            ($tail[1] | sub("^attention: "; "") | fromjson) as $entries |
+            if ($entries | valid_attention_entries) and
+               ($tail[2:] | valid_help_tail) then
+              {schemaVersion: 5, providers: unknown_providers($entries)}
+            else error("invalid zero-row attention array")
+            end
+          else error("invalid zero-row attention section")
+          end
+        else error("invalid zero-row quota sections")
+        end
+      else error("invalid zero-row quota header")
+      end
+    else
+      ($lines | map(test("^quota\\[[1-9][0-9]*\\]\\{provider,scope,effectivePercentRemaining,spendPriority,runway,confidence,limitedBy,resetsAt\\}:$")) | index(true)) as $quota_index |
+      if $quota_index == null then error("missing quota section")
+      else
+        ($lines[:$quota_index]) as $head |
+        ($lines[$quota_index] | capture("^quota\\[(?<count>[1-9][0-9]*)\\]").count | tonumber) as $quota_count |
+        ($lines[($quota_index + 1):($quota_index + 1 + $quota_count)]) as $quota_lines |
+        ($quota_index + 1 + $quota_count) as $exhaustion_index |
+        ($lines[$exhaustion_index] | exhaustion_count) as $exhaustion_count |
+        ($lines[($exhaustion_index + 1):($exhaustion_index + 1 + $exhaustion_count)]) as $exhaustion_rows |
+        ($exhaustion_index + 1 + $exhaustion_count) as $attention_index |
+        ($lines[$attention_index] | attention_count) as $attention_count |
+        ($lines[($attention_index + 1):($attention_index + 1 + $attention_count)]) as $attention_rows |
+        ($lines[($attention_index + 1 + $attention_count):]) as $tail |
+        if (($head | valid_preamble) | not) or
+           ($quota_lines | length) != $quota_count or
+           (($quota_lines | valid_rows(8)) | not) or
+           ($exhaustion_rows | length) != $exhaustion_count or
+           (($exhaustion_rows | valid_rows(5)) | not) or
+           ($attention_rows | length) != $attention_count or
+           (($attention_rows | valid_rows(5)) | not) or
+           (($tail | valid_help_tail) | not) then
+          error("invalid quota-axi TOON envelope")
+        else
+          ($quota_lines | map(decoded_row)) as $rows |
+          ($attention_rows | map(decoded_row | {
+            provider: .[0], scope: .[1], kind: .[2], detail: .[3], remedy: .[4]
+          })) as $attention_entries |
+          if (($attention_entries | valid_attention_entries) | not) then error("invalid attention identities")
+          elif any($rows[]; length != 8) then error("invalid quota rows")
+          else
+            {
+              schemaVersion: 5,
+              providers: (($rows |
+                map({
+                  provider: .[0],
+                  availability: {
+                    scope: .[1],
+                    status: "known",
+                    effectivePercentRemaining: (.[2] | tonumber),
+                    runway: {status: .[4]}
+                  }
+                })) +
+                ($attention_entries | map(. as $entry | {
+                  provider: $entry.provider,
+                  availability: ([$entry | attention_availability] | first // null)
+                })) |
+                group_by(.provider) |
+                map({
+                  provider: .[0].provider,
+                  quotaSemantics: {
+                    status: (if any(.[]; .availability.status == "known") then "known" else "unknown" end),
+                    effectiveAvailability: [.[].availability | select(. != null)]
+                  }
+                })
+              )
+            }
+          end
+        end
+      end
+    end
+  ' 2>/dev/null) || die "invalid quota-axi snapshot"
+fi
+
+printf '%s\n' "$QUOTA_JSON" | fm_quota_json_valid || die "invalid quota-axi provider data"
+
+# provider_for_harness <harness>
+# Map a firstmate harness name to its primary quota-axi provider family.
+# Multi-provider harnesses (Pi, OpenCode) map to their primary family only; see
+# the header limitation note. Authoritative multi-provider routing is owned by
+# AGENTS.md section 4 and the quota-array-dispatch skill, not this helper.
+provider_for_harness() {
+  case "$1" in
+    claude)       printf 'claude\n' ;;
+    codex)        printf 'codex\n' ;;
+    opencode)     printf 'codex\n' ;;
+    pi|pi-signed) printf 'pi\n' ;;
+    grok)         printf 'grok\n' ;;
+    kimi)         printf 'kimi\n' ;;
+    cursor)       printf 'cursor\n' ;;
+    muse)         printf 'meta\n' ;;
+    *)            return 1 ;;
+  esac
+}
+
+# effective_for_provider_model <provider> <model>
+# Print the most constraining applicable quota evidence for the provider/model
+# tuple, including provider-wide and exact model or product scopes.
+effective_for_provider_model() {
+  local provider=$1 model=${2:-default}
+  printf '%s\n' "$QUOTA_JSON" | jq -c --arg provider "$provider" --arg model "$model" '
+    ($model | sub("^model:"; "")) as $model_token |
+    ([.providers[]? | select(.provider == $provider)] | first) as $p |
+    if ($p // null) == null then {status: "unknown"}
+    else ($p.quotaSemantics.effectiveAvailability // []) |
+    map(select(.scope as $scope |
+      $scope == "all_models" or $scope == "all_products" or
+      ($model_token != "" and $model_token != "default" and
+       (($scope | startswith("model:")) or ($scope | startswith("product:"))) and
+       ($model_token == ($scope | sub("^(model|product):"; ""))))
+    )) as $applicable |
+    ($applicable | map(select(.status == "known"))) as $known |
+    if ($applicable | length) == 0 then {status: "unknown"}
+    elif any($applicable[]; (.runway.status // "") == "exhausted_now") then
+      ($applicable | map(select((.runway.status // "") == "exhausted_now")) | first)
+    elif ($known | length) == 0 then {status: "unknown"}
+    elif any($known[]; .effectivePercentRemaining == 0) then
+      ($known | map(select(.effectivePercentRemaining == 0)) | first)
+    else ($known | min_by(.effectivePercentRemaining))
+    end
+    end
+  ' 2>/dev/null
+}
+
+for c in "${CANDIDATES[@]}"; do
+  harness=${c%%:*}
+  model=${c#*:}
+  [ "$model" = "$c" ] && model="default"
+  [ -n "$model" ] || die "invalid candidate: $c"
+  fm_control_harness_supported "$harness" || die "unknown harness: $harness"
+  provider_for_harness "$harness" >/dev/null || die "unknown harness: $harness"
+done
+
+chosen="none"
+for c in "${CANDIDATES[@]}"; do
+  harness=${c%%:*}
+  model=${c#*:}
+  [ "$model" = "$c" ] && model="default"
+  provider=$(provider_for_harness "$harness")
+  effective=$(effective_for_provider_model "$provider" "$model")
+  if [ -z "$effective" ] || [ "$effective" = "null" ]; then
+    continue
+  fi
+  if printf '%s\n' "$effective" | jq -e '
+    if (.runway.status // "") == "exhausted_now" then false
+    elif .status == "unknown" then false
+    else
+      .effectivePercentRemaining as $remaining |
+      (($remaining | type) == "number") and
+      ($remaining > 0) and
+      ((.runway.status // "") != "exhausted_now")
+    end
+  ' >/dev/null 2>&1; then
+    chosen="$harness $model"
+    break
+  fi
+done
+
+printf '%s\n' "$chosen"
+[ "$chosen" != "none" ]