crewly 1.6.4 → 1.7.0

package/config/skills/_common/complete-body-shape.test.sh

@@ -0,0 +1,249 @@
+#!/bin/bash
+# =============================================================================
+# Hygiene #4 (2026-05-09) — wire-shape smoke test for /api/task-pool/complete
+#
+# Brief allows: "a smoke test that verifies the JSON body shape against the
+# controller's accepted schema" (.crewly/specs equivalent). This is that test.
+#
+# Covers the 3 skill callsites that emit POSTs to /task-pool/complete:
+#   1. config/skills/agent/core/report-status/execute.sh        (status=done branch)
+#   2. config/skills/agent/core/complete-task/execute.sh        (always)
+#   3. config/skills/orchestrator/complete-task/execute.sh      (always)
+#
+# Strategy: spin up a Python HTTP stub that records every POST body; point
+# each skill at it via CREWLY_API_URL; assert the captured body matches the
+# canonical `{agentId, result:{summary}, ...}` shape required by
+# task-pool.controller.ts `completeItem`.
+#
+# Pattern mirrors the existing `config/skills/agent/remote-browser/
+# execute.test.sh` Python-stub harness — same JSONL request log, same
+# subshell-pid trick.
+#
+# Test runner:
+#   bash config/skills/_common/complete-body-shape.test.sh
+#   echo $?    # 0 on pass, 1 on fail
+# =============================================================================
+set -eo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../../.." && pwd)"
+PASS=0
+FAIL=0
+
+assert_eq_json() {
+  local test_name="$1" expected="$2" actual="$3"
+  # Normalize both via jq -S so key order does not matter.
+  local norm_expected norm_actual
+  norm_expected=$(printf '%s' "$expected" | jq -S '.' 2>/dev/null || echo "INVALID_JSON_EXPECTED")
+  norm_actual=$(printf '%s' "$actual" | jq -S '.' 2>/dev/null || echo "INVALID_JSON_ACTUAL")
+  if [ "$norm_expected" = "$norm_actual" ]; then
+    PASS=$((PASS + 1))
+    echo "  ✓ ${test_name}"
+  else
+    FAIL=$((FAIL + 1))
+    echo "  ✗ ${test_name}"
+    echo "    expected: ${norm_expected}"
+    echo "    actual:   ${norm_actual}"
+  fi
+}
+
+assert_jq() {
+  local test_name="$1" jq_filter="$2" body="$3"
+  local result
+  result=$(printf '%s' "$body" | jq -er "$jq_filter" 2>/dev/null || true)
+  if [ -n "$result" ] && [ "$result" != "null" ] && [ "$result" != "false" ]; then
+    PASS=$((PASS + 1))
+    echo "  ✓ ${test_name}"
+  else
+    FAIL=$((FAIL + 1))
+    echo "  ✗ ${test_name}"
+    echo "    filter: ${jq_filter}"
+    echo "    body:   ${body}"
+  fi
+}
+
+start_stub() {
+  local port="$1" log_file="$2"
+  PORT=$port LOG_FILE=$log_file \
+    python3 -c '
+import http.server, json, os, sys
+LOG = os.environ["LOG_FILE"]
+PORT = int(os.environ["PORT"])
+
+class Handler(http.server.BaseHTTPRequestHandler):
+    def log_message(self, *a, **kw): pass  # quiet
+    def _record(self, body_bytes):
+        with open(LOG, "a") as f:
+            f.write(json.dumps({
+                "method": self.command,
+                "path": self.path,
+                "body": body_bytes.decode("utf-8") if body_bytes else "",
+            }) + "\n")
+    def _ok(self):
+        self.send_response(200)
+        self.send_header("Content-Type", "application/json")
+        self.end_headers()
+        self.wfile.write(b"{\"success\":true}")
+    def do_POST(self):
+        ln = int(self.headers.get("Content-Length") or 0)
+        body = self.rfile.read(ln) if ln else b""
+        self._record(body)
+        # Specific handling for the resolve-running-WI fallback
+        if self.path.startswith("/api/task-pool/items"):
+            self.send_response(200)
+            self.send_header("Content-Type","application/json")
+            self.end_headers()
+            # Top-level workItems shape — matches the jq fallback chain
+            # in the skills (`.workItems[0].id // .data[0].id // empty`).
+            self.wfile.write(b"{\"workItems\":[{\"id\":\"wi-stub-1\"}]}")
+            return
+        self._ok()
+    def do_GET(self):
+        self._record(b"")
+        if self.path.startswith("/api/task-pool/items"):
+            self.send_response(200)
+            self.send_header("Content-Type","application/json")
+            self.end_headers()
+            # Top-level workItems shape — matches the jq fallback chain
+            # in the skills (`.workItems[0].id // .data[0].id // empty`).
+            self.wfile.write(b"{\"workItems\":[{\"id\":\"wi-stub-1\"}]}")
+            return
+        self._ok()
+
+httpd = http.server.HTTPServer(("127.0.0.1", PORT), Handler)
+httpd.serve_forever()
+' >/dev/null 2>&1 &
+  echo $!
+}
+
+# ---------------------------------------------------------------------------
+# Per-skill scenario harness
+# ---------------------------------------------------------------------------
+PORT=39184
+TMPROOT=$(mktemp -d -t crewly-hygiene4-XXXXXX)
+LOG="${TMPROOT}/requests.jsonl"
+: > "$LOG"
+
+STUB_PID=$(start_stub "$PORT" "$LOG")
+trap "kill $STUB_PID 2>/dev/null || true; rm -rf $TMPROOT" EXIT
+
+# Wait briefly for the HTTP server to bind.
+for _ in 1 2 3 4 5 6 7 8 9 10; do
+  if curl -s "http://127.0.0.1:${PORT}/healthz" >/dev/null 2>&1; then break; fi
+  sleep 0.1
+done
+
+export CREWLY_API_URL="http://127.0.0.1:${PORT}"
+
+echo "=== Hygiene #4 — /task-pool/complete body-shape smoke ==="
+
+# ---------------------------------------------------------------------------
+# Scenario 1 — agent/core/report-status (status=done branch)
+# ---------------------------------------------------------------------------
+echo ""
+echo "--- Scenario 1: agent/core/report-status status=done ---"
+: > "$LOG"
+bash "${REPO_ROOT}/config/skills/agent/core/report-status/execute.sh" \
+  --session quinn-test --status done \
+  --summary "Report-status smoke summary" \
+  --project /tmp/proj-foo >/dev/null 2>&1 || true
+
+# Expect at least one POST to /api/task-pool/complete/ — find it.
+COMPLETE_LINE=$(grep -F '"path": "/api/task-pool/complete/' "$LOG" | head -1 || true)
+if [ -z "$COMPLETE_LINE" ]; then
+  FAIL=$((FAIL + 1))
+  echo "  ✗ no /task-pool/complete POST captured"
+else
+  COMPLETE_BODY=$(printf '%s' "$COMPLETE_LINE" | jq -r '.body')
+  assert_jq "agentId is the session name" '.agentId == "quinn-test"' "$COMPLETE_BODY"
+  assert_jq "result.summary is non-empty" '.result.summary | length > 0' "$COMPLETE_BODY"
+  assert_jq "result.summary matches input" '.result.summary == "Report-status smoke summary"' "$COMPLETE_BODY"
+  assert_jq "no top-level summary leak (strict shape)" '.summary == null' "$COMPLETE_BODY"
+fi
+
+# ---------------------------------------------------------------------------
+# Scenario 2 — agent/core/complete-task
+# ---------------------------------------------------------------------------
+echo ""
+echo "--- Scenario 2: agent/core/complete-task ---"
+: > "$LOG"
+TASK_DIR=$(mktemp -d -t crewly-hygiene4-task-XXXXXX)
+TASK_PATH="${TASK_DIR}/task.md"
+echo "# task" > "$TASK_PATH"
+
+bash "${REPO_ROOT}/config/skills/agent/core/complete-task/execute.sh" \
+  '{"absoluteTaskPath":"'"$TASK_PATH"'","sessionName":"quinn-ct","summary":"Complete-task smoke summary","workItemId":"wi-stub-1","output":{"prNumber":42,"callsites":5}}' \
+  >/dev/null 2>&1 || true
+
+COMPLETE_LINE=$(grep -F '"path": "/api/task-pool/complete/' "$LOG" | head -1 || true)
+if [ -z "$COMPLETE_LINE" ]; then
+  FAIL=$((FAIL + 1))
+  echo "  ✗ no /task-pool/complete POST captured"
+else
+  COMPLETE_BODY=$(printf '%s' "$COMPLETE_LINE" | jq -r '.body')
+  assert_jq "agentId is the session name" '.agentId == "quinn-ct"' "$COMPLETE_BODY"
+  assert_jq "result.summary matches" '.result.summary == "Complete-task smoke summary"' "$COMPLETE_BODY"
+  assert_jq "result.prNumber merged into result (was top-level result before)" '.result.prNumber == 42' "$COMPLETE_BODY"
+  assert_jq "result.callsites merged into result" '.result.callsites == 5' "$COMPLETE_BODY"
+  assert_jq "no top-level summary leak" '.summary == null' "$COMPLETE_BODY"
+fi
+rm -rf "$TASK_DIR"
+
+# ---------------------------------------------------------------------------
+# Scenario 3 — orchestrator/complete-task
+# ---------------------------------------------------------------------------
+echo ""
+echo "--- Scenario 3: orchestrator/complete-task ---"
+: > "$LOG"
+bash "${REPO_ROOT}/config/skills/orchestrator/complete-task/execute.sh" \
+  '{"workItemId":"wi-stub-1","summary":"Orc complete-task smoke summary"}' \
+  >/dev/null 2>&1 || true
+
+COMPLETE_LINE=$(grep -F '"path": "/api/task-pool/complete/' "$LOG" | head -1 || true)
+if [ -z "$COMPLETE_LINE" ]; then
+  FAIL=$((FAIL + 1))
+  echo "  ✗ no /task-pool/complete POST captured"
+else
+  COMPLETE_BODY=$(printf '%s' "$COMPLETE_LINE" | jq -r '.body')
+  assert_jq "agentId defaults to crewly-orc" '.agentId == "crewly-orc"' "$COMPLETE_BODY"
+  assert_jq "result.summary matches" '.result.summary == "Orc complete-task smoke summary"' "$COMPLETE_BODY"
+  assert_jq "no top-level summary leak" '.summary == null' "$COMPLETE_BODY"
+fi
+
+echo ""
+echo "--- Scenario 3b: orchestrator/complete-task with explicit agentId override ---"
+: > "$LOG"
+bash "${REPO_ROOT}/config/skills/orchestrator/complete-task/execute.sh" \
+  '{"workItemId":"wi-stub-1","summary":"Orc on-behalf-of summary","agentId":"crewly-product-leo-21a5477e"}' \
+  >/dev/null 2>&1 || true
+
+COMPLETE_LINE=$(grep -F '"path": "/api/task-pool/complete/' "$LOG" | head -1 || true)
+if [ -z "$COMPLETE_LINE" ]; then
+  FAIL=$((FAIL + 1))
+  echo "  ✗ no /task-pool/complete POST captured"
+else
+  COMPLETE_BODY=$(printf '%s' "$COMPLETE_LINE" | jq -r '.body')
+  assert_jq "agentId overridden to caller value" '.agentId == "crewly-product-leo-21a5477e"' "$COMPLETE_BODY"
+fi
+
+# ---------------------------------------------------------------------------
+# Scenario 4 — orchestrator/complete-task rejects empty summary
+# ---------------------------------------------------------------------------
+echo ""
+echo "--- Scenario 4: orchestrator/complete-task rejects empty summary ---"
+: > "$LOG"
+EXIT=0
+OUTPUT=$(bash "${REPO_ROOT}/config/skills/orchestrator/complete-task/execute.sh" \
+  '{"workItemId":"wi-stub-1","summary":""}' 2>&1) || EXIT=$?
+
+if [ "$EXIT" -ne 0 ] && printf '%s' "$OUTPUT" | grep -q "summary is required"; then
+  PASS=$((PASS + 1))
+  echo "  ✓ exits non-zero with helpful 'summary is required' error"
+else
+  FAIL=$((FAIL + 1))
+  echo "  ✗ should reject empty summary; exit=$EXIT, output=$OUTPUT"
+fi
+
+echo ""
+echo "=== Results: ${PASS} passed, ${FAIL} failed ==="
+[ $FAIL -eq 0 ]

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

@@ -1,5 +1,17 @@
 #!/bin/bash
-# Accept and take the next available task from the task queue
+# Claim the next available WorkItem from the V3 task-pool.
+#
+# V3-only as of spec 2026-05-06-task-management-v1-deprecation.md. The
+# legacy `/task-management/take-next` endpoint (which read `.md` files
+# from `delegated/open/`) is no longer the source of truth.
+#
+# Input shape (backwards-compat from v1):
+#   { "sessionName": "dev-1", "projectPath"?: "...", "taskGroup"?: "..." }
+#
+# `taskGroup` (legacy v1 milestone filter) maps to V3's `filters.types`.
+# `teamMemberId` is no longer needed — V3 keys claims by `agentId`
+# (= sessionName).
+
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "${SCRIPT_DIR}/../../_common/lib.sh"
@@ -10,18 +22,9 @@ INPUT=$(read_json_input "${1:-}")
 SESSION_NAME=$(printf '%s' "$INPUT" | jq -r '.sessionName // empty')
 require_param "sessionName" "$SESSION_NAME"
 
-TEAM_MEMBER_ID=$(printf '%s' "$INPUT" | jq -r '.teamMemberId // empty')
-PROJECT_PATH=$(printf '%s' "$INPUT" | jq -r '.projectPath // empty')
-TASK_GROUP=$(printf '%s' "$INPUT" | jq -r '.taskGroup // empty')
-
-BODY=$(jq -n \
-  --arg sessionName "$SESSION_NAME" \
-  --arg teamMemberId "$TEAM_MEMBER_ID" \
-  --arg projectPath "$PROJECT_PATH" \
-  --arg taskGroup "$TASK_GROUP" \
-  '{sessionName: $sessionName} +
-   (if $teamMemberId != "" then {teamMemberId: $teamMemberId} else {} end) +
-   (if $projectPath != "" then {projectPath: $projectPath} else {} end) +
-   (if $taskGroup != "" then {taskGroup: $taskGroup} else {} end)')
+# v1's `taskGroup` is informational metadata; V3 filters by WorkItem `type`
+# instead. We pass the session name as the agent identity and let the pool
+# pick the highest-scored available WI for this agent.
+BODY=$(jq -n --arg agentId "$SESSION_NAME" '{agentId: $agentId}')
 
-api_call POST "/task-management/take-next" "$BODY"
+api_call POST "/task-pool/claim" "$BODY"

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

@@ -1,28 +1,46 @@
 #!/bin/bash
-# Mark a task as blocked with a reason and optional questions
+# Mark a WorkItem as blocked with a reason.
+#
+# V3-only as of spec 2026-05-06-task-management-v1-deprecation.md. The
+# legacy `/task-management/block` endpoint (which moved a `.md` file to
+# `delegated/blocked/`) is no longer the source of truth — V3 task-pool's
+# `/task-pool/block/:workItemId` is.
+#
+# Input shape:
+#   { "workItemId": "abc-123", "reason": "missing creds", "questions"?: "...", "urgency"?: "..." }
+#
+# Backwards-compat: if `absoluteTaskPath` is provided instead of
+# `workItemId`, we emit a warning and skip the call rather than fall back
+# to the deprecated v1 path. Callers should obtain `workItemId` from the
+# claim response or from a [CREWLY-DISPATCH] terminal message.
+
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "${SCRIPT_DIR}/../../_common/lib.sh"
 
 INPUT=$(read_json_input "${1:-}")
-[ -z "$INPUT" ] && error_exit "Usage: execute.sh '{\"absoluteTaskPath\":\"/path/to/task\",\"reason\":\"Missing API credentials\"}'"
+[ -z "$INPUT" ] && error_exit "Usage: execute.sh '{\"workItemId\":\"abc-123\",\"reason\":\"Missing API credentials\"}'"
 
-ABSOLUTE_TASK_PATH=$(printf '%s' "$INPUT" | jq -r '.absoluteTaskPath // empty')
+WORK_ITEM_ID=$(printf '%s' "$INPUT" | jq -r '.workItemId // empty')
 REASON=$(printf '%s' "$INPUT" | jq -r '.reason // empty')
 QUESTIONS=$(printf '%s' "$INPUT" | jq -r '.questions // empty')
 URGENCY=$(printf '%s' "$INPUT" | jq -r '.urgency // empty')
-require_param "absoluteTaskPath" "$ABSOLUTE_TASK_PATH"
+LEGACY_PATH=$(printf '%s' "$INPUT" | jq -r '.absoluteTaskPath // empty')
+
+if [ -z "$WORK_ITEM_ID" ] && [ -n "$LEGACY_PATH" ]; then
+  echo '{"error":"`absoluteTaskPath` is no longer accepted — pass `workItemId` instead. See spec/2026-05-06-task-management-v1-deprecation.md"}' >&2
+  exit 1
+fi
+
+require_param "workItemId" "$WORK_ITEM_ID"
 require_param "reason" "$REASON"
 
 BODY=$(jq -n \
-  --arg absoluteTaskPath "$ABSOLUTE_TASK_PATH" \
-  --arg taskPath "$ABSOLUTE_TASK_PATH" \
   --arg reason "$REASON" \
-  --arg blockReason "$REASON" \
   --arg questions "$QUESTIONS" \
   --arg urgency "$URGENCY" \
-  '{absoluteTaskPath: $absoluteTaskPath, taskPath: $taskPath, reason: $reason, blockReason: $blockReason} +
+  '{reason: $reason} +
    (if $questions != "" then {questions: $questions} else {} end) +
    (if $urgency != "" then {urgency: $urgency} else {} end)')
 
-api_call POST "/task-management/block" "$BODY"
+api_call POST "/task-pool/block/${WORK_ITEM_ID}" "$BODY"

package/config/skills/agent/core/cancel-followup/SKILL.md

@@ -1,3 +1,21 @@
+---
+name: cancel-followup
+description: Cancel a follow-up trigger previously created with `schedule-followup` or `watch-for-event`, by trigger id or by team-scoped name.
+version: 1.0.0
+category: followup
+skillType: claude-skill
+tags:
+  - followup
+  - trigger
+  - lifecycle
+execution:
+  type: script
+  script:
+    file: execute.sh
+    interpreter: bash
+    timeoutMs: 15000
+---
+
 # cancel-followup
 
 Cancel a follow-up trigger you previously created with `schedule-followup` or

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

@@ -61,18 +61,56 @@ if echo "$ABSOLUTE_TASK_PATH" | grep -q '/in_progress/'; then
   fi
 fi
 
+# V3-only as of spec 2026-05-06-task-management-v1-deprecation.md.
+# Resolve which V3 WorkItem to complete:
+#   1. Explicit `workItemId` from input (preferred)
+#   2. Fall back: query the pool for the agent's currently-running WI
+#
+# The legacy `absoluteTaskPath` input is still accepted but no longer
+# drives the API call — it's only used for logging context. Callers
+# should switch to passing `workItemId`.
+WORK_ITEM_ID=$(printf '%s' "$INPUT" | jq -r '.workItemId // empty')
+if [ -z "$WORK_ITEM_ID" ]; then
+  POOL_RESP=$(api_call 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
+
+if [ -z "$WORK_ITEM_ID" ]; then
+  echo '{"error":"Could not resolve a running WorkItem for this session — pass `workItemId` explicitly."}' >&2
+  exit 1
+fi
+
+# Hygiene #4: emit canonical body shape `{agentId, result:{summary, ...output}}`
+# required by /api/task-pool/complete (task-pool.controller.ts `completeItem`).
+# Prior shape `{summary, ..., result: $output}` 400'd because top-level summary
+# was ignored (controller looks at result.summary) and `result` was overloaded
+# with the output payload instead of the summary wrapper.
+#
+# The optional `output` is now MERGED into `result` alongside `summary` —
+# this matches the controller's mergedOutput behavior (task-pool.controller.ts
+# §405-419) which spreads result fields beyond `summary` into WorkItem.output.
+#
+# Precedence (per Sam #527 review note): jq's `+` operator is right-side-wins
+# on key conflicts. The spread order here is `{summary: $summary} + $output`,
+# so a caller-supplied `output.summary` WILL override the explicit `--summary`
+# parameter. Intentional — callers passing structured output already have an
+# authoritative summary in there; the explicit param is the fallback. If you
+# need the param to win, swap the operands.
 BODY=$(jq -n \
-  --arg absoluteTaskPath "$ABSOLUTE_TASK_PATH" \
-  --arg taskPath "$ABSOLUTE_TASK_PATH" \
-  --arg sessionName "$SESSION_NAME" \
+  --arg agentId "$SESSION_NAME" \
   --arg summary "$SUMMARY" \
   --arg skipGates "$SKIP_GATES" \
   --argjson output "${OUTPUT_JSON:-null}" \
-  '{absoluteTaskPath: $absoluteTaskPath, taskPath: $taskPath, sessionName: $sessionName, summary: $summary} +
-   (if $skipGates == "true" then {skipGates: true} else {} end) +
-   (if $output != null then {output: $output} else {} end)')
+  '{
+    agentId: $agentId,
+    result: ({summary: $summary}
+              + (if $output != null and ($output | type) == "object"
+                 then $output
+                 else {} end))
+  }
+   + (if $skipGates == "true" then {skipGates: true} else {} end)')
 
-api_call POST "/task-management/complete" "$BODY"
+api_call POST "/task-pool/complete/${WORK_ITEM_ID}" "$BODY"
 
 # Auto-persist the task summary as project knowledge (#127, #219).
 # Use [COMPLETED] prefix so recall can distinguish completed tasks from other patterns.

package/config/skills/agent/core/create-request/SKILL.md

@@ -91,7 +91,7 @@ Use these to classify the complexity of the request:
 | `--intent-level` | Yes | -- | L0, L1, L2, or L3 |
 | `--intent-category` | Yes | -- | communication, query, code_change, planning, debugging, deployment, team_management, other |
 | `--priority` | No | normal | low, normal, high, urgent |
-| `--source-message-id` | No | -- | Original message ID (for dedup) |
+| `--source-message-id` | No | `agent-self-{session}-{epoch}` | Original message ID (for dedup). When omitted, the skill synthesizes `agent-self-{CREWLY_SESSION_NAME}-{epoch}` so agent-context callers (e.g. TL self-filing a child Request) don't 400 on the backend's required-field check. Issue #458. |
 | `--needs-mission` | No | false | Whether this L3 request should trigger Mission creation |
 
 ## Examples -- CLI Flags (preferred)

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

@@ -155,9 +155,36 @@ if [ -n "$PRIORITY" ]; then
   BODY=$(printf '%s' "$BODY" | jq --arg p "$PRIORITY" '. + {priority: $p}')
 fi
 
-if [ -n "$SOURCE_MESSAGE_ID" ]; then
-  BODY=$(printf '%s' "$BODY" | jq --arg sid "$SOURCE_MESSAGE_ID" '. + {sourceConversationItemId: $sid}')
+# Issue #458: the backend validator at v2/request.types.ts:283 requires
+# `sourceConversationItemId` to be a non-empty string. The orc passes the
+# inbound Slack/chat message id when filing a Request, but agent-context
+# callers (e.g. a TL filing a child Request from a delegated task) have
+# no inbound message of their own. Auto-synthesize a stable
+# `agent-self-{session}-{epoch}-{nonce}` id so the request lands instead
+# of 400-ing.
+#
+# Notes:
+# - The synthetic shape is intentionally distinct from the `slack-{ch}-
+#   {ts}` / `chatv2-{ch}__{msg}` prefixes so downstream consumers
+#   (extractSlackThreadTs, extractChatV2ChannelId, SLA tracker, .md
+#   store) inert-skip it.
+# - The trailing `${RANDOM}` nonce prevents per-second collisions when
+#   two rapid create-request calls from the same session land in the
+#   same wall-clock second. `findBySourceConversationItemId` (the dedup
+#   path) keys on this string verbatim.
+# - When `CREWLY_SESSION_NAME` is unset (likely a misconfiguration, but
+#   not load-bearing), we warn to stderr and continue with
+#   `unknown-session` so the request still lands instead of failing
+#   silently. The warn surfaces the missing env in observability.
+if [ -z "$SOURCE_MESSAGE_ID" ]; then
+  AGENT_SESSION="${CREWLY_SESSION_NAME:-}"
+  if [ -z "$AGENT_SESSION" ]; then
+    echo "warn: CREWLY_SESSION_NAME unset; falling back to 'unknown-session' for synthesized sourceConversationItemId" >&2
+    AGENT_SESSION="unknown-session"
+  fi
+  SOURCE_MESSAGE_ID="agent-self-${AGENT_SESSION}-$(date +%s)-${RANDOM}"
 fi
+BODY=$(printf '%s' "$BODY" | jq --arg sid "$SOURCE_MESSAGE_ID" '. + {sourceConversationItemId: $sid}')
 
 # Call the API to create the Request
 RESULT=$(api_call POST "/requests" "$BODY")

package/config/skills/agent/core/create-request/execute.test.sh

@@ -0,0 +1,168 @@
+#!/bin/bash
+# Co-located bash test for create-request skill.
+# Spins up a tiny python HTTP stub to capture the outgoing body, then
+# asserts that sourceConversationItemId is always present (synthesized
+# when missing) — Issue #458 regression gate.
+#
+# Usage: bash execute.test.sh  (exit 0 on pass)
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SKILL="${SCRIPT_DIR}/execute.sh"
+
+if [ ! -x "$SKILL" ]; then
+  echo "FAIL: skill not executable at $SKILL" >&2
+  exit 1
+fi
+
+PASS=0
+FAIL=0
+PORT=18789
+
+# --- Start stub backend on a fixed test port ---
+STUB_LOG="$(mktemp)"
+export STUB_LOG
+export STUB_PORT="${PORT}"
+
+python3 -u <<'PY' >/tmp/create-request-stub.log 2>&1 &
+from http.server import BaseHTTPRequestHandler, HTTPServer
+import json, os, sys
+
+LOG_PATH = os.environ['STUB_LOG']
+PORT = int(os.environ['STUB_PORT'])
+
+class H(BaseHTTPRequestHandler):
+    def do_POST(self):
+        length = int(self.headers.get('content-length', '0'))
+        body = self.rfile.read(length).decode('utf-8') if length else ''
+        log = {
+            'path': self.path,
+            'body': body,
+            'agentSession': self.headers.get('x-agent-session', ''),
+        }
+        with open(LOG_PATH, 'w') as f:
+            f.write(json.dumps(log))
+        self.send_response(201)
+        self.send_header('Content-Type', 'application/json')
+        self.end_headers()
+        self.wfile.write(json.dumps({'success': True, 'data': {'id': 'req-stub-123'}}).encode('utf-8'))
+    def log_message(self, *a, **k):
+        pass
+
+srv = HTTPServer(('127.0.0.1', PORT), H)
+srv.serve_forever()
+PY
+STUB_PID=$!
+
+cleanup() { kill "$STUB_PID" >/dev/null 2>&1 || true; rm -f "$STUB_LOG" || true; }
+trap cleanup EXIT
+
+# Wait until the port actually accepts a connection
+for i in $(seq 1 30); do
+  if curl -s -o /dev/null -m 0.2 "http://127.0.0.1:${PORT}/__probe__" 2>/dev/null; then
+    break
+  fi
+  sleep 0.1
+done
+
+assert_contains() {
+  local name="$1" haystack="$2" needle="$3"
+  if echo "$haystack" | grep -q -- "$needle"; then
+    PASS=$((PASS + 1))
+    echo "  ✓ $name"
+  else
+    FAIL=$((FAIL + 1))
+    echo "  ✗ $name (wanted: $needle)"
+    echo "    in: $haystack"
+  fi
+}
+
+run_skill() {
+  CREWLY_API_URL="http://127.0.0.1:${PORT}" \
+  CREWLY_SESSION_NAME="crewly-product-sam-TEST" \
+  bash "$SKILL" "$@"
+}
+
+# --- Test 1: Issue #458 — TL agent flow without --source-message-id ---
+echo "test 1: agent-self synthesis when --source-message-id is omitted"
+: > "$STUB_LOG"
+OUT=$(run_skill \
+  --title "Fix dogfood pipeline P0" \
+  --description "Fix the pipeline regression that blocked decomposition" \
+  --intent-level L1 \
+  --intent-category debugging \
+  2>&1 || true)
+LOG=$(cat "$STUB_LOG" 2>/dev/null || echo '{}')
+assert_contains "success echoed" "$OUT" '"success": true'
+assert_contains "sourceConversationItemId synthesized" "$LOG" 'sourceConversationItemId'
+assert_contains "synthesized id uses agent-self prefix" "$LOG" 'agent-self-crewly-product-sam-TEST-'
+assert_contains "path targets /requests" "$LOG" '/requests'
+
+# --- Test 2: --source-message-id provided is preserved ---
+echo "test 2: explicit --source-message-id passes through unchanged"
+: > "$STUB_LOG"
+OUT=$(run_skill \
+  --title "Inbound Slack request" \
+  --description "Some inbound user message routing through orc" \
+  --intent-level L2 \
+  --intent-category code_change \
+  --source-message-id "slack-D0AC7-1234567890.000001" \
+  2>&1 || true)
+LOG=$(cat "$STUB_LOG" 2>/dev/null || echo '{}')
+assert_contains "explicit sourceConversationItemId preserved" "$LOG" 'slack-D0AC7-1234567890.000001'
+if echo "$LOG" | grep -q 'agent-self-'; then
+  FAIL=$((FAIL + 1))
+  echo "  ✗ agent-self prefix wrongly added when explicit id present"
+else
+  PASS=$((PASS + 1))
+  echo "  ✓ explicit id is not overwritten by agent-self synthesis"
+fi
+
+# --- Test 3: legacy JSON form without sourceMessageId still gets synthesis ---
+echo "test 3: legacy JSON form falls back to agent-self synthesis"
+: > "$STUB_LOG"
+OUT=$(run_skill '{"title":"json form","description":"some description","intentLevel":"L1","intentCategory":"debugging"}' 2>&1 || true)
+LOG=$(cat "$STUB_LOG" 2>/dev/null || echo '{}')
+assert_contains "json-form synthesis works too" "$LOG" 'agent-self-crewly-product-sam-TEST-'
+
+# --- Test 4: explicit empty-string --source-message-id triggers synthesis ---
+echo "test 4: empty-string source-message-id treated as missing"
+: > "$STUB_LOG"
+OUT=$(run_skill \
+  --title "Empty id test" \
+  --description "Caller passed --source-message-id with an empty string" \
+  --intent-level L1 \
+  --intent-category debugging \
+  --source-message-id "" \
+  2>&1 || true)
+LOG=$(cat "$STUB_LOG" 2>/dev/null || echo '{}')
+assert_contains "empty-string id triggers synthesis" "$LOG" 'agent-self-crewly-product-sam-TEST-'
+
+# --- Test 5: two back-to-back synthesis calls produce distinct ids ---
+# Issue #458 review follow-up: the synthesis nonce ($RANDOM) must prevent
+# per-second collisions so `findBySourceConversationItemId` doesn't false-
+# positive on a second TL self-file in the same wall-clock second.
+echo "test 5: rapid synthesis produces distinct ids (no per-second collision)"
+: > "$STUB_LOG"
+run_skill --title "First" --description "Description one" --intent-level L1 --intent-category debugging >/dev/null 2>&1 || true
+ID_1=$(jq -r '.body | fromjson | .sourceConversationItemId' "$STUB_LOG" 2>/dev/null || echo '')
+: > "$STUB_LOG"
+run_skill --title "Second" --description "Description two" --intent-level L1 --intent-category debugging >/dev/null 2>&1 || true
+ID_2=$(jq -r '.body | fromjson | .sourceConversationItemId' "$STUB_LOG" 2>/dev/null || echo '')
+if [ -n "$ID_1" ] && [ -n "$ID_2" ] && [ "$ID_1" != "$ID_2" ]; then
+  PASS=$((PASS + 1))
+  echo "  ✓ two rapid syntheses produce distinct ids ($ID_1 vs $ID_2)"
+else
+  FAIL=$((FAIL + 1))
+  echo "  ✗ rapid syntheses collided or were empty: '$ID_1' '$ID_2'"
+fi
+
+echo
+echo "========================================"
+echo "create-request skill: PASS=$PASS  FAIL=$FAIL"
+echo "========================================"
+if [ "$FAIL" -gt 0 ]; then
+  echo "--- stub server log ---"
+  cat /tmp/create-request-stub.log 2>/dev/null | tail -40
+  exit 1
+fi
+exit 0