ainb-fleet-needs

name	ainb-fleet:needs
description	Center control panel — enumerate every claude session that is blocked waiting on something: a user answer (AskUserQuestion fired), an API error retry, an idle assistant turn-end with no follow-up, or an explicit WAITING: marker. Returns rich JSON with signal kind + context per session. Use this when you've stepped away from the fleet and want one place to see everything that wants your attention and answer it.
version	0.2.0
user-invocable	true
triggers	["ainb-fleet:needs","fleet needs","what does my fleet need","blocked sessions","sessions waiting on me","jarvis status","control panel"]
allowed-tools	["Bash"]

ainb fleet:needs — center control panel

Single place to see every claude session that wants your attention. Four signal kinds classified per session, priority ASK > ERR > IDLE > WAIT.

needs vs fleet-needs — which skill?

This skill (needs) is the plain, always-available control panel. It is prompt-driven: render the HUD, fire AskUserQuestion, route answers back. It needs no workflow gate and works everywhere.

/ainb-fleet:fleet-needs is the workflow-backed "Jarvis" cockpit — same purpose, but it runs the deterministic hangar workflow (verb=needs) for discover→enrich→prioritize, batches enrichment in a single agent, and adds key-route ASK answering (presses the target's picker keys via tmux for an open AskUserQuestion). It requires CLAUDE_CODE_WORKFLOWS=1; with the gate off it falls back to this skill.

Rule of thumb: reach for fleet-needs when the workflow gate is on and you want the batched/cockpit path; otherwise use needs. Both read the same underlying ainb fleet needs data, so the panel content is identical.

Source of truth — materialized current_state (hooks), tmux fallback

ainb fleet needs reads the event-sourced read model first. Claude Code hooks append lifecycle events to events.jsonl; notifyd ingests them into a SQLite current_state table that materializes the latest stage per session (ASK / ERR / WAIT / IDLE / RUNNING / DONE). For each session (keyed by cwd — the fleet's cross-source dedupe key), the reader resolves one of three ways:

resolution	when	what happens	row source
hook-authoritative	a materialized ASK/ERR/WAIT/IDLE row exists for the cwd (source = hook)	use it directly — no pane scan	"hook"
hook-healthy	the hook says RUNNING / DONE	not a "need" — emit nothing, skip the pane scan	—
fallback	no usable hook row — absent from current_state (a non-Claude session like Codex/Gemini fires no Claude hooks), source = tmux, or a stale row	run the live classify() pane/transcript scan, exactly as before the event store existed	"tmux"

So a Claude session's ASK/WAIT/IDLE/ERR is learned primarily from hooks; the tmux pane scan is the fallback for non-Claude agents (Codex/Gemini) and for sessions the daemon hasn't materialized. The read-time merge IS the tmux / non-Claude fold — each session yields at most one row, never double-listed.

The source field ("hook" | "tmux") on each row tells a consumer which path produced it. ASK/ERR/WAIT/IDLE are sticky states the materializer only changes on a new event, so an aged row is normally still the truth and there is no staleness check by default. Override only when you have an independent reason to distrust an aged row: AINB_FLEET_STATE_STALE_MS=<ms> (default 0 = no age check). When notifyd is down or the hooks were never installed, current_state is empty and every session falls back to the live scan, so the panel still works.

This skill does NOT install hooks. It only consumes the materialized state. The global Claude Code hooks are installed by ainb fleet atc setup (into ~/.claude/settings.json).

Run

ainb fleet needs                        # text Jarvis-HUD layout
ainb --format json fleet needs          # structured JSON (preferred by LLM)
ainb fleet needs --idle-min 10          # override idle threshold (default 5 min)

Env override: AINB_FLEET_IDLE_MIN=10.

JSON schema

Each row in the output array:

{
  "session": {
    "id": "…",
    "cwd": "/Users/…",
    "tmux_session": "tmux_…",
    "workspace_name": "…",
    "peer_id": "…",         // null if not broker-registered
    "sources": ["ainb", "peers"],
    "summary": "…",         // JSONL-derived (see standup)
    "last_seen_ms": 1779…
  },
  "kind": "ASK" | "ERR" | "IDLE" | "WAIT",
  "context": {
    // shape depends on `kind`:
    //
    // ASK — structured AskUserQuestion pulled from JSONL tool_use:
    "question": "…",
    "header": "…",
    "options": [ { "label": "…", "description": "…" } ],
    "multi_select": false,
    //
    // ERR — API error matched in pane:
    "pattern": "rate_limited",
    "snippet": "…API Error · rate_limited · …",
    //
    // IDLE — assistant turn-end, no user follow-up, > N min ago:
    "idle_minutes": 17,
    "last_assistant_text": "…",
    //
    // WAIT — explicit WAITING: prefix in peer summary:
    "marker": "WAITING:",
    "text": "…the post-marker text…"
  },
  "route_hint": "tmux" | "broker" | "none",  // advisory; send is tmux-first
  "source": "hook" | "tmux"                   // provenance: event-sourced row vs live tmux/transcript scan
}

source distinguishes a hook-sourced need (materialized from events.jsonl) from a tmux-folded one (the live fallback scan for non-Claude agents / un- materialized sessions). It is additive — older consumers that ignore it still work.

Enrich — token-efficient (cache-aware)

Each row also carries three enrich fields:

field	meaning
enrich_key	content hash of the card; the producer's cache key
enriched	a fresh cached suggestion (free) — render it as-is
need_enrich	true only when there is no cache entry and enrichment is on

Draft the missing ones by COUNT, never one subagent per session:

stale = rows where need_enrich == true
  stale == 0  ─▶ render cached/snippet only         (0 tokens)
  stale ≤ 6   ─▶ draft inline in THIS session        (0 subagents)
  stale  > 6  ─▶ /ainb-fleet:fleet-needs workflow     (1 batched agent)

Cutoff: AINB_FLEET_ENRICH_INLINE_MAX (default 6). When you draft inline, persist each so the next read is free:

ainb fleet enrich-cache put --key "<enrich_key>" --suggestion "<text>"

ainb fleet needs --no-enrich (or AINB_FLEET_ENRICH=0) skips all of this — cached suggestions still render, nothing new is drafted, 0 tokens.

Render template — Jarvis HUD

The calling LLM session should render this exact layout in chat:

╔════════════════════════════════════╗
║  ⚡ FLEET STATUS · N NEED YOU ⚡    ║
║  🔴 X err  🟡 Y ask  ⚪ Z idle      ║
║  highest priority: <session> (<KIND>) ║
╚════════════════════════════════════╝

▸ 🟡 <session> ─ <question text>
    ① <option label>
    ② <option label>
    ③ <option label>

▸ 🔴 <session> ─ <pattern> (<snippet>)

▸ ⚪ <session> ─ idle <N>m
    '<last assistant snippet>'

▸ 🟢 <session> ─ WAITING: <text>

Rules:

• Banner always present (even for 0 sessions — "0 NEED YOU" + skip the priority line)
• Per-card ▸ prefix, signal emoji, em-dash separator
• ASK cards show options as ① ② ③ ④ ⑤ (numeric circled)
• Cap at 10 cards visible; if more, render top 10 then + N more
• Priority order: ASK > ERR > IDLE > WAIT (binary already sorts this way)
• Status emoji: 🔴 ERR · 🟡 ASK · ⚪ IDLE · 🟢 WAIT
• Box-drawing chars: ╔ ╗ ╚ ╝ ║ ─ ▸ (monospace, no ANSI needed)

Compose the AskUserQuestion batch

After rendering the HUD, fire AskUserQuestion per session that wants an answer. Each kind maps to a different prompt shape:

kind	AskUserQuestion shape
ASK	Relay options 1:1 from context.options
ERR	" hit <pattern> — retry? skip? investigate?"
IDLE	" idle m after: '' — resume? close? other?"
WAIT	" says: <marker> <text> — answer:"

For ASK kinds, the LLM session SHOULD use AskUserQuestion's structured options so the user can click rather than type.

Route the answers back

Writes are tmux-first. Prefer driving the target pane directly — it lands reliably and is verifiable with capture-pane:

# default, most reliable: write keystrokes straight to the pane
tmux send-keys -t "<tmux_session>" -l "<answer>"
tmux send-keys -t "<tmux_session>" Enter
# verify it landed
tmux capture-pane -t "<tmux_session>" -p -S -40 | grep -F "<answer>" && echo "✓"

Or go through the verb, which honours AINB_FLEET_TRANSPORT (tmux-first):

ainb fleet broadcast "<answer>" --filter "<exact tmux_session>"

route_hint is advisory — it mirrors the default tmux-first order:

• tmux — a live tmux pane exists → tmux send-keys -l (the normal case)
• broker — no tmux pane, but a healthy broker peer → claude-peers HTTP fallback
• none — bg job or no targets; can't auto-route; tell user manually

Composition example

out=$(ainb --format json fleet needs)

# 1. Render the HUD in chat (LLM does this from the JSON)
# 2. For each entry, fire AskUserQuestion (claude code session does this)
# 3. After each answer:
echo "$out" | jq -r ".[] | select(.session.tmux_session == \"$picked\") | .session.tmux_session" \
  | xargs -I% ainb fleet broadcast "$answer" --filter "%"

Caveats

• Race window — between fleet sees the AskUserQuestion and Stevie's answer reaches claude, the session still appears blocked on next invocation. Acceptable for v0.2; full dedupe lands in v0.3.
• IDLE false positives — a session you walked away from briefly shows IDLE if past the threshold. Tune via --idle-min or env var.
• WAIT requires opt-in — only fires when a session explicitly sets summary to start with WAITING:. Most sessions never do.
• Bg jobs are excluded — they have no tmux pane and no JSONL transcript follow the normal shape; surfacing them would dilute the panel. Use ainb status <job> for those.

Changelog

v0.3 — hooks-primary (event-sourced)

• Reads the materialized current_state table FIRST (hook-sourced ASK/ERR/ WAIT/IDLE per session); the live tmux/transcript classify() scan is now the fallback for non-Claude agents (Codex/Gemini) and un-materialized sessions
• Added the source field ("hook" | "tmux") to each row
• AINB_FLEET_STATE_STALE_MS (default 0 = no age check) to optionally distrust aged rows
• Hooks are installed by ainb fleet atc setup, NOT by this skill

v0.2

• Added ASK, ERR, IDLE signal kinds (was: WAIT-only in v0.1)
• Added --idle-min flag + AINB_FLEET_IDLE_MIN env override
• Rich JSON output with context polymorphic per kind
• route_hint field to guide answer-routing
• Text-mode renders the Jarvis HUD directly
• Priority sort: ASK > ERR > IDLE > WAIT