@mmerterden/multi-agent-pipeline 20.20.0 → 20.22.0

package/pipeline/commands/multi-agent/setup/SKILL.md

@@ -24,6 +24,10 @@ node "$HOME/.claude/scripts/doctor.mjs"
 
 Run it before the first question and again at the end. The first run turns setup from a fixed script into a targeted one: there is no point asking for a token that is already mapped and answering. The second run is the only honest way to end - "setup complete" is a claim, and the doctor's exit code is the evidence for or against it. Report both in `outputLanguage`, and if the second run still shows a BLOCK, say so plainly rather than closing on the word "complete".
 
+## Sections
+
+`/multi-agent:setup hosts`: the Step 3.5 host prompt per mapped hosted service, then Token Save Flow Step 3.7 per mapped GitHub/Bitbucket token. `accounts`: Step 3.6. `jira-keys`: the Jira key mapping. Tokens are left alone.
+
 ## Setup (Credential Store + Git Identity Onboarding)
 
 Uses `$HOME/.claude/lib/credential-store.sh` to read/write secrets in the macOS Keychain (`security`, built in). The pipeline is macOS only (ADR-0012).
@@ -209,11 +213,12 @@ The Step 2 discovery summary is never the end of setup. Immediately after showin
 10. `jenkins`
 11. App Store Connect block (Step 3b; only when the target repo is iOS)
 12. Google Play block (Step 3d; only when the target repo is Android)
+13. Free-model keys `llm-<id>` (only after `route-on --free`): `$HOME/.claude/multi-agent-refs/setup/free-models.md`
 
 Loop rules:
 
 - **One prompt per service.** Never collapse the list into a single "add missing tokens now?" yes/no, and never offer one multi-select covering all services: each service has its own source URL, key name, identity binding and host prompt, so each gets its own Token Save Flow pass.
-- **Each service pass asks, in order: token → author → host.** Step A/B collect the secret, Step C binds the git identity (author)  -  Bitbucket and GitHub included; every saved token gets an author  -  and Step 3.5 asks the host domain inline for hosted services (jira, confluence, bitbucket, fortify, graylog) - plus the Fortify project versions and the optional Graylog test instance. GitHub and Figma skip the host question (fixed domains); `bitbucket_user` skips author binding (username, not a PAT). Never end a service pass with the token saved but the author or a required host unasked.
+- **Each service pass asks, in order: token → author → host → read binding (GitHub, Bitbucket; Token Save Flow Step 3.7).** Step A/B collect the secret, Step C binds the git identity (author)  -  Bitbucket and GitHub included; every saved token gets an author  -  and Step 3.5 asks the host domain inline for hosted services (jira, confluence, bitbucket, fortify, graylog) - plus the Fortify project versions and the optional Graylog test instance. GitHub and Figma skip the host question (fixed domains); `bitbucket_user` skips author binding (username, not a PAT). Never end a service pass with the token saved but the author or a required host unasked.
 - **Skip is per-service.** A Skip answer leaves that service's `keychainMapping` at `null` and the loop continues with the next service. Skips never abort the loop.
 - **`figma` and `figma_mcp` are distinct credentials for distinct tiers  -  ask both.** Skipping the PAT does not imply skipping MCP, and vice versa. The `figma_mcp` pass opens with a Remote / Local mode question instead of a clipboard paste (see "Figma MCP Setup" below): Remote generates a `figu_` OAuth token for the current user, Local wires the PAT-based local server.
 - The loop ends only when every missing service has been asked exactly once; then continue to Step 4 (Verify all).
@@ -256,23 +261,10 @@ Use the global default ({hosts.jira}) or set a per-account host?
   2) Set per-account host
 ```
 
-If `2`, prompt for `jiraHost` / `bitbucketHost` / `confluenceHost` (each optional). Save to `prefs.global.accounts[]`:
-
-```json
-{
-  "global": {
-    "accounts": [
-      { "id": "personal", "jiraHost": "personal.atlassian.net" },
-      { "id": "client-x", "jiraHost": "client-x.atlassian.net", "bitbucketHost": "bitbucket.client-x.com" }
-    ]
-  }
-}
-```
+If `2`, prompt for `jiraHost` / `bitbucketHost` / `confluenceHost` (each optional). Save to `prefs.global.accounts[]` as `{ \"id\": \"client-x\", \"jiraHost\": \"client-x.atlassian.net\", \"bitbucketHost\": \"bitbucket.client-x.com\" }`.
 
 `account-resolver.sh` reads this on every invocation; per-account override wins over `global.hosts.*`. Skip this step on autopilot  -  `accounts[]` stays empty until the user opts in via `/multi-agent:setup accounts`.
 
-**Re-run / update**: `/multi-agent:setup accounts` opens the editor for this block without re-running token discovery.
-
 ---
 
 ### Step 4  -  Verify all
@@ -377,7 +369,7 @@ Standard key names are a convention for NEW tokens; discovery may find existing
 
 ### Inline Token Save Pattern
 
-All tokens go through `~/.claude/lib/credential-store.sh`, which auto-delegates to the deterministic Python helper (`~/.claude/scripts/keychain.py`). The Python path writes both `-l` (label) and `-s` (service) attributes so existing manually-added entries with either convention remain findable.
+All tokens go through `~/.claude/lib/credential-store.sh` (Python helper and label/service attributes: see "Setup" above).
 
 ```bash
 # PAT / API Key / JSON contents (from clipboard)

package/pipeline/lib/model-dispatch.sh

@@ -9,11 +9,11 @@
 #   model-dispatch.sh <call-site> [--persona P] [--phase N] [--task-kind K]
 #                                 [--default RUNG] [--task-id ID]
 #
-# <call-site> is one of the `scope` members: subagent | bulk-read | research.
-# stdout is a single rung NAME. Rung names are the contract; the model id behind
-# one lives in cost-table.json and moves without a config edit.
+# <call-site> is one of the `scope` members: subagent | bulk-read | delegate |
+# research. stdout is a single rung NAME. Rung names are the contract; the model
+# id behind one lives in cost-table.json and moves without a config edit.
 #
-# Exit is always 0 and stdout is always a usable rung. A router that can fail
+# Exit is always 0 and stdout is always a usable answer. A router that can fail
 # turns every call site into a place the run can die, for a feature that ships
 # disabled; when anything is missing, unparseable or out of scope, the caller's
 # default comes back unchanged.
@@ -22,16 +22,18 @@
 #
 #   Layer 1  an Anthropic rung. Reachable from every call site, because it
 #            writes to a seam that already exists and opens no new network path.
-#   Layer 2  a non-Anthropic rung. NO call site can dispatch to one today, and
-#            the router refuses it rather than returning a rung its caller will
-#            hand to a CLI that does not know the name:
-#              - a subagent is dispatched by the HOST;
-#              - bulk-read shells out to `claude -p --model <rung>`;
-#              - research_ask runs in the MCP server and picks its own model.
-#            `provider` in cost-table.json is what makes this checkable, and it
-#            is the seam a future call site would use. Until one exists, the
-#            refusal is the honest answer: an allowed rung nothing can honour is
-#            a rule the user believes worked.
+#   Layer 2  the `free` rung: the multi-agent-toolkit's verified free-model
+#            chain. Reachable only where the pipeline makes the call itself -
+#            bulk-read and delegate - and only with modelRouting.free.enabled.
+#            Its caller must keep its default as the fallback, because the chain
+#            answers ESCALATE_TO_CLAUDE whenever no free answer survives
+#            verification. A subagent is dispatched by the HOST, so `free` and
+#            every other non-Anthropic rung is refused there and the rule's next
+#            rung answers instead.
+#
+# Strategies: manual keeps the rule's order; task-fit tries the cheapest rung
+# first; cost-ceiling keeps the order until cost-budget-check.mjs reports the run
+# at its warn threshold of budgetCeilingUsd, then tries the cheapest first.
 
 set -uo pipefail
 
@@ -74,7 +76,7 @@ fi
 [ "$DEFAULT_RUNG" = "fable" ] && [ "$FABLE_ON" != "true" ] && DEFAULT_RUNG="opus"
 
 case "$CALL_SITE" in
-  subagent|bulk-read|research) ;;
+  subagent|bulk-read|delegate|research) ;;
   *) emit "$DEFAULT_RUNG" ;;
 esac
 
@@ -103,11 +105,45 @@ MATCH=$(jq -r \
          and ((.when.taskKind // null) as $k | $k == null or $k == $kind)
        )
    ] | first | (.prefer // []) | join(" ")' "$PREFS" 2>/dev/null) || emit "$DEFAULT_RUNG"
-[ -n "$MATCH" ] && [ "$MATCH" != "null" ] || emit "$DEFAULT_RUNG"
+[ "$MATCH" = "null" ] && MATCH=""
+
+FREE_ON=$(jq -r '.global.modelRouting.free.enabled // false' "$PREFS" 2>/dev/null)
+CANDIDATES="$MATCH"
+case "$CALL_SITE" in
+  bulk-read|delegate) [ "$FREE_ON" = "true" ] && CANDIDATES="free $MATCH" ;;
+esac
+[ -n "${CANDIDATES// /}" ] || emit "$DEFAULT_RUNG"
 
 HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 COST_TABLE="$HERE/../scripts/cost-table.json"
 
+STRATEGY=$(jq -r '.global.modelRouting.strategy // "manual"' "$PREFS" 2>/dev/null)
+CHEAPEST_FIRST=false
+STRATEGY_NOTE=""
+case "$STRATEGY" in
+  task-fit) CHEAPEST_FIRST=true; STRATEGY_NOTE="task-fit" ;;
+  cost-ceiling)
+    CEILING=$(jq -r '.global.modelRouting.budgetCeilingUsd // empty' "$PREFS" 2>/dev/null)
+    if [ -n "$CEILING" ] && [ "$TASK_ID" != "unknown" ] && command -v node >/dev/null 2>&1 \
+       && [ -f "$HERE/../scripts/cost-budget-check.mjs" ]; then
+      node "$HERE/../scripts/cost-budget-check.mjs" --task-id "$TASK_ID" --max-usd "$CEILING" --enabled >/dev/null 2>&1
+      case $? in
+        10|11) CHEAPEST_FIRST=true; STRATEGY_NOTE="cost-ceiling reached" ;;
+      esac
+    fi
+    ;;
+esac
+
+if [ "$CHEAPEST_FIRST" = "true" ] && [ -f "$COST_TABLE" ]; then
+  CANDIDATES=$(
+    jq -r --arg c "$CANDIDATES" '
+      .prices as $p
+    | ($c | split(" ") | map(select(length > 0)))
+    | to_entries
+    | sort_by([($p[.value].inPerMtok // 1e9), .key])
+    | map(.value) | join(" ")' "$COST_TABLE" 2>/dev/null || printf '%s' "$CANDIDATES")
+fi
+
 # The fable rung answers only when the fable switch is on (FABLE_ON, read
 # above). Routing is a policy over what is available; it is not a second way to
 # turn a rung on, or `/multi-agent:model off` would stop meaning anything the
@@ -116,13 +152,13 @@ COST_TABLE="$HERE/../scripts/cost-table.json"
 record() {
   [ -x "$HERE/../scripts/log-metric.sh" ] || return 0
   local rec
-  rec=$(jq -r '.global.modelRouting.recordDecisions // true' "$PREFS" 2>/dev/null)
+  rec=$(jq -r 'if .global.modelRouting.recordDecisions == false then "false" else "true" end' "$PREFS" 2>/dev/null)
   [ "$rec" = "false" ] && return 0
   "$HERE/../scripts/log-metric.sh" "$TASK_ID" "${PHASE:-0}" model_routing.decision \
     call_site="$CALL_SITE" rung="$1" reason="$2" >/dev/null 2>&1 || true
 }
 
-for rung in $MATCH; do
+for rung in $CANDIDATES; do
   if [ ! -f "$COST_TABLE" ]; then
     record "$rung" "no cost table; rung taken on trust"
     emit "$rung"
@@ -139,15 +175,27 @@ for rung in $MATCH; do
     echo "model-dispatch: rule prefers 'fable' but modelFallback.fableEnabled is false; skipping it" >&2
     continue
   fi
+  if [ "$PROVIDER" = "free-chain" ]; then
+    if [ "$FREE_ON" != "true" ]; then
+      echo "model-dispatch: rule prefers 'free' but modelRouting.free.enabled is false (route-on --free); skipping it" >&2
+      continue
+    fi
+    case "$CALL_SITE" in
+      bulk-read|delegate)
+        record "$rung" "free chain${STRATEGY_NOTE:+, $STRATEGY_NOTE}"
+        emit "$rung" ;;
+    esac
+    echo "model-dispatch: rung 'free' is reachable only at bulk-read and delegate; a $CALL_SITE is dispatched by the host, skipping it" >&2
+    continue
+  fi
   if [ "$PROVIDER" != "anthropic" ]; then
-    # The honest limit, said out loud at the moment it bites. Every call site
-    # that asks here hands the rung to something that only speaks the Anthropic
-    # ladder, so returning an external rung would produce a failed call rather
-    # than a cheaper one.
-    echo "model-dispatch: rung '$rung' is $PROVIDER and no call site can dispatch to one yet; skipping it" >&2
+    # Every call site that asks here hands any other rung to something that
+    # speaks the Anthropic ladder or the free chain, so returning an external
+    # rung would produce a failed call rather than a cheaper one.
+    echo "model-dispatch: rung '$rung' is $PROVIDER and no call site dispatches to it; skipping it" >&2
     continue
   fi
-  record "$rung" "rule matched"
+  record "$rung" "rule matched${STRATEGY_NOTE:+, $STRATEGY_NOTE}"
   emit "$rung"
 done
 

package/pipeline/lib/outbound-gate.mjs

@@ -82,6 +82,8 @@ export const RULES = [
   { name: "stripe-key", certain: true, re: /\b[sr]k_live_[A-Za-z0-9]{20,}\b/g },
   { name: "perplexity-key", certain: true, re: /\bpplx-[A-Za-z0-9]{32,}\b/g },
   { name: "huggingface-token", certain: true, re: /\bhf_[A-Za-z0-9]{30,}\b/g },
+  { name: "groq-key", certain: true, re: /\bgsk_[A-Za-z0-9]{40,}\b/g },
+  { name: "openrouter-key", certain: true, re: /\bsk-or-v1-[A-Za-z0-9]{40,}\b/g },
   {
     name: "service-account-json",
     certain: true,

package/pipeline/lib/route-state.sh

@@ -10,10 +10,11 @@
 # for a configuration the user already gave.
 #
 # Usage:
-#   route-state.sh status                       print the current policy
-#   route-state.sh on  [--strategy=S] [--scope=a,b]
+#   route-state.sh status                       print the current policy and savings
+#   route-state.sh on  [--strategy=S] [--scope=a,b] [--free [--allow-training]] [--no-free]
 #   route-state.sh off
-#   route-state.sh set-rules <file.json>        replace rules[] from a JSON array
+#   route-state.sh set-rules <file.json>        replace rules[] from a JSON array,
+#                                               checked against the schema and cost table
 #
 # Exit codes:
 #   0  -  done
@@ -34,7 +35,7 @@ if [ -f "$_MA_RS_HERE/user-facing.sh" ]; then . "$_MA_RS_HERE/user-facing.sh"; e
 # included - through a third layer, breaks the subscription's auth model, and
 # silently changes which model answers. The schema encodes the same list so a
 # hand-edited preferences file is rejected too, rather than only this entry point.
-ALLOWED_SCOPE="subagent bulk-read research"
+ALLOWED_SCOPE="subagent bulk-read delegate research"
 
 die() { echo "route-state: $1" >&2; exit "${2:-3}"; }
 
@@ -47,6 +48,9 @@ jq -e . "$PREFS" >/dev/null 2>&1 || die "$PREFS is not valid JSON  -  refusing t
 
 ACTION="${1:-status}"; shift 2>/dev/null || true
 
+COST_TABLE="$_MA_RS_HERE/../scripts/cost-table.json"
+USAGE_LOG="${MCP_TOOLKIT_INDEX_DIR:-$HOME/.claude/logs/multi-agent-toolkit/.index}/llm-usage.jsonl"
+
 write_prefs() {
   local filter="$1"; shift
   local tmp
@@ -56,6 +60,57 @@ write_prefs() {
   mv "$tmp" "$PREFS"
 }
 
+# Last seven days of the toolkit's usage logs (attended, and an unattended run's
+# own under ~/.multi-agent-unattended): verified answers, cache hits and
+# escalations, and what those tokens would have cost on haiku, the rung bulk-read
+# and simple tasks fall back to. An estimate, and labelled as one.
+free_savings() {
+  local logs=() f
+  for f in "$USAGE_LOG" "$HOME/.multi-agent-unattended/toolkit-index/llm-usage.jsonl"; do
+    [ -f "$f" ] && logs+=("$f")
+  done
+  if [ "${#logs[@]}" -eq 0 ]; then
+    echo "savings: no free-model task recorded yet ($USAGE_LOG)"
+    return 0
+  fi
+  local since
+  since=$(( $(date +%s) - 7 * 86400 ))
+  jq -rs --argjson since "$since" --slurpfile ct "$COST_TABLE" '
+      map(select((.ts | sub("\\.[0-9]+Z$"; "Z") | fromdateiso8601? // 0) >= $since))
+    | ($ct[0].prices.haiku // {inPerMtok: 1, outPerMtok: 5}) as $h
+    | {
+        n: length,
+        ok: (map(select(.ok and (.cached | not))) | length),
+        cached: (map(select(.ok and .cached)) | length),
+        esc: (map(select(.ok | not)) | length),
+        pin: (map(.prompt_tokens // 0) | add // 0),
+        pout: (map(.completion_tokens // 0) | add // 0),
+        by: (map(select(.ok and .provider)) | group_by(.provider) | map("\(.[0].provider) \(length)") | join(", "))
+      }
+    | . + {usd: ((.pin * $h.inPerMtok + .pout * $h.outPerMtok) / 1000000)}
+    | "savings (7 days): \(.n) task(s), \(.ok) answered free and verified, \(.cached) from cache, \(.esc) handed back to Claude\n"
+      + "  tokens kept off Claude: \(.pin) in + \(.pout) out  (~$\(.usd * 100 | round / 100) at haiku rates, an estimate)"
+      + (if .by != "" then "\n  by provider: \(.by)" else "" end)
+  ' "${logs[@]}" 2>/dev/null || echo "savings: the usage log could not be read"
+}
+
+# What the toolkit can reach, without a single network call: configured
+# providers and where their keys come from. Names only, never values.
+free_providers() {
+  local tl="$_MA_RS_HERE/toolkit-llm.sh"
+  [ -f "$tl" ] || tl="$HOME/.claude/lib/toolkit-llm.sh"
+  [ -f "$tl" ] || { echo "free chain: toolkit-llm.sh is not installed"; return 1; }
+  # shellcheck source=/dev/null
+  . "$tl"
+  local out
+  out=$(ma_toolkit_llm providers ${1:+--allow-training} 2>/dev/null) || { echo "free chain: the multi-agent-toolkit CLI could not be run (node and npx are needed)"; return 1; }
+  jq -r '
+      "free chain: \(.configured) provider(s) usable under the \(.data_policy) data policy",
+      (.providers[] | "  \(if .configured and .allowed_by_policy then "ready  " elif .configured then "policy " else "missing" end) \(.id)\(if .key_source then " (" + .key_source + ")" else "" end)\(if (.configured | not) then "  -  " + .setup else "" end)")
+    ' <<< "$out"
+  [ "$(jq -r '.configured' <<< "$out")" -gt 0 ]
+}
+
 case "$ACTION" in
   status)
     ENABLED=$(jq -r '.global.modelRouting.enabled // false' "$PREFS")
@@ -63,12 +118,16 @@ case "$ACTION" in
     SCOPE=$(jq -r '(.global.modelRouting.scope // ["subagent"]) | join(", ")' "$PREFS")
     NRULES=$(jq -r '(.global.modelRouting.rules // []) | length' "$PREFS")
     CEIL=$(jq -r '.global.modelRouting.budgetCeilingUsd // "none"' "$PREFS")
-    REC=$(jq -r '.global.modelRouting.recordDecisions // true' "$PREFS")
+    REC=$(jq -r 'if .global.modelRouting.recordDecisions == false then "false" else "true" end' "$PREFS")
+
+    FREE=$(jq -r '.global.modelRouting.free.enabled // false' "$PREFS")
+    TRAIN=$(jq -r '.global.modelRouting.free.allowTraining // false' "$PREFS")
 
     echo "routing:   $ENABLED"
     echo "strategy:  $STRATEGY"
     echo "scope:     $SCOPE"
     echo "rules:     $NRULES"
+    echo "free:      $FREE$([ "$FREE" = "true" ] && echo " (data policy: $([ "$TRAIN" = "true" ] && echo any || echo no-training))")"
     echo "ceiling:   $CEIL"
     echo "decisions: $REC"
     echo ""
@@ -79,34 +138,46 @@ case "$ACTION" in
       exit 0
     fi
 
-    if [ "$NRULES" -eq 0 ]; then
+    if [ "$NRULES" -eq 0 ] && [ "$FREE" != "true" ]; then
       echo "Armed with no rules. Nothing matches, so nothing is routed  -  this is a"
       echo "configuration state, not an error."
-    else
+    elif [ "$NRULES" -gt 0 ]; then
       jq -r '(.global.modelRouting.rules // [])[] |
         "  when " + ([.when | to_entries[] | "\(.key)=\(.value)"] | join(" ")) +
         "  ->  " + (.prefer | join(" > "))' "$PREFS"
     fi
 
+    if [ "$FREE" = "true" ]; then
+      echo "  free chain first at: bulk-read, delegate (Anthropic default when it escalates)"
+      echo ""
+      free_savings
+    fi
+
     echo ""
     # The limit is printed every time rather than documented once, because the
     # question it answers ("routing is on, why is the reviewer still on Opus")
     # otherwise arrives days later as a bug report.
     echo "Honest limit: on Claude Code a subagent cannot be sent to a non-Anthropic"
     echo "model  -  subagent dispatch belongs to the host. Phase 1/2/3 personas stay"
-    echo "inside the Anthropic ladder whatever the rules say. External providers apply"
-    echo "only where this pipeline makes the call itself (bulk-read, research)."
+    echo "inside the Anthropic ladder whatever the rules say. Free models answer only"
+    echo "where this pipeline makes the call itself (bulk-read, delegate), only after"
+    echo "the toolkit verified the answer against its source, and Claude takes over"
+    echo "whenever none passes."
     ;;
 
   on)
-    STRATEGY="manual"; SCOPE_ARG=""
+    STRATEGY="manual"; SCOPE_ARG=""; FREE_ARG=""; TRAIN_ARG=false
     for arg in "$@"; do
       case "$arg" in
         --strategy=*) STRATEGY="${arg#*=}" ;;
         --scope=*)    SCOPE_ARG="${arg#*=}" ;;
+        --free)       FREE_ARG=on ;;
+        --no-free)    FREE_ARG=off ;;
+        --allow-training) TRAIN_ARG=true ;;
         *) die "unknown option: $arg" 2 ;;
       esac
     done
+    [ "$TRAIN_ARG" = "true" ] && [ "$FREE_ARG" != "on" ] && die "--allow-training only goes with --free" 2
     case "$STRATEGY" in
       manual|task-fit|cost-ceiling) ;;
       *) die "strategy must be manual, task-fit or cost-ceiling (got '$STRATEGY')" 2 ;;
@@ -138,6 +209,26 @@ case "$ACTION" in
         | .global.modelRouting.scope //= ["subagent"]
       ' --arg st "$STRATEGY"
     fi
+    if [ "$FREE_ARG" = "on" ]; then
+      write_prefs '
+          .global.modelRouting.free = {enabled: true, allowTraining: $tr}
+        | .global.modelRouting.scope = (((.global.modelRouting.scope // ["subagent"]) + ["bulk-read", "delegate"]) | unique)
+      ' --argjson tr "$TRAIN_ARG"
+      echo "free chain enabled at bulk-read and delegate (data policy: $([ "$TRAIN_ARG" = "true" ] && echo any || echo no-training))"
+      TRAIN_FLAG=""
+      [ "$TRAIN_ARG" = "true" ] && TRAIN_FLAG=1
+      if ! free_providers "$TRAIN_FLAG"; then
+        echo ""
+        echo "No free provider is usable yet, so every task still runs on Claude. Add one key"
+        echo "(free at https://console.groq.com/keys) with $(ma_command setup), or from a shell:"
+        echo "  bash \"\$HOME/.claude/lib/credential-store.sh\" set llm-groq -    (paste the key, then Ctrl-D)"
+        echo "or export GROQ_API_KEY for the server, then run $(ma_command route-status)."
+      fi
+      echo ""
+    elif [ "$FREE_ARG" = "off" ]; then
+      write_prefs '.global.modelRouting.free.enabled = false'
+      echo "free chain disabled; Anthropic rungs only"
+    fi
     echo "routing enabled (strategy: $STRATEGY)"
     exec "$0" status
     ;;
@@ -154,6 +245,23 @@ case "$ACTION" in
     [ -n "$FILE" ] || die "set-rules needs a JSON file containing an array of rules" 2
     [ -f "$FILE" ] || die "no such file: $FILE" 2
     jq -e 'type == "array"' "$FILE" >/dev/null 2>&1 || die "$FILE must contain a JSON ARRAY of rules" 2
+    # The schema's rule shape, enforced here so a hand-written file cannot store
+    # a rule that dispatch silently skips: when has 1-3 known keys with valid
+    # values, prefer is a non-empty list of rungs the cost table prices.
+    RUNGS=$(jq -c '.prices | keys' "$COST_TABLE" 2>/dev/null || echo '[]')
+    BAD=$(jq -r --argjson rungs "$RUNGS" '
+        to_entries[] | .key as $i | .value as $r
+      | if ($r | type) != "object" then "rule \($i): not an object"
+        elif (($r | keys) - ["when", "prefer"]) != [] then "rule \($i): unknown key(s) \((($r | keys) - ["when", "prefer"]) | join(", "))"
+        elif ($r.when | type) != "object" or ($r.when | length) == 0 then "rule \($i): when needs persona, phase or taskKind"
+        elif (($r.when | keys) - ["persona", "phase", "taskKind"]) != [] then "rule \($i): when has unknown key(s) \((($r.when | keys) - ["persona", "phase", "taskKind"]) | join(", "))"
+        elif ($r.when.persona != null and ($r.when.persona | type) != "string") then "rule \($i): persona must be a string"
+        elif ($r.when.phase != null and (($r.when.phase | type) != "number" or $r.when.phase < 0 or $r.when.phase > 5 or ($r.when.phase | floor) != $r.when.phase)) then "rule \($i): phase must be an integer 0-5"
+        elif ($r.when.taskKind != null and ([$r.when.taskKind] | inside(["bugfix", "feature", "refactor", "chore", "component"]) | not)) then "rule \($i): taskKind must be bugfix, feature, refactor, chore or component"
+        elif ($r.prefer | type) != "array" or ($r.prefer | length) == 0 then "rule \($i): prefer needs at least one rung"
+        elif ([$r.prefer[] | select((type != "string") or (. as $x | $rungs | index($x) | not))] | length) > 0 then "rule \($i): unknown rung(s) \([$r.prefer[] | select((type != "string") or (. as $x | $rungs | index($x) | not))] | map(tostring) | join(", ")) (known: \($rungs | join(", ")))"
+        else empty end' "$FILE" 2>/dev/null)
+    [ -z "$BAD" ] || die "$(printf 'rules rejected, nothing written:\n%s' "$BAD")" 2
     write_prefs '.global.modelRouting //= {} | .global.modelRouting.rules = $r' --slurpfile _ignore /dev/null --argjson r "$(cat "$FILE")"
     echo "rules replaced: $(jq -r 'length' "$FILE")"
     ;;

package/pipeline/lib/toolkit-llm.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# toolkit-llm.sh  -  run the multi-agent-toolkit's free-model CLI.
+#
+# Sourced by bulk-read.sh and route-state.sh. `ma_toolkit_llm <args>` runs
+# `multi-agent-toolkit-llm <args>` from the first place it exists:
+#
+#   1. MULTI_AGENT_TOOLKIT_LLM            a path to the CLI script
+#   2. multi-agent-toolkit-llm on PATH    a global install
+#   3. npx -p @mmerterden/multi-agent-toolkit-mcp@latest, the same package
+#      the MCP registration runs
+#
+# A maintainer's working copy (prefs.global.devToolkit) is deliberately not a
+# source: it can sit on an unreleased branch, and a run should use what ships.
+#
+# The CLI prints one JSON object and exits 0 on a verified answer, 3 on
+# ESCALATE_TO_CLAUDE, 2 on a usage error. Any other status (no node, no network
+# for npx) is the caller's cue to keep its own default.
+
+ma_toolkit_llm() {
+  if [ -n "${MULTI_AGENT_TOOLKIT_LLM:-}" ] && [ -f "$MULTI_AGENT_TOOLKIT_LLM" ]; then
+    node "$MULTI_AGENT_TOOLKIT_LLM" "$@"
+    return $?
+  fi
+  if command -v multi-agent-toolkit-llm >/dev/null 2>&1; then
+    multi-agent-toolkit-llm "$@"
+    return $?
+  fi
+  command -v npx >/dev/null 2>&1 || return 127
+  npx -y --@mmerterden:registry=https://registry.npmjs.org -p @mmerterden/multi-agent-toolkit-mcp@latest multi-agent-toolkit-llm "$@"
+}

package/pipeline/lib/unattended-profile-check.mjs

@@ -22,9 +22,22 @@ import { join } from "node:path";
 
 const PREFS_HOST_KEYS = ["jira", "confluence", "bitbucket"];
 
+// The free-model hosts a sandboxed bulk-read may reach once route-on --free is
+// on: Groq alone under the default no-training policy, all five with
+// allowTraining. A local Ollama needs no host; allowLocalBinding covers it.
+const FREE_HOSTS_NO_TRAINING = ["api.groq.com"];
+const FREE_HOSTS_ANY = [
+  "api.groq.com",
+  "api.mistral.ai",
+  "generativelanguage.googleapis.com",
+  "openrouter.ai",
+  "api.z.ai",
+];
+
 /**
  * Hosts from prefs.global.hosts, so the sandbox's network list covers this
- * machine's own Jira / Confluence / Bitbucket.
+ * machine's own Jira / Confluence / Bitbucket, plus the free-model providers
+ * modelRouting.free allows.
  *
  * @param {string} home
  * @returns {string[]}
@@ -35,7 +48,7 @@ export function prefsHosts(home) {
       readFileSync(join(home, ".claude", "multi-agent-preferences.json"), "utf-8"),
     );
     const hosts = prefs?.global?.hosts || {};
-    return PREFS_HOST_KEYS.map((k) => hosts[k])
+    const own = PREFS_HOST_KEYS.map((k) => hosts[k])
       .filter((v) => typeof v === "string" && v.trim())
       .map(
         (v) =>
@@ -44,6 +57,14 @@ export function prefsHosts(home) {
             .replace(/^[a-z]+:\/\//i, "")
             .split("/")[0],
       );
+    const routing = prefs?.global?.modelRouting;
+    const free =
+      routing?.enabled === true && routing?.free?.enabled === true
+        ? routing.free.allowTraining === true
+          ? FREE_HOSTS_ANY
+          : FREE_HOSTS_NO_TRAINING
+        : [];
+    return [...own, ...free];
   } catch {
     return [];
   }

package/pipeline/multi-agent-refs/_dev-context.md

@@ -81,6 +81,21 @@ Selects extra repos the pipeline may touch beyond the primary repo(s)  -  typica
      | node $HOME/.claude/scripts/write-state.mjs "$STATE_FILE"
    ```
 
+6. **Product map (once per project, attended only).** If the project has never
+   answered, offer to map the product it belongs to, so Phase 1 can read the
+   other repositories of it:
+   ```bash
+   PRIMARY_REMOTE=$(git -C "$REPO_PATH" remote get-url origin)
+   node $HOME/.claude/scripts/product-context.mjs needs-mapping --project "$PRIMARY_REPO_NAME" --developed "$PRIMARY_REMOTE"
+   ```
+   Exit 3 = already answered, or the remote is already in a product: skip. Exit
+   0: list candidates with `repo-cache.sh` and `product-context.mjs suggest`
+   (commands in the contract). One multi-select of the suggestions (each with a stack the user sets; no
+   stack is guessed from a name), plus "not part of a product". Confirmed →
+   `product-context.mjs learn`; declined → `product-context.mjs decline`, which
+   stops the offer for good. Autopilot skips this step and uses the map as it
+   is. Contract: `$HOME/.claude/multi-agent-refs/features/product-context.md`.
+
 ## Web repos  -  `webRepos`
 
 Web repos are rarely submodules of the app repo, so submodule detection never finds them. `prefs.projects[<key>].webRepos[]` (or the pre-rename `frontendRepos[]`) is the primary source for them and is merged into the candidate list alongside the detected submodules. Only `/multi-agent:analysis` used to read this key, which meant the pipeline's own dev-context picker could not offer a web repo at all.

package/pipeline/multi-agent-refs/analysis/evidence.md

@@ -27,7 +27,11 @@ For each entry in `state.analysisSpec.contextLinks[]`, fan out by `type`. Entrie
 2. Surface a one-line warning to the user during Phase 1 progress output: `WARN: Confluence requires browser auth for <url>. Falling back to repo evidence; add the page text manually to /tmp/analysis-paste.md and re-run if needed.`
 3. Continue Phase 1 with remaining evidence sources rather than aborting.
 
-For each repo in `state.analysisSpec.repos[]`, run parallel greps (lightweight surface scan; the deeper 13-bucket extraction happens in Phase 1b):
+**Long sources:** with the free chain on, summarize long confluence/document/jira/generic-doc texts via `llm_delegate` first (`features/free-models.md`).
+
+For each repo in `state.analysisSpec.repos[]`, run parallel greps (lightweight surface scan; the deeper 13-bucket extraction happens in Phase 1b).
+
+Other repos are read at their latest branch via `repo_*` (`features/product-context.md`), shas in `evidence.repoShas[]`.
 
 ```bash
 # Localization
@@ -202,9 +206,9 @@ Phase 2 Section 20 Risks reads this list and emits one open question per entry.
 
 **Fallback source**: when `confidence == "none"` AND `evidence.standards[]` does not contain an explicit rule for that field, the renderer reads `$HOME/.claude/multi-agent-refs/conventions-defaults.md` and applies the platform default.
 
-**Caching (Locked 26)**: compute `evidence_digest = sha256(featureName || sorted(platforms) || options.redesign || hash(evidence.repoEvidence) || hash(evidence.conventions))`. `options.redesign` is a digest input: without it a redesign within a day of a normal run on the same feature reuses that cache, skips Phase 1b, and renders an empty current-behaviour table every redesign check then passes over. Cache key on disk: `/tmp/multi-agent-analysis-cache/<digest>.json` with mtime <= 24h. Cache hit skips Phase 1b and Phase 1c. `--no-cache` flag forces re-run.
+**Caching (Locked 26)**: compute `evidence_digest = sha256(featureName || sorted(platforms) || options.redesign || evidence.repoShas || hash(evidence.repoEvidence) || hash(evidence.conventions))`. `options.redesign` is an input so a redesign never reuses a normal run's cache, which would skip Phase 1b and render an empty current-behaviour table. Cache key on disk: `/tmp/multi-agent-analysis-cache/<digest>.json` with mtime <= 24h. Cache hit skips Phase 1b and Phase 1c. `--no-cache` flag forces re-run.
 
-Phase 1d is deliberately absent from the digest inputs. Community signal changes by the hour, so folding it in would produce a new digest on every run, invalidate the cache every time, and re-run the two expensive repo phases the cache exists to skip. The consequence is worth stating plainly: a cache hit reuses yesterday's signal rows. That is the correct trade for an advisory tier, and `--no-cache` is the way to refresh them.
+Phase 1d is not a digest input: community signal changes hourly and would invalidate the cache, re-running the two costly repo phases, every run. A hit reuses yesterday's advisory rows; `--no-cache` refreshes them.
 
 ### Phase 1d - Outside facts (optional, analyst toolkit)
 

package/pipeline/multi-agent-refs/analysis/locked.md

@@ -72,7 +72,7 @@ behind.
 23. **Convention extraction mandatory (Phase 1c).** After Phase 1b repo evidence, Phase 1c extracts seven pattern groups (folder structure, class naming, UI state model, test method naming, accessibility identifier, localization key, DI registration) per selected repo via `~/.claude/lib/extract-conventions.sh`. Output lands in `state.analysisSpec.evidence.conventions[<repo>]` with confidence levels (high / medium / low / none) and evidence file citations.
 24. **Pass B cell footnote mandatory.** Every cell Pass B fills in Section 13 (Architecture Plan concept table) and any other per-platform projection carries a footnote of the form `^[<convention-key> <confidence>: <evidence-source>]` pointing back to Phase 1c output. Cells with `confidence: low | none` cite `conventions-defaults.md:C<n>-<platform>` and emit a row in Section 20 Risks ("convention fallback applied"). Footnote-less cells fail the dispatch gate.
 25. **Pass B preview before render.** Phase 2a presents the resolved convention table to the user before Phase 2b emits any platform file. The user can approve, override individual cells, or cancel. Empty answers do not imply consent (`feedback_no-inferred-defaults-from-empty-answer`); the picker re-asks on empty submit.
-26. **Evidence digest caches Phase 1b and 1c.** `evidence_digest = sha256(featureName || sorted(platforms) || repoEvidence.summary || conventions.summary)`. When the same feature name is invoked again against the same set of repos and the digest matches, Phase 1b and 1c are skipped and the cached `evidence.repoEvidence` / `evidence.conventions` is reused. Cache TTL is 24 hours; manual invalidation via `--no-cache` flag.
+26. **Evidence digest caches Phase 1b and 1c.** `evidence_digest = sha256(featureName || sorted(platforms) || repoShas || repoEvidence.summary || conventions.summary)`. When the same feature name is invoked again against the same set of repos and the digest matches, Phase 1b and 1c are skipped and the cached `evidence.repoEvidence` / `evidence.conventions` is reused. Cache TTL is 24 hours; manual invalidation via `--no-cache` flag.
 27. **SwiftUI Preview block mandatory (iOS projection, SwiftUI only).** When the iOS file is produced AND the affected view is a SwiftUI view (detected via `import SwiftUI` + `: View` protocol conformance in `evidence.repoEvidence[<repo>].buckets.uiComponents`), Section 13.6 renders a Preview block table covering at minimum: canonical default (LTR Light), Dark, RTL, Dynamic Type accessibilityLarge, and one error variant. Loading state and edge-case variants are added when distinct from canonical. UIKit-only features (no SwiftUI view artefact) drop Section 13.6 with note `(N/A: UIKit-only feature)`. Preview macro convention (`#Preview` for Swift 5.9+ vs legacy `PreviewProvider`) is read from `evidence.conventions[<repo>].previewMacro`. Each Preview variant listed in Section 13.6 must have a matching row in Section 15.2 Snapshot Tests; a Preview without a snapshot row triggers a Section 20 Risk.
 28. **Variant usage explicit and bounded.** Section 6 inventory rows list which variants this feature consumes per component (concrete enum case + bool value). New Section 6.X (Variant Usage Matrix) catalogues the full variant axis vs. used subset with a rationale per excluded variant. Sections 13.6 (Preview) and 15.2 (Snapshot) cover only the used subset; expanding the variant set requires updating Section 6.X first.
 29. **Analysis as self-contained design bridge - no MCP outside analysis phase (BLOCKING, pipeline-wide).** The analysis document is the sole design source for every downstream phase. After Phase 1 of `/multi-agent:analysis` produces `analysis/<feature>-<platform>.md`, Phase 1 Plan, Phase 2 Dev, Phase 3 Review, Phase 4 Commit, and Phase 5 Report consume only the analysis document plus repo Code Connect mappings (`*.figma.swift` / `*.figma.kt`). Calling `mcp__claude_ai_Figma__*`, hitting `api.figma.com`, or fetching a `figma.com/design/...` URL during Phase 2+ is a violation. Applies to every mode that runs Phase 2+ (`/multi-agent` and `/multi-agent:autopilot`), in either workspace. Hard requirement (v9.0.0): Phase 2 Pre-item and Phase 3 Pre-item (BLOCKING) abort the run when the analysis document is missing. Memory: `[[mcp-only-in-analysis]]`. Generic rule rationale and access matrix: see `$HOME/.claude/rules/figma-pipeline.md` "MUST: No MCP outside analysis phase".

package/pipeline/multi-agent-refs/cross-cli-contract.md

@@ -115,6 +115,8 @@ it does not. Contracts: `features/exploratory-testing.md`,
 | Web states and locators | `web_route`, `web_network_state`, `web_clock`, `web_dialog`, `web_upload`, `web_drag`, `web_hover`, `web_fill_form`, `web_find`, `web_generate_locator`, `web_trace`; `request_id` on `web_network`; `locator` on `web_click` / `web_type` | ≥ v3.20.0 |
 | Document fetch and crawl | `web_scrape` (formats, cache, `change_tracking`), `url` / `sitemap` / `include_paths` / `llms_txt` on `web_crawl` and `web_map` | ≥ v3.20.0 |
 | Research modes and threads | `mode`, `recency`, `domains`, `sources`, `thread_id` on `research_ask`; `arxiv` and `fetch_content` on `research_search` | ≥ v3.20.0 |
+| Free-model delegation | `llm_delegate`, `llm_providers`; `ESCALATE_TO_CLAUDE`; the `multi-agent-toolkit-llm` CLI (`delegate`, `providers`, `probe`, `usage`) | ≥ v3.21.0 |
+| Related repositories | `repo_resolve`, `repo_grep`, `repo_read`, `repo_ls`, `repo_log`, `repo_find_keys`; `stale`, `not_found_at_sha` (`features/product-context.md`) | ≥ v3.22.1 |
 
 ---
 
@@ -270,9 +272,13 @@ happen.
 The routing trio (`route-on`, `route-off`, `route-status`) has no such split -
 it writes `prefs.global.modelRouting` identically everywhere. Its honest limit is
 different and applies on every host: a subagent cannot be dispatched to a
-non-Anthropic model, because subagent dispatch belongs to the host. External
-providers are reachable only where the pipeline makes the HTTP call itself
-(`bulk-read.sh`, `research_ask`). `route-status` prints that on every run.
+non-Anthropic model, because subagent dispatch belongs to the host. The `free`
+rung (`route-on --free`) is reachable only where the pipeline makes the call
+itself: `bulk-read.sh` and the `delegate` call site, where a skill asks
+`model-dispatch.sh delegate --default host` and calls `llm_delegate` on `free`.
+The toolkit and its CLI are the same on all three hosts, so the free chain
+behaves identically everywhere. `route-status` prints the limit on every run.
+Contract: `features/free-models.md`.
 
 ## 3. Frontmatter Transform Rules (Claude ↔ Copilot)