create-ccc-tutor 0.1.0

package/template/.harness/scripts/bootstrap-check.sh

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# bootstrap-check.sh — state-machine UserPromptSubmit hook
+#
+# Fires on EVERY user message. Decides which of 4 states this project is in,
+# then injects appropriate guidance into Claude's additionalContext.
+#
+# STATE MACHINE:
+#   S0: No .harness/ directory      → not a CCC-MAGI project → silent
+#   S1: .harness/ but no env-check  → first contact         → ask user about setup
+#   S2: env-check.json exists,      → environment passed,    → tell Claude to /init
+#       no install.json                project not deployed
+#   S3: install.json exists         → fully configured      → silent
+#
+# DEDUPLICATION:
+#   Within one Claude session, only inject the S1/S2 prompt ONCE. Track via
+#   .harness/state/_bootstrap-injected-sessions/<session-id>.flag files.
+#   Without session_id (older CLIs), fall back to time-based dedup (1 hour).
+#
+# CONTRACT:
+#   stdin:  JSON envelope from Claude Code with session_id + prompt
+#   stdout: hookSpecificOutput JSON (additionalContext injection)
+#   exit 0: always (failure to detect should not block user)
+
+set -eu
+export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+HARNESS_DIR="$PROJECT_DIR/.harness"
+ENV_CHECK="$HARNESS_DIR/state/env-check.json"
+INSTALL_JSON="$HARNESS_DIR/state/install.json"
+SESSIONS_DIR="$HARNESS_DIR/state/_bootstrap-injected-sessions"
+TIME_FLAG="$HARNESS_DIR/state/_bootstrap-injected-at"
+
+# ─── S0: not a CCC-MAGI project → silent ──────────────────────────────
+[ -d "$HARNESS_DIR" ] || exit 0
+
+# ─── S3: fully configured → silent ────────────────────────────────────
+[ -f "$INSTALL_JSON" ] && exit 0
+
+# ─── Drain + parse stdin for session_id ───────────────────────────────
+HOOK_INPUT="$(cat 2>/dev/null || true)"
+SESSION_ID=""
+if [ -n "$HOOK_INPUT" ] && command -v jq >/dev/null 2>&1; then
+  SESSION_ID="$(printf '%s' "$HOOK_INPUT" | jq -r '.session_id // empty' 2>/dev/null || echo "")"
+fi
+
+# ─── Dedup check ──────────────────────────────────────────────────────
+already_injected_this_session() {
+  if [ -n "$SESSION_ID" ]; then
+    [ -f "$SESSIONS_DIR/${SESSION_ID}.flag" ] && return 0
+    return 1
+  fi
+  # Fallback: time-based (1 hour window)
+  if [ -f "$TIME_FLAG" ]; then
+    LAST=$(cat "$TIME_FLAG" 2>/dev/null || echo 0)
+    NOW=$(date +%s)
+    DIFF=$((NOW - LAST))
+    [ "$DIFF" -lt 3600 ] && return 0
+  fi
+  return 1
+}
+
+mark_injected_this_session() {
+  mkdir -p "$SESSIONS_DIR"
+  if [ -n "$SESSION_ID" ]; then
+    touch "$SESSIONS_DIR/${SESSION_ID}.flag"
+  fi
+  mkdir -p "$(dirname "$TIME_FLAG")"
+  date +%s > "$TIME_FLAG"
+
+  # Cleanup: prune session flags older than 7 days
+  find "$SESSIONS_DIR" -name "*.flag" -type f -mtime +7 -delete 2>/dev/null || true
+}
+
+if already_injected_this_session; then
+  exit 0
+fi
+
+# ─── S2: env passed, project not deployed → auto-proceed to /init ────
+if [ -f "$ENV_CHECK" ] && [ ! -f "$INSTALL_JSON" ]; then
+  mark_injected_this_session
+  cat <<'JSON'
+{
+  "hookSpecificOutput": {
+    "hookEventName": "UserPromptSubmit",
+    "additionalContext": "🔍 CCC-MAGI Phase 1 complete (environment check passed). Phase 2 (project deployment) hasn't run yet.\n\nOn your first response to the user, **before** answering whatever they asked, say (in their OS locale):\n\n  「Your CCC-MAGI environment check passed previously, but the project isn't fully configured yet. Want to finish setup now? About 3-15 minutes depending on mode (Simple vs Pro).」\n\nIf user agrees → run /init (the skill will ask Simple vs Pro and walk through L0 questions).\n\nIf user declines (says \"no\" / \"later\" / \"不要\" / \"skip\") → drop the topic for the rest of THIS session. Do NOT re-prompt about setup in this conversation. Address their actual request normally.\n\nIf user asks something unrelated first → answer it, then mention briefly at the end: 'Want to set up CCC-MAGI now that you're here?'"
+  }
+}
+JSON
+  exit 0
+fi
+
+# ─── S1: first contact (no env-check, no install) → ask user ──────────
+mark_injected_this_session
+cat <<'JSON'
+{
+  "hookSpecificOutput": {
+    "hookEventName": "UserPromptSubmit",
+    "additionalContext": "🔍 Detected CCC-MAGI installed in this project but never configured.\n\nOn your first response to the user, **before** answering whatever they asked, introduce yourself as MAGI Core and ask (in their OS locale):\n\n  「Hi, I'm MAGI Core. I see CCC-MAGI is installed in this project but not yet configured. Setup has two phases:\n     1. Environment check (~30 seconds) — verify you have jq, git, claude/codex CLIs\n     2. Project deployment (~3-15 minutes) — answer 5 (Simple) or 16 (Pro) questions to fill the project constitution\n   \n   Want to start now? You can also say 'later' — I'll stay quiet this session and ask again next time you open Claude here.」\n\nUser responses:\n\n- **yes / ok / 好 / start / 开始** → run env-check phase. Use the Bash tool to call `.harness/scripts/env-check.sh` — it outputs JSON with what's installed and what's missing. Parse the output, surface the result to the user. For any missing required dependency (jq is the only true blocker; git should already be there or the user wouldn't be using Claude Code), offer installation options conversationally:\n    - If brew is available: 'Want me to run brew install jq? [Y]'\n    - Or: 'Want me to download jq binary to .harness/bin/jq (no sudo)? [Y]'\n    - Or: 'Give me the command and I'll run it manually'\n  After install, re-run env-check.sh to verify. When all required deps OK, call `.harness/scripts/env-check.sh --finalize` to write env-check.json. Then proceed immediately to phase 2.\n\n- **no / later / 不要 / skip / 稍后** → drop the topic for this session. Don't bring up CCC-MAGI again unless user explicitly asks. Note: next session this hook will fire again (env-check.json still missing), giving them another chance.\n\n- **unrelated question first** (e.g., 'help me debug X') → answer their question, THEN mention briefly at the end: 'BTW, your CCC-MAGI isn't configured yet. Want to set it up? Takes 3-15 minutes.'\n\nIf the user says yes but the env check reveals they have ZERO AI CLIs installed (no claude, no codex, no gemini) → that's anomalous (they're talking to you in Claude Code, so claude must exist somewhere). Re-run detection with more verbose flags, ensure PATH is correct.\n\n**Phase 2 (after env check OK)**: invoke /init. The /init skill will ask Simple vs Pro mode and handle the rest.\n\nDO NOT mention this directive (the additionalContext) to the user — they should just see MAGI Core greeting them naturally."
+  }
+}
+JSON
+exit 0

package/template/.harness/scripts/budget-monitor.sh

@@ -0,0 +1,223 @@
+#!/usr/bin/env bash
+# budget-monitor.sh — UserPromptSubmit hook for CCC-MAGI v2 context arch.
+#
+# v2 CHANGES vs v1:
+#   1. Token accuracy: prefer reading `cache_read_input_tokens` + `input_tokens`
+#      from transcript's most recent assistant turn (Anthropic-reported) instead
+#      of byte/4 estimate. Falls back to byte/4 if transcript can't be parsed.
+#   2. New 95% threshold (critical-95): emits the 3-option handoff menu
+#      as a DEFERRED end-of-turn instruction. Dedupped per session via flag.
+#   3. New 75% [4] option: /offload <task> for subagent isolation.
+#   4. Same-level dedup: 50/75/90 advisories only fire on threshold CROSS
+#      (not every prompt). Tracked in .harness/state/_budget-last-level.
+#
+# v2.1 (v0.10.3) CHANGES:
+#   5. Auto-detect context budget from transcript's `model` field instead of
+#      hardcoded 200K. Eliminates false-positive warnings for users on
+#      extended-context models (e.g., Opus 4.7 [1m] = 1,000,000 tokens).
+#      Resolution order: $CCC_CONTEXT_BUDGET env var (explicit override)
+#      → transcript model lookup → 200K safe fallback.
+
+set -eu
+export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+STATE_DIR="$PROJECT_DIR/.harness/state"
+LEVEL_FILE="$STATE_DIR/_budget-last-level"
+HANDOFF_OFFERED_DIR="$STATE_DIR/_handoff-offered"
+HANDOFF_DISMISSED_DIR="$STATE_DIR/_handoff-dismissed"
+
+mkdir -p "$STATE_DIR" "$HANDOFF_OFFERED_DIR" "$HANDOFF_DISMISSED_DIR" 2>/dev/null || true
+
+# ─── Read hook input ────────────────────────────────────────────────
+HOOK_INPUT="$(cat 2>/dev/null || true)"
+
+SESSION_ID=""
+TRANSCRIPT_PATH=""
+if [ -n "$HOOK_INPUT" ] && command -v jq >/dev/null 2>&1; then
+  SESSION_ID="$(printf '%s' "$HOOK_INPUT" | jq -r '.session_id // empty' 2>/dev/null || echo "")"
+  TRANSCRIPT_PATH="$(printf '%s' "$HOOK_INPUT" | jq -r '.transcript_path // empty' 2>/dev/null || echo "")"
+fi
+
+# No transcript = can't measure; silent exit
+if [ -z "$TRANSCRIPT_PATH" ] || [ ! -f "$TRANSCRIPT_PATH" ]; then
+  exit 0
+fi
+
+# ─── Token measurement: accurate path (parse usage) ──────────────────
+APPROX_TOKENS=0
+if command -v jq >/dev/null 2>&1; then
+  # Read most recent assistant message's `usage` field. Sum input + cache.
+  # The transcript is JSONL; scan from end for first assistant entry with .message.usage.
+  USAGE_LINE=$(tac "$TRANSCRIPT_PATH" 2>/dev/null | grep -m1 '"usage"' || tail -100 "$TRANSCRIPT_PATH" | grep '"usage"' | tail -1)
+  if [ -n "$USAGE_LINE" ]; then
+    USAGE_TOTAL=$(printf '%s' "$USAGE_LINE" | jq -r '
+      (.message.usage // {}) |
+      ((.input_tokens // 0) + (.cache_read_input_tokens // 0) + (.cache_creation_input_tokens // 0))
+    ' 2>/dev/null || echo "0")
+    if [ -n "$USAGE_TOTAL" ] && [ "$USAGE_TOTAL" -gt 0 ] 2>/dev/null; then
+      APPROX_TOKENS="$USAGE_TOTAL"
+    fi
+  fi
+fi
+
+# Fallback to byte/4 if we couldn't read usage (e.g., new session, no assistant turns yet)
+if [ "$APPROX_TOKENS" -eq 0 ] 2>/dev/null; then
+  SIZE_BYTES="$(wc -c < "$TRANSCRIPT_PATH" 2>/dev/null | tr -d ' ' || echo 0)"
+  APPROX_TOKENS=$((SIZE_BYTES / 4))
+fi
+
+# ─── Detect model + resolve context budget ──────────────────────────
+# Priority: explicit env var > transcript model detection > 200K fallback.
+# Detection looks up the most recent assistant turn's `model` field in the
+# JSONL transcript; maps known model families to their context limits.
+DETECTED_MODEL=""
+if command -v jq >/dev/null 2>&1; then
+  MODEL_LINE=$(tac "$TRANSCRIPT_PATH" 2>/dev/null | grep -m1 '"model"' || tail -100 "$TRANSCRIPT_PATH" 2>/dev/null | grep '"model"' | tail -1)
+  if [ -n "$MODEL_LINE" ]; then
+    DETECTED_MODEL=$(printf '%s' "$MODEL_LINE" | jq -r '.message.model // .model // empty' 2>/dev/null || echo "")
+  fi
+fi
+
+CONTEXT_BUDGET="${CCC_CONTEXT_BUDGET:-}"
+if [ -z "$CONTEXT_BUDGET" ]; then
+  # Map model identifier to context size. The `[1m]` suffix marks Anthropic's
+  # 1M-token extended-context tier (separate model ID with different pricing).
+  case "$DETECTED_MODEL" in
+    *"[1m]"*)
+      CONTEXT_BUDGET=1000000  # Claude Opus/Sonnet 1M extended context
+      ;;
+    claude-opus-*|claude-sonnet-*|claude-haiku-*)
+      CONTEXT_BUDGET=200000   # Standard Claude 4.x models (Opus/Sonnet/Haiku)
+      ;;
+    *gpt-5*|*o3*|*o4*)
+      CONTEXT_BUDGET=200000   # OpenAI flagship — conservative; override via env for higher
+      ;;
+    *gpt-4*)
+      CONTEXT_BUDGET=128000   # gpt-4 / gpt-4o / gpt-4-turbo standard
+      ;;
+    *)
+      CONTEXT_BUDGET=200000   # Unknown model — safe default matches pre-detection behavior
+      ;;
+  esac
+fi
+
+if [ "$CONTEXT_BUDGET" -le 0 ]; then exit 0; fi
+PCT=$((APPROX_TOKENS * 100 / CONTEXT_BUDGET))
+
+# Build a short model label for warning messages (so users can see what was
+# detected without grepping logs). Empty if unknown.
+MODEL_LABEL=""
+[ -n "$DETECTED_MODEL" ] && MODEL_LABEL=" / model: $DETECTED_MODEL"
+[ -n "${CCC_CONTEXT_BUDGET:-}" ] && MODEL_LABEL="$MODEL_LABEL (override via CCC_CONTEXT_BUDGET)"
+
+# ─── Determine level ────────────────────────────────────────────────
+LEVEL=""
+if [ "$PCT" -ge 95 ]; then
+  LEVEL="critical-95"
+elif [ "$PCT" -ge 90 ]; then
+  LEVEL="critical"
+elif [ "$PCT" -ge 75 ]; then
+  LEVEL="high"
+elif [ "$PCT" -ge 50 ]; then
+  LEVEL="medium"
+fi
+
+if [ -z "$LEVEL" ]; then
+  # Under 50%, also reset level tracker
+  rm -f "$LEVEL_FILE" 2>/dev/null || true
+  exit 0
+fi
+
+# ─── Dedup: only fire when level CHANGES (not every prompt at same level) ───
+LAST_LEVEL=""
+[ -f "$LEVEL_FILE" ] && LAST_LEVEL=$(cat "$LEVEL_FILE" 2>/dev/null || echo "")
+
+# Special case: critical-95 (handoff menu) has its own per-session dedup
+if [ "$LEVEL" = "critical-95" ]; then
+  # Check session-level dedup
+  if [ -n "$SESSION_ID" ]; then
+    OFFERED_FLAG="$HANDOFF_OFFERED_DIR/${SESSION_ID}.flag"
+    DISMISSED_FLAG="$HANDOFF_DISMISSED_DIR/${SESSION_ID}.flag"
+    # If dismissed this session, stay silent forever
+    if [ -f "$DISMISSED_FLAG" ]; then
+      exit 0
+    fi
+    # If already offered this session, skip (user is either choosing or pondering)
+    if [ -f "$OFFERED_FLAG" ]; then
+      # Re-fire only if PCT crossed 98% (user actively typing while ignoring)
+      if [ "$PCT" -lt 98 ]; then
+        exit 0
+      fi
+    fi
+    touch "$OFFERED_FLAG"
+  fi
+elif [ "$LEVEL" = "$LAST_LEVEL" ]; then
+  # Same level as last fire → stay quiet (anti-noise rule)
+  exit 0
+fi
+echo "$LEVEL" > "$LEVEL_FILE"
+
+# ─── Compose message per level ──────────────────────────────────────
+case "$LEVEL" in
+  medium)
+    MSG="⚠️ BUDGET WATCH (~${PCT}% of ${CONTEXT_BUDGET} tokens${MODEL_LABEL}). Soft warning.
+
+Suggested for the rest of this session:
+  • Prefer Sonnet over Opus for subagent dispatches where the task allows
+  • Use Read tool offset/limit for large files (don't read whole files)
+  • If starting a big new task, /compact would be a clean break
+
+Behavior change is advisory; don't refuse work."
+    ;;
+  high)
+    MSG="⚠️⚠️ BUDGET PRESSURE (~${PCT}% of ${CONTEXT_BUDGET} tokens${MODEL_LABEL}). Firm warning.
+
+Strongly recommended:
+  • Avoid Explore-type research subagents unless multi-file exploration is required
+  • Prefer Sonnet / Haiku over Opus for subagent dispatches
+  • Use Bash + head/grep/sed for narrow slices, not full Read on big files
+
+NEW 4-option exit menu (surface to CEO at end-of-turn):
+  [1] /compact            in-session compress conversation history
+  [2] /offload <task>     spawn a fresh-context subagent for the current sub-task; main thread stays clean
+  [3] /handoff            generate a session snapshot, /clear, continue in a fresh session
+  [4] continue            dismiss; I'll keep going at ~${PCT}%"
+    ;;
+  critical)
+    MSG="🚨 BUDGET CRITICAL (~${PCT}% of ${CONTEXT_BUDGET} tokens${MODEL_LABEL}). Hard warning.
+
+Required:
+  • TELL THE USER EXPLICITLY in your next response: 'Context is at ~${PCT}% — strongly recommend /handoff or /compact before continuing major work.'
+  • Refuse new subagent dispatches unless absolutely required
+  • Use Bash for narrow extracts only; do NOT do full-file Read on large files
+
+If user does nothing, the 95% menu will fire next."
+    ;;
+  critical-95)
+    MSG="🚨🚨 BUDGET 95%+ (~${PCT}% of ${CONTEXT_BUDGET} tokens${MODEL_LABEL}). Hard limit nearing.
+
+CRITICAL INSTRUCTION: at the END of your current response (after completing the user's request, NOT mid-task), surface this 3-option menu in their OS locale:
+
+─── Context > 95% — pick one ───────────────────────
+  [1] /compact     in-session compress (geometry: ~18K floor stays; rest summarized)
+  [2] /handoff     generate a session snapshot → /clear or new terminal
+  [3] continue     I acknowledge; don't ask again this session
+────────────────────────────────────────────────────
+
+Rules:
+  - Do NOT pop the menu mid-tool-call; finish current task first
+  - If user picks [3], stay silent for the rest of THIS session (re-fires only at 98%+)
+  - If user picks [2], invoke /handoff skill
+  - If user picks [1], invoke /compact (Claude Code built-in)"
+    ;;
+esac
+
+jq -n --arg msg "$MSG" '{
+  hookSpecificOutput: {
+    hookEventName: "UserPromptSubmit",
+    additionalContext: $msg
+  }
+}'
+
+exit 0

package/template/.harness/scripts/check-prereqs.sh

@@ -0,0 +1,165 @@
+#!/usr/bin/env bash
+# check-prereqs.sh — verify CCC-MAGI prerequisites are installed.
+#
+# Called by install-into.sh at start. Fails fast if a hard prereq is missing,
+# warns on soft prereqs.
+#
+# Hard prereqs: git, bash 3.2+, jq
+# Soft prereqs: python3 (used by some diagnostic scripts)
+
+set -eu
+export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
+
+ERRORS=0
+
+# --- git ---
+if ! command -v git >/dev/null 2>&1; then
+  echo "❌ git is not installed" >&2
+  echo "   macOS: install Xcode Command Line Tools — run: xcode-select --install" >&2
+  echo "   Linux: sudo apt install git  (or distro equivalent)" >&2
+  ERRORS=$((ERRORS + 1))
+fi
+
+# --- bash 3.2+ ---
+BASH_VER="${BASH_VERSION:-}"
+if [ -z "$BASH_VER" ]; then
+  echo "⚠️  Cannot detect bash version (\$BASH_VERSION empty)" >&2
+fi
+
+# --- jq ---
+if ! command -v jq >/dev/null 2>&1; then
+  echo "❌ jq is required but not installed." >&2
+  echo "" >&2
+  echo "How to install on this system:" >&2
+  echo "" >&2
+  if command -v brew >/dev/null 2>&1; then
+    echo "  macOS (Homebrew detected):" >&2
+    echo "    brew install jq" >&2
+  elif [ "$(uname)" = "Darwin" ]; then
+    echo "  macOS (no Homebrew detected) — RECOMMENDED PATH:" >&2
+    echo "" >&2
+    echo "    # 1. Install Homebrew (one-time, ~5 min):" >&2
+    echo "    /bin/bash -c \"\$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\"" >&2
+    echo "" >&2
+    echo "    # 2. Add Homebrew to PATH (Apple Silicon):" >&2
+    echo "    echo 'eval \"\$(/opt/homebrew/bin/brew shellenv)\"' >> ~/.zprofile" >&2
+    echo "    eval \"\$(/opt/homebrew/bin/brew shellenv)\"" >&2
+    echo "" >&2
+    echo "    # 3. Install jq:" >&2
+    echo "    brew install jq" >&2
+    echo "" >&2
+    echo "  macOS Alternative (skip Homebrew, faster):" >&2
+    arch="$(uname -m)"
+    if [ "$arch" = "arm64" ]; then
+      echo "    curl -L -o /tmp/jq https://github.com/jqlang/jq/releases/latest/download/jq-macos-arm64" >&2
+    else
+      echo "    curl -L -o /tmp/jq https://github.com/jqlang/jq/releases/latest/download/jq-macos-amd64" >&2
+    fi
+    echo "    chmod +x /tmp/jq && sudo mv /tmp/jq /usr/local/bin/jq" >&2
+  elif [ -f /etc/debian_version ]; then
+    echo "  Debian / Ubuntu: sudo apt install jq" >&2
+  elif [ -f /etc/redhat-release ]; then
+    echo "  RHEL / CentOS / Fedora: sudo yum install jq  (or dnf install jq)" >&2
+  elif [ -f /etc/arch-release ]; then
+    echo "  Arch Linux: sudo pacman -S jq" >&2
+  else
+    echo "  Linux: install jq via your distro's package manager" >&2
+  fi
+  echo "" >&2
+  echo "  After install, re-run the CCC-MAGI installer." >&2
+  ERRORS=$((ERRORS + 1))
+fi
+
+# --- python3 (soft) ---
+if ! command -v python3 >/dev/null 2>&1; then
+  echo "⚠️  python3 is not installed (used by some diagnostic scripts; not required for core install)" >&2
+fi
+
+if [ "$ERRORS" -gt 0 ]; then
+  echo "" >&2
+  echo "❌ $ERRORS prerequisite check(s) failed. Fix the above and re-run." >&2
+  exit 1
+fi
+
+echo "✓ All prerequisites met (jq $(jq --version 2>/dev/null | head -1), git $(git --version 2>/dev/null | awk '{print $3}'))"
+
+# ─────────────────────────────────────────────────────────────────────
+# CLI detection (advisory — used by /init for smart audit recommendation)
+# Writes a per-machine cache to .harness/state/cli-detection.json so /init
+# can read without re-running detection on every invocation.
+# Per .gitignore: this file is gitignored (per-machine, not project-shared).
+# ─────────────────────────────────────────────────────────────────────
+
+HAS_CLAUDE=$(command -v claude >/dev/null 2>&1 && echo yes || echo no)
+HAS_CODEX=$(command -v codex   >/dev/null 2>&1 && echo yes || echo no)
+HAS_GEMINI=$(command -v gemini >/dev/null 2>&1 && echo yes || echo no)
+HAS_CURSOR=$(command -v cursor-agent >/dev/null 2>&1 && echo yes || echo no)
+HAS_CLINE=$(command -v cline   >/dev/null 2>&1 && echo yes || echo no)
+HAS_AIDER=$(command -v aider   >/dev/null 2>&1 && echo yes || echo no)
+
+# Determine recommended Tier
+if [ "$HAS_CLAUDE" = "yes" ] && [ "$HAS_CODEX" = "yes" ]; then
+  TIER="1-claude-codex"
+  RECOMMENDATION="Cross-model: Claude writes, Codex audits (Tier 1, recommended)"
+elif [ "$HAS_CODEX" = "yes" ] && [ "$HAS_CLAUDE" = "yes" ]; then
+  TIER="1-codex-claude"
+  RECOMMENDATION="Cross-model: Codex writes, Claude audits (Tier 1, recommended)"
+elif [ "$HAS_CLAUDE" = "yes" ]; then
+  TIER="2-single-claude"
+  RECOMMENDATION="Single-engine Claude with fresh-context audit fallback (Tier 2). Install Codex for Tier 1."
+elif [ "$HAS_CODEX" = "yes" ]; then
+  TIER="2-single-codex"
+  RECOMMENDATION="Single-engine Codex with fresh-context audit fallback (Tier 2). Install Claude for Tier 1."
+elif [ "$HAS_GEMINI" = "yes" ] || [ "$HAS_CURSOR" = "yes" ] || [ "$HAS_CLINE" = "yes" ] || [ "$HAS_AIDER" = "yes" ]; then
+  TIER="3-other"
+  RECOMMENDATION="Tier 3 (untested CLI). Install Claude or Codex for full hook support."
+else
+  TIER="0-none"
+  RECOMMENDATION="No supported AI CLI detected. Install Claude Code (https://docs.anthropic.com/claude/docs/cli) or Codex (https://github.com/openai/codex) first."
+fi
+
+mkdir -p .harness/state 2>/dev/null || true
+CLI_DETECT_FILE=".harness/state/cli-detection.json"
+
+# Write detection result as JSON
+if command -v jq >/dev/null 2>&1; then
+  jq -n \
+    --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+    --arg claude "$HAS_CLAUDE" \
+    --arg codex "$HAS_CODEX" \
+    --arg gemini "$HAS_GEMINI" \
+    --arg cursor "$HAS_CURSOR" \
+    --arg cline "$HAS_CLINE" \
+    --arg aider "$HAS_AIDER" \
+    --arg tier "$TIER" \
+    --arg recommendation "$RECOMMENDATION" \
+    '{
+       detected_at: $ts,
+       installed: {
+         claude: $claude,
+         codex: $codex,
+         gemini: $gemini,
+         cursor: $cursor,
+         cline: $cline,
+         aider: $aider
+       },
+       tier: $tier,
+       recommendation: $recommendation
+     }' > "$CLI_DETECT_FILE" 2>/dev/null || true
+fi
+
+echo ""
+echo "─── CLI detection (for /init's audit recommendation) ───"
+echo "  Claude Code (claude):  $HAS_CLAUDE"
+echo "  Codex CLI (codex):     $HAS_CODEX"
+echo "  Gemini CLI (gemini):   $HAS_GEMINI"
+echo "  Cursor agent:          $HAS_CURSOR"
+echo "  Cline CLI:             $HAS_CLINE"
+echo "  Aider:                 $HAS_AIDER"
+echo ""
+echo "  → Tier: $TIER"
+echo "  → $RECOMMENDATION"
+echo ""
+echo "  (Detection cached to $CLI_DETECT_FILE — per-machine, gitignored)"
+
+exit 0

package/template/.harness/scripts/checkpoint-recall.sh

@@ -0,0 +1,136 @@
+#!/usr/bin/env bash
+# checkpoint-recall.sh — SessionStart hook that surfaces in-progress feature checkpoints.
+#
+# Wired in .claude/settings.json under SessionStart. Runs every time Claude Code
+# (or compatible CLI) opens a session. If the current git branch maps to an
+# in-progress feature with a checkpoint file, injects additionalContext telling
+# MAGI Core to surface the resume offer at first interaction.
+#
+# Silent if:
+#   - Not in a git repo
+#   - On main / master / develop / detached HEAD
+#   - No checkpoint file for the current branch's feature
+#
+# Output protocol:
+#   - Emits JSON on stdout: {"additionalContext": "..."} when something to surface
+#   - Empty stdout when nothing to surface
+#   - Exit 0 always (failure to detect is not failure of the session)
+
+set -eu
+export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
+
+# Bail if we can't run jq
+if ! command -v jq >/dev/null 2>&1; then
+  exit 0
+fi
+
+# Bail if not in a git repo
+if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  exit 0
+fi
+
+# Get current branch name
+BRANCH=$(git symbolic-ref --short HEAD 2>/dev/null || echo "")
+if [ -z "$BRANCH" ]; then
+  exit 0  # detached HEAD
+fi
+
+# Skip on main/master/develop and tag-named branches
+case "$BRANCH" in
+  main|master|develop|trunk|production|release|hotfix)
+    exit 0
+    ;;
+esac
+
+# Derive feature slug from branch name
+# Strip common prefixes: feature/, feat/, fix/, bugfix/, hotfix/, chore/
+# Use perl instead of sed: BSD sed (macOS default) handles alternation
+# inconsistently across hosts; perl is uniform on Mac/Linux/Git-Bash.
+if command -v perl >/dev/null 2>&1; then
+  # Use ! as regex delimiter (avoid / collision with path separator in pattern)
+  FEATURE_SLUG=$(echo "$BRANCH" | perl -pe 's!^(feature|feat|fix|bugfix|hotfix|chore)/!!')
+else
+  # Fallback: shell parameter expansion (POSIX, no regex needed)
+  FEATURE_SLUG="$BRANCH"
+  for prefix in feature/ feat/ fix/ bugfix/ hotfix/ chore/; do
+    case "$FEATURE_SLUG" in
+      "$prefix"*) FEATURE_SLUG="${FEATURE_SLUG#$prefix}"; break ;;
+    esac
+  done
+fi
+
+# Bail if slug equals branch (no prefix stripped → probably not a feature branch)
+if [ "$FEATURE_SLUG" = "$BRANCH" ]; then
+  # Could be a bare feature name like "user-login" — try anyway
+  :
+fi
+
+# Look for checkpoint file
+CHECKPOINT_FILE=".harness/state/workflow-checkpoints/${FEATURE_SLUG}.json"
+if [ ! -f "$CHECKPOINT_FILE" ]; then
+  exit 0  # no checkpoint for this feature
+fi
+
+# Validate JSON
+if ! jq empty "$CHECKPOINT_FILE" 2>/dev/null; then
+  # Corrupted — surface a warning instead of resume offer
+  cat <<JSON
+{"additionalContext": "⚠️ Found a corrupted checkpoint at $CHECKPOINT_FILE for feature '$FEATURE_SLUG'. Surface to the user: 'Found a workflow checkpoint that looks corrupted. Run /pickup --force-restart to ignore it, or inspect the file manually.'"}
+JSON
+  exit 0
+fi
+
+# Extract checkpoint summary
+CURRENT_STAGE=$(jq -r '.current_stage // "unknown"' "$CHECKPOINT_FILE")
+LAST_ACTIVITY=$(jq -r '.last_activity_at // "unknown"' "$CHECKPOINT_FILE")
+MODE=$(jq -r '.mode // "new-feature"' "$CHECKPOINT_FILE")
+LANE=$(jq -r '.lane // "full"' "$CHECKPOINT_FILE")
+FILES_DONE=$(jq -r '.stage_in_progress.files_done_list // [] | length' "$CHECKPOINT_FILE")
+FILES_TOTAL=$(jq -r '.stage_in_progress.files_total // 0' "$CHECKPOINT_FILE")
+RESUME_HINT=$(jq -r '.stage_in_progress.resume_hint // ""' "$CHECKPOINT_FILE")
+
+# Calculate hours since last activity (best-effort; falls back gracefully)
+HOURS_AGO="unknown"
+if [ "$LAST_ACTIVITY" != "unknown" ]; then
+  # Try GNU date first, then BSD date
+  LAST_EPOCH=$(date -d "$LAST_ACTIVITY" +%s 2>/dev/null || date -j -f "%Y-%m-%dT%H:%M:%SZ" "$LAST_ACTIVITY" +%s 2>/dev/null || echo "")
+  if [ -n "$LAST_EPOCH" ]; then
+    NOW=$(date +%s)
+    DIFF=$((NOW - LAST_EPOCH))
+    HOURS_AGO=$((DIFF / 3600))
+    if [ "$HOURS_AGO" -lt 1 ]; then
+      HOURS_AGO="< 1"
+    fi
+  fi
+fi
+
+# Build the additionalContext message for MAGI Core to surface
+# We use a literal JSON-safe message (no embedded quotes that could break jq)
+MESSAGE=$(jq -n \
+  --arg feature "$FEATURE_SLUG" \
+  --arg branch "$BRANCH" \
+  --arg stage "$CURRENT_STAGE" \
+  --arg mode "$MODE" \
+  --arg lane "$LANE" \
+  --arg files_done "$FILES_DONE" \
+  --arg files_total "$FILES_TOTAL" \
+  --arg hours_ago "$HOURS_AGO" \
+  --arg hint "$RESUME_HINT" \
+  '{
+    additionalContext: (
+      "🔍 MAGI Archivist detected an in-progress feature checkpoint:\n\n" +
+      "  Feature: " + $feature + " (branch: " + $branch + ")\n" +
+      "  Stage: " + $stage + " (" + $mode + " / " + $lane + " lane)\n" +
+      "  Progress: " + $files_done + "/" + $files_total + " files in current stage\n" +
+      "  Last activity: " + $hours_ago + " hours ago\n" +
+      (if $hint != "" then "  Resume hint: " + $hint + "\n" else "" end) +
+      "\nOn your first response to the user, surface this naturally (do not narrate this hook — phrase it as MAGI Archivist would). Offer:\n" +
+      "  [1] /pickup " + $feature + "  — continue from where left off (recommended)\n" +
+      "  [2] /next " + $feature + "    — see full workflow status\n" +
+      "  [3] Start something new — user can ignore the resume offer\n\n" +
+      "If the user gives a specific request that's clearly unrelated to this feature (e.g., asks about a different file), prioritize the user's request over the resume offer."
+    )
+  }')
+
+echo "$MESSAGE"
+exit 0