crewly 1.20.106 → 1.20.107

package/README.md

@@ -22,14 +22,8 @@ Crewly is an open-source multi-agent orchestration platform that coordinates AI
 ## Quick Start
 
 ```bash
-# Initialize Crewly in your project (no global install needed)
-npx crewly init
-
-# Or install globally first
 npm install -g crewly
 crewly init
-
-# Start the platform
 crewly start
 ```
 
@@ -39,10 +33,19 @@ The `init` command walks you through provider selection, installs agent skills,
 2. Assign the team to a **project** (any local code directory)
 3. Watch agents work in real time through live terminal streams
 
-## Prerequisites
+## Requirements
+
+- **Node.js 22 or later** (with npm). Node 20 is end-of-life and its `better-sqlite3` has no prebuilt binary.
+- **No C/C++ toolchain on macOS (x64/arm64) or glibc Linux (x64/arm64).** The native modules install from prebuilt binaries there. You do need `python3`, `make` and `g++` (Xcode Command Line Tools on macOS) in these cases:
+  - Alpine/musl, glibc older than 2.28, or other architectures, where `node-pty` compiles from source
+
+  On Debian/Ubuntu, install the toolchain with `sudo apt-get install -y python3 make g++`. `crewly doctor` tells you whether you need it.
+- **jq** (`brew install jq` on macOS, `sudo apt-get install -y jq` on Debian/Ubuntu). Agent skills use it, and `crewly init` stops if it is missing.
+- **curl**
+- **One AI coding CLI, installed and logged in**: Claude Code (`claude`), Gemini CLI (`gemini`) or Codex (`codex`). OpenCode also works.
+- **A normal user account, not root.** Run Crewly as a normal user, not with `sudo` or as root. Claude Code refuses to start its agents under root.
 
-- **Node.js** v20+ and **npm** v9+
-- **At least one** AI coding CLI installed:
+tmux is not required.
 
 | Runtime | Install | Verify |
 |---------|---------|--------|
@@ -51,7 +54,7 @@ The `init` command walks you through provider selection, installs agent skills,
 | **Codex (OpenAI)** | `npm install -g @openai/codex` | `codex --version` |
 | **OpenCode** | `npm install -g opencode-ai` | `opencode --version` |
 
-**API keys:** Gemini CLI requires `GEMINI_API_KEY`. Codex requires an OpenAI API key. Claude Code authenticates through its own login flow. OpenCode uses whichever provider you connect via `opencode auth login` (or the `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `GEMINI_API_KEY` env vars Crewly already exports to agent sessions).
+**API keys:** Gemini CLI requires `GEMINI_API_KEY`. On a Gemini agent's first run, answer its two terminal prompts: authentication (**Use Gemini API Key**) and folder trust (**Yes**). Codex requires an OpenAI API key. Claude Code: run `claude` once in a terminal, finish its first-run setup (choose a theme) **and** log in before you start a team. A Claude agent cannot get past those screens on its own. OpenCode uses whichever provider you connect via `opencode auth login` (or the `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `GEMINI_API_KEY` env vars Crewly already exports to agent sessions).
 
 ## Architecture
 
@@ -128,7 +131,7 @@ GEMINI_API_KEY=your_key_here       # Required for Gemini CLI runtime
 SLACK_BOT_TOKEN=xoxb-...           # Optional: self-hosted Slack app (see "Slack" below)
 SLACK_APP_TOKEN=xapp-...
 SLACK_SIGNING_SECRET=...
-CREWLY_SLACK_SOURCE=cloud          # Optional: env | cloud (unset = Cloud wins when both exist)
+CREWLY_SLACK_SOURCE=cloud          # Optional: env | cloud (unset = last connected source, else self-hosted, when both exist)
 CREWLY_SLACK_PRIMARY=1             # Optional: this instance handles DMs / unmapped channels
 
 LOG_LEVEL=info                     # debug, info, warn, error
@@ -165,7 +168,14 @@ instance — the Settings toggle, or `CREWLY_SLACK_PRIMARY=1`.
 `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` / `SLACK_SIGNING_SECRET` or the form under
 Settings → Slack → Advanced) still works. `CREWLY_SLACK_SOURCE` picks the source:
 `cloud` uses only the Cloud workspace, `env` uses only local tokens and never
-asks Cloud, unset prefers Cloud when both exist (logged once at boot).
+asks Cloud. Unset, when both exist, a restart keeps the app that was last
+connected (with none recorded, the self-hosted app) and logs a warning — the
+two are different bot users, so switching silently would break every channel of
+the other one. The other app is used only if the chosen one cannot connect.
+Switch explicitly with `PUT /api/slack/source {"source":"env"|"cloud"}`.
+`GET /api/slack/status` reports the connected `source` and turns `degraded`
+(with `degradedReason`) when posts keep failing with `channel_not_found` /
+`not_in_channel`.
 
 ### Securing a server install
 

package/config/constants.ts

@@ -188,6 +188,32 @@ export const PROCESS_EXIT_CODES = {
 	RESTART_REQUESTED: 120,
 } as const;
 
+// ========================= SAFE RESTART CONSTANTS =========================
+
+/**
+ * Safe-restart budget shared by the backend (which drains in-flight agent
+ * turns on SIGTERM/SIGINT) and every supervisor that stops it (CLI `start`
+ * parent, `crewly stop`, `crewly service`, the systemd unit). A supervisor
+ * that escalates to SIGKILL sooner than the drain plus a margin would cut
+ * off the very turns the drain is waiting for.
+ */
+export const SAFE_RESTART_CONSTANTS = {
+	/** Default time the backend waits for agents to finish their current turn (ms) */
+	DRAIN_TIMEOUT_MS: 120_000,
+	/** Env var overriding DRAIN_TIMEOUT_MS; `0` disables the wait */
+	DRAIN_ENV_VAR: 'CREWLY_RESTART_DRAIN_MS',
+	/**
+	 * Time allowed after the drain for the rest of the shutdown (session state
+	 * save, PTY teardown, queue flush) before a supervisor may SIGKILL (ms).
+	 * Must exceed the backend's own post-drain force-exit timer (10s).
+	 */
+	SHUTDOWN_MARGIN_MS: 30_000,
+	/** Two signals closer together than this count as one (tty process-group delivery) */
+	SIGNAL_DEDUP_WINDOW_MS: 1_000,
+	/** REST path an operator (or the CLI) polls before restarting */
+	READINESS_ENDPOINT: '/api/system/restart-readiness',
+} as const;
+
 // ========================= WEB SERVER CONSTANTS =========================
 
 /**
@@ -220,6 +246,10 @@ export const WEB_CONSTANTS = {
 		ORCHESTRATOR: '/api/orchestrator',
 		/** Terminal operations endpoints */
 		TERMINAL: '/api/terminal',
+		/** Live agent sessions (PTY): name, pid, cwd */
+		SESSIONS: '/api/sessions',
+		/** Live terminal sessions including in-process (no PTY) agents */
+		TERMINAL_SESSIONS: '/api/terminal/sessions',
 		/** Task management endpoints */
 		TASKS: '/api/tasks',
 		/** Factory SSE endpoint */
@@ -295,6 +325,19 @@ export const API_SECURITY_CONSTANTS = {
 	},
 	/** Actor recorded on approvals performed with the owner token */
 	OWNER_ACTOR: 'owner',
+	/**
+	 * Header the dashboard sets on owner-initiated actions (e.g. the per-member
+	 * Start button). Paired with the ABSENCE of `X-Agent-Session`, it marks a
+	 * request as a human action rather than an agent skill or an internal
+	 * server-to-server call, which send neither (issue #775).
+	 */
+	CALLER_HEADER: 'x-crewly-caller',
+	/** Value of {@link CALLER_HEADER} sent by the dashboard. */
+	DASHBOARD_CALLER: 'dashboard',
+	/** Header skills send to identify the calling agent session. */
+	AGENT_SESSION_HEADER: 'x-agent-session',
+	/** Legacy alias of {@link AGENT_SESSION_HEADER} still accepted by the backend. */
+	AGENT_SESSION_HEADER_LEGACY: 'x-crewly-agent-session',
 	/** Hint appended to 401 responses */
 	UNAUTHORIZED_HINT:
 		'Non-loopback callers must send the API token: `Authorization: Bearer <token>`, `X-Crewly-Token: <token>` or a `crewly_token` cookie. Run `crewly token` on the server to print it.',

package/config/index.ts

@@ -36,6 +36,7 @@ import {
   MARKETPLACE_CONSTANTS,
   TEMPLATE_MARKETPLACE_CONSTANTS,
   PROCESS_EXIT_CODES,
+  SAFE_RESTART_CONSTANTS,
   SERVER_CONSTANTS,
   API_SECURITY_CONSTANTS,
   EVENT_DEBOUNCE_MS,
@@ -64,6 +65,7 @@ export {
   MARKETPLACE_CONSTANTS,
   TEMPLATE_MARKETPLACE_CONSTANTS,
   PROCESS_EXIT_CODES,
+  SAFE_RESTART_CONSTANTS,
   SERVER_CONSTANTS,
   API_SECURITY_CONSTANTS,
   EVENT_DEBOUNCE_MS,

package/config/skills/_common/lib.sh

@@ -4,8 +4,10 @@
 # Provides common utilities for all bash skills (agent and orchestrator).
 # =============================================================================
 
-# Base URL for the Crewly backend API
-CREWLY_API_URL="${CREWLY_API_URL:-http://localhost:8787}"
+# Base URL for the Crewly backend API. The backend sets CREWLY_API_URL on
+# every agent to the port it actually runs on (#777); without it, fall back to
+# the WEB_PORT the server was started with, then the default port.
+CREWLY_API_URL="${CREWLY_API_URL:-http://localhost:${WEB_PORT:-8787}}"
 
 # -----------------------------------------------------------------------------
 # Skill output cap (context-cost control)
@@ -249,6 +251,14 @@ api_call() {
   if [ -n "${CREWLY_GOOGLE_ACCOUNT:-}" ]; then
     args+=(-H "X-Google-Account: $CREWLY_GOOGLE_ACCOUNT")
   fi
+  # What the agent is trying to accomplish, shown in the owner's Chrome
+  # takeover banner and the live browser view. Callers export
+  # CREWLY_AGENT_GOAL, or pass remote-browser's --goal. Base64 for the same
+  # reason as the authorization above: goals are often not ASCII, and a raw
+  # newline would end the header.
+  if [ -n "${CREWLY_AGENT_GOAL:-}" ]; then
+    args+=(-H "X-Agent-Goal: b64:$(printf '%s' "$CREWLY_AGENT_GOAL" | base64 | tr -d '\n')")
+  fi
   [ -n "$body" ] && args+=(-d "$body")
 
   local response
@@ -273,6 +283,49 @@ api_call() {
   fi
 }
 
+# -----------------------------------------------------------------------------
+# api_call_full METHOD endpoint [json_body]
+#
+# api_call for skills that reduce the response THEMSELVES — filter a list to
+# the caller's team, count rows, pick one id — and therefore must see all of
+# it. The output cap in api_call replaces any body over
+# CREWLY_SKILL_MAX_OUTPUT_BYTES with a {"truncated":true,...} envelope, and a
+# skill that runs `.data // []` over that envelope reports an EMPTY list with
+# success:true (2026-09-21: list-my-followups and cancel-followup saw 0 of
+# 335 triggers because GET /triggers was 233 KB). This helper:
+#   1. bypasses the cap for this one call;
+#   2. if an envelope still comes back (api_call swapped for a test double,
+#      or a future cap path), reads the parked file it points at;
+#   3. otherwise prints an error object on stderr and returns 1 — never a
+#      body the caller could mistake for "no rows".
+#
+# The full body must not reach the LLM: callers reduce it before printing.
+# Do not use this from a skill that echoes the response verbatim — that is
+# exactly what the cap exists to prevent.
+#
+# Usage:
+#   if ! RESP=$(api_call_full GET "/triggers"); then error_exit "..."; fi
+# -----------------------------------------------------------------------------
+api_call_full() {
+  local body
+  if ! body=$(CREWLY_SKILL_FULL_OUTPUT=1 api_call "$@"); then
+    return 1
+  fi
+  if printf '%s' "$body" | jq -e 'if type == "object" then .truncated == true else false end' >/dev/null 2>&1; then
+    local file
+    file=$(printf '%s' "$body" | jq -r '.file // empty')
+    if [ -n "$file" ] && [ -r "$file" ]; then
+      cat "$file"
+      echo
+      return 0
+    fi
+    jq -nc --arg m "$1" --arg e "$2" --arg f "$file" \
+      '{error: true, truncated: true, details: ("api_call_full \($m) \($e): the response was replaced by a truncated envelope and its parked file (" + $f + ") is unreadable; refusing to return a body that would parse as an empty list")}' >&2
+    return 1
+  fi
+  printf '%s\n' "$body"
+}
+
 # -----------------------------------------------------------------------------
 # error_exit message
 # Prints a JSON error to stderr and exits with code 1.

package/config/skills/_common/lib.test.sh

@@ -2,7 +2,8 @@
 # =============================================================================
 # Tests for lib.sh — shared skills library
 # Covers: --file preprocessor, read_json_input, require_param, error_exit,
-#         api_call output cap (CREWLY_SKILL_MAX_OUTPUT_BYTES)
+#         api_call output cap (CREWLY_SKILL_MAX_OUTPUT_BYTES),
+#         CREWLY_API_URL default (#777)
 # =============================================================================
 set -euo pipefail
 
@@ -252,12 +253,68 @@ assert_eq "api_call: prune runs even when the body is small" '{"ok":true}' "$RES
 assert_eq "api_call: stale parked output is deleted" "missing" "$([ -f "$CAP_DIR/old-skill-stale.json" ] && echo present || echo missing)"
 assert_eq "api_call: fresh parked output is kept" "present" "$([ -f "$CAP_DIR/fresh-skill-recent.json" ] && echo present || echo missing)"
 
+# =============================================================================
+# api_call_full — callers that reduce the body themselves must see all of it
+# (2026-09-21: list-my-followups saw 0 of 335 triggers via the envelope).
+# =============================================================================
+mkdir -p "$TEMP_DIR/skills/fake-full"
+cat > "$TEMP_DIR/skills/fake-full/execute.sh" << 'SKILL_EOF'
+#!/bin/bash
+set -euo pipefail
+source "$LIB_PATH"
+curl() {
+  printf '%s\n%s' "$MOCK_BODY" "${MOCK_CODE:-200}"
+}
+# MOCK_ENVELOPE, when set, swaps api_call for a double that always hands back a
+# truncated envelope pointing at that path — what an api_call that ignored the
+# bypass (or a future cap path) would do.
+if [ -n "${MOCK_ENVELOPE:-}" ]; then
+  api_call() { printf '{"truncated":true,"bytes":9,"file":"%s","head":"","hint":"x"}' "$MOCK_ENVELOPE"; }
+fi
+api_call_full GET "/anything"
+SKILL_EOF
+chmod +x "$TEMP_DIR/skills/fake-full/execute.sh"
+
+# ---- Test 24: an oversized body comes back whole, and nothing is parked ----
+export MOCK_BODY="$BIG"; unset MOCK_ENVELOPE MOCK_CODE
+RESULT=$(CREWLY_SKILL_MAX_OUTPUT_BYTES=1000 bash "$TEMP_DIR/skills/fake-full/execute.sh")
+assert_eq "api_call_full: oversized body returned whole" "$BIG" "$RESULT"
+assert_eq "api_call_full: nothing parked on disk" "0" "$(find "$CAP_DIR" -name 'fake-full-*' 2>/dev/null | wc -l | tr -d ' ')"
+
+# ---- Test 25: an envelope that still arrives is resolved from its parked file ----
+printf '%s' '{"data":[1,2,3]}' > "$TEMP_DIR/parked.json"
+RESULT=$(MOCK_ENVELOPE="$TEMP_DIR/parked.json" bash "$TEMP_DIR/skills/fake-full/execute.sh")
+assert_eq "api_call_full: envelope resolved from its parked file" '{"data":[1,2,3]}' "$RESULT"
+
+# ---- Test 26: an envelope whose parked file is unreadable fails loudly ----
+FULL_CODE=0
+RESULT=$(MOCK_ENVELOPE="$TEMP_DIR/missing.json" bash "$TEMP_DIR/skills/fake-full/execute.sh" 2>&1) || FULL_CODE=$?
+assert_eq "api_call_full: unreadable parked file -> exit 1" "1" "$FULL_CODE"
+assert_contains "api_call_full: the error names the truncation" '"truncated":true' "$RESULT"
+assert_eq "api_call_full: no body on stdout for the caller to mistake for empty" "" \
+  "$(MOCK_ENVELOPE="$TEMP_DIR/missing.json" bash "$TEMP_DIR/skills/fake-full/execute.sh" 2>/dev/null || true)"
+
+# ---- Test 27: HTTP errors still propagate as a non-zero return ----
+export MOCK_BODY='{"error":"nope"}' MOCK_CODE=500; unset MOCK_ENVELOPE
+FULL_CODE=0
+bash "$TEMP_DIR/skills/fake-full/execute.sh" >/dev/null 2>&1 || FULL_CODE=$?
+assert_eq "api_call_full: non-2xx returns 1" "1" "$FULL_CODE"
+unset MOCK_BODY MOCK_CODE
+
 # ---- Test 23: error responses are untouched by the cap ----
 export MOCK_BODY='{"error":"nope"}' MOCK_CODE=500
 RESULT=$(CREWLY_SKILL_MAX_OUTPUT_BYTES=5 bash "$TEMP_DIR/skills/fake-skill/execute.sh" 2>&1 || true)
 assert_contains "api_call: non-2xx still reports the error object" '"status":500' "$RESULT"
 unset MOCK_BODY MOCK_CODE CREWLY_HOME
 
+# ---- Test 24: CREWLY_API_URL default follows the instance's port (#777) ----
+RESULT=$(env -u CREWLY_API_URL WEB_PORT=8797 bash -c 'source "$1"; echo "$CREWLY_API_URL"' _ "$SCRIPT_DIR/lib.sh")
+assert_eq "lib.sh: default API URL uses WEB_PORT" "http://localhost:8797" "$RESULT"
+RESULT=$(env -u CREWLY_API_URL -u WEB_PORT bash -c 'source "$1"; echo "$CREWLY_API_URL"' _ "$SCRIPT_DIR/lib.sh")
+assert_eq "lib.sh: default API URL without WEB_PORT is 8787" "http://localhost:8787" "$RESULT"
+RESULT=$(CREWLY_API_URL=http://localhost:9001 WEB_PORT=8797 bash -c 'source "$1"; echo "$CREWLY_API_URL"' _ "$SCRIPT_DIR/lib.sh")
+assert_eq "lib.sh: CREWLY_API_URL set by the backend wins" "http://localhost:9001" "$RESULT"
+
 echo ""
 echo "=== Results: $PASS/$TOTAL passed, $FAIL failed ==="
 

package/config/skills/_common/task-pool-body-shape.test.sh

@@ -465,6 +465,66 @@ else
   PASS=$((PASS + 1)); echo "  ✓ no /block POST emitted"
 fi
 
+# ---------------------------------------------------------------------------
+# Scenario 12 — ticket loop: every WorkItem-creating skill forwards
+# --request-id as the top-level `requestId` (specs/ticket-loop.md §3), and
+# omits it entirely when not given.
+# ---------------------------------------------------------------------------
+echo ""
+echo "--- Scenario 12: --request-id reaches /add as requestId ---"
+: > "$LOG"
+bash "${REPO_ROOT}/config/skills/agent/core/create-task/execute.sh" \
+  --project-path /tmp/proj-foo --task "Ticketed task" --request-id TKT-042 >/dev/null 2>&1 || true
+BODY=$(capture "/api/task-pool/add")
+if [ -z "$BODY" ]; then
+  FAIL=$((FAIL + 1)); echo "  ✗ no /task-pool/add POST captured for create-task --request-id"
+else
+  assert_add_contract "create-task(ticket)" "$BODY"
+  assert_jq "create-task: --request-id forwarded as requestId" '.requestId == "TKT-042"' "$BODY"
+fi
+
+: > "$LOG"
+bash "${REPO_ROOT}/config/skills/agent/core/create-task/execute.sh" \
+  --project-path /tmp/proj-foo --task "Unticketed task" >/dev/null 2>&1 || true
+BODY=$(capture "/api/task-pool/add")
+if [ -n "$BODY" ]; then
+  assert_jq "create-task: omits requestId when not given" 'has("requestId") == false' "$BODY"
+fi
+
+: > "$LOG"
+bash "${REPO_ROOT}/config/skills/team-leader/delegate-task/execute.sh" \
+  --to quinn-target --task "Ticketed delegation" --request-id req-ticket-7 >/dev/null 2>&1 || true
+BODY=$(capture "/api/task-pool/add")
+if [ -z "$BODY" ]; then
+  FAIL=$((FAIL + 1)); echo "  ✗ no /task-pool/add POST captured for tl-delegate-task --request-id"
+else
+  assert_add_contract "tl-delegate-task(ticket)" "$BODY"
+  assert_jq "tl-delegate-task: --request-id forwarded as requestId" '.requestId == "req-ticket-7"' "$BODY"
+fi
+
+: > "$LOG"
+bash "${REPO_ROOT}/config/skills/team-leader/decompose-goal/execute.sh" \
+  '{"objective":"Ticketed objective","projectPath":"/tmp/proj-foo","tasks":[{"title":"Sub","description":"d"}]}' \
+  --request-id req-ticket-9 >/dev/null 2>&1 || true
+BODY=$(capture "/api/task-pool/add")
+if [ -z "$BODY" ]; then
+  FAIL=$((FAIL + 1)); echo "  ✗ no /task-pool/add POST captured for decompose-goal --request-id"
+else
+  assert_add_contract "decompose-goal(ticket)" "$BODY"
+  assert_jq "decompose-goal: --request-id forwarded as requestId" '.requestId == "req-ticket-9"' "$BODY"
+fi
+
+: > "$LOG"
+bash "${REPO_ROOT}/config/skills/team-leader/decompose-goal/execute.sh" \
+  '{"objective":"JSON ticket","projectPath":"/tmp/proj-foo","requestId":"req-json-3","tasks":[{"title":"Sub","description":"d"}]}' \
+  >/dev/null 2>&1 || true
+BODY=$(capture "/api/task-pool/add")
+if [ -n "$BODY" ]; then
+  assert_jq "decompose-goal: JSON requestId forwarded" '.requestId == "req-json-3"' "$BODY"
+else
+  FAIL=$((FAIL + 1)); echo "  ✗ no /task-pool/add POST captured for decompose-goal JSON requestId"
+fi
+
 echo ""
 echo "=== Results: ${PASS} passed, ${FAIL} failed ==="
 [ "$FAIL" -eq 0 ] || exit 1

package/config/skills/agent/core/cancel-followup/execute.sh

@@ -73,7 +73,22 @@ if [ -z "$TRIGGER_ID" ]; then
   TEAM_ID=$(resolve_team_id || true)
   [ -z "$TEAM_ID" ] && { echo '{"error":"Cannot resolve owning team — cannot scope name lookup"}' >&2; exit 1; }
 
-  LIST_RESP=$(api_call GET "/triggers" "" 2>/dev/null || echo '{"data":[]}')
+  # The whole trigger table is needed to resolve a name (335 rows / 233 KB on
+  # 2026-09-21 — over the skill-output cap). Plain api_call would return a
+  # {"truncated":true} envelope and every name lookup would miss. A truncated
+  # or non-array body must fail loudly, or "not found" is reported for a
+  # trigger that exists.
+  if ! LIST_RESP=$(api_call_full GET "/triggers" ""); then
+    jq -n --arg n "$TRIGGER_NAME" \
+      '{success:false, name:$n, error:"GET /triggers failed or came back as a truncated envelope; cannot resolve the trigger by name (it may well exist)"}'
+    exit 1
+  fi
+  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 n "$TRIGGER_NAME" --arg why "$EXAMINED" \
+      '{success:false, name:$n, error:("GET /triggers returned a body whose .data is " + $why + "; cannot resolve the trigger by name")}'
+    exit 1
+  fi
   TRIGGER_ID=$(printf '%s' "$LIST_RESP" | jq -r \
     --arg team "$TEAM_ID" \
     --arg name "$TRIGGER_NAME" \
@@ -82,8 +97,8 @@ if [ -z "$TRIGGER_ID" ]; then
        | .id) // empty' | head -1)
 
   if [ -z "$TRIGGER_ID" ]; then
-    echo "$(jq -n --arg n "$TRIGGER_NAME" --arg team "$TEAM_ID" \
-      '{success:false, error:"No active trigger found with name", name:$n, teamId:$team}')"
+    jq -n --arg n "$TRIGGER_NAME" --arg team "$TEAM_ID" --arg e "$EXAMINED" \
+      '{success:false, error:"No active trigger found with name", name:$n, teamId:$team, examined:($e|tonumber)}'
     exit 0
   fi
 fi

package/config/skills/agent/core/cancel-followup/execute.test.sh

@@ -37,6 +37,79 @@ OUTPUT=$(bash "$SCRIPT_DIR/execute.sh" --help 2>&1) || true
 assert_contains "Help lists --id" -- "--id" "$OUTPUT"
 assert_contains "Help lists --name" -- "--name" "$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 "--- Name lookup: a truncated list must not read as 'not found' ---"
+
+# Real skill + real lib.sh, with api_call swapped for a double: GET /triggers
+# returns $MOCK_RESPONSE, POST .../cancel is logged and acknowledged.
+REAL_LIB="$(cd "$SCRIPT_DIR/../../../_common" && pwd)/lib.sh"
+TMP=$(mktemp -d); trap 'rm -rf "$TMP"' EXIT
+mkdir -p "$TMP/skills/agent/core/cancel-followup" "$TMP/skills/agent/_common"
+cp "$SCRIPT_DIR/execute.sh" "$TMP/skills/agent/core/cancel-followup/execute.sh"
+cat > "$TMP/skills/agent/_common/lib.sh" <<'STUB_EOF'
+source "$REAL_LIB"
+resolve_team_id() { echo "team-a"; }
+api_call() {
+  echo "$1 $2" >> "$API_LOG"
+  case "$1 $2" in
+    "GET /triggers") printf '%s' "$MOCK_RESPONSE" ;;
+    POST\ /triggers/*/cancel) printf '{"success":true,"data":{"status":"cancelled"}}' ;;
+    *) printf '{"success":true}' ;;
+  esac
+}
+STUB_EOF
+
+run() {
+  local mock="$1"; shift
+  CODE=0
+  : > "$TMP/api.log"
+  OUTPUT=$(env -u CREWLY_SESSION_NAME REAL_LIB="$REAL_LIB" API_LOG="$TMP/api.log" MOCK_RESPONSE="$mock" \
+    bash "$TMP/skills/agent/core/cancel-followup/execute.sh" "$@" 2>/dev/null) || CODE=$?
+}
+
+ENVELOPE='{"truncated":true,"bytes":233481,"file":"'"$TMP"'/nonexistent.json","head":"{\"success\":true,\"data\":[{","hint":"pass --full or read the file"}'
+ROWS='{"success":true,"data":[
+  {"id":"t-1","teamId":"team-a","name":"followup:abc","status":"active"},
+  {"id":"t-2","teamId":"team-b","name":"followup:zzz","status":"active"},
+  {"id":"t-3","teamId":"team-a","name":"followup:old","status":"cancelled"}]}'
+
+run "$ENVELOPE" --name followup:abc
+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, not 'not found'" 'truncated envelope' "$OUTPUT"
+assert_eq "Envelope -> nothing cancelled" "" "$(grep POST "$TMP/api.log" || true)"
+
+run "$ROWS" --name followup:abc
+assert_eq "Match -> exit 0" "0" "$CODE"
+assert_eq "Match -> cancels the team's trigger by id" "POST /triggers/t-1/cancel" "$(grep POST "$TMP/api.log")"
+assert_eq "Match -> success:true" "true" "$(printf '%s' "$OUTPUT" | jq -r '.success')"
+
+run "$ROWS" --name followup:zzz
+assert_eq "Other team's name -> not found (team-scoped), exit 0" "0" "$CODE"
+assert_contains "Other team's name -> not-found message" 'No active trigger found' "$OUTPUT"
+assert_eq "Not found -> reports how many rows were examined" "3" "$(printf '%s' "$OUTPUT" | jq -r '.examined')"
+assert_eq "Not found -> nothing cancelled" "" "$(grep POST "$TMP/api.log" || true)"
+
+run "$ROWS" --name followup:old
+assert_contains "Cancelled trigger -> not found (only active are cancellable)" 'No active trigger found' "$OUTPUT"
+
+run '{"success":true,"data":"nope"}' --name followup:abc
+assert_eq "Non-array .data -> non-zero exit" "1" "$CODE"
+assert_contains "Non-array .data -> error says why" 'not-an-array' "$OUTPUT"
+
 echo ""
 echo "=== Results: ${PASS} passed, ${FAIL} failed ==="
 [ $FAIL -eq 0 ]

package/config/skills/agent/core/complete-task/execute.sh

@@ -101,7 +101,7 @@ fi
 # WORK_ITEM_ID was read from the input up top alongside the other params,
 # so the identifier is known before any of the legacy path handling runs.
 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/create-intent-tasks/execute.sh

@@ -67,7 +67,7 @@ BODY=$(jq -n \
 # ---------------------------------------------------------------------------
 # 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/core/create-task/SKILL.md

@@ -52,6 +52,7 @@ Create a new task via the `/api/task-management/create` endpoint. This allows te
 | `--owner` | `owner` | No | Responsible role: `orchestrator`, `team_lead`, `agent` (default), `system`. A role, not a session name — use `--session` for the session |
 | `--description` / `-d` | `description` | No | Short summary of the task |
 | `--brief` | `briefMarkdown` | No | Long-form brief in markdown. Inline text, or `@/path/to/file.md`. Max 16384 bytes |
+| `--request-id` / `-R` | `requestId` | No | Ticket this work is for: the id (or `TKT-123`) from the `[TICKET:TKT-123 <id>]` line of the message you are acting on. Omit it and the task is still linked when your current turn has exactly one ticket |
 
 ### Always attach a brief
 

package/config/skills/agent/core/create-task/execute.sh

@@ -30,6 +30,8 @@ Options:
   --description  | -d   Short summary of the task (optional)
   --brief               Long-form brief in markdown: inline text, or @/path/to/file.md
                         Should carry Goal + Expected Outcome + Eval Criteria. Max 16384 bytes.
+  --request-id   | -R   Ticket this task is for: the id (or TKT-123) from the
+                        [TICKET:TKT-123 <id>] line of the message you are working on
   --json         | -j   Raw JSON payload (same as legacy)
   --help         | -h   Show this help
 EOF_USAGE
@@ -45,6 +47,7 @@ OUTPUT_SCHEMA=""
 OWNER=""
 DESCRIPTION=""
 BRIEF=""
+REQUEST_ID=""
 
 # Detect legacy JSON argument
 if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then
@@ -90,6 +93,10 @@ while [[ $# -gt 0 ]]; do
       BRIEF="$2"
       shift 2
       ;;
+    --request-id|-R)
+      REQUEST_ID="$2"
+      shift 2
+      ;;
     --json|-j)
       INPUT_JSON="$2"
       shift 2
@@ -133,6 +140,7 @@ if [ -n "$INPUT_JSON" ]; then
   [ -z "$OWNER" ] && OWNER=$(printf '%s' "$INPUT" | jq -r '.owner // empty')
   [ -z "$DESCRIPTION" ] && DESCRIPTION=$(printf '%s' "$INPUT" | jq -r '.description // empty')
   [ -z "$BRIEF" ] && BRIEF=$(printf '%s' "$INPUT" | jq -r '.briefMarkdown // .brief // empty')
+  [ -z "$REQUEST_ID" ] && REQUEST_ID=$(printf '%s' "$INPUT" | jq -r '.requestId // empty')
 fi
 
 # Apply defaults
@@ -203,6 +211,7 @@ WORK_ITEM=$(jq -n \
   --arg priority "$PRIORITY" \
   --arg description "$DESCRIPTION" \
   --arg briefMarkdown "$BRIEF" \
+  --arg requestId "$REQUEST_ID" \
   '{
     title: $title,
     type: "delegate",
@@ -212,6 +221,7 @@ WORK_ITEM=$(jq -n \
   }
   + (if $description != "" then {description: $description} else {} end)
   + (if $briefMarkdown != "" then {briefMarkdown: $briefMarkdown} else {} end)
+  + (if $requestId != "" then {requestId: $requestId} else {} end)
   | with_entries(select(.value != null))')
 
 if [ -n "$OUTPUT_SCHEMA" ] && [ "$OUTPUT_SCHEMA" != "" ]; then

package/config/skills/agent/core/decompose-intent/execute.sh

@@ -82,7 +82,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/core/handoff-task/execute.sh

@@ -56,7 +56,7 @@ TIMESTAMP="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
 # --- Step 0: Resolve target WorkItem if not supplied ---
 # Resolve order: explicit workItemId > the agent's currently-running claim.
 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/list-my-followups/SKILL.md

@@ -37,7 +37,7 @@ bash execute.sh --name-prefix watch:
 
 ## What you see
 
-Returns `{ success, count, data: [Trigger, ...] }`. Each `Trigger` includes:
+Returns `{ success, examined, count, data: [Trigger, ...] }` — `examined` is the number of triggers fetched before the team filter, `count` the number left after all filters. A truncated or malformed backend response exits 1 with `success:false` and an `error`; it is never reported as `count: 0`. Each `Trigger` includes:
 - `id`, `name`, `status`
 - `config` (cron expression / fireAt / event type)
 - `action` (what it creates when it fires)