crewly 1.20.195 → 1.20.196

package/config/skills/agent/core/project-tickets/execute.sh

@@ -23,6 +23,10 @@
 #   bash execute.sh ask-owner --project P --id APP-12 --clear [--note "answer"]
 #   bash execute.sh autopilot --project P [--on|--off] [--driver <session>|--driver default]
 #                             [--daily-budget <tokens, e.g. 20M>] [--max-in-flight <n>]      (owner / orchestrator)
+#                             [--retro on|off|default]
+#   bash execute.sh stats     --project P [--days 14] [--label feed]       (owner / orc / lead)
+#   bash execute.sh runs      --project P [--days 7] [--label feed]        (owner / orc / lead)
+#   bash execute.sh retro     --project P --day YYYY-MM-DD --summary "…" [--problem "class|title|detail|evidence" …]
 #   bash execute.sh '{"action":"create","project":"P","title":"…"}'
 #
 # P = project id, name, or absolute path.
@@ -58,9 +62,23 @@ Usage:
   bash execute.sh ask-owner --project P --id APP-12 --clear [--note "answer"]
                                                               The owner answered: remove the needs-owner mark
   bash execute.sh autopilot --project P [--on|--off] [--driver <session>|default]
-                          [--daily-budget <tokens, e.g. 20M>] [--max-in-flight <n>]
+                          [--daily-budget <tokens, e.g. 20M>] [--max-in-flight <n>] [--retro on|off|default]
                                                               Owner / orchestrator: show or change the ticket
-                                                              autopilot (no flags = show)
+                                                              autopilot (no flags = show). --retro: the lead's
+                                                              daily retro (default: on while an autopilot
+                                                              experiment runs)
+  bash execute.sh stats     --project P [--days 14] [--label feed]
+                                                              Autopilot numbers per day: tickets triaged /
+                                                              started / done / verified / sent back / stalled,
+                                                              cycle times, owner touches, stalls by cause,
+                                                              interventions, cost vs the daily budget
+  bash execute.sh runs      --project P [--days 7] [--label feed]
+                                                              Run trace + ticket traces per day (for trace-read)
+  bash execute.sh retro     --project P --day YYYY-MM-DD --summary "what shipped, where it stalled, why"
+                          [--problem "class|title|detail|evidence" …]
+                                                              Team lead: file the daily autopilot retro.
+                                                              class = agent_judgment | missing_skill |
+                                                              harness_gap | owner_dependency
 
 P = project id, name or absolute path. Workers' new tickets start in backlog;
 the owner, the orchestrator or a team lead makes them ready.
@@ -72,6 +90,7 @@ STATUS=""; SOURCE=""; REQUEST_ID=""; NOTE=""; OWNER_REVIEW=""; ASSIGNEE=""; STAR
 ACCEPTANCE_JSON="null"
 HAS_DESCRIPTION=0
 QUESTION=""; CLEAR=""; OPTIONS_JSON="[]"; DEFAULT_OPT=""; DEADLINE=""; SENSITIVE=""; AP_ENABLED=""; AP_DRIVER=""; AP_BUDGET=""; AP_MAX=""
+AP_RETRO=""; DAYS=""; LABEL=""; DAY=""; SUMMARY=""; PROBLEMS_JSON="[]"
 
 if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then
   J="$1"; shift
@@ -104,6 +123,12 @@ if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then
   AP_DRIVER=$(printf '%s' "$J" | jq -r '.driver // empty')
   AP_BUDGET=$(printf '%s' "$J" | jq -r '.dailyBudgetTokens // empty')
   AP_MAX=$(printf '%s' "$J" | jq -r '.maxInFlightPerMember // empty')
+  AP_RETRO=$(printf '%s' "$J" | jq -r 'if (.retro|type) == "boolean" then (if .retro then "on" else "off" end) else (.retro // empty) end')
+  DAYS=$(printf '%s' "$J" | jq -r '.days // empty')
+  LABEL=$(printf '%s' "$J" | jq -r '.label // empty')
+  DAY=$(printf '%s' "$J" | jq -r '.day // empty')
+  SUMMARY=$(printf '%s' "$J" | jq -r '.summary // empty')
+  PROBLEMS_JSON=$(printf '%s' "$J" | jq -c 'if (.problems|type) == "array" then .problems else [] end')
 fi
 if [[ -z "$ACTION" && $# -gt 0 && ${1:0:1} != '-' ]]; then ACTION="$1"; shift; fi
 
@@ -140,13 +165,20 @@ while [[ $# -gt 0 ]]; do
     --daily-budget|--budget)
                      [ $# -ge 2 ] || error_exit "--daily-budget requires a value"; AP_BUDGET="$2"; shift 2 ;;
     --max-in-flight) [ $# -ge 2 ] || error_exit "--max-in-flight requires a value"; AP_MAX="$2"; shift 2 ;;
+    --retro)         [ $# -ge 2 ] || error_exit "--retro requires on, off or default"; AP_RETRO="$2"; shift 2 ;;
+    --days)          [ $# -ge 2 ] || error_exit "--days requires a value";        DAYS="$2"; shift 2 ;;
+    --label)         [ $# -ge 2 ] || error_exit "--label requires a value";       LABEL="$2"; shift 2 ;;
+    --day)           [ $# -ge 2 ] || error_exit "--day requires a value";         DAY="$2"; shift 2 ;;
+    --summary)       [ $# -ge 2 ] || error_exit "--summary requires a value";     SUMMARY="$2"; shift 2 ;;
+    --problem)       [ $# -ge 2 ] || error_exit "--problem requires \"class|title|detail|evidence\""
+                     PROBLEMS_JSON=$(jq -c --arg p "$2" '. + [($p | split("|")) as $f | {class: ($f[0] // "" | gsub("^\\s+|\\s+$"; "")), title: ($f[1] // "")} + (if ($f[2] // "") != "" then {detail: $f[2]} else {} end) + (if ($f[3:] | join("|")) != "" then {evidence: ($f[3:] | join("|"))} else {} end)]' <<<"$PROBLEMS_JSON"); shift 2 ;;
     --full)          shift ;;
     --help|-h)       print_usage; exit 0 ;;
     *) error_exit "Unknown option: $1" ;;
   esac
 done
 
-[ -n "$ACTION" ] || { print_usage >&2; error_exit "Missing action: list | show | create | update | claim | release | assign | log | link | ask-owner | autopilot"; }
+[ -n "$ACTION" ] || { print_usage >&2; error_exit "Missing action: list | show | create | update | claim | release | assign | log | link | ask-owner | autopilot | stats | runs | retro"; }
 
 # URL-encode a path segment (project paths contain slashes).
 enc() { jq -rn --arg v "$1" '$v|@uri'; }
@@ -250,19 +282,40 @@ case "$ACTION" in
     ;;
   autopilot)
     require_param "project" "$PROJECT"
-    if [ -z "$AP_ENABLED$AP_DRIVER$AP_BUDGET$AP_MAX" ]; then
+    if [ -z "$AP_ENABLED$AP_DRIVER$AP_BUDGET$AP_MAX$AP_RETRO" ]; then
       api_call GET "/project-ticket-autopilot/$(enc "$PROJECT")" | jq '{success, autopilot: .data}'
     else
-      BODY=$(jq -n --arg enabled "$AP_ENABLED" --arg driver "$AP_DRIVER" --arg budget "$AP_BUDGET" --arg max "$AP_MAX" \
+      BODY=$(jq -n --arg enabled "$AP_ENABLED" --arg driver "$AP_DRIVER" --arg budget "$AP_BUDGET" --arg max "$AP_MAX" --arg retro "$AP_RETRO" \
         '{}
          + (if $enabled != "" then {enabled: ($enabled == "true")} else {} end)
+         + (if $retro == "default" then {retro: null} elif $retro != "" then {retro: $retro} else {} end)
          + (if $driver == "default" then {driver: null} elif $driver != "" then {driver: $driver} else {} end)
          + (if $budget == "default" then {dailyBudgetTokens: null} elif $budget != "" then {dailyBudgetTokens: ($budget | tonumber? // $budget)} else {} end)
          + (if $max == "default" then {maxInFlightPerMember: null} elif $max != "" then {maxInFlightPerMember: ($max | tonumber? // $max)} else {} end)')
       api_call POST "/project-ticket-autopilot/$(enc "$PROJECT")" "$BODY" | jq '{success, autopilot: .data}'
     fi
     ;;
+  stats|runs)
+    require_param "project" "$PROJECT"
+    QS=""
+    [ -n "$DAYS" ] && QS="days=$(enc "$DAYS")"
+    [ -n "$LABEL" ] && QS="${QS:+$QS&}label=$(enc "$LABEL")"
+    if [ "$ACTION" = "stats" ]; then
+      api_call GET "/project-ticket-autopilot/$(enc "$PROJECT")/stats${QS:+?$QS}" \
+        | jq '{success, stats: (.data | if . == null then null else {project, label, range, pausedForToday, total, labels,
+               days: [.days[] | {day, triaged, started, done, verified, sentBack, stalled, ownerTouches: .ownerTouches.total, stallMs: .stalls.totalMs, costUsd, pausedMs, runTraceId}]} end)}'
+    else
+      api_call GET "/project-ticket-autopilot/$(enc "$PROJECT")/runs${QS:+?$QS}" | jq '{success, runs: .data}'
+    fi
+    ;;
+  retro)
+    require_param "project" "$PROJECT"
+    require_param "day (--day YYYY-MM-DD)" "$DAY"
+    require_param "summary (--summary)" "$SUMMARY"
+    BODY=$(jq -n --arg d "$DAY" --arg s "$SUMMARY" --argjson p "$PROBLEMS_JSON" '{day: $d, summary: $s, problems: $p}')
+    api_call POST "/project-ticket-autopilot/$(enc "$PROJECT")/retro" "$BODY" | jq '{success, retro: .data, error}'
+    ;;
   *)
-    error_exit "Unknown action: $ACTION (use list | show | create | update | claim | release | assign | log | link | ask-owner | autopilot)"
+    error_exit "Unknown action: $ACTION (use list | show | create | update | claim | release | assign | log | link | ask-owner | autopilot | stats | runs | retro)"
     ;;
 esac

package/config/skills/agent/core/project-tickets/execute.test.sh

@@ -31,6 +31,13 @@ class H(BaseHTTPRequestHandler):
             if self.path.count('/') >= 4 and not self.path.split('?')[0].endswith('%2Fapp'):
                 return self.reply(200, {'success': True, 'data': T})
             return self.reply(200, {'success': True, 'data': {'project': {'id': 'p1'}, 'tickets': [T], 'invalid': []}})
+        if self.path.startswith('/api/project-ticket-autopilot/') and '/stats' in self.path:
+            day = {'day': '2026-10-02', 'triaged': 3, 'started': 2, 'done': 2, 'verified': 1, 'sentBack': 0, 'stalled': 1,
+                   'ownerTouches': {'total': 2}, 'stalls': {'totalMs': 60000}, 'costUsd': 1.5, 'pausedMs': 0, 'runTraceId': 'tr-x', 'extra': 1}
+            return self.reply(200, {'success': True, 'data': {'project': {'id': 'p1'}, 'label': 'feed', 'range': {}, 'pausedForToday': False,
+                                                               'total': {'verified': 1}, 'labels': ['feed'], 'days': [day]}})
+        if self.path.startswith('/api/project-ticket-autopilot/') and '/runs' in self.path:
+            return self.reply(200, {'success': True, 'data': {'project': {'id': 'p1'}, 'days': [{'day': '2026-10-02', 'runTraceId': 'tr-x', 'traces': []}]}})
         if self.path.startswith('/api/project-ticket-autopilot/'):
             return self.reply(200, {'success': True, 'data': {'settings': {'enabled': False}}})
         if self.path.startswith('/api/project-tickets'):
@@ -147,6 +154,23 @@ check "autopilot off: body" "$(last '.body | tostring')" '{"enabled":false,"driv
 run '{"action":"autopilot","project":"p1","enabled":true,"driver":"ce-owen"}' >/dev/null
 check "autopilot json: body" "$(last '.body | tostring')" '{"enabled":true,"driver":"ce-owen"}'
 
+run autopilot --project p1 --retro on >/dev/null
+check "autopilot retro on: body" "$(last '.body | tostring')" '{"retro":"on"}'
+run autopilot --project p1 --retro default >/dev/null
+check "autopilot retro default: body" "$(last '.body | tostring')" '{"retro":null}'
+
+# --- stats / runs / retro (specs/2026-10-03-autopilot-experiments.md) ---
+OUT=$(run stats --project p1 --days 7 --label feed)
+check "stats: path" "$(last .path)" "/api/project-ticket-autopilot/p1/stats?days=7&label=feed"
+check "stats: day row" "$(printf '%s' "$OUT" | jq -c '.stats.days[0] | [.day, .verified, .ownerTouches, .stallMs, .runTraceId, has("extra")]')" '["2026-10-02",1,2,60000,"tr-x",false]'
+OUT=$(run runs --project p1)
+check "runs: path" "$(last .path)" "/api/project-ticket-autopilot/p1/runs"
+check "runs: output" "$(printf '%s' "$OUT" | jq -c '.runs.days[0].runTraceId')" '"tr-x"'
+run retro --project p1 --day 2026-10-02 --summary "Shipped CE-1; CE-2 stalled on the owner." --problem "owner_dependency|CE-2 waited for copy|D-4 open 3h|tr-a" --problem "harness_gap|Triage listed a stopped member as busy" >/dev/null
+check "retro: path" "$(last .path)" "/api/project-ticket-autopilot/p1/retro"
+check "retro: body" "$(last '.body | tostring')" '{"day":"2026-10-02","summary":"Shipped CE-1; CE-2 stalled on the owner.","problems":[{"class":"owner_dependency","title":"CE-2 waited for copy","detail":"D-4 open 3h","evidence":"tr-a"},{"class":"harness_gap","title":"Triage listed a stopped member as busy"}]}'
+check "retro: missing day" "$(run_err retro --project p1 --summary x | grep -c 'day')" "1"
+
 # --- errors ---
 check "missing action" "$(run_err | grep -c 'Missing action')" "1"
 check "unknown action" "$(run_err explode | grep -c 'Unknown action')" "1"

package/config/skills/agent/core/send-message/execute.sh

@@ -39,7 +39,23 @@ if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then
   shift || true
 fi
 
+# A value flag at the end of the line (or followed by another of this skill's
+# flags) has no value: say so instead of failing on an unset "$2". Any other
+# value is kept, so a message may still start with "-".
+flag_value() {
+  if [[ $# -lt 2 ]]; then
+    error_exit "Flag $1 needs a value, e.g. $1 <value>. Use --help for usage."
+  fi
+  case "$2" in
+    --to|-t|--message|-m|--message-file|--json|-j|--help|-h)
+      error_exit "Flag $1 needs a value, e.g. $1 <value>. Use --help for usage." ;;
+  esac
+}
+
 while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --to|-t|--message|-m|--message-file|--json|-j) flag_value "$@" ;;
+  esac
   case "$1" in
     --to|-t)
       TO="$2"

package/config/skills/agent/core/send-message/execute.test.sh

@@ -12,6 +12,7 @@
 #      queued, not delivered, with a do-not-resend note (#937)
 #   4. another queued answer is reported as queued, not delivered
 #   5. an HTTP error still fails the skill
+#   6. a value flag with no value prints a clear error (#997)
 
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
@@ -76,6 +77,15 @@ else
   echo "  PASS: an HTTP error fails the skill"; PASS=$((PASS + 1))
 fi
 
+OUT=$(bash "$RUN" --to 2>&1 >/dev/null || true)
+check "--to with no value names the flag" "$OUT" 'Flag --to needs a value'
+
+OUT=$(bash "$RUN" --to qa-1 --message 2>&1 >/dev/null || true)
+check "--message with no value names the flag" "$OUT" 'Flag --message needs a value'
+
+OUT=$(bash "$RUN" --to --message hi 2>&1 >/dev/null || true)
+check "--to followed by another flag is refused" "$OUT" 'Flag --to needs a value'
+
 echo ""
 echo "Results: $PASS passed, $FAIL failed"
 [ "$FAIL" -eq 0 ]

package/config/skills/agent/core/trace-read/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: Trace Read
+description: Read how a run went, sized for your context — where the time went (agents working, waiting on the owner, waiting on an agent, idle), owner touches, rework, stalls with their cause, harness interventions, tokens and cost by agent and model, the key events and links. Look a run up by trace, work item, ticket, request or experiment, or list recent runs. For team leads and the orchestrator reviewing runs (retros), and for any agent checking what happened to its own work.
+version: 1.0.0
+category: monitoring
+skillType: claude-skill
+assignableRoles:
+  - orchestrator
+  - team-leader
+  - developer
+  - qa
+  - tpm
+  - designer
+  - frontend-developer
+  - backend-developer
+  - fullstack-dev
+  - qa-engineer
+  - product-manager
+  - architect
+  - generalist
+  - marketing
+  - content-strategist
+  - sales
+  - support
+triggers:
+  - trace
+  - how did the run go
+  - what happened to my work
+  - why was it stuck
+  - stalls
+  - retro
+  - autonomy
+tags:
+  - traces
+  - monitoring
+  - retros
+  - autonomy
+execution:
+  type: script
+  script:
+    file: execute.sh
+    interpreter: bash
+    timeoutMs: 60000
+---
+
+# Trace Read
+
+Every unit of work has a **run trace**: one id from the owner's request (or
+a goal / experiment) through its tickets, work items, agent turns, messages,
+decisions and token usage. `trace-read` turns one into a short summary you
+can reason about without pulling hundreds of raw events into your context.
+
+## Read one run
+
+```bash
+bash execute.sh --trace tr-20261003-ab12cd34
+bash execute.sh --work-item 2c2a1c55-…        # the run a work item belongs to
+bash execute.sh --ticket CE-7                  # a project ticket
+bash execute.sh --ticket TKT-12                # an owner ticket
+bash execute.sh --request <request id>
+bash execute.sh --experiment EXP-3
+```
+
+You get, in at most `--max-chars` (default 4000):
+
+- **Outcome** — done / cancelled / failed / waiting on the owner / in
+  progress, the ticket's status, work items done / failed / open, the
+  experiment's verdict.
+- **Time** — wall time split into *active* (an agent turn was busy),
+  *waiting on owner* (an open decision card, a ticket in review), *waiting on
+  agent* (open work, an unanswered agent message) and *idle* (nobody held
+  anything).
+- **Owner touches** — answered, approved, sent back, corrected (the owner
+  stepped in unprompted).
+- **Rework** — send-backs, retries, failed verifications, subagent
+  send-backs.
+- **Harness interventions** — nudges, redeliveries, wakes, corrections,
+  guard blocks, misroutes (agent messages that were refused or not
+  delivered).
+- **Tokens and cost** by agent and by model.
+- **Stalls** — gaps longer than `--stall-minutes` (default 30) where nobody
+  worked and nothing moved, each with a cause: runtime out of usage or signed
+  out, a message not delivered, waiting on the owner, waiting on an agent, or
+  nobody pushing.
+- **Key events** — state changes, refusals, errors, interventions and owner
+  touches, in time order (routine skill calls and usage lines are only
+  counted).
+- **Links** — the dashboard page with its Timeline tab, and the API.
+
+## Recent runs
+
+```bash
+bash execute.sh --since 2026-10-01T00:00:00Z --limit 10
+```
+
+One line per run, newest first: state, wall / active / waiting-on-owner
+time, touches, rework, stalls (and whether one is still going on),
+interventions, cost. Pick one and read it with `--trace`.
+
+## Options
+
+| Option | Meaning |
+|---|---|
+| `--max-chars N` | Output size bound (600–16000, default 4000) |
+| `--stall-minutes N` | Stall threshold in minutes (default 30) |
+| `--json` | `{traceId, links, text, metrics}` — the full metrics object (not size-bounded) |
+
+## Using it well
+
+- In a retro, name the stage that failed and cite the stall or event by its
+  time; say whether it was agent judgement, a missing skill, a harness gap or
+  an owner dependency.
+- A *waiting on the owner* stall is not a failure by itself; many in a row,
+  or long ones with nothing to decide, are.
+- *Nobody pushing* means work sat with no owner of the next step: that is
+  the run's real gap, not the agent that eventually picked it up.
+- Only work started after run traces were enabled (2026-10-03) has a trace.

package/config/skills/agent/core/trace-read/execute.sh

@@ -0,0 +1,116 @@
+#!/bin/bash
+# =============================================================================
+# trace-read — how a run went, sized for your context: time (active / waiting
+# on the owner / waiting on an agent / idle), owner touches, rework, stalls
+# with their cause, harness interventions, tokens and cost, key events, links.
+#
+# Backed by GET /api/traces (specs/2026-10-03-autonomy-metrics.md, issue #984).
+#
+# Usage:
+#   bash execute.sh --trace tr-20261003-ab12cd34
+#   bash execute.sh --work-item <id> | --ticket CE-7 | --ticket TKT-12 | --request <id> | --experiment EXP-3
+#   bash execute.sh --since 2026-10-01T00:00:00Z [--limit 10]      # recent runs, one line each
+#   Options: [--max-chars 4000] [--stall-minutes 30] [--json]
+# =============================================================================
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/../../_common/lib.sh"
+
+print_usage() {
+  cat <<'EOF_USAGE'
+Usage:
+  bash execute.sh --trace tr-YYYYMMDD-xxxxxxxx     One run: metrics, stalls with causes, key events, links
+  bash execute.sh --work-item ID                   The run a work item belongs to
+  bash execute.sh --ticket CE-7 | --ticket TKT-12  The run of a project ticket or an owner ticket
+  bash execute.sh --request ID                     The run of a Request
+  bash execute.sh --experiment EXP-3               The run of an experiment card
+  bash execute.sh --since ISO [--limit 10]         Runs active since then, one line each, newest first (at most 100)
+Options:
+  --max-chars N       Size bound of the output (default 4000, 600..16000)
+  --stall-minutes N   A gap with no progress longer than this is a stall (default 30)
+  --json              Summary text + links + metrics as JSON (metrics are not size-bounded)
+EOF_USAGE
+}
+
+TRACE=""; WORK_ITEM=""; TICKET=""; REQUEST=""; EXPERIMENT=""; SINCE=""; LIMIT="10"; MAX_CHARS="4000"; STALL=""; JSON_OUT="0"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --trace|-t)       [ $# -ge 2 ] || error_exit "--trace requires a value"; TRACE="$2"; shift 2 ;;
+    --work-item|-w)   [ $# -ge 2 ] || error_exit "--work-item requires a value"; WORK_ITEM="$2"; shift 2 ;;
+    --ticket)         [ $# -ge 2 ] || error_exit "--ticket requires a value"; TICKET="$2"; shift 2 ;;
+    --request|-r)     [ $# -ge 2 ] || error_exit "--request requires a value"; REQUEST="$2"; shift 2 ;;
+    --experiment|-e)  [ $# -ge 2 ] || error_exit "--experiment requires a value"; EXPERIMENT="$2"; shift 2 ;;
+    --since|-s)       [ $# -ge 2 ] || error_exit "--since requires a value"; SINCE="$2"; shift 2 ;;
+    --limit|-l)       [ $# -ge 2 ] || error_exit "--limit requires a value"; LIMIT="$2"; shift 2 ;;
+    --max-chars)      [ $# -ge 2 ] || error_exit "--max-chars requires a value"; MAX_CHARS="$2"; shift 2 ;;
+    --stall-minutes)  [ $# -ge 2 ] || error_exit "--stall-minutes requires a value"; STALL="$2"; shift 2 ;;
+    --json)           JSON_OUT="1"; shift ;;
+    --help|-h)        print_usage; exit 0 ;;
+    *) error_exit "Unknown option: $1 (see --help)" ;;
+  esac
+done
+
+[[ "$MAX_CHARS" =~ ^[0-9]+$ ]] || error_exit "--max-chars must be a whole number"
+[[ "$LIMIT" =~ ^[0-9]+$ ]] || error_exit "--limit must be a whole number"
+[ -z "$STALL" ] || [[ "$STALL" =~ ^[0-9]+(\.[0-9]+)?$ ]] || error_exit "--stall-minutes must be a positive number"
+# The same bounds the backend applies, so the cut below matches its summary.
+[ "$MAX_CHARS" -lt 600 ] && MAX_CHARS=600
+[ "$MAX_CHARS" -gt 16000 ] && MAX_CHARS=16000
+# The backend embeds metrics in at most 100 rows; ask for no more.
+[ "$LIMIT" -gt 100 ] && LIMIT=100
+[ "$LIMIT" -lt 1 ] && LIMIT=1
+
+enc() { jq -rn --arg v "$1" '$v|@uri'; }
+STALL_QS=""
+[ -n "$STALL" ] && STALL_QS="&stallMinutes=$(enc "$STALL")"
+
+# --- Recent runs -------------------------------------------------------------
+if [ -z "$TRACE$WORK_ITEM$TICKET$REQUEST$EXPERIMENT" ]; then
+  [ -n "$SINCE" ] || { print_usage >&2; error_exit "Pass one of --trace, --work-item, --ticket, --request, --experiment or --since"; }
+  if ! RESP=$(api_call_full GET "/traces?since=$(enc "$SINCE")&limit=$(enc "$LIMIT")${STALL_QS}"); then
+    error_exit "Could not list traces since $SINCE"
+  fi
+  if [ "$JSON_OUT" = "1" ]; then
+    printf '%s' "$RESP" | jq -c '{success: true, traces: [.data.traces[] | {traceId, kind: .root.kind, summary: .root.summary, updatedAt, metrics}]}'
+    exit 0
+  fi
+  printf '%s' "$RESP" | jq -r --argjson max "$MAX_CHARS" '
+    def dur: (. / 60000 | floor) as $m
+      | if $m < 1 then "<1m" elif $m < 60 then "\($m)m" elif $m < 1440 then "\($m / 60 | floor)h \($m % 60)m" else "\($m / 1440 | floor)d \(($m % 1440) / 60 | floor)h" end;
+    (.data.traces // []) as $t
+    | (if ($t | length) == 0 then "No traces active since then."
+       else ([ "\($t | length) runs (newest first):" ] + [ $t[] |
+         "\(.traceId) · \(.root.kind) · \(.updatedAt[0:16] | sub("T"; " ")) · \(.root.summary[0:80])" +
+         (if .metrics then
+            " — \(.metrics.state | gsub("_"; " ")); wall \(.metrics.wallMs | dur), active \(.metrics.activeMs | dur), waiting on owner \(.metrics.waitingOwnerMs | dur); touches \(.metrics.ownerTouches), rework \(.metrics.rework), stalls \(.metrics.stalls)\(if .metrics.ongoingStall then " (one ongoing)" else "" end), interventions \(.metrics.interventions), $\(.metrics.costUsd * 100 | round / 100)"
+          else "" end) ] | join("\n")) + "\nRead one: trace-read --trace <id>"
+       end) as $text
+    | if ($text | length) > $max then $text[0:($max - 1)] + "…" else $text end'
+  exit 0
+fi
+
+# --- One run -----------------------------------------------------------------
+if [ -z "$TRACE" ]; then
+  if [ -n "$WORK_ITEM" ]; then Q="workItemId=$(enc "$WORK_ITEM")"
+  elif [ -n "$TICKET" ]; then Q="ticketId=$(enc "$TICKET")"
+  elif [ -n "$REQUEST" ]; then Q="requestId=$(enc "$REQUEST")"
+  else Q="experimentId=$(enc "$EXPERIMENT")"; fi
+  if ! REF=$(api_call GET "/traces/by-ref?${Q}" 2>/dev/null); then
+    error_exit "No trace for that reference (only work started after run traces were enabled has one)"
+  fi
+  TRACE=$(printf '%s' "$REF" | jq -r '.data.traceId // empty')
+  [ -n "$TRACE" ] || error_exit "No trace for that reference"
+fi
+[[ "$TRACE" =~ ^tr-[0-9]{8}-[0-9a-f]+$ ]] || error_exit "Not a trace id (tr-YYYYMMDD-xxxxxxxx): $TRACE"
+
+if ! RESP=$(api_call_full GET "/traces/$(enc "$TRACE")/summary?maxChars=${MAX_CHARS}${STALL_QS}"); then
+  error_exit "Trace $TRACE could not be read"
+fi
+if [ "$JSON_OUT" = "1" ]; then
+  printf '%s' "$RESP" | jq -c --argjson max "$MAX_CHARS" '{success: true, traceId: .data.traceId, links: .data.links, text: (.data.text[0:$max]), metrics: .data.metrics}'
+else
+  # The backend already keeps the text within --max-chars; cut again so a
+  # different backend version can never flood the caller's context.
+  printf '%s' "$RESP" | jq -r --argjson max "$MAX_CHARS" '.data.text as $t | if ($t | length) > $max then $t[0:($max - 1)] + "…" else $t end'
+fi

package/config/skills/agent/core/update-intent-task/execute.sh

@@ -75,6 +75,8 @@ API_URL="${CREWLY_API_URL:-http://localhost:${CREWLY_PORT}}"
 RESPONSE=$(curl -s -w "\n%{http_code}" \
   -X PUT \
   -H "Content-Type: application/json" \
+  -H "X-Agent-Badge: ${CREWLY_AGENT_BADGE:-}" \
+  -H "X-Agent-Session: ${CREWLY_SESSION_NAME:-}" \
   -d "$BODY" \
   "${API_URL}/api/intent-tasks/${TASK_ID}" 2>&1) || {
   echo "{\"success\":false,\"error\":\"Failed to connect to backend at ${API_URL}\"}"

package/config/skills/agent/marketing/submit-for-approval/execute.sh

@@ -65,6 +65,7 @@ case "$ACTION" in
 
     # Submit via API
     RESPONSE=$(curl -s -X POST "${API_BASE}/api/content-approvals" \
+      -H "X-Agent-Badge: ${CREWLY_AGENT_BADGE:-}" \
       -H "Content-Type: application/json" \
       -d "$PAYLOAD" 2>/dev/null || echo '{"error":"API unreachable"}')
 
@@ -93,7 +94,7 @@ case "$ACTION" in
     fi
 
     # Check via API
-    RESPONSE=$(curl -s "${API_BASE}/api/content-approvals/${APPROVAL_ID}" 2>/dev/null || echo '{"error":"API unreachable"}')
+    RESPONSE=$(curl -s -H "X-Agent-Badge: ${CREWLY_AGENT_BADGE:-}" "${API_BASE}/api/content-approvals/${APPROVAL_ID}" 2>/dev/null || echo '{"error":"API unreachable"}')
 
     if echo "$RESPONSE" | jq -e '.id' >/dev/null 2>&1; then
       STATUS=$(echo "$RESPONSE" | jq -r '.status')
@@ -114,7 +115,7 @@ case "$ACTION" in
 
   list)
     # List pending approvals via API
-    RESPONSE=$(curl -s "${API_BASE}/api/content-approvals?teamId=${TEAM_ID}&status=pending" 2>/dev/null || echo '[]')
+    RESPONSE=$(curl -s -H "X-Agent-Badge: ${CREWLY_AGENT_BADGE:-}" "${API_BASE}/api/content-approvals?teamId=${TEAM_ID}&status=pending" 2>/dev/null || echo '[]')
 
     if echo "$RESPONSE" | jq -e '.[0]' >/dev/null 2>&1; then
       COUNT=$(echo "$RESPONSE" | jq 'length')

package/config/skills/orchestrator/decompose-mission/execute.sh

@@ -130,6 +130,8 @@ After generating the JSON, call the following to submit the decomposition:
 \`\`\`bash
 curl -s -X POST "${CREWLY_API_URL}/api/missions/${MISSION_ID}/decompose" \\
   -H "Content-Type: application/json" \\
+  -H "X-Agent-Badge: \${CREWLY_AGENT_BADGE:-}" \\
+  -H "X-Agent-Session: \${CREWLY_SESSION_NAME:-}" \\
   -d '<YOUR_JSON_OUTPUT>'
 \`\`\`
 

package/config/skills/orchestrator/decompose-okr/execute.sh

@@ -122,6 +122,7 @@ After generating the JSON, submit the proposal (children are created as
 \`\`\`bash
 curl -s -X POST "${CREWLY_API_URL}/api/missions/${MISSION_ID}/decompose-okr" \\
   -H "Content-Type: application/json" \\
+  -H "X-Agent-Badge: \${CREWLY_AGENT_BADGE:-}" \\
   -H "X-Agent-Session: \${CREWLY_SESSION_NAME:-}" \\
   -d '<YOUR_JSON_OUTPUT>'
 \`\`\`

package/config/skills/orchestrator/design-team/execute.sh

@@ -135,6 +135,8 @@ After generating the JSON, create the team:
 \`\`\`bash
 curl -s -X POST "${CREWLY_API_URL}/api/teams" \\
   -H "Content-Type: application/json" \\
+  -H "X-Agent-Badge: \${CREWLY_AGENT_BADGE:-}" \\
+  -H "X-Agent-Session: \${CREWLY_SESSION_NAME:-}" \\
   -d '<YOUR_JSON_OUTPUT>'
 \`\`\`
 

package/config/skills/orchestrator/measure-kr/execute.sh

@@ -79,6 +79,8 @@ After measuring, submit the value:
 \`\`\`bash
 curl -s -X POST "${CREWLY_API_URL}/api/missions/${MISSION_ID}/key-results/${KR_ID}/measure" \\
   -H "Content-Type: application/json" \\
+  -H "X-Agent-Badge: \${CREWLY_AGENT_BADGE:-}" \\
+  -H "X-Agent-Session: \${CREWLY_SESSION_NAME:-}" \\
   -d '{"value": <MEASURED_VALUE>, "source": "measure-kr-skill", "note": "Brief description of how measured"}'
 \`\`\`
 

package/config/skills/orchestrator/review-mission/execute.sh

@@ -119,6 +119,8 @@ After generating the decision, submit it:
 \`\`\`bash
 curl -s -X POST "${CREWLY_API_URL}/api/missions/${MISSION_ID}/review-decision" \\
   -H "Content-Type: application/json" \\
+  -H "X-Agent-Badge: \${CREWLY_AGENT_BADGE:-}" \\
+  -H "X-Agent-Session: \${CREWLY_SESSION_NAME:-}" \\
   -d '<YOUR_JSON_OUTPUT>'
 \`\`\`
 

package/config/skills/orchestrator/send-message/execute.sh

@@ -9,10 +9,18 @@ source "${SCRIPT_DIR}/../_common/lib.sh"
 # safe-call guide shows the flag form.
 if [ "${1:-}" != "" ] && [ "${1#--}" != "${1}" ]; then
   FLAG_SESSION=""; FLAG_MESSAGE=""; FLAG_FORCE=""
+  # A value flag at the end of the line (or followed by another flag) has no
+  # value: say so instead of letting `shift 2` exit silently under set -e.
+  flag_value() {
+    case "${2-__missing__}" in
+      __missing__|--session|--sessionName|--to|--message|--force)
+        error_exit "Flag $1 needs a value, e.g. $1 <value>" ;;
+    esac
+  }
   while [ $# -gt 0 ]; do
     case "$1" in
-      --session|--sessionName|--to) FLAG_SESSION="${2:-}"; shift 2 ;;
-      --message) FLAG_MESSAGE="${2:-}"; shift 2 ;;
+      --session|--sessionName|--to) flag_value "$@"; FLAG_SESSION="$2"; shift 2 ;;
+      --message) flag_value "$@"; FLAG_MESSAGE="$2"; shift 2 ;;
       --force) FLAG_FORCE="true"; shift ;;
       *) error_exit "Unknown option: $1" ;;
     esac

package/config/skills/orchestrator/send-message/execute.test.sh

@@ -71,6 +71,15 @@ else
   PASS=$((PASS + 1)); echo "  ✓ missing session delivers nothing"
 fi
 
+run --to
+check "--to with no value names the flag" "Flag --to needs a value" "$OUT"
+
+run --to dev-5 --message
+check "--message with no value names the flag" "Flag --message needs a value" "$OUT"
+
+run --to --message hi
+check "--to followed by another flag is refused" "Flag --to needs a value" "$OUT"
+
 run --bogus x
 check "unknown flag is refused" "Unknown option: --bogus" "$OUT"
 

package/config/skills/team-leader/design-checklist/execute.sh

@@ -144,6 +144,8 @@ CHECKLIST_EOF
 # Submit for approval
 curl -s -X POST "${CREWLY_API_URL}/api/task-management/${TASK_ID}/checklist" \\
   -H "Content-Type: application/json" \\
+  -H "X-Agent-Badge: \${CREWLY_AGENT_BADGE:-}" \\
+  -H "X-Agent-Session: \${CREWLY_SESSION_NAME:-}" \\
   -d @"${PROJECT_PATH}/.crewly/tasks/checklist-${TASK_ID}.json"
 \`\`\`