crewly 1.20.106 → 1.20.107

package/config/skills/agent/core/list-my-followups/execute.sh

@@ -21,7 +21,10 @@ Options:
   --json   -j     Raw JSON payload (legacy)
   --help   -h     Show this help
 
-Output: JSON object { success, count, data: [Trigger, ...] }
+Output: JSON object { success, examined, count, data: [Trigger, ...] }
+  examined = triggers received from the backend BEFORE the team filter;
+  count    = triggers left after the team/status/prefix filters.
+  A truncated or malformed response is an error (exit 1), never count 0.
 EOF_USAGE
 }
 
@@ -60,7 +63,25 @@ fi
 TEAM_ID=$(resolve_team_id || true)
 [ -z "$TEAM_ID" ] && { echo '{"error":"Cannot resolve owning team from CREWLY_SESSION_NAME"}' >&2; exit 1; }
 
-LIST_RESP=$(api_call GET "/triggers" "")
+# GET /triggers is the whole trigger table (335 rows / 233 KB on 2026-09-21),
+# well over the skill-output cap. Plain api_call would hand back a
+# {"truncated":true} envelope and `.data // []` would turn that into an empty
+# list with success:true. api_call_full returns the real body or fails.
+if ! LIST_RESP=$(api_call_full GET "/triggers" ""); then
+  jq -n '{success:false, examined:0, error:"GET /triggers failed or came back as a truncated envelope; refusing to report an empty follow-up list"}'
+  exit 1
+fi
+
+# A guard must report what it examined, not just its verdict. `.data` has to be
+# an array; an envelope, an error object or anything else is an UNKNOWN result,
+# not "no triggers" — refuse rather than print success with count 0.
+EXAMINED=$(printf '%s' "$LIST_RESP" | jq -r 'if type == "object" then (if (.data | type) == "array" then (.data | length) else "not-an-array" end) else "not-an-object" end' 2>/dev/null || echo "unparseable")
+if ! [ "$EXAMINED" -ge 0 ] 2>/dev/null; then
+  jq -n --arg why "$EXAMINED" --arg head "${LIST_RESP:0:200}" \
+    '{success:false, examined:0, error:("GET /triggers returned a body whose .data is " + $why + "; refusing to report an empty follow-up list"), head:$head}'
+  exit 1
+fi
+
 FILTERED=$(printf '%s' "$LIST_RESP" | jq \
   --arg team "$TEAM_ID" \
   --arg status "$STATUS_FILTER" \
@@ -71,4 +92,5 @@ FILTERED=$(printf '%s' "$LIST_RESP" | jq \
     | (if $prefix != "" then map(select(.name != null and (.name | startswith($prefix)))) else . end)')
 
 COUNT=$(printf '%s' "$FILTERED" | jq 'length')
-printf '%s' "$FILTERED" | jq --arg c "$COUNT" '{success:true, count:($c|tonumber), data:.}'
+printf '%s' "$FILTERED" | jq --arg c "$COUNT" --arg e "$EXAMINED" \
+  '{success:true, examined:($e|tonumber), count:($c|tonumber), data:.}'

package/config/skills/agent/core/list-my-followups/execute.test.sh

@@ -36,6 +36,78 @@ echo "--- Team resolution ---"
 OUTPUT=$(env -u CREWLY_SESSION_NAME bash "$SCRIPT_DIR/execute.sh" 2>&1) || true
 assert_contains "No session → team-resolve error" "Cannot resolve owning team" "$OUTPUT"
 
+assert_eq() {
+  local test_name="$1" expected="$2" actual="$3"
+  if [ "$expected" = "$actual" ]; then
+    PASS=$((PASS + 1))
+    echo "  ✓ ${test_name}"
+  else
+    FAIL=$((FAIL + 1))
+    echo "  ✗ ${test_name}"
+    echo "    expected: ${expected}"
+    echo "    got:      ${actual}"
+  fi
+}
+
+echo ""
+echo "--- Response shape: a guard must report what it examined ---"
+
+# Run the real skill against a lib.sh double: the REAL library plus an
+# api_call override, so the real api_call_full is what the skill exercises.
+# The double returns whatever $MOCK_RESPONSE holds, for any request.
+REAL_LIB="$(cd "$SCRIPT_DIR/../../../_common" && pwd)/lib.sh"
+TMP=$(mktemp -d); trap 'rm -rf "$TMP"' EXIT
+mkdir -p "$TMP/skills/agent/core/list-my-followups" "$TMP/skills/agent/_common"
+cp "$SCRIPT_DIR/execute.sh" "$TMP/skills/agent/core/list-my-followups/execute.sh"
+cat > "$TMP/skills/agent/_common/lib.sh" <<'STUB_EOF'
+source "$REAL_LIB"
+resolve_team_id() { echo "team-a"; }
+api_call() { printf '%s' "$MOCK_RESPONSE"; }
+STUB_EOF
+
+# run <mock-response> [skill args...] -> sets CODE and OUTPUT (stdout only)
+run() {
+  local mock="$1"; shift
+  CODE=0
+  OUTPUT=$(env -u CREWLY_SESSION_NAME REAL_LIB="$REAL_LIB" MOCK_RESPONSE="$mock" \
+    bash "$TMP/skills/agent/core/list-my-followups/execute.sh" "$@" 2>/dev/null) || CODE=$?
+}
+
+# What api_call hands back when GET /triggers is over the output cap (233 KB /
+# 335 rows on 2026-09-21). The parked file deliberately does not exist.
+ENVELOPE='{"truncated":true,"bytes":233481,"file":"'"$TMP"'/nonexistent.json","head":"{\"success\":true,\"data\":[{\"id\":\"4bc7","hint":"pass --full or read the file"}'
+ROWS='{"success":true,"data":[
+  {"id":"t-1","teamId":"team-a","name":"followup:abc","status":"paused"},
+  {"id":"t-2","teamId":"team-b","name":"followup:abc","status":"active"},
+  {"id":"t-3","teamId":"team-b","name":"watch:x","status":"active"}]}'
+
+run "$ENVELOPE"
+assert_eq "Envelope -> non-zero exit" "1" "$CODE"
+assert_contains "Envelope -> success:false" '"success":false' "$(printf '%s' "$OUTPUT" | jq -c .)"
+assert_contains "Envelope -> explicit error field" 'truncated envelope' "$OUTPUT"
+assert_eq "Envelope -> never count 0" "" "$(printf '%s' "$OUTPUT" | jq -r '.count // empty')"
+
+run "$ROWS"
+assert_eq "Rows -> exit 0" "0" "$CODE"
+assert_eq "Rows -> examined counts every row before the team filter" "3" "$(printf '%s' "$OUTPUT" | jq -r '.examined')"
+assert_eq "Rows -> count is the team's rows" "1" "$(printf '%s' "$OUTPUT" | jq -r '.count')"
+assert_eq "Rows -> the team's trigger is returned" "t-1" "$(printf '%s' "$OUTPUT" | jq -r '.data[0].id')"
+
+run "$ROWS" --status active
+assert_eq "--status active with none active -> legitimate count 0" "0" "$(printf '%s' "$OUTPUT" | jq -r '.count')"
+assert_eq "--status active -> examined still 3" "3" "$(printf '%s' "$OUTPUT" | jq -r '.examined')"
+assert_eq "--status active -> success:true (this zero is real)" "true" "$(printf '%s' "$OUTPUT" | jq -r '.success')"
+
+run "$ROWS" --name-prefix watch:
+assert_eq "--name-prefix scoped to team -> count 0, examined 3" "0/3" "$(printf '%s' "$OUTPUT" | jq -r '"\(.count)/\(.examined)"')"
+
+run '{"success":true,"data":{"oops":1}}'
+assert_eq "Non-array .data -> non-zero exit" "1" "$CODE"
+assert_contains "Non-array .data -> error says why" 'not-an-array' "$OUTPUT"
+
+run '{"error":true,"status":500}'
+assert_eq "Error object without .data -> non-zero exit" "1" "$CODE"
+
 echo ""
 echo "=== Results: ${PASS} passed, ${FAIL} failed ==="
 [ $FAIL -eq 0 ]

package/config/skills/agent/core/poll-tasks/execute.sh

@@ -77,9 +77,9 @@ fi
 
 QUERY_PARAMS="?types=${TYPES}&owner=agent"
 
-AVAILABLE_RESPONSE=$(api_call GET "/task-pool${QUERY_PARAMS}" 2>&1) || {
+AVAILABLE_RESPONSE=$(api_call_full GET "/task-pool${QUERY_PARAMS}" 2>&1) || {
   # Also try without owner filter — some items may target specific agents
-  AVAILABLE_RESPONSE=$(api_call GET "/task-pool?types=${TYPES}&target=${SESSION_NAME}" 2>&1) || {
+  AVAILABLE_RESPONSE=$(api_call_full GET "/task-pool?types=${TYPES}&target=${SESSION_NAME}" 2>&1) || {
     error_exit "Failed to query Task Pool: ${AVAILABLE_RESPONSE}"
   }
 }
@@ -93,7 +93,7 @@ AVAILABLE_COUNT=$(printf '%s' "$AVAILABLE_RESPONSE" | jq -r '.count // 0')
 # picker filters owner=agent and would otherwise ignore these items).
 TARGET_PINNED_ID=""
 if [ "$AVAILABLE_COUNT" -eq 0 ]; then
-  TARGET_RESPONSE=$(api_call GET "/task-pool?types=${TYPES}&target=${SESSION_NAME}" 2>&1) || TARGET_RESPONSE=""
+  TARGET_RESPONSE=$(api_call_full GET "/task-pool?types=${TYPES}&target=${SESSION_NAME}" 2>&1) || TARGET_RESPONSE=""
   TARGET_COUNT=$(printf '%s' "$TARGET_RESPONSE" | jq -r '.count // 0' 2>/dev/null || echo 0)
   if [ "$TARGET_COUNT" -gt 0 ]; then
     AVAILABLE_RESPONSE="$TARGET_RESPONSE"

package/config/skills/agent/core/reply-channel/SKILL.md

@@ -106,7 +106,7 @@ An unknown name returns `404` with the names that were found.
 - `CREWLY_SESSION_NAME` — your agent session id. Auto-set in agent sessions.
   The skill attaches it as `X-Agent-Session` so the backend routes the
   reply as `senderType:"agent"`.
-- `CREWLY_API_URL` — defaults to `http://localhost:8787`.
+- `CREWLY_API_URL` — set by Crewly to the running instance (e.g. `http://localhost:8797` when started with `-p 8797`); falls back to `http://localhost:${WEB_PORT:-8787}`.
 
 ## Success / failure
 

package/config/skills/agent/core/report-progress/execute.sh

@@ -30,7 +30,7 @@ require_param "current" "$CURRENT"
 
 # Resolve target WI: explicit > running claim for this agent
 if [ -z "$WORK_ITEM_ID" ]; then
-  POOL_RESP=$(api_call GET "/task-pool/items?status=running&target=${SESSION_NAME}" 2>/dev/null || echo '{}')
+  POOL_RESP=$(api_call_full GET "/task-pool/items?status=running&target=${SESSION_NAME}" 2>/dev/null || echo '{}')
   WORK_ITEM_ID=$(echo "$POOL_RESP" | jq -r '.workItems[0].id // .data[0].id // empty' 2>/dev/null || true)
 fi
 

package/config/skills/agent/core/report-status/execute.sh

@@ -259,7 +259,7 @@ if [ "$STATUS" = "done" ]; then
   WI_RESOLUTION="explicit"
 
   if [ -z "$TARGET_WI_ID" ]; then
-    POOL_RESP=$(api_call GET "/task-pool/items?status=running&target=${SESSION_NAME}" 2>/dev/null || echo '{}')
+    POOL_RESP=$(api_call_full GET "/task-pool/items?status=running&target=${SESSION_NAME}" 2>/dev/null || echo '{}')
     RUNNING_IDS=$(printf '%s' "$POOL_RESP" | jq -r '((.workItems // .data // []) | map(.id)) | .[]' 2>/dev/null || true)
     RUNNING_COUNT=$(printf '%s' "$RUNNING_IDS" | grep -c . || true)
 

package/config/skills/agent/core/slack-post/SKILL.md

@@ -117,7 +117,7 @@ two are told apart. Write ids exactly as Slack shows them.
 
 - `CREWLY_SESSION_NAME` — your agent session, attached automatically. The post
   is sent under that agent's identity, so this must be set.
-- `CREWLY_API_URL` — defaults to `http://localhost:8787`.
+- `CREWLY_API_URL` — set by Crewly to the running instance (e.g. `http://localhost:8797` when started with `-p 8797`); falls back to `http://localhost:${WEB_PORT:-8787}`.
 
 ## Output
 

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

@@ -69,7 +69,7 @@ fi
 # ---------------------------------------------------------------------------
 # Call backend API
 # ---------------------------------------------------------------------------
-CREWLY_PORT="${CREWLY_PORT:-8787}"
+CREWLY_PORT="${CREWLY_PORT:-${WEB_PORT:-8787}}"
 API_URL="${CREWLY_API_URL:-http://localhost:${CREWLY_PORT}}"
 
 RESPONSE=$(curl -s -w "\n%{http_code}" \

package/config/skills/agent/marketing/brand-onboarding/execute.sh

@@ -27,7 +27,7 @@ OUTPUT_DIR=$(printf '%s' "$INPUT" | jq -r '.outputDir // ""')
 PROJECT_PATH=$(printf '%s' "$INPUT" | jq -r '.projectPath // ""')
 
 # Crewly API base URL
-API_BASE="${CREWLY_API_URL:-http://localhost:3000}"
+API_BASE="${CREWLY_API_URL:-http://localhost:${WEB_PORT:-8787}}"
 
 # Local storage directory
 LOCAL_DIR="${PROJECT_PATH:-.}/.crewly/onboarding"

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

@@ -28,7 +28,7 @@ TEAM_ID=$(printf '%s' "$INPUT" | jq -r '.teamId // ""')
 PROJECT_PATH=$(printf '%s' "$INPUT" | jq -r '.projectPath // ""')
 
 # Crewly API base URL
-API_BASE="${CREWLY_API_URL:-http://localhost:3000}"
+API_BASE="${CREWLY_API_URL:-http://localhost:${WEB_PORT:-8787}}"
 
 case "$ACTION" in
   submit)

package/config/skills/agent/remote-browser/SOP-google-flow-video.md

@@ -131,7 +131,7 @@ bash .../remote-browser/execute.sh '{"action":"navigate","url":"https://labs.goo
 
 ```bash
 # Direct API call (bypasses execute.sh):
-curl -s -X POST http://localhost:8787/api/browser/set-file-input \
+curl -s -X POST "$CREWLY_API_URL/api/browser/set-file-input" \
   -H "Content-Type: application/json" \
   -d '{"selector":"input[type=file]","filePaths":["/tmp/image.png"]}'
 

package/config/skills/agent/remote-browser/execute.sh

@@ -42,6 +42,11 @@
 #                       call (drops the X-Agent-Session header).
 #   --active            Only meaningful with `bind-tab`: foreground
 #                       the new tab on creation.
+#   --goal <text>       What you're trying to accomplish. Sent as the
+#                       X-Agent-Goal header so the user's Chrome takeover
+#                       banner shows your objective (e.g. "Verify DMARC
+#                       setup"), not just the current tool. Overrides any
+#                       inherited CREWLY_AGENT_GOAL for this call.
 #
 # Supported actions and their parameters:
 #   status              — connection status (no params)
@@ -86,6 +91,9 @@ EXTRA_PARAMS=""
 TAB_ID=""        # --tab-id <N>: explicit override
 NO_BIND="false"  # --no-bind: drop X-Agent-Session for this call
 FOREGROUND="false" # --active: only meaningful with bind-tab
+GOAL=""          # --goal <text>: what the agent is trying to accomplish
+                 # (shown in the Chrome takeover banner). Overrides any
+                 # inherited CREWLY_AGENT_GOAL for this call.
 
 # Detect legacy JSON argument
 if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then
@@ -119,6 +127,10 @@ while [[ $# -gt 0 ]]; do
       CODE="$2"
       shift 2
       ;;
+    --goal|-g)
+      GOAL="$2"
+      shift 2
+      ;;
     --params|-P)
       EXTRA_PARAMS="$2"
       shift 2
@@ -142,6 +154,11 @@ while [[ $# -gt 0 ]]; do
     --help|-h)
       echo "Usage: execute.sh --action navigate --url https://example.com"
       echo "       execute.sh '{\"action\":\"screenshot\"}'"
+      echo "       execute.sh --action navigate --url https://x.com --goal 'Check pricing'"
+      echo ""
+      echo "  --goal <text>  What you're trying to accomplish; shown in the"
+      echo "                 user's Chrome takeover banner. Recommended on the"
+      echo "                 first action of a browser task."
       echo ""
       echo "Actions: status, navigate, screenshot, read-text, click, fill, type,"
       echo "         scroll, hover, press-key, get-element, wait-for-selector,"
@@ -184,6 +201,7 @@ if [ -n "$INPUT_JSON" ]; then
   [ -z "$VALUE" ] && VALUE=$(printf '%s' "$INPUT" | jq -r '.value // empty')
   [ -z "$TEXT" ] && TEXT=$(printf '%s' "$INPUT" | jq -r '.text // empty')
   [ -z "$CODE" ] && CODE=$(printf '%s' "$INPUT" | jq -r '.code // empty')
+  [ -z "$GOAL" ] && GOAL=$(printf '%s' "$INPUT" | jq -r '.goal // empty')
   # Per-tab dispatch fields surfaced in JSON input. CLI flags win over JSON
   # (CLI is more explicit). Empty string = "not provided".
   if [ -z "$TAB_ID" ]; then
@@ -200,7 +218,7 @@ if [ -n "$INPUT_JSON" ]; then
   # Capture all extra fields from JSON input as pass-through params (strip
   # per-tab fields too — they're handled by the dedicated branches below).
   if [ -z "$EXTRA_PARAMS" ]; then
-    EXTRA_PARAMS=$(printf '%s' "$INPUT" | jq -c 'del(.action, .url, .selector, .value, .text, .code, .tabId, .noBind, .active) | if length == 0 then empty else . end' 2>/dev/null || true)
+    EXTRA_PARAMS=$(printf '%s' "$INPUT" | jq -c 'del(.action, .url, .selector, .value, .text, .code, .goal, .tabId, .noBind, .active) | if length == 0 then empty else . end' 2>/dev/null || true)
   fi
 fi
 
@@ -493,6 +511,15 @@ esac
 # X-Agent-Session header for this single call (api_call reads it from the
 # env). Using a subshell to scope the unset.
 
+# An explicit --goal (or JSON `goal`) overrides any inherited CREWLY_AGENT_GOAL
+# for this call. lib.sh::api_call reads CREWLY_AGENT_GOAL and forwards it as the
+# X-Agent-Goal header, which the backend stamps onto the browser command so the
+# Chrome takeover banner shows what the agent is doing. When --goal is absent we
+# leave CREWLY_AGENT_GOAL untouched (auto path).
+if [ -n "$GOAL" ]; then
+  export CREWLY_AGENT_GOAL="$GOAL"
+fi
+
 run_api_call() {
   if [ "$METHOD" = "GET" ]; then
     api_call GET "$ENDPOINT"
@@ -524,7 +551,12 @@ fi
 # 404 with `tab_not_found` indicates our cached tabId is stale (Extension
 # closed the tab while we weren't looking). Purge cache and retry the call
 # WITHOUT a cached tabId so the backend auto-binds a fresh one.
+#
+# Only for a CACHED tabId. A tab the caller named with --tab-id must be
+# honoured or the call fails: retrying elsewhere would quietly answer about a
+# different tab than the one asked about.
 if [ "$RESPONSE_EXIT" -ne 0 ] \
+   && [ -z "$TAB_ID" ] \
    && [ -n "$STDERR_CAPTURE" ] \
    && printf '%s' "$STDERR_CAPTURE" | grep -q '"status":404' \
    && printf '%s' "$STDERR_CAPTURE" | grep -q 'tab_not_found' \

package/config/skills/agent/remote-browser/execute.test.sh

@@ -318,6 +318,26 @@ assert_contains "first request had stale tabId:100" "$first_body" '"tabId":100'
   || pass "cache purged on 404"
 scenario_teardown
 
+# Scenario 6b: an explicit --tab-id that 404s is NOT retried on another tab
+scenario_init "scenario 6b: explicit --tab-id 404 fails without retry"
+mkdir -p "${RUNTIME_DIR}/agent-6b"
+echo "55" > "${RUNTIME_DIR}/agent-6b/browser-tab-id"
+queue_response '404|{"id":"x","success":false,"error":"Tab 100 no longer exists. Bind a new tab instead of reusing this tabId.","code":"tab_not_found"}'
+queue_response '{"success":true,"data":{"text":"some other tab"}}'
+start_stub
+export CREWLY_SESSION_NAME="agent-6b"
+set +e
+"$SKILL" --action read-text --tab-id 100 > /dev/null 2>&1
+rc=$?
+set -e
+total_reqs=$(wc -l < "$LOG_FILE")
+assert_eq "stub received exactly 1 request" "1" "$(printf '%s' "$total_reqs" | tr -d ' ')"
+[ "$rc" -ne 0 ] && pass "explicit --tab-id 404 exits non-zero" || fail "explicit --tab-id 404 exits non-zero" "rc=$rc"
+[ -f "${RUNTIME_DIR}/agent-6b/browser-tab-id" ] \
+  && pass "cached tab left alone for an explicit --tab-id failure" \
+  || fail "cached tab left alone" "cache was purged"
+scenario_teardown
+
 # Scenario 7: bind-tab with --active sends active:true
 scenario_init "scenario 7: bind-tab --active forwards foreground flag"
 queue_response '{"success":true,"data":{"tabId":7}}'
@@ -468,6 +488,48 @@ total_reqs=$(wc -l < "$LOG_FILE" | tr -d ' ')
 assert_eq "stub received 0 requests" "0" "$total_reqs"
 scenario_teardown
 
+# The goal header is sent as b64:<base64 of UTF-8>; decode it for comparison.
+decode_goal() {
+  case "$1" in
+    b64:*) printf '%s' "${1#b64:}" | base64 --decode 2>/dev/null || printf '%s' "${1#b64:}" | base64 -D ;;
+    *) printf 'NOT-B64:%s' "$1" ;;
+  esac
+}
+
+# Scenario 20: --goal forwards the X-Agent-Goal header (takeover banner)
+scenario_init "scenario 20: --goal forwards X-Agent-Goal"
+queue_response '{"success":true,"data":{}}'
+start_stub
+unset CREWLY_SESSION_NAME
+unset CREWLY_AGENT_GOAL 2>/dev/null || true
+"$SKILL" --action navigate --url https://x.com --goal "Verify DMARC setup" > /dev/null 2>&1 || true
+assert_eq "X-Agent-Goal from --goal" "Verify DMARC setup" "$(decode_goal "$(request_field 0 headers.X-Agent-Goal)")"
+scenario_teardown
+
+# Scenario 21: CREWLY_AGENT_GOAL env auto-forwards; --goal overrides it
+scenario_init "scenario 21: CREWLY_AGENT_GOAL auto-forwards + --goal override"
+queue_response '{"success":true,"data":{}}'
+queue_response '{"success":true,"data":{}}'
+start_stub
+unset CREWLY_SESSION_NAME
+export CREWLY_AGENT_GOAL="Goal from env"
+"$SKILL" --action navigate --url https://x.com > /dev/null 2>&1 || true
+assert_eq "auto X-Agent-Goal from env" "Goal from env" "$(decode_goal "$(request_field 0 headers.X-Agent-Goal)")"
+"$SKILL" --action navigate --url https://y.com --goal "Override goal" > /dev/null 2>&1 || true
+assert_eq "--goal overrides env" "Override goal" "$(decode_goal "$(request_field 1 headers.X-Agent-Goal)")"
+unset CREWLY_AGENT_GOAL
+scenario_teardown
+
+# Scenario 22: a non-ASCII goal survives the header (base64-encoded)
+scenario_init "scenario 22: non-ASCII --goal round-trips"
+queue_response '{"success":true,"data":{}}'
+start_stub
+unset CREWLY_SESSION_NAME
+unset CREWLY_AGENT_GOAL 2>/dev/null || true
+"$SKILL" --action navigate --url https://x.com --goal "核对 DMARC 设置" > /dev/null 2>&1 || true
+assert_eq "non-ASCII goal decoded" "核对 DMARC 设置" "$(decode_goal "$(request_field 0 headers.X-Agent-Goal)")"
+scenario_teardown
+
 # ---------------------------------------------------------------------------
 # Summary
 # ---------------------------------------------------------------------------

package/config/skills/agent/screenshot-compare/execute.sh

@@ -50,7 +50,7 @@ fi
 # ── API key resolution ─────────────────────────────────────────────────────────
 if [ -z "${GEMINI_API_KEY:-}" ]; then
   # Try loading from settings via Crewly API
-  GEMINI_API_KEY=$(curl -sf "http://localhost:8787/api/settings" 2>/dev/null | jq -r '.data.apiKeys.global.gemini // empty' 2>/dev/null || true)
+  GEMINI_API_KEY=$(curl -sf "${CREWLY_API_URL:-http://localhost:${WEB_PORT:-8787}}/api/settings" 2>/dev/null | jq -r '.data.apiKeys.global.gemini // empty' 2>/dev/null || true)
 fi
 
 if [ -z "${GEMINI_API_KEY:-}" ]; then

package/config/skills/agent/transcribe-audio/SKILL.md

@@ -99,7 +99,7 @@ downstream consumers have a stable shape).
   - If the binary or model is missing, the skill falls back to OpenAI (or reports a clear hint when `engine:"local"` is forced).
 - **OpenAI engine** — needs an OpenAI API key. Resolution order:
   1. `OPENAI_API_KEY` environment variable (injected by Crewly secrets).
-  2. Crewly Settings → API Keys (`GET http://localhost:8787/api/settings` → `data.apiKeys.global.openai`).
+  2. Crewly Settings → API Keys (`GET $CREWLY_API_URL/api/settings` → `data.apiKeys.global.openai`).
   No key is ever hard-coded.
 
 ## Notes

package/config/skills/agent/transcribe-audio/execute.sh

@@ -24,7 +24,7 @@ FLOPOST_WHISPER_DIR="${HOME}/.flopost/whisper"
 WHISPER_CACHE_DIR="${HOME}/.cache/whisper-models"
 OPENAI_TRANSCRIBE_URL="https://api.openai.com/v1/audio/transcriptions"
 OPENAI_MODEL="whisper-1"
-SETTINGS_URL="http://localhost:8787/api/settings"
+SETTINGS_URL="${CREWLY_API_URL:-http://localhost:${WEB_PORT:-8787}}/api/settings"
 
 err_json() { printf '{"success":false,"error":%s}\n' "$(printf '%s' "$1" | jq -Rsa .)"; exit 1; }
 

package/config/skills/agent/transcribe-audio/instructions.md

@@ -81,7 +81,7 @@ downstream consumers have a stable shape).
   - If the binary or model is missing, the skill falls back to OpenAI (or reports a clear hint when `engine:"local"` is forced).
 - **OpenAI engine** — needs an OpenAI API key. Resolution order:
   1. `OPENAI_API_KEY` environment variable (injected by Crewly secrets).
-  2. Crewly Settings → API Keys (`GET http://localhost:8787/api/settings` → `data.apiKeys.global.openai`).
+  2. Crewly Settings → API Keys (`GET $CREWLY_API_URL/api/settings` → `data.apiKeys.global.openai`).
   No key is ever hard-coded.
 
 ## Notes

package/config/skills/orchestrator/delegate-task/SKILL.md

@@ -46,7 +46,7 @@ The script auto-resolves `config/skills/...` references to absolute paths so del
 | `--team` / `-g` | `teamId` | No | Team ID for cross-team validation |
 | `--task-type` | `taskType` | No | Task type: `general`, `technical` (default: `general`) |
 | `--force-cross-team` | `forceCrossTeam` | No | Allow cross-team delegation |
-| `--request-id` / `-R` | `requestId` | No | Parent V3 Request ID; tags the resulting WorkItem so `Request.workItemIds[]` is populated by the SLA subscriber (Pipeline-#4 fix) |
+| `--request-id` / `-R` | `requestId` | No | Ticket (Request) this work is for — the id or `TKT-123` from the `[TICKET:TKT-123 <id>]` line of the message you are acting on. Links the WorkItem into `Request.workItemIds[]`. Omit it and the WorkItem is still linked when your current turn has exactly one ticket |
 | `--fallback-minutes` | — | No | Minutes until the ONE §3.0 fallback check fires for this delegation (default `120` ≈ 2× a TL milestone ETA). `0` disables it. Not cancelled on completion — keep it at 2× ETA, never a poll interval |
 
 ## Usage — CLI Flags (preferred)

package/config/skills/orchestrator/get-tasks/SKILL.md

@@ -50,4 +50,10 @@ The whole pool can be several MB.
 
 ## Output
 
-JSON with team task progress including assigned, completed, and blocked tasks.
+`{ success, stats, examined, matched, shown, workItems, hint }`.
+
+- `stats` — the pool's `/task-pool/stats` aggregate (totals by type/status).
+- `examined` — number of pool rows fetched before filtering (the whole pool).
+- `matched` / `shown` — rows that passed the filters, and how many of them are listed (`limit`).
+- `workItems` — the compact items described above.
+- If the item list could not be fetched or was not a list, the skill prints `success:false` with an `error` and exits 1 — an unknown list is never reported as an empty one.

package/config/skills/orchestrator/get-tasks/execute.sh

@@ -23,19 +23,28 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "${SCRIPT_DIR}/../_common/lib.sh"
 
 INPUT=$(read_json_input "${1:-}" 2>/dev/null || echo '{}')
+# No argument and no stdin gives an empty string, not '{}'. Without this
+# default LIMIT came out empty, `--argjson limit ""` failed, and a bare
+# `get-tasks` reported "could not read the task pool".
+[ -n "${INPUT//[[:space:]]/}" ] || INPUT='{}'
 
 PROJECT_PATH=$(printf '%s' "$INPUT" | jq -r '.projectPath // empty')
 STATUS=$(printf '%s' "$INPUT" | jq -r '.status // empty')
 ALL=$(printf '%s' "$INPUT" | jq -r '.all // false')
-LIMIT=$(printf '%s' "$INPUT" | jq -r '.limit // 50')
+LIMIT=$(printf '%s' "$INPUT" | jq -r '(.limit // 50) | tonumber? // 50')
 TARGET=$(printf '%s' "$INPUT" | jq -r '.target // empty')
 
 STATS=$(api_call GET "/task-pool/stats" 2>/dev/null || echo '{"data":{}}')
 
-# The item list goes through a pipe, never argv, however large the pool is,
-# and bypasses the skill output cap — it is filtered down below, and a
-# truncation envelope in its place would read as "no work items".
-CREWLY_SKILL_MAX_OUTPUT_BYTES=0 api_call GET "/task-pool/items" 2>/dev/null \
+# The item list goes through a pipe, never argv, however large the pool is.
+# api_call_full bypasses the skill output cap (or reads the parked body); it
+# fails rather than hand back a truncation envelope that would read as "no
+# work items". An unknown list is reported as success:false and exit 1.
+if ! ITEMS=$(api_call_full GET "/task-pool/items" 2>/dev/null); then
+  ITEMS='{"data":null}'
+fi
+
+OUT=$(printf '%s' "$ITEMS" \
   | jq -c \
       --argjson stats "$STATS" \
       --arg projectPath "$PROJECT_PATH" \
@@ -45,26 +54,40 @@ CREWLY_SKILL_MAX_OUTPUT_BYTES=0 api_call GET "/task-pool/items" 2>/dev/null \
       --argjson limit "$LIMIT" \
       '
       def finished: ["done","verified","cancelled","failed","rejected"];
-      (.data // .workItems // []) as $items
-      | ($items
-          | map(select(
-              ($status == "" or (.status as $s | ($status | split(",") | index($s)) != null))
-              and ($all == "true" or $status != "" or ((.status as $s | finished | index($s)) == null))
-              and ($target == "" or .target == $target)
-            ))
-          | sort_by(.createdAt) | reverse) as $matched
-      | {
-          success: true,
-          projectPath: (if $projectPath == "" then null else $projectPath end),
-          stats: ($stats.data // $stats),
-          matched: ($matched | length),
-          shown: ([$matched | length, $limit] | min),
-          workItems: ($matched[:$limit] | map({
-            id, title, status, target,
-            createdAt,
-            blockedReason: (.blockedReason // null)
-          })),
-          hint: "Compact view: open items only, newest first. Finished ones: {\"all\":true}. One agent: {\"target\":\"<session>\"}."
-        }
-      ' \
-  || echo '{"success":false,"error":"could not read the task pool"}'
+      (.data // .workItems) as $raw
+      | if ($raw | type) != "array" then
+          {
+            success: false,
+            projectPath: (if $projectPath == "" then null else $projectPath end),
+            stats: ($stats.data // $stats),
+            examined: 0,
+            error: "GET /task-pool/items failed or did not return a list; workItems is UNKNOWN, not empty"
+          }
+        else
+          $raw as $items
+          | ($items
+              | map(select(
+                  ($status == "" or (.status as $s | ($status | split(",") | index($s)) != null))
+                  and ($all == "true" or $status != "" or ((.status as $s | finished | index($s)) == null))
+                  and ($target == "" or .target == $target)
+                ))
+              | sort_by(.createdAt) | reverse) as $matched
+          | {
+              success: true,
+              projectPath: (if $projectPath == "" then null else $projectPath end),
+              stats: ($stats.data // $stats),
+              examined: ($items | length),
+              matched: ($matched | length),
+              shown: ([$matched | length, $limit] | min),
+              workItems: ($matched[:$limit] | map({
+                id, title, status, target,
+                createdAt,
+                blockedReason: (.blockedReason // null)
+              })),
+              hint: "Compact view: open items only, newest first. Finished ones: {\"all\":true}. One agent: {\"target\":\"<session>\"}."
+            }
+        end
+      ') || OUT='{"success":false,"examined":0,"error":"could not read the task pool"}'
+printf '%s\n' "$OUT"
+# Exit non-zero when the item list is unknown, so callers cannot mistake it for empty.
+printf '%s' "$OUT" | jq -e '.success' >/dev/null