From 62d5b7b2fab3494878a20fad296f89ae64b0c5d7 Mon Sep 17 00:00:00 2001 From: Tiago Date: Sun, 8 Nov 2026 00:29:49 -0300 Subject: [PATCH 1/2] fix(bin): bind crewmate spawns to the recorded dispatch selection (#8262) * fix(spawn): bind launch flags to dispatch selection * no-mistakes(review): Bind spawn to resolver-recorded dispatch selection * no-mistakes(review): Bind spawn to per-task dispatch resolution record * no-mistakes(document): Document relaunch exemption and fix task record heading * no-mistakes(ci): Fixed the selected Greptile findings ci-2 and ci-3. Changes are left uncommitted in the worktree. ci-2 rule: a spawn under a clear recorded dispatch selection launches only that selection unless the task records an override. A raw launch command (a full command line instead of a harness name) keeps its own --model/--effort options, so matching flags beside it proved nothing. bin/fm-spawn.sh now refuses any raw launch command under a clear record unless --dispatch-override is given. The error message now says "with no raw launch command". This check gates both the single-task path and the batch path. Raw commands under ambiguous/escalate/error/off records still work, so the manual path is unchanged. ci-3 rule: the resolver writes the task record where fm-spawn.sh reads it, which is FM_DATA_OVERRIDE, else $FM_HOME/data. bin/fm-dispatch-resolve.sh used to look for a folder literally named "data". It now records only when the brief is //brief.md, comparing real directory paths. As a side effect, a data// folder outside the configured root no longer gets a record. The resolver header comment and docs/configuration.md now describe the override. Tests added: - tests/fm-spawn-dispatch-profile.test.sh: the reviewer's case is refused (record selects claude/haiku/low; raw command "claude --model opus --effort high" with --model haiku --effort low). The same command launches with an override, and the reason is saved in the .meta file. - tests/fm-dispatch-resolve.test.sh: a brief under FM_DATA_OVERRIDE gets its record. A data/ folder outside the configured root does not. The existing task-record test now puts its brief under $FM_HOME/data. Verification: both full suites passed locally. For the spawn suite I put the real Python and Node install folders ahead of mise's wrapper scripts on PATH, because those wrappers fail on this host when a test changes HOME. That is a host problem, not a product defect. Shellcheck shows only info notes about sourced files it was not asked to follow. I did not run the new tests against the old code. From reading the old checks, each would have failed there. ci-1 and ci-4 were not touched, because the user chose to ignore both (cherry picked from commit 18b20eafa0284f48a7f2dea346777ae98b3a2e3d) --- AGENTS.md | 2 +- bin/fm-dispatch-resolve.sh | 49 +++- bin/fm-spawn.sh | 36 ++- docs/configuration.md | 14 ++ tests/fm-dispatch-resolve.test.sh | 52 +++++ .../fm-spawn-compact-adviser-disable.test.sh | 11 +- tests/fm-spawn-dispatch-profile.test.sh | 219 +++++++++++++++++- 7 files changed, 371 insertions(+), 12 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 45ed9b00a98..cd23e912e94 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 `, 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. diff --git a/bin/fm-dispatch-resolve.sh b/bin/fm-dispatch-resolve.sh index 1d13d67f1f9..6b3e9a0cab8 100755 --- a/bin/fm-dispatch-resolve.sh +++ b/bin/fm-dispatch-resolve.sh @@ -99,6 +99,12 @@ # candidate: : provider=.. scope=.. remaining=..% spendPriority=.. runway=.. -> eligible | eligible, unranked: | not eligible: # (with the shared-quota opt-out: : provider=.. -> eligible (quota ranking off: home declares a single shared quota)) # profile: --harness [--model ] [--effort ] [--seat ] [--seat-home ] (status clear only) +# Task record: for //brief.md, where is FM_DATA_OVERRIDE, +# else $FM_HOME/data, every run first removes +# //dispatch-resolution.json, then every outcome except exit 2 writes +# {"task", "status" (clear, ambiguous, escalate, error, or off), "profile"} +# there; profile holds harness, model, effort, and seat on clear and is null +# otherwise. fm-spawn.sh reads it as the task's dispatch decision. # clear -> pass the profile line to fm-spawn.sh unless you state a reason to 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 @@ -166,12 +172,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 @@ -199,6 +222,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 : set the variable from the source @@ -237,8 +273,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 } @@ -312,8 +347,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)" ;; @@ -468,8 +502,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, @@ -820,5 +853,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 diff --git a/bin/fm-spawn.sh b/bin/fm-spawn.sh index 92acae1cc64..74326da5e27 100755 --- a/bin/fm-spawn.sh +++ b/bin/fm-spawn.sh @@ -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 --mode --yolo [--branch-prefix ] [--base-branch ] [--harness |harness|launch-command] [--model ] [--effort ] [--hermes-profile ] [--seat ] [--account ] [--backend ] [--herdr-resume-lock-wait] -# fm-spawn.sh --scout [--base-branch ] [--harness |harness|launch-command] [--model ] [--effort ] [--hermes-profile ] [--seat ] [--account ] [--backend ] [--herdr-resume-lock-wait] +# Usage: fm-spawn.sh --mode --yolo [--branch-prefix ] [--base-branch ] [--harness |harness|launch-command] [--model ] [--effort ] [--dispatch-override ] [--hermes-profile ] [--seat ] [--seat-home ] [--account ] [--backend ] [--herdr-resume-lock-wait] +# fm-spawn.sh --scout [--base-branch ] [--harness |harness|launch-command] [--model ] [--effort ] [--dispatch-override ] [--hermes-profile ] [--seat ] [--seat-home ] [--account ] [--backend ] [--herdr-resume-lock-wait] # fm-spawn.sh [] [--harness |harness|launch-command] [--model ] [--effort ] [--seat ] [--backend ] --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 @@ -987,6 +987,7 @@ KIND_SET=0 HARNESS_ARG= MODEL= EFFORT= +DISPATCH_OVERRIDE= BACKEND_ARG= MODE= YOLO= @@ -1045,6 +1046,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 @@ -1119,6 +1121,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 ;; @@ -2230,6 +2234,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 @@ -3349,6 +3354,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 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 " >&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 " >&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 @@ -7517,6 +7548,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. diff --git a/docs/configuration.md b/docs/configuration.md index 0ae8f1d696e..5d6d0f7e369 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1504,6 +1504,12 @@ Remote spawn and `/updatefirstmate` restart resolve the pin on the primary side; Remote secondmate routes accept verified harness adapters only and reject raw launch commands. When `config/crew-dispatch.json` exists, crewmate and scout spawns require an explicit resolved harness instead of automatically falling back to `config/crew-harness`. +Such a spawn also refuses until `bin/fm-dispatch-resolve.sh data//brief.md` has written that task's record, `data//dispatch-resolution.json`. +Both paths are under `FM_DATA_OVERRIDE` instead of `data/` when it is set. +When the record is `clear`, the spawn must match its harness and logical seat (including no seat), and its model and effort where the record sets them, with no raw launch command, unless `--dispatch-override ` records a task override in `state/.meta` as `dispatch_override=`. +A model or effort the record leaves empty is not bound, so the documented effort fallback still applies. +When the record is `ambiguous`, `escalate`, `error`, or `off`, the explicit flags from the manual intake are enough. +An `fm-spawn.sh --relaunch` skips this check. The inherited-local-material contract is owned by [`secondmate-provisioning`](../.agents/skills/secondmate-provisioning/SKILL.md); its harness-relevant consequence is that a secondmate's own crewmates use the primary's dispatch profiles and static harness value. Those inherited values are defaults and rules only; `fm-spawn` still permits a consciously chosen explicit runtime outside the config. @@ -2301,6 +2307,14 @@ Explicit captain overrides retain precedence over the resolver's suggestion. Firstmate passes its profile line unless it states a reason to override, such as the brief's reasoning class or an eligible-unranked-candidate note; every non-clear result returns to the full existing intake. +**Task record (data//dispatch-resolution.json)** + +For a brief at `data//brief.md`, or `//brief.md` when that override is set, each run first removes that task's `dispatch-resolution.json`, so a decision never outlives a later run. +Every outcome that exits 0, including off, then writes one JSON object there: `task` (the ``), `status` (`clear`, `ambiguous`, `escalate`, `error`, or `off`), and `profile`. +On `clear`, `profile` holds `harness`, `model`, `effort`, and `seat`, each `null` when the chosen profile leaves it unset; otherwise `profile` is `null`. +A usage or configuration error (exit 2) writes no record. +`fm-spawn.sh` reads this record as the task's decision, as "Per-launch overrides and inherited defaults" describes. + **Credential source declaration (config/dispatch-credential-sources.json)** The optional local, gitignored `config/dispatch-credential-sources.json` tells the resolver where a provider's key lives when neither the environment nor `.env` supplies one. diff --git a/tests/fm-dispatch-resolve.test.sh b/tests/fm-dispatch-resolve.test.sh index 4df0366c7df..d7e4ca4082d 100755 --- a/tests/fm-dispatch-resolve.test.sh +++ b/tests/fm-dispatch-resolve.test.sh @@ -423,6 +423,7 @@ assert_contains "$out" 'dispatch-resolve:' "TOON block header" assert_contains "$out" ' status: clear' "clear status" assert_contains "$out" ' rule: rule_4 (A simple bug fix with a stated root cause.) confidence: 0.9' "rule and confidence line" assert_contains "$out" " profile: --harness 'cursor' --model 'cursor-grok-4.6-medium'" "argmax picks the highest spendPriority" +assert_absent "$TMP_ROOT/dispatch-resolution.json" "a brief outside data// writes no task record" assert_contains "$out" 'candidate: claude:sonnet provider=claude scope=all_models remaining=79% spendPriority=-0.4627 runway=projected_exhaustion -> eligible' "every candidate is accounted for" assert_contains "$out" 'candidate: kimi:kimi-code/k3 provider=kimi -> eligible, unranked: provider kimi unmeasured (unknown): disclosed uncertainty' "unmeasured provider stays listed as eligible and unranked" assert_contains "$out" ' note: 1 eligible candidate(s) unranked (kimi)' "clear results flag eligible unranked candidates once" @@ -1365,6 +1366,53 @@ assert_contains "$out" 'candidate: kimi:kimi-code/k3 provider=kimi -> eligible assert_not_contains "$out" ' profile:' "ambiguous emits no profile line" pass "ambiguous: confidence below the fixed floor hands the decision back" +# --- task record: data//dispatch-resolution.json for fm-spawn --------------- +TASK_BRIEF="$HOME_DIR/data/pager-fix/brief.md" +TASK_RECORD="$HOME_DIR/data/pager-fix/dispatch-resolution.json" +mkdir -p "$(dirname "$TASK_BRIEF")" +cp "$BRIEF" "$TASK_BRIEF" +reset_log +write_response "$RESPONSE" rule_4 0.9 +TYPESAFE_API_KEY=$KEY run code out err "$TASK_BRIEF" --project pager +assert_contains "$out" " profile: --harness 'cursor' --model 'cursor-grok-4.6-medium'" "the task brief resolves clear" +assert_equals '{"task":"pager-fix","status":"clear","profile":{"harness":"cursor","model":"cursor-grok-4.6-medium","effort":null}}' \ + "$(jq -c '{task, status, profile: (.profile | {harness, model, effort})}' "$TASK_RECORD")" \ + "a clear run records the task, status, and the printed profile with an unset effort as null" +reset_log +write_response "$RESPONSE" rule_4 0.41 +TYPESAFE_API_KEY=$KEY run code out err "$TASK_BRIEF" --project pager +assert_equals 'ambiguous null' "$(jq -r '"\(.status) \(.profile)"' "$TASK_RECORD")" \ + "a later non-clear run replaces the clear selection, so the manual intake is not bound to it" +reset_log +run code out err "$TASK_BRIEF" --project pager +assert_contains "$err" 'dispatch-resolve: off (' "the keyless run is off" +assert_equals 'off null' "$(jq -r '"\(.status) \(.profile)"' "$TASK_RECORD")" "an off run records off so fm-spawn accepts the manual intake" +mv "$RULES" "$RULES.keep" +printf '{"broken":\n' > "$RULES" +TYPESAFE_API_KEY=$KEY run code out err "$TASK_BRIEF" --project pager +expect_code 2 "$code" "malformed rules exit 2" +assert_absent "$TASK_RECORD" "a configuration error leaves no task record to act on" +mv "$RULES.keep" "$RULES" +pass "task record: every exit-0 outcome records its decision for data//brief.md, and exit 2 records none" + +# A home with FM_DATA_OVERRIDE keeps briefs outside $FM_HOME/data; fm-spawn.sh +# reads the record there, so the resolver must write it there too. +OVERRIDE_DATA="$TMP_ROOT/custom-records" +mkdir -p "$OVERRIDE_DATA/pager-fix" "$TMP_ROOT/data/pager-fix" +cp "$BRIEF" "$OVERRIDE_DATA/pager-fix/brief.md" +cp "$BRIEF" "$TMP_ROOT/data/pager-fix/brief.md" +reset_log +write_response "$RESPONSE" rule_4 0.9 +FM_DATA_OVERRIDE=$OVERRIDE_DATA TYPESAFE_API_KEY=$KEY run code out err "$OVERRIDE_DATA/pager-fix/brief.md" --project pager +assert_equals 'pager-fix clear cursor' \ + "$(jq -r '"\(.task) \(.status) \(.profile.harness)"' "$OVERRIDE_DATA/pager-fix/dispatch-resolution.json")" \ + "a brief under FM_DATA_OVERRIDE records its decision beside it" +reset_log +write_response "$RESPONSE" rule_4 0.9 +TYPESAFE_API_KEY=$KEY run code out err "$TMP_ROOT/data/pager-fix/brief.md" --project pager +assert_absent "$TMP_ROOT/data/pager-fix/dispatch-resolution.json" "a data// directory outside the configured data root writes no task record" +pass "task record: the configured data root, including FM_DATA_OVERRIDE, decides where the record goes" + # --- per-rule confidence floor ------------------------------------------------ write_floor_response() { # cat > "$1" < "$HOME_DIR/config/crew-dispatch.json" + mkdir -p "$HOME_DIR/data/raw-compound-a1" + printf '%s\n' '{"task":"raw-compound-a1","status":"off","profile":null}' > "$HOME_DIR/data/raw-compound-a1/dispatch-resolution.json" probe_dir="$CASE_DIR/agent-cwd" mkdir -p "$probe_dir" @@ -464,7 +468,10 @@ SH chmod +x "$FAKEBIN_DIR/codex" seen=$(emitted_launch_env "$FAKEBIN_DIR" "$LAUNCH_LOG" "$PANE_LOG") \ || fail "$name path: the emitted launch failed to run" - brief=$("$ROOT/bin/fm-operational-input.sh" encode launch-brief < "$HOME_DIR/data/$id/launch-brief.md") + brief=$(printf 'Read and follow the complete Firstmate launch brief at %s before doing any other work.' \ + "$HOME_DIR/data/$id/launch-brief.md" | "$ROOT/bin/fm-operational-input.sh" encode launch-brief) + assert_grep "brief for $id" "$HOME_DIR/data/$id/launch-brief.md" \ + "$name path: the referenced brief lost its task content" want="$(cd "$HOME_DIR/state" && pwd -P)/$id.inbox $brief" assert_equals "$want" "$seen" "$name path: launch changed the home or brief bytes" diff --git a/tests/fm-spawn-dispatch-profile.test.sh b/tests/fm-spawn-dispatch-profile.test.sh index d19ccb98695..aa1de16e63c 100755 --- a/tests/fm-spawn-dispatch-profile.test.sh +++ b/tests/fm-spawn-dispatch-profile.test.sh @@ -154,6 +154,18 @@ enable_dispatch_profile() { > "$home/config/crew-dispatch.json" } +# Writes the task record bin/fm-dispatch-resolve.sh leaves in data// (its +# documented shape: task, status, and profile with null for an unset axis). +record_dispatch() { # [ ] + local home=$1 id=$2 status=$3 + mkdir -p "$home/data/$id" + jq -cn --arg id "$id" --arg status "$status" --arg h "${4:-}" --arg m "${5:-}" --arg e "${6:-}" --arg seat "${7:-}" ' + def opt: if . == "" then null else . end; + {task: $id, status: $status, + profile: (if $status == "clear" then {harness: $h, model: ($m | opt), effort: ($e | opt), seat: ($seat | opt)} else null end)}' \ + > "$home/data/$id/dispatch-resolution.json" +} + make_seeded_secondmate_home() { local home=$1 id=$2 mkdir -p "$home/bin" "$home/data" @@ -515,6 +527,7 @@ test_active_dispatch_profile_allows_explicit_harness() { enable_dispatch_profile "$HOME_DIR" jq '.preferred_provider = "claude"' "$HOME_DIR/config/crew-dispatch.json" > "$HOME_DIR/config/preferred.json" mv "$HOME_DIR/config/preferred.json" "$HOME_DIR/config/crew-dispatch.json" + record_dispatch "$HOME_DIR" "$id" ambiguous out=$(run_ship_spawn "$HOME_DIR" "$WT_DIR" "$FAKEBIN_DIR" "$LAUNCH_LOG" \ "$id" "$PROJ_DIR" --harness codex --model gpt-5 --effort high) @@ -525,7 +538,197 @@ test_active_dispatch_profile_allows_explicit_harness() { launch=$(fm_test_launch_unframe "$(cat "$LAUNCH_LOG")") assert_contains "$launch" "codex --model 'gpt-5' -c 'model_reasoning_effort=\"high\"' --dangerously-bypass-approvals-and-sandbox" \ "explicit harness launch did not thread model, effort, and Codex bypass flag" - pass "active crew-dispatch profile allows an explicit resolved harness" + pass "a non-clear dispatch record accepts the explicit flags of the manual intake" +} + +test_recorded_dispatch_selection_refuses_conflicting_flags() { + local rec id out status + id=profile-selected-conflict-z13 + rec=$(make_spawn_case profile-selected-conflict claude "$id") + read_case_record "$rec" + enable_dispatch_profile "$HOME_DIR" + record_dispatch "$HOME_DIR" "$id" clear claude opus high + + out=$(run_ship_spawn "$HOME_DIR" "$WT_DIR" "$FAKEBIN_DIR" "$LAUNCH_LOG" \ + "$id" "$PROJ_DIR" --harness codex --model gpt-5 --effort high) + status=$? + expect_code 1 "$status" "flags that differ from the recorded selection should be refused" + assert_contains "$out" 'launch flags do not match the clear dispatch selection --harness claude --model opus --effort high' "spawn did not name the recorded selection" + assert_absent "$HOME_DIR/state/$id.meta" "selection mismatch should refuse before task publication" + assert_equals '' "$(cat "$LAUNCH_LOG")" "selection mismatch must not create a worker" + pass "a recorded dispatch selection refuses conflicting explicit launch flags" +} + +test_recorded_dispatch_selection_allows_matching_flags() { + local rec id out status + id=profile-selected-match-z13 + rec=$(make_spawn_case profile-selected-match claude "$id") + read_case_record "$rec" + enable_dispatch_profile "$HOME_DIR" + record_dispatch "$HOME_DIR" "$id" clear codex gpt-5 high + + out=$(run_ship_spawn "$HOME_DIR" "$WT_DIR" "$FAKEBIN_DIR" "$LAUNCH_LOG" \ + "$id" "$PROJ_DIR" --harness codex --model gpt-5 --effort high) + status=$? + expect_code 0 "$status" "flags equal to the recorded selection should launch: $out" + assert_meta_profile "$HOME_DIR/state/$id.meta" codex gpt-5 high + assert_no_grep 'dispatch_override=' "$HOME_DIR/state/$id.meta" "a matching launch should record no override" + pass "a recorded dispatch selection allows the matching launch flags" +} + +test_recorded_dispatch_selection_allows_recorded_override() { + local rec id out status + id=profile-selected-override-z13 + rec=$(make_spawn_case profile-selected-override claude "$id") + read_case_record "$rec" + enable_dispatch_profile "$HOME_DIR" + record_dispatch "$HOME_DIR" "$id" clear claude opus high + + out=$(run_ship_spawn "$HOME_DIR" "$WT_DIR" "$FAKEBIN_DIR" "$LAUNCH_LOG" \ + "$id" "$PROJ_DIR" --harness codex --model gpt-5 --effort high \ + --dispatch-override 'authorized account test') + status=$? + expect_code 0 "$status" "a recorded task override should permit a different launch: $out" + assert_contains "$out" "spawned $id harness=codex" "spawn did not report the overridden Codex launch" + assert_grep 'dispatch_override=authorized account test' "$HOME_DIR/state/$id.meta" "task record omitted the override reason" + pass "a task override with its reason permits a different launch and is recorded" +} + +test_recorded_dispatch_selection_binds_seat() { + local rec id out status seat_home scenario + local -a args + for scenario in refused override matching omitted batch; do + id="profile-selected-seat-$scenario-z13" + rec=$(make_spawn_case "profile-selected-seat-$scenario" codex "$id") + read_case_record "$rec" + enable_dispatch_profile "$HOME_DIR" + record_dispatch "$HOME_DIR" "$id" clear codex gpt-5 high devprimary + seat_home="$CASE_DIR/seat home" + mkdir -p "$seat_home" + printf '%s\n' '{"OPENAI_API_KEY":"sk-fm-synthetic"}' > "$seat_home/auth.json" + jq -n --arg home "$seat_home" \ + '{version:1,id:"selection-dock",seats:{luna:{harness:"codex",credential_home:$home},devprimary:{harness:"codex",credential_home:$home}}}' \ + > "$HOME_DIR/config/dock.json" + cat > "$FAKEBIN_DIR/codex" <<'SH' +#!/usr/bin/env bash +if [ "${1:-}" = login ] && [ "${2:-}" = status ]; then + echo 'Logged in using ChatGPT' >&2 +fi +SH + chmod +x "$FAKEBIN_DIR/codex" + args=("$id" "$PROJ_DIR" --harness codex --model gpt-5 --effort high) + case "$scenario" in + refused) args+=(--seat luna) ;; + override) args+=(--seat luna --dispatch-override 'standing worker seat rule') ;; + matching) args+=(--seat devprimary --seat-home "$seat_home") ;; + omitted) : ;; + batch) args=("$id=$PROJ_DIR" --harness codex --model gpt-5 --effort high --seat luna --dispatch-override='standing worker seat rule') ;; + esac + out=$(run_ship_spawn "$HOME_DIR" "$WT_DIR" "$FAKEBIN_DIR" "$LAUNCH_LOG" "${args[@]}") + status=$? + case "$scenario" in + refused|omitted) + expect_code 1 "$status" "seat $scenario must refuse without an override: $out" + assert_contains "$out" '--seat devprimary' "refusal must name the selected seat" + assert_contains "$out" '--dispatch-override ' "refusal must explain the override" + assert_absent "$HOME_DIR/state/$id.meta" "refused seat must not publish metadata" + assert_equals '' "$(cat "$LAUNCH_LOG")" "refused seat must not launch" + ;; + *) + expect_code 0 "$status" "seat $scenario must launch: $out" + assert_grep "seat_home=$seat_home" "$HOME_DIR/state/$id.meta" "seat binding was lost" + assert_contains "$(cat "$LAUNCH_LOG")" "CODEX_HOME='$seat_home'" "launch lost seat home" + if [ "$scenario" = matching ]; then + assert_grep 'seat=devprimary' "$HOME_DIR/state/$id.meta" "matching seat was lost" + assert_no_grep 'dispatch_override=' "$HOME_DIR/state/$id.meta" "matching seat needs no override" + else + assert_grep 'seat=luna' "$HOME_DIR/state/$id.meta" "override seat was lost" + assert_grep 'dispatch_override=standing worker seat rule' "$HOME_DIR/state/$id.meta" "override reason was lost" + fi + ;; + esac + done + pass "recorded seats bind launches; explicit overrides permit dock-resolved luna on single and batch paths" +} + +test_recorded_dispatch_selection_leaves_unset_effort_unbound() { + local rec id out status + id=profile-selected-fallback-z13 + rec=$(make_spawn_case profile-selected-fallback claude "$id") + read_case_record "$rec" + enable_dispatch_profile "$HOME_DIR" + record_dispatch "$HOME_DIR" "$id" clear codex gpt-5 '' + + out=$(run_ship_spawn "$HOME_DIR" "$WT_DIR" "$FAKEBIN_DIR" "$LAUNCH_LOG" \ + "$id" "$PROJ_DIR" --harness codex --model gpt-5 --effort low) + status=$? + expect_code 0 "$status" "a fallback effort beside a selection with no effort should launch: $out" + assert_meta_profile "$HOME_DIR/state/$id.meta" codex gpt-5 low + assert_no_grep 'dispatch_override=' "$HOME_DIR/state/$id.meta" "the documented effort fallback should need no override" + pass "an effort the clear selection leaves unset is not bound" +} + +# A raw command keeps its own options, so matching --harness/--model/--effort +# beside it proves nothing about what the worker runs. +test_recorded_dispatch_selection_refuses_raw_launch_without_override() { + local rec id out status + id=profile-selected-raw-z13 + rec=$(make_spawn_case profile-selected-raw claude "$id") + read_case_record "$rec" + enable_dispatch_profile "$HOME_DIR" + record_dispatch "$HOME_DIR" "$id" clear claude haiku low + + out=$(run_ship_spawn "$HOME_DIR" "$WT_DIR" "$FAKEBIN_DIR" "$LAUNCH_LOG" \ + "$id" "$PROJ_DIR" "claude --model opus --effort high" --model haiku --effort low) + status=$? + expect_code 1 "$status" "a raw command under a clear selection should be refused without an override" + assert_contains "$out" 'launch flags do not match the clear dispatch selection --harness claude --model haiku --effort low' "spawn did not name the recorded selection" + assert_absent "$HOME_DIR/state/$id.meta" "a refused raw launch should not publish the task" + assert_equals '' "$(cat "$LAUNCH_LOG")" "a refused raw launch must not create a worker" + + out=$(run_ship_spawn "$HOME_DIR" "$WT_DIR" "$FAKEBIN_DIR" "$LAUNCH_LOG" \ + "$id" "$PROJ_DIR" "claude --model opus --effort high" --dispatch-override 'captain asked for opus') + status=$? + expect_code 0 "$status" "a raw command with a recorded task override should launch: $out" + assert_grep 'dispatch_override=captain asked for opus' "$HOME_DIR/state/$id.meta" "task record omitted the override reason" + pass "a clear dispatch selection refuses a raw launch command unless a task override is recorded" +} + +test_active_dispatch_without_task_record_is_refused() { + local rec id out status + id=profile-unrecorded-z13 + rec=$(make_spawn_case profile-unrecorded claude "$id") + read_case_record "$rec" + enable_dispatch_profile "$HOME_DIR" + + out=$(run_ship_spawn "$HOME_DIR" "$WT_DIR" "$FAKEBIN_DIR" "$LAUNCH_LOG" \ + "$id" "$PROJ_DIR" --harness codex --model gpt-5 --effort high) + status=$? + expect_code 1 "$status" "an active dispatch spawn with no task record should be refused" + assert_contains "$out" "has no recorded dispatch resolution; run bin/fm-dispatch-resolve.sh" "refusal did not name the resolver command" + assert_absent "$HOME_DIR/state/$id.meta" "an unrecorded dispatch should refuse before task publication" + assert_equals '' "$(cat "$LAUNCH_LOG")" "an unrecorded dispatch must not create a worker" + pass "active dispatch refuses a spawn whose task has no recorded resolution" +} + +test_batch_checks_each_task_against_its_own_record() { + local rec id1 id2 out status + id1=profile-batch-own-a-z13 + id2=profile-batch-own-b-z13 + rec=$(make_spawn_case profile-batch-own claude "$id1" "$id2") + read_case_record "$rec" + enable_dispatch_profile "$HOME_DIR" + record_dispatch "$HOME_DIR" "$id1" clear codex gpt-5 high + record_dispatch "$HOME_DIR" "$id2" clear claude opus high + + out=$(run_ship_spawn "$HOME_DIR" "$WT_DIR" "$FAKEBIN_DIR" "$LAUNCH_LOG" \ + "$id1=$PROJ_DIR" "$id2=$PROJ_DIR" --harness codex --model gpt-5 --effort high) + status=$? + expect_code 1 "$status" "a batch with one conflicting task record should report failure" + assert_meta_profile "$HOME_DIR/state/$id1.meta" codex gpt-5 high + assert_absent "$HOME_DIR/state/$id2.meta" "the task whose record selects claude must not launch codex" + assert_contains "$out" "batch: FAILED to spawn $id2" "batch did not name the refused task" + pass "batch dispatch checks each task against its own recorded selection" } test_active_dispatch_profile_allows_positional_harness() { @@ -534,6 +737,7 @@ test_active_dispatch_profile_allows_positional_harness() { rec=$(make_spawn_case profile-positional claude "$id") read_case_record "$rec" enable_dispatch_profile "$HOME_DIR" + record_dispatch "$HOME_DIR" "$id" clear codex gpt-5 high out=$(run_ship_spawn "$HOME_DIR" "$WT_DIR" "$FAKEBIN_DIR" "$LAUNCH_LOG" \ "$id" "$PROJ_DIR" codex --model gpt-5 --effort high) @@ -636,6 +840,7 @@ test_active_dispatch_profile_allows_raw_launch_command() { rec=$(make_spawn_case profile-raw claude "$id") read_case_record "$rec" enable_dispatch_profile "$HOME_DIR" + record_dispatch "$HOME_DIR" "$id" off out=$(run_ship_spawn "$HOME_DIR" "$WT_DIR" "$FAKEBIN_DIR" "$LAUNCH_LOG" \ "$id" "$PROJ_DIR" "custom-agent --flag") @@ -1736,6 +1941,8 @@ test_batch_preserves_native_ultra() { rec=$(make_spawn_case ultra-batch pi "$id1" "$id2") read_case_record "$rec" enable_dispatch_profile "$HOME_DIR" + record_dispatch "$HOME_DIR" "$id1" clear pi codex-native/gpt-6-astra ultra + record_dispatch "$HOME_DIR" "$id2" clear pi codex-native/gpt-6-astra ultra out=$(run_ship_spawn "$HOME_DIR" "$WT_DIR" "$FAKEBIN_DIR" "$LAUNCH_LOG" \ "$id1=$PROJ_DIR" "$id2=$PROJ_DIR" --harness pi --model codex-native/gpt-6-astra --effort ultra) expect_code 0 "$?" "native Ultra batch failed: $out" @@ -2278,6 +2485,8 @@ test_batch_forwards_shared_profile_flags() { rec=$(make_spawn_case profile-batch claude "$id1" "$id2") read_case_record "$rec" enable_dispatch_profile "$HOME_DIR" + record_dispatch "$HOME_DIR" "$id1" clear codex gpt-5 high + record_dispatch "$HOME_DIR" "$id2" escalate out=$(run_ship_spawn "$HOME_DIR" "$WT_DIR" "$FAKEBIN_DIR" "$LAUNCH_LOG" \ "$id1=$PROJ_DIR" "$id2=$PROJ_DIR" --harness codex --model gpt-5 --effort high) @@ -3386,6 +3595,14 @@ test_unresolvable_relative_overrides_fail_loudly test_active_dispatch_profile_requires_explicit_harness_for_ship test_active_dispatch_profile_requires_explicit_harness_for_scout test_active_dispatch_profile_allows_explicit_harness +test_recorded_dispatch_selection_refuses_conflicting_flags +test_recorded_dispatch_selection_allows_matching_flags +test_recorded_dispatch_selection_allows_recorded_override +test_recorded_dispatch_selection_binds_seat +test_recorded_dispatch_selection_leaves_unset_effort_unbound +test_recorded_dispatch_selection_refuses_raw_launch_without_override +test_active_dispatch_without_task_record_is_refused +test_batch_checks_each_task_against_its_own_record test_active_dispatch_profile_allows_positional_harness test_active_dispatch_profile_allows_raw_launch_command test_raw_launch_trailing_separator_or_comment_keeps_disarm From 594107f231f84d0e6f5cfab84be2a9a74fe0a51f Mon Sep 17 00:00:00 2001 From: jazz127 Date: Wed, 11 Nov 2026 20:39:16 +1000 Subject: [PATCH 2/2] no-mistakes(document): Clarify dispatch binding and seat override documentation --- bin/fm-dispatch-resolve.sh | 13 +++++-------- bin/fm-spawn.sh | 16 ++++++++++++---- docs/configuration.md | 13 ++++++++----- 3 files changed, 25 insertions(+), 17 deletions(-) diff --git a/bin/fm-dispatch-resolve.sh b/bin/fm-dispatch-resolve.sh index 6b3e9a0cab8..fd4ceb1ca94 100755 --- a/bin/fm-dispatch-resolve.sh +++ b/bin/fm-dispatch-resolve.sh @@ -99,17 +99,14 @@ # candidate: : provider=.. scope=.. remaining=..% spendPriority=.. runway=.. -> eligible | eligible, unranked: | not eligible: # (with the shared-quota opt-out: : provider=.. -> eligible (quota ranking off: home declares a single shared quota)) # profile: --harness [--model ] [--effort ] [--seat ] [--seat-home ] (status clear only) -# Task record: for //brief.md, where is FM_DATA_OVERRIDE, -# else $FM_HOME/data, every run first removes -# //dispatch-resolution.json, then every outcome except exit 2 writes -# {"task", "status" (clear, ambiguous, escalate, error, or off), "profile"} -# there; profile holds harness, model, effort, and seat on clear and is null -# otherwise. fm-spawn.sh reads it as the task's dispatch decision. -# 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 diff --git a/bin/fm-spawn.sh b/bin/fm-spawn.sh index 74326da5e27..e23914fd7b2 100755 --- a/bin/fm-spawn.sh +++ b/bin/fm-spawn.sh @@ -102,6 +102,10 @@ # only a shell that will not go refuses. # --harness is the explicit per-spawn harness/profile adapter. The old # positional harness arg still works for back-compat. +# --dispatch-override records a non-empty printable reason as +# dispatch_override= in state/.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 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 @@ -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 @@ -384,11 +390,13 @@ # Batch dispatch: pass one or more `id=repo` pairs instead of a single , 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: diff --git a/docs/configuration.md b/docs/configuration.md index 5d6d0f7e369..132a86e80d4 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1506,13 +1506,15 @@ Remote secondmate routes accept verified harness adapters only and reject raw la When `config/crew-dispatch.json` exists, crewmate and scout spawns require an explicit resolved harness instead of automatically falling back to `config/crew-harness`. Such a spawn also refuses until `bin/fm-dispatch-resolve.sh data//brief.md` has written that task's record, `data//dispatch-resolution.json`. Both paths are under `FM_DATA_OVERRIDE` instead of `data/` when it is set. +An absent or malformed record refuses even when an override reason is supplied. When the record is `clear`, the spawn must match its harness and logical seat (including no seat), and its model and effort where the record sets them, with no raw launch command, unless `--dispatch-override ` records a task override in `state/.meta` as `dispatch_override=`. +A standing worker-seat rule that selects a different logical seat requires this task override too. A model or effort the record leaves empty is not bound, so the documented effort fallback still applies. When the record is `ambiguous`, `escalate`, `error`, or `off`, the explicit flags from the manual intake are enough. An `fm-spawn.sh --relaunch` skips this check. The inherited-local-material contract is owned by [`secondmate-provisioning`](../.agents/skills/secondmate-provisioning/SKILL.md); its harness-relevant consequence is that a secondmate's own crewmates use the primary's dispatch profiles and static harness value. -Those inherited values are defaults and rules only; `fm-spawn` still permits a consciously chosen explicit runtime outside the config. +An explicit runtime outside those inherited values follows the per-launch override requirements above. `config/secondmate-harness` is not inherited because secondmates do not launch secondmates. @@ -2126,7 +2128,7 @@ See [`docs/examples/crew-dispatch.json`](examples/crew-dispatch.json) for a star An OpenRouter key or OpenRouter declaration alone does not enable these bootstrap checks; the resolver validates those declarations itself before any request. Without a typesafe key or a declared typesafe source, bootstrap retains its pre-existing verified-harness baseline. - Missing `jq` is reported through the normal `MISSING: jq` install-consent flow. -- While the file remains present, no crewmate or scout spawn may proceed without an explicit resolved harness; malformed configuration must be reported and corrected rather than selected around. +- Spawn requirements are owned by [Per-launch overrides and inherited defaults](#per-launch-overrides-and-inherited-defaults); malformed configuration must be reported and corrected rather than selected around. **Inheritance** @@ -2305,14 +2307,15 @@ By accepted design, a `clear` result does not enforce catalog/authentication, re Firstmate still applies those gates before dispatch, including when `preferred_provider` is present. Explicit captain overrides retain precedence over the resolver's suggestion. -Firstmate passes its profile line unless it states a reason to override, such as the brief's reasoning class or an eligible-unranked-candidate note; every non-clear result returns to the full existing intake. +Launch binding and reasoned overrides follow [Per-launch overrides and inherited defaults](#per-launch-overrides-and-inherited-defaults); `AGENTS.md` section 4 owns the intake for non-clear results. **Task record (data//dispatch-resolution.json)** -For a brief at `data//brief.md`, or `//brief.md` when that override is set, each run first removes that task's `dispatch-resolution.json`, so a decision never outlives a later run. -Every outcome that exits 0, including off, then writes one JSON object there: `task` (the ``), `status` (`clear`, `ambiguous`, `escalate`, `error`, or `off`), and `profile`. +For a brief at `data//brief.md`, or `//brief.md` when that override is set, the resolver removes that task's previous `dispatch-resolution.json` after parsing its arguments and before resolving the task. +Every outcome that exits 0, including off, then attempts to write one JSON object there: `task` (the ``), `status` (`clear`, `ambiguous`, `escalate`, `error`, or `off`), and `profile`. On `clear`, `profile` holds `harness`, `model`, `effort`, and `seat`, each `null` when the chosen profile leaves it unset; otherwise `profile` is `null`. A usage or configuration error (exit 2) writes no record. +A write failure is reported on stderr and can leave no record even with exit 0. `fm-spawn.sh` reads this record as the task's decision, as "Per-launch overrides and inherited defaults" describes. **Credential source declaration (config/dispatch-credential-sources.json)**