@zerwiz/ymir 0.1.4 → 0.1.5

package/.agents/backend/fm-public-followup-emit.sh

@@ -0,0 +1,260 @@
+#!/usr/bin/env bash
+# fm-public-followup-emit.sh - emit ONE structured terminal work result for work
+# bound to a public commitment, into the owning home's private event inbox.
+#
+# WHY THIS EXISTS: a public promise is kept by the home that owns the relay
+# consent and the thread binding. The home doing the work only has to report a
+# TYPED result. Firstmate must never recover the source home, work id, outcome,
+# or deliverables by parsing a free-form "done: ..." status sentence, so this
+# script is the structured channel that carries them.
+#
+# WHAT IT DOES NOT DO: it never posts anything, never reads relay credentials,
+# and never resolves a public thread. Outward delivery stays with the owning
+# home (bin/fm-public-followup.sh deliver).
+#
+# Usage:
+#   fm-public-followup-emit.sh --home <owning-home> \
+#     --obligation <obligation-id> --relation <relation-id> \
+#     --source-home <main|secondmate:<id>> --work-id <task-id> \
+#     --generation <n> --outcome <outcome-type> \
+#     [--deliverable <key>=<value>]... \
+#     (--outcome-text <text> | --outcome-text-file <path> | --outcome-text -)
+#
+# Options:
+#   --home <path>          The home that owns the public commitment (the primary
+#                          that took the mention). Must already have a
+#                          registration for --obligation; see
+#                          `fm-public-followup.sh register`.
+#   --obligation <id>      tasks-axi public-followup obligation id.
+#   --relation <id>        The relation_id this work fulfills or contributes to.
+#   --source-home <id>     This worker's stable home identity, exactly as bound:
+#                          "main" or "secondmate:<stable-id>".
+#   --work-id <id>         This worker's exact task id, exactly as bound.
+#   --generation <n>       The bound relation generation (integer >= 1).
+#   --outcome <type>       Typed outcome. tasks-axi owns the vocabulary and
+#                          refuses anything it does not accept; this script only
+#                          checks the token is a safe slug.
+#   --deliverable k=v      Repeatable safe deliverable (for example
+#                          pr_url=https://...). tasks-axi owns which keys a given
+#                          expected-final type permits.
+#   --outcome-text ...     Public-safe outcome sentence, from an argument, a
+#                          file, or stdin ("-"). Collapsed to one line; the
+#                          event builder bounds it by codepoint, so control
+#                          characters cannot survive.
+#
+# Output: the event id on stdout. Exit 0 on a published or already-present event
+# (both are successes: the id is derived, so re-emitting the same terminal result
+# is a no-op), 2 on a usage or validation error, 1 on a publication failure.
+#
+# IDEMPOTENCY: the event id is a digest of the identity tuple (obligation,
+# relation, source home, work id, generation, outcome type, deliverables), so a
+# retry, a duplicate report, or a rerun after restart resolves to the same file
+# and the first published copy wins. Nothing here needs coordination.
+#
+# SAFETY: the event is published through the shared private-artifact primitive -
+# atomic rename into place, single link, mode 0600 (never executable), inside a
+# 0700 directory this script refuses to create. The owning home must already have
+# registered the obligation, so a home that never opted into the relay can never
+# be given public-followup artifacts by a child.
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=bin/fm-public-followup-lib.sh
+. "$SCRIPT_DIR/fm-public-followup-lib.sh"
+
+usage() {
+  cat >&2 <<'EOF'
+usage: fm-public-followup-emit.sh --home <owning-home> --obligation <id> --relation <id>
+         --source-home <main|secondmate:<id>> --work-id <id> --generation <n>
+         --outcome <type> [--deliverable <key>=<value>]...
+         (--outcome-text <text> | --outcome-text-file <path> | --outcome-text -)
+EOF
+}
+
+# The header comment IS the help text, so the two can never drift apart.
+help() {
+  sed -n '2,/^set -u$/p' "$0" | sed '$d; s/^# \{0,1\}//'
+}
+
+die() { printf 'fm-public-followup-emit: %s\n' "$1" >&2; exit "${2:-2}"; }
+
+HOME_DIR=
+OBLIGATION=
+RELATION=
+SOURCE_HOME=
+WORK_ID=
+GENERATION=
+OUTCOME=
+TEXT_SOURCE=
+TEXT_MODE=
+DELIVERABLE_KEYS=()
+DELIVERABLE_VALUES=()
+
+case "${1:-}" in
+  --help|-h) help; exit 0 ;;
+  '') usage; exit 2 ;;
+esac
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --home)            shift; HOME_DIR=${1:-} ;;
+    --obligation)      shift; OBLIGATION=${1:-} ;;
+    --relation)        shift; RELATION=${1:-} ;;
+    --source-home)     shift; SOURCE_HOME=${1:-} ;;
+    --work-id)         shift; WORK_ID=${1:-} ;;
+    --generation)      shift; GENERATION=${1:-} ;;
+    --outcome)         shift; OUTCOME=${1:-} ;;
+    --outcome-text)    shift; TEXT_MODE='inline'; TEXT_SOURCE=${1:-} ;;
+    --outcome-text-file) shift; TEXT_MODE='file'; TEXT_SOURCE=${1:-} ;;
+    --deliverable)
+      shift
+      case "${1:-}" in
+        *=*) ;;
+        *) die "--deliverable needs <key>=<value>, got '${1:-}'" ;;
+      esac
+      DELIVERABLE_KEYS+=("${1%%=*}")
+      DELIVERABLE_VALUES+=("${1#*=}")
+      ;;
+    --help|-h) help; exit 0 ;;
+    *) die "unknown argument '$1'" ;;
+  esac
+  shift || true
+done
+
+[ -n "$HOME_DIR" ]    || { usage; exit 2; }
+[ -n "$OBLIGATION" ]  || { usage; exit 2; }
+[ -n "$RELATION" ]    || { usage; exit 2; }
+[ -n "$SOURCE_HOME" ] || { usage; exit 2; }
+[ -n "$WORK_ID" ]     || { usage; exit 2; }
+[ -n "$GENERATION" ]  || { usage; exit 2; }
+[ -n "$OUTCOME" ]     || { usage; exit 2; }
+[ -n "$TEXT_MODE" ]   || { usage; exit 2; }
+
+fm_pf_slug_valid "$OBLIGATION" || die "unsafe obligation id: $OBLIGATION"
+fm_pf_slug_valid "$RELATION"   || die "unsafe relation id: $RELATION"
+fm_pf_slug_valid "$WORK_ID"    || die "unsafe work id: $WORK_ID"
+fm_pf_slug_valid "$OUTCOME"    || die "unsafe outcome type: $OUTCOME"
+fm_pf_home_id_valid "$SOURCE_HOME" \
+  || die "source home must be 'main' or 'secondmate:<stable-id>', got '$SOURCE_HOME'"
+case "$GENERATION" in
+  ''|*[!0-9]*) die "generation must be a positive integer, got '$GENERATION'" ;;
+esac
+[ "$GENERATION" -ge 1 ] || die "generation must be >= 1, got '$GENERATION'"
+
+i=0
+while [ "$i" -lt "${#DELIVERABLE_KEYS[@]}" ]; do
+  key=${DELIVERABLE_KEYS[$i]}
+  case "$key" in
+    ''|*[!a-z0-9_]*) die "deliverable key must be lowercase [a-z0-9_], got '$key'" ;;
+  esac
+  [ "${#DELIVERABLE_VALUES[$i]}" -le 512 ] \
+    || die "deliverable '$key' exceeds 512 characters"
+  case "${DELIVERABLE_VALUES[$i]}" in
+    *[[:cntrl:]]*) die "deliverable '$key' must be single-line text with no control characters" ;;
+  esac
+  i=$((i + 1))
+done
+
+# Resolve the owning home to a real absolute directory before composing any path
+# under it, so a relative or symlinked argument cannot make the destination
+# ambiguous in a later message or write.
+case "$HOME_DIR" in
+  /*) ;;
+  *) HOME_DIR=$(CDPATH='' cd -- "$HOME_DIR" 2>/dev/null && pwd -P) \
+       || die "--home is not a reachable directory: $1" ;;
+esac
+[ -d "$HOME_DIR" ] && [ ! -L "$HOME_DIR" ] \
+  || die "--home must name an existing directory, got '$HOME_DIR'"
+
+fm_pf_relay_active "$HOME_DIR" || exit 0
+command -v jq >/dev/null 2>&1 || die "jq is required to build a typed terminal event" 1
+
+STATE="$HOME_DIR/state"
+REGISTRY="$(fm_pf_registry_dir "$STATE")/$OBLIGATION"
+if [ ! -f "$REGISTRY" ] || [ -L "$REGISTRY" ]; then
+  die "home '$HOME_DIR' has no public-followup registration for '$OBLIGATION'; the owning home registers a commitment before its work can report one" 1
+fi
+
+# The registration is the owning home's own record of what it bound, so checking
+# the identity tuple against it catches a mis-briefed worker at the edge with a
+# clear message. tasks-axi still re-validates everything at consume time and
+# remains the authority; this is a cheap early refusal, not a second gatekeeper.
+reg_mismatch() {
+  local field=$1 expected=$2 got=$3
+  [ -z "$expected" ] || [ "$expected" = "$got" ] \
+    || die "event $field '$got' does not match this home's registration ('$expected')"
+}
+reg_mismatch relation   "$(fm_pf_registry_get "$STATE" "$OBLIGATION" relation_id)" "$RELATION"
+reg_mismatch source-home "$(fm_pf_registry_get "$STATE" "$OBLIGATION" work_home)"  "$SOURCE_HOME"
+reg_mismatch work-id    "$(fm_pf_registry_get "$STATE" "$OBLIGATION" work_id)"     "$WORK_ID"
+reg_mismatch generation "$(fm_pf_registry_get "$STATE" "$OBLIGATION" generation)"  "$GENERATION"
+
+case "$TEXT_MODE" in
+  inline) OUTCOME_TEXT=$(printf '%s' "$TEXT_SOURCE" | fm_pf_clean_outcome_text) ;;
+  file)
+    if [ "$TEXT_SOURCE" = '-' ]; then
+      OUTCOME_TEXT=$(fm_pf_clean_outcome_text)
+    else
+      [ -f "$TEXT_SOURCE" ] || die "outcome text file not found: $TEXT_SOURCE"
+      OUTCOME_TEXT=$(fm_pf_clean_outcome_text < "$TEXT_SOURCE")
+    fi
+    ;;
+esac
+[ -n "$OUTCOME_TEXT" ] || die "outcome text is empty once whitespace and control characters are removed"
+
+# Canonical deliverables object: sorted keys, compact, so the same deliverables
+# always hash to the same identity regardless of flag order.
+DELIVERABLES_JSON=$(
+  {
+    i=0
+    while [ "$i" -lt "${#DELIVERABLE_KEYS[@]}" ]; do
+      printf '%s\n%s\n' "${DELIVERABLE_KEYS[$i]}" "${DELIVERABLE_VALUES[$i]}"
+      i=$((i + 1))
+    done
+  } | jq -Rsc 'split("\n") | .[:-1] | [range(0; length; 2) as $i | {key: .[$i], value: .[$i+1]}] | from_entries | to_entries | sort_by(.key) | from_entries'
+) || die "could not encode deliverables" 1
+
+EVENT_ID=$(fm_pf_event_id \
+  "$OBLIGATION" "$RELATION" "$SOURCE_HOME" "$WORK_ID" "$GENERATION" "$OUTCOME" \
+  "$DELIVERABLES_JSON") || die "sha256 (shasum or sha256sum) is required" 1
+# The derived id becomes a filename, so require the exact digest shape rather
+# than trusting whatever the hashing tool printed.
+case "$EVENT_ID" in
+  *[!0-9a-f]*|'') die "could not derive a usable event id" 1 ;;
+esac
+[ "${#EVENT_ID}" -eq 64 ] || die "could not derive a usable event id" 1
+
+# jq bounds the outcome text by codepoint, so a long or non-ASCII sentence is
+# capped without ever splitting a multi-byte character.
+EVENT_JSON=$(jq -Sc -n \
+  --argjson schema_version "$FM_PF_EVENT_SCHEMA_VERSION" \
+  --arg event_id "$EVENT_ID" \
+  --arg obligation_id "$OBLIGATION" \
+  --arg relation_id "$RELATION" \
+  --arg work_id "$WORK_ID" \
+  --argjson generation "$GENERATION" \
+  --arg source_home_id "$SOURCE_HOME" \
+  --arg outcome_type "$OUTCOME" \
+  --argjson deliverables "$DELIVERABLES_JSON" \
+  --arg public_safe_outcome "$OUTCOME_TEXT" \
+  --argjson outcome_max "$FM_PF_OUTCOME_TEXT_MAX" \
+  --arg occurred_at "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+  '{schema_version:$schema_version, event_id:$event_id, obligation_id:$obligation_id,
+    relation_id:$relation_id, work_id:$work_id, generation:$generation,
+    source_home_id:$source_home_id, outcome_type:$outcome_type,
+    deliverables:$deliverables,
+    public_safe_outcome:($public_safe_outcome[0:$outcome_max]),
+    occurred_at:$occurred_at, successor:null}') \
+  || die "could not build the typed terminal event" 1
+
+EVENT_BYTES=$(printf '%s\n' "$EVENT_JSON" | LC_ALL=C wc -c | tr -d ' ') \
+  || die "could not measure the typed terminal event" 1
+[ "$EVENT_BYTES" -le "$FM_PF_EVENT_BYTES_MAX" ] \
+  || die "typed terminal event exceeds $FM_PF_EVENT_BYTES_MAX bytes" 2
+
+printf '%s\n' "$EVENT_JSON" \
+  | fmx_private_artifact_publish_stdin_once "$(fm_pf_events_dir "$STATE")" "$EVENT_ID.json" 600
+case $? in
+  0|1) printf '%s\n' "$EVENT_ID" ;;
+  *) die "could not publish the terminal event into $HOME_DIR" 1 ;;
+esac

package/.agents/backend/fm-public-followup-lib.sh

@@ -0,0 +1,398 @@
+# shellcheck shell=bash
+# fm-public-followup-lib.sh - shared gating and private-transport helpers for the
+# deterministic public-followup consumer.
+#
+# Firstmate promises a public final reply when a myfirstmate relay mention (X or
+# Discord) asks for work. `tasks-axi public-followup` is the sole owner of that
+# typed obligation and its state machine; state/x-context/ is the sole owner of
+# the private full request context. This library owns Firstmate's activation
+# gate, private per-home transport paths, retained-loop state and locking
+# helpers, follow-up window classification, and deterministic terminal-event
+# identity.
+#
+# Sourced, never executed. No side effects on source (it creates nothing), which
+# is what keeps a relay-disabled home free of public-followup artifacts.
+# set -u / set -e safe.
+#
+# GATE ORDER - the acceptance criterion for relay-disabled homes:
+#   1. fm_pf_relay_active <home>     the authoritative myfirstmate activation
+#                                    contract, a non-empty FMX_PAIRING_TOKEN in
+#                                    <home>/.env. There is no second flag. When
+#                                    <home>/.env is absent this is a single
+#                                    [ -f ] test and nothing else runs.
+#   2. fm_pf_has_registrations       O(1) presence check on the registry created
+#      / fm_pf_has_events            only by the relay path (fm-public-followup.sh
+#      / fm_pf_has_open_loops        register). Open loops ARE registrations:
+#                                    a delivered final keeps the record, so this
+#                                    same check is the fail-loud session-start
+#                                    gate. Relay-enabled homes with no public
+#                                    loops stop here, so no tasks-axi call and
+#                                    no backlog scan happens.
+#
+# Private transport layout, all under <home>/state/public-followup (mode 0700,
+# initialized by `fm-public-followup.sh register` and extended only by these
+# public-followup commands):
+#   registry/<obligation-id>   registration record: the bounded private binding
+#                              (obligation, relation, work ref and canonical
+#                              secondmate path, generation, platform, request id)
+#                              plus the loop fields that survive delivery (state,
+#                              delivered_at, followup_expires_at,
+#                              request_context_b64). Presence means the public
+#                              loop is still open. Delivery
+#                              stamps state=delivered; only `retire` removes the
+#                              record. The obligation itself always remains
+#                              tasks-axi truth.
+#   events/<event-id>.json     inbound typed terminal events awaiting
+#                              reconciliation, one file per event id.
+#   consumed/<event-id>        idempotency ledger: an accepted event id is never
+#                              replayed, so duplicate emits and restart replay
+#                              are no-ops.
+#   rejected/<event-id>.json   events tasks-axi refused, kept with a
+#   rejected/<event-id>.reason one-line reason so a refusal is inspectable and
+#                              never retried in a loop.
+#   surfaced                   last surfaced pending-event signature, so the
+#                              existing relay poll wakes once per new event set
+#                              instead of every cycle.
+#   retired/<obligation-id>    private retirement receipt containing the bounded
+#                              reason and timestamp recorded before the registry
+#                              entry is removed; its presence prevents replayed
+#                              registration from reopening the closed loop.
+#
+# Event identity is DERIVED, never random: fm_pf_event_id hashes the canonical
+# identity tuple, so re-emitting the same terminal result produces the same
+# event id and the same destination path. Idempotency therefore holds across
+# retries, restarts, and duplicate child reports without any coordination.
+#
+# Depends on bin/fm-x-lib.sh for .env reading and the private-artifact
+# publication primitives (atomic, single-link, mode-validated, non-executable);
+# those remain that file's contract and are not restated here.
+
+_FM_PF_LIB_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd 2>/dev/null)" || _FM_PF_LIB_DIR="."
+# shellcheck source=bin/fm-x-lib.sh
+. "$_FM_PF_LIB_DIR/fm-x-lib.sh"
+
+FM_PF_DIRNAME='public-followup'
+# Consumed by the sourcing scripts, not by this library.
+# shellcheck disable=SC2034
+FM_PF_EVENT_SCHEMA_VERSION=1
+# Bounded so a public-safe outcome line can never carry a raw public message,
+# and so one event file stays small enough to read and validate cheaply.
+FM_PF_OUTCOME_TEXT_MAX=${FM_PF_OUTCOME_TEXT_MAX:-600}
+FM_PF_EVENT_BYTES_MAX=${FM_PF_EVENT_BYTES_MAX:-8192}
+
+# --- gate 1: the authoritative relay activation contract --------------------
+
+# fm_pf_relay_active <home>: 0 when this home has opted into the myfirstmate
+# relay, 1 otherwise. Identical contract to bootstrap's X-mode activation - a
+# non-empty FMX_PAIRING_TOKEN in <home>/.env - so no second activation flag
+# exists to drift. FMX_PAIRING_TOKEN in the environment wins, matching
+# fmx_load_config, so a direct client call and this gate agree.
+fm_pf_relay_active() {
+  local home=$1 token
+  if [ -n "${FMX_PAIRING_TOKEN+x}" ]; then
+    [ -n "${FMX_PAIRING_TOKEN-}" ]
+    return $?
+  fi
+  [ -f "$home/.env" ] || return 1
+  token=$(fmx_env_get FMX_PAIRING_TOKEN "$home/.env")
+  [ -n "$token" ]
+}
+
+# --- gate 2: O(1) presence checks on relay-path-owned registrations ---------
+
+fm_pf_root()       { printf '%s\n' "$1/$FM_PF_DIRNAME"; }
+fm_pf_registry_dir() { printf '%s\n' "$1/$FM_PF_DIRNAME/registry"; }
+fm_pf_events_dir()   { printf '%s\n' "$1/$FM_PF_DIRNAME/events"; }
+fm_pf_consumed_dir() { printf '%s\n' "$1/$FM_PF_DIRNAME/consumed"; }
+fm_pf_rejected_dir() { printf '%s\n' "$1/$FM_PF_DIRNAME/rejected"; }
+fm_pf_retired_dir()  { printf '%s\n' "$1/$FM_PF_DIRNAME/retired"; }
+
+fm_pf_retirement_receipt_exists() {
+  local file
+  file="$(fm_pf_retired_dir "$1")/$2"
+  [ -f "$file" ] && [ ! -L "$file" ]
+}
+
+# fm_pf_dir_has_entry <dir>: 0 when <dir> is a real directory holding at least
+# one non-dot entry. Stops at the first hit, so cost does not grow with the
+# directory's size.
+fm_pf_dir_has_entry() {
+  local dir=$1 entry
+  [ -d "$dir" ] && [ ! -L "$dir" ] || return 1
+  for entry in "$dir"/*; do
+    [ -e "$entry" ] || continue
+    return 0
+  done
+  return 1
+}
+
+fm_pf_has_registrations() { fm_pf_dir_has_entry "$(fm_pf_registry_dir "$1")"; }
+fm_pf_has_events()        { fm_pf_dir_has_entry "$(fm_pf_events_dir "$1")"; }
+# Every retained registration is an open public loop (owed or delivered). Same
+# O(1) directory presence check as fm_pf_has_registrations; the name is the
+# post-retention semantic so callers do not treat "a reply is owed" as the
+# only reason a record exists.
+fm_pf_has_open_loops()    { fm_pf_has_registrations "$1"; }
+
+# fm_pf_active <home> <state>: both gates, in order. The single predicate every
+# caller outside the relay path should use before doing any public-followup work.
+fm_pf_active() {
+  fm_pf_relay_active "$1" || return 1
+  fm_pf_has_registrations "$2" || fm_pf_has_events "$2"
+}
+
+# --- identifiers ------------------------------------------------------------
+
+# fm_pf_slug_valid <value>: obligation ids, relation ids, work ids, and request
+# ids all compose filenames. They arrive from tasks-axi, the relay, and child
+# homes, so every one is checked against a conservative slug before use.
+fm_pf_slug_valid() {
+  local v=$1
+  case "$v" in
+    ''|.*|*[!A-Za-z0-9._-]*) return 1 ;;
+  esac
+  [ "${#v}" -le 128 ]
+}
+
+# fm_pf_home_id_valid <home_id>: tasks-axi accepts "main" or
+# "secondmate:<stable-id>" as a work_ref home. Validate the same shape here so a
+# malformed source home is refused before it reaches a filename or a CLI call.
+fm_pf_home_id_valid() {
+  local v=$1
+  case "$v" in
+    main) return 0 ;;
+    secondmate:*) fm_pf_slug_valid "${v#secondmate:}" ;;
+    *) return 1 ;;
+  esac
+}
+
+fm_pf_sha256() {
+  if command -v shasum >/dev/null 2>&1; then
+    shasum -a 256 2>/dev/null | awk '{print $1}'
+  elif command -v sha256sum >/dev/null 2>&1; then
+    sha256sum 2>/dev/null | awk '{print $1}'
+  else
+    return 1
+  fi
+}
+
+# fm_pf_event_id <obligation> <relation> <source_home> <work_id> <generation>
+#                <outcome_type> <deliverables-canonical>
+# The stable idempotency identity. Derived from the identity tuple only, so the
+# same terminal result always yields the same id no matter who emits it or how
+# often. Public-safe outcome text is deliberately excluded: rewording the same
+# landed outcome must not create a second event.
+fm_pf_event_id() {
+  printf '%s\037%s\037%s\037%s\037%s\037%s\037%s' "$1" "$2" "$3" "$4" "$5" "$6" "$7" \
+    | fm_pf_sha256
+}
+
+# --- bounded public-safe text ----------------------------------------------
+
+# fm_pf_clean_outcome_text: read stdin, drop control characters, collapse every
+# whitespace run to a single space, and trim. An event line therefore stays
+# single-line and a raw pasted public message cannot ride along inside it.
+# Deliberately does NOT truncate: a byte-wise cut would split a multi-byte
+# character, so length bounding happens where it can count codepoints - jq, at
+# the point the typed event is built.
+fm_pf_clean_outcome_text() {
+  LC_ALL=C tr -d '\000-\010\013\014\016-\037\177' \
+    | LC_ALL=C tr '\011\012\015' '   ' \
+    | LC_ALL=C tr -s ' ' \
+    | sed 's/^ //; s/ $//'
+}
+
+# fm_pf_bound_bytes <max>: hard byte cap for text that never becomes JSON, such
+# as a quarantined event's one-line refusal reason.
+fm_pf_bound_bytes() {
+  LC_ALL=C cut -b "1-$1"
+}
+
+# --- registry records -------------------------------------------------------
+
+# fm_pf_registry_get <state> <obligation-id> <key>: read one key=value line from
+# a registration record. Prints nothing and succeeds when absent.
+fm_pf_registry_get() {
+  local state=$1 id=$2 key=$3 file line
+  fm_pf_slug_valid "$id" || return 1
+  file="$(fm_pf_registry_dir "$state")/$id"
+  [ -f "$file" ] && [ ! -L "$file" ] || return 0
+  line=$(grep -E "^${key}=" "$file" 2>/dev/null | tail -n1) || return 0
+  printf '%s' "${line#*=}"
+}
+
+# fm_pf_registry_ids <state>: every registered obligation id, one per line.
+# The registry only ever holds this home's live public commitments, so this stays
+# a bounded listing rather than a backlog scan.
+fm_pf_registry_ids() {
+  local dir entry
+  dir=$(fm_pf_registry_dir "$1")
+  [ -d "$dir" ] && [ ! -L "$dir" ] || return 0
+  for entry in "$dir"/*; do
+    [ -f "$entry" ] && [ ! -L "$entry" ] || continue
+    basename "$entry"
+  done
+}
+
+# fm_pf_registry_ids_for_work <state> <work_home_id> <work_id>: the obligations
+# this home registered against one exact work relation. Used by the completion
+# guard so cleanup cannot declare bound work finished while its public promise is
+# still open.
+fm_pf_registry_ids_for_work() {
+  local state=$1 home_id=$2 work_id=$3 id
+  while IFS= read -r id; do
+    [ -n "$id" ] || continue
+    [ "$(fm_pf_registry_get "$state" "$id" work_home)" = "$home_id" ] || continue
+    [ "$(fm_pf_registry_get "$state" "$id" work_id)" = "$work_id" ] || continue
+    printf '%s\n' "$id"
+  done <<EOF
+$(fm_pf_registry_ids "$state")
+EOF
+}
+
+# fm_pf_now_epoch: wall clock as epoch seconds. FMX_NOW_OVERRIDE pins it for
+# tests, matching bin/fm-x-lib.sh.
+fm_pf_now_epoch() {
+  printf '%s\n' "${FMX_NOW_OVERRIDE:-$(date +%s)}"
+}
+
+# fm_pf_now_rfc3339: UTC timestamp for delivered_at and similar stamps.
+fm_pf_now_rfc3339() {
+  local epoch
+  epoch=$(fm_pf_now_epoch)
+  date -u -r "$epoch" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null \
+    || date -u -d "@$epoch" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null \
+    || date -u +%Y-%m-%dT%H:%M:%SZ
+}
+
+# fm_pf_rfc3339_to_epoch <rfc3339>: parse a Zulu timestamp. Empty on failure.
+fm_pf_rfc3339_to_epoch() {
+  local ts=$1
+  [ -n "$ts" ] || return 1
+  date -u -j -f '%Y-%m-%dT%H:%M:%SZ' "$ts" +%s 2>/dev/null \
+    || date -u -d "$ts" +%s 2>/dev/null \
+    || return 1
+}
+
+# fm_pf_followup_window_class <rfc3339>: ok, closing (<48h), expired, or unknown.
+fm_pf_followup_window_class() {
+  local ts=$1 exp now
+  exp=$(fm_pf_rfc3339_to_epoch "$ts") || { printf 'unknown\n'; return 0; }
+  now=$(fm_pf_now_epoch)
+  if [ "$now" -ge "$exp" ]; then
+    printf 'expired\n'
+  elif [ $((exp - now)) -lt 172800 ]; then
+    printf 'closing\n'
+  else
+    printf 'ok\n'
+  fi
+}
+
+# fm_pf_b64_encode: stdin to a single-line base64 payload (no wrapping).
+fm_pf_b64_encode() {
+  base64 2>/dev/null | tr -d '\n\r'
+}
+
+# fm_pf_b64_decode: stdin (single-line or wrapped base64) to bytes on stdout.
+fm_pf_b64_decode() {
+  local data
+  data=$(cat)
+  printf '%s\n' "$data" | base64 -d 2>/dev/null \
+    || printf '%s\n' "$data" | base64 -D 2>/dev/null
+}
+
+# fm_pf_registry_loop_state <state> <id>: open or delivered. A pre-change
+# record with no state= is treated as open so live homes never crash.
+fm_pf_registry_loop_state() {
+  local v
+  v=$(fm_pf_registry_get "$1" "$2" state)
+  case "$v" in
+    delivered) printf 'delivered\n' ;;
+    *) printf 'open\n' ;;
+  esac
+}
+
+# fm_pf_registry_rechainable <state> <id>: 0 when request_context_b64 is present.
+fm_pf_registry_rechainable() {
+  local ctx
+  ctx=$(fm_pf_registry_get "$1" "$2" request_context_b64)
+  [ -n "$ctx" ]
+}
+
+# fm_pf_has_delivered_open_loops <state>: 0 when any retained record is
+# state=delivered (an open loop with nothing owed). Pre-change records have no
+# state= and are treated as still-owed, not delivered.
+fm_pf_has_delivered_open_loops() {
+  local state=$1 id
+  while IFS= read -r id; do
+    [ -n "$id" ] || continue
+    [ "$(fm_pf_registry_get "$state" "$id" state)" = delivered ] || continue
+    return 0
+  done <<EOF
+$(fm_pf_registry_ids "$state")
+EOF
+  return 1
+}
+
+fm_pf_registry_lock_path() {
+  printf '%s/.registry-%s.lock\n' "$(fm_pf_root "$1")" "$2"
+}
+
+fm_pf_registry_lock_acquire() {
+  local state=$1 id=$2
+  fm_pf_slug_valid "$id" || return 1
+  fmx_private_artifact_dir_prepare "$(fm_pf_root "$state")" >/dev/null || return 1
+  if ! command -v fm_lock_acquire_wait >/dev/null 2>&1; then
+    # shellcheck source=bin/fm-wake-lib.sh
+    . "$_FM_PF_LIB_DIR/fm-wake-lib.sh"
+  fi
+  fm_lock_acquire_wait "$(fm_pf_registry_lock_path "$state" "$id")"
+}
+
+fm_pf_registry_lock_release() {
+  fm_lock_release "$(fm_pf_registry_lock_path "$1" "$2")"
+}
+
+# fm_pf_registry_stamp_delivered <state> <id> <rfc3339>: rewrite one record
+# with state=delivered and delivered_at, keeping every other field. The record
+# stays; only retire removes it.
+fm_pf_registry_stamp_delivered() {
+  local state=$1 id=$2 delivered_at=$3 file rest rc=0
+  fm_pf_slug_valid "$id" || return 1
+  [ -n "$delivered_at" ] || return 1
+  fm_pf_registry_lock_acquire "$state" "$id" || return 1
+  file="$(fm_pf_registry_dir "$state")/$id"
+  if [ -f "$file" ] && [ ! -L "$file" ]; then
+    rest=$(grep -v -E '^(state|delivered_at|delivered_obligation)=' "$file" 2>/dev/null || true)
+    printf '%s\nstate=delivered\ndelivered_at=%s\ndelivered_obligation=%s\n' \
+      "$rest" "$delivered_at" "$id" \
+      | fmx_private_artifact_publish_stdin "$(fm_pf_registry_dir "$state")" "$id" 600 \
+      || rc=$?
+  else
+    rc=3
+  fi
+  fm_pf_registry_lock_release "$state" "$id"
+  return "$rc"
+}
+
+# --- pending-event signature ------------------------------------------------
+
+# Consumed by the sourcing scripts, not by this library.
+# shellcheck disable=SC2034
+FM_PF_SURFACED_BASENAME=surfaced
+
+# fm_pf_events_signature <state>: a stable digest of the pending event id set.
+# The relay poll compares it against the surfaced record so an unconsumed event
+# wakes firstmate once per new event, not once per poll cycle.
+fm_pf_events_signature() {
+  local dir entry pending_names=
+  dir=$(fm_pf_events_dir "$1")
+  [ -d "$dir" ] && [ ! -L "$dir" ] || return 1
+  for entry in "$dir"/*.json; do
+    [ -f "$entry" ] && [ ! -L "$entry" ] || continue
+    pending_names="$pending_names$(basename "$entry")
+"
+  done
+  [ -n "$pending_names" ] || return 1
+  printf '%s' "$pending_names" | LC_ALL=C sort | fm_pf_sha256
+}