@arthai/agents 1.0.4 → 1.0.6

package/dist/plugins/sentinel/commands/restart.md

@@ -1,68 +1,224 @@
 ---
 name: restart
-description: "Kill and restart local dev servers. Reads service config from CLAUDE.md. Usage: /restart [service]"
+description: "Discover, restart, and validate local dev servers. Auto-detects Docker vs native, checks health, catches crash loops. Usage: /restart <service> <--preflight>"
 ---
 
 # Restart Servers Skill
 
-Kill and restart local dev servers using the configuration from CLAUDE.md.
+Discover how services run, restart them safely, and verify they stay healthy.
 
-## Instructions
+## Phase 1: Discover Services
 
-1. **Read CLAUDE.md** in the project root. Look for the **Local Dev Services** table:
+**First, check CLAUDE.md** for a `Local Dev Services` table:
 
 ```markdown
 ## Local Dev Services
 
-| Service  | Port | Directory | Start Command |
-|----------|------|-----------|---------------|
-| Frontend | 3000 | frontend/ | npm run dev |
-| Backend  | 8000 | backend/  | uvicorn app.main:app --reload --port 8000 |
+| Service  | Type   | Port | Directory | Start Command                         | Health Check    | Depends On |
+|----------|--------|------|-----------|---------------------------------------|-----------------|------------|
+| Postgres | docker | 5432 | —         | docker compose up -d postgres         | pg_isready      | Docker     |
+| Backend  | native | 8000 | backend/  | uvicorn app.main:app --reload         | /api/health     | Postgres   |
+| Frontend | native | 3000 | frontend/ | npm run dev                           | /health         | Backend    |
 ```
 
-If CLAUDE.md doesn't have this section, scan the project:
-- `package.json` scripts → find dev/start commands
-- `requirements.txt` / `pyproject.toml` → look for uvicorn/gunicorn/flask
-- `docker-compose.yml` → extract service ports
-- Common ports: frontend 3000, backend 8000
+**If the table is missing or incomplete, auto-discover** by scanning the repo. Check these files in order:
+
+| File | What to extract |
+|------|-----------------|
+| `docker-compose.yml` / `docker-compose.*.yml` | Service names, ports, images, healthcheck configs, volume mounts. These are **docker** type services. |
+| `Dockerfile` / `Dockerfile.*` | What gets containerized — cross-reference with compose to understand which services are Docker-managed. |
+| `package.json` (root + subdirs) | `scripts.dev`, `scripts.start`, `scripts.serve` → these are **native** Node services. Check `proxy` field for backend port. |
+| `Makefile` / `Procfile` / `Justfile` | Process definitions, often with ports and dependency ordering. |
+| `pyproject.toml` / `requirements.txt` | Python services — look for uvicorn/gunicorn/flask/django in deps. |
+| `.env` / `.env.local` / `.env.example` | Port assignments (`PORT=`, `DATABASE_URL=`, `REDIS_URL=`), required env vars. |
+| `turbo.json` / `nx.json` / `pnpm-workspace.yaml` | Monorepo structure — maps workspace packages to services. |
+
+For each discovered service, determine:
+- **Name**: human-readable (e.g., "Backend API", "Postgres")
+- **Type**: `docker` (managed by docker compose) or `native` (runs directly on host)
+- **Port**: what port it listens on
+- **Directory**: where to `cd` before running the start command
+- **Start command**: exact command to launch it
+- **Health check**: endpoint or command to verify it's running (look for `/health`, `/api/health`, `pg_isready`, `redis-cli ping`, etc.)
+- **Depends on**: other services that must be running first (DB before backend, backend before frontend)
+
+**If discovery is ambiguous, ASK the user.** Specifically ask when:
+- Multiple compose files exist and it's unclear which to use (dev vs prod vs test)
+- A service could be Docker OR native (e.g., Postgres has both a compose entry and a local install)
+- No health check endpoint is obvious — ask what URL or command confirms the service is healthy
+- Port conflicts or unusual port assignments are detected
+- You find services but can't determine the dependency order
+
+Present what you found and ask for confirmation:
+```
+Found 3 services:
+  1. Postgres (docker, port 5432) — via docker-compose.yml
+  2. Backend (native, port 8000) — via backend/pyproject.toml
+  3. Frontend (native, port 3000) — via frontend/package.json
+
+Dependencies: Frontend → Backend → Postgres
+
+Health checks:
+  - Postgres: pg_isready -h localhost -p 5432
+  - Backend: curl localhost:8000/api/health
+  - Frontend: curl localhost:3000
+
+Does this look right? Any corrections?
+```
+
+After confirmation (or if CLAUDE.md table already exists), proceed to Phase 2.
+
+**Update CLAUDE.md**: If services were auto-discovered and the user confirmed, write/update the `Local Dev Services` table in CLAUDE.md so future runs skip discovery.
 
-2. **Kill existing processes** for the target service(s):
+## Phase 2: Pre-flight Validation
 
+Before touching any running processes, validate the environment is ready:
+
+### 2a. Docker check (if any service type is `docker`)
+```bash
+# Is Docker daemon running?
+docker info > /dev/null 2>&1 && echo "Docker: OK" || echo "Docker: NOT RUNNING"
+```
+If Docker is not running, **stop and tell the user**. Don't proceed.
+
+### 2b. Dependency check (for native services)
 ```bash
-# Kill by port
+# Node services — are node_modules installed?
+[ -d "<directory>/node_modules" ] && echo "node_modules: OK" || echo "node_modules: MISSING — run npm install"
+
+# Python services — is the venv active / deps installed?
+[ -f "<directory>/.venv/bin/python" ] && echo "venv: OK" || echo "venv: MISSING"
+```
+
+### 2c. Environment variables
+```bash
+# Check critical env vars exist (read from .env.example or known requirements)
+[ -f "<directory>/.env" ] || [ -f "<directory>/.env.local" ] && echo "env file: OK" || echo "env file: MISSING"
+```
+
+### 2d. Port availability
+```bash
+# Check if port is already in use by a DIFFERENT process than expected
+lsof -ti:<port> 2>/dev/null
+```
+If a port is occupied by an unexpected process, warn the user before killing it.
+
+### 2e. Pre-flight only mode
+If the user ran `/restart --preflight`, **stop here** and report results. Don't restart anything.
+
+## Phase 3: Restart Services (dependency order)
+
+Restart in dependency order — infrastructure first, then backends, then frontends.
+
+### 3a. Stop services (reverse dependency order)
+```bash
+# For native services — kill by port
 lsof -ti:<port> | xargs kill -9 2>/dev/null
 
+# For docker services — stop the specific service
+docker compose stop <service_name>
+
 # Wait for ports to free
 sleep 2
-```
 
-3. **Start each server** in background using the configured start command:
+# Verify port is actually free
+lsof -ti:<port> 2>/dev/null && echo "WARNING: port <port> still occupied" || echo "Port <port>: free"
+```
 
+### 3b. Start services (dependency order)
 ```bash
-# Run in background
-<start_command> &
+# Docker services first
+docker compose up -d <service_name>
+
+# Then native services — run in background
+cd <directory> && <start_command>
 ```
 
-Use `run_in_background: true` on the Bash tool.
+Use `run_in_background: true` on the Bash tool for native services.
+
+**Wait between dependency layers** — don't start the backend until the DB health check passes. Don't start the frontend until the backend health check passes.
+
+## Phase 4: Post-restart Health Validation
+
+This is the critical phase. A single health check is not enough — services can start and then crash seconds later.
 
-4. **Health check** after startup:
+### 4a. Initial health check (per service, in dependency order)
 
 ```bash
-# Check each service
-curl -sf http://localhost:<port>/health > /dev/null 2>&1 && echo "<service>:UP" || echo "<service>:DOWN"
+# HTTP services
+curl -sf http://localhost:<port><health_path> > /dev/null 2>&1 && echo "<service>: UP" || echo "<service>: DOWN"
+
+# Postgres
+pg_isready -h localhost -p <port> 2>/dev/null && echo "Postgres: UP" || echo "Postgres: DOWN"
+
+# Redis
+redis-cli -p <port> ping 2>/dev/null | grep -q PONG && echo "Redis: UP" || echo "Redis: DOWN"
+
+# Docker services
+docker compose ps <service_name> --format '{{.Status}}' | grep -q "Up" && echo "<service>: UP" || echo "<service>: DOWN"
+```
+
+### 4b. Crash loop detection (wait 8 seconds, check again)
+
+```bash
+sleep 8
+
+# Re-check each service
+curl -sf http://localhost:<port><health_path> > /dev/null 2>&1 && echo "<service>: STABLE" || echo "<service>: CRASHED"
+
+# For native services — is the process still running?
+lsof -ti:<port> > /dev/null 2>&1 && echo "<service> process: alive" || echo "<service> process: GONE"
 ```
 
-5. **Report** status of all servers.
+If a service is down on the second check:
+1. **Check logs** — read the last 30 lines of output for error messages
+2. **Report the failure clearly** with the error
+3. **Do NOT retry automatically** — tell the user what went wrong
+
+### 4c. Final status report
+
+```
+✅ Restart complete
+
+| Service  | Type   | Port | Status  |
+|----------|--------|------|---------|
+| Postgres | docker | 5432 | STABLE  |
+| Backend  | native | 8000 | STABLE  |
+| Frontend | native | 3000 | STABLE  |
+
+All services healthy after 10s stability check.
+```
+
+Or if something failed:
+
+```
+⚠️ Restart partial — 1 service unhealthy
+
+| Service  | Type   | Port | Status  |
+|----------|--------|------|---------|
+| Postgres | docker | 5432 | STABLE  |
+| Backend  | native | 8000 | CRASHED |
+| Frontend | native | 3000 | SKIPPED |
+
+Backend crashed after startup. Last error:
+  ModuleNotFoundError: No module named 'sqlalchemy'
+
+Fix: Run `pip install -r requirements.txt` in backend/ and retry.
+Frontend was skipped because it depends on Backend.
+```
 
 ## Argument Patterns
 
 | User Input | Action |
 |-----------|--------|
-| `/restart` (no args) | Kill and restart all configured servers |
-| `/restart backend` | Kill and restart only the backend service |
-| `/restart frontend` | Kill and restart only the frontend service |
-| `/restart <service>` | Kill and restart the named service |
+| `/restart` (no args) | Discover → validate → restart all services |
+| `/restart backend` | Restart only the named service (and its dependencies if they're down) |
+| `/restart --preflight` | Discover and validate only — don't restart anything |
 
-## If CLAUDE.md Is Missing Service Config
+## Key Principles
 
-Report: "No Local Dev Services table found in CLAUDE.md. Add a table with Service, Port, Directory, and Start Command columns. Or specify the services manually."
+1. **Never guess** — if you can't determine how a service runs, ask
+2. **Dependency order matters** — always start infra → backend → frontend
+3. **One health check isn't enough** — check twice with a gap to catch crash loops
+4. **Report errors with context** — show the actual log output, not just "DOWN"
+5. **Don't retry blindly** — if a service crashes, diagnose and report, don't loop

package/dist/plugins/sentinel/hooks/escalation-guard.sh

@@ -0,0 +1,177 @@
+#!/bin/bash
+# PostToolUse hook (Bash): Circuit breaker for consecutive failures.
+# Tracks failed commands by error signature. After 3 failures with the same
+# signature, forces KB consultation and outputs a structured stuck report.
+#
+# Uses .claude/.escalation-state.json to persist state across tool calls.
+# stdout is injected as context.
+
+set -euo pipefail
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+STATE_FILE="$PROJECT_DIR/.claude/.escalation-state.json"
+CIRCUIT_BREAKER_THRESHOLD=3
+
+# Extract the command and exit code
+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
+
+EXIT_CODE="${CLAUDE_TOOL_RESULT_EXIT_CODE:-0}"
+
+[ -z "$COMMAND" ] && exit 0
+
+# ---------------------------------------------------------------------------
+# Skip tracking for non-failing commands and read-only commands
+# ---------------------------------------------------------------------------
+
+# Success — reset state if we had failures for this signature
+if [ "$EXIT_CODE" = "0" ]; then
+    if [ -f "$STATE_FILE" ]; then
+        # Clear state on success — the issue is resolved
+        python3 -c "
+import json, sys
+try:
+    with open('$STATE_FILE', 'r') as f:
+        state = json.load(f)
+    # Reset consecutive failures
+    state['consecutive_failures'] = 0
+    state['last_error_signature'] = ''
+    state['attempts'] = []
+    with open('$STATE_FILE', 'w') as f:
+        json.dump(state, f, indent=2)
+except:
+    pass
+" 2>/dev/null || true
+    fi
+    exit 0
+fi
+
+# Skip tracking for read-only commands (ls, cat, grep, git status, etc.)
+if echo "$COMMAND" | grep -qE '^\s*(ls|cat|head|tail|grep|rg|git\s+(status|log|diff|show|branch)|echo|pwd|which|type|file|wc)\b'; then
+    exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Compute error signature from command + exit code
+# ---------------------------------------------------------------------------
+
+# Get the last few lines of error output (from CLAUDE_TOOL_RESULT_STDERR or infer)
+ERROR_OUTPUT="${CLAUDE_TOOL_RESULT_STDERR:-}"
+if [ -z "$ERROR_OUTPUT" ] && [ -n "${CLAUDE_TOOL_RESULT_STDOUT:-}" ]; then
+    # Sometimes errors go to stdout (e.g., npm, python)
+    ERROR_OUTPUT=$(echo "${CLAUDE_TOOL_RESULT_STDOUT:-}" | tail -5)
+fi
+
+# Compute signature: hash of (command_base + error_pattern)
+# Strip variable parts (paths, timestamps, PIDs) for stable signatures
+COMMAND_BASE=$(echo "$COMMAND" | awk '{print $1, $2}')
+ERROR_PATTERN=$(echo "$ERROR_OUTPUT" | sed 's/[0-9]\{4,\}//g; s|/[^ ]*||g' | head -3)
+SIGNATURE=$(echo "${COMMAND_BASE}:${ERROR_PATTERN}" | shasum -a 256 | cut -c1-16)
+
+# ---------------------------------------------------------------------------
+# Update state and check circuit breaker
+# ---------------------------------------------------------------------------
+
+RESULT=$(python3 -c "
+import json, sys, time, os
+
+state_file = '$STATE_FILE'
+signature = '$SIGNATURE'
+command = '''$COMMAND'''[:200]
+error = '''$ERROR_OUTPUT'''[:500]
+threshold = $CIRCUIT_BREAKER_THRESHOLD
+
+# Load or create state
+state = {'consecutive_failures': 0, 'last_error_signature': '', 'attempts': [], 'total_circuits_tripped': 0}
+try:
+    if os.path.exists(state_file):
+        with open(state_file, 'r') as f:
+            state = json.load(f)
+except:
+    pass
+
+# Check if same signature as last failure
+if state.get('last_error_signature') == signature:
+    state['consecutive_failures'] = state.get('consecutive_failures', 0) + 1
+else:
+    # New error signature — reset counter
+    state['consecutive_failures'] = 1
+    state['attempts'] = []
+
+state['last_error_signature'] = signature
+state['attempts'] = (state.get('attempts', []) + [{'command': command, 'error': error[:200], 'time': time.time()}])[-5:]
+
+# Check threshold
+tripped = state['consecutive_failures'] >= threshold
+
+if tripped:
+    state['total_circuits_tripped'] = state.get('total_circuits_tripped', 0) + 1
+
+# Save state
+os.makedirs(os.path.dirname(state_file), exist_ok=True)
+with open(state_file, 'w') as f:
+    json.dump(state, f, indent=2)
+
+# Output: tripped|count|attempts_summary
+attempts_summary = ' / '.join([a.get('command', '')[:60] for a in state.get('attempts', [])])
+print(f\"{'TRIPPED' if tripped else 'OK'}|{state['consecutive_failures']}|{attempts_summary}\")
+" 2>/dev/null) || exit 0
+
+STATUS=$(echo "$RESULT" | cut -d'|' -f1)
+COUNT=$(echo "$RESULT" | cut -d'|' -f2)
+ATTEMPTS=$(echo "$RESULT" | cut -d'|' -f3-)
+
+# ---------------------------------------------------------------------------
+# If not tripped, show warning at count 2
+# ---------------------------------------------------------------------------
+
+if [ "$STATUS" = "OK" ] && [ "$COUNT" = "2" ]; then
+    echo "ESCALATION WARNING: 2 consecutive failures with same error pattern."
+    echo "One more failure triggers the circuit breaker."
+    echo "Before retrying: check .claude/knowledge/ for known solutions."
+    exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Circuit breaker tripped — inject structured stuck report
+# ---------------------------------------------------------------------------
+
+if [ "$STATUS" = "TRIPPED" ]; then
+    echo "CIRCUIT BREAKER TRIPPED — $COUNT consecutive failures with same error signature."
+    echo ""
+    echo "STOP. Do not attempt another fix without completing these steps:"
+    echo ""
+    echo "1. CONSULT KNOWLEDGE BASE:"
+    echo "   - Read .claude/knowledge/shared/conventions.md"
+    echo "   - Read .claude/knowledge/qa-knowledge/ (search for error keywords)"
+    echo "   - Run: git log --all --grep='fix:' --oneline -10"
+    echo ""
+    echo "2. GATHER EVIDENCE (if not already done):"
+    echo "   - Read full error output (not just the last line)"
+    echo "   - Check environment: env vars, ports (lsof), processes (ps), disk (df)"
+    echo "   - Check dependencies: node_modules, venv, Docker containers"
+    echo ""
+    echo "3. IF STILL STUCK — use this template to ask for help:"
+    echo "   ┌─────────────────────────────────────────────────────────┐"
+    echo "   │ STUCK REPORT                                           │"
+    echo "   │                                                        │"
+    echo "   │ Error: [exact error message]                           │"
+    echo "   │ Context: [what I was doing]                            │"
+    echo "   │ Attempts:                                              │"
+    echo "   │   1. [what I tried] -> [result]                        │"
+    echo "   │   2. [what I tried] -> [result]                        │"
+    echo "   │   3. [what I tried] -> [result]                        │"
+    echo "   │ Evidence: [logs, state, KB search results]             │"
+    echo "   │ What I need: [access/data/decision]                    │"
+    echo "   │ My recommendation: [option A because X]                │"
+    echo "   └─────────────────────────────────────────────────────────┘"
+    echo ""
+    echo "4. IF ON A TEAM — escalate to troubleshooter agent or ask a teammate."
+    echo "   If solo — present the stuck report to the user with options."
+    echo ""
+    echo "Previous attempts: $ATTEMPTS"
+fi
+
+exit 0

package/dist/plugins/sentinel/hooks/hooks.json

@@ -1,5 +1,17 @@
 {
   "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/project-setup.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
     "PostToolUse": [
       {
         "matcher": "Bash",
@@ -20,6 +32,58 @@
             "timeout": 5
           }
         ]
+      },
+      {
+        "matcher": "Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-config-change-restart-reminder.sh",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-config-change-restart-reminder.sh",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-server-crash-watch.sh",
+            "timeout": 15
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/escalation-guard.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre-server-port-guard.sh",
+            "timeout": 5
+          }
+        ]
       }
     ]
   }

package/dist/plugins/sentinel/hooks/post-config-change-restart-reminder.sh

@@ -0,0 +1,86 @@
+#!/bin/bash
+# PostToolUse hook (Edit/Write): Remind to restart after config file changes.
+# Detects modifications to docker-compose, .env, Dockerfile, nginx, and port
+# configs, then reminds the user that a /restart may be needed.
+#
+# stdout is injected as context.
+
+set -euo pipefail
+
+# Extract the file path from tool input
+FILE_PATH="${CLAUDE_TOOL_INPUT_FILE_PATH:-}"
+if [ -z "$FILE_PATH" ] && [ -n "${CLAUDE_TOOL_INPUT:-}" ]; then
+    FILE_PATH=$(echo "$CLAUDE_TOOL_INPUT" | python3 -c "import json,sys; print(json.load(sys.stdin).get('file_path',''))" 2>/dev/null) || true
+fi
+
+[ -z "$FILE_PATH" ] && exit 0
+
+# ---------------------------------------------------------------------------
+# Check if the modified file is a config that affects running services
+# ---------------------------------------------------------------------------
+
+BASENAME=$(basename "$FILE_PATH")
+NEEDS_RESTART=false
+REASON=""
+
+case "$BASENAME" in
+    docker-compose.yml|docker-compose.yaml|docker-compose.*.yml|docker-compose.*.yaml|compose.yml|compose.yaml)
+        NEEDS_RESTART=true
+        REASON="Docker Compose config changed — containers may need rebuilding"
+        ;;
+    .env|.env.local|.env.development|.env.production)
+        NEEDS_RESTART=true
+        REASON="Environment variables changed — servers need restart to pick up new values"
+        ;;
+    Dockerfile|Dockerfile.*)
+        NEEDS_RESTART=true
+        REASON="Dockerfile changed — container needs rebuilding"
+        ;;
+    nginx.conf|nginx.*.conf)
+        NEEDS_RESTART=true
+        REASON="Nginx config changed — needs reload"
+        ;;
+    next.config.js|next.config.mjs|next.config.ts)
+        NEEDS_RESTART=true
+        REASON="Next.js config changed — dev server needs restart"
+        ;;
+    vite.config.js|vite.config.ts|vite.config.mjs)
+        NEEDS_RESTART=true
+        REASON="Vite config changed — dev server needs restart"
+        ;;
+    tsconfig.json|tsconfig.*.json)
+        NEEDS_RESTART=true
+        REASON="TypeScript config changed — dev server may need restart"
+        ;;
+    webpack.config.js|webpack.config.ts)
+        NEEDS_RESTART=true
+        REASON="Webpack config changed — dev server needs restart"
+        ;;
+    package.json)
+        NEEDS_RESTART=true
+        REASON="package.json changed — may need npm install + restart"
+        ;;
+    pyproject.toml|setup.py|setup.cfg|requirements.txt|requirements.*.txt)
+        NEEDS_RESTART=true
+        REASON="Python dependencies changed — may need pip install + restart"
+        ;;
+    Procfile|Procfile.*)
+        NEEDS_RESTART=true
+        REASON="Procfile changed — process definitions updated"
+        ;;
+esac
+
+# Also check for port-related changes in any file
+if [ "$NEEDS_RESTART" = "false" ]; then
+    # Check if the file path contains common config directories
+    if echo "$FILE_PATH" | grep -qE '(config/|conf/|\.config)'; then
+        NEEDS_RESTART=true
+        REASON="Config file modified — services may need restart"
+    fi
+fi
+
+$NEEDS_RESTART || exit 0
+
+echo "CONFIG CHANGED — $REASON. Run /restart to apply."
+
+exit 0