feat(bin): add opt-in intake classifier

.agents/skills/backlog-operations/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: backlog-operations
+description: >-
+  Agent-only intake reference for deciding what to do with a captain request.
+  Load before using the opt-in System One intake classifier.
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# backlog-operations
+
+Before classifying a captain request, run the opt-in `bin/fm-intake-classify.sh` directly on the request file in the same turn.
+Its result recommends only `ship`, `scout`, or `answer_now` with urgency and never authorizes a spawn or replaces your intake judgment.
+`docs/configuration.md` "Typed intake classification" owns the complete contract and every status meaning.

.agents/skills/harness-adapters/references/common/dispatch.md

@@ -8,6 +8,7 @@ Use the router's detection and safety sections for static crew and secondmate ha
 `config/crew-dispatch.json` can override that static default for one crewmate or scout with concrete harness, model, and effort axes.
 For a profile array, load `quota-array-dispatch` after establishing harness and provider facts here.
 When the opt-in `bin/fm-dispatch-resolve.sh` is on, its `clear` answer already names the concrete axes; `docs/configuration.md` "Typed dispatch resolution" owns that contract.
+At request intake, `bin/fm-intake-classify.sh` is an advisory disposition recommendation only; `docs/configuration.md` "Typed intake classification" owns its contract.
 
 `../secondmate-provisioning/SKILL.md` owns inherited local material.
 Its harness consequence is that a secondmate's workers receive literal `config/crew-harness` and `config/crew-dispatch.json`, while the primary-only `config/secondmate-harness` is never inherited because secondmates do not spawn secondmates.

AGENTS.md

@@ -68,7 +68,7 @@ README.md            public overview and development notes
 .claude/mods/        Claude Code mods (function-hooks plugins), committed; Calm's module may load through CLAUDE_CODE_ENABLE_FUNCTION_HOOKS or tengu_plugin_hooks_modules, but activates only when CLAUDE_CODE_ENABLE_FUNCTION_HOOKS is exactly "1" and is otherwise a complete no-op (docs/calm.md)
 skills/              standalone public installer-facing skills, committed; not loaded by firstmate
 bin/                 helper scripts, committed; read each script's header before first use
-.env                 optional Relay pairing token (presence-gates section 14), mail-plane credentials (schema: docs/configuration.md "Mail plane"), and typed dispatch resolution key TYPESAFE_API_KEY (presence-gates bin/fm-dispatch-resolve.sh; docs/configuration.md "Typed dispatch resolution"); LOCAL, gitignored
+.env                 optional Relay pairing token (presence-gates section 14), mail-plane credentials (schema: docs/configuration.md "Mail plane"), and typed-classifier key TYPESAFE_API_KEY (presence-gates bin/fm-dispatch-resolve.sh and bin/fm-intake-classify.sh; docs/configuration.md owns both typed classifier contracts); LOCAL, gitignored
 config/crew-harness  crewmate harness override; LOCAL, gitignored; absent or "default" = same as firstmate. Inherited as the literal file: a concrete primary adapter value also controls a secondmate home's own crewmates (section 4)
 config/claude-permission-mode  optional one-token permission posture for every Claude worker launch: absent or "bypass" keeps --dangerously-skip-permissions, "auto" launches with --permission-mode auto; LOCAL, gitignored; inherited by secondmate homes; see docs/configuration.md "Claude permission mode"
 config/crew-dispatch.json  optional crewmate dispatch profiles; LOCAL, gitignored; firstmate-maintained but human-editable natural-language rules that choose a per-task harness/model/effort profile (section 4). Inherited by secondmate homes
@@ -232,6 +232,7 @@ 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; 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").
+Load `backlog-operations` before using the opt-in request-intake classifier; its disposition remains advisory until firstmate decides the next action.
 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.
 For a crewmate's native child delegation, [`docs/configuration.md`](docs/configuration.md) "Nested delegation" owns the same-profile requirement, legacy-tier retirement, and the boundary of Firstmate's runtime enforcement; generated ship and scout briefs carry its operational reinforcement.
@@ -579,6 +580,7 @@ These skills are not captain-invocable; load them only at their precise triggers
 - `bootstrap-diagnostics` - load whenever the session-start digest's bootstrap or network-checks section prints an actionable diagnostic line (`MISSING:`, `MISSING_MANUAL:`, `PRESENTATION_UNAVAILABLE:`, `BACKEND_INVALID:`, `NEEDS_GH_AUTH`, `TANGLE:`, `STARTUP_MEMORY_BUDGET:`, `CREW_DISPATCH: invalid`, `FLEET_SYNC:`, `NETWORK_CHECKS:`, `HOME_SUMMARY:`, `BACKLOG_RECONCILE:`, `SECONDMATE_SYNC:`, `SECONDMATE_LIVENESS:`, `SECONDMATE_HANDOFF:`, `NUDGE_SECONDMATES:`, or `FMX:`), or when `BOOTSTRAP_INFO:` says an interrupted backlog cleanup may have left an endpoint or local copy; silence and other `BOOTSTRAP_INFO:` facts need no load.
 - `diagnostic-reasoning` - load before scoping a reported bug and before acting on a diagnostic report.
 - `ask-user-authority` - load before deciding any ask-user finding.
+- `backlog-operations` - load before classifying a captain request with the opt-in intake classifier.
 - `quota-array-dispatch` - load before choosing among a matched crew-dispatch profile array from current quota-axi default TOON.
 - `harness-adapters` - load before spawning or recovering a crewmate or secondmate, handling a trust dialog, sending a harness-specific skill invocation, interrupting or exiting an agent, resuming an exited agent, or verifying a new harness adapter.
 - `firstmate-orca` - load before switching to Orca, spawning or supervising Orca-backed work, smoke-testing Orca backend behavior, debugging Orca task state, or reconciling Orca-backed task metadata.

bin/fm-bootstrap.sh

@@ -156,6 +156,11 @@
 #          nothing; bin/fm-brief.sh uses it to gate scout Lavish hosting.
 set -u
 
+# A caller may invoke bootstrap under `bash -x` while testing the opt-in typed
+# dispatch gate.
+# Disable tracing before copying its key so neither the environment value nor
+# the private handoff variable reaches the shell trace.
+set +x
 TYPESAFE_API_KEY_PRIVATE=${TYPESAFE_API_KEY:-}
 export -n TYPESAFE_API_KEY_PRIVATE 2>/dev/null || true
 unset TYPESAFE_API_KEY

bin/fm-classify-lib.sh

@@ -1775,9 +1775,12 @@ _fm_status_open_decision_origins() {  # <status-file> [<kind>]
   while IFS= read -r line || [ -n "$line" ]; do
     number=$((number + 1))
     after=$(_fm_decision_fold_line "$open" "$line" "$resolve" "$held" "$kind")
-    [ -n "$after" ] || origins=''
-    key=$(_fm_decision_key "$line") || { open=$after; continue; }
     verb=$(status_line_verb "$line")
+    # A failure clears the current open-decision set but still needs its unseen decision origin in the same escalation span.
+    # A completed task drops the historical origin from this escalation-specific view.
+    # An explicit resolution or verified captain-held transfer drops its own origin below.
+    [ -n "$after" ] || [ "$verb" != "done" ] || origins=''
+    key=$(_fm_decision_key "$line") || { open=$after; continue; }
     note=$(status_line_note "$line")
     case "$verb" in
       needs-decision|blocked)

bin/fm-intake-classify.sh

@@ -0,0 +1,233 @@
+#!/usr/bin/env bash
+# fm-intake-classify.sh - recommend a firstmate intake disposition with
+# typesafe.ai's System One model (Jev), opt-in.
+#
+# Usage:
+#   fm-intake-classify.sh <request-file> [--project <name>]
+#
+# Opt-in gate: TYPESAFE_API_KEY non-empty in this process environment, else a
+#   TYPESAFE_API_KEY= line in $FM_HOME/.env read with fmx_env_get. The
+#   environment wins. Absent in both: one "intake-classify: off" line on
+#   stderr, nothing on stdout, exit 0, and no network call.
+#
+# What it does when on: one POST to https://api.typesafe.ai/v1/systemone with
+# the project name and a bounded request-text snapshot as state. It asks three
+# parallel questions: a Choice recommendation of ship, scout, answer_now, or
+# unclear; a NOUL answer about implementation authorization; and a three-level
+# urgency Score. Jq composes clear, ambiguous, escalate, or error afterwards.
+# The result is recommendation-only: it never spawns a worker, chooses a
+# harness or model, or changes firstmate's intake judgment.
+#
+# Output (stdout, TOON-style block):
+#   intake-classify:
+#     status: clear | ambiguous | escalate | error
+#     model/latency_ms/tokens, deliverable and confidence, intent_clear and
+#     NOUL score, urgency and score, request truncation, and any reason
+#   clear     -> a high-confidence recommendation; ship is also authorized
+#   ambiguous -> a low-confidence or unclear recommendation
+#   escalate  -> a ship recommendation without implementation authorization
+#   error     -> local runtime, API, network, response, or rendering failure
+#   Every runtime outcome exits 0 so intake is never blocked by this tool.
+#   Exit 2 only for invalid argv, an initially unreadable request, or missing
+#   jq, which are actionable usage or configuration errors.
+#
+# Environment:
+#   TYPESAFE_API_KEY is the only classifier-specific environment setting.
+#
+# Authority: docs/configuration.md "Typed intake classification" owns the
+# operator contract. This script owns flags and exact output. The classifier
+# never replaces firstmate judgment or auto-spawns work.
+set +x
+set -u
+
+TYPESAFE_API_KEY_PRIVATE=${TYPESAFE_API_KEY:-}
+export -n TYPESAFE_API_KEY_PRIVATE 2>/dev/null || true
+unset TYPESAFE_API_KEY
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+FM_ROOT="${FM_ROOT_OVERRIDE:-$(cd "$SCRIPT_DIR/.." && pwd)}"
+FM_HOME="${FM_HOME:-$FM_ROOT}"
+
+# shellcheck source=bin/fm-env-lib.sh
+. "$SCRIPT_DIR/fm-env-lib.sh"
+# shellcheck source=bin/fm-timing-lib.sh
+. "$SCRIPT_DIR/fm-timing-lib.sh"
+
+CONFIDENCE_FLOOR=0.6
+TS_MODEL=jev-latest
+TS_BASE=https://api.typesafe.ai
+TS_TIMEOUT=5
+REQUEST_MAX_BYTES=32768
+
+die() { printf 'error: %s\n' "$1" >&2; exit 2; }
+usage() {
+  awk '
+    NR == 1 { next }
+    /^#/ { sub(/^# ?/, ""); print; next }
+    { exit }
+  ' "$0"
+}
+emit_error() {
+  local reason=$1
+  printf 'intake-classify: error (%s)\n' "$reason" >&2
+  printf 'intake-classify:\n  status: error\n  reason: %s\n' "$reason"
+  exit 0
+}
+
+REQUEST_FILE='' PROJECT=''
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --project) [ $# -ge 2 ] || die "--project needs a value"; PROJECT=$2; shift 2 ;;
+    -h|--help) usage; exit 0 ;;
+    -*) die "unknown flag $1" ;;
+    *) [ -z "$REQUEST_FILE" ] || die "one request file only"; REQUEST_FILE=$1; shift ;;
+  esac
+done
+
+# ---- opt-in gate ---------------------------------------------------------------
+if [ -z "$TYPESAFE_API_KEY_PRIVATE" ]; then
+  TYPESAFE_API_KEY_PRIVATE=$(fmx_env_get TYPESAFE_API_KEY "$FM_HOME/.env")
+fi
+if [ -z "$TYPESAFE_API_KEY_PRIVATE" ]; then
+  printf '%s\n' 'intake-classify: off' >&2
+  exit 0
+fi
+
+# ---- inputs --------------------------------------------------------------------
+[ -n "$REQUEST_FILE" ] || die "request file required (see --help)"
+[ -r "$REQUEST_FILE" ] || die "request file not readable: $REQUEST_FILE"
+command -v jq >/dev/null 2>&1 || die "jq required"
+
+REQUEST_SNAPSHOT=$(mktemp 2>/dev/null) || emit_error "temporary file setup failed"
+RESP_FILE=$(mktemp 2>/dev/null) || { rm -f "$REQUEST_SNAPSHOT"; emit_error "temporary file setup failed"; }
+trap 'rm -f "$REQUEST_SNAPSHOT" "$RESP_FILE"' EXIT
+head -c "$REQUEST_MAX_BYTES" "$REQUEST_FILE" > "$REQUEST_SNAPSHOT" || emit_error "request read failed"
+REQUEST_BYTES=$(wc -c < "$REQUEST_FILE") || emit_error "request measurement failed"
+REQUEST_BYTES=${REQUEST_BYTES//[[:space:]]/}
+case "$REQUEST_BYTES" in ''|*[!0-9]*) emit_error "request measurement failed" ;; esac
+if [ "$REQUEST_BYTES" -gt "$REQUEST_MAX_BYTES" ]; then REQUEST_TRUNCATED=true; else REQUEST_TRUNCATED=false; fi
+
+# ---- one System One request ----------------------------------------------------
+command -v curl >/dev/null 2>&1 || emit_error "curl not installed"
+REQUEST=$(jq -n --rawfile request "$REQUEST_SNAPSHOT" --arg project "$PROJECT" --arg model "$TS_MODEL" '
+  {
+    model: $model,
+    state: {intake: {project: $project, request: $request}},
+    questions: {
+      deliverable: {
+        type: "choice",
+        instructions: "Which disposition should firstmate consider for this request? This is advice only and must not create, dispatch, or select any worker.",
+        criteria: {
+          ship: "A concrete, authorized implementation change should be handled as a ship task.",
+          scout: "The request needs bounded investigation, reproduction, audit, or planning before an implementation decision.",
+          answer_now: "The request can be answered directly now without creating a worker task.",
+          unclear: "The request is too incomplete or conflicting to recommend a disposition."
+        }
+      },
+      intent_clear: {
+        type: "noul",
+        instructions: "Is the captain already authorizing a concrete implementation change in this request? Answer true only when the requested change and scope are sufficiently concrete."
+      },
+      urgency: {
+        type: "score",
+        instructions: "Score urgency on this ordered scale: 0 routine means ordinary work with no material time pressure; 1 soon means a stated near-term deadline or materially useful prompt follow-up; 2 blocking means current work, a release, safety, or a stated deadline is blocked until this is addressed.",
+        criteria: [
+          "0 routine: ordinary work with no material time pressure.",
+          "1 soon: a stated near-term deadline or materially useful prompt follow-up.",
+          "2 blocking: current work, a release, safety, or a stated deadline is blocked until this is addressed."
+        ]
+      }
+    }
+  }') || emit_error "request rendering failed"
+
+T0=$(fm_timing_now_ms)
+HTTP=$(printf '%s' "$REQUEST" | curl -q -sS --max-time "$TS_TIMEOUT" -o "$RESP_FILE" -w '%{http_code}' \
+  -X POST "$TS_BASE/v1/systemone" -H 'Content-Type: application/json' \
+  -H @/dev/fd/3 3< <(printf 'Authorization: Bearer %s\n' "$TYPESAFE_API_KEY_PRIVATE") \
+  --data-binary @- 2>/dev/null) || HTTP=000
+T1=$(fm_timing_now_ms)
+LAT_MS=$(( T1 - T0 ))
+[ "$HTTP" = 200 ] || emit_error "http $HTTP after ${LAT_MS} ms: $(head -c 200 "$RESP_FILE" 2>/dev/null | tr '\n' ' ')"
+
+# ---- response validation and status composition --------------------------------
+jq -e '
+  def confidence($a): $a.confidence;
+  def intent_noul($a): $a.noul;
+  def urgency_score($a): $a.score;
+  def confidence_ok($a): (confidence($a) | type) == "number" and confidence($a) >= 0 and confidence($a) <= 1;
+  (.answers | type) == "object" and
+  (.answers.deliverable | type) == "object" and
+  (.answers.deliverable.choice | type) == "string" and
+  (.answers.deliverable.choice as $choice | ["ship", "scout", "answer_now", "unclear"] | index($choice)) != null and
+  confidence_ok(.answers.deliverable) and
+  (.answers.deliverable.probabilities | type) == "object" and
+  ((.answers.deliverable.probabilities | keys | sort) == ["answer_now", "scout", "ship", "unclear"]) and
+  all(.answers.deliverable.probabilities[]; type == "number" and . >= 0 and . <= 1) and
+  ((.answers.deliverable.probabilities | [.[]] | add) as $total | $total >= 0.99 and $total <= 1.01) and
+  (.answers.intent_clear | type) == "object" and
+  (intent_noul(.answers.intent_clear) | type) == "number" and
+  intent_noul(.answers.intent_clear) >= 0 and intent_noul(.answers.intent_clear) <= 1 and
+  (.answers.urgency | type) == "object" and
+  (urgency_score(.answers.urgency) | type) == "number" and
+  urgency_score(.answers.urgency) >= 0 and urgency_score(.answers.urgency) <= 2 and
+  confidence_ok(.answers.urgency) and
+  ((has("usage") | not) or
+    ((.usage | type) == "object" and
+     (.usage.input_tokens | type) == "number" and
+     (.usage.output_tokens | type) == "number"))
+' "$RESP_FILE" >/dev/null 2>&1 || emit_error "response is not a typed intake answer"
+
+RESULT=$(jq -n --argjson floor "$CONFIDENCE_FLOOR" --argjson latency "$LAT_MS" --argjson truncated "$REQUEST_TRUNCATED" --slurpfile response "$RESP_FILE" '
+  ($response[0]) as $r |
+  ($r.answers.deliverable) as $deliverable |
+  ($r.answers.intent_clear) as $intent |
+  ($r.answers.urgency) as $urgency |
+  def intent_noul: .noul;
+  def urgency_score: .score;
+  def urgency_level($score):
+    if $score < 0.5 then "routine"
+    elif $score < 1.5 then "soon"
+    else "blocking"
+    end;
+  ($deliverable.confidence) as $deliverable_confidence |
+  ($intent | intent_noul) as $intent_noul |
+  ($urgency.confidence) as $urgency_confidence |
+  ([ $deliverable_confidence, $urgency_confidence ] | min) as $confidence |
+  {
+    model: $r.model,
+    latency_ms: $latency,
+    tokens: ($r.usage // null),
+    deliverable: $deliverable.choice,
+    deliverable_confidence: $deliverable_confidence,
+    deliverable_probabilities: $deliverable.probabilities,
+    intent_clear: ($intent_noul >= $floor),
+    intent_clear_noul: $intent_noul,
+    urgency: urgency_level($urgency | urgency_score),
+    urgency_score: ($urgency | urgency_score),
+    urgency_confidence: $urgency_confidence,
+    confidence: $confidence,
+    request_truncated: $truncated
+  } |
+  if $confidence < $floor then
+    . + {status: "ambiguous", reason: "lowest answer confidence \($confidence) below floor \($floor)"}
+  elif .deliverable == "ship" and .intent_clear != true then
+    . + {status: "escalate", reason: "concrete implementation authorization is not clear"}
+  elif .deliverable == "unclear" then
+    . + {status: "ambiguous", reason: "deliverable recommendation is unclear"}
+  else . + {status: "clear"}
+  end') || emit_error "status composition failed"
+
+TEXT=$(jq -r '
+  def flat: tostring | gsub("[\t\r\n]"; " ");
+  def show($value): ($value // "-") | flat;
+  "intake-classify:",
+  "  status: \(.status | flat)",
+  "  model: \(show(.model))   latency_ms: \(show(.latency_ms))   tokens: \(show(.tokens.input_tokens))/\(show(.tokens.output_tokens))",
+  "  deliverable: \(.deliverable | flat)   confidence: \(.deliverable_confidence | flat)",
+  "  probabilities: \([.deliverable_probabilities | to_entries[] | "\(.key | flat)=\(.value | flat)"] | join(" "))",
+  "  intent_clear: \(.intent_clear | flat)   noul: \(.intent_clear_noul | flat)",
+  "  urgency: \(.urgency | flat)   score: \(.urgency_score | flat)   confidence: \(.urgency_confidence | flat)",
+  "  request_truncated: \(.request_truncated | flat)",
+  (if .reason then "  reason: \(.reason | flat)" else empty end)' <<<"$RESULT") || emit_error "output rendering failed"
+printf '%s\n' "$TEXT"
+exit 0