crewly 1.20.194 → 1.20.196

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/desktop-app-control/execute.sh

@@ -32,6 +32,9 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 LOG_DIR="${HOME}/.crewly/logs"
 LOG_FILE="${LOG_DIR}/desktop-app-control.log"
+# Where `scan` looks for installed apps. Overridable so the scan can be
+# exercised against a fixture directory on machines without /Applications.
+APPLICATIONS_DIR="${CREWLY_APPLICATIONS_DIR:-/Applications}"
 
 # Ensure log directory exists
 mkdir -p "$LOG_DIR"
@@ -108,7 +111,7 @@ do_scan() {
   }
 
   # Scan for Electron apps by checking framework directory
-  for app_dir in /Applications/*.app; do
+  for app_dir in "$APPLICATIONS_DIR"/*.app; do
     [ ! -d "$app_dir" ] && continue
     if [ -d "$app_dir/Contents/Frameworks/Electron Framework.framework" ]; then
       local app_name
@@ -138,7 +141,7 @@ do_scan() {
   local browser port
   while IFS='|' read -r browser port; do
     [ -z "$browser" ] && continue
-    if [ -d "/Applications/$browser.app" ]; then
+    if [ -d "$APPLICATIONS_DIR/$browser.app" ]; then
       local running="false"
       if pgrep -f "$browser" > /dev/null 2>&1; then
         running="true"

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

@@ -5,10 +5,35 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "${SCRIPT_DIR}/../_common/lib.sh"
 
-INPUT=$(read_json_input "${1:-}")
+# CLI flags (--session/--to, --message, --force) are accepted too: the Gemini
+# 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_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
+  done
+  INPUT=$(jq -n --arg s "$FLAG_SESSION" --arg m "$FLAG_MESSAGE" --arg f "$FLAG_FORCE" \
+    '{sessionName: $s, message: $m} + (if $f == "true" then {force: true} else {} end)')
+else
+  INPUT=$(read_json_input "${1:-}")
+fi
 [ -z "$INPUT" ] && error_exit "Usage: execute.sh '{\"sessionName\":\"agent-session\",\"message\":\"hello\"}' or echo '{...}' | execute.sh"
 
-SESSION_NAME=$(printf '%s' "$INPUT" | jq -r '.sessionName // empty')
+# `to` is accepted as an alias for `sessionName` (older prompt examples used it).
+SESSION_NAME=$(printf '%s' "$INPUT" | jq -r '.sessionName // .to // empty')
 MESSAGE=$(printf '%s' "$INPUT" | jq -r '.message // empty')
 FORCE=$(printf '%s' "$INPUT" | jq -r '.force // empty')
 require_param "sessionName" "$SESSION_NAME"

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

@@ -0,0 +1,89 @@
+#!/bin/bash
+# Tests for the orchestrator send-message skill.
+#
+# Guards the input forms the orchestrator prompt teaches: JSON with
+# `sessionName` (canonical), JSON with `to` (older examples), and the CLI
+# flag form from the Gemini safe-call guide. `curl` is stubbed on PATH, so
+# every case runs offline and records the real request the skill issues.
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PASS=0
+FAIL=0
+
+check() {
+  local name="$1" needle="$2" haystack="$3"
+  if printf '%s' "$haystack" | grep -qF -- "$needle"; then
+    PASS=$((PASS + 1)); echo "  ✓ ${name}"
+  else
+    FAIL=$((FAIL + 1)); echo "  ✗ ${name}"; echo "    expected to contain: ${needle}"; echo "    actual: ${haystack}"
+  fi
+}
+
+STUB_DIR="$(mktemp -d)"
+cat > "$STUB_DIR/curl" << 'STUB_EOF'
+#!/bin/bash
+URL=""; BODY=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -d) BODY="$2"; shift 2 ;;
+    -X|-H|-w) shift 2 ;;
+    -s) shift ;;
+    *) URL="$1"; shift ;;
+  esac
+done
+printf '%s %s\n' "$URL" "$(printf '%s' "$BODY" | tr -d '\n ')" >> "$CURL_LOG"
+printf '{"success":true}\n200'
+STUB_EOF
+chmod +x "$STUB_DIR/curl"
+export PATH="$STUB_DIR:$PATH" CREWLY_API_URL="http://stub.invalid" CREWLY_SESSION_NAME="crewly-orc"
+
+# Runs the skill; sets OUT (stdout+stderr) and REQ (requests sent).
+run() {
+  CURL_LOG="$(mktemp)"; export CURL_LOG
+  OUT="$(bash "$SCRIPT_DIR/execute.sh" "$@" </dev/null 2>&1)" || true
+  REQ="$(cat "$CURL_LOG")"; rm -f "$CURL_LOG"
+}
+
+echo "=== orchestrator send-message tests ==="
+
+run '{"sessionName":"dev-1","message":"hi"}'
+check "sessionName JSON reaches /deliver for that session" "http://stub.invalid/api/terminal/dev-1/deliver" "$REQ"
+check "readiness-aware delivery by default" '"waitForReady":true' "$REQ"
+
+run '{"to":"dev-2","message":"hi"}'
+check "'to' is accepted as an alias for sessionName" "/api/terminal/dev-2/deliver" "$REQ"
+
+run --to dev-3 --message "hello there"
+check "--to/--message flags work" "/api/terminal/dev-3/deliver" "$REQ"
+check "flag message is sent" '"message":"hellothere"' "$REQ"
+
+run --session dev-4 --message hi --force
+check "--session and --force flags work" "/api/terminal/dev-4/deliver" "$REQ"
+check "--force sends force:true" '"force":true' "$REQ"
+
+run '{"message":"no target"}'
+check "missing session is reported" "sessionName" "$OUT"
+# (lib.sh sends a skill-start heartbeat; what must not happen is a delivery.)
+if printf '%s' "$REQ" | grep -q "/deliver"; then
+  FAIL=$((FAIL + 1)); echo "  ✗ missing session must not deliver anything"
+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"
+
+rm -rf "$STUB_DIR"
+echo ""
+echo "=== Results: ${PASS} passed, ${FAIL} failed ==="
+[ "$FAIL" -eq 0 ]

package/config/skills/registry.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 2,
-  "lastUpdated": "2026-10-02T23:58:51.779Z",
+  "lastUpdated": "2026-10-03T01:12:43.309Z",
   "cdnBaseUrl": "https://raw.githubusercontent.com/stevehuang0115/crewly/main",
   "source": "github",
   "items": [
@@ -1412,7 +1412,7 @@
       "name": "SEO Ops",
       "description": "Search Console-driven SEO operations for any site: query patterns (low-CTR top-3, near-miss 4-20, rising queries, keyword cannibalization), per-URL report cards, pre-publish SEO/AEO checks, a gated programmatic-page queue, and a live-diff gate that stops agents from removing things from live pages. Use when auditing organic search, deciding what to rewrite, or before changing a live page. For writing posts use seo-blog-writer instead.",
       "author": "Crewly",
-      "version": "1.1.0",
+      "version": "1.2.0",
       "category": "development",
       "tags": [
         "seo",
@@ -1425,12 +1425,12 @@
       "downloads": 0,
       "rating": 0,
       "createdAt": "2026-09-29T01:43:29.904Z",
-      "updatedAt": "2026-10-02T23:58:51.779Z",
+      "updatedAt": "2026-10-03T01:12:43.309Z",
       "source": "config/skills/agent/marketplace/seo-ops",
       "assets": {
         "archive": "config/skills/agent/marketplace/seo-ops",
         "checksum": "",
-        "sizeBytes": 122232
+        "sizeBytes": 149452
       },
       "metadata": {
         "skillType": "claude-skill",
@@ -1448,7 +1448,8 @@
           "pre-publish seo check",
           "programmatic seo pages",
           "live page diff",
-          "experiment metric"
+          "experiment metric",
+          "url inspection"
         ],
         "files": [
           "execute.sh",

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"
 \`\`\`
 

package/config/skills/team-leader/signal-digest/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: Signal Digest
+description: "Daily signal digest for a site you own as team lead: GA4 traffic and key events, Search Console opportunities (low-CTR top-3, near-miss 4-20, rising, cannibalization), the site's inbound mail and broken pages / JS errors, minus what was already tried — turned into 3-5 ranked actions the owner answers Do / Skip on one Slack card. Do opens an experiment ticket."
+version: 1.1.0
+category: productivity
+skillType: claude-skill
+assignableRoles:
+  - team-leader
+triggers:
+  - daily signal digest
+  - daily signals
+  - what should we try on the site
+  - site opportunities
+tags:
+  - seo
+  - analytics
+  - experiments
+  - owner-decisions
+execution:
+  type: script
+  script:
+    file: execute.sh
+    interpreter: bash
+    timeoutMs: 180000
+---
+
+# Signal Digest (team lead)
+
+One run per site per day (#987, `specs/2026-10-03-signal-digest.md`):
+
+1. **collect** — gathers the signals and drafts actions.
+2. **you decide** — keep the 3–5 actions most worth the owner's tap, rewrite them in plain words,
+   add your own (e.g. a question the inbox keeps asking → an FAQ section).
+3. **propose** — the owner gets **one card**: each action with **Do** / **Skip**.
+   - **Do** opens an experiment ticket in the site's project and, when the action names an
+     `experiment` metric, an **experiment card** (#986) linked to it: the baseline is captured when
+     the ticket is done and the result is measured after 14 days, automatically. You get a
+     `[SIGNAL DIGEST]` message with both ids. Ship it and close the ticket.
+   - **Skip** keeps that action off your list for 30 days. A Do keeps it off for 90.
+   - Unanswered actions are replaced by your next digest (you may propose them again).
+
+## Setup (once per site)
+
+The config is the site's **seo-ops** config plus a `signalDigest` section — copy
+`signal-digest.config.example.json`. Google access is seo-ops's service account
+(`SEO_OPS_GOOGLE_CREDENTIALS`, read-only: Search Console user + GA4 Viewer).
+
+| `signalDigest` key | Meaning |
+|---|---|
+| `site` | Site name on the card and in the history (default: host of `siteUrl`) |
+| `project` | Project the Do tickets go into (name or id). Without it a Do opens no ticket |
+| `days` | Window, compared with the window before it (default 7) |
+| `ga4.conversionEvents` | Key events that count as conversions (default: all key events) |
+| `inbox.query` / `.account` / `.max` | Gmail search for the site's inbound requests (Google connector) |
+| `errors.checkSitemap` / `.maxUrls` | Fetch up to N sitemap pages and report the ones not answering 200 (default on, 60) |
+| `errors.url` or `errors.command` | JS errors as JSON: `[{"message","count","url"}]` or `{"errors":[…]}` |
+| `experimentLog` | Extra Markdown experiment log; a draft whose query/page it mentions is dropped (experiment cards are always checked) |
+| `thresholds` | `ga4DropPct` (20), `ga4MinPrevSessions` (50), `ga4MinPrevKeyEvents` (5) |
+
+Daily run: `bash execute.sh schedule --config <file> [--cron "0 8 * * *"] [--timezone America/New_York]`
+prints the cron task; hand it to the orchestrator to create with `create-cron`.
+
+## Commands
+
+```bash
+bash execute.sh collect --config ce.signal.json            # JSON: signals, alreadyTried, candidates
+bash execute.sh propose --config ce.signal.json --actions actions.json
+```
+
+`collect` prints `sources` (ok / not configured / error: why), the signals (`ga4`, `gsc`,
+`inbox`, `errors`), `alreadyTried` (dropped drafts and why: the owner's earlier Do / Skip, an
+experiment card on the same query or page, or the experiment log), `pendingOnOwner` and up to 10
+`candidates`, best first. GA4 respects seo-ops' `ga4HostName`. The sitemap check takes a different
+slice of `errors.maxUrls` pages each day, so the whole sitemap is covered over a few days.
+
+`collect` also reports the source statuses to Crewly (`sourceReport` in the output). The owner is
+told **once** when a source starts failing and once when it works again; the digest card shows
+each source's status. So never post about a failing source yourself. Exit `1` when no source
+could be examined: stop there and do not propose from nothing.
+
+`--actions` is a JSON array (file or inline) of 3–5 actions, best first:
+
+```json
+[{"key":"gsc:low-ctr:h1b visa fee","source":"gsc",
+  "signal":"'h1b visa fee' ranks #2 with 4% CTR on 900 impressions (7 days)",
+  "proposal":"Rewrite the title and description of /h1b-fee to answer the fee question",
+  "expectedEffect":"CTR 4% → ~16%: about +100 clicks a week",
+  "effort":"S — 1 h","metric":"GSC CTR for 'h1b visa fee'",
+  "experiment":{"source":"gsc","measure":"ctr","query":"h1b visa fee","page":"https://visa.careerengine.us/h1b-fee"}}]
+```
+
+- `key` is the action's identity across days. Keep the draft's key when you keep its action;
+  for your own, use `<source>:<kind>:<subject>`.
+- `source`: `ga4` | `gsc` | `inbox` | `errors` | `other`.
+- Lengths: signal ≤ 400, proposal ≤ 200, expectedEffect ≤ 240, effort ≤ 60 characters.
+- `experiment` (optional, keep the draft's): the seo-ops metric that measures it —
+  `source` gsc (`clicks` / `impressions` / `ctr` / `position`, filters `query`, `page`) or
+  ga4 (`sessions` / `events`, `event`, `channel`). Leave it out for fixes that move no metric
+  (a broken page, a JS error).
+
+`propose` answers `{"success":true,"digestId":"SD-4","card":"posted"}`. A `409` lists actions
+the owner already decided — replace them and propose again. One card a day: while today's
+digest (the last 20 hours) still has open actions, proposing the same actions returns it and
+different ones get a `409` — do not post a second card.
+
+## Rules
+
+- Never propose what `alreadyTried` lists, and never more than 5 actions.
+- Each action states signal → proposal → expected effect → effort, with a number when there is one.
+- This skill only reads Google and Gmail; it never changes the site.