@zerwiz/ymir 0.1.4 → 0.1.7

package/.agents/backend/fm-stow-cascade.sh

@@ -0,0 +1,251 @@
+#!/usr/bin/env bash
+# Enumerate this home's registered secondmates for an internal /stow cascade.
+# Usage: fm-stow-cascade.sh [--help]
+#
+# The internal /stow skill owns curation judgement; this command owns only the
+# mechanical inputs a cascade needs: which homes exist, what each home's own
+# startup-memory accounting says right now, and how the sweep can reach it.
+#
+# Enumeration comes from data/secondmates.md, the registry that already refuses
+# a duplicate id, a duplicate home, and an overlapping home, so each registered
+# secondmate is emitted exactly once and no home is accounted twice. A home's
+# budget is that home's alone: this command never sums a fleet total, because
+# config/startup-memory-budget is a per-home allowance.
+#
+# Each home is reported as one blank-line-separated key=value stanza:
+#   secondmate=<id>
+#   placement=local|remote            (host=<alias> on a remote route)
+#   home=<path>
+#   budget_report=ok|error|timeout    (report lines follow on ok)
+#   transport=agent|direct|deferred|unavailable
+#   reason=<one line>                 (whenever a step did not complete)
+#
+# transport says how the sweep reaches that home:
+#   agent     - a live secondmate agent owns the home; steer it with
+#               bin/fm-send.sh so it sweeps its own uncaptured session
+#               knowledge and replies through its marked return channel.
+#   direct    - a local home with no live agent; curate its editable memory
+#               files in place.
+#   deferred  - a remote home with no live agent. There is deliberately no
+#               generic remote write path (bin/fm-remote-file.sh put reaches
+#               only the handoff outbox), so that home is accounted read-only
+#               and curated by its next cascade once its agent is back.
+#   unavailable - the home's own accounting did not complete, so no transport
+#               conclusion is safe.
+#
+# Every step that crosses a host, plus each home's own accounting, runs under
+# one hard bound (FM_STOW_CASCADE_TIMEOUT seconds, default 60), so a slow or
+# unreachable home reports an exception and the sweep continues instead of
+# blocking the primary's own /stow. A local endpoint probe reads this host's
+# recorded backend in process, like every other caller of that contract.
+#
+# A secondmate home never cascades: secondmates do not own secondmates, so this
+# command reports the empty cascade there rather than reaching for a registry.
+#
+# Exit status: 0 every home reported cleanly (or there were none); 3 at least
+# one home reported an exception and every home was still reported; 1 the
+# cascade input itself is unusable; 2 invalid use.
+set -u
+
+usage() {
+  sed -n '2,47{s/^# \{0,1\}//;p;}' "$0"
+}
+
+case "${1:-}" in
+  -h|--help) usage; exit 0 ;;
+  "") ;;
+  *) usage >&2; exit 2 ;;
+esac
+[ "$#" -le 1 ] || { usage >&2; exit 2; }
+
+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}}"
+DATA="${FM_DATA_OVERRIDE:-$FM_HOME/data}"
+STATE="${FM_STATE_OVERRIDE:-$FM_HOME/state}"
+REGISTRY="$DATA/secondmates.md"
+BUDGET_CMD=fm-startup-memory-budget.sh
+SUB_HOME_MARKER="${SUB_HOME_MARKER:-.fm-secondmate-home}"
+
+# shellcheck source=bin/fm-ff-lib.sh
+. "$SCRIPT_DIR/fm-ff-lib.sh"
+# shellcheck source=bin/fm-backend.sh
+. "$SCRIPT_DIR/fm-backend.sh"
+# shellcheck source=bin/fm-timeout-lib.sh
+. "$SCRIPT_DIR/fm-timeout-lib.sh"
+
+BOUND=${FM_STOW_CASCADE_TIMEOUT:-60}
+case "$BOUND" in
+  ''|*[!0-9]*) printf 'error: FM_STOW_CASCADE_TIMEOUT must be a positive integer: %s\n' "$BOUND" >&2; exit 2 ;;
+esac
+[ "$BOUND" -gt 0 ] \
+  || { printf 'error: FM_STOW_CASCADE_TIMEOUT must be a positive integer: %s\n' "$BOUND" >&2; exit 2; }
+
+die() { printf 'error: %s\n' "$1" >&2; exit 1; }
+emit() { printf '%s\n' "$1"; }
+
+TMP=$(mktemp -d "${TMPDIR:-/tmp}/fm-stow-cascade.XXXXXX") || exit 1
+# shellcheck disable=SC2317,SC2329 # Invoked by the EXIT trap.
+cleanup() { rm -rf -- "$TMP"; }
+trap cleanup EXIT
+STEP_OUT="$TMP/step.out"
+
+# Run one bounded external step, capturing its stdout for the caller.
+# Returns the step's own status, or 124 when the bound was hit.
+run_step() {
+  local rc=0
+  fm_run_timed "$BOUND" "$@" < /dev/null > "$STEP_OUT" 2>/dev/null || rc=$?
+  return "$rc"
+}
+
+# This home's recorded secondmate endpoint for <id>, if it has one.
+meta_for() { # <id>
+  local meta="$STATE/$1.meta"
+  [ -f "$meta" ] && [ ! -L "$meta" ] || return 1
+  grep -q '^kind=secondmate$' "$meta" 2>/dev/null || return 1
+  printf '%s\n' "$meta"
+}
+
+TRANSPORT=
+TRANSPORT_REASON=
+set_transport() { TRANSPORT=$1; TRANSPORT_REASON=${2:-}; }
+
+# A local home is curated in place when no live agent owns it.
+resolve_local_transport() { # <id> <resolved-home>
+  local id=$1 home=$2 meta backend target meta_home
+  if ! meta=$(meta_for "$id"); then
+    set_transport direct 'no recorded endpoint for this home'
+    return 0
+  fi
+  meta_home=$(fm_meta_get "$meta" home)
+  if [ -n "$meta_home" ] \
+    && [ "$(secondmate_registry_path_key "$meta_home" 2>/dev/null || true)" != "$home" ]; then
+    set_transport direct 'recorded endpoint belongs to another home'
+    return 0
+  fi
+  backend=$(fm_backend_of_meta "$meta")
+  target=$(fm_backend_target_of_meta "$meta")
+  [ -n "$target" ] || target=$(fm_meta_get "$meta" window)
+  if [ -z "$target" ]; then
+    set_transport direct 'recorded endpoint has no target'
+    return 0
+  fi
+  case "$(fm_backend_agent_state "$backend" "$target" 2>/dev/null || printf 'unreadable')" in
+    alive) set_transport agent ;;
+    *) set_transport direct 'no live agent on the recorded endpoint' ;;
+  esac
+}
+
+# A remote home with no live agent is deferred, never direct: this repo has no
+# generic remote write path for a home's own memory files.
+resolve_remote_transport() { # <id>
+  local id=$1 rc=0
+  if ! meta_for "$id" >/dev/null; then
+    set_transport deferred 'no recorded endpoint and no remote memory write path'
+    return 0
+  fi
+  run_step "$SCRIPT_DIR/fm-on.sh" "$id" fm-remote-secondmate-control.sh state "$id" || rc=$?
+  if [ "$rc" -eq 124 ]; then
+    set_transport deferred "remote endpoint probe exceeded the ${BOUND}s bound"
+    return 0
+  fi
+  if [ "$rc" -ne 0 ]; then
+    set_transport deferred 'remote endpoint probe failed'
+    return 0
+  fi
+  case "$(tail -1 "$STEP_OUT")" in
+    alive) set_transport agent ;;
+    *) set_transport deferred 'no live agent and no remote memory write path' ;;
+  esac
+}
+
+if [ -e "$FM_HOME/$SUB_HOME_MARKER" ] || [ -L "$FM_HOME/$SUB_HOME_MARKER" ]; then
+  emit 'role=secondmate'
+  emit 'secondmates=0'
+  emit 'reason=a secondmate home stows its own memory only and never cascades'
+  exit 0
+fi
+emit 'role=primary'
+
+if [ ! -e "$REGISTRY" ] && [ ! -L "$REGISTRY" ]; then
+  emit 'secondmates=0'
+  emit 'exceptions=0'
+  emit 'reason=no secondmate registry in this home'
+  exit 0
+fi
+if ! secondmate_registry_validate_bindings "$REGISTRY" secondmate_registry_path_key; then
+  die "$SECONDMATE_REGISTRY_ERROR"
+fi
+
+grep '^- ' "$REGISTRY" > "$TMP/records" 2>/dev/null || : > "$TMP/records"
+total=0
+exceptions=0
+while IFS= read -r line || [ -n "$line" ]; do
+  [ -n "$line" ] || continue
+  secondmate_registry_parse_line "$line" || die "malformed secondmate registry entry: $line"
+  id=$SECONDMATE_REGISTRY_ID
+  home=$SECONDMATE_REGISTRY_HOME
+  remote=$SECONDMATE_REGISTRY_REMOTE
+  host=$SECONDMATE_REGISTRY_HOST
+  total=$((total + 1))
+  rc=0
+  printf '\n'
+  emit "secondmate=$id"
+  if [ "$remote" -eq 1 ]; then
+    emit 'placement=remote'
+    emit "host=$host"
+    emit "home=$home"
+    run_step "$SCRIPT_DIR/fm-on.sh" "$id" "$BUDGET_CMD" report || rc=$?
+  else
+    emit 'placement=local'
+    if ! validate_secondmate_home "$id" "$home"; then
+      emit "home=$home"
+      emit 'budget_report=error'
+      emit 'transport=unavailable'
+      emit "reason=$VALIDATION_ERROR"
+      exceptions=$((exceptions + 1))
+      continue
+    fi
+    resolved=$VALIDATED_HOME
+    emit "home=$resolved"
+    # Every FM_*_OVERRIDE is restated so a caller's own override cannot leak
+    # this home's memory files into the accounting of another home.
+    run_step env \
+      FM_ROOT_OVERRIDE="$FM_ROOT" \
+      FM_HOME="$resolved" \
+      FM_STATE_OVERRIDE="$resolved/state" \
+      FM_DATA_OVERRIDE="$resolved/data" \
+      FM_CONFIG_OVERRIDE="$resolved/config" \
+      "$SCRIPT_DIR/$BUDGET_CMD" report || rc=$?
+  fi
+  if [ "$rc" -eq 124 ]; then
+    emit 'budget_report=timeout'
+    emit 'transport=unavailable'
+    emit "reason=this home's own accounting exceeded the ${BOUND}s bound"
+    exceptions=$((exceptions + 1))
+    continue
+  fi
+  if [ "$rc" -ne 0 ]; then
+    emit 'budget_report=error'
+    emit 'transport=unavailable'
+    emit "reason=this home's own accounting failed"
+    exceptions=$((exceptions + 1))
+    continue
+  fi
+  emit 'budget_report=ok'
+  cat "$STEP_OUT"
+  if [ "$remote" -eq 1 ]; then
+    resolve_remote_transport "$id"
+  else
+    resolve_local_transport "$id" "$resolved"
+  fi
+  emit "transport=$TRANSPORT"
+  [ -z "$TRANSPORT_REASON" ] || emit "reason=$TRANSPORT_REASON"
+  case "$TRANSPORT" in agent|direct) ;; *) exceptions=$((exceptions + 1)) ;; esac
+done < "$TMP/records"
+
+printf '\n'
+emit "secondmates=$total"
+emit "exceptions=$exceptions"
+[ "$exceptions" -eq 0 ] || exit 3
+exit 0

package/.agents/backend/fm-subagent-pretool-check.sh

@@ -0,0 +1,207 @@
+#!/usr/bin/env bash
+# PreToolUse guard against primary-session delegation outside the fleet.
+#
+# A firstmate primary that delegates through a harness's own delegation,
+# scheduling, or background-work tool creates work with no `state/<id>.meta` and
+# no `data/<id>/brief.md`. Only `bin/fm-spawn.sh` writes that metadata, and
+# untracked project work contributes nothing to the in-flight branch of
+# bin/fm-supervision-lib.sh or bin/fm-turnend-guard.sh. So such work is not
+# merely unsupervised: absent an independent X-mode need, it makes the whole
+# guard stack structurally inert, and it dies with the primary session instead
+# of living in its own backend session.
+#
+# This scoped PreToolUse guard is the shipped mechanism.
+# Claude primaries should also use an untracked per-home local
+# `permissions.deny` list as hardening for known Claude delegation tools,
+# because it removes them from the model's schema entirely.
+# That deny list must not be tracked: it is Claude-only rather than
+# harness-agnostic, and tracked project settings propagate into linked
+# worktrees where they disarm legitimate crewmates.
+# The tracked Claude matcher is deliberately `.*`: a stem-enumerating matcher
+# would reintroduce the fail-open-by-enumeration problem this guard exists to
+# solve, because any future tool name outside the matcher would never reach this
+# script.
+# This script is therefore the single owner of classification.
+# It matches a delegation-SHAPED tool name rather than a fixed list, so a future
+# tool that ships before anyone updates a local deny list is still refused.
+#
+# The guard is narrow by design. It classifies ONE thing: the shape of the tool
+# name. It makes no judgment about whether the work should be delegated at all,
+# which is a reasoning boundary no tool-shape hook can enforce.
+# See docs/subagent-guard.md for the complete contract and validation record.
+#
+# Usage:
+#   <PreToolUse JSON on stdin> | bin/fm-subagent-pretool-check.sh
+#   bin/fm-subagent-pretool-check.sh --tool '<tool-name>'
+#
+# Stdin mode extracts .tool_name for Claude and Codex, or .toolName for Grok.
+# CLI mode is for adapters that already hold the tool name (OpenCode, Pi).
+#
+# Exit/output contract (identical shape to bin/fm-cd-pretool-check.sh):
+#   ALLOW - exit 0 and no output.
+#   DENY - exit 2, a Claude-shaped deny object on stderr, and a Grok-shaped
+#          deny object on stdout unless --claude was supplied.
+#   INERT - not a genuine primary home (a crewmate/scout task worktree or a
+#           non-firstmate repo): exit 0 with no output, exactly like ALLOW.
+#   ESCAPE - FM_ALLOW_SUBAGENT=1 in the environment allows deliberately.
+#   FAIL OPEN - malformed or empty stdin, or missing jq for stdin transport.
+#
+# Claude requires stdout to remain empty on deny.
+# Codex blocks on exit 2 and displays stderr.
+# Grok consumes the stdout decision object.
+# OpenCode and Pi consume exit 2 plus stderr.
+set -u
+
+# Lowercase substrings that mark a tool name as delegation-shaped: it creates
+# work, an agent, a schedule, or an isolated workspace that firstmate would not
+# know about. This list is the single owner of the shipped classification.
+DELEGATION_STEMS='agent subagent task workflow cron schedul worktree delegate spawn dispatch handoff remote sendmessage monitor'
+
+# Exact lowercase tool names that match a stem above but only OBSERVE or STOP
+# work that already exists. Reading or ending unaccounted work is not creating
+# it, and denying these would strand already-running work with no way to inspect
+# or end it. A local Claude deny list may still remove these from the
+# schema; this shipped guard deliberately stays narrower so it can never be the
+# reason a runaway task cannot be stopped.
+OBSERVE_ONLY_TOOLS='taskoutput taskstop taskget tasklist cronlist bashoutput killshell'
+
+# Exact lowercase tool names that match a stem above but create no RUNNABLE
+# work. These write only the harness's session-local todo list, which has no
+# executor: it spawns no agent, allocates no worktree, registers no schedule,
+# and starts nothing that could outlive the session or escape a firstmate
+# guard. Denying them stops the primary tracking its own plan while granting no
+# delegation power, and the deny text would tell it to run bin/fm-brief.sh for a
+# todo entry, so the stem match here is a false positive rather than a policy.
+# This is a separate list from OBSERVE_ONLY_TOOLS on purpose: these tools WRITE,
+# so folding them into a list documented as observe-or-stop would make that
+# contract untrue. Both lists are exact-name, never substring, so neither can
+# widen by accident.
+PLAN_ONLY_TOOLS='taskcreate taskupdate'
+
+TOOL=""
+TOOL_SET=0
+CLAUDE_MODE=0
+
+usage() {
+  cat <<'EOF'
+Usage: fm-subagent-pretool-check.sh [--tool <tool-name>] [--claude]
+
+With no --tool, reads a PreToolUse-style JSON payload on stdin (Claude/Codex
+tool_name, or Grok toolName).
+Denies a delegation-SHAPED tool name in a genuine primary home.
+Claude primaries may also add an untracked per-home permissions.deny list that
+removes known delegation tools from the model schema before this hook is needed.
+Do not ship that Claude-only list in tracked project settings, because linked
+worktrees inherit it and legitimate crewmates would lose their delegation tools.
+This hook remains as the shipped guard for future delegation-shaped names
+outside any local fixed list.
+Fires only in a genuine firstmate primary home; it is a silent no-op in a
+crewmate/scout task worktree or any non-firstmate repo, where a worker using
+delegation tools is legitimate.
+Exits 0 to allow and 2 to deny, naming the real crewmate dispatch path instead.
+Set FM_ALLOW_SUBAGENT=1 in the session environment to allow deliberately.
+Malformed transport fails open.
+EOF
+}
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --tool)
+      [ "$#" -gt 1 ] || { echo "error: --tool requires a value" >&2; exit 2; }
+      TOOL=$2
+      TOOL_SET=1
+      shift 2
+      ;;
+    --tool=*)
+      TOOL=${1#--tool=}
+      TOOL_SET=1
+      shift
+      ;;
+    --claude)
+      CLAUDE_MODE=1
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "error: unknown argument: $1" >&2
+      usage >&2
+      exit 2
+      ;;
+  esac
+done
+
+if [ "$TOOL_SET" -eq 0 ]; then
+  PAYLOAD=$(cat 2>/dev/null || true)
+  [ -n "$PAYLOAD" ] || exit 0
+  command -v jq >/dev/null 2>&1 || exit 0
+  TOOL=$(printf '%s' "$PAYLOAD" | jq -r '(.tool_name // .toolName // empty)' 2>/dev/null) || exit 0
+fi
+
+[ -n "$TOOL" ] || exit 0
+
+LC_ALL=C NORMALIZED=$(printf '%s' "$TOOL" | tr '[:upper:]' '[:lower:]' | tr -cd 'a-z0-9')
+
+# An MCP tool belongs to an external integration, not to the harness's own
+# delegation surface, and its name is chosen by that server. Never classify one
+# here: an MCP server with a task or agent noun in a tool name is common and
+# blocking it would be a false positive with no bearing on fleet dispatch.
+case "$TOOL" in
+  mcp__*) exit 0 ;;
+esac
+
+for allowed in $OBSERVE_ONLY_TOOLS $PLAN_ONLY_TOOLS; do
+  [ "$NORMALIZED" != "$allowed" ] || exit 0
+done
+
+MATCHED=""
+for stem in $DELEGATION_STEMS; do
+  case "$NORMALIZED" in
+    *"$stem"*) MATCHED=$stem; break ;;
+  esac
+done
+[ -n "$MATCHED" ] || exit 0
+
+# The single deliberate escape hatch. It is an environment variable rather than
+# a flag or a state file so it must be set when the session is launched, which
+# makes a genuinely intended use possible and an accidental one impossible: no
+# in-session tool call can set it for the call that follows.
+[ "${FM_ALLOW_SUBAGENT:-}" != "1" ] || exit 0
+
+SCRIPT_DIR=$(CDPATH='' cd -- "$(dirname -- "${BASH_SOURCE[0]}")" 2>/dev/null && pwd -P) || exit 0
+FM_ROOT=${FM_ROOT_OVERRIDE:-$(CDPATH='' cd -- "$SCRIPT_DIR/.." 2>/dev/null && pwd -P)} || exit 0
+FM_HOME=${FM_HOME:-${FM_ROOT_OVERRIDE:-$FM_ROOT}}
+STATE=${FM_STATE_OVERRIDE:-$FM_HOME/state}
+
+# Scope to a genuine primary home, exactly as the session-start nudge and the
+# turn-end guard do. fm_primary_scope_matches accepts a plain checkout or a
+# marked secondmate home - both operate a fleet and must dispatch through it -
+# and rejects a linked task worktree, which is the shape bin/fm-spawn.sh always
+# hands a crewmate. A crewmate using delegation tools inside its own task
+# worktree is legitimate and stays allowed. Any failure to confirm the home is
+# inert (exit 0), never a block, so a broken environment never denies a call.
+# shellcheck source=bin/fm-primary-scope-lib.sh
+. "$SCRIPT_DIR/fm-primary-scope-lib.sh"
+fm_primary_scope_matches "$FM_ROOT" "$STATE" || exit 0
+
+# Name the dedicated scout entry point only when this home carries it; degrade
+# to the two-step brief-then-spawn path when it does not, rather than naming a
+# script that is not there.
+if [ -f "$FM_ROOT/bin/fm-scout.sh" ]; then
+  ROUTE='first classify the work under the AGENTS.md intake contract: work already classified as a scout goes to bin/fm-scout.sh "<question>" [project], while authorized ship work and its bounded research go to bin/fm-brief.sh then bin/fm-spawn.sh'
+else
+  ROUTE='first classify the work under the AGENTS.md intake contract, then use bin/fm-brief.sh followed by bin/fm-spawn.sh for dispatched work'
+fi
+
+REASON="[subagent-dispatch] the firstmate primary dispatches through the fleet, not the harness's own delegation tools: work started that way has no durable fleet record, leaves every firstmate guard inert, and dies with this session. Instead, $ROUTE (blocked tool: $TOOL, delegation-shaped on \"$MATCHED\"). Launch the session with FM_ALLOW_SUBAGENT=1 for a deliberate exception."
+
+json_escape() {
+  printf '%s' "$1" | sed -e 's/\\/\\\\/g' -e 's/"/\\"/g' | tr '\n' ' '
+}
+
+ESCAPED=$(json_escape "$REASON")
+printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny"},"systemMessage":"%s"}\n' "$ESCAPED" >&2
+[ "$CLAUDE_MODE" -eq 1 ] || printf '{"decision":"deny","reason":"%s"}\n' "$ESCAPED"
+exit 2