@cyperx/clawforge 1.2.0

package/bin/spawn-agent.sh

@@ -0,0 +1,190 @@
+#!/usr/bin/env bash
+# spawn-agent.sh — Module 2: Create worktree + tmux + launch coding agent
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "${SCRIPT_DIR}/../lib/common.sh"
+
+# ── Help ───────────────────────────────────────────────────────────────
+usage() {
+  cat <<EOF
+Usage: spawn-agent.sh --repo <path> --branch <name> --task <description> [options]
+
+Options:
+  --repo <path>        Path to the git repository (required)
+  --branch <name>      Branch name to create (required)
+  --task <description> Task description for the agent (required)
+  --agent <name>       Agent to use: claude or codex (default: auto-detect)
+  --model <model>      Model override
+  --effort <level>     Effort level: high, medium, low (default: high)
+  --dry-run            Do everything except launch the agent
+  --help               Show this help
+EOF
+}
+
+# ── Parse args ─────────────────────────────────────────────────────────
+REPO="" BRANCH="" TASK="" AGENT="" MODEL="" EFFORT="" DRY_RUN=false
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --repo)     REPO="$2"; shift 2 ;;
+    --branch)   BRANCH="$2"; shift 2 ;;
+    --task)     TASK="$2"; shift 2 ;;
+    --agent)    AGENT="$2"; shift 2 ;;
+    --model)    MODEL="$2"; shift 2 ;;
+    --effort)   EFFORT="$2"; shift 2 ;;
+    --dry-run)  DRY_RUN=true; shift ;;
+    --help|-h)  usage; exit 0 ;;
+    *)          log_error "Unknown option: $1"; usage; exit 1 ;;
+  esac
+done
+
+# ── Validate ───────────────────────────────────────────────────────────
+[[ -z "$REPO" ]]   && { log_error "--repo is required"; usage; exit 1; }
+[[ -z "$BRANCH" ]] && { log_error "--branch is required"; usage; exit 1; }
+[[ -z "$TASK" ]]   && { log_error "--task is required"; usage; exit 1; }
+[[ -d "$REPO/.git" ]] || [[ -f "$REPO/.git" ]] || { log_error "Not a git repo: $REPO"; exit 1; }
+
+# ── Resolve settings ──────────────────────────────────────────────────
+RESOLVED_AGENT=$(detect_agent "${AGENT:-}")
+EFFORT="${EFFORT:-$(config_get default_effort high)}"
+
+if [[ -z "$MODEL" ]]; then
+  if [[ "$RESOLVED_AGENT" == "claude" ]]; then
+    MODEL=$(config_get default_model_claude "claude-sonnet-4-5")
+  else
+    MODEL=$(config_get default_model_codex "gpt-5.3-codex")
+  fi
+fi
+
+SAFE_BRANCH=$(sanitize_branch "$BRANCH")
+WORKTREE_BASE=$(config_get worktree_base "../worktrees")
+REPO_ABS=$(cd "$REPO" && pwd)
+
+# Resolve worktree path relative to repo
+if [[ "$WORKTREE_BASE" == ../* ]]; then
+  WORKTREE_DIR="$(cd "$REPO_ABS" && cd .. && pwd)/worktrees/${SAFE_BRANCH}"
+else
+  WORKTREE_DIR="${WORKTREE_BASE}/${SAFE_BRANCH}"
+fi
+
+TMUX_SESSION="agent-${SAFE_BRANCH}"
+MAX_RETRIES=$(config_get max_retries 3)
+
+log_info "Spawning agent: $RESOLVED_AGENT ($MODEL)"
+log_info "Repo: $REPO_ABS"
+log_info "Branch: $BRANCH → worktree: $WORKTREE_DIR"
+log_info "tmux session: $TMUX_SESSION"
+
+# ── Step 1: Create worktree ───────────────────────────────────────────
+if [[ -d "$WORKTREE_DIR" ]]; then
+  log_warn "Worktree already exists: $WORKTREE_DIR"
+else
+  log_info "Creating worktree..."
+  mkdir -p "$(dirname "$WORKTREE_DIR")"
+  git -C "$REPO_ABS" worktree add "$WORKTREE_DIR" -b "$BRANCH" 2>/dev/null || \
+    git -C "$REPO_ABS" worktree add "$WORKTREE_DIR" "$BRANCH" 2>/dev/null || \
+    git -C "$REPO_ABS" worktree add "$WORKTREE_DIR" -B "$BRANCH"
+fi
+
+# ── Step 2: Install deps ──────────────────────────────────────────────
+if [[ -f "$WORKTREE_DIR/package.json" ]]; then
+  log_info "Installing dependencies..."
+  if ! $DRY_RUN; then
+    if [[ -f "$WORKTREE_DIR/pnpm-lock.yaml" ]]; then
+      (cd "$WORKTREE_DIR" && pnpm install --frozen-lockfile 2>/dev/null || pnpm install) || true
+    else
+      (cd "$WORKTREE_DIR" && npm install) || true
+    fi
+  else
+    log_info "[dry-run] Would install deps in $WORKTREE_DIR"
+  fi
+fi
+
+# ── Step 3: Build prompt (with memory injection) ─────────────────────
+MEMORY_SECTION=""
+MEMORY_BASE="$HOME/.clawforge/memory"
+REPO_NAME=$(basename "$REPO_ABS")
+# Try git remote for repo name
+REMOTE_URL=$(git -C "$REPO_ABS" config --get remote.origin.url 2>/dev/null || true)
+[[ -n "$REMOTE_URL" ]] && REPO_NAME=$(basename "$REMOTE_URL" .git)
+MEMORY_FILE="${MEMORY_BASE}/${REPO_NAME}.jsonl"
+
+if [[ -f "$MEMORY_FILE" ]] && [[ -s "$MEMORY_FILE" ]]; then
+  MEMORIES=$(tail -20 "$MEMORY_FILE" | jq -r '.text' 2>/dev/null || true)
+  if [[ -n "$MEMORIES" ]]; then
+    MEMORY_SECTION="
+## Project Notes
+$MEMORIES
+"
+    log_info "Injected $(echo "$MEMORIES" | wc -l | tr -d ' ') memories into prompt"
+  fi
+fi
+
+FULL_PROMPT="${MEMORY_SECTION}$TASK
+
+When complete:
+1. Commit your changes with a descriptive message
+2. Push the branch: git push origin $BRANCH
+3. Create a PR: gh pr create --fill --base main"
+
+# ── Step 4: Register task ─────────────────────────────────────────────
+NOW=$(epoch_ms)
+TASK_JSON=$(jq -n \
+  --arg id "$SAFE_BRANCH" \
+  --arg tmux "$TMUX_SESSION" \
+  --arg agent "$RESOLVED_AGENT" \
+  --arg model "$MODEL" \
+  --arg desc "$TASK" \
+  --arg repo "$REPO_ABS" \
+  --arg wt "$WORKTREE_DIR" \
+  --arg branch "$BRANCH" \
+  --argjson started "$NOW" \
+  --argjson maxRetries "$MAX_RETRIES" \
+  '{
+    id: $id,
+    tmuxSession: $tmux,
+    agent: $agent,
+    model: $model,
+    description: $desc,
+    repo: $repo,
+    worktree: $wt,
+    branch: $branch,
+    startedAt: $started,
+    status: "spawned",
+    retries: 0,
+    maxRetries: $maxRetries,
+    pr: null,
+    checks: {},
+    completedAt: null,
+    note: null
+  }')
+
+registry_add "$TASK_JSON"
+
+# ── Step 5: Launch agent in tmux ──────────────────────────────────────
+if $DRY_RUN; then
+  log_info "[dry-run] Would create tmux session '$TMUX_SESSION' and launch $RESOLVED_AGENT"
+  log_info "[dry-run] Working directory: $WORKTREE_DIR"
+  log_info "[dry-run] Prompt: $(echo "$FULL_PROMPT" | head -1)..."
+  registry_update "$SAFE_BRANCH" "status" '"running"'
+  echo "$TASK_JSON"
+  exit 0
+fi
+
+# Kill existing session if present (idempotent)
+tmux kill-session -t "$TMUX_SESSION" 2>/dev/null || true
+
+# Build agent command
+if [[ "$RESOLVED_AGENT" == "claude" ]]; then
+  AGENT_CMD="claude --model ${MODEL} --dangerously-skip-permissions -p \"$(echo "$FULL_PROMPT" | sed 's/"/\\"/g')\""
+elif [[ "$RESOLVED_AGENT" == "codex" ]]; then
+  AGENT_CMD="codex --model ${MODEL} --dangerously-bypass-approvals-and-sandbox \"$(echo "$FULL_PROMPT" | sed 's/"/\\"/g')\""
+fi
+
+# Create tmux session and launch
+tmux new-session -d -s "$TMUX_SESSION" -c "$WORKTREE_DIR" "$AGENT_CMD"
+registry_update "$SAFE_BRANCH" "status" '"running"'
+
+log_info "Agent spawned successfully in tmux session: $TMUX_SESSION"
+echo "$TASK_JSON"

package/bin/sprint.sh

@@ -0,0 +1,320 @@
+#!/usr/bin/env bash
+# sprint.sh — Sprint mode: single agent, full dev cycle
+# Usage: clawforge sprint [repo] "<task>" [flags]
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "${SCRIPT_DIR}/../lib/common.sh"
+source "${SCRIPT_DIR}/routing.sh"
+
+# ── Help ───────────────────────────────────────────────────────────────
+usage() {
+  cat <<EOF
+Usage: clawforge sprint [repo] "<task>" [flags]
+
+The workhorse. Single agent, full dev cycle.
+
+Arguments:
+  [repo]               Path to git repository (default: auto-detect from cwd)
+  "<task>"             Task description (required)
+
+Flags:
+  --quick              Patch mode: auto-branch, auto-merge, skip review, targeted tests
+  --branch <name>      Override auto-generated branch name
+  --agent <name>       Agent to use: claude or codex (default: auto-detect)
+  --model <model>      Model override
+  --routing <strategy>  Model routing: auto, cheap, or quality (--model overrides)
+  --auto-merge         Merge automatically if CI + review pass
+  --template <name>    Apply a task template (overrides defaults, CLI flags override template)
+  --ci-loop            Enable CI auto-fix feedback loop
+  --max-ci-retries <N> Max CI auto-fix retries (default: 3)
+  --budget <dollars>   Kill agent if cost exceeds budget
+  --json               Output structured JSON
+  --notify             Send OpenClaw event on completion
+  --webhook <url>      POST completion payload to URL
+  --auto-clean         Clean up worktree+session on completion
+  --timeout <minutes>  Kill agent after N minutes
+  --dry-run            Preview what would happen
+  --help               Show this help
+
+Examples:
+  clawforge sprint "Add JWT authentication middleware"
+  clawforge sprint ~/github/api "Fix null pointer in UserService" --quick
+  clawforge sprint "Add rate limiter" --branch feat/rate-limit --agent codex
+  clawforge sprint --template refactor "Refactor auth module"
+  clawforge sprint "Fix login bug" --ci-loop --budget 5.00
+EOF
+}
+
+# ── Parse args ────────────────────────────────────────────────────────
+REPO="" TASK="" BRANCH="" AGENT="" MODEL="" QUICK=false AUTO_MERGE=false DRY_RUN=false
+TEMPLATE="" CI_LOOP=false MAX_CI_RETRIES=3 BUDGET="" JSON_OUTPUT=false NOTIFY=false WEBHOOK="" ROUTING=""
+AUTO_CLEAN=false
+TIMEOUT_MIN=""
+POSITIONAL=()
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --quick)          QUICK=true; shift ;;
+    --branch)         BRANCH="$2"; shift 2 ;;
+    --agent)          AGENT="$2"; shift 2 ;;
+    --model)          MODEL="$2"; shift 2 ;;
+    --routing)        ROUTING="$2"; shift 2 ;;
+    --auto-clean)     AUTO_CLEAN=true; shift ;;
+    --timeout)        TIMEOUT_MIN="$2"; shift 2 ;;
+    --auto-merge)     AUTO_MERGE=true; shift ;;
+    --template)       TEMPLATE="$2"; shift 2 ;;
+    --ci-loop)        CI_LOOP=true; shift ;;
+    --max-ci-retries) MAX_CI_RETRIES="$2"; shift 2 ;;
+    --budget)         BUDGET="$2"; shift 2 ;;
+    --json)           JSON_OUTPUT=true; shift ;;
+    --notify)         NOTIFY=true; shift ;;
+    --webhook)        WEBHOOK="$2"; shift 2 ;;
+    --dry-run)        DRY_RUN=true; shift ;;
+    --help|-h)        usage; exit 0 ;;
+    --*)              log_error "Unknown option: $1"; usage; exit 1 ;;
+    *)                POSITIONAL+=("$1"); shift ;;
+  esac
+done
+
+# ── Apply template (template < CLI flags) ─────────────────────────────
+if [[ -n "$TEMPLATE" ]]; then
+  TMPL_FILE=""
+  if [[ -f "${CLAWFORGE_DIR}/lib/templates/${TEMPLATE}.json" ]]; then
+    TMPL_FILE="${CLAWFORGE_DIR}/lib/templates/${TEMPLATE}.json"
+  elif [[ -f "${HOME}/.clawforge/templates/${TEMPLATE}.json" ]]; then
+    TMPL_FILE="${HOME}/.clawforge/templates/${TEMPLATE}.json"
+  else
+    log_error "Template '$TEMPLATE' not found"; exit 1
+  fi
+  log_info "Applying template: $TEMPLATE"
+  # Template sets defaults; CLI flags override
+  TMPL_AUTO_MERGE=$(jq -r '.autoMerge // false' "$TMPL_FILE")
+  TMPL_CI_LOOP=$(jq -r '.ciLoop // false' "$TMPL_FILE")
+  TMPL_QUICK=$(jq -r '.quick // false' "$TMPL_FILE")
+  # Only apply template values if CLI didn't set them explicitly
+  [[ "$TMPL_AUTO_MERGE" == "true" ]] && AUTO_MERGE=true
+  [[ "$TMPL_CI_LOOP" == "true" ]] && CI_LOOP=true
+  [[ "$TMPL_QUICK" == "true" ]] && QUICK=true
+fi
+
+# Parse positional args: [repo] "<task>"
+case ${#POSITIONAL[@]} in
+  0) log_error "Task description is required"; usage; exit 1 ;;
+  1) TASK="${POSITIONAL[0]}" ;;
+  2) REPO="${POSITIONAL[0]}"; TASK="${POSITIONAL[1]}" ;;
+  *) log_error "Too many positional arguments"; usage; exit 1 ;;
+esac
+
+# ── Resolve repo ──────────────────────────────────────────────────────
+if [[ -z "$REPO" ]]; then
+  REPO=$(detect_repo) || { log_error "No --repo and no git repo found from cwd"; exit 1; }
+fi
+REPO_ABS=$(cd "$REPO" && pwd)
+
+# ── Resolve branch ────────────────────────────────────────────────────
+if [[ -z "$BRANCH" ]]; then
+  if $QUICK; then
+    BRANCH=$(auto_branch_name "quick" "$TASK" "$REPO_ABS")
+  else
+    BRANCH=$(auto_branch_name "sprint" "$TASK" "$REPO_ABS")
+  fi
+fi
+
+# ── Quick mode overrides ─────────────────────────────────────────────
+if $QUICK; then
+  AUTO_MERGE=true
+fi
+
+# ── Resolve agent + model ────────────────────────────────────────────
+RESOLVED_AGENT=$(detect_agent "${AGENT:-}")
+MODEL_OVERRIDE="$MODEL"  # preserve explicit --model
+if [[ -z "$MODEL" ]]; then
+  if [[ "$RESOLVED_AGENT" == "claude" ]]; then
+    MODEL=$(config_get default_model_claude "claude-sonnet-4-5")
+  else
+    MODEL=$(config_get default_model_codex "gpt-5.3-codex")
+  fi
+fi
+
+# ── Load routing ────────────────────────────────────────────────────
+if [[ -n "$ROUTING" ]]; then
+  load_routing "$ROUTING"
+  log_info "Routing: strategy=$ROUTING"
+fi
+
+# ── Assign short ID ──────────────────────────────────────────────────
+SHORT_ID=$(_next_short_id)
+SAFE_BRANCH=$(sanitize_branch "$BRANCH")
+MODE="sprint"
+$QUICK && MODE="quick"
+
+# ── Log intent ────────────────────────────────────────────────────────
+log_info "Sprint mode ($MODE): $TASK"
+log_info "Repo: $REPO_ABS"
+log_info "Branch: $BRANCH (short ID: #$SHORT_ID)"
+log_info "Agent: $RESOLVED_AGENT ($MODEL)"
+$QUICK && log_info "Quick mode: auto-merge=true, skip-review=true"
+$AUTO_MERGE && log_info "Auto-merge enabled"
+
+# ── Dry-run ───────────────────────────────────────────────────────────
+if $DRY_RUN; then
+  echo "=== Sprint Dry Run ==="
+  echo "  Mode:       $MODE"
+  echo "  Task:       $TASK"
+  echo "  Repo:       $REPO_ABS"
+  echo "  Branch:     $BRANCH"
+  echo "  Agent:      $RESOLVED_AGENT ($MODEL)"
+  echo "  Short ID:   #$SHORT_ID"
+  echo "  Auto-merge: $AUTO_MERGE"
+  echo "  Quick:      $QUICK"
+  [[ -n "$ROUTING" ]] && echo "  Routing:    $ROUTING"
+  echo ""
+  echo "Would execute:"
+  echo "  1. Scope task"
+  echo "  2. Create worktree + spawn agent"
+  if $QUICK; then
+    echo "  3. Auto-merge on CI pass (skip review)"
+  else
+    echo "  3. Wait for PR → review → merge"
+  fi
+  exit 0
+fi
+
+# ── Escalation check ──────────────────────────────────────────────────
+# Quick mode: detect if task looks too complex for a patch
+if $QUICK; then
+  WORD_COUNT=$(echo "$TASK" | wc -w | tr -d ' ')
+  if [[ "$WORD_COUNT" -gt 20 ]]; then
+    log_warn "This task description is long for --quick mode."
+    echo "  Tip: This looks bigger than a patch. Consider running as full sprint:"
+    echo "        clawforge sprint $(printf '%q' "$TASK")"
+  fi
+fi
+
+# ── Step 1: Scope ─────────────────────────────────────────────────────
+log_info "Step 1: Scoping task..."
+# Apply routing model for scope phase (--model overrides routing)
+if [[ -n "$ROUTING" && -z "$MODEL_OVERRIDE" ]]; then
+  SCOPE_MODEL=$(get_model_for_phase "scope")
+  [[ -n "$SCOPE_MODEL" ]] && log_info "Routing: scope → $SCOPE_MODEL"
+fi
+PROMPT=$("${SCRIPT_DIR}/scope-task.sh" --task "$TASK" 2>/dev/null || echo "$TASK")
+
+# ── Step 2: Spawn ─────────────────────────────────────────────────────
+# Disk space check
+disk_check "$REPO_ABS" || { log_error "Aborting due to low disk space"; exit 1; }
+
+log_info "Step 2: Spawning agent..."
+# Apply routing model for implement phase (--model overrides routing)
+SPAWN_MODEL="$MODEL"
+if [[ -n "$ROUTING" && -z "$MODEL_OVERRIDE" ]]; then
+  IMPL_MODEL=$(get_model_for_phase "implement")
+  [[ -n "$IMPL_MODEL" ]] && SPAWN_MODEL="$IMPL_MODEL" && log_info "Routing: implement → $IMPL_MODEL"
+fi
+SPAWN_ARGS=(--repo "$REPO_ABS" --branch "$BRANCH" --task "$PROMPT")
+[[ -n "${AGENT:-}" ]] && SPAWN_ARGS+=(--agent "$AGENT")
+[[ -n "${SPAWN_MODEL:-}" ]] && SPAWN_ARGS+=(--model "$SPAWN_MODEL")
+
+TASK_JSON=$("${SCRIPT_DIR}/spawn-agent.sh" "${SPAWN_ARGS[@]}" 2>/dev/null || true)
+
+# ── Step 3: Enhance registry with mode data ───────────────────────────
+registry_update "$SAFE_BRANCH" "short_id" "$SHORT_ID"
+registry_update "$SAFE_BRANCH" "mode" "\"$MODE\""
+registry_update "$SAFE_BRANCH" "files_touched" '[]'
+registry_update "$SAFE_BRANCH" "ci_retries" '0'
+registry_update "$SAFE_BRANCH" "max_ci_retries" "$MAX_CI_RETRIES"
+$AUTO_MERGE && registry_update "$SAFE_BRANCH" "auto_merge" 'true'
+$QUICK && registry_update "$SAFE_BRANCH" "skip_review" 'true'
+$CI_LOOP && registry_update "$SAFE_BRANCH" "ci_loop" 'true'
+[[ -n "$BUDGET" ]] && registry_update "$SAFE_BRANCH" "budget" "$BUDGET"
+
+
+# ── Signal trap cleanup ──────────────────────────────────────────────
+WATCHDOG_PID=""
+_sprint_cleanup() {
+  log_warn "Sprint interrupted. Cleaning up..."
+  registry_update "$SAFE_BRANCH" "status" '"cancelled"'
+  if tmux has-session -t "agent-${SAFE_BRANCH}" 2>/dev/null; then
+    tmux kill-session -t "agent-${SAFE_BRANCH}" 2>/dev/null || true
+  fi
+  [[ -n "$WATCHDOG_PID" ]] && kill "$WATCHDOG_PID" 2>/dev/null || true
+  echo "Task #${SHORT_ID} cancelled."
+  exit 130
+}
+trap _sprint_cleanup SIGINT SIGTERM
+
+# ── Watchdog timeout ─────────────────────────────────────────────────
+if [[ -n "$TIMEOUT_MIN" ]]; then
+  log_info "Watchdog: will kill agent after ${TIMEOUT_MIN} minutes"
+  (
+    sleep $((TIMEOUT_MIN * 60))
+    log_warn "Timeout reached (${TIMEOUT_MIN}m). Stopping agent..."
+    registry_update "$SAFE_BRANCH" "status" '"timeout"'
+    tmux kill-session -t "agent-${SAFE_BRANCH}" 2>/dev/null || true
+  ) &
+  WATCHDOG_PID=$!
+fi
+
+# ── Step 4: Notify ────────────────────────────────────────────────────
+"${SCRIPT_DIR}/notify.sh" --type task-started --description "$TASK" --dry-run 2>/dev/null || true
+
+# ── OpenClaw notify ──────────────────────────────────────────────────
+if $NOTIFY; then
+  openclaw system event --text "ClawForge: sprint started — $TASK (#$SHORT_ID)" --mode now 2>/dev/null || true
+fi
+
+# ── Webhook ──────────────────────────────────────────────────────────
+if [[ -n "$WEBHOOK" ]]; then
+  local payload
+  payload=$(jq -cn \
+    --arg taskId "$SAFE_BRANCH" \
+    --argjson shortId "$SHORT_ID" \
+    --arg mode "$MODE" \
+    --arg status "spawned" \
+    --arg branch "$BRANCH" \
+    --arg description "$TASK" \
+    --arg repo "$REPO_ABS" \
+    '{taskId: $taskId, shortId: $shortId, mode: $mode, status: $status, branch: $branch, description: $description, repo: $repo}')
+  curl -s -X POST -H "Content-Type: application/json" -d "$payload" "$WEBHOOK" >/dev/null 2>&1 || log_warn "Webhook POST failed"
+fi
+
+# ── Output ────────────────────────────────────────────────────────────
+if $JSON_OUTPUT; then
+  jq -cn \
+    --arg taskId "$SAFE_BRANCH" \
+    --argjson shortId "$SHORT_ID" \
+    --arg mode "$MODE" \
+    --arg status "spawned" \
+    --arg branch "$BRANCH" \
+    --arg description "$TASK" \
+    --arg repo "$REPO_ABS" \
+    --arg agent "$RESOLVED_AGENT" \
+    --arg model "$MODEL" \
+    --argjson autoMerge "$AUTO_MERGE" \
+    --argjson ciLoop "$CI_LOOP" \
+    '{taskId: $taskId, shortId: $shortId, mode: $mode, status: $status, branch: $branch, description: $description, repo: $repo, agent: $agent, model: $model, autoMerge: $autoMerge, ciLoop: $ciLoop}'
+else
+  echo ""
+  echo "  #${SHORT_ID}  ${MODE}  spawned  $(basename "$REPO_ABS")  \"$(echo "$TASK" | head -c 50)\""
+  echo ""
+  echo "  Agent running in tmux session: agent-${SAFE_BRANCH}"
+  echo "  Attach: clawforge attach $SHORT_ID"
+  echo "  Steer:  clawforge steer $SHORT_ID \"<message>\""
+  echo "  Status: clawforge status"
+  echo ""
+  $CI_LOOP && echo "  CI feedback loop: enabled (max retries: $MAX_CI_RETRIES)"
+  [[ -n "$BUDGET" ]] && echo "  Budget cap: \$$BUDGET"
+  echo "  Tip: Run 'clawforge watch --daemon' in another pane for auto-monitoring"
+fi
+
+# ── Auto-clean on completion ─────────────────────────────────────────
+if $AUTO_CLEAN; then
+  log_info "Auto-clean enabled. Will clean on task completion."
+  # Note: actual cleanup happens when task reaches "done" status
+  registry_update "$SAFE_BRANCH" "auto_clean" 'true'
+fi
+
+# Kill watchdog if still running
+[[ -n "$WATCHDOG_PID" ]] && kill "$WATCHDOG_PID" 2>/dev/null || true
+trap - SIGINT SIGTERM

package/bin/steer.sh

@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+# steer.sh — Send course correction to a running agent
+# Usage: clawforge steer <id> "<message>"
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "${SCRIPT_DIR}/../lib/common.sh"
+
+# ── Help ───────────────────────────────────────────────────────────────
+usage() {
+  cat <<EOF
+Usage: clawforge steer <id> "<message>"
+
+Send a course correction to a running agent via tmux.
+
+Arguments:
+  <id>          Task short ID (#1), full ID, or sub-agent ID (3.2)
+  "<message>"   Course correction message
+
+Examples:
+  clawforge steer 1 "Use bcrypt instead of md5 for password hashing"
+  clawforge steer 3.2 "Skip the legacy migration files"
+  clawforge steer myapp-auth "Add rate limiting too"
+EOF
+}
+
+# ── Parse args ────────────────────────────────────────────────────────
+if [[ $# -lt 1 ]] || [[ "$1" == "--help" ]] || [[ "$1" == "-h" ]]; then
+  usage
+  [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]] && exit 0 || exit 1
+fi
+
+TASK_REF="$1"
+shift
+
+MESSAGE="${*:-}"
+if [[ -z "$MESSAGE" ]]; then
+  log_error "Message is required"
+  usage
+  exit 1
+fi
+
+# ── Resolve task ──────────────────────────────────────────────────────
+TASK_ID=$(resolve_task_id "$TASK_REF")
+if [[ -z "$TASK_ID" ]]; then
+  log_error "Could not resolve task: $TASK_REF"
+  exit 1
+fi
+
+TASK=$(registry_get "$TASK_ID")
+if [[ -z "$TASK" ]]; then
+  log_error "Task not found: $TASK_ID"
+  exit 1
+fi
+
+STATUS=$(echo "$TASK" | jq -r '.status')
+TMUX_SESSION=$(echo "$TASK" | jq -r '.tmuxSession')
+DESCRIPTION=$(echo "$TASK" | jq -r '.description' | head -c 50)
+
+# ── Check task state ──────────────────────────────────────────────────
+case "$STATUS" in
+  done|archived)
+    log_warn "Task $TASK_REF is already $STATUS."
+    echo "  Tip: Run 'clawforge review --pr <num>' instead."
+    exit 0
+    ;;
+  failed)
+    log_warn "Task $TASK_REF has failed. Consider restarting it."
+    exit 1
+    ;;
+  stopped)
+    log_warn "Task $TASK_REF is stopped. Start it first."
+    exit 1
+    ;;
+esac
+
+# ── Check tmux session ────────────────────────────────────────────────
+if [[ -z "$TMUX_SESSION" ]] || ! tmux has-session -t "$TMUX_SESSION" 2>/dev/null; then
+  log_error "tmux session not found: ${TMUX_SESSION:-none}"
+  echo "  The agent may have finished or crashed."
+  echo "  Use 'clawforge status' to check."
+  exit 1
+fi
+
+# ── Send message ──────────────────────────────────────────────────────
+# For long messages (>200 chars), use tmux load-buffer to avoid truncation
+if [[ ${#MESSAGE} -gt 200 ]]; then
+  TMPFILE=$(mktemp)
+  echo "$MESSAGE" > "$TMPFILE"
+  tmux load-buffer "$TMPFILE"
+  tmux paste-buffer -t "$TMUX_SESSION"
+  tmux send-keys -t "$TMUX_SESSION" Enter
+  rm -f "$TMPFILE"
+else
+  tmux send-keys -t "$TMUX_SESSION" "$MESSAGE" Enter
+fi
+
+# ── Log steer event in registry ───────────────────────────────────────
+NOW=$(epoch_ms)
+STEER_LOG=$(registry_get "$TASK_ID" | jq -r '.steer_log // "[]"')
+STEER_ENTRY=$(jq -n --argjson ts "$NOW" --arg msg "$MESSAGE" '{timestamp: $ts, message: $msg}')
+NEW_LOG=$(echo "$STEER_LOG" | jq --argjson entry "$STEER_ENTRY" '. += [$entry]')
+registry_update "$TASK_ID" "steer_log" "$NEW_LOG" 2>/dev/null || true
+
+log_info "Steered task $TASK_REF ($DESCRIPTION): $(echo "$MESSAGE" | head -c 60)..."
+echo "  Sent to: $TMUX_SESSION"
+echo "  Attach:  clawforge attach $TASK_REF"