@zerwiz/ymir 0.1.3 → 0.1.5

package/.agents/backend/fm-install-treehouse.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# fm-install-treehouse.sh - install CI's pinned, verified Treehouse build.
+#
+# Used only by the required real-Herdr CI lane for E2E scripts that genuinely
+# need treehouse (spawn worktree acquisition). Same pin/checksum discipline as
+# fm-install-herdr.sh: official release URL, exact asset, SHA-256, bounded
+# download, post-install version check. Never a floating package-manager latest.
+#
+# Usage:
+#   fm-install-treehouse.sh <destination-directory>
+#
+# Pins Treehouse v2.0.1, the version exercised by the local real-Herdr suite.
+set -eu
+
+FM_TREEHOUSE_CI_VERSION=2.0.1
+FM_TREEHOUSE_CI_TAG="v${FM_TREEHOUSE_CI_VERSION}"
+# Bounded download ceiling (bytes). Official 2.0.1 archives are under 8 MiB.
+FM_TREEHOUSE_CI_MAX_BYTES=15000000
+FM_TREEHOUSE_CI_REPO=kunchenguid/treehouse
+
+die() {
+  printf 'fm-install-treehouse.sh: %s\n' "$*" >&2
+  exit 1
+}
+
+DESTINATION=${1:?usage: fm-install-treehouse.sh <destination-directory>}
+
+os=$(uname -s)
+arch=$(uname -m)
+case "${os}-${arch}" in
+  Linux-x86_64)
+    ARCHIVE=treehouse-v${FM_TREEHOUSE_CI_VERSION}-linux-amd64.tar.gz
+    SHA256=1d5a32751ab921670103fd201ddb2b91b47338cb13976f45642b827cf8976af2
+    ;;
+  Linux-aarch64|Linux-arm64)
+    ARCHIVE=treehouse-v${FM_TREEHOUSE_CI_VERSION}-linux-arm64.tar.gz
+    SHA256=eaccc9c5b98125df8bd77425598eeecee66cb0371db4eb1cf75f0d813c18fab9
+    ;;
+  Darwin-arm64)
+    ARCHIVE=treehouse-v${FM_TREEHOUSE_CI_VERSION}-darwin-arm64.tar.gz
+    SHA256=7ee5078f3d1f33c01196548797fce65408e459d53530b77d4ba56e074fa1c1a2
+    ;;
+  Darwin-x86_64)
+    ARCHIVE=treehouse-v${FM_TREEHOUSE_CI_VERSION}-darwin-amd64.tar.gz
+    SHA256=1cf44580a5837f995e1d3bb74f4fbd3112b642acd20406087d9735a8106112fd
+    ;;
+  *)
+    die "unsupported platform ${os}-${arch}; official Treehouse assets are linux/darwin amd64 and arm64"
+    ;;
+esac
+
+URL="https://github.com/${FM_TREEHOUSE_CI_REPO}/releases/download/${FM_TREEHOUSE_CI_TAG}/${ARCHIVE}"
+TMP=$(mktemp -d "${RUNNER_TEMP:-${TMPDIR:-/tmp}}/fm-treehouse.XXXXXX")
+trap 'rm -rf "$TMP"' EXIT
+
+printf 'fm-install-treehouse.sh: downloading %s from %s\n' "$ARCHIVE" "$URL" >&2
+curl -fsSL --max-filesize "$FM_TREEHOUSE_CI_MAX_BYTES" "$URL" -o "$TMP/$ARCHIVE" \
+  || die "download failed for $URL (bounded at $FM_TREEHOUSE_CI_MAX_BYTES bytes)"
+
+if command -v sha256sum >/dev/null 2>&1; then
+  ACTUAL_SHA256=$(sha256sum "$TMP/$ARCHIVE" | awk '{print $1}')
+elif command -v shasum >/dev/null 2>&1; then
+  ACTUAL_SHA256=$(shasum -a 256 "$TMP/$ARCHIVE" | awk '{print $1}')
+else
+  die "need sha256sum or shasum to verify the Treehouse archive"
+fi
+
+[ "$ACTUAL_SHA256" = "$SHA256" ] || die "checksum mismatch for $ARCHIVE (expected $SHA256, got $ACTUAL_SHA256)"
+
+tar -xzf "$TMP/$ARCHIVE" -C "$TMP"
+# Archive layout: a single `treehouse` binary at the archive root (verified for v2.0.1).
+if [ -f "$TMP/treehouse" ]; then
+  BIN="$TMP/treehouse"
+elif [ -f "$TMP/treehouse-v${FM_TREEHOUSE_CI_VERSION}/treehouse" ]; then
+  BIN="$TMP/treehouse-v${FM_TREEHOUSE_CI_VERSION}/treehouse"
+else
+  BIN=$(find "$TMP" -type f -name treehouse | head -n 1)
+  [ -n "$BIN" ] || die "archive $ARCHIVE did not contain a treehouse binary"
+fi
+
+mkdir -p "$DESTINATION"
+install -m 0755 "$BIN" "$DESTINATION/treehouse"
+
+installed_version=$("$DESTINATION/treehouse" --version 2>/dev/null | tr -d '[:space:]')
+# treehouse prints "v2.0.1" (leading v) on --version.
+case "$installed_version" in
+  "v${FM_TREEHOUSE_CI_VERSION}"|"${FM_TREEHOUSE_CI_VERSION}") ;;
+  *)
+    die "installed treehouse version is '${installed_version:-<empty>}', expected exact pin v${FM_TREEHOUSE_CI_VERSION}"
+    ;;
+esac
+
+printf 'fm-install-treehouse.sh: installed treehouse %s to %s\n' \
+  "$installed_version" "$DESTINATION/treehouse" >&2
+"$DESTINATION/treehouse" --version

package/.agents/backend/fm-kimi-turnend-hook.sh

@@ -0,0 +1,276 @@
+#!/usr/bin/env bash
+# Install or remove Firstmate's guarded Kimi crew turn-end hook.
+#
+# This command is the sole owner of the text-level edit to
+# $HOME/.kimi-code/config.toml. It validates the existing TOML but never
+# serializes it: install adds or replaces one marker-delimited Firstmate region,
+# and remove excises only that region. Missing, malformed, symlinked, partially
+# marked, or otherwise surprising config is refused without a config write.
+#
+# The installed Stop hook always exits 0 and stays silent. It reads cwd from the
+# hook payload, checks for a .fm-kimi-turnend pointer before registry work, and
+# touches a task turn-end marker only when the pointer names a Firstmate-created
+# token in $HOME/.kimi-code/fm-turn-end.d/.
+#
+# Usage:
+#   fm-kimi-turnend-hook.sh install
+#   fm-kimi-turnend-hook.sh remove
+set -u
+
+case "${1:-}" in
+  install|remove) ACTION=$1 ;;
+  -h|--help)
+    sed -n '2,18{s/^# \{0,1\}//;p;}' "$0"
+    exit 0
+    ;;
+  *)
+    printf 'usage: %s install|remove\n' "${0##*/}" >&2
+    exit 2
+    ;;
+esac
+
+if [ -z "${HOME:-}" ]; then
+  printf 'fm-kimi-turnend-hook: refused: HOME is unset.\n' >&2
+  exit 1
+fi
+if ! command -v python3 >/dev/null 2>&1; then
+  printf 'fm-kimi-turnend-hook: refused: python3 with tomllib is required to validate config.toml.\n' >&2
+  exit 1
+fi
+if [ "$ACTION" = install ] && ! command -v jq >/dev/null 2>&1; then
+  printf 'fm-kimi-turnend-hook: refused: jq is required by the installed Kimi turn-end hook.\n' >&2
+  exit 1
+fi
+
+python3 - "$ACTION" "$HOME/.kimi-code" <<'PY'
+import os
+import re
+import shutil
+import stat
+import sys
+import tempfile
+
+try:
+    import tomllib
+except ImportError:
+    print(
+        "fm-kimi-turnend-hook: refused: python3 with tomllib is required to validate config.toml.",
+        file=sys.stderr,
+    )
+    raise SystemExit(1)
+
+ACTION = sys.argv[1]
+CONFIG_DIR = sys.argv[2]
+CONFIG = os.path.join(CONFIG_DIR, "config.toml")
+HOOK = os.path.join(CONFIG_DIR, "fm-turn-end.sh")
+REGISTRY = os.path.join(CONFIG_DIR, "fm-turn-end.d")
+BEGIN = b"# BEGIN FIRSTMATE KIMI TURN-END HOOK"
+BEGIN_OWNS_NEWLINE = BEGIN + b" (OWNS PRECEDING NEWLINE)"
+END = b"# END FIRSTMATE KIMI TURN-END HOOK"
+IDENTIFIER = b"FIRSTMATE KIMI TURN-END HOOK"
+HOOK_NAME = b"fm-turn-end.sh"
+TOKEN_NAME = re.compile(r"fm\.[A-Za-z0-9]{12}\Z")
+
+HOOK_BYTES = b'''#!/usr/bin/env bash
+# Firstmate Kimi turn-end hook. Managed by fm-kimi-turnend-hook.sh.
+# This hook is deliberately passive: every path is silent and exits zero.
+set +e
+exec >/dev/null 2>&1
+payload=
+IFS= read -r payload || [ -n "$payload" ] || exit 0
+command -v jq >/dev/null 2>&1 || exit 0
+workspace=$(jq -er 'select(.hook_event_name == "Stop") | .cwd | strings | select(length > 0)' <<< "$payload" 2>/dev/null) || exit 0
+pointer="$workspace/.fm-kimi-turnend"
+[ -f "$pointer" ] || exit 0
+first=
+IFS= read -r -n 256 first < "$pointer" 2>/dev/null || [ -n "$first" ] || exit 0
+case "$first" in token=*) token=${first#token=} ;; *) exit 0 ;; esac
+case "$token" in fm.????????????) : ;; *) exit 0 ;; esac
+case "$token" in *[!A-Za-z0-9._-]*) exit 0 ;; esac
+auth_dir=${HOME:-}/.kimi-code/fm-turn-end.d
+[ -n "${HOME:-}" ] || exit 0
+target=$(cat "$auth_dir/$token" 2>/dev/null) || exit 0
+case "$target" in /*.turn-ended) : ;; *) exit 0 ;; esac
+touch -- "$target" 2>/dev/null || true
+exit 0
+'''
+
+
+def refuse(reason: str) -> None:
+    print(f"fm-kimi-turnend-hook: refused: {reason}", file=sys.stderr)
+    raise SystemExit(1)
+
+
+def regular_not_symlink(path: str, label: str) -> os.stat_result:
+    try:
+        info = os.lstat(path)
+    except FileNotFoundError:
+        refuse(f"{label} is missing at {path}.")
+    if stat.S_ISLNK(info.st_mode) or not stat.S_ISREG(info.st_mode):
+        refuse(f"{label} is not a regular non-symlink file at {path}.")
+    return info
+
+
+def parse_toml(data: bytes, label: str):
+    try:
+        text = data.decode("utf-8")
+    except UnicodeDecodeError as error:
+        refuse(f"{label} is not UTF-8: {error}.")
+    try:
+        parsed = tomllib.loads(text)
+    except tomllib.TOMLDecodeError as error:
+        refuse(f"{label} is malformed TOML: {error}.")
+    hooks = parsed.get("hooks")
+    if hooks is not None and not isinstance(hooks, list):
+        refuse(f"{label} has an unexpected non-array 'hooks' value.")
+    return parsed
+
+
+def locate_region(data: bytes):
+    normal_count = data.count(BEGIN + b"\n")
+    owned_count = data.count(BEGIN_OWNS_NEWLINE + b"\n")
+    end_count = data.count(END)
+    identifier_count = data.count(IDENTIFIER)
+    if normal_count + owned_count == 0 and end_count == 0 and identifier_count == 0:
+        return None
+    if normal_count + owned_count != 1 or end_count != 1 or identifier_count != 2:
+        refuse("config.toml has partial, duplicated, or altered Firstmate region markers.")
+    marker = BEGIN_OWNS_NEWLINE if owned_count else BEGIN
+    marker_at = data.find(marker)
+    if marker_at != 0 and data[marker_at - 1 : marker_at] != b"\n":
+        refuse("the Firstmate begin marker is not at a line boundary.")
+    start = marker_at
+    if owned_count:
+        if marker_at == 0 or data[marker_at - 1 : marker_at] != b"\n":
+            refuse("the Firstmate region claims a preceding newline that is absent.")
+        start -= 1
+    end_at = data.find(END, marker_at + len(marker))
+    if end_at < 0:
+        refuse("the Firstmate end marker is missing.")
+    after = end_at + len(END)
+    if after < len(data):
+        if data[after : after + 1] != b"\n":
+            refuse("the Firstmate end marker is not a complete line.")
+        after += 1
+    return start, after, marker
+
+
+def block(marker: bytes) -> bytes:
+    return b"\n".join(
+        (
+            marker,
+            b"[[hooks]]",
+            b'event = "Stop"',
+            b'matcher = "^$"',
+            b'command = "bash \\"$HOME/.kimi-code/fm-turn-end.sh\\" >/dev/null 2>&1 || true"',
+            b"timeout = 1",
+            END,
+            b"",
+        )
+    )
+
+
+def without_region(data: bytes, region) -> bytes:
+    prefix = data[: region[0]]
+    suffix = data[region[1] :]
+    # Retain a newline so removal cannot join the captain's preceding line to content appended after installation.
+    separator = b"\n" if region[2] == BEGIN_OWNS_NEWLINE and suffix else b""
+    return prefix + separator + suffix
+
+
+def atomic_write(path: str, data: bytes, mode: int) -> None:
+    fd, temporary = tempfile.mkstemp(prefix=f".{os.path.basename(path)}.", dir=os.path.dirname(path))
+    try:
+        os.fchmod(fd, mode)
+        with os.fdopen(fd, "wb") as stream:
+            fd = -1
+            stream.write(data)
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.replace(temporary, path)
+    except Exception:
+        if fd >= 0:
+            os.close(fd)
+        try:
+            os.unlink(temporary)
+        except FileNotFoundError:
+            pass
+        raise
+
+
+def validate_firstmate_files_for_remove() -> None:
+    if os.path.lexists(HOOK):
+        info = regular_not_symlink(HOOK, "Firstmate hook script")
+        with open(HOOK, "rb") as stream:
+            if stream.read() != HOOK_BYTES:
+                refuse(f"Firstmate hook script has unexpected content at {HOOK}.")
+        if stat.S_IMODE(info.st_mode) & 0o077:
+            refuse(f"Firstmate hook script has unexpectedly broad permissions at {HOOK}.")
+    if os.path.lexists(REGISTRY):
+        info = os.lstat(REGISTRY)
+        if stat.S_ISLNK(info.st_mode) or not stat.S_ISDIR(info.st_mode):
+            refuse(f"Firstmate registry is not a regular directory at {REGISTRY}.")
+        for name in os.listdir(REGISTRY):
+            path = os.path.join(REGISTRY, name)
+            child = os.lstat(path)
+            if not TOKEN_NAME.fullmatch(name) or stat.S_ISLNK(child.st_mode) or not stat.S_ISREG(child.st_mode):
+                refuse(f"Firstmate registry contains an unexpected entry at {path}.")
+
+
+try:
+    if not os.path.isdir(CONFIG_DIR) or os.path.islink(CONFIG_DIR):
+        refuse(f"Kimi config directory is missing or unexpected at {CONFIG_DIR}.")
+    config_info = regular_not_symlink(CONFIG, "Kimi config")
+    with open(CONFIG, "rb") as stream:
+        original = stream.read()
+    parse_toml(original, "config.toml")
+    region = locate_region(original)
+    outside = original if region is None else without_region(original, region)
+    if HOOK_NAME in outside:
+        refuse("config.toml references fm-turn-end.sh outside the Firstmate-owned region.")
+
+    if ACTION == "install":
+        if os.path.lexists(REGISTRY):
+            info = os.lstat(REGISTRY)
+            if stat.S_ISLNK(info.st_mode) or not stat.S_ISDIR(info.st_mode):
+                refuse(f"Firstmate registry is not a regular directory at {REGISTRY}.")
+        if os.path.lexists(HOOK):
+            regular_not_symlink(HOOK, "Firstmate hook script")
+            with open(HOOK, "rb") as stream:
+                existing_hook = stream.read()
+            if existing_hook != HOOK_BYTES and not existing_hook.startswith(
+                b"#!/usr/bin/env bash\n# Firstmate Kimi turn-end hook."
+            ):
+                refuse(f"Firstmate hook path has unexpected content at {HOOK}.")
+        if region is None:
+            marker = BEGIN if original.endswith(b"\n") else BEGIN_OWNS_NEWLINE
+            addition = block(marker)
+            candidate = original + (b"" if original.endswith(b"\n") else b"\n") + addition
+        else:
+            candidate = original[: region[0]] + (
+                (b"\n" if region[2] == BEGIN_OWNS_NEWLINE else b"") + block(region[2])
+            ) + original[region[1] :]
+        parse_toml(candidate, "updated config.toml")
+        os.makedirs(REGISTRY, mode=0o700, exist_ok=True)
+        os.chmod(REGISTRY, 0o700)
+        installed_hook = None
+        if os.path.exists(HOOK):
+            with open(HOOK, "rb") as stream:
+                installed_hook = stream.read()
+        if installed_hook != HOOK_BYTES or stat.S_IMODE(os.stat(HOOK).st_mode) != 0o700:
+            atomic_write(HOOK, HOOK_BYTES, 0o700)
+        if candidate != original:
+            atomic_write(CONFIG, candidate, stat.S_IMODE(config_info.st_mode))
+    else:
+        validate_firstmate_files_for_remove()
+        candidate = outside
+        parse_toml(candidate, "config.toml after Firstmate region removal")
+        if candidate != original:
+            atomic_write(CONFIG, candidate, stat.S_IMODE(config_info.st_mode))
+        if os.path.lexists(HOOK):
+            os.unlink(HOOK)
+        if os.path.lexists(REGISTRY):
+            shutil.rmtree(REGISTRY)
+except OSError as error:
+    refuse(f"filesystem operation failed: {error}.")
+PY

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

@@ -0,0 +1,218 @@
+#!/usr/bin/env bash
+# fm-lease-lib.sh - the per-task supervision lease contract (one owner).
+#
+# WHY. On the Pi supervision branch (docs/pi-supervision-branch.md), two LLM
+# actors share one firstmate home inside one pi process: MAIN (the captain's
+# chat) and BRANCH (the persistent supervision conversation). Most records have
+# exactly one natural owner, but the overlap set - steering or stopping a
+# worker, post-landing cleanup, backlog status for a task, stuck-worker
+# recovery - could otherwise be mutated by both actors at once. The lease is
+# the merge-conflict analog: a small per-task file saying which actor is
+# changing that task right now, and the mutating entrypoints refuse the other
+# actor while it exists.
+#
+# CONTRACT.
+#   - Lease file: $STATE/.lease-<task>, one line "<actor>\t<pid>\t<epoch>".
+#     Written atomically (temp + ln for claim, temp + mv for a same-actor
+#     refresh), with inspection and mutation serialized by the home-local
+#     lease-command lock; leases never coordinate across firstmate homes.
+#   - Actors: exactly "main" and "branch". The current actor is
+#     $FM_SUPERVISION_ACTOR when set, else "main". The branch's shell gets
+#     FM_SUPERVISION_ACTOR=branch injected deterministically by the Pi branch
+#     extension's bash tool, not by agent memory. Any other value is refused
+#     loudly - an unknown actor is a wiring bug, not a third role.
+#   - Staleness: the recorded pid is the long-lived supervising process (the
+#     session-lock holder, or FM_LEASE_HOLDER_PID - see bin/fm-lease.sh), and
+#     both actors live inside that one pi process, so a dead recorded pid
+#     means the process died; the lease is cleared at the next claim, guard,
+#     or sweep. Liveness requires a Pi calling context plus state/.lock, and
+#     the recorded pid must BE its current holder, so a lease left by an exited
+#     Pi session goes stale even if its pid was recycled by an unrelated
+#     process, and a non-Pi home never honors a leftover Pi lease. A lease held by the
+#     live current session but an abandoned branch conversation is recovered
+#     by the branch extension's generation-activation cleanup.
+#
+# THREAT MODEL (deliberate, captain-decided): these guards are
+# CONFUSED-AGENT-GRADE, the same grade bin/fm-gate-refuse-lib.sh documents
+# for the gate refusal. They stop non-deliberate misuse - the injected actor
+# identity, the loud refusals, and the session-bound staleness make every
+# accidental cross-actor mutation fail loudly. A deliberately forging shell
+# running as the same uid inside the same pi process can evade any in-process
+# discriminator (it can rewrite env, spawn fresh shells, and edit state
+# files), so adversarial-grade separation is explicitly out of scope here and
+# tracked as separate follow-up design work. The branch's shell prelude makes
+# the actor variables readonly (see the Pi branch extension), so an
+# ACCIDENTAL override fails loudly inside the branch's own shell as well.
+#   - Guard semantics (fm_lease_guard): no lease, a same-actor lease, or a
+#     provably stale lease passes; a live lease held by the OTHER actor
+#     refuses with exit FM_LEASE_REFUSE_EXIT. In a Pi supervision context the
+#     guard retains the lease-command lock until fm_lease_guard_release, so the
+#     other actor cannot claim between the check and the guarded mutation. A
+#     home without the current Pi session lock cannot have a live lease, so
+#     the guard is a no-op there - non-Pi behavior is unchanged by construction.
+#   - Role partition (fm_lease_forbid_branch): actions MAIN alone owns -
+#     merging a PR, landing local-only work, spawning workers - refuse the
+#     branch actor outright, lease or no lease.
+#   - "backlog" is a reserved claimable resource name used by the branch
+#     prompt around its own data/backlog.md writes. This is deliberately
+#     branch-side containment only; main's tasks-axi path has no executable
+#     backlog lease guard in this scope.
+#
+# Sourced by bin/fm-send.sh, bin/fm-control.sh, bin/fm-teardown.sh,
+# bin/fm-pr-merge.sh, bin/fm-merge-local.sh, bin/fm-spawn.sh, and
+# bin/fm-lease.sh. Callers must have $STATE resolved before calling. No side
+# effects on source. set -u / set -e safe.
+
+# Distinct from usage errors (2), the gate refusal (3), and fm-send's
+# unconfirmed submit (3): recognizable as "the other supervision actor holds
+# this task right now - retry after the lease clears".
+FM_LEASE_REFUSE_EXIT=6
+FM_LEASE_LIB_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+FM_LEASE_GUARD_LOCK=
+
+fm_lease_lock_helpers() {
+  command -v fm_lock_acquire_wait >/dev/null 2>&1 && return 0
+  # fm-wake-lib.sh is a canonical lint root in its own right and is already
+  # sourced directly by every caller of this lazy fallback; keep this an
+  # analysis boundary so ShellCheck's external-source traversal does not
+  # recursively duplicate that large graph for every lease-lib consumer.
+  # shellcheck source=/dev/null
+  . "$FM_LEASE_LIB_DIR/fm-wake-lib.sh"
+}
+
+# fm_lease_actor: print the current actor after validating it. Returns 1 (with
+# stderr) for an unknown FM_SUPERVISION_ACTOR value.
+fm_lease_actor() {
+  local actor=${FM_SUPERVISION_ACTOR:-main}
+  case "$actor" in
+    main|branch) printf '%s\n' "$actor" ;;
+    *)
+      echo "error: unknown FM_SUPERVISION_ACTOR '$actor' (expected main or branch)" >&2
+      return 1
+      ;;
+  esac
+}
+
+# fm_lease_valid_id <id>: 0 iff the task/resource id is safe to embed in a
+# state filename.
+fm_lease_valid_id() {
+  case "${1:-}" in
+    '' | *[!A-Za-z0-9._-]*) return 1 ;;
+    *) return 0 ;;
+  esac
+}
+
+fm_lease_path() {
+  printf '%s/.lease-%s\n' "$STATE" "$1"
+}
+
+# fm_lease_read <task>: read the lease into FM_LEASE_ACTOR/FM_LEASE_PID/
+# FM_LEASE_EPOCH. Returns 1 when no lease file exists. A malformed lease
+# (unreadable actor or pid) reads as actor "" so callers treat it as stale
+# rather than blocking forever on a torn record.
+fm_lease_read() {
+  local file line
+  file=$(fm_lease_path "$1")
+  FM_LEASE_ACTOR=
+  FM_LEASE_PID=
+  FM_LEASE_EPOCH=
+  [ -e "$file" ] || return 1
+  IFS= read -r line < "$file" 2>/dev/null || line=
+  FM_LEASE_ACTOR=$(printf '%s' "$line" | cut -f1)
+  FM_LEASE_PID=$(printf '%s' "$line" | cut -f2)
+  # shellcheck disable=SC2034 # Consumed by sourcing callers (bin/fm-lease.sh check).
+  FM_LEASE_EPOCH=$(printf '%s' "$line" | cut -f3)
+  case "$FM_LEASE_ACTOR" in
+    main|branch) ;;
+    *) FM_LEASE_ACTOR= ;;
+  esac
+  case "$FM_LEASE_PID" in
+    '' | *[!0-9]*) FM_LEASE_PID= ;;
+  esac
+  return 0
+}
+
+# fm_lease_live <task>: 0 iff a well-formed lease exists in a Pi context, its
+# recorded pid is alive, and that pid IS the current session-lock holder (see
+# the staleness contract above).
+fm_lease_live() {
+  local lock_pid
+  case "${PI_CODING_AGENT:-}:${FM_SUPERVISION_ACTOR:-}" in
+    true:*|*:main|*:branch) ;;
+    *) return 1 ;;
+  esac
+  fm_lease_read "$1" || return 1
+  [ -n "$FM_LEASE_ACTOR" ] || return 1
+  [ -n "$FM_LEASE_PID" ] || return 1
+  kill -0 "$FM_LEASE_PID" 2>/dev/null || return 1
+  lock_pid=$(head -n 1 "$STATE/.lock" 2>/dev/null || true)
+  case "$lock_pid" in ''|0|1|*[!0-9]*) return 1 ;; esac
+  [ "$FM_LEASE_PID" = "$lock_pid" ]
+}
+
+# fm_lease_clear_stale <task>: remove the lease file when it exists but is not
+# live. Silent; never touches a live lease.
+fm_lease_clear_stale() {
+  local file
+  file=$(fm_lease_path "$1")
+  [ -e "$file" ] || return 0
+  fm_lease_live "$1" && return 0
+  rm -f -- "$file"
+}
+
+# fm_lease_guard <task> <action-label>: refuse (exit FM_LEASE_REFUSE_EXIT) when
+# a live lease held by the OTHER actor exists for <task>. In a Pi supervision
+# context, a successful guard retains the command lock across the caller's
+# mutation; the caller must invoke fm_lease_guard_release from its EXIT cleanup.
+# This closes the check/use race with a concurrent claim. Outside Pi, stale
+# records are still cleaned but the lock is released before returning.
+fm_lease_guard() {
+  local task=$1 action=$2 actor lock lease_actor active=0
+  fm_lease_valid_id "$task" || return 0
+  actor=$(fm_lease_actor) || exit "$FM_LEASE_REFUSE_EXIT"
+  case "${PI_CODING_AGENT:-}:${FM_SUPERVISION_ACTOR:-}" in
+    true:*|*:main|*:branch) active=1 ;;
+  esac
+  [ "$active" = 1 ] || [ -e "$(fm_lease_path "$task")" ] || return 0
+  fm_lease_lock_helpers
+  lock="$STATE/.fm-lease-command.lock"
+  # A caller with more than one guarded phase already excludes claims until
+  # its shared cleanup; do not recursively acquire the non-reentrant lock.
+  if [ "$FM_LEASE_GUARD_LOCK" != "$lock" ]; then
+    fm_lock_acquire_wait "$lock"
+    FM_LEASE_GUARD_LOCK=$lock
+  fi
+  if ! fm_lease_live "$task"; then
+    fm_lease_clear_stale "$task" || { fm_lease_guard_release; return 1; }
+    if [ "$active" != 1 ]; then
+      fm_lease_guard_release
+    fi
+    return 0
+  fi
+  lease_actor=$FM_LEASE_ACTOR
+  if [ "$lease_actor" != "$actor" ]; then
+    fm_lease_guard_release
+    echo "error: $action refused - task '$task' is leased to the $lease_actor supervision actor (state/.lease-$task); retry after that actor releases it" >&2
+    exit "$FM_LEASE_REFUSE_EXIT"
+  fi
+}
+
+# Release the claim/guard serialization lock retained by fm_lease_guard.
+# Idempotent so callers can use it unconditionally from existing EXIT cleanup.
+fm_lease_guard_release() {
+  local lock=$FM_LEASE_GUARD_LOCK
+  [ -n "$lock" ] || return 0
+  FM_LEASE_GUARD_LOCK=
+  fm_lock_release "$lock"
+}
+
+# fm_lease_forbid_branch <action-label>: refuse (exit FM_LEASE_REFUSE_EXIT)
+# when the current actor is the supervision branch. Guards the main-owned role
+# partition; a home with no branch never sets the actor and always passes.
+fm_lease_forbid_branch() {
+  local action=$1 actor
+  actor=$(fm_lease_actor) || exit "$FM_LEASE_REFUSE_EXIT"
+  [ "$actor" = branch ] || return 0
+  echo "error: $action refused - the supervision branch never performs this action; report the outcome and leave it to main (role partition: docs/pi-supervision-branch.md)" >&2
+  exit "$FM_LEASE_REFUSE_EXIT"
+}