@arthai/agents 1.0.5 → 1.0.6

package/hooks/post-server-crash-watch.sh

@@ -0,0 +1,120 @@
+#!/bin/bash
+# PostToolUse hook (Bash): Detect server start commands and check for crash loops.
+# After a server start is detected, waits briefly then verifies the process is
+# still running and the port is responding. Catches services that start then die.
+#
+# stdout is injected as context.
+
+set -euo pipefail
+
+COMMAND="${CLAUDE_TOOL_INPUT_COMMAND:-}"
+if [ -z "$COMMAND" ] && [ -n "${CLAUDE_TOOL_INPUT:-}" ]; then
+    COMMAND=$(echo "$CLAUDE_TOOL_INPUT" | python3 -c "import json,sys; print(json.load(sys.stdin).get('command',''))" 2>/dev/null) || true
+fi
+
+[ -z "$COMMAND" ] && exit 0
+
+# Only check commands that ran successfully
+EXIT_CODE="${CLAUDE_TOOL_RESULT_EXIT_CODE:-0}"
+[ "$EXIT_CODE" != "0" ] && exit 0
+
+# ---------------------------------------------------------------------------
+# Detect server start commands and extract ports
+# ---------------------------------------------------------------------------
+
+PORT=""
+SERVICE=""
+
+# npm/pnpm/yarn dev/start
+if echo "$COMMAND" | grep -qE '\b(npm|pnpm|yarn)\s+run\s+(dev|start|serve)\b'; then
+    PORT=$(echo "$COMMAND" | grep -oE '\-\-port\s+([0-9]+)' | awk '{print $2}')
+    PORT="${PORT:-3000}"
+    SERVICE="Node.js dev server"
+fi
+
+# next dev
+if echo "$COMMAND" | grep -qE '\bnext\s+dev\b'; then
+    PORT=$(echo "$COMMAND" | grep -oE '\-\-port\s+([0-9]+)' | awk '{print $2}')
+    PORT="${PORT:-3000}"
+    SERVICE="Next.js dev server"
+fi
+
+# uvicorn
+if echo "$COMMAND" | grep -qE '\buvicorn\b'; then
+    PORT=$(echo "$COMMAND" | grep -oE '\-\-port\s+([0-9]+)' | awk '{print $2}')
+    PORT="${PORT:-8000}"
+    SERVICE="Uvicorn"
+fi
+
+# gunicorn
+if echo "$COMMAND" | grep -qE '\bgunicorn\b'; then
+    PORT=$(echo "$COMMAND" | grep -oE '\-b\s+[^:]+:([0-9]+)' | grep -oE '[0-9]+$')
+    if [ -z "$PORT" ]; then
+        PORT=$(echo "$COMMAND" | grep -oE '\-\-bind\s+[^:]+:([0-9]+)' | grep -oE '[0-9]+$')
+    fi
+    PORT="${PORT:-8000}"
+    SERVICE="Gunicorn"
+fi
+
+# flask run
+if echo "$COMMAND" | grep -qE '\bflask\s+run\b'; then
+    PORT=$(echo "$COMMAND" | grep -oE '\-\-port\s+([0-9]+)' | awk '{print $2}')
+    PORT="${PORT:-5000}"
+    SERVICE="Flask"
+fi
+
+# docker compose up
+if echo "$COMMAND" | grep -qE '\bdocker\s+compose\s+up\b'; then
+    SERVICE="Docker Compose services"
+    # For docker compose, check container status instead of port
+    sleep 8
+    down_containers=$(docker compose ps --format '{{.Name}} {{.Status}}' 2>/dev/null | grep -viE 'Up|running' | head -5) || true
+    if [ -n "$down_containers" ]; then
+        echo "CRASH DETECTED — Docker containers not healthy after 8s:"
+        echo "$down_containers"
+        echo "Check logs: docker compose logs --tail=30"
+    fi
+    exit 0
+fi
+
+# rails server
+if echo "$COMMAND" | grep -qE '\brails\s+s(erver)?\b'; then
+    PORT=$(echo "$COMMAND" | grep -oE '\-p\s+([0-9]+)' | awk '{print $2}')
+    PORT="${PORT:-3000}"
+    SERVICE="Rails server"
+fi
+
+# No server start detected
+[ -z "$SERVICE" ] && exit 0
+[ -z "$PORT" ] && exit 0
+
+# ---------------------------------------------------------------------------
+# Wait and check for crash loop
+# ---------------------------------------------------------------------------
+
+sleep 8
+
+# Check if process is still listening on the port
+pid=$(lsof -ti:"$PORT" 2>/dev/null | head -1) || true
+
+if [ -z "$pid" ]; then
+    echo "CRASH DETECTED — $SERVICE (port $PORT) is no longer running after 8s."
+    echo "The process started but has since exited. Check the terminal output for errors."
+    echo "Common causes: missing env vars, port conflict, dependency errors, syntax errors."
+    exit 0
+fi
+
+# Process is alive — try a quick HTTP health check
+http_status=$(timeout 5 curl -sf -o /dev/null -w "%{http_code}" "http://localhost:$PORT/" 2>/dev/null) || http_status="no_response"
+
+if [ "$http_status" = "no_response" ]; then
+    # Process exists but not responding to HTTP — might be starting up or non-HTTP
+    echo "$SERVICE (port $PORT): process alive (PID $pid) but not responding to HTTP yet. May still be starting."
+elif echo "$http_status" | grep -qE '^[2345]'; then
+    # Any HTTP response means the server is up
+    : # Silent success — don't spam on healthy starts
+else
+    echo "$SERVICE (port $PORT): process alive but returned HTTP $http_status."
+fi
+
+exit 0

package/hooks/pre-server-port-guard.sh

@@ -0,0 +1,110 @@
+#!/bin/bash
+# PreToolUse hook (Bash): Check port availability before server start commands.
+# Detects server start commands and warns if the target port is already occupied
+# by an unexpected process.
+#
+# Exit 0  = allow the command
+# Exit 2  = block the command (stdout shown as reason)
+# stdout  = injected as context (warnings)
+
+set -euo pipefail
+
+COMMAND="${CLAUDE_TOOL_INPUT_COMMAND:-}"
+if [ -z "$COMMAND" ] && [ -n "${CLAUDE_TOOL_INPUT:-}" ]; then
+    COMMAND=$(echo "$CLAUDE_TOOL_INPUT" | python3 -c "import json,sys; print(json.load(sys.stdin).get('command',''))" 2>/dev/null) || true
+fi
+
+[ -z "$COMMAND" ] && exit 0
+
+# ---------------------------------------------------------------------------
+# Detect server start commands and extract ports
+# ---------------------------------------------------------------------------
+
+declare -a PORTS=()
+
+# npm/pnpm/yarn dev/start — default port 3000 unless --port specified
+if echo "$COMMAND" | grep -qE '\b(npm|pnpm|yarn)\s+run\s+(dev|start|serve)\b'; then
+    port=$(echo "$COMMAND" | grep -oE '\-\-port\s+([0-9]+)' | awk '{print $2}')
+    if [ -z "$port" ]; then
+        port=$(echo "$COMMAND" | grep -oE '\bp(ort)?\s*=?\s*([0-9]{4,5})' | grep -oE '[0-9]+')
+    fi
+    PORTS+=("${port:-3000}")
+fi
+
+# next dev — default port 3000
+if echo "$COMMAND" | grep -qE '\bnext\s+dev\b'; then
+    port=$(echo "$COMMAND" | grep -oE '\-\-port\s+([0-9]+)' | awk '{print $2}')
+    PORTS+=("${port:-3000}")
+fi
+
+# vite — default port 5173
+if echo "$COMMAND" | grep -qE '\bvite\b' && ! echo "$COMMAND" | grep -qE '\bvite\s+build\b'; then
+    port=$(echo "$COMMAND" | grep -oE '\-\-port\s+([0-9]+)' | awk '{print $2}')
+    PORTS+=("${port:-5173}")
+fi
+
+# uvicorn — default port 8000
+if echo "$COMMAND" | grep -qE '\buvicorn\b'; then
+    port=$(echo "$COMMAND" | grep -oE '\-\-port\s+([0-9]+)' | awk '{print $2}')
+    PORTS+=("${port:-8000}")
+fi
+
+# gunicorn — default port 8000
+if echo "$COMMAND" | grep -qE '\bgunicorn\b'; then
+    port=$(echo "$COMMAND" | grep -oE '\-b\s+[^:]+:([0-9]+)' | grep -oE '[0-9]+$')
+    if [ -z "$port" ]; then
+        port=$(echo "$COMMAND" | grep -oE '\-\-bind\s+[^:]+:([0-9]+)' | grep -oE '[0-9]+$')
+    fi
+    PORTS+=("${port:-8000}")
+fi
+
+# flask run — default port 5000
+if echo "$COMMAND" | grep -qE '\bflask\s+run\b'; then
+    port=$(echo "$COMMAND" | grep -oE '\-\-port\s+([0-9]+)' | awk '{print $2}')
+    PORTS+=("${port:-5000}")
+fi
+
+# docker compose up — check compose file for ports
+if echo "$COMMAND" | grep -qE '\bdocker\s+compose\s+up\b'; then
+    PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+    if [ -f "$PROJECT_DIR/docker-compose.yml" ]; then
+        # Extract host ports from ports: mappings (e.g., "3000:3000", "5432:5432")
+        compose_ports=$(grep -oE '^\s*-\s*"?([0-9]+):' "$PROJECT_DIR/docker-compose.yml" 2>/dev/null | grep -oE '[0-9]+' | head -5) || true
+        for p in $compose_ports; do
+            PORTS+=("$p")
+        done
+    fi
+fi
+
+# rails server — default port 3000
+if echo "$COMMAND" | grep -qE '\brails\s+s(erver)?\b'; then
+    port=$(echo "$COMMAND" | grep -oE '\-p\s+([0-9]+)' | awk '{print $2}')
+    PORTS+=("${port:-3000}")
+fi
+
+# go run with -addr or explicit port
+if echo "$COMMAND" | grep -qE '\bgo\s+run\b'; then
+    port=$(echo "$COMMAND" | grep -oE ':([0-9]{4,5})' | head -1 | tr -d ':')
+    [ -n "$port" ] && PORTS+=("$port")
+fi
+
+# No server command detected
+[ ${#PORTS[@]} -eq 0 ] && exit 0
+
+# ---------------------------------------------------------------------------
+# Check each port for conflicts
+# ---------------------------------------------------------------------------
+
+for port in "${PORTS[@]}"; do
+    [ -z "$port" ] && continue
+
+    pid=$(lsof -ti:"$port" 2>/dev/null | head -1) || true
+    if [ -n "$pid" ]; then
+        proc_name=$(ps -p "$pid" -o comm= 2>/dev/null) || proc_name="unknown"
+        echo "PORT CONFLICT — port $port is already in use by $proc_name (PID $pid)."
+        echo "Kill it first: lsof -ti:$port | xargs kill -9"
+        echo "Or use a different port."
+    fi
+done
+
+exit 0

package/hooks/project-setup.sh

@@ -0,0 +1,109 @@
+#!/bin/bash
+# hooks/project-setup.sh — SessionStart hook: first-run project setup for marketplace installs.
+#
+# Runs on every SessionStart. Checks for marker file .claude/.toolkit-setup-done.
+# If missing (or version is stale): creates CLAUDE.md from template, injects managed block,
+# updates .gitignore with toolkit markers.
+#
+# Templates are read from ${CLAUDE_PLUGIN_ROOT}/templates/ (bundled with the plugin).
+
+set -euo pipefail
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-}"
+MARKER_FILE="$PROJECT_DIR/.claude/.toolkit-setup-done"
+
+# Exit silently if CLAUDE_PLUGIN_ROOT is not set (not running from a plugin context)
+if [ -z "$PLUGIN_ROOT" ]; then
+    exit 0
+fi
+
+TEMPLATES_DIR="$PLUGIN_ROOT/templates"
+TEMPLATE_CLAUDE="$TEMPLATES_DIR/CLAUDE.md.template"
+TEMPLATE_BLOCK="$TEMPLATES_DIR/CLAUDE.md.managed-block"
+
+# Exit silently if templates are not bundled
+if [ ! -f "$TEMPLATE_CLAUDE" ] || [ ! -f "$TEMPLATE_BLOCK" ]; then
+    exit 0
+fi
+
+# Read toolkit version from VERSION file (bundled alongside plugin)
+TOOLKIT_VERSION="0.0.0"
+if [ -f "$PLUGIN_ROOT/VERSION" ]; then
+    TOOLKIT_VERSION=$(cat "$PLUGIN_ROOT/VERSION" 2>/dev/null | tr -d '[:space:]' || echo "0.0.0")
+fi
+
+MANAGED_START="<!-- >>> claude-agents toolkit (DO NOT EDIT THIS BLOCK) >>> -->"
+MANAGED_END="<!-- <<< claude-agents toolkit <<< -->"
+GITIGNORE_START="# >>> claude-agents managed (DO NOT EDIT THIS BLOCK) >>>"
+
+# Check marker file — skip if current version is already set up
+if [ -f "$MARKER_FILE" ]; then
+    STORED_VERSION=$(cat "$MARKER_FILE" 2>/dev/null | tr -d '[:space:]' || echo "")
+    if [ "$STORED_VERSION" = "$TOOLKIT_VERSION" ]; then
+        exit 0
+    fi
+fi
+
+CLAUDE_MD="$PROJECT_DIR/CLAUDE.md"
+GITIGNORE="$PROJECT_DIR/.gitignore"
+
+# 1. Create CLAUDE.md from template if it doesn't exist (never overwrite existing)
+if [ ! -f "$CLAUDE_MD" ]; then
+    PROJECT_NAME=$(basename "$PROJECT_DIR")
+    sed "s/{{PROJECT_NAME}}/$PROJECT_NAME/g" "$TEMPLATE_CLAUDE" > "$CLAUDE_MD"
+fi
+
+# 2. Inject managed block into CLAUDE.md if missing, or update if version is stale
+if [ -f "$CLAUDE_MD" ]; then
+    BLOCK_CONTENT=$(cat "$TEMPLATE_BLOCK")
+    NEW_BLOCK=$(printf '%s\n<!-- version: %s -->\n%s\n%s' \
+        "$MANAGED_START" "$TOOLKIT_VERSION" "$BLOCK_CONTENT" "$MANAGED_END")
+
+    if ! grep -qF "$MANAGED_START" "$CLAUDE_MD"; then
+        # Block missing — append it
+        printf '\n\n%s\n' "$NEW_BLOCK" >> "$CLAUDE_MD"
+    else
+        # Block exists — update if version changed
+        EXISTING_VERSION=$(grep -o '<!-- version: [^>]* -->' "$CLAUDE_MD" 2>/dev/null | head -1 | sed 's/<!-- version: //;s/ -->//' | tr -d '[:space:]' || echo "")
+        if [ "$EXISTING_VERSION" != "$TOOLKIT_VERSION" ]; then
+            # Replace block contents between markers
+            tmp=$(mktemp)
+            in_block=false
+            wrote_block=false
+            while IFS= read -r line; do
+                if echo "$line" | grep -qF "$MANAGED_START"; then
+                    in_block=true
+                    printf '%s\n' "$NEW_BLOCK" >> "$tmp"
+                    wrote_block=true
+                    continue
+                fi
+                if echo "$line" | grep -qF "$MANAGED_END"; then
+                    in_block=false
+                    continue
+                fi
+                if ! $in_block; then
+                    echo "$line" >> "$tmp"
+                fi
+            done < "$CLAUDE_MD"
+            mv "$tmp" "$CLAUDE_MD"
+        fi
+    fi
+fi
+
+# 3. Update .gitignore with toolkit marker block if missing
+if [ ! -f "$GITIGNORE" ] || ! grep -qF "$GITIGNORE_START" "$GITIGNORE" 2>/dev/null; then
+    GITIGNORE_BLOCK=$(printf '%s\n.claude/.toolkit-last-seen-sha\n.claude/.toolkit-setup-done\n.claude/.claude-agents.conf\n%s' \
+        "$GITIGNORE_START" "# <<< claude-agents managed <<<")
+    if [ ! -f "$GITIGNORE" ]; then
+        printf '%s\n' "$GITIGNORE_BLOCK" > "$GITIGNORE"
+    else
+        printf '\n\n%s\n' "$GITIGNORE_BLOCK" >> "$GITIGNORE"
+    fi
+fi
+
+# 4. Write marker file with current version
+mkdir -p "$PROJECT_DIR/.claude"
+printf '%s\n' "$TOOLKIT_VERSION" > "$MARKER_FILE"
+
+exit 0

package/hooks/sync-agents.sh

@@ -22,8 +22,9 @@ if [ ! -d "$AGENTS_DIR/.git" ]; then
     exit 0
 fi
 
-# Exit silently if no license
-if [ ! -f "$LICENSE_FILE" ]; then
+# Exit silently if no license found in any path
+ARTHAI_LICENSE_PATH="$REAL_HOME/.arthai/license"
+if [ ! -f "$LICENSE_FILE" ] && [ ! -f "$ARTHAI_LICENSE_PATH" ] && [ -z "${ARTHAI_LICENSE_KEY:-}" ]; then
     exit 0
 fi
 
@@ -108,6 +109,27 @@ fi
 
 # --- Step 2: Check license (with revocation enforcement) ---
 NOW=$(date +%s)
+WORKER_URL="https://license-worker.muddassar-shaikh.workers.dev"
+
+# Resolve license key: ~/.claude-agents/.license takes priority (existing clone-install users),
+# fall back to ~/.arthai/license (npm activate users).
+ARTHAI_LICENSE_KEY_VALUE="${ARTHAI_LICENSE_KEY:-}"
+RESOLVED_KEY=""
+if [ -n "$ARTHAI_LICENSE_KEY_VALUE" ]; then
+    RESOLVED_KEY="$ARTHAI_LICENSE_KEY_VALUE"
+elif [ -f "$LICENSE_FILE" ]; then
+    RESOLVED_KEY=$(cat "$LICENSE_FILE" 2>/dev/null | tr -d '[:space:]' || echo "")
+elif [ -f "$REAL_HOME/.arthai/license" ]; then
+    RESOLVED_KEY=$(cat "$REAL_HOME/.arthai/license" 2>/dev/null | tr -d '[:space:]' || echo "")
+fi
+
+# Validate key format before using it in any JSON payload — prevents JSON injection
+# via a crafted key value in the env var or license file.
+KEY_FORMAT='^ARTH-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}$'
+if [ -n "$RESOLVED_KEY" ] && ! echo "$RESOLVED_KEY" | grep -qE "$KEY_FORMAT"; then
+    # Key has invalid format — don't use it for Worker call or local check
+    RESOLVED_KEY=""
+fi
 
 # Detect if authorized-keys.txt changed in the pull — force re-check if so
 AK_HASH_FILE="$AGENTS_DIR/.ak-hash"
@@ -128,6 +150,49 @@ fi
 # Store current hash for next comparison
 [ -n "$AK_CURRENT_HASH" ] && echo "$AK_CURRENT_HASH" > "$AK_HASH_FILE" 2>/dev/null || true
 
+# validate_with_worker: call Worker /validate with the resolved key.
+# Sets WORKER_RESULT: "valid", "invalid" (definitive), or "network_error".
+validate_with_worker() {
+    local key="$1"
+    if [ -z "$key" ]; then
+        WORKER_RESULT="invalid"
+        return
+    fi
+
+    local payload="{\"key\":\"$key\"}"
+    local response
+    local curl_exit
+
+    # Pass payload via stdin (--data @-) so the key is not visible in the process list
+    response=$(printf '%s' "$payload" | curl \
+        --silent \
+        --max-time 10 \
+        --connect-timeout 5 \
+        --request POST \
+        --header "Content-Type: application/json" \
+        --data "@-" \
+        "$WORKER_URL/validate" 2>/dev/null)
+    curl_exit=$?
+
+    if [ $curl_exit -ne 0 ] || [ -z "$response" ]; then
+        WORKER_RESULT="network_error"
+        return
+    fi
+
+    # Parse "valid" field from JSON — minimal grep-based parse, no jq dependency
+    local valid_field
+    valid_field=$(echo "$response" | grep -o '"valid"[[:space:]]*:[[:space:]]*[a-z]*' | head -1 | grep -o '[a-z]*$')
+
+    if [ "$valid_field" = "true" ]; then
+        WORKER_RESULT="valid"
+    elif [ "$valid_field" = "false" ]; then
+        WORKER_RESULT="invalid"
+    else
+        # Unexpected response format — treat as network error (fail safe)
+        WORKER_RESULT="network_error"
+    fi
+}
+
 LICENSE_VALID=true
 if [ -f "$LICENSE_CACHE" ]; then
     LAST_CHECK=$(cat "$LICENSE_CACHE" 2>/dev/null || echo "0")
@@ -136,19 +201,41 @@ if [ -f "$LICENSE_CACHE" ]; then
         # Cache is fresh, skip validation
         :
     else
-        # Re-validate
-        if ! "$AGENTS_DIR/install.sh" --check-license-only 2>/dev/null; then
+        # Re-validate: try Worker first, fall back to local only on network error
+        validate_with_worker "$RESOLVED_KEY"
+        if [ "$WORKER_RESULT" = "valid" ]; then
+            echo "$NOW" > "$LICENSE_CACHE"
+        elif [ "$WORKER_RESULT" = "invalid" ]; then
+            # Worker says definitively invalid — no local fallback, clear cache
+            rm -f "$LICENSE_CACHE" 2>/dev/null || true
             LICENSE_VALID=false
         else
-            echo "$NOW" > "$LICENSE_CACHE"
+            # Network error — fall back to local authorized-keys.txt check
+            echo "License server unavailable. Retrying with local validation..." >&2
+            if ! "$AGENTS_DIR/install.sh" --check-license-only 2>/dev/null; then
+                LICENSE_VALID=false
+            else
+                echo "$NOW" > "$LICENSE_CACHE"
+            fi
         fi
     fi
 else
-    # First check (or cache was invalidated by AK change)
-    if ! "$AGENTS_DIR/install.sh" --check-license-only 2>/dev/null; then
+    # First check (or cache was invalidated by AK change): try Worker first
+    validate_with_worker "$RESOLVED_KEY"
+    if [ "$WORKER_RESULT" = "valid" ]; then
+        echo "$NOW" > "$LICENSE_CACHE"
+    elif [ "$WORKER_RESULT" = "invalid" ]; then
+        # Worker says definitively invalid — no local fallback, ensure cache stays clear
+        rm -f "$LICENSE_CACHE" 2>/dev/null || true
         LICENSE_VALID=false
     else
-        echo "$NOW" > "$LICENSE_CACHE"
+        # Network error — fall back to local authorized-keys.txt check
+        echo "License server unavailable. Retrying with local validation..." >&2
+        if ! "$AGENTS_DIR/install.sh" --check-license-only 2>/dev/null; then
+            LICENSE_VALID=false
+        else
+            echo "$NOW" > "$LICENSE_CACHE"
+        fi
     fi
 fi
 
@@ -182,12 +269,12 @@ if ! $LICENSE_VALID; then
 
         # Remove CLAUDE.md managed block
         CLAUDEMD="$PROJECT_DIR/CLAUDE.md"
-        if [ -f "$CLAUDEMD" ] && grep -qF "<!-- >>> claude-agents toolkit -->" "$CLAUDEMD" 2>/dev/null; then
+        if [ -f "$CLAUDEMD" ] && grep -qF "<!-- >>> claude-agents toolkit (DO NOT EDIT THIS BLOCK) >>> -->" "$CLAUDEMD" 2>/dev/null; then
             tmp=$(mktemp)
             in_block=false
             skip_next_blank=false
             while IFS= read -r line; do
-                if echo "$line" | grep -qF "<!-- >>> claude-agents toolkit -->"; then
+                if echo "$line" | grep -qF "<!-- >>> claude-agents toolkit (DO NOT EDIT THIS BLOCK) >>> -->"; then
                     in_block=true
                     continue
                 fi
@@ -218,8 +305,8 @@ if ! $LICENSE_VALID; then
         rm -f "$LICENSE_CACHE" 2>/dev/null || true
     fi
 
-    echo "⚠ License revoked. Toolkit has been disabled for this project."
-    echo "  Contact support to renew your license."
+    echo "Invalid license key. Toolkit has been disabled for this project."
+    echo "  Check your key or get one at arthai.dev/pricing"
     exit 0
 fi
 

package/install.sh

@@ -114,7 +114,7 @@ get_category_items() {
             echo "agents/architect.md agents/code-reviewer.md agents/design-studio-create.md agents/design-studio-critique.md agents/design-studio-think.md agents/gtm-expert.md agents/product-manager.md agents/stakeholder-reporter.md agents/meeting-prep.md agents/content-strategist.md agents/user-researcher.md agents/competitive-analyst.md"
             ;;
         development)
-            echo "agents/frontend.md agents/python-backend.md agents/ops.md skills/planning skills/implement skills/fix skills/pr skills/precheck skills/review-pr skills/issue"
+            echo "agents/frontend.md agents/python-backend.md agents/ops.md agents/troubleshooter.md skills/planning skills/implement skills/fix skills/pr skills/precheck skills/review-pr skills/issue"
             ;;
         quality)
             echo "agents/qa.md agents/qa-e2e.md agents/qa-challenger.md agents/qa-test-promoter.md agents/qa-baseline-updater.md agents/qa-domain.md skills/qa skills/ci-fix skills/qa-incident skills/qa-learn"
@@ -126,7 +126,7 @@ get_category_items() {
             echo "hooks/triage-router.sh hooks/session-end.sh"
             ;;
         guardrails)
-            echo "hooks/session-bootstrap.sh hooks/pre-bash-guard.sh hooks/pre-task-context.sh hooks/pre-edit-guard.sh hooks/post-test-summary.sh hooks/post-edit-lint.sh hooks/post-deploy-health.sh hooks/post-diff-test-compare.sh hooks/post-git-state.sh hooks/post-merge-cleanup.sh skills/onboard skills/welcome skills/share skills/templates skills/wizard skills/autopilot skills/continue"
+            echo "hooks/session-bootstrap.sh hooks/pre-bash-guard.sh hooks/pre-task-context.sh hooks/pre-edit-guard.sh hooks/post-test-summary.sh hooks/post-edit-lint.sh hooks/post-deploy-health.sh hooks/post-diff-test-compare.sh hooks/post-git-state.sh hooks/post-merge-cleanup.sh hooks/escalation-guard.sh hooks/project-setup.sh hooks/pre-server-port-guard.sh hooks/post-config-change-restart-reminder.sh hooks/post-server-crash-watch.sh skills/onboard skills/welcome skills/share skills/templates skills/wizard skills/autopilot skills/continue"
             ;;
         railway)
             echo "skills/railway/central-station skills/railway/database skills/railway/deploy skills/railway/deployment skills/railway/domain skills/railway/environment skills/railway/metrics skills/railway/new skills/railway/projects skills/railway/railway-docs skills/railway/service skills/railway/status skills/railway/templates"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arthai/agents",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "AI-powered development toolkit for Claude Code — agents, skills, and hooks",
   "bin": {
     "arthai": "bin/cli.js"

package/portable.manifest

@@ -38,6 +38,7 @@ agent agents/content-strategist.md
 agent agents/user-researcher.md
 agent agents/competitive-analyst.md
 agent agents/ai-consultant.md
+agent agents/troubleshooter.md
 
 # Portable skills (30)
 skill skills/explore.md
@@ -78,7 +79,8 @@ skill-dir skills/solution-architect
 skill-dir skills/deliverable-builder
 skill-dir skills/engagement-tracker
 
-# Portable hooks (13)
+# Portable hooks (14)
+hook hooks/project-setup.sh
 hook hooks/ensure-client-dir.sh
 hook hooks/check-deliverable.sh
 hook hooks/session-summary.sh
@@ -109,4 +111,8 @@ railway-skill-dir skills/railway/railway-docs
 railway-skill-dir skills/railway/service
 railway-skill-dir skills/railway/status
 railway-skill-dir skills/railway/templates
+hook hooks/escalation-guard.sh
+hook hooks/pre-server-port-guard.sh
+hook hooks/post-config-change-restart-reminder.sh
+hook hooks/post-server-crash-watch.sh
 hook hooks/session-end.sh

package/skills/calibrate/SKILL.md

@@ -74,6 +74,26 @@ This goes far deeper than `/scan`. Read **actual source code** to understand HOW
 
 #### Step 1.1: Foundation Scan
 
+**Managed block check (belt-and-suspenders — runs before anything else):**
+
+Check if CLAUDE.md has the toolkit managed block. If missing, inject it before proceeding:
+
+```bash
+MANAGED_START="<!-- >>> claude-agents toolkit (DO NOT EDIT THIS BLOCK) >>> -->"
+if [ -f "$CLAUDE_PROJECT_DIR/CLAUDE.md" ]; then
+    grep -qF "$MANAGED_START" "$CLAUDE_PROJECT_DIR/CLAUDE.md" || echo "MISSING_BLOCK"
+fi
+```
+
+If the managed block is missing:
+1. Read `~/.claude-agents/templates/CLAUDE.md.managed-block` (or `$CLAUDE_PROJECT_DIR/.claude/hooks/../templates/CLAUDE.md.managed-block` if installed via plugin)
+2. Inject it at the end of CLAUDE.md using the markers:
+   - Start: `<!-- >>> claude-agents toolkit (DO NOT EDIT THIS BLOCK) >>> -->`
+   - End: `<!-- <<< claude-agents toolkit <<< -->`
+3. Report: "Injected toolkit managed block into CLAUDE.md (was missing)"
+
+This catches any install path that missed the injection — clone installs, manual setups, or projects that predate the managed block feature.
+
 Run `/scan` first if CLAUDE.md has `<!-- TODO -->` placeholders or doesn't exist. This populates
 the basics (tech stack, services, test commands, infrastructure). Then proceed to deep scan.
 

package/skills/ci-fix/SKILL.md

@@ -162,6 +162,42 @@ gh run view <FAILED_RUN_ID> --log-failed 2>&1 | tail -200
 | **Build failures** | build errors | Read error, fix import/export/config |
 | **Migration** | Alembic/Django errors | Fix migration file |
 | **Dependency** | pip/npm install failures | Fix requirements/package.json |
+| **Toolkit tests** | 15/20-skill-runtime-safety, manifest-coverage | See Toolkit Test Fixes below |
+
+#### Toolkit-Specific Test Fixes (claude-agents repo)
+
+When CI fails on the mechanical test suite (`tests/run.sh`), these are the common failures and auto-fixes:
+
+| Test | Failure message | Root cause | Auto-fix |
+|------|----------------|-----------|----------|
+| `20-skill-runtime-safety` | "regex-unsafe [brackets] in descriptions" | SKILL.md `description:` or `arguments:` field contains `[text]` | Replace `[text]` with `<text>` in the frontmatter field. Brackets break regex matching in Claude Code. |
+| `20-skill-runtime-safety` | "Skills missing required frontmatter fields" | SKILL.md missing `user-invocable: true` or `arguments:` | Add missing field to the YAML frontmatter between `---` markers. Check `git show HEAD~1:path/to/SKILL.md` for the original. |
+| `15-manifest-coverage` | "entries mapped to categories" | New file in `portable.manifest` not listed in any `get_category_items()` category in `install.sh` | Add the manifest entry to the appropriate category in `install.sh:get_category_items()`. |
+| `15-manifest-coverage` | "Install creates all expected symlinks" | New file in `portable.manifest` but install didn't create the symlink | Usually follows from the category mapping fix above. |
+| `15-manifest-coverage` | "Entry counts are consistent" | Mismatch between manifest entries and installed files | Check that new manifest entries have matching source files. |
+| `19-brownfield-assessment` | "classify_file returns IDENTICAL" | Agent fixture is stale after editing an agent `.md` file | Update fixture: `cp agents/{name}.md tests/fixtures/claude-setups/poweruser/.claude/agents/` |
+
+**Auto-fix sequence for toolkit tests:**
+
+```bash
+# 1. Get the exact failure
+gh run view <ID> --log-failed 2>&1 | grep -E "FAIL|✗" | head -5
+
+# 2. For bracket issues — find and fix ALL bracket descriptions
+grep -rn 'description:.*\[' skills/*/SKILL.md
+# Replace [text] with <text> in each match
+
+# 3. For missing frontmatter — compare against last known good
+git show HEAD~1:path/to/SKILL.md | head -6
+# Restore missing fields
+
+# 4. For manifest coverage — add to install.sh categories
+grep "get_category_items" install.sh
+# Add new entries to the right category
+
+# 5. Verify locally before pushing
+bash tests/run.sh --suite 15,20 --scenario a
+```
 
 **Attempt escalation:**
 - Attempt 1: Apply the obvious fix (auto-fix tools, direct code fix)

package/skills/fix/SKILL.md

@@ -478,6 +478,29 @@ Select the right agent based on which layer the bug is in:
 If `.claude/project-profile.md` exists, read it to determine the platform and pick the right agent.
 If `/calibrate` generated custom agents (e.g., `ios-developer.md`), use those for platform-specific bugs.
 
+**4.2b: Escalation protocol for fix agents**
+
+Include this in the implementation agent's prompt:
+
+```
+## When Your Fix Doesn't Work (MANDATORY)
+
+1. After first failed attempt: re-read the root cause analysis from Step 1.
+   Is the root cause correct? If not, go back to Step 1.
+2. After second failed attempt: consult knowledge base:
+   - .claude/knowledge/qa-knowledge/ (error keywords)
+   - .claude/knowledge/shared/conventions.md (project gotchas)
+   - git log --all --grep="<error keyword>" --oneline -10
+3. After third failed attempt: STOP. Do not try another fix.
+   Generate a STUCK REPORT and send to team-lead:
+   - Error: [exact message]
+   - Root cause hypothesis: [from Step 1]
+   - Fix attempts: [1, 2, 3 with results]
+   - KB consultation results: [what you found]
+   - Recommendation: [re-investigate root cause / ask user for X / try different approach]
+4. If a troubleshooter agent is available, team-lead may spawn one.
+```
+
 **Agent prompt includes:**
 ```
 1. Root cause analysis from Step 1