Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -107,7 +107,7 @@ When every candidate is tight, preserve the captain's strongest-reasoning class
Break genuine evidence ties without array-order or harness bias.
`quota-axi` owns how model or product windows relate to bounding account windows and remains data-only.
Load `quota-array-dispatch` before choosing among a matched profile array or a Claude spawn's declared accounts; that skill is the single owner of the TOON-first spendPriority selection procedure.
Run `bin/fm-dispatch-resolve.sh` directly on the written brief in the same turn, with no preflight, and on `clear` pass its `profile:` line to `fm-spawn` unless you state a reason to override; `ambiguous`, `escalate`, `error`, and off all mean the intake above, unchanged (contract: `docs/configuration.md` "Typed dispatch resolution").
Run `bin/fm-dispatch-resolve.sh` directly on the written brief in the same turn, with no preflight, and on `clear` pass its `profile:` line to `fm-spawn`, or pass your reason to override as `--dispatch-override <reason>`, because `fm-spawn` refuses other flags without it; `ambiguous`, `escalate`, `error`, and off all mean the intake above, unchanged (contract: `docs/configuration.md` "Typed dispatch resolution").
The generic effort fallback and its precedence are owned by `harness-adapters`: explicit captain and standing configured effort win; otherwise use low for well-understood explicit work, xhigh for ambiguous investigation or design, intermediate levels proportionally, and never max without explicit captain preference.
Do not add model-specific versions of that policy.

Expand Down
50 changes: 42 additions & 8 deletions bin/fm-dispatch-resolve.sh
Original file line number Diff line number Diff line change
Expand Up @@ -99,11 +99,14 @@
# candidate: <harness>:<model> provider=.. scope=.. remaining=..% spendPriority=.. runway=.. -> eligible | eligible, unranked: <reason> | not eligible: <reason>
# (with the shared-quota opt-out: <harness>:<model> provider=.. -> eligible (quota ranking off: home declares a single shared quota))
# profile: --harness <h> [--model <m>] [--effort <e>] [--seat <name>] [--seat-home <resolved path>] (status clear only)
# clear -> pass the profile line to fm-spawn.sh unless you state a reason to override
# Task record schema and lifecycle: docs/configuration.md "Task record".
# clear -> pass the profile line to fm-spawn.sh or use its documented dispatch override
# ambiguous -> confidence below the floor; decide as today from the probabilities
# escalate -> the rule requires captain approval, no candidate is rankable, or a genuine tie
# error -> API, network, response, quota-axi, or declared credential source failure; decide as today
# Every outcome exits 0 so an intake is never blocked by this tool.
# Every outcome exits 0; fm-spawn.sh still requires a valid task record when
# crew-dispatch.json exists (docs/configuration.md "Per-launch overrides
# and inherited defaults").
# Exit 2 only for a usage or configuration error (unreadable brief, an
# existing unreadable rules file, malformed rules, an unreadable or invalid
# credential source declaration, missing jq, an unknown provider, a selected
Expand Down Expand Up @@ -166,12 +169,29 @@ OA_TIMEOUT=10
DEFAULT_WHEN="No listed rule applies to this task."

die() { printf 'error: %s\n' "$1" >&2; exit 2; }
record_task() {
[ -n "$TASK_RECORD" ] || return 0
if ! { jq -cn --arg task "$TASK_ID" --arg status "$1" --argjson profile "${2:-null}" \
'{task: $task, status: $status, profile: $profile}' > "$TASK_RECORD.tmp.$$" \
&& mv -f -- "$TASK_RECORD.tmp.$$" "$TASK_RECORD"; } 2>/dev/null; then
rm -f -- "$TASK_RECORD.tmp.$$"
echo "dispatch-resolve: could not write $TASK_RECORD" >&2
return 1
fi
}
resolver_off() {
echo "dispatch-resolve: off ($1)" >&2
record_task off || true
exit 0
}
no_rules() {
record_task escalate || true
printf 'dispatch-resolve:\n status: escalate\n reason: no rules to match\n'
exit 0
}
emit_error() {
local reason=$1
record_task error || true
echo "dispatch-resolve: error ($reason)" >&2
printf 'dispatch-resolve:\n status: error\n reason: %s\n' "$reason"
exit 0
Expand Down Expand Up @@ -199,6 +219,19 @@ while [ $# -gt 0 ]; do
*) [ -z "$BRIEF" ] || die "one brief file only"; BRIEF=$1; shift ;;
esac
done
TASK_ID='' TASK_RECORD=''
# Matched against the same data directory fm-brief.sh and fm-spawn.sh use, so a
# FM_DATA_OVERRIDE home records where fm-spawn.sh reads.
task_dir=$(CDPATH='' cd -- "$(dirname -- "$BRIEF")" 2>/dev/null && pwd -P) || task_dir=''
data_dir=$(CDPATH='' cd -- "${FM_DATA_OVERRIDE:-$FM_HOME/data}" 2>/dev/null && pwd -P) || data_dir=''
if [ "$(basename -- "$BRIEF")" = brief.md ] && [ -n "$task_dir" ] && [ -n "$data_dir" ] \
&& [ "$(dirname -- "$task_dir")" = "$data_dir" ]; then
TASK_ID=$(basename -- "$task_dir")
TASK_RECORD="$task_dir/dispatch-resolution.json"
if [ -e "$TASK_RECORD" ] || [ -L "$TASK_RECORD" ]; then
rm -f -- "$TASK_RECORD" || die "could not clear the previous dispatch resolution: $TASK_RECORD"
fi
fi

# ---- opt-in gate ---------------------------------------------------------------
# declared_key <provider> <private variable>: set the variable from the source
Expand Down Expand Up @@ -237,8 +270,7 @@ select_key() {
[ -n "${!var}" ] || printf -v "$var" '%s' "$(fmx_env_get "$name" "$FM_HOME/.env")"
[ -n "${!var}" ] || declared_key "$provider" "$var"
if [ -z "${!var}" ]; then
echo "dispatch-resolve: off ($name absent from the environment and $FM_HOME/.env)" >&2
exit 0
resolver_off "$name absent from the environment and $FM_HOME/.env"
fi
}

Expand Down Expand Up @@ -312,8 +344,7 @@ case "$DISPATCH_PROVIDER" in
[ -n "$DISPATCH_MODEL" ] || die "FM_DISPATCH_MODEL required when FM_DISPATCH_PROVIDER=openai"
[ -n "$OPENAI_API_KEY_PRIVATE" ] || OPENAI_API_KEY_PRIVATE=$(fmx_env_get OPENAI_API_KEY "$FM_HOME/.env")
if [ -z "$OPENAI_API_KEY_PRIVATE" ]; then
echo "dispatch-resolve: off (OPENAI_API_KEY absent from the environment and $FM_HOME/.env)" >&2
exit 0
resolver_off "OPENAI_API_KEY absent from the environment and $FM_HOME/.env"
fi
;;
*) die "unknown FM_DISPATCH_PROVIDER: $DISPATCH_PROVIDER (expected typesafe, openrouter, systemone, or openai)" ;;
Expand Down Expand Up @@ -468,8 +499,7 @@ SEND_TEXT=$(mktemp) || { rm -f "$RESP_FILE" "$QUOTA" "$TASK_TEXT"; die "mktemp f
trap 'rm -f "$RULES" "$RESP_FILE" "$QUOTA" "$TASK_TEXT" "$SEND_TEXT"' EXIT

never_send_off() {
echo "dispatch-resolve: off ($1; nothing sent)" >&2
exit 0
resolver_off "$1; nothing sent"
}

# Checks the endpoint and every string the final request body carries,
Expand Down Expand Up @@ -820,5 +850,9 @@ TEXT=$(jq -r --argjson seat_homes "$SEAT_HOMES" '
+ (if .chosen.profile.model then " --model \(.chosen.profile.model | shell_arg)" else "" end)
+ (if .chosen.profile.effort then " --effort \(.chosen.profile.effort | shell_arg)" else "" end)
+ (if .chosen.profile.seat then " --seat \(.chosen.profile.seat | shell_arg) --seat-home \($seat_homes[.chosen.profile.seat] | shell_arg)" else "" end) else empty end)' <<<"$RESULT") || emit_error "output rendering failed"
STATUS=$(jq -r '.status' <<<"$RESULT") || emit_error "status rendering failed"
PROFILE=$(jq -c 'if .chosen then .chosen.profile | {harness, model: (.model // null), effort: (.effort // null), seat: (.seat // null)} else null end' <<<"$RESULT") \
|| emit_error "profile rendering failed"
record_task "$STATUS" "$PROFILE" || emit_error "could not record the dispatch resolution"
printf '%s\n' "$TEXT"
exit 0
52 changes: 46 additions & 6 deletions bin/fm-spawn.sh
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
#!/usr/bin/env bash
# Spawn a direct report: a crewmate in a treehouse or Orca worktree, or a
# secondmate in its isolated firstmate home.
# Usage: fm-spawn.sh <task-id> <project-dir> --mode <no-mistakes|direct-PR|local-only> --yolo <on|off> [--branch-prefix <prefix>] [--base-branch <branch>] [--harness <name>|harness|launch-command] [--model <name>] [--effort <level>] [--hermes-profile <name>] [--seat <seat>] [--account <entry>] [--backend <name>] [--herdr-resume-lock-wait]
# fm-spawn.sh <task-id> <project-dir> --scout [--base-branch <branch>] [--harness <name>|harness|launch-command] [--model <name>] [--effort <level>] [--hermes-profile <name>] [--seat <seat>] [--account <entry>] [--backend <name>] [--herdr-resume-lock-wait]
# Usage: fm-spawn.sh <task-id> <project-dir> --mode <no-mistakes|direct-PR|local-only> --yolo <on|off> [--branch-prefix <prefix>] [--base-branch <branch>] [--harness <name>|harness|launch-command] [--model <name>] [--effort <level>] [--dispatch-override <reason>] [--hermes-profile <name>] [--seat <seat>] [--seat-home <resolved path>] [--account <entry>] [--backend <name>] [--herdr-resume-lock-wait]
# fm-spawn.sh <task-id> <project-dir> --scout [--base-branch <branch>] [--harness <name>|harness|launch-command] [--model <name>] [--effort <level>] [--dispatch-override <reason>] [--hermes-profile <name>] [--seat <seat>] [--seat-home <resolved path>] [--account <entry>] [--backend <name>] [--herdr-resume-lock-wait]
# fm-spawn.sh <task-id> [<firstmate-home>] [--harness <name>|harness|launch-command] [--model <name>] [--effort <level>] [--seat <seat>] [--backend <name>] --secondmate
# --mode and --yolo are this task's delivery contract, REQUIRED for every ship
# spawn and refused on --scout and --secondmate spawns. Firstmate resolves both
Expand Down Expand Up @@ -102,6 +102,10 @@
# only a shell that will not go refuses.
# --harness <name> is the explicit per-spawn harness/profile adapter. The old
# positional harness arg still works for back-compat.
# --dispatch-override <reason> records a non-empty printable reason as
# dispatch_override= in state/<id>.meta. It permits departing from a clear
# dispatch selection under docs/configuration.md "Per-launch overrides and
# inherited defaults"; it does not bypass other launch validation.
# --hermes-profile <name> selects Hermes's native -p profile for a tmux
# crewmate/scout; omission keeps Hermes's default selection. Names follow the
# native lowercase 1-64 character grammar. The resolved home is pinned for
Expand Down Expand Up @@ -255,8 +259,10 @@
# capacity.
# With no harness arg, a crewmate/scout spawn resolves the CREW harness only when
# config/crew-dispatch.json is absent. When that file exists, crewmate/scout
# spawns require an explicit harness so firstmate cannot silently skip dispatch
# profile consultation. A --secondmate spawn is exempt and resolves the SECONDMATE
# spawns require an explicit harness and a task dispatch record under
# docs/configuration.md "Per-launch overrides and inherited defaults" so
# firstmate cannot silently skip dispatch profile consultation.
# A --secondmate spawn is exempt and resolves the SECONDMATE
# harness (config/secondmate-harness -> config/crew-harness -> own), so the
# secondmate-vs-crewmate split is DURABLE across every respawn (recovery,
# /updatefirstmate, restart). A bare adapter name from fm_control_harnesses
Expand Down Expand Up @@ -384,11 +390,13 @@
# Batch dispatch: pass one or more `id=repo` pairs instead of a single <id> <project>, e.g.
# fm-spawn.sh fix-a-k3=projects/foo add-b-q7=projects/bar [--scout]
# Each pair re-execs this script in single-task mode, so the single path stays the only
# source of truth; shared --scout/--harness/--model/--effort/--backend/--mode/--yolo
# source of truth; shared --scout/--harness/--model/--effort/--seat/--seat-home/
# --dispatch-override/--backend/--mode/--yolo
# applies to every pair. A ship batch therefore carries one delivery contract, and each
# pair still checks it against its own brief; a batch spanning modes is two invocations.
# If config/crew-dispatch.json exists, shared --harness is required for crewmate
# and scout batches. The loop lives here, in bash, so callers never hand-write a
# and scout batches, and each pair checks its own dispatch record.
# The loop lives here, in bash, so callers never hand-write a
# multi-task shell loop (the tool shell is zsh, which does not word-split unquoted
# $vars and silently breaks ad-hoc `for ... in $pairs` loops).
# Launch delivery:
Expand Down Expand Up @@ -987,6 +995,7 @@ KIND_SET=0
HARNESS_ARG=
MODEL=
EFFORT=
DISPATCH_OVERRIDE=
BACKEND_ARG=
MODE=
YOLO=
Expand Down Expand Up @@ -1045,6 +1054,7 @@ for a in "$@"; do
seat-home)
SEAT_HOME_ARG=$a
;;
dispatch-override) DISPATCH_OVERRIDE=$a ;;
hermes-profile)
HERMES_PROFILE=$a
HERMES_PROFILE_SET=1
Expand Down Expand Up @@ -1119,6 +1129,8 @@ for a in "$@"; do
--seat=*) SEAT=${a#--seat=}; SEAT_SET=1 ;;
--seat-home) want_value="seat-home" ;;
--seat-home=*) SEAT_HOME_ARG=${a#--seat-home=} ;;
--dispatch-override) want_value=dispatch-override ;;
--dispatch-override=*) DISPATCH_OVERRIDE=${a#--dispatch-override=} ;;
--hermes-profile) want_value=hermes-profile ;;
--hermes-profile=*) HERMES_PROFILE=${a#--hermes-profile=}; HERMES_PROFILE_SET=1 ;;
--backend) want_value=backend ;;
Expand Down Expand Up @@ -2230,6 +2242,7 @@ if [ "${#POS[@]}" -gt 0 ] && [ "${POS[0]}" != "$idpart" ] && case "$idpart" in *
[ -z "$EFFORT" ] || shared_args+=(--effort "$EFFORT")
[ -z "$SEAT" ] || shared_args+=(--seat "$SEAT")
[ -z "$SEAT_HOME_ARG" ] || shared_args+=(--seat-home "$SEAT_HOME_ARG")
[ -z "$DISPATCH_OVERRIDE" ] || shared_args+=(--dispatch-override "$DISPATCH_OVERRIDE")
[ "$HERMES_PROFILE_SET" -eq 0 ] || shared_args+=(--hermes-profile "$HERMES_PROFILE")
[ -z "$BACKEND_ARG" ] || shared_args+=(--backend "$BACKEND_ARG")
# One delivery contract applies to every pair in a batch, exactly like the shared
Expand Down Expand Up @@ -3349,6 +3362,32 @@ if [ -n "$SEAT" ]; then
fi
fi

case "$DISPATCH_OVERRIDE" in *[![:print:]]*) echo 'error: --dispatch-override must be a printable reason' >&2; exit 1 ;; esac
DISPATCH_RECORD="$DATA/$ID/dispatch-resolution.json"
if [ "$KIND" != secondmate ] && [ "$RELAUNCH" -eq 0 ] && [ -f "$CONFIG/crew-dispatch.json" ]; then
if [ ! -e "$DISPATCH_RECORD" ]; then
echo "error: config/crew-dispatch.json is active and task $ID has no recorded dispatch resolution; run bin/fm-dispatch-resolve.sh $DATA/$ID/brief.md --project <name> first" >&2
exit 1
fi
dispatch_fields=$(jq -r --arg id "$ID" '
select(.task == $id and (.status | IN("clear", "ambiguous", "escalate", "error", "off"))
and (if .status == "clear" then (.profile.harness | type) == "string" and .profile.harness != "" else true end))
| .status, (.profile.harness // ""), (.profile.model // ""), (.profile.effort // ""), (.profile.seat // "")' "$DISPATCH_RECORD" 2>/dev/null) || dispatch_fields=
{ read -r dispatch_status; read -r selected_harness; read -r selected_model; read -r selected_effort; read -r selected_seat; } <<<"$dispatch_fields" || true
if [ -z "$dispatch_status" ]; then
echo "error: malformed dispatch resolution $DISPATCH_RECORD for task $ID; rerun bin/fm-dispatch-resolve.sh $DATA/$ID/brief.md --project <name>" >&2
exit 1
fi
if [ "$dispatch_status" = clear ] && [ -z "$DISPATCH_OVERRIDE" ] \
&& { [ "$RAW_LAUNCH" -eq 1 ] || [ "$HARNESS" != "$selected_harness" ] \
|| { [ -n "$selected_model" ] && [ "${MODEL:-}" != "$selected_model" ]; } \
|| { [ -n "$selected_effort" ] && [ "${EFFORT:-}" != "$selected_effort" ]; } \
|| [ "${SEAT:-}" != "$selected_seat" ]; }; then
echo "error: launch flags do not match the clear dispatch selection --harness $selected_harness${selected_model:+ --model $selected_model}${selected_effort:+ --effort $selected_effort}${selected_seat:+ --seat $selected_seat} recorded in $DISPATCH_RECORD; pass those flags with no raw launch command, or record this task's override with --dispatch-override <reason>" >&2
exit 1
fi
fi

# muse, gemini, devin, commandcode, polytoken, cortex, and kiro are verified as CREWMATE/SCOUT adapters only. A secondmate is
# a firstmate instance, so it needs a primary supervision protocol.
# gemini has none: docs/supervision-protocols/ carries no gemini wake protocol
Expand Down Expand Up @@ -7517,6 +7556,7 @@ preserve_relaunch_meta() {
[ -z "$SEAT_DOCK" ] || echo "dock=$SEAT_DOCK"
[ -z "$SEAT_HOME" ] || echo "seat_home=$SEAT_HOME"
[ -z "$SEAT_SOURCE" ] || echo "seat_source=$SEAT_SOURCE"
[ -z "$DISPATCH_OVERRIDE" ] || printf 'dispatch_override=%s\n' "$DISPATCH_OVERRIDE"
# The detected OpenCode major, recorded so fm-control sends the exit key this
# agent's TUI understands. Written only when a version was resolved, so a
# non-opencode or undetectable task record stays byte-identical.
Expand Down
Loading
Loading