Initial import from garrytan/gstack@026751e (main snapshot via local relay)

Source: https://github.com/garrytan/gstack/commit/026751e

bin/chrome-cdp

@@ -0,0 +1,70 @@
+#!/bin/bash
+# Launch Chrome with CDP (remote debugging) enabled.
+# Usage: chrome-cdp [port]
+#
+# Chrome refuses --remote-debugging-port on its default data directory.
+# We create a separate data dir with a symlink to the user's real profile,
+# so Chrome thinks it's non-default but uses the same cookies/extensions.
+
+PORT="${1:-9222}"
+CHROME="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+REAL_PROFILE="$HOME/Library/Application Support/Google/Chrome"
+CDP_DATA_DIR="$HOME/.gstack/cdp-profile/chrome"
+
+if ! [ -f "$CHROME" ]; then
+  echo "Chrome not found at $CHROME" >&2
+  exit 1
+fi
+
+# Check if Chrome is running
+if pgrep -f "Google Chrome" >/dev/null 2>&1; then
+  echo "Chrome is still running. Quitting..."
+  osascript -e 'tell application "Google Chrome" to quit' 2>/dev/null
+
+  # Wait for it to fully exit
+  for i in $(seq 1 20); do
+    pgrep -f "Google Chrome" >/dev/null 2>&1 || break
+    sleep 0.5
+  done
+
+  if pgrep -f "Google Chrome" >/dev/null 2>&1; then
+    echo "Chrome won't quit. Force-killing..." >&2
+    pkill -f "Google Chrome"
+    sleep 1
+  fi
+fi
+
+# Set up CDP data dir with symlinked profile
+# Chrome requires a "non-default" data dir for --remote-debugging-port.
+# We symlink the real Default profile so cookies/extensions carry over.
+mkdir -p "$CDP_DATA_DIR"
+if [ -d "$REAL_PROFILE/Default" ] && ! [ -e "$CDP_DATA_DIR/Default" ]; then
+  ln -s "$REAL_PROFILE/Default" "$CDP_DATA_DIR/Default"
+  echo "Linked real Chrome profile into CDP data dir"
+fi
+# Also link Local State (contains crypto keys for cookie decryption, etc.)
+if [ -f "$REAL_PROFILE/Local State" ] && ! [ -e "$CDP_DATA_DIR/Local State" ]; then
+  ln -s "$REAL_PROFILE/Local State" "$CDP_DATA_DIR/Local State"
+fi
+
+echo "Launching Chrome with CDP on port $PORT..."
+"$CHROME" \
+  --remote-debugging-port="$PORT" \
+  --remote-debugging-address=127.0.0.1 \
+  --remote-allow-origins="http://127.0.0.1:$PORT" \
+  --user-data-dir="$CDP_DATA_DIR" \
+  --restore-last-session &
+disown
+
+# Wait for CDP to be available
+for i in $(seq 1 30); do
+  if curl -s "http://127.0.0.1:$PORT/json/version" >/dev/null 2>&1; then
+    echo "CDP ready on port $PORT"
+    echo "Run: \$B connect chrome"
+    exit 0
+  fi
+  sleep 1
+done
+
+echo "CDP not available after 30s." >&2
+exit 1

bin/dev-setup

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# Set up gstack for local development — test skills from within this repo.
+#
+# Creates .claude/skills/gstack → (symlink to repo root) so Claude Code
+# discovers skills from your working tree. Changes take effect immediately.
+#
+# Also copies .env from the main worktree if this is a Conductor workspace
+# or git worktree (so API keys carry over automatically).
+#
+# Usage: bin/dev-setup       # set up
+#        bin/dev-teardown    # clean up
+set -e
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+
+# 1. Copy .env from main worktree (if we're a worktree and don't have one)
+if [ ! -f "$REPO_ROOT/.env" ]; then
+  MAIN_WORKTREE="$(git -C "$REPO_ROOT" worktree list --porcelain 2>/dev/null | head -1 | sed 's/^worktree //')"
+  if [ -n "$MAIN_WORKTREE" ] && [ "$MAIN_WORKTREE" != "$REPO_ROOT" ] && [ -f "$MAIN_WORKTREE/.env" ]; then
+    cp "$MAIN_WORKTREE/.env" "$REPO_ROOT/.env"
+    echo "Copied .env from main worktree ($MAIN_WORKTREE)"
+  fi
+fi
+
+# 2. Install dependencies
+if [ ! -d "$REPO_ROOT/node_modules" ]; then
+  echo "Installing dependencies..."
+  (cd "$REPO_ROOT" && bun install)
+fi
+
+# 3. Create .claude/skills/ inside the repo
+mkdir -p "$REPO_ROOT/.claude/skills"
+
+# 4. Symlink .claude/skills/gstack → repo root
+# This makes setup think it's inside a real .claude/skills/ directory
+GSTACK_LINK="$REPO_ROOT/.claude/skills/gstack"
+if [ -L "$GSTACK_LINK" ]; then
+  echo "Updating existing symlink..."
+  rm "$GSTACK_LINK"
+elif [ -d "$GSTACK_LINK" ]; then
+  echo "Error: .claude/skills/gstack is a real directory, not a symlink." >&2
+  echo "Remove it manually if you want to use dev mode." >&2
+  exit 1
+fi
+ln -s "$REPO_ROOT" "$GSTACK_LINK"
+
+# 5. Create .agents/skills/gstack → repo root (for Codex/Gemini/Cursor)
+mkdir -p "$REPO_ROOT/.agents/skills"
+AGENTS_LINK="$REPO_ROOT/.agents/skills/gstack"
+if [ -L "$AGENTS_LINK" ]; then
+  rm "$AGENTS_LINK"
+elif [ -d "$AGENTS_LINK" ]; then
+  echo "Warning: .agents/skills/gstack is a real directory, skipping." >&2
+fi
+if [ ! -e "$AGENTS_LINK" ]; then
+  ln -s "$REPO_ROOT" "$AGENTS_LINK"
+fi
+
+# 6. Run setup via the symlink so it detects .claude/skills/ as its parent
+"$GSTACK_LINK/setup"
+
+echo ""
+echo "Dev mode active. Skills resolve from this working tree."
+echo "  .claude/skills/gstack → $REPO_ROOT"
+echo "  .agents/skills/gstack → $REPO_ROOT"
+echo "Edit any SKILL.md and test immediately — no copy/deploy needed."
+echo ""
+echo "To tear down: bin/dev-teardown"

bin/dev-teardown

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# Remove local dev skill symlinks. Restores global gstack as the active install.
+set -e
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+
+removed=()
+
+# ─── Clean up .claude/skills/ ─────────────────────────────────
+CLAUDE_SKILLS="$REPO_ROOT/.claude/skills"
+if [ -d "$CLAUDE_SKILLS" ]; then
+  for link in "$CLAUDE_SKILLS"/*/; do
+    name="$(basename "$link")"
+    [ "$name" = "gstack" ] && continue
+    if [ -L "${link%/}" ]; then
+      rm "${link%/}"
+      removed+=("claude/$name")
+    fi
+  done
+
+  if [ -L "$CLAUDE_SKILLS/gstack" ]; then
+    rm "$CLAUDE_SKILLS/gstack"
+    removed+=("claude/gstack")
+  fi
+
+  rmdir "$CLAUDE_SKILLS" 2>/dev/null || true
+  rmdir "$REPO_ROOT/.claude" 2>/dev/null || true
+fi
+
+# ─── Clean up .agents/skills/ ────────────────────────────────
+AGENTS_SKILLS="$REPO_ROOT/.agents/skills"
+if [ -d "$AGENTS_SKILLS" ]; then
+  for link in "$AGENTS_SKILLS"/*/; do
+    name="$(basename "$link")"
+    [ "$name" = "gstack" ] && continue
+    if [ -L "${link%/}" ]; then
+      rm "${link%/}"
+      removed+=("agents/$name")
+    fi
+  done
+
+  if [ -L "$AGENTS_SKILLS/gstack" ]; then
+    rm "$AGENTS_SKILLS/gstack"
+    removed+=("agents/gstack")
+  fi
+
+  rmdir "$AGENTS_SKILLS" 2>/dev/null || true
+  rmdir "$REPO_ROOT/.agents" 2>/dev/null || true
+fi
+
+if [ ${#removed[@]} -gt 0 ]; then
+  echo "Removed: ${removed[*]}"
+else
+  echo "No symlinks found."
+fi
+echo "Dev mode deactivated. Global gstack (~/.claude/skills/gstack) is now active."

bin/gstack-analytics

@@ -0,0 +1,191 @@
+#!/usr/bin/env bash
+# gstack-analytics — personal usage dashboard from local JSONL
+#
+# Usage:
+#   gstack-analytics          # default: last 7 days
+#   gstack-analytics 7d       # last 7 days
+#   gstack-analytics 30d      # last 30 days
+#   gstack-analytics all      # all time
+#
+# Env overrides (for testing):
+#   GSTACK_STATE_DIR  — override ~/.gstack state directory
+set -uo pipefail
+
+STATE_DIR="${GSTACK_STATE_DIR:-$HOME/.gstack}"
+JSONL_FILE="$STATE_DIR/analytics/skill-usage.jsonl"
+
+# ─── Parse time window ───────────────────────────────────────
+WINDOW="${1:-7d}"
+case "$WINDOW" in
+  7d)  DAYS=7;  LABEL="last 7 days" ;;
+  30d) DAYS=30; LABEL="last 30 days" ;;
+  all) DAYS=0;  LABEL="all time" ;;
+  *)   DAYS=7;  LABEL="last 7 days" ;;
+esac
+
+# ─── Check for data ──────────────────────────────────────────
+if [ ! -f "$JSONL_FILE" ]; then
+  echo "gstack usage — no data yet"
+  echo ""
+  echo "Usage data will appear here after you use gstack skills"
+  echo "with telemetry enabled (gstack-config set telemetry anonymous)."
+  exit 0
+fi
+
+TOTAL_LINES="$(wc -l < "$JSONL_FILE" | tr -d ' ')"
+if [ "$TOTAL_LINES" = "0" ]; then
+  echo "gstack usage — no data yet"
+  exit 0
+fi
+
+# ─── Filter by time window ───────────────────────────────────
+if [ "$DAYS" -gt 0 ] 2>/dev/null; then
+  # Calculate cutoff date
+  if date -v-1d +%Y-%m-%d >/dev/null 2>&1; then
+    # macOS date
+    CUTOFF="$(date -v-${DAYS}d -u +%Y-%m-%dT%H:%M:%SZ)"
+  else
+    # GNU date
+    CUTOFF="$(date -u -d "$DAYS days ago" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || echo "2000-01-01T00:00:00Z")"
+  fi
+  # Filter: skill_run events (new format) OR basic skill events (old format, no event_type)
+  # Old format: {"skill":"X","ts":"Y","repo":"Z"} (no event_type field)
+  # New format: {"event_type":"skill_run","skill":"X","ts":"Y",...}
+  FILTERED="$(awk -F'"' -v cutoff="$CUTOFF" '
+    /"ts":"/ {
+      # Skip hook_fire events
+      if (/"event":"hook_fire"/) next
+      # Skip non-skill_run new-format events
+      if (/"event_type":"/ && !/"event_type":"skill_run"/) next
+      for (i=1; i<=NF; i++) {
+        if ($i == "ts" && $(i+1) ~ /^:/) {
+          ts = $(i+2)
+          if (ts >= cutoff) { print; break }
+        }
+      }
+    }
+  ' "$JSONL_FILE")"
+else
+  # All time: include skill_run events + old-format basic events, exclude hook_fire
+  FILTERED="$(awk '/"ts":"/ && !/"event":"hook_fire"/' "$JSONL_FILE" | grep -v '"event_type":"upgrade_' 2>/dev/null || true)"
+fi
+
+if [ -z "$FILTERED" ]; then
+  echo "gstack usage ($LABEL) — no skill runs found"
+  exit 0
+fi
+
+# ─── Aggregate by skill ──────────────────────────────────────
+# Extract skill names and count
+SKILL_COUNTS="$(echo "$FILTERED" | awk -F'"' '
+  /"skill":"/ {
+    for (i=1; i<=NF; i++) {
+      if ($i == "skill" && $(i+1) ~ /^:/) {
+        skill = $(i+2)
+        counts[skill]++
+        break
+      }
+    }
+  }
+  END {
+    for (s in counts) print counts[s], s
+  }
+' | sort -rn)"
+
+# Count outcomes
+TOTAL="$(echo "$FILTERED" | wc -l | tr -d ' ')"
+SUCCESS="$(echo "$FILTERED" | grep -c '"outcome":"success"' || true)"
+SUCCESS="${SUCCESS:-0}"; SUCCESS="$(echo "$SUCCESS" | tr -d ' \n\r\t')"
+ERRORS="$(echo "$FILTERED" | grep -c '"outcome":"error"' || true)"
+ERRORS="${ERRORS:-0}"; ERRORS="$(echo "$ERRORS" | tr -d ' \n\r\t')"
+# Old format events have no outcome field — count them as successful
+NO_OUTCOME="$(echo "$FILTERED" | grep -vc '"outcome":' || true)"
+NO_OUTCOME="${NO_OUTCOME:-0}"; NO_OUTCOME="$(echo "$NO_OUTCOME" | tr -d ' \n\r\t')"
+SUCCESS=$(( SUCCESS + NO_OUTCOME ))
+
+# Calculate success rate
+if [ "$TOTAL" -gt 0 ] 2>/dev/null; then
+  SUCCESS_RATE=$(( SUCCESS * 100 / TOTAL ))
+else
+  SUCCESS_RATE=100
+fi
+
+# ─── Calculate total duration ────────────────────────────────
+TOTAL_DURATION="$(echo "$FILTERED" | awk -F'[:,]' '
+  /"duration_s"/ {
+    for (i=1; i<=NF; i++) {
+      if ($i ~ /"duration_s"/) {
+        val = $(i+1)
+        gsub(/[^0-9.]/, "", val)
+        if (val+0 > 0) total += val
+      }
+    }
+  }
+  END { printf "%.0f", total }
+')"
+
+# Format duration
+TOTAL_DURATION="${TOTAL_DURATION:-0}"
+if [ "$TOTAL_DURATION" -ge 3600 ] 2>/dev/null; then
+  HOURS=$(( TOTAL_DURATION / 3600 ))
+  MINS=$(( (TOTAL_DURATION % 3600) / 60 ))
+  DUR_DISPLAY="${HOURS}h ${MINS}m"
+elif [ "$TOTAL_DURATION" -ge 60 ] 2>/dev/null; then
+  MINS=$(( TOTAL_DURATION / 60 ))
+  DUR_DISPLAY="${MINS}m"
+else
+  DUR_DISPLAY="${TOTAL_DURATION}s"
+fi
+
+# ─── Render output ───────────────────────────────────────────
+echo "gstack usage ($LABEL)"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+# Find max count for bar scaling
+MAX_COUNT="$(echo "$SKILL_COUNTS" | head -1 | awk '{print $1}')"
+BAR_WIDTH=20
+
+echo "$SKILL_COUNTS" | while read -r COUNT SKILL; do
+  # Scale bar
+  if [ "$MAX_COUNT" -gt 0 ] 2>/dev/null; then
+    BAR_LEN=$(( COUNT * BAR_WIDTH / MAX_COUNT ))
+  else
+    BAR_LEN=1
+  fi
+  [ "$BAR_LEN" -lt 1 ] && BAR_LEN=1
+
+  # Build bar
+  BAR=""
+  i=0
+  while [ "$i" -lt "$BAR_LEN" ]; do
+    BAR="${BAR}█"
+    i=$(( i + 1 ))
+  done
+
+  # Calculate avg duration for this skill
+  AVG_DUR="$(echo "$FILTERED" | awk -v skill="$SKILL" '
+    index($0, "\"skill\":\"" skill "\"") > 0 {
+      # Extract duration_s value using split on "duration_s":
+      n = split($0, parts, "\"duration_s\":")
+      if (n >= 2) {
+        # parts[2] starts with the value, e.g. "142,"
+        gsub(/[^0-9.].*/, "", parts[2])
+        if (parts[2]+0 > 0) { total += parts[2]; count++ }
+      }
+    }
+    END { if (count > 0) printf "%.0f", total/count; else print "0" }
+  ')"
+
+  # Format avg duration
+  if [ "$AVG_DUR" -ge 60 ] 2>/dev/null; then
+    AVG_DISPLAY="$(( AVG_DUR / 60 ))m"
+  else
+    AVG_DISPLAY="${AVG_DUR}s"
+  fi
+
+  printf "  /%-20s %s  %d runs  (avg %s)\n" "$SKILL" "$BAR" "$COUNT" "$AVG_DISPLAY"
+done
+
+echo ""
+echo "Success rate: ${SUCCESS_RATE}% | Errors: ${ERRORS} | Total time: ${DUR_DISPLAY}"
+echo "Events: ${TOTAL} skill runs"

bin/gstack-artifacts-init

@@ -0,0 +1,413 @@
+#!/usr/bin/env bash
+# gstack-artifacts-init — set up ~/.gstack/ as a git repo synced to a private
+# git host (GitHub or GitLab) so a remote gbrain can ingest your artifacts
+# (CEO plans, designs, /investigate reports) as a federated source.
+#
+# Replaces gstack-brain-init in v1.27.0.0 (per D4 hard-delete; no compat
+# shim). Existing users are migrated by gstack-upgrade/migrations/v1.27.0.0.sh.
+#
+# Usage:
+#   gstack-artifacts-init [--remote <url>] [--host github|gitlab|manual]
+#                         [--url-form-supported true|false]
+#
+# Interactive by default. Pass --remote to skip the host prompt.
+#
+# Idempotent: safe to re-run. If ~/.gstack/.git already exists AND points at
+# the same remote, reconfigures drivers/hooks/attributes without clobbering
+# history. If it points at a DIFFERENT remote, refuses.
+#
+# What it does:
+#   1. git init ~/.gstack/  (or verify existing repo points at the right remote)
+#   2. Write .gitignore = "*"  (ignore everything; allowlist is explicit)
+#   3. Write .brain-allowlist  (canonical paths to sync)
+#   4. Write .brain-privacy-map.json  (paths → privacy class)
+#   5. Write .gitattributes  (register JSONL + union merge drivers)
+#   6. git config  merge.jsonl-append.driver + merge.union.driver
+#   7. Install .git/hooks/pre-commit  (defense-in-depth secret scan)
+#   8. Provider-aware repo create (gh / glab) OR manual URL paste
+#   9. Initial commit + push
+#   10. Write ~/.gstack-artifacts-remote.txt  (HTTPS URL — canonical form)
+#   11. Print "Send this to your brain admin" hookup command
+#
+# Env:
+#   GSTACK_HOME — override ~/.gstack
+#   USER — fallback for repo naming if $USER is unset
+
+set -euo pipefail
+
+GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+URL_BIN="$SCRIPT_DIR/gstack-artifacts-url"
+REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
+
+REMOTE_URL=""
+HOST_PREF=""
+URL_FORM_SUPPORTED="false"
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --remote) REMOTE_URL="$2"; shift 2 ;;
+    --host) HOST_PREF="$2"; shift 2 ;;
+    --url-form-supported) URL_FORM_SUPPORTED="$2"; shift 2 ;;
+    --help|-h) sed -n '2,32p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    *) echo "Unknown flag: $1" >&2; exit 1 ;;
+  esac
+done
+
+# ---- preconditions ----
+mkdir -p "$GSTACK_HOME"
+
+EXISTING_REMOTE=""
+if [ -d "$GSTACK_HOME/.git" ]; then
+  EXISTING_REMOTE=$(git -C "$GSTACK_HOME" remote get-url origin 2>/dev/null || echo "")
+  if [ -n "$EXISTING_REMOTE" ] && [ -n "$REMOTE_URL" ]; then
+    # Compare at the canonical level. The stored remote is SSH (for git push),
+    # the input is usually HTTPS — same logical repo, different surface form.
+    EXISTING_HTTPS=$("$URL_BIN" --to https "$EXISTING_REMOTE" 2>/dev/null || echo "$EXISTING_REMOTE")
+    INPUT_HTTPS=$("$URL_BIN" --to https "$REMOTE_URL" 2>/dev/null || echo "$REMOTE_URL")
+    if [ "$EXISTING_HTTPS" != "$INPUT_HTTPS" ]; then
+      cat >&2 <<EOF
+gstack-artifacts-init: ~/.gstack/ is already a git repo pointing at:
+  $EXISTING_REMOTE  (canonical: $EXISTING_HTTPS)
+
+You asked to init with:
+  $REMOTE_URL  (canonical: $INPUT_HTTPS)
+
+Refusing to overwrite. To switch remotes, edit manually:
+  git -C ~/.gstack remote set-url origin <url>
+EOF
+      exit 1
+    fi
+  fi
+fi
+
+# ---- detect available providers ----
+gh_ok=false
+glab_ok=false
+if command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1; then gh_ok=true; fi
+if command -v glab >/dev/null 2>&1 && glab auth status >/dev/null 2>&1; then glab_ok=true; fi
+
+# ---- choose remote URL ----
+if [ -z "$REMOTE_URL" ] && [ -n "$EXISTING_REMOTE" ]; then
+  REMOTE_URL="$EXISTING_REMOTE"
+  echo "Using existing remote: $REMOTE_URL"
+fi
+
+REPO_NAME="gstack-artifacts-${USER:-$(whoami)}"
+DESCRIPTION="gstack artifacts (CEO plans, designs, reports) — synced from ~/.gstack/projects/"
+
+# Decide host preference if not pinned by --host.
+if [ -z "$REMOTE_URL" ] && [ -z "$HOST_PREF" ]; then
+  if $gh_ok && $glab_ok; then
+    cat >&2 <<EOF
+
+gstack-artifacts-init: which git host?
+  1) GitHub      (gh CLI authenticated)
+  2) GitLab      (glab CLI authenticated)
+  3) Other / paste a private git URL
+
+EOF
+    printf "Choice [1]: " >&2
+    read -r CH || CH=""
+    case "$CH" in
+      ""|1) HOST_PREF="github" ;;
+      2) HOST_PREF="gitlab" ;;
+      3) HOST_PREF="manual" ;;
+      *) echo "Invalid choice: $CH" >&2; exit 1 ;;
+    esac
+  elif $gh_ok; then
+    HOST_PREF="github"
+    echo "Using GitHub (gh CLI authenticated; glab not available)" >&2
+  elif $glab_ok; then
+    HOST_PREF="gitlab"
+    echo "Using GitLab (glab CLI authenticated; gh not available)" >&2
+  else
+    HOST_PREF="manual"
+    echo "(Neither gh nor glab CLI authenticated — falling through to manual URL)" >&2
+  fi
+fi
+
+# ---- create repo on chosen host ----
+if [ -z "$REMOTE_URL" ]; then
+  case "$HOST_PREF" in
+    github)
+      echo "Creating GitHub repo: $REPO_NAME ..."
+      if ! gh repo create "$REPO_NAME" --private --description "$DESCRIPTION" 2>/dev/null; then
+        # Maybe already exists; try to fetch its URL.
+        REMOTE_URL=$(gh repo view "$REPO_NAME" --json url -q .url 2>/dev/null || echo "")
+        if [ -z "$REMOTE_URL" ]; then
+          echo "Failed to create or find '$REPO_NAME'. Try --remote <url>." >&2
+          exit 1
+        fi
+        echo "Repo already exists; using $REMOTE_URL"
+      else
+        REMOTE_URL=$(gh repo view "$REPO_NAME" --json url -q .url 2>/dev/null || echo "")
+      fi
+      ;;
+    gitlab)
+      echo "Creating GitLab repo: $REPO_NAME ..."
+      if ! glab repo create "$REPO_NAME" --private --description "$DESCRIPTION" 2>/dev/null; then
+        REMOTE_URL=$(glab repo view "$REPO_NAME" -F json 2>/dev/null | jq -r '.web_url // empty' 2>/dev/null || echo "")
+        if [ -z "$REMOTE_URL" ]; then
+          echo "Failed to create or find '$REPO_NAME'. Try --remote <url>." >&2
+          exit 1
+        fi
+        echo "Repo already exists; using $REMOTE_URL"
+      else
+        REMOTE_URL=$(glab repo view "$REPO_NAME" -F json 2>/dev/null | jq -r '.web_url // empty' 2>/dev/null || echo "")
+      fi
+      ;;
+    manual)
+      echo "(provide a private git URL)"
+      printf "Paste an HTTPS git URL (e.g. https://github.com/you/gstack-artifacts.git): " >&2
+      read -r REMOTE_URL || REMOTE_URL=""
+      if [ -z "$REMOTE_URL" ]; then
+        echo "No URL provided. Aborting." >&2
+        exit 1
+      fi
+      ;;
+    *) echo "Unknown --host: $HOST_PREF (expected github|gitlab|manual)" >&2; exit 1 ;;
+  esac
+fi
+
+# ---- canonicalize to HTTPS form ----
+# We store HTTPS in ~/.gstack-artifacts-remote.txt (codex Finding #10:
+# canonical form, derive SSH at push time via gstack-artifacts-url --to ssh).
+# Unrecognized forms (local bare paths, file:// URLs, self-hosted gitea, etc.)
+# pass through verbatim so unusual remotes still work.
+CANONICAL_HTTPS=$("$URL_BIN" --to https "$REMOTE_URL" 2>/dev/null || echo "")
+if [ -z "$CANONICAL_HTTPS" ]; then
+  CANONICAL_HTTPS="$REMOTE_URL"
+fi
+
+# Use SSH for git push (more reliable for repeated pushes than HTTPS+token).
+# Fall back to the canonical input if derivation fails.
+PUSH_URL=$("$URL_BIN" --to ssh "$CANONICAL_HTTPS" 2>/dev/null || echo "$CANONICAL_HTTPS")
+
+# ---- verify push URL is reachable ----
+echo "Verifying remote connectivity: $PUSH_URL"
+if ! git ls-remote "$PUSH_URL" >/dev/null 2>&1; then
+  cat >&2 <<EOF
+Remote not reachable via SSH: $PUSH_URL
+This could mean:
+  - Wrong URL
+  - SSH key not added to your git host (GitHub: gh ssh-key list; GitLab: glab ssh-key list)
+  - Network issue
+Fix and re-run gstack-artifacts-init.
+EOF
+  exit 1
+fi
+
+# ---- git init ----
+if [ ! -d "$GSTACK_HOME/.git" ]; then
+  git -C "$GSTACK_HOME" init -q -b main 2>/dev/null || git -C "$GSTACK_HOME" init -q
+  git -C "$GSTACK_HOME" branch -M main 2>/dev/null || true
+fi
+
+if [ -z "$(git -C "$GSTACK_HOME" remote 2>/dev/null)" ]; then
+  git -C "$GSTACK_HOME" remote add origin "$PUSH_URL"
+else
+  git -C "$GSTACK_HOME" remote set-url origin "$PUSH_URL"
+fi
+
+# ---- write canonical files (idempotent) ----
+cat > "$GSTACK_HOME/.gitignore" <<'EOF'
+# gstack-artifacts sync: ignore-everything base. Paths are included explicitly via
+# .brain-allowlist and `git add -f` from gstack-brain-sync. Do not edit.
+*
+EOF
+
+cat > "$GSTACK_HOME/.brain-allowlist" <<'EOF'
+# Canonical allowlist of paths that gstack-brain-sync will publish.
+# One glob per line. Anything not matching stays local.
+# Do not edit directly; managed by gstack-artifacts-init. User additions go
+# below the marker and survive re-init.
+projects/*/learnings.jsonl
+projects/*/*-reviews.jsonl
+projects/*/ceo-plans/*.md
+projects/*/ceo-plans/*/*.md
+projects/*/designs/*.md
+projects/*/designs/*/*.md
+# Project-root design / test-plan artifacts written by /office-hours,
+# /plan-eng-review, and /autoplan. The skills emit
+# `{user}-{branch}-design-{datetime}.md`,
+# `{user}-{branch}-test-plan-{datetime}.md`, and
+# `{user}-{branch}-eng-review-test-plan-{datetime}.md` at the project
+# root (not under designs/), so the existing `designs/*.md` patterns
+# miss them. Without these the cross-machine pull on machine B gets
+# the referencing CEO plan but not the underlying design / test plan
+# (#1452).
+projects/*/*-design-*.md
+projects/*/*-test-plan-*.md
+projects/*/*-eng-review-test-plan-*.md
+projects/*/timeline.jsonl
+retros/*.md
+developer-profile.json
+builder-journey.md
+builder-profile.jsonl
+# Transcripts staged in remote-http MCP mode (per plan D11 split-engine).
+# gstack-memory-ingest persists per-run dirs here when local gbrain import
+# is skipped; brain admin pulls + indexes into the remote brain.
+transcripts/run-*/*.md
+transcripts/run-*/**/*.md
+# NOT synced (machine-local UX state):
+#   projects/*/question-preferences.json (per-machine UX preferences)
+#   projects/*/question-log.jsonl (audit/derivation log stays with preferences)
+#   projects/*/question-events.jsonl (same)
+# ---- USER ADDITIONS BELOW ---- (survives re-init; above is managed)
+EOF
+
+cat > "$GSTACK_HOME/.brain-privacy-map.json" <<'EOF'
+[
+  {"pattern": "projects/*/learnings.jsonl", "class": "artifact"},
+  {"pattern": "projects/*/*-reviews.jsonl", "class": "artifact"},
+  {"pattern": "projects/*/ceo-plans/*.md", "class": "artifact"},
+  {"pattern": "projects/*/ceo-plans/*/*.md", "class": "artifact"},
+  {"pattern": "projects/*/designs/*.md", "class": "artifact"},
+  {"pattern": "projects/*/designs/*/*.md", "class": "artifact"},
+  {"pattern": "projects/*/*-design-*.md", "class": "artifact"},
+  {"pattern": "projects/*/*-test-plan-*.md", "class": "artifact"},
+  {"pattern": "projects/*/*-eng-review-test-plan-*.md", "class": "artifact"},
+  {"pattern": "retros/*.md", "class": "artifact"},
+  {"pattern": "builder-journey.md", "class": "artifact"},
+  {"pattern": "projects/*/timeline.jsonl", "class": "behavioral"},
+  {"pattern": "developer-profile.json", "class": "behavioral"},
+  {"pattern": "builder-profile.jsonl", "class": "behavioral"},
+  {"pattern": "transcripts/run-*/*.md", "class": "behavioral"},
+  {"pattern": "transcripts/run-*/**/*.md", "class": "behavioral"}
+]
+EOF
+
+cat > "$GSTACK_HOME/.gitattributes" <<'EOF'
+# gstack-artifacts: merge drivers for cross-machine sync conflicts.
+*.jsonl merge=jsonl-append
+retros/*.md merge=union
+projects/*/designs/**/*.md merge=union
+projects/*/ceo-plans/**/*.md merge=union
+projects/*/*-design-*.md merge=union
+projects/*/*-test-plan-*.md merge=union
+EOF
+
+# ---- register merge drivers in local git config ----
+git -C "$GSTACK_HOME" config merge.jsonl-append.driver "$SCRIPT_DIR/gstack-jsonl-merge %O %A %B"
+git -C "$GSTACK_HOME" config merge.jsonl-append.name "gstack JSONL append-only merger"
+git -C "$GSTACK_HOME" config merge.union.driver "cat %A %B > %A.merged && mv %A.merged %A"
+git -C "$GSTACK_HOME" config merge.union.name "union concat"
+
+# ---- install pre-commit hook (defense-in-depth) ----
+HOOK="$GSTACK_HOME/.git/hooks/pre-commit"
+mkdir -p "$(dirname "$HOOK")"
+cat > "$HOOK" <<'HOOK_EOF'
+#!/usr/bin/env bash
+# gstack-artifacts pre-commit hook — secret-scan defense-in-depth.
+# The primary scanner runs inside gstack-brain-sync BEFORE staging. This hook
+# catches any manual `git commit` a user might accidentally run against the
+# artifacts repo.
+set -uo pipefail
+
+python3 -c "
+import sys, re, subprocess
+try:
+    out = subprocess.check_output(['git', 'diff', '--cached'], stderr=subprocess.DEVNULL).decode('utf-8', 'replace')
+except Exception:
+    sys.exit(0)
+
+patterns = [
+    ('aws-access-key', re.compile(r'AKIA[0-9A-Z]{16}')),
+    ('github-token', re.compile(r'\b(gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,})')),
+    ('openai-key', re.compile(r'\bsk-[A-Za-z0-9_-]{20,}')),
+    ('pem-block', re.compile(r'-----BEGIN [A-Z ]{3,}-----')),
+    ('jwt', re.compile(r'\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b')),
+    ('bearer-token-json',
+     re.compile(r'\"(authorization|api[_-]?key|apikey|token|secret|password)\"\s*:\s*\"[A-Za-z0-9_./+=-]{16,}\"',
+                re.IGNORECASE)),
+]
+for name, rx in patterns:
+    if rx.search(out):
+        sys.stderr.write(f'gstack-artifacts pre-commit: refusing commit — {name} detected in staged diff.\n')
+        sys.stderr.write('Either edit the offending file, or if intentional, run:\n')
+        sys.stderr.write('  gstack-brain-sync --skip-file <path>  (to permanently exclude)\n')
+        sys.exit(1)
+sys.exit(0)
+"
+HOOK_EOF
+chmod +x "$HOOK"
+
+# ---- initial commit (idempotent) ----
+cd "$GSTACK_HOME"
+git add -f .gitignore .brain-allowlist .brain-privacy-map.json .gitattributes
+if git rev-parse HEAD >/dev/null 2>&1; then
+  if ! git diff --cached --quiet 2>/dev/null; then
+    git -c user.email="gstack@localhost" -c user.name="gstack-artifacts-init" \
+        commit -q -m "chore: gstack-artifacts-init (refresh sync config)"
+  fi
+else
+  git -c user.email="gstack@localhost" -c user.name="gstack-artifacts-init" \
+      commit -q -m "chore: gstack-artifacts-init"
+fi
+
+# ---- initial push ----
+if ! git push -q -u origin main 2>/dev/null; then
+  CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+  if git fetch origin 2>/dev/null && git pull --ff-only origin "$CURRENT_BRANCH" 2>/dev/null; then
+    git push -q -u origin "$CURRENT_BRANCH" || {
+      echo "Push to $PUSH_URL failed. The remote may have divergent content." >&2
+      echo "Try: cd ~/.gstack && git pull --rebase origin $CURRENT_BRANCH && git push origin $CURRENT_BRANCH" >&2
+      exit 1
+    }
+  else
+    echo "Push to $PUSH_URL failed and fetch/merge didn't help." >&2
+    echo "Manual recovery: cd ~/.gstack && git status, then push once conflicts are resolved." >&2
+    exit 1
+  fi
+fi
+
+# ---- write the remote-url helper file (HTTPS canonical) ----
+echo "$CANONICAL_HTTPS" > "$REMOTE_FILE"
+chmod 600 "$REMOTE_FILE"
+
+# ---- print brain-admin hookup command (always print, never auto-execute;
+#      codex Finding #3) ----
+SOURCE_ID="gstack-artifacts-${USER:-$(whoami)}"
+cat <<EOF
+
+gstack-artifacts-init complete.
+Repo:    $GSTACK_HOME (git)
+Remote:  $CANONICAL_HTTPS  (canonical form, in ~/.gstack-artifacts-remote.txt)
+Push:    $PUSH_URL  (derived SSH form for git push)
+
+EOF
+
+cat <<EOF
+─────────────────────────────────────────────────────────────────────────
+  Send this to your brain admin (the person who runs your gbrain server)
+─────────────────────────────────────────────────────────────────────────
+EOF
+
+if [ "$URL_FORM_SUPPORTED" = "true" ]; then
+  cat <<EOF
+On the brain host, run:
+
+  gbrain sources add $SOURCE_ID --url $CANONICAL_HTTPS --federated
+
+EOF
+else
+  cat <<EOF
+On the brain host (gbrain v0.26.x doesn't accept URLs directly yet), run:
+
+  git clone $CANONICAL_HTTPS ~/$SOURCE_ID
+  gbrain sources add $SOURCE_ID --path ~/$SOURCE_ID --federated
+
+When gbrain ships --url support, this becomes a one-liner:
+  gbrain sources add $SOURCE_ID --url $CANONICAL_HTTPS --federated
+
+EOF
+fi
+
+cat <<EOF
+After that, your CEO plans / designs / reports become searchable via
+'gbrain search' from any machine pointing at this brain.
+─────────────────────────────────────────────────────────────────────────
+
+New machine? Put a copy of $REMOTE_FILE in that machine's home directory,
+then run: gstack-artifacts-init  (it'll detect the remote and re-init).
+EOF

bin/gstack-artifacts-url

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+# gstack-artifacts-url — canonical-URL helper for the artifacts repo.
+#
+# We store the HTTPS URL as canonical (in ~/.gstack-artifacts-remote.txt) and
+# derive other forms on demand. Centralizes the regex so callers don't each
+# string-mangle, which is how URL-format bugs creep into branch logic
+# (codex Finding #10).
+#
+# Usage:
+#   gstack-artifacts-url --to ssh    <https-url>   # https → git@host:owner/repo.git
+#   gstack-artifacts-url --to https  <any-url>     # idempotent canonicalization
+#   gstack-artifacts-url --host      <any-url>     # extract hostname
+#   gstack-artifacts-url --owner-repo <any-url>    # extract owner/repo
+#
+# Inputs accepted:
+#   https://github.com/garrytan/gstack-artifacts-garrytan
+#   https://github.com/garrytan/gstack-artifacts-garrytan.git
+#   git@github.com:garrytan/gstack-artifacts-garrytan.git
+#   ssh://git@gitlab.com/garrytan/gstack-artifacts-garrytan.git
+#   git@gitlab.example.org:team/gstack-artifacts-team.git
+#
+# Output: the requested form on stdout. Exits non-zero on parse failure with
+# an error on stderr.
+set -euo pipefail
+
+usage() {
+  echo "Usage: gstack-artifacts-url --to {ssh|https} <url>" >&2
+  echo "       gstack-artifacts-url --host <url>" >&2
+  echo "       gstack-artifacts-url --owner-repo <url>" >&2
+  exit 2
+}
+
+[ $# -ge 2 ] || usage
+
+mode=""
+to=""
+case "$1" in
+  --to) mode="to"; to="$2"; shift 2 ;;
+  --host) mode="host"; shift ;;
+  --owner-repo) mode="owner-repo"; shift ;;
+  *) usage ;;
+esac
+
+[ $# -eq 1 ] || usage
+url="$1"
+
+# Strip trailing .git for normalization; reattach where needed.
+strip_git() {
+  echo "${1%.git}"
+}
+
+# Parse to (host, owner_repo) regardless of input shape.
+parse_url() {
+  local u="$1"
+  local host="" owner_repo=""
+  case "$u" in
+    https://*)
+      # https://host/owner/repo[.git]
+      local rest="${u#https://}"
+      host="${rest%%/*}"
+      owner_repo="${rest#*/}"
+      owner_repo=$(strip_git "$owner_repo")
+      ;;
+    ssh://*)
+      # ssh://git@host/owner/repo[.git] OR ssh://host/owner/repo[.git]
+      local rest="${u#ssh://}"
+      # Strip optional user@
+      rest="${rest#*@}"
+      host="${rest%%/*}"
+      owner_repo="${rest#*/}"
+      owner_repo=$(strip_git "$owner_repo")
+      ;;
+    git@*:*)
+      # git@host:owner/repo[.git]
+      local rest="${u#git@}"
+      host="${rest%%:*}"
+      owner_repo="${rest#*:}"
+      owner_repo=$(strip_git "$owner_repo")
+      ;;
+    *)
+      echo "gstack-artifacts-url: unrecognized URL form: $u" >&2
+      exit 3
+      ;;
+  esac
+  if [ -z "$host" ] || [ -z "$owner_repo" ] || [ "$owner_repo" = "$u" ]; then
+    echo "gstack-artifacts-url: failed to parse host/owner from: $u" >&2
+    exit 3
+  fi
+  printf '%s\n%s\n' "$host" "$owner_repo"
+}
+
+parsed=$(parse_url "$url")
+host=$(echo "$parsed" | head -1)
+owner_repo=$(echo "$parsed" | tail -1)
+
+case "$mode" in
+  to)
+    case "$to" in
+      ssh)   printf 'git@%s:%s.git\n' "$host" "$owner_repo" ;;
+      https) printf 'https://%s/%s\n' "$host" "$owner_repo" ;;
+      *) usage ;;
+    esac
+    ;;
+  host)       printf '%s\n' "$host" ;;
+  owner-repo) printf '%s\n' "$owner_repo" ;;
+esac

bin/gstack-brain-consumer

@@ -0,0 +1,201 @@
+#!/usr/bin/env bash
+# gstack-brain-consumer — manage the consumer (reader) registry.
+#
+# DEPRECATED in v1.17.0.0. This binary targets a gbrain HTTP /ingest-repo
+# endpoint that never shipped on the gbrain side. Live federation now uses
+# `gbrain sources` directly via bin/gstack-gbrain-source-wireup. This file
+# stays for one cycle to avoid breaking external scripts; removal in v1.18.0.0.
+#
+# Consumer = a reader that ingests the gstack-brain git repo as a source of
+# session memory. v1 primary consumer is GBrain; later versions can register
+# Codex, OpenClaw, or third-party readers.
+#
+# NOTE ON NAMING: internally this helper uses "consumer" (correct data-model
+# term). User-facing copy and the alias `gstack-brain-reader` use "reader"
+# (matches user mental model: "what's reading my brain?").
+#
+# Usage:
+#   gstack-brain-consumer add <name> --ingest-url <url> --token <token>
+#   gstack-brain-consumer list
+#   gstack-brain-consumer remove <name>
+#   gstack-brain-consumer test <name>
+#
+# Env:
+#   GSTACK_HOME — override ~/.gstack
+
+set -euo pipefail
+
+GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
+CONSUMERS_FILE="$GSTACK_HOME/consumers.json"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+CONFIG_BIN="$SCRIPT_DIR/gstack-config"
+
+ensure_file() {
+  mkdir -p "$GSTACK_HOME"
+  if [ ! -f "$CONSUMERS_FILE" ]; then
+    echo '{"consumers": []}' > "$CONSUMERS_FILE"
+  fi
+}
+
+get_remote_url() {
+  git -C "$GSTACK_HOME" remote get-url origin 2>/dev/null || echo ""
+}
+
+sub_add() {
+  local name="" url="" token=""
+  local positional=""
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --ingest-url) url="$2"; shift 2 ;;
+      --token) token="$2"; shift 2 ;;
+      --) shift; break ;;
+      -*) echo "Unknown flag: $1" >&2; exit 1 ;;
+      *) positional="$1"; shift ;;
+    esac
+  done
+  name="$positional"
+  if [ -z "$name" ] || [ -z "$url" ]; then
+    echo "Usage: gstack-brain-consumer add <name> --ingest-url <url> [--token <token>]" >&2
+    exit 1
+  fi
+  ensure_file
+  # Upsert in consumers.json, store token in gstack-config under `<name>_token`.
+  python3 - "$CONSUMERS_FILE" "$name" "$url" <<'PYEOF'
+import sys, json
+path, name, url = sys.argv[1:4]
+try:
+    with open(path) as f:
+        data = json.load(f)
+except Exception:
+    data = {"consumers": []}
+entry = {"name": name, "ingest_url": url, "status": "unknown", "token_ref": f"{name}_token"}
+cs = data.setdefault("consumers", [])
+for i, c in enumerate(cs):
+    if c.get("name") == name:
+        cs[i] = entry
+        break
+else:
+    cs.append(entry)
+with open(path, "w") as f:
+    json.dump(data, f, indent=2)
+    f.write("\n")
+print(f"registered consumer: {name}")
+PYEOF
+  if [ -n "$token" ]; then
+    "$CONFIG_BIN" set "${name}_token" "$token"
+    echo "token stored: gstack-config get ${name}_token to retrieve"
+  fi
+  # Attempt registration with remote (HTTP POST).
+  sub_test "$name"
+}
+
+sub_list() {
+  if [ ! -f "$CONSUMERS_FILE" ]; then
+    echo '{"consumers": []}'
+    return 0
+  fi
+  cat "$CONSUMERS_FILE"
+}
+
+sub_remove() {
+  local name="${1:-}"
+  if [ -z "$name" ]; then
+    echo "Usage: gstack-brain-consumer remove <name>" >&2
+    exit 1
+  fi
+  ensure_file
+  python3 - "$CONSUMERS_FILE" "$name" <<'PYEOF'
+import sys, json
+path, name = sys.argv[1:3]
+try:
+    with open(path) as f:
+        data = json.load(f)
+except Exception:
+    data = {"consumers": []}
+before = len(data.get("consumers", []))
+data["consumers"] = [c for c in data.get("consumers", []) if c.get("name") != name]
+after = len(data["consumers"])
+with open(path, "w") as f:
+    json.dump(data, f, indent=2)
+    f.write("\n")
+print(f"removed: {before - after} entry(ies)")
+PYEOF
+}
+
+sub_test() {
+  local name="${1:-}"
+  if [ -z "$name" ]; then
+    echo "Usage: gstack-brain-consumer test <name>" >&2
+    exit 1
+  fi
+  ensure_file
+  # Look up the consumer by name.
+  local info
+  info=$(python3 - "$CONSUMERS_FILE" "$name" <<'PYEOF'
+import sys, json
+path, name = sys.argv[1:3]
+try:
+    with open(path) as f:
+        data = json.load(f)
+except Exception:
+    data = {"consumers": []}
+for c in data.get("consumers", []):
+    if c.get("name") == name:
+        print(c.get("ingest_url", ""))
+        sys.exit(0)
+sys.exit(1)
+PYEOF
+  ) || { echo "No such consumer: $name" >&2; exit 1; }
+
+  local url="$info"
+  local token
+  token=$("$CONFIG_BIN" get "${name}_token" 2>/dev/null || echo "")
+  if [ -z "$url" ] || [ -z "$token" ]; then
+    echo "consumer '$name': url or token missing; cannot test"
+    return 0
+  fi
+  local repo_url
+  repo_url=$(get_remote_url)
+  echo "Testing $name at ${url%/}/ingest-repo ..."
+  local resp
+  resp=$(curl -sS -X POST "${url%/}/ingest-repo" \
+    -H "Authorization: Bearer $token" \
+    -H "Content-Type: application/json" \
+    --data "{\"repo_url\":\"$repo_url\"}" \
+    -w "\n%{http_code}" 2>&1 || echo -e "\ncurl-error")
+  local code
+  code=$(echo "$resp" | tail -1)
+  if [ "$code" = "200" ] || [ "$code" = "201" ] || [ "$code" = "204" ]; then
+    echo "ok (HTTP $code)"
+    # Update status in consumers.json.
+    python3 - "$CONSUMERS_FILE" "$name" "ok" <<'PYEOF'
+import sys, json
+path, name, status = sys.argv[1:4]
+with open(path) as f: data = json.load(f)
+for c in data.get("consumers", []):
+    if c.get("name") == name:
+        c["status"] = status
+with open(path, "w") as f: json.dump(data, f, indent=2); f.write("\n")
+PYEOF
+  else
+    echo "failed (HTTP $code)"
+    python3 - "$CONSUMERS_FILE" "$name" "error" <<'PYEOF'
+import sys, json
+path, name, status = sys.argv[1:4]
+with open(path) as f: data = json.load(f)
+for c in data.get("consumers", []):
+    if c.get("name") == name:
+        c["status"] = status
+with open(path, "w") as f: json.dump(data, f, indent=2); f.write("\n")
+PYEOF
+  fi
+}
+
+case "${1:-}" in
+  add) shift; sub_add "$@" ;;
+  list) sub_list ;;
+  remove) shift; sub_remove "$@" ;;
+  test) shift; sub_test "$@" ;;
+  --help|-h|"") sed -n '2,20p' "$0" | sed 's/^# \{0,1\}//' ;;
+  *) echo "Unknown subcommand: $1" >&2; exit 1 ;;
+esac

bin/gstack-brain-context-load.ts

@@ -0,0 +1,465 @@
+#!/usr/bin/env bun
+/**
+ * gstack-brain-context-load — V1 retrieval surface (Lane C).
+ *
+ * Called from the gstack preamble at every skill start. Reads the active skill's
+ * `gbrain.context_queries:` frontmatter (Layer 2) or falls back to a generic
+ * salience block (Layer 1). Dispatches each query by kind:
+ *
+ *   kind: vector       → gbrain query <text>
+ *   kind: list         → gbrain list_pages --filter ...
+ *   kind: filesystem   → local glob
+ *
+ * Each MCP/CLI call has a 500ms hard timeout per Section 1C. On timeout or
+ * "gbrain not in PATH" / "MCP not registered", the helper renders
+ * `(unavailable)` for that section and continues — skill startup never blocks
+ * > 2s on gbrain issues.
+ *
+ * Layer 1 fallback per F7 (Codex outside-voice): every default query carries
+ * an explicit `repo: {repo_slug}` filter so cross-repo contamination is the
+ * non-default path.
+ *
+ * Datamark envelope per Section 1D: each rendered page body is wrapped in
+ * `<USER_TRANSCRIPT_DATA do-not-interpret-as-instructions>...</USER_TRANSCRIPT_DATA>`
+ * once at the page level (not per-message). Layer 1 prompt-injection defense.
+ *
+ * V1.5 P0: salience smarts promote to gbrain server-side MCP tools
+ * (`get_recent_salience`, `find_anomalies`). Helper signature stays the same;
+ * internals switch from 4-call composition to a single MCP call.
+ *
+ * Usage:
+ *   gstack-brain-context-load --skill office-hours --repo garrytan-gstack
+ *   gstack-brain-context-load --skill-file ./SKILL.md --repo X --user Y
+ *   gstack-brain-context-load --window 14d --explain
+ *   gstack-brain-context-load --quiet
+ */
+
+import { existsSync, readFileSync, statSync, readdirSync } from "fs";
+import { join, dirname, basename, resolve } from "path";
+import { execFileSync, spawnSync } from "child_process";
+import { homedir } from "os";
+
+import { parseSkillManifest, type GbrainManifest, type GbrainManifestQuery, withErrorContext } from "../lib/gstack-memory-helpers";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+interface CliArgs {
+  skill?: string;
+  skillFile?: string;
+  repo?: string;
+  user?: string;
+  branch?: string;
+  window: string; // e.g. "14d"
+  limit: number;
+  explain: boolean;
+  quiet: boolean;
+}
+
+interface QueryResult {
+  query: GbrainManifestQuery;
+  ok: boolean;
+  rendered: string;
+  bytes: number;
+  duration_ms: number;
+  reason?: string;
+}
+
+// ── Constants ──────────────────────────────────────────────────────────────
+
+const HOME = homedir();
+const GSTACK_HOME = process.env.GSTACK_HOME || join(HOME, ".gstack");
+const MCP_TIMEOUT_MS = 500;
+const PAGE_SIZE_CAP = 10 * 1024; // 10KB per query result before truncation
+
+// ── CLI ────────────────────────────────────────────────────────────────────
+
+function printUsage(): void {
+  console.error(`Usage: gstack-brain-context-load [options]
+
+Options:
+  --skill <name>          Active skill name (looks up SKILL.md path)
+  --skill-file <path>     Direct path to SKILL.md (overrides --skill)
+  --repo <slug>           Repo slug for {repo_slug} template var
+  --user <slug>           User slug for {user_slug} template var
+  --branch <name>         Branch name for {branch} template var
+  --window <Nd>           Layer 1 window (default: 14d)
+  --limit <N>             Max results per query (default: from manifest, else 10)
+  --explain               Print byte counts + which queries ran (to stderr)
+  --quiet                 Suppress everything except the rendered block
+  --help                  This text.
+
+Output: rendered ## sections to stdout, ready for the preamble to inject.
+`);
+}
+
+function parseArgs(): CliArgs {
+  const args = process.argv.slice(2);
+  let skill: string | undefined;
+  let skillFile: string | undefined;
+  let repo: string | undefined;
+  let user: string | undefined;
+  let branch: string | undefined;
+  let window = "14d";
+  let limit = 10;
+  let explain = false;
+  let quiet = false;
+
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    switch (a) {
+      case "--skill": skill = args[++i]; break;
+      case "--skill-file": skillFile = args[++i]; break;
+      case "--repo": repo = args[++i]; break;
+      case "--user": user = args[++i]; break;
+      case "--branch": branch = args[++i]; break;
+      case "--window": window = args[++i] || "14d"; break;
+      case "--limit":
+        limit = parseInt(args[++i] || "10", 10);
+        if (!Number.isFinite(limit) || limit <= 0) {
+          console.error("--limit requires a positive integer");
+          process.exit(1);
+        }
+        break;
+      case "--explain": explain = true; break;
+      case "--quiet": quiet = true; break;
+      case "--help":
+      case "-h":
+        printUsage();
+        process.exit(0);
+      default:
+        console.error(`Unknown argument: ${a}`);
+        printUsage();
+        process.exit(1);
+    }
+  }
+
+  return { skill, skillFile, repo, user, branch, window, limit, explain, quiet };
+}
+
+// ── Template var substitution ──────────────────────────────────────────────
+
+function substituteTemplateVars(s: string, args: CliArgs): { resolved: string; unresolved: string[] } {
+  const unresolved: string[] = [];
+  const resolved = s.replace(/\{(\w+)\}/g, (full, name) => {
+    switch (name) {
+      case "repo_slug":
+        if (args.repo) return args.repo;
+        unresolved.push(name);
+        return full;
+      case "user_slug":
+        if (args.user) return args.user;
+        unresolved.push(name);
+        return full;
+      case "branch":
+        if (args.branch) return args.branch;
+        unresolved.push(name);
+        return full;
+      case "skill_name":
+        if (args.skill) return args.skill;
+        unresolved.push(name);
+        return full;
+      case "window":
+        return args.window;
+      default:
+        unresolved.push(name);
+        return full;
+    }
+  });
+  return { resolved, unresolved };
+}
+
+// ── Skill manifest resolution ──────────────────────────────────────────────
+
+function resolveSkillFile(args: CliArgs): string | null {
+  if (args.skillFile) {
+    return resolve(args.skillFile);
+  }
+  if (!args.skill) return null;
+  // Look in common gstack skill locations
+  const candidates = [
+    join(HOME, ".claude", "skills", args.skill, "SKILL.md"),
+    join(HOME, ".claude", "skills", "gstack", args.skill, "SKILL.md"),
+    join(process.cwd(), ".claude", "skills", args.skill, "SKILL.md"),
+    join(process.cwd(), args.skill, "SKILL.md"),
+  ];
+  for (const c of candidates) {
+    if (existsSync(c)) return c;
+  }
+  return null;
+}
+
+// ── Dispatchers ────────────────────────────────────────────────────────────
+
+function gbrainAvailable(): boolean {
+  try {
+    execFileSync("command", ["-v", "gbrain"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function dispatchVector(q: GbrainManifestQuery, args: CliArgs): QueryResult {
+  const t0 = Date.now();
+  const { resolved: query, unresolved } = substituteTemplateVars(q.query || "", args);
+  if (unresolved.length > 0) {
+    return {
+      query: q,
+      ok: false,
+      rendered: "",
+      bytes: 0,
+      duration_ms: Date.now() - t0,
+      reason: `template vars unresolved: ${unresolved.join(",")}`,
+    };
+  }
+  if (!gbrainAvailable()) {
+    return { query: q, ok: false, rendered: "", bytes: 0, duration_ms: Date.now() - t0, reason: "gbrain CLI missing" };
+  }
+
+  const limit = q.limit ?? args.limit;
+  const result = spawnSync("gbrain", ["query", query, "--limit", String(limit), "--format", "compact"], {
+    encoding: "utf-8",
+    timeout: MCP_TIMEOUT_MS,
+  });
+
+  if (result.status !== 0 || !result.stdout) {
+    return {
+      query: q,
+      ok: false,
+      rendered: "",
+      bytes: 0,
+      duration_ms: Date.now() - t0,
+      reason: result.error?.message || `gbrain query exited ${result.status}`,
+    };
+  }
+
+  const rendered = wrapDatamarked(q.render_as, capBody(result.stdout));
+  return { query: q, ok: true, rendered, bytes: rendered.length, duration_ms: Date.now() - t0 };
+}
+
+function dispatchList(q: GbrainManifestQuery, args: CliArgs): QueryResult {
+  const t0 = Date.now();
+  if (!gbrainAvailable()) {
+    return { query: q, ok: false, rendered: "", bytes: 0, duration_ms: Date.now() - t0, reason: "gbrain CLI missing" };
+  }
+  const limit = q.limit ?? args.limit;
+  const cliArgs: string[] = ["list_pages", "--limit", String(limit)];
+  if (q.sort) cliArgs.push("--sort", q.sort);
+  if (q.filter) {
+    for (const [k, v] of Object.entries(q.filter)) {
+      const { resolved: rv } = substituteTemplateVars(String(v), args);
+      cliArgs.push("--filter", `${k}=${rv}`);
+    }
+  }
+  const result = spawnSync("gbrain", cliArgs, { encoding: "utf-8", timeout: MCP_TIMEOUT_MS });
+  if (result.status !== 0 || !result.stdout) {
+    return {
+      query: q,
+      ok: false,
+      rendered: "",
+      bytes: 0,
+      duration_ms: Date.now() - t0,
+      reason: result.error?.message || `gbrain list_pages exited ${result.status}`,
+    };
+  }
+  const rendered = wrapDatamarked(q.render_as, capBody(result.stdout));
+  return { query: q, ok: true, rendered, bytes: rendered.length, duration_ms: Date.now() - t0 };
+}
+
+function dispatchFilesystem(q: GbrainManifestQuery, args: CliArgs): QueryResult {
+  const t0 = Date.now();
+  if (!q.glob) {
+    return { query: q, ok: false, rendered: "", bytes: 0, duration_ms: Date.now() - t0, reason: "filesystem kind missing glob" };
+  }
+  const { resolved: glob, unresolved } = substituteTemplateVars(q.glob, args);
+  if (unresolved.length > 0) {
+    return {
+      query: q,
+      ok: false,
+      rendered: "",
+      bytes: 0,
+      duration_ms: Date.now() - t0,
+      reason: `template vars unresolved: ${unresolved.join(",")}`,
+    };
+  }
+  // Expand ~ to home dir
+  const expanded = glob.replace(/^~/, HOME);
+
+  // Simple glob: match against filesystem
+  const matches = simpleGlob(expanded);
+  if (matches.length === 0) {
+    return { query: q, ok: false, rendered: "", bytes: 0, duration_ms: Date.now() - t0, reason: "no matches" };
+  }
+
+  // Sort + limit
+  let sorted = matches;
+  if (q.sort === "mtime_desc") {
+    sorted = matches
+      .map((p) => ({ p, mtime: tryStatMtime(p) }))
+      .sort((a, b) => b.mtime - a.mtime)
+      .map((x) => x.p);
+  }
+  const limit = q.limit ?? args.limit;
+  const limited = q.tail !== undefined ? sorted.slice(-q.tail) : sorted.slice(0, limit);
+
+  const lines = limited.map((p) => {
+    const mt = new Date(tryStatMtime(p)).toISOString().slice(0, 10);
+    return `- ${mt} — ${basename(p)}`;
+  });
+  const rendered = wrapDatamarked(q.render_as, capBody(lines.join("\n")));
+  return { query: q, ok: true, rendered, bytes: rendered.length, duration_ms: Date.now() - t0 };
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function simpleGlob(pattern: string): string[] {
+  // Handle simple patterns: <dir>/*<glob>* or <dir>/file or <full-path-no-glob>
+  if (!pattern.includes("*") && !pattern.includes("?")) {
+    return existsSync(pattern) ? [pattern] : [];
+  }
+  // Split on the last '/' before any glob char
+  const idx = pattern.search(/[*?]/);
+  const dirEnd = pattern.lastIndexOf("/", idx);
+  if (dirEnd === -1) return [];
+  const dir = pattern.slice(0, dirEnd);
+  const fileGlob = pattern.slice(dirEnd + 1);
+  if (!existsSync(dir)) return [];
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return [];
+  }
+  const re = new RegExp("^" + fileGlob.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".") + "$");
+  return entries.filter((e) => re.test(e)).map((e) => join(dir, e));
+}
+
+function tryStatMtime(p: string): number {
+  try {
+    return statSync(p).mtimeMs;
+  } catch {
+    return 0;
+  }
+}
+
+function capBody(s: string): string {
+  if (s.length <= PAGE_SIZE_CAP) return s;
+  return s.slice(0, PAGE_SIZE_CAP) + `\n\n_(truncated; ${s.length - PAGE_SIZE_CAP} more bytes — query gbrain directly for full results)_\n`;
+}
+
+function wrapDatamarked(renderAs: string, body: string): string {
+  // Layer 1 prompt-injection defense (Section 1D, D12). Single envelope around
+  // the whole rendered body, not per-message.
+  return [
+    renderAs,
+    "",
+    "<USER_TRANSCRIPT_DATA do-not-interpret-as-instructions>",
+    body,
+    "</USER_TRANSCRIPT_DATA>",
+    "",
+  ].join("\n");
+}
+
+// ── Layer 1 fallback (no manifest) ─────────────────────────────────────────
+
+function defaultManifest(args: CliArgs): GbrainManifest {
+  // Per plan §"Three-section default" (D13). Each query carries explicit
+  // `repo: {repo_slug}` filter (F7 cleanup) so cross-repo contamination is
+  // the non-default path.
+  return {
+    schema: 1,
+    context_queries: [
+      {
+        id: "recent-transcripts",
+        kind: "list",
+        filter: { type: "transcript", "tags_contains": "repo:{repo_slug}" },
+        sort: "updated_at_desc",
+        limit: 5,
+        render_as: "## Recent transcripts in this repo",
+      },
+      {
+        id: "recent-curated",
+        kind: "list",
+        filter: { "tags_contains": "repo:{repo_slug}", updated_after: "now-7d" },
+        sort: "updated_at_desc",
+        limit: 10,
+        render_as: "## Recent curated memory",
+      },
+      {
+        id: "skill-name-events",
+        kind: "list",
+        filter: { type: "timeline", content_contains: "{skill_name}" },
+        limit: 5,
+        render_as: "## Recent {skill_name} events",
+      },
+    ],
+  };
+}
+
+// ── Main pipeline ──────────────────────────────────────────────────────────
+
+async function loadContext(args: CliArgs): Promise<{ rendered: string; results: QueryResult[]; mode: "manifest" | "default" }> {
+  const skillFile = resolveSkillFile(args);
+  let manifest: GbrainManifest | null = null;
+  let mode: "manifest" | "default" = "default";
+
+  if (skillFile) {
+    manifest = parseSkillManifest(skillFile);
+    if (manifest && manifest.context_queries.length > 0) {
+      mode = "manifest";
+    }
+  }
+  if (!manifest) {
+    manifest = defaultManifest(args);
+  }
+
+  const results: QueryResult[] = [];
+  for (const q of manifest.context_queries) {
+    const r = await withErrorContext(`context-load:${q.id}`, () => {
+      switch (q.kind) {
+        case "vector": return dispatchVector(q, args);
+        case "list": return dispatchList(q, args);
+        case "filesystem": return dispatchFilesystem(q, args);
+      }
+    }, "gstack-brain-context-load");
+    results.push(r);
+  }
+
+  // Substitute render_as template vars (e.g. "{skill_name}")
+  const rendered = results
+    .filter((r) => r.ok && r.rendered.length > 0)
+    .map((r) => {
+      const { resolved } = substituteTemplateVars(r.rendered, args);
+      return resolved;
+    })
+    .join("\n");
+
+  return { rendered, results, mode };
+}
+
+// ── Entry point ────────────────────────────────────────────────────────────
+
+async function main(): Promise<void> {
+  const args = parseArgs();
+  const { rendered, results, mode } = await loadContext(args);
+
+  if (!args.quiet && rendered.length > 0) {
+    console.log(rendered);
+  }
+
+  if (args.explain) {
+    console.error(`[brain-context-load] mode=${mode} queries=${results.length}`);
+    for (const r of results) {
+      const status = r.ok ? "OK" : "SKIP";
+      console.error(`  ${status.padEnd(5)} ${r.query.id.padEnd(28)} kind=${r.query.kind.padEnd(10)} bytes=${r.bytes.toString().padStart(6)} dur=${r.duration_ms}ms${r.reason ? ` (${r.reason})` : ""}`);
+    }
+    const totalBytes = results.reduce((s, r) => s + r.bytes, 0);
+    const totalDur = results.reduce((s, r) => s + r.duration_ms, 0);
+    console.error(`[brain-context-load] total bytes=${totalBytes} dur=${totalDur}ms`);
+  }
+}
+
+main().catch((err) => {
+  console.error(`gstack-brain-context-load fatal: ${err instanceof Error ? err.message : String(err)}`);
+  process.exit(1);
+});

bin/gstack-brain-enqueue

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# gstack-brain-enqueue — atomically append a path to the GBrain sync queue.
+#
+# Usage:
+#   gstack-brain-enqueue <file-path>
+#
+# Called by writer scripts (gstack-learnings-log, gstack-timeline-log, etc.)
+# after their local write. Fire-and-forget; failures are silent (never blocks
+# the writer). Queue is drained by `gstack-brain-sync --once` invoked from the
+# preamble at skill START and END boundaries.
+#
+# No-op when:
+#   - artifacts_sync_mode is off (the default)
+#   - ~/.gstack/.git doesn't exist (feature not initialized)
+#   - <file-path> matches a line in ~/.gstack/.brain-skip.txt
+#
+# Env:
+#   GSTACK_HOME — override ~/.gstack state directory (aligns with writers).
+#                 Tests use GSTACK_HOME=/tmp/test-$$ for isolation.
+#
+# Concurrency: POSIX append is atomic up to PIPE_BUF (~4KB Linux, 512 BSD).
+# Queue lines are ~200 bytes, safe under concurrent callers.
+
+# No `-e` — writer shims rely on this never failing loudly.
+set -uo pipefail
+
+FILE="${1:-}"
+[ -z "$FILE" ] && exit 0
+
+GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
+QUEUE="$GSTACK_HOME/.brain-queue.jsonl"
+SKIP_FILE="$GSTACK_HOME/.brain-skip.txt"
+
+# Fast exits: no git repo, no sync.
+[ ! -d "$GSTACK_HOME/.git" ] && exit 0
+
+# Check sync mode. off → silent no-op.
+SCRIPT_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd)"
+MODE=$("$SCRIPT_DIR/gstack-config" get artifacts_sync_mode 2>/dev/null || echo off)
+[ "$MODE" = "off" ] && exit 0
+
+# User-maintained skip list (for secret-scan false positives).
+if [ -f "$SKIP_FILE" ]; then
+  if grep -Fxq "$FILE" "$SKIP_FILE" 2>/dev/null; then
+    exit 0
+  fi
+fi
+
+# JSON-escape the file path (backslash + quotes only; paths shouldn't have other specials).
+ESC_FILE=$(printf '%s' "$FILE" | sed 's/\\/\\\\/g; s/"/\\"/g')
+TS=$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || echo "")
+
+printf '{"file":"%s","ts":"%s"}\n' "$ESC_FILE" "$TS" >> "$QUEUE" 2>/dev/null
+
+exit 0

bin/gstack-brain-reader

@@ -0,0 +1 @@
+gstack-brain-consumer

bin/gstack-brain-restore

@@ -0,0 +1,229 @@
+#!/usr/bin/env bash
+# gstack-brain-restore — bootstrap a new machine from an existing brain repo.
+#
+# Usage:
+#   gstack-brain-restore [<git-remote-url>]
+#
+# If no URL is given, reads from ~/.gstack-brain-remote.txt (written by
+# gstack-brain-init on the original machine). Copy that file to the new
+# machine before running this command.
+#
+# Safety gates (refuses with clear message):
+#   - ~/.gstack/.git already exists with a DIFFERENT remote
+#   - ~/.gstack/ contains non-allowlisted, non-gitignored user files
+#     that would be clobbered by restore
+#
+# What it does:
+#   1. Clone the remote to a staging directory
+#   2. Validate the repo is gstack-brain-shaped (.brain-allowlist, .gitattributes)
+#   3. rsync-copy tracked files into ~/.gstack/ with skip-if-same-hash
+#   4. Move staging's .git into ~/.gstack/.git
+#   5. Register local git config merge drivers (they don't clone from remote)
+#   6. Wire the cloned brain into gbrain via gstack-gbrain-source-wireup
+#      (best-effort; restore continues even if gbrain wireup fails)
+#
+# Env:
+#   GSTACK_HOME — override ~/.gstack
+
+set -euo pipefail
+
+GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+CONFIG_BIN="$SCRIPT_DIR/gstack-config"
+# v1.27.0.0+ canonical name; brain-remote is the legacy fallback during the
+# migration window. The migration script renames the file in place.
+if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
+  REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
+else
+  REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
+fi
+
+REMOTE_URL="${1:-}"
+if [ -z "$REMOTE_URL" ]; then
+  if [ -f "$REMOTE_FILE" ]; then
+    REMOTE_URL=$(head -1 "$REMOTE_FILE" | tr -d '[:space:]')
+  fi
+fi
+
+if [ -z "$REMOTE_URL" ]; then
+  cat >&2 <<EOF
+gstack-brain-restore: no remote URL provided.
+
+Provide one of:
+  gstack-brain-restore <git-url>
+  or put the URL in $REMOTE_FILE (copy from the original machine)
+EOF
+  exit 1
+fi
+
+# ---- safety gates ----
+if [ -d "$GSTACK_HOME/.git" ]; then
+  EXISTING_REMOTE=$(git -C "$GSTACK_HOME" remote get-url origin 2>/dev/null || echo "")
+  if [ -n "$EXISTING_REMOTE" ] && [ "$EXISTING_REMOTE" != "$REMOTE_URL" ]; then
+    cat >&2 <<EOF
+gstack-brain-restore: ~/.gstack/.git already points at:
+  $EXISTING_REMOTE
+
+You asked to restore from:
+  $REMOTE_URL
+
+Refusing to overwrite. Run 'gstack-brain-uninstall' first or pass a matching URL.
+EOF
+    exit 1
+  fi
+fi
+
+# ---- clone to staging ----
+STAGING=$(mktemp -d "${TMPDIR:-/tmp}/gstack-brain-restore.XXXXXX")
+trap 'rm -rf "$STAGING" 2>/dev/null' EXIT
+
+echo "Cloning $REMOTE_URL to staging..."
+if ! git clone --quiet "$REMOTE_URL" "$STAGING/repo" 2>/dev/null; then
+  echo "Clone failed. Check:" >&2
+  echo "  - URL is correct: $REMOTE_URL" >&2
+  echo "  - Auth: gh auth status (github) / glab auth status (gitlab)" >&2
+  exit 1
+fi
+
+# ---- validate shape ----
+if [ ! -f "$STAGING/repo/.brain-allowlist" ] || [ ! -f "$STAGING/repo/.gitattributes" ]; then
+  cat >&2 <<EOF
+gstack-brain-restore: $REMOTE_URL does not look like a gstack-brain repo.
+Missing: .brain-allowlist and/or .gitattributes
+
+This command only works on repos created by gstack-brain-init.
+EOF
+  exit 1
+fi
+
+# ---- validate target ~/.gstack/ has no non-gitignored user files ----
+mkdir -p "$GSTACK_HOME"
+if [ ! -d "$GSTACK_HOME/.git" ]; then
+  # No existing git → check if we'd clobber anything allowlisted.
+  # Read the new allowlist globs and see if any existing files would collide.
+  CLOBBER_RISK=$(python3 - "$GSTACK_HOME" "$STAGING/repo/.brain-allowlist" <<'PYEOF'
+import sys, os, fnmatch
+home, allowlist_path = sys.argv[1:3]
+try:
+    with open(allowlist_path) as f:
+        globs = [l.strip() for l in f if l.strip() and not l.lstrip().startswith('#')]
+except FileNotFoundError:
+    globs = []
+risks = []
+for root, dirs, files in os.walk(home):
+    dirs[:] = [d for d in dirs if d != '.git']
+    for name in files:
+        full = os.path.join(root, name)
+        rel = os.path.relpath(full, home)
+        for g in globs:
+            if fnmatch.fnmatchcase(rel, g):
+                risks.append(rel)
+                break
+for r in risks[:5]:
+    print(r)
+if len(risks) > 5:
+    print(f"...and {len(risks) - 5} more")
+sys.exit(0 if not risks else 2)
+PYEOF
+  ) || true
+  if [ -n "$CLOBBER_RISK" ]; then
+    cat >&2 <<EOF
+gstack-brain-restore: ~/.gstack/ has existing allowlisted files that would
+be clobbered by restore:
+
+$CLOBBER_RISK
+
+Back these up first, or run this command on a machine with an empty
+~/.gstack/. If these files are from an earlier gstack session on THIS
+machine, you probably want to run gstack-brain-init instead (to create a
+new brain repo with this machine's state).
+EOF
+    exit 1
+  fi
+fi
+
+# ---- copy tracked files in ----
+echo "Copying tracked files into ~/.gstack/ ..."
+# Use git-ls-tree to get exact tracked file list (avoids staged/untracked files).
+cd "$STAGING/repo"
+git ls-tree -r --name-only HEAD | while IFS= read -r rel_path; do
+  src="$STAGING/repo/$rel_path"
+  dst="$GSTACK_HOME/$rel_path"
+  mkdir -p "$(dirname "$dst")"
+  # Skip if identical (content hash). Otherwise copy.
+  if [ -f "$dst" ] && cmp -s "$src" "$dst"; then
+    continue
+  fi
+  cp "$src" "$dst"
+done
+
+# ---- move .git into place ----
+if [ -d "$GSTACK_HOME/.git" ]; then
+  # Existing .git with matching remote — just fetch + fast-forward.
+  git -C "$GSTACK_HOME" fetch origin >/dev/null 2>&1 || true
+else
+  mv "$STAGING/repo/.git" "$GSTACK_HOME/.git"
+fi
+
+# ---- register merge drivers (local git config; don't survive clones) ----
+git -C "$GSTACK_HOME" config merge.jsonl-append.driver "$SCRIPT_DIR/gstack-jsonl-merge %O %A %B"
+git -C "$GSTACK_HOME" config merge.jsonl-append.name "gstack JSONL append-only merger"
+git -C "$GSTACK_HOME" config merge.union.driver "cat %A %B > %A.merged && mv %A.merged %A"
+git -C "$GSTACK_HOME" config merge.union.name "union concat"
+
+# ---- install pre-commit hook (same as init) ----
+HOOK="$GSTACK_HOME/.git/hooks/pre-commit"
+mkdir -p "$(dirname "$HOOK")"
+cat > "$HOOK" <<'HOOK_EOF'
+#!/usr/bin/env bash
+set -uo pipefail
+python3 -c "
+import sys, re, subprocess
+try:
+    out = subprocess.check_output(['git', 'diff', '--cached'], stderr=subprocess.DEVNULL).decode('utf-8', 'replace')
+except Exception:
+    sys.exit(0)
+patterns = [
+    ('aws-access-key', re.compile(r'AKIA[0-9A-Z]{16}')),
+    ('github-token', re.compile(r'\b(gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,})')),
+    ('openai-key', re.compile(r'\bsk-[A-Za-z0-9_-]{20,}')),
+    ('pem-block', re.compile(r'-----BEGIN [A-Z ]{3,}-----')),
+    ('jwt', re.compile(r'\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b')),
+    ('bearer-token-json',
+     re.compile(r'\"(authorization|api[_-]?key|apikey|token|secret|password)\"\s*:\s*\"[A-Za-z0-9_./+=-]{16,}\"',
+                re.IGNORECASE)),
+]
+for name, rx in patterns:
+    if rx.search(out):
+        sys.stderr.write(f'gstack-brain pre-commit: refusing commit — {name} detected.\n')
+        sys.exit(1)
+sys.exit(0)
+"
+HOOK_EOF
+chmod +x "$HOOK"
+
+# ---- write remote helper file if missing ----
+if [ ! -f "$REMOTE_FILE" ]; then
+  echo "$REMOTE_URL" > "$REMOTE_FILE"
+  chmod 600 "$REMOTE_FILE"
+  echo ""
+  echo "Wrote $REMOTE_FILE for future skill-run auto-detection."
+fi
+
+# ---- wire the cloned brain into gbrain (best-effort) ----
+WIREUP_BIN="$SCRIPT_DIR/gstack-gbrain-source-wireup"
+if [ -x "$WIREUP_BIN" ]; then
+  "$WIREUP_BIN" || >&2 echo "WARNING: gbrain wireup failed; run $WIREUP_BIN manually after fixing prereqs"
+fi
+
+cat <<EOF
+
+gstack-brain-restore complete.
+Local:   $GSTACK_HOME
+Remote:  $REMOTE_URL
+
+Next skill run will ask about privacy mode (one-time question) and then
+sync automatically at skill boundaries.
+
+Status anytime:  gstack-brain-sync --status
+EOF

bin/gstack-brain-sync

@@ -0,0 +1,452 @@
+#!/usr/bin/env bash
+# gstack-brain-sync — drain queue, commit allowlisted paths, push to remote.
+#
+# Usage:
+#   gstack-brain-sync --once           drain queue, commit, push (default)
+#   gstack-brain-sync --status         print sync health as JSON
+#   gstack-brain-sync --skip-file <p>  add <p> to ~/.gstack/.brain-skip.txt
+#   gstack-brain-sync --drop-queue --yes   clear queue without committing
+#   gstack-brain-sync --discover-new   scan allowlist dirs, enqueue changed files
+#
+# Invoked by the preamble at skill START and END boundaries. No persistent
+# daemon. Typical run <1s when queue empty; ~200-800ms with network push.
+#
+# Singleton enforcement: flock on ~/.gstack/.brain-sync.lock. Concurrent
+# invocations queue and serialize.
+#
+# Env:
+#   GSTACK_HOME — override ~/.gstack (aligns with writers).
+
+set -uo pipefail
+
+GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
+QUEUE="$GSTACK_HOME/.brain-queue.jsonl"
+ALLOWLIST="$GSTACK_HOME/.brain-allowlist"
+PRIVACY_MAP="$GSTACK_HOME/.brain-privacy-map.json"
+SKIP_FILE="$GSTACK_HOME/.brain-skip.txt"
+STATUS_FILE="$GSTACK_HOME/.brain-sync-status.json"
+LAST_PUSH_FILE="$GSTACK_HOME/.brain-last-push"
+LOCK_FILE="$GSTACK_HOME/.brain-sync.lock"
+DISCOVER_CURSOR="$GSTACK_HOME/.brain-discover-cursor"
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+CONFIG_BIN="$SCRIPT_DIR/gstack-config"
+
+# Remote-specific hint for auth errors (branch on origin URL).
+remote_auth_hint() {
+  local url
+  url=$(git -C "$GSTACK_HOME" remote get-url origin 2>/dev/null || echo "")
+  case "$url" in
+    *github.com*|*@github.*) echo "run: gh auth status (and gh auth refresh if needed)" ;;
+    *gitlab*) echo "run: glab auth status" ;;
+    *) echo "check 'git remote -v' and your credentials" ;;
+  esac
+}
+
+write_status() {
+  # args: status_code message [extra_json_blob]
+  local code="$1"
+  local msg="$2"
+  local extra="${3:-{\}}"
+  local ts
+  ts=$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || echo "")
+  python3 - "$STATUS_FILE" "$code" "$msg" "$ts" "$extra" <<'PYEOF' 2>/dev/null || true
+import json, sys
+path, code, msg, ts, extra = sys.argv[1:6]
+try:
+    extra_obj = json.loads(extra) if extra else {}
+except Exception:
+    extra_obj = {}
+data = {"status": code, "message": msg, "ts": ts, **extra_obj}
+with open(path, "w") as f:
+    json.dump(data, f)
+    f.write("\n")
+PYEOF
+}
+
+# Read config; return 0 if sync active, 1 otherwise.
+sync_active() {
+  if [ ! -d "$GSTACK_HOME/.git" ]; then
+    return 1
+  fi
+  local mode
+  mode=$("$CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
+  [ "$mode" = "off" ] && return 1
+  return 0
+}
+
+# Secret regex families — stdin scan. Exits 0 clean, 1 if hit.
+# Echoes the matching pattern family name on hit. Uses python3 -c (not
+# heredoc) so sys.stdin stays available for the diff content.
+secret_scan_stdin() {
+  python3 -c "
+import sys, re
+patterns = [
+    ('aws-access-key', re.compile(r'AKIA[0-9A-Z]{16}')),
+    ('github-token', re.compile(r'\\b(gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,})')),
+    ('openai-key', re.compile(r'\\bsk-[A-Za-z0-9_-]{20,}')),
+    ('pem-block', re.compile(r'-----BEGIN [A-Z ]{3,}-----')),
+    ('jwt', re.compile(r'\\beyJ[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{10,}\\b')),
+    ('bearer-token-json',
+     # JSON-embedded auth headers. The optional Bearer/Basic/Token prefix
+     # matters: real auth values include a literal space after the scheme
+     # name, but the value charset below does not include spaces, so
+     # without the optional prefix every Bearer token in a JSON blob slips
+     # past the scanner.
+     re.compile(r'\"(authorization|api[_-]?key|apikey|token|secret|password)\"\\s*:\\s*\"(Bearer |Basic |Token )?[A-Za-z0-9_./+=-]{16,}\"',
+                re.IGNORECASE)),
+]
+text = sys.stdin.read()
+for name, rx in patterns:
+    m = rx.search(text)
+    if m:
+        snippet = m.group(0)
+        if len(snippet) > 30:
+            snippet = snippet[:30] + '...'
+        print(name + ':' + snippet)
+        sys.exit(1)
+sys.exit(0)
+"
+}
+
+# Compute matched allowlisted, privacy-filtered path set from queue.
+# Output: newline-delimited relative paths that should be staged.
+compute_paths_to_stage() {
+  local mode="$1"
+  python3 - "$GSTACK_HOME" "$QUEUE" "$ALLOWLIST" "$PRIVACY_MAP" "$SKIP_FILE" "$mode" <<'PYEOF'
+import sys, json, os, fnmatch, glob
+
+gstack_home, queue, allowlist_path, privacy_path, skip_path, mode = sys.argv[1:7]
+
+def load_lines(path):
+    try:
+        with open(path) as f:
+            return [l.strip() for l in f if l.strip() and not l.lstrip().startswith("#")]
+    except FileNotFoundError:
+        return []
+
+def load_privacy_map(path):
+    try:
+        with open(path) as f:
+            data = json.load(f)
+        # Expected: [{"pattern": "glob", "class": "artifact" | "behavioral"}]
+        return data if isinstance(data, list) else []
+    except (FileNotFoundError, json.JSONDecodeError):
+        return []
+
+allowlist_globs = load_lines(allowlist_path)
+privacy_map = load_privacy_map(privacy_path)
+skip_lines = set(load_lines(skip_path))
+
+# Read queue; collect unique file paths.
+queue_paths = set()
+try:
+    with open(queue) as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                obj = json.loads(line)
+                p = obj.get("file")
+                if isinstance(p, str):
+                    queue_paths.add(p)
+            except json.JSONDecodeError:
+                continue
+except FileNotFoundError:
+    pass
+
+def path_matches_any(path, globs):
+    for pattern in globs:
+        if fnmatch.fnmatchcase(path, pattern):
+            return True
+    return False
+
+def privacy_class(path, mapping):
+    for entry in mapping:
+        pat = entry.get("pattern")
+        if pat and fnmatch.fnmatchcase(path, pat):
+            return entry.get("class", "artifact")
+    # Default class when no pattern matches: artifact (safe default).
+    return "artifact"
+
+# mode filter: 'off' → nothing; 'artifacts-only' → only artifact class;
+# 'full' → both classes.
+def mode_allows(cls, mode):
+    if mode == "off":
+        return False
+    if mode == "artifacts-only":
+        return cls == "artifact"
+    return True  # full
+
+final = []
+for p in sorted(queue_paths):
+    if p in skip_lines:
+        continue
+    # Must be under GSTACK_HOME root. Reject absolute + reject ../ escape.
+    if p.startswith("/") or ".." in p.split("/"):
+        continue
+    # Must match at least one allowlist glob.
+    if not path_matches_any(p, allowlist_globs):
+        continue
+    # Must survive privacy mode filter.
+    cls = privacy_class(p, privacy_map)
+    if not mode_allows(cls, mode):
+        continue
+    # Must exist on disk — can't stage what isn't there.
+    if not os.path.exists(os.path.join(gstack_home, p)):
+        continue
+    final.append(p)
+
+for p in final:
+    print(p)
+PYEOF
+}
+
+subcmd_once() {
+  if ! sync_active; then
+    # Silent no-op when feature not initialized / disabled.
+    exit 0
+  fi
+
+  # Singleton lock via atomic mkdir. `flock(1)` isn't on macOS by default;
+  # `mkdir` is atomic on every POSIX filesystem. If another --once is already
+  # running, skip (don't wait) — the next skill boundary will catch up.
+  local lock_dir="${LOCK_FILE}.d"
+  if ! mkdir "$lock_dir" 2>/dev/null; then
+    # Is the lock stale? Check the pidfile inside. If process is dead, clear it.
+    if [ -f "$lock_dir/pid" ]; then
+      local lock_pid
+      lock_pid=$(cat "$lock_dir/pid" 2>/dev/null || echo "")
+      if [ -n "$lock_pid" ] && ! kill -0 "$lock_pid" 2>/dev/null; then
+        # Stale lock — clear and retry once.
+        rm -rf "$lock_dir" 2>/dev/null || true
+        if ! mkdir "$lock_dir" 2>/dev/null; then
+          exit 0
+        fi
+      else
+        # Lock is held by a live process.
+        exit 0
+      fi
+    else
+      # Lock dir without pidfile — treat as held; don't touch.
+      exit 0
+    fi
+  fi
+  echo "$$" > "$lock_dir/pid" 2>/dev/null || true
+
+  local mode
+  mode=$("$CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
+
+  local paths_file
+  paths_file=$(mktemp /tmp/brain-sync-paths.XXXXXX) || { rm -rf "$lock_dir" 2>/dev/null; write_status "error" "mktemp failed"; exit 1; }
+  # Single trap covers both: lock cleanup AND tempfile cleanup.
+  trap 'rm -f "$paths_file" 2>/dev/null; rm -rf "$lock_dir" 2>/dev/null || true' EXIT INT TERM
+
+  compute_paths_to_stage "$mode" > "$paths_file"
+  if [ ! -s "$paths_file" ]; then
+    # Nothing to stage. Clear any stale queue entries and exit.
+    : > "$QUEUE"
+    write_status "idle" "no allowlisted changes in queue"
+    exit 0
+  fi
+
+  # Stage with git add -f (forces past .gitignore=*) explicit paths only.
+  while IFS= read -r p; do
+    [ -z "$p" ] && continue
+    git -C "$GSTACK_HOME" add -f -- "$p" 2>/dev/null || true
+  done < "$paths_file"
+
+  # Secret-scan staged diff.
+  local scan_out
+  scan_out=$(git -C "$GSTACK_HOME" diff --cached 2>/dev/null | secret_scan_stdin || true)
+  if [ -n "$scan_out" ]; then
+    # Hit — unstage, preserve queue, write loud status.
+    git -C "$GSTACK_HOME" reset HEAD -- . >/dev/null 2>&1 || true
+    local hint
+    hint="secret pattern detected ($scan_out). Remediation: review the staged file, then run: gstack-brain-sync --skip-file <path> OR edit the content."
+    write_status "blocked" "$hint"
+    echo "BRAIN_SYNC: blocked: $scan_out" >&2
+    exit 0
+  fi
+
+  # Commit with template message.
+  local n ts
+  n=$(wc -l < "$paths_file" | tr -d ' ')
+  ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+  local msg="sync: $n file(s) | $ts"
+  git -C "$GSTACK_HOME" -c user.email="gstack@localhost" -c user.name="gstack-brain-sync" \
+    commit -q -m "$msg" 2>/dev/null || {
+      # Nothing to commit (e.g. all files already committed).
+      : > "$QUEUE"
+      write_status "idle" "queue drained but no new changes to commit"
+      exit 0
+    }
+
+  # Push. On reject, fetch + merge (merge driver handles JSONL) + retry once.
+  local push_err
+  push_err=$(git -C "$GSTACK_HOME" push origin HEAD 2>&1 >/dev/null) || {
+    # Check if this is an auth error first — no point retrying.
+    if echo "$push_err" | grep -qiE "auth|permission|403|401|forbidden"; then
+      local hint
+      hint=$(remote_auth_hint)
+      write_status "push_failed" "push failed: auth error. fix: $hint"
+      echo "BRAIN_SYNC: push failed: auth. fix: $hint" >&2
+      # Queue cleared because the commit exists locally; next push will send it.
+      : > "$QUEUE"
+      exit 0
+    fi
+
+    # Try a fetch-and-merge + retry.
+    if git -C "$GSTACK_HOME" fetch origin 2>/dev/null; then
+      local branch
+      branch=$(git -C "$GSTACK_HOME" rev-parse --abbrev-ref HEAD 2>/dev/null || echo main)
+      if git -C "$GSTACK_HOME" merge --no-edit "origin/$branch" >/dev/null 2>&1; then
+        if git -C "$GSTACK_HOME" push origin HEAD 2>/dev/null; then
+          : > "$QUEUE"
+          date -u +%Y-%m-%dT%H:%M:%SZ > "$LAST_PUSH_FILE"
+          write_status "ok" "pushed $n file(s) after rebase"
+          exit 0
+        fi
+      fi
+    fi
+    write_status "push_failed" "push failed: $(printf '%s' "$push_err" | head -1)"
+    : > "$QUEUE"
+    exit 0
+  }
+
+  # Success: clear queue, update last-push.
+  : > "$QUEUE"
+  date -u +%Y-%m-%dT%H:%M:%SZ > "$LAST_PUSH_FILE"
+  write_status "ok" "pushed $n file(s)"
+  exit 0
+}
+
+subcmd_status() {
+  if [ -f "$STATUS_FILE" ]; then
+    cat "$STATUS_FILE"
+  else
+    echo '{"status":"unknown","message":"no status file yet"}'
+  fi
+  # Supplemental info (not in status file).
+  local queue_depth=0
+  [ -f "$QUEUE" ] && queue_depth=$(wc -l < "$QUEUE" | tr -d ' ')
+  local last_push="never"
+  [ -f "$LAST_PUSH_FILE" ] && last_push=$(cat "$LAST_PUSH_FILE" 2>/dev/null || echo never)
+  local mode
+  mode=$("$CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
+  printf '{"queue_depth":%s,"last_push":"%s","mode":"%s"}\n' "$queue_depth" "$last_push" "$mode"
+}
+
+subcmd_skip_file() {
+  local path="${1:-}"
+  if [ -z "$path" ]; then
+    echo "Usage: gstack-brain-sync --skip-file <path>" >&2
+    exit 1
+  fi
+  mkdir -p "$GSTACK_HOME"
+  # Avoid duplicate entries.
+  if [ -f "$SKIP_FILE" ] && grep -Fxq "$path" "$SKIP_FILE"; then
+    echo "already in skip list: $path"
+    exit 0
+  fi
+  echo "$path" >> "$SKIP_FILE"
+  echo "added to skip list: $path"
+  echo "(future writers will not enqueue this path; existing queue entries ignored on next --once)"
+}
+
+subcmd_drop_queue() {
+  local force="${1:-}"
+  if [ "$force" != "--yes" ]; then
+    echo "Refusing: --drop-queue discards pending syncs. Pass --yes to confirm." >&2
+    exit 1
+  fi
+  if [ ! -f "$QUEUE" ]; then
+    echo "queue already empty"
+    exit 0
+  fi
+  local n
+  n=$(wc -l < "$QUEUE" | tr -d ' ')
+  : > "$QUEUE"
+  echo "dropped $n queue entries"
+}
+
+subcmd_discover_new() {
+  if ! sync_active; then
+    exit 0
+  fi
+  # Walk allowlist globs; enqueue any file where mtime+size differs from cursor.
+  python3 - "$GSTACK_HOME" "$ALLOWLIST" "$DISCOVER_CURSOR" "$SCRIPT_DIR/gstack-brain-enqueue" <<'PYEOF' 2>/dev/null || true
+import sys, os, json, glob, fnmatch, subprocess, hashlib
+
+gstack_home, allowlist_path, cursor_path, enqueue_bin = sys.argv[1:5]
+
+def load_lines(path):
+    try:
+        with open(path) as f:
+            return [l.strip() for l in f if l.strip() and not l.lstrip().startswith("#")]
+    except FileNotFoundError:
+        return []
+
+def load_cursor(path):
+    try:
+        with open(path) as f:
+            return json.load(f)
+    except (FileNotFoundError, json.JSONDecodeError):
+        return {}
+
+def save_cursor(path, data):
+    try:
+        with open(path, "w") as f:
+            json.dump(data, f)
+    except OSError:
+        pass
+
+allowlist = load_lines(allowlist_path)
+cursor = load_cursor(cursor_path)
+new_cursor = dict(cursor)
+
+# Walk all files under gstack_home, match against allowlist.
+for root, dirs, files in os.walk(gstack_home):
+    # Skip .git and .brain-* state files.
+    if ".git" in root.split(os.sep):
+        continue
+    for name in files:
+        full = os.path.join(root, name)
+        rel = os.path.relpath(full, gstack_home)
+        if rel.startswith(".brain-"):
+            continue
+        matched = any(fnmatch.fnmatchcase(rel, pat) for pat in allowlist)
+        if not matched:
+            continue
+        try:
+            st = os.stat(full)
+            key = f"{int(st.st_mtime)}:{st.st_size}"
+        except OSError:
+            continue
+        prev = cursor.get(rel)
+        if prev != key:
+            # Enqueue via the shim (respects sync mode + skip list).
+            subprocess.run([enqueue_bin, rel], check=False)
+            new_cursor[rel] = key
+
+save_cursor(cursor_path, new_cursor)
+PYEOF
+}
+
+# -------- dispatch --------
+case "${1:-}" in
+  --once|"") subcmd_once ;;
+  --status) subcmd_status ;;
+  --skip-file) shift; subcmd_skip_file "${1:-}" ;;
+  --drop-queue) shift; subcmd_drop_queue "${1:-}" ;;
+  --discover-new) subcmd_discover_new ;;
+  --help|-h)
+    sed -n '2,18p' "$0" | sed 's/^# \{0,1\}//'
+    ;;
+  *)
+    echo "Unknown subcommand: $1" >&2
+    echo "Run: gstack-brain-sync --help" >&2
+    exit 1
+    ;;
+esac

bin/gstack-brain-uninstall

@@ -0,0 +1,160 @@
+#!/usr/bin/env bash
+# gstack-brain-uninstall — clean off-ramp for gstack-brain sync.
+#
+# Usage:
+#   gstack-brain-uninstall [--yes] [--delete-remote]
+#
+# Removes the git layer from ~/.gstack/ and clears sync config. Your local
+# gstack memory (learnings, timelines, etc.) is NOT touched — this is an
+# uninstall-sync command, not a delete-data command.
+#
+# Flags:
+#   --yes             Skip the confirmation prompt.
+#   --delete-remote   Also delete the GitHub repo via `gh repo delete`
+#                     (interactive unless --yes is also passed).
+#
+# What it removes (in ~/.gstack/):
+#   .git/                      — the sync repo's git data
+#   .gitignore                 — canonical ignore-all marker
+#   .gitattributes             — merge driver declarations
+#   .brain-allowlist           — sync path list
+#   .brain-privacy-map.json    — sync privacy classifier
+#   .brain-queue.jsonl         — pending queue
+#   .brain-discover-cursor     — discover-new cursor
+#   .brain-last-push           — timestamp marker
+#   .brain-skip.txt            — user-maintained skip list
+#   .brain-sync.lock.d/        — lock dir (if present)
+#   .brain-sync-status.json    — health status
+#   consumers.json             — consumer/reader registry
+#
+# What it clears (via gstack-config):
+#   artifacts_sync_mode            → off
+#   artifacts_sync_mode_prompted   → false (so user re-prompts on re-init)
+#
+# What it does NOT touch:
+#   Project data (projects/*, retros/*, developer-profile.json, etc.)
+#   Consumer tokens in gstack-config (<name>_token keys)
+#   ~/.gstack-brain-remote.txt in your home directory
+#   The actual remote git repo (unless --delete-remote)
+
+set -euo pipefail
+
+GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+CONFIG_BIN="$SCRIPT_DIR/gstack-config"
+# v1.27.0.0+ canonical name; brain-remote is the legacy fallback during migration.
+if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
+  REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
+else
+  REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
+fi
+
+ASSUME_YES=0
+DELETE_REMOTE=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --yes|-y) ASSUME_YES=1; shift ;;
+    --delete-remote) DELETE_REMOTE=1; shift ;;
+    --help|-h) sed -n '2,30p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    *) echo "Unknown flag: $1" >&2; exit 1 ;;
+  esac
+done
+
+if [ ! -d "$GSTACK_HOME/.git" ]; then
+  echo "gstack-brain-uninstall: nothing to do (~/.gstack/.git doesn't exist)."
+  exit 0
+fi
+
+REMOTE_URL=$(git -C "$GSTACK_HOME" remote get-url origin 2>/dev/null || echo "")
+
+# ---- confirmation ----
+if [ "$ASSUME_YES" != "1" ]; then
+  cat <<EOF
+This will remove gstack-brain sync from this machine:
+  - Remove ~/.gstack/.git and sync config files
+  - Clear artifacts_sync_mode in gstack-config
+  - Remote: $REMOTE_URL will be $([ "$DELETE_REMOTE" = "1" ] && echo "DELETED" || echo "kept")
+
+Local memory (learnings, plans, etc.) is NOT touched.
+
+EOF
+  printf "Proceed? [y/N] "
+  read -r reply
+  case "$reply" in
+    y|Y|yes|Yes) ;;
+    *) echo "Aborted."; exit 0 ;;
+  esac
+fi
+
+# ---- delete remote if requested ----
+if [ "$DELETE_REMOTE" = "1" ] && [ -n "$REMOTE_URL" ]; then
+  case "$REMOTE_URL" in
+    *github.com*|*@github*)
+      if command -v gh >/dev/null 2>&1; then
+        # Extract owner/repo from URL.
+        REPO_SLUG=$(echo "$REMOTE_URL" | sed -E 's#.*[:/]([^/:]+/[^/]+)(\.git)?$#\1#' | sed 's/\.git$//')
+        if [ -n "$REPO_SLUG" ]; then
+          echo "Deleting GitHub repo: $REPO_SLUG"
+          if [ "$ASSUME_YES" = "1" ]; then
+            gh repo delete "$REPO_SLUG" --yes 2>/dev/null || echo "gh repo delete failed; continuing local uninstall"
+          else
+            gh repo delete "$REPO_SLUG" 2>/dev/null || echo "gh repo delete failed; continuing local uninstall"
+          fi
+        fi
+      else
+        echo "--delete-remote requires the gh CLI. Skipping remote deletion."
+      fi
+      ;;
+    *)
+      echo "--delete-remote only supports github.com remotes. Delete manually if needed: $REMOTE_URL"
+      ;;
+  esac
+fi
+
+# ---- remove sync files ----
+echo "Removing git layer and sync config files..."
+rm -rf "$GSTACK_HOME/.git" 2>/dev/null || true
+rm -f "$GSTACK_HOME/.gitignore" 2>/dev/null || true
+rm -f "$GSTACK_HOME/.gitattributes" 2>/dev/null || true
+rm -f "$GSTACK_HOME/.brain-allowlist" 2>/dev/null || true
+rm -f "$GSTACK_HOME/.brain-privacy-map.json" 2>/dev/null || true
+rm -f "$GSTACK_HOME/.brain-queue.jsonl" 2>/dev/null || true
+rm -f "$GSTACK_HOME/.brain-discover-cursor" 2>/dev/null || true
+rm -f "$GSTACK_HOME/.brain-last-push" 2>/dev/null || true
+rm -f "$GSTACK_HOME/.brain-last-pull" 2>/dev/null || true
+rm -f "$GSTACK_HOME/.brain-skip.txt" 2>/dev/null || true
+rm -f "$GSTACK_HOME/.brain-sync-status.json" 2>/dev/null || true
+rm -rf "$GSTACK_HOME/.brain-sync.lock.d" 2>/dev/null || true
+
+# ---- unregister gbrain federated source + remove worktree (best-effort) ----
+# The wireup helper handles: gbrain sources remove, git worktree remove,
+# launchd plist (future). All best-effort; uninstall continues on failure.
+WIREUP_BIN="$SCRIPT_DIR/gstack-gbrain-source-wireup"
+if [ -x "$WIREUP_BIN" ]; then
+  "$WIREUP_BIN" --uninstall 2>/dev/null || true
+fi
+
+# ---- legacy consumers.json (no longer written by gstack-brain-init since v1.17.0.0) ----
+rm -f "$GSTACK_HOME/consumers.json" 2>/dev/null || true
+
+# ---- clear config keys ----
+"$CONFIG_BIN" set artifacts_sync_mode off >/dev/null 2>&1 || true
+"$CONFIG_BIN" set artifacts_sync_mode_prompted false >/dev/null 2>&1 || true
+
+# ---- leave remote-helper file alone unless user asked to delete remote ----
+if [ "$DELETE_REMOTE" = "1" ]; then
+  rm -f "$REMOTE_FILE" 2>/dev/null || true
+else
+  if [ -f "$REMOTE_FILE" ]; then
+    echo "(keeping $REMOTE_FILE — remove manually if you want to forget the URL)"
+  fi
+fi
+
+cat <<EOF
+
+gstack-brain uninstall complete.
+Sync is off. ~/.gstack/ is a plain directory again.
+Your project data, learnings, and profile are untouched.
+
+To re-enable sync later: gstack-brain-init
+EOF

bin/gstack-builder-profile

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# gstack-builder-profile — LEGACY SHIM.
+#
+# Superseded by bin/gstack-developer-profile. This binary now delegates to
+# `gstack-developer-profile --read` to keep /office-hours working during the
+# transition. When all call sites have been updated, this file can be removed.
+#
+# The migration from ~/.gstack/builder-profile.jsonl to the unified
+# ~/.gstack/developer-profile.json happens automatically on first read —
+# see bin/gstack-developer-profile --migrate for details.
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+exec "$SCRIPT_DIR/gstack-developer-profile" --read "$@"

bin/gstack-codex-probe

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+# gstack-codex-probe: shared helper for /codex and /autoplan skills.
+# Sourced from template bash blocks; never execute directly.
+#
+# Functions (all prefixed with _gstack_codex_ for namespace hygiene):
+#   _gstack_codex_auth_probe      — multi-signal auth check (env + file)
+#   _gstack_codex_version_check   — warn on known-bad Codex CLI versions
+#   _gstack_codex_timeout_wrapper — gtimeout -> timeout -> unwrapped fallback
+#   _gstack_codex_log_event       — telemetry emission to ~/.gstack/analytics/
+#
+# Hygiene rules (enforced by test/codex-hardening.test.ts):
+#   - Never set -e / set -u / trap / IFS= / PATH= in this file.
+#   - All internal vars prefix with _GSTACK_CODEX_.
+#   - All functions prefix with _gstack_codex_.
+#   - No command execution at source time (only function defs).
+
+# --- Auth probe -------------------------------------------------------------
+
+_gstack_codex_auth_probe() {
+  # Multi-signal: env vars OR auth file. Avoids false negatives for env-auth
+  # users (CI, platform engineers) that a file-only check would reject.
+  local _codex_home="${CODEX_HOME:-$HOME/.codex}"
+  # Use `-n` which returns true only for non-empty non-whitespace. Bash's [ -n ]
+  # alone allows whitespace; pair with a whitespace strip for robustness.
+  local _k1 _k2
+  _k1=$(printf '%s' "${CODEX_API_KEY:-}" | tr -d '[:space:]')
+  _k2=$(printf '%s' "${OPENAI_API_KEY:-}" | tr -d '[:space:]')
+  if [ -n "$_k1" ] || [ -n "$_k2" ] || [ -f "$_codex_home/auth.json" ]; then
+    echo "AUTH_OK"
+    return 0
+  fi
+  echo "AUTH_FAILED"
+  return 1
+}
+
+# --- Version check ----------------------------------------------------------
+
+_gstack_codex_version_check() {
+  # Warn on known-bad Codex CLI versions. Anchored regex prevents false
+  # positives like 0.120.10 or 0.120.20 from matching. 0.120.2-beta still
+  # matches the bad release and gets warned (it IS buggy).
+  # Update this list when a new Codex CLI version regresses.
+  local _ver
+  _ver=$(codex --version 2>/dev/null | head -1)
+  [ -z "$_ver" ] && return 0
+  if echo "$_ver" | grep -Eq '(^|[^0-9.])0\.120\.(0|1|2)([^0-9.]|$)'; then
+    echo "WARN: Codex CLI $_ver has known stdin deadlock bugs. Run: npm install -g @openai/codex@latest"
+    _gstack_codex_log_event "codex_version_warning"
+  fi
+}
+
+# --- Timeout wrapper --------------------------------------------------------
+
+_gstack_codex_timeout_wrapper() {
+  # Resolve wrapper binary: prefer gtimeout (Homebrew coreutils on macOS),
+  # fall back to timeout (Linux), else run unwrapped. Arguments: $1 is the
+  # duration in seconds; rest is the command to run.
+  local _duration="$1"
+  shift
+  local _to
+  _to=$(command -v gtimeout 2>/dev/null || command -v timeout 2>/dev/null || echo "")
+  if [ -n "$_to" ]; then
+    "$_to" "$_duration" "$@"
+  else
+    "$@"
+  fi
+}
+
+# --- Telemetry event --------------------------------------------------------
+
+_gstack_codex_log_event() {
+  # Emit a telemetry event to ~/.gstack/analytics/skill-usage.jsonl.
+  # Gated on $_TEL != "off" (caller sets this from gstack-config).
+  # Event types: codex_timeout, codex_auth_failed, codex_cli_missing,
+  #              codex_version_warning.
+  # Payload schema: {skill, event, duration_s, ts}. NEVER includes prompt
+  # content, env var values, or auth tokens.
+  local _event="$1"
+  local _duration="${2:-0}"
+  [ "${_TEL:-off}" = "off" ] && return 0
+  mkdir -p "$HOME/.gstack/analytics" 2>/dev/null || return 0
+  local _ts
+  _ts=$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || echo unknown)
+  printf '{"skill":"codex","event":"%s","duration_s":"%s","ts":"%s"}\n' \
+    "$_event" "$_duration" "$_ts" \
+    >> "$HOME/.gstack/analytics/skill-usage.jsonl" 2>/dev/null || true
+}
+
+# --- Learnings log on hang --------------------------------------------------
+
+_gstack_codex_log_hang() {
+  # Invoked when a codex invocation times out (exit 124). Records an
+  # operational learning so future /investigate sessions surface the pattern.
+  # Best-effort: errors swallowed.
+  local _mode="${1:-unknown}"
+  local _prompt_size="${2:-0}"
+  local _log_bin="$HOME/.claude/skills/gstack/bin/gstack-learnings-log"
+  [ -x "$_log_bin" ] || return 0
+  local _key="codex-hang-$(date +%s 2>/dev/null || echo unknown)"
+  "$_log_bin" "$(printf '{"skill":"codex","type":"operational","key":"%s","insight":"Codex timed out after 600s during [%s] invocation. Prompt size: %s. Consider splitting prompt or checking network.","confidence":8,"source":"observed","files":["codex/SKILL.md.tmpl","autoplan/SKILL.md.tmpl"]}' "$_key" "$_mode" "$_prompt_size")" \
+    >/dev/null 2>&1 || true
+}

bin/gstack-community-dashboard

@@ -0,0 +1,105 @@
+#!/usr/bin/env bash
+# gstack-community-dashboard — community usage stats from Supabase
+#
+# Calls the community-pulse edge function for aggregated stats:
+# skill popularity, crash clusters, version distribution, retention.
+#
+# Env overrides (for testing):
+#   GSTACK_DIR                    — override auto-detected gstack root
+#   GSTACK_SUPABASE_URL           — override Supabase project URL
+#   GSTACK_SUPABASE_ANON_KEY      — override Supabase anon key
+set -uo pipefail
+
+GSTACK_DIR="${GSTACK_DIR:-$(cd "$(dirname "$0")/.." && pwd)}"
+
+# Source Supabase config if not overridden by env
+if [ -z "${GSTACK_SUPABASE_URL:-}" ] && [ -f "$GSTACK_DIR/supabase/config.sh" ]; then
+  . "$GSTACK_DIR/supabase/config.sh"
+fi
+SUPABASE_URL="${GSTACK_SUPABASE_URL:-}"
+ANON_KEY="${GSTACK_SUPABASE_ANON_KEY:-}"
+
+if [ -z "$SUPABASE_URL" ] || [ -z "$ANON_KEY" ]; then
+  echo "gstack community dashboard"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo ""
+  echo "Supabase not configured yet. The community dashboard will be"
+  echo "available once the gstack Supabase project is set up."
+  echo ""
+  echo "For local analytics, run: gstack-analytics"
+  exit 0
+fi
+
+# ─── Fetch aggregated stats from edge function ────────────────
+DATA="$(curl -sf --max-time 15 \
+  "${SUPABASE_URL}/functions/v1/community-pulse" \
+  -H "apikey: ${ANON_KEY}" \
+  2>/dev/null || echo "{}")"
+
+echo "gstack community dashboard"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+
+# ─── Weekly active installs ──────────────────────────────────
+WEEKLY="$(echo "$DATA" | grep -o '"weekly_active":[0-9]*' | grep -o '[0-9]*' || echo "0")"
+CHANGE="$(echo "$DATA" | grep -o '"change_pct":[0-9-]*' | grep -o '[0-9-]*' || echo "0")"
+
+echo "Weekly active installs: ${WEEKLY}"
+if [ "$CHANGE" -gt 0 ] 2>/dev/null; then
+  echo "  Change: +${CHANGE}%"
+elif [ "$CHANGE" -lt 0 ] 2>/dev/null; then
+  echo "  Change: ${CHANGE}%"
+fi
+echo ""
+
+# ─── Skill popularity (top 10) ───────────────────────────────
+echo "Top skills (last 7 days)"
+echo "────────────────────────"
+
+# Parse top_skills array from JSON
+SKILLS="$(echo "$DATA" | grep -o '"top_skills":\[[^]]*\]' || echo "")"
+if [ -n "$SKILLS" ] && [ "$SKILLS" != '"top_skills":[]' ]; then
+  # Parse each object — handle any key order (JSONB doesn't preserve order)
+  echo "$SKILLS" | grep -o '{[^}]*}' | while read -r OBJ; do
+    SKILL="$(echo "$OBJ" | grep -o '"skill":"[^"]*"' | awk -F'"' '{print $4}')"
+    COUNT="$(echo "$OBJ" | grep -o '"count":[0-9]*' | grep -o '[0-9]*')"
+    [ -n "$SKILL" ] && [ -n "$COUNT" ] && printf "  /%-20s %s runs\n" "$SKILL" "$COUNT"
+  done
+else
+  echo "  No data yet"
+fi
+echo ""
+
+# ─── Crash clusters ──────────────────────────────────────────
+echo "Top crash clusters"
+echo "──────────────────"
+
+CRASHES="$(echo "$DATA" | grep -o '"crashes":\[[^]]*\]' || echo "")"
+if [ -n "$CRASHES" ] && [ "$CRASHES" != '"crashes":[]' ]; then
+  echo "$CRASHES" | grep -o '{[^}]*}' | head -5 | while read -r OBJ; do
+    ERR="$(echo "$OBJ" | grep -o '"error_class":"[^"]*"' | awk -F'"' '{print $4}')"
+    C="$(echo "$OBJ" | grep -o '"total_occurrences":[0-9]*' | grep -o '[0-9]*')"
+    [ -n "$ERR" ] && printf "  %-30s %s occurrences\n" "$ERR" "${C:-?}"
+  done
+else
+  echo "  No crashes reported"
+fi
+echo ""
+
+# ─── Version distribution ────────────────────────────────────
+echo "Version distribution (last 7 days)"
+echo "───────────────────────────────────"
+
+VERSIONS="$(echo "$DATA" | grep -o '"versions":\[[^]]*\]' || echo "")"
+if [ -n "$VERSIONS" ] && [ "$VERSIONS" != '"versions":[]' ]; then
+  echo "$VERSIONS" | grep -o '{[^}]*}' | head -5 | while read -r OBJ; do
+    VER="$(echo "$OBJ" | grep -o '"version":"[^"]*"' | awk -F'"' '{print $4}')"
+    COUNT="$(echo "$OBJ" | grep -o '"count":[0-9]*' | grep -o '[0-9]*')"
+    [ -n "$VER" ] && [ -n "$COUNT" ] && printf "  v%-15s %s events\n" "$VER" "$COUNT"
+  done
+else
+  echo "  No data yet"
+fi
+
+echo ""
+echo "For local analytics: gstack-analytics"

bin/gstack-config

@@ -0,0 +1,198 @@
+#!/usr/bin/env bash
+# gstack-config — read/write ~/.gstack/config.yaml
+#
+# Usage:
+#   gstack-config get <key>          — read a config value (falls back to DEFAULTS)
+#   gstack-config set <key> <value>  — write a config value
+#   gstack-config list               — show all config (values + defaults)
+#   gstack-config defaults           — show just the defaults table
+#
+# Env overrides (for testing):
+#   GSTACK_HOME       — override ~/.gstack state directory (aligns with writer scripts)
+#   GSTACK_STATE_DIR  — legacy alias for GSTACK_HOME (kept for backwards compat)
+set -euo pipefail
+
+STATE_DIR="${GSTACK_HOME:-${GSTACK_STATE_DIR:-$HOME/.gstack}}"
+CONFIG_FILE="$STATE_DIR/config.yaml"
+
+# Annotated header for new config files. Written once on first `set`.
+# Default semantics: DEFAULTS table below is the canonical source. Header text
+# is documentation that must stay in sync with DEFAULTS.
+CONFIG_HEADER='# gstack configuration — edit freely, changes take effect on next skill run.
+# Docs: https://github.com/garrytan/gstack
+#
+# ─── Behavior ────────────────────────────────────────────────────────
+# proactive: true           # Auto-invoke skills when your request matches one.
+#                           # Set to false to only run skills you type explicitly.
+#
+# routing_declined: false   # Set to true to skip the CLAUDE.md routing injection
+#                           # prompt. Set back to false to be asked again.
+#
+# ─── Telemetry ───────────────────────────────────────────────────────
+# telemetry: off            # off | anonymous | community
+#                           #   off       — no data sent, no local analytics (default)
+#                           #   anonymous — counter only, no device ID
+#                           #   community — usage data + stable device ID
+#
+# ─── Updates ─────────────────────────────────────────────────────────
+# auto_upgrade: false       # true = silently upgrade on session start
+# update_check: true        # false = suppress version check notifications
+#
+# ─── Skill naming ────────────────────────────────────────────────────
+# skill_prefix: false       # true = namespace skills as /gstack-qa, /gstack-ship
+#                           # false = short names /qa, /ship
+#
+# ─── Checkpoint ──────────────────────────────────────────────────────
+# checkpoint_mode: explicit # explicit | continuous
+#                           #   explicit   — commit only when you run /ship or /checkpoint
+#                           #   continuous — auto-commit after each significant change
+#                           #                with WIP: prefix + [gstack-context] body
+#
+# checkpoint_push: false    # true = push WIP commits to remote as you go
+#                           # false = keep WIP commits local only (default)
+#                           # Pushing can trigger CI/deploy hooks — opt in carefully.
+#
+# ─── Writing style (V1) ──────────────────────────────────────────────
+# explain_level: default    # default = jargon-glossed, outcome-framed prose
+#                           #           (V1 default — more accessible for everyone)
+#                           # terse   = V0 prose style, no glosses, no outcome-framing layer
+#                           #           (for power users who know the terms)
+#                           # Unknown values default to "default" with a warning.
+#                           # See docs/designs/PLAN_TUNING_V1.md for rationale.
+#
+# ─── Artifacts sync (renamed from gbrain_sync_mode in v1.27.0.0) ─────
+# artifacts_sync_mode: off  # off | artifacts-only | full
+#                           #   off            — no sync (default)
+#                           #   artifacts-only — sync plans/designs/retros/learnings only
+#                           #                    (skip behavioral data: question-log,
+#                           #                    developer-profile, timeline)
+#                           #   full           — sync everything allowlisted
+#                           # Set by the first-run privacy stop-gate. See docs/gbrain-sync.md.
+#
+# artifacts_sync_mode_prompted: false
+#                           # Set to true once the privacy gate has asked the user.
+#                           # Flip back to false to be re-prompted.
+#
+# ─── Advanced ────────────────────────────────────────────────────────
+# codex_reviews: enabled    # disabled = skip Codex adversarial reviews in /ship
+# gstack_contributor: false # true = file field reports when gstack misbehaves
+# skip_eng_review: false    # true = skip eng review gate in /ship (not recommended)
+#
+# ─── Workspace-aware ship ────────────────────────────────────────────
+# workspace_root: $HOME/conductor/workspaces  # Where /ship looks for sibling
+#                           # Conductor worktrees when picking a VERSION slot.
+#                           # Set to "null" to disable sibling scanning entirely.
+#                           # Non-Conductor users can point this at any directory
+#                           # that holds parallel worktrees of the same repo.
+#
+'
+
+# DEFAULTS table — canonical default values for known keys.
+# `get <key>` returns DEFAULTS[key] when the key is absent from the config file
+# AND the env override is not set. Keep in sync with the CONFIG_HEADER comments.
+lookup_default() {
+  case "$1" in
+    proactive) echo "true" ;;
+    routing_declined) echo "false" ;;
+    telemetry) echo "off" ;;
+    auto_upgrade) echo "false" ;;
+    update_check) echo "true" ;;
+    skill_prefix) echo "false" ;;
+    checkpoint_mode) echo "explicit" ;;
+    checkpoint_push) echo "false" ;;
+    codex_reviews) echo "enabled" ;;
+    gstack_contributor) echo "false" ;;
+    skip_eng_review) echo "false" ;;
+    workspace_root) echo "$HOME/conductor/workspaces" ;;
+    cross_project_learnings) echo "" ;; # intentionally empty → unset triggers first-time prompt
+    artifacts_sync_mode) echo "off" ;;
+    artifacts_sync_mode_prompted) echo "false" ;;
+    *) echo "" ;;
+  esac
+}
+
+case "${1:-}" in
+  get)
+    KEY="${2:?Usage: gstack-config get <key>}"
+    # Validate key (alphanumeric + underscore only)
+    if ! printf '%s' "$KEY" | grep -qE '^[a-zA-Z0-9_]+$'; then
+      echo "Error: key must contain only alphanumeric characters and underscores" >&2
+      exit 1
+    fi
+    VALUE=$(grep -E "^${KEY}:" "$CONFIG_FILE" 2>/dev/null | tail -1 | awk '{print $2}' | tr -d '[:space:]' || true)
+    if [ -z "$VALUE" ]; then
+      VALUE=$(lookup_default "$KEY")
+    fi
+    printf '%s' "$VALUE"
+    ;;
+  set)
+    KEY="${2:?Usage: gstack-config set <key> <value>}"
+    VALUE="${3:?Usage: gstack-config set <key> <value>}"
+    # Validate key (alphanumeric + underscore only)
+    if ! printf '%s' "$KEY" | grep -qE '^[a-zA-Z0-9_]+$'; then
+      echo "Error: key must contain only alphanumeric characters and underscores" >&2
+      exit 1
+    fi
+    # V1: whitelist values for keys with closed value domains. Unknown values warn + default.
+    if [ "$KEY" = "explain_level" ] && [ "$VALUE" != "default" ] && [ "$VALUE" != "terse" ]; then
+      echo "Warning: explain_level '$VALUE' not recognized. Valid values: default, terse. Using default." >&2
+      VALUE="default"
+    fi
+    if [ "$KEY" = "artifacts_sync_mode" ] && [ "$VALUE" != "off" ] && [ "$VALUE" != "artifacts-only" ] && [ "$VALUE" != "full" ]; then
+      echo "Warning: artifacts_sync_mode '$VALUE' not recognized. Valid values: off, artifacts-only, full. Using off." >&2
+      VALUE="off"
+    fi
+    mkdir -p "$STATE_DIR"
+    # Write annotated header on first creation
+    if [ ! -f "$CONFIG_FILE" ]; then
+      printf '%s' "$CONFIG_HEADER" > "$CONFIG_FILE"
+    fi
+    # Escape sed special chars in value and drop embedded newlines
+    ESC_VALUE="$(printf '%s' "$VALUE" | head -1 | sed 's/[&/\]/\\&/g')"
+    if grep -qE "^${KEY}:" "$CONFIG_FILE" 2>/dev/null; then
+      # Portable in-place edit (BSD sed uses -i '', GNU sed uses -i without arg)
+      _tmpfile="$(mktemp "${CONFIG_FILE}.XXXXXX")"
+      sed "/^${KEY}:/s/.*/${KEY}: ${ESC_VALUE}/" "$CONFIG_FILE" > "$_tmpfile" && mv "$_tmpfile" "$CONFIG_FILE"
+    else
+      echo "${KEY}: ${VALUE}" >> "$CONFIG_FILE"
+    fi
+    # Auto-relink skills when prefix setting changes (skip during setup to avoid recursive call)
+    if [ "$KEY" = "skill_prefix" ] && [ -z "${GSTACK_SETUP_RUNNING:-}" ]; then
+      GSTACK_RELINK="$(dirname "$0")/gstack-relink"
+      [ -x "$GSTACK_RELINK" ] && "$GSTACK_RELINK" || true
+    fi
+    ;;
+  list)
+    if [ -f "$CONFIG_FILE" ]; then
+      cat "$CONFIG_FILE"
+    fi
+    echo ""
+    echo "# ─── Active values (including defaults for unset keys) ───"
+    for KEY in proactive routing_declined telemetry auto_upgrade update_check \
+               skill_prefix checkpoint_mode checkpoint_push codex_reviews \
+               gstack_contributor skip_eng_review workspace_root \
+               artifacts_sync_mode artifacts_sync_mode_prompted; do
+      VALUE=$(grep -E "^${KEY}:" "$CONFIG_FILE" 2>/dev/null | tail -1 | awk '{print $2}' | tr -d '[:space:]' || true)
+      SOURCE="default"
+      if [ -n "$VALUE" ]; then
+        SOURCE="set"
+      else
+        VALUE=$(lookup_default "$KEY")
+      fi
+      printf '  %-24s %s (%s)\n' "$KEY:" "$VALUE" "$SOURCE"
+    done
+    ;;
+  defaults)
+    echo "# gstack-config defaults"
+    for KEY in proactive routing_declined telemetry auto_upgrade update_check \
+               skill_prefix checkpoint_mode checkpoint_push codex_reviews \
+               gstack_contributor skip_eng_review workspace_root \
+               artifacts_sync_mode artifacts_sync_mode_prompted; do
+      printf '  %-24s %s\n' "$KEY:" "$(lookup_default "$KEY")"
+    done
+    ;;
+  *)
+    echo "Usage: gstack-config {get|set|list|defaults} [key] [value]"
+    exit 1
+    ;;
+esac

bin/gstack-developer-profile

@@ -0,0 +1,450 @@
+#!/usr/bin/env bash
+# gstack-developer-profile — unified developer profile access and derivation.
+#
+# Supersedes bin/gstack-builder-profile. The old binary remains as a legacy
+# shim that delegates to `gstack-developer-profile --read`.
+#
+# Subcommands:
+#   --read              (default)  emit KEY: VALUE pairs in builder-profile format
+#                                  for /office-hours compatibility.
+#   --derive            recompute inferred dimensions from question events;
+#                       write updated ~/.gstack/developer-profile.json.
+#   --profile           emit the full profile as JSON (all fields).
+#   --gap               emit declared-vs-inferred gap as JSON.
+#   --trace <dim>       show events that contributed to a dimension.
+#   --narrative         (v2 stub) output a coach bio paragraph.
+#   --vibe              (v2 stub) output the one-word archetype.
+#   --check-mismatch    detect meaningful gaps between declared and observed.
+#   --migrate           migrate builder-profile.jsonl → developer-profile.json.
+#                       Idempotent; archives the source file on success.
+#
+# Profile file: ~/.gstack/developer-profile.json (unified schema — see
+# docs/designs/PLAN_TUNING_V0.md). Event file: ~/.gstack/projects/{SLUG}/
+# question-events.jsonl.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
+PROFILE_FILE="$GSTACK_HOME/developer-profile.json"
+LEGACY_FILE="$GSTACK_HOME/builder-profile.jsonl"
+eval "$("$SCRIPT_DIR/gstack-slug" 2>/dev/null || true)"
+SLUG="${SLUG:-unknown}"
+
+CMD="${1:---read}"
+shift || true
+
+# -----------------------------------------------------------------------
+# Migration: builder-profile.jsonl → developer-profile.json
+# -----------------------------------------------------------------------
+do_migrate() {
+  if [ ! -f "$LEGACY_FILE" ]; then
+    echo "MIGRATE: no legacy file to migrate"
+    return 0
+  fi
+
+  if [ -f "$PROFILE_FILE" ]; then
+    # Already migrated — no-op (idempotent).
+    echo "MIGRATE: already migrated (developer-profile.json exists)"
+    return 0
+  fi
+
+  # Run migration in a temp file, then atomic rename.
+  local TMPOUT
+  TMPOUT=$(mktemp "$GSTACK_HOME/developer-profile.json.XXXXXX.tmp")
+  trap 'rm -f "$TMPOUT"' EXIT
+
+  cat "$LEGACY_FILE" | bun -e "
+    const lines = (await Bun.stdin.text()).trim().split('\n').filter(Boolean);
+    const sessions = [];
+    const signalsAcc = {};
+    const resources = new Set();
+    const topics = new Set();
+    for (const line of lines) {
+      try {
+        const e = JSON.parse(line);
+        sessions.push(e);
+        for (const s of (e.signals || [])) {
+          signalsAcc[s] = (signalsAcc[s] || 0) + 1;
+        }
+        for (const r of (e.resources_shown || [])) resources.add(r);
+        for (const t of (e.topics || [])) topics.add(t);
+      } catch {}
+    }
+    const profile = {
+      identity: {},
+      declared: {},
+      inferred: {
+        values: {
+          scope_appetite: 0.5,
+          risk_tolerance: 0.5,
+          detail_preference: 0.5,
+          autonomy: 0.5,
+          architecture_care: 0.5,
+        },
+        sample_size: 0,
+        diversity: { skills_covered: 0, question_ids_covered: 0, days_span: 0 },
+      },
+      gap: {},
+      overrides: {},
+      sessions,
+      signals_accumulated: signalsAcc,
+      resources_shown: Array.from(resources),
+      topics: Array.from(topics),
+      migrated_at: new Date().toISOString(),
+      schema_version: 1,
+    };
+    console.log(JSON.stringify(profile, null, 2));
+  " > "$TMPOUT"
+
+  # Atomic rename.
+  mv "$TMPOUT" "$PROFILE_FILE"
+  trap - EXIT
+
+  # gbrain-sync: enqueue the migrated file for cross-machine sync (no-op if off).
+  SCRIPT_DIR_E="$(cd "$(dirname "$0")" && pwd)"
+  "$SCRIPT_DIR_E/gstack-brain-enqueue" "developer-profile.json" 2>/dev/null &
+
+  # Archive the legacy file.
+  local TS
+  TS="$(date +%Y-%m-%d-%H%M%S)"
+  mv "$LEGACY_FILE" "$LEGACY_FILE.migrated-$TS"
+
+  local COUNT
+  COUNT=$(bun -e "console.log(JSON.parse(require('fs').readFileSync('$PROFILE_FILE','utf-8')).sessions.length)" 2>/dev/null || echo "?")
+  echo "MIGRATE: ok — migrated $COUNT sessions from builder-profile.jsonl"
+}
+
+# -----------------------------------------------------------------------
+# Load-or-migrate helper: ensure developer-profile.json exists.
+# Auto-migrates from builder-profile.jsonl if present.
+# Returns path to profile file via stdout. Creates a minimal stub if nothing exists.
+# -----------------------------------------------------------------------
+ensure_profile() {
+  if [ -f "$PROFILE_FILE" ]; then
+    return 0
+  fi
+  if [ -f "$LEGACY_FILE" ]; then
+    do_migrate >/dev/null
+    return 0
+  fi
+  # Nothing yet — create a stub.
+  mkdir -p "$GSTACK_HOME"
+  cat > "$PROFILE_FILE" <<EOF
+{
+  "identity": {},
+  "declared": {},
+  "inferred": {
+    "values": {
+      "scope_appetite": 0.5,
+      "risk_tolerance": 0.5,
+      "detail_preference": 0.5,
+      "autonomy": 0.5,
+      "architecture_care": 0.5
+    },
+    "sample_size": 0,
+    "diversity": { "skills_covered": 0, "question_ids_covered": 0, "days_span": 0 }
+  },
+  "gap": {},
+  "overrides": {},
+  "sessions": [],
+  "signals_accumulated": {},
+  "schema_version": 1
+}
+EOF
+}
+
+# -----------------------------------------------------------------------
+# Read: emit legacy KEY: VALUE output for /office-hours compat.
+# -----------------------------------------------------------------------
+do_read() {
+  ensure_profile
+  cat "$PROFILE_FILE" | bun -e "
+    const p = JSON.parse(await Bun.stdin.text());
+    const sessions = p.sessions || [];
+    const count = sessions.length;
+    let tier = 'introduction';
+    if (count >= 8) tier = 'inner_circle';
+    else if (count >= 4) tier = 'regular';
+    else if (count >= 1) tier = 'welcome_back';
+
+    const last = sessions[count - 1] || {};
+    const prev = sessions[count - 2] || {};
+    const crossProject = prev.project_slug && last.project_slug
+      ? prev.project_slug !== last.project_slug
+      : false;
+
+    const designs = sessions.map(e => e.design_doc || '').filter(Boolean);
+    const designTitles = sessions
+      .map(e => (e.design_doc ? (e.project_slug || 'unknown') : ''))
+      .filter(Boolean);
+
+    const signalCounts = p.signals_accumulated || {};
+    let totalSignals = 0;
+    for (const v of Object.values(signalCounts)) totalSignals += v;
+    const signalStr = Object.entries(signalCounts).map(([k,v]) => k + ':' + v).join(',');
+
+    const builderSessions = sessions.filter(e => e.mode !== 'startup').length;
+    const nudgeEligible = builderSessions >= 3 && totalSignals >= 5;
+
+    const resources = p.resources_shown || [];
+    const topics = p.topics || [];
+
+    console.log('SESSION_COUNT: ' + count);
+    console.log('TIER: ' + tier);
+    console.log('LAST_PROJECT: ' + (last.project_slug || ''));
+    console.log('LAST_ASSIGNMENT: ' + (last.assignment || ''));
+    console.log('LAST_DESIGN_TITLE: ' + (last.design_doc || ''));
+    console.log('DESIGN_COUNT: ' + designs.length);
+    console.log('DESIGN_TITLES: ' + JSON.stringify(designTitles));
+    console.log('ACCUMULATED_SIGNALS: ' + signalStr);
+    console.log('TOTAL_SIGNAL_COUNT: ' + totalSignals);
+    console.log('CROSS_PROJECT: ' + crossProject);
+    console.log('NUDGE_ELIGIBLE: ' + nudgeEligible);
+    console.log('RESOURCES_SHOWN: ' + resources.join(','));
+    console.log('RESOURCES_SHOWN_COUNT: ' + resources.length);
+    console.log('TOPICS: ' + topics.join(','));
+  "
+}
+
+# -----------------------------------------------------------------------
+# Profile: emit the full JSON
+# -----------------------------------------------------------------------
+do_profile() {
+  ensure_profile
+  cat "$PROFILE_FILE"
+}
+
+# -----------------------------------------------------------------------
+# Gap: declared vs inferred diff
+# -----------------------------------------------------------------------
+do_gap() {
+  ensure_profile
+  cat "$PROFILE_FILE" | bun -e "
+    const p = JSON.parse(await Bun.stdin.text());
+    const declared = p.declared || {};
+    const inferred = (p.inferred && p.inferred.values) || {};
+    const dims = ['scope_appetite','risk_tolerance','detail_preference','autonomy','architecture_care'];
+    const gap = {};
+    for (const d of dims) {
+      if (declared[d] !== undefined && inferred[d] !== undefined) {
+        gap[d] = +(Math.abs(declared[d] - inferred[d])).toFixed(3);
+      }
+    }
+    console.log(JSON.stringify({ declared, inferred, gap }, null, 2));
+  "
+}
+
+# -----------------------------------------------------------------------
+# Derive: recompute inferred dimensions from question-events.jsonl
+# -----------------------------------------------------------------------
+do_derive() {
+  ensure_profile
+  local EVENTS="$GSTACK_HOME/projects/$SLUG/question-log.jsonl"
+  local REGISTRY="$ROOT_DIR/scripts/question-registry.ts"
+  local SIGNALS="$ROOT_DIR/scripts/psychographic-signals.ts"
+  if [ ! -f "$REGISTRY" ] || [ ! -f "$SIGNALS" ]; then
+    echo "DERIVE: registry or signals file missing, cannot derive" >&2
+    exit 1
+  fi
+
+  cd "$ROOT_DIR"
+  PROFILE_FILE_PATH="$PROFILE_FILE" EVENTS_PATH="$EVENTS" bun -e "
+    import('./scripts/question-registry.ts').then(async (regmod) => {
+      const sigmod = await import('./scripts/psychographic-signals.ts');
+      const fs = require('fs');
+      const { QUESTIONS } = regmod;
+      const { SIGNAL_MAP, applySignal, newDimensionTotals, normalizeToDimensionValue } = sigmod;
+
+      const profilePath = process.env.PROFILE_FILE_PATH;
+      const eventsPath = process.env.EVENTS_PATH;
+      const profile = JSON.parse(fs.readFileSync(profilePath, 'utf-8'));
+
+      let lines = [];
+      if (fs.existsSync(eventsPath)) {
+        lines = fs.readFileSync(eventsPath, 'utf-8').trim().split('\n').filter(Boolean);
+      }
+
+      const totals = newDimensionTotals();
+      const skills = new Set();
+      const qids = new Set();
+      const days = new Set();
+      let count = 0;
+      for (const line of lines) {
+        let e;
+        try { e = JSON.parse(line); } catch { continue; }
+        if (!e.question_id || !e.user_choice) continue;
+        count++;
+        skills.add(e.skill);
+        qids.add(e.question_id);
+        if (e.ts) days.add(String(e.ts).slice(0,10));
+        const def = QUESTIONS[e.question_id];
+        if (def && def.signal_key) {
+          applySignal(totals, def.signal_key, e.user_choice);
+        }
+      }
+
+      const values = {};
+      for (const [dim, total] of Object.entries(totals)) {
+        values[dim] = +normalizeToDimensionValue(total).toFixed(3);
+      }
+
+      profile.inferred = {
+        values,
+        sample_size: count,
+        diversity: {
+          skills_covered: skills.size,
+          question_ids_covered: qids.size,
+          days_span: days.size,
+        },
+      };
+
+      // Recompute gap.
+      const gap = {};
+      for (const d of Object.keys(values)) {
+        if (profile.declared && profile.declared[d] !== undefined) {
+          gap[d] = +(Math.abs(profile.declared[d] - values[d])).toFixed(3);
+        }
+      }
+      profile.gap = gap;
+      profile.derived_at = new Date().toISOString();
+
+      const tmp = profilePath + '.tmp';
+      fs.writeFileSync(tmp, JSON.stringify(profile, null, 2));
+      fs.renameSync(tmp, profilePath);
+      console.log('DERIVE: ok — ' + count + ' events, ' + skills.size + ' skills, ' + qids.size + ' questions');
+    }).catch(err => { console.error('DERIVE:', err.message); process.exit(1); });
+  "
+}
+
+# -----------------------------------------------------------------------
+# Trace: show events contributing to a dimension
+# -----------------------------------------------------------------------
+do_trace() {
+  local DIM="${1:-}"
+  if [ -z "$DIM" ]; then
+    echo "TRACE: missing dimension argument" >&2
+    exit 1
+  fi
+  local EVENTS="$GSTACK_HOME/projects/$SLUG/question-log.jsonl"
+  if [ ! -f "$EVENTS" ]; then
+    echo "TRACE: no events for this project"
+    return 0
+  fi
+  cd "$ROOT_DIR"
+  EVENTS_PATH="$EVENTS" TRACE_DIM="$DIM" bun -e "
+    import('./scripts/question-registry.ts').then(async (regmod) => {
+      const sigmod = await import('./scripts/psychographic-signals.ts');
+      const fs = require('fs');
+      const { QUESTIONS } = regmod;
+      const { SIGNAL_MAP } = sigmod;
+      const target = process.env.TRACE_DIM;
+      const lines = fs.readFileSync(process.env.EVENTS_PATH, 'utf-8').trim().split('\n').filter(Boolean);
+      const rows = [];
+      for (const line of lines) {
+        let e;
+        try { e = JSON.parse(line); } catch { continue; }
+        const def = QUESTIONS[e.question_id];
+        if (!def || !def.signal_key) continue;
+        const deltas = SIGNAL_MAP[def.signal_key]?.[e.user_choice] || [];
+        for (const d of deltas) {
+          if (d.dim === target) {
+            rows.push({ ts: e.ts, question_id: e.question_id, choice: e.user_choice, delta: d.delta });
+          }
+        }
+      }
+      if (rows.length === 0) {
+        console.log('TRACE: no events contribute to ' + target);
+      } else {
+        console.log('TRACE: ' + rows.length + ' events for ' + target);
+        for (const r of rows) {
+          console.log('  ' + (r.ts || '').slice(0,19) + '  ' + r.question_id + '  → ' + r.choice + '  (' + (r.delta > 0 ? '+' : '') + r.delta + ')');
+        }
+      }
+    });
+  "
+}
+
+# -----------------------------------------------------------------------
+# Check mismatch: flag when declared ≠ inferred by > threshold
+# -----------------------------------------------------------------------
+do_check_mismatch() {
+  ensure_profile
+  cat "$PROFILE_FILE" | bun -e "
+    const p = JSON.parse(await Bun.stdin.text());
+    const declared = p.declared || {};
+    const inferred = (p.inferred && p.inferred.values) || {};
+    const sampleSize = (p.inferred && p.inferred.sample_size) || 0;
+    const diversity = (p.inferred && p.inferred.diversity) || {};
+
+    // Require enough data before reporting mismatch.
+    if (sampleSize < 10) {
+      console.log('MISMATCH: not enough data (' + sampleSize + ' events; need 10+)');
+      process.exit(0);
+    }
+
+    const THRESHOLD = 0.3;
+    const flagged = [];
+    for (const d of Object.keys(declared)) {
+      if (inferred[d] === undefined) continue;
+      const gap = Math.abs(declared[d] - inferred[d]);
+      if (gap > THRESHOLD) {
+        flagged.push({ dim: d, declared: declared[d], inferred: inferred[d], gap: +gap.toFixed(3) });
+      }
+    }
+
+    if (flagged.length === 0) {
+      console.log('MISMATCH: none');
+    } else {
+      console.log('MISMATCH: ' + flagged.length + ' dimension(s) disagree (gap > ' + THRESHOLD + ')');
+      for (const f of flagged) {
+        console.log('  ' + f.dim + ': declared ' + f.declared + ' vs inferred ' + f.inferred + ' (gap ' + f.gap + ')');
+      }
+    }
+  "
+}
+
+# -----------------------------------------------------------------------
+# Narrative + Vibe (v2 stubs)
+# -----------------------------------------------------------------------
+do_narrative() {
+  echo "NARRATIVE: (v2 — not yet implemented; use /plan-tune profile for now)"
+}
+
+do_vibe() {
+  ensure_profile
+  cd "$ROOT_DIR"
+  cat "$PROFILE_FILE" | PROFILE_DATA="$(cat "$PROFILE_FILE")" bun -e "
+    import('./scripts/archetypes.ts').then(async (mod) => {
+      const p = JSON.parse(process.env.PROFILE_DATA);
+      const dims = (p.inferred && p.inferred.values) || {
+        scope_appetite: 0.5, risk_tolerance: 0.5, detail_preference: 0.5,
+        autonomy: 0.5, architecture_care: 0.5,
+      };
+      const arch = mod.matchArchetype(dims);
+      console.log(arch.name);
+      console.log(arch.description);
+    });
+  "
+}
+
+# -----------------------------------------------------------------------
+# Dispatch
+# -----------------------------------------------------------------------
+case "$CMD" in
+  --read) do_read ;;
+  --profile) do_profile ;;
+  --gap) do_gap ;;
+  --derive) do_derive ;;
+  --trace) do_trace "$@" ;;
+  --narrative) do_narrative ;;
+  --vibe) do_vibe ;;
+  --check-mismatch) do_check_mismatch ;;
+  --migrate) do_migrate ;;
+  --help|-h) sed -n '1,/^set -euo/p' "$0" | sed 's|^# \?||' ;;
+  *)
+    echo "gstack-developer-profile: unknown subcommand '$CMD'" >&2
+    echo "run --help for usage" >&2
+    exit 1
+    ;;
+esac

bin/gstack-diff-scope

@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+# gstack-diff-scope — categorize what changed in the diff against a base branch
+# Usage: source <(gstack-diff-scope main)  → sets SCOPE_FRONTEND=true SCOPE_BACKEND=false ...
+# Or:    gstack-diff-scope main           → prints SCOPE_*=... lines
+set -euo pipefail
+
+BASE="${1:-main}"
+
+# Get changed file list
+FILES=$(git diff "${BASE}...HEAD" --name-only 2>/dev/null || git diff "${BASE}" --name-only 2>/dev/null || echo "")
+
+if [ -z "$FILES" ]; then
+  echo "SCOPE_FRONTEND=false"
+  echo "SCOPE_BACKEND=false"
+  echo "SCOPE_PROMPTS=false"
+  echo "SCOPE_TESTS=false"
+  echo "SCOPE_DOCS=false"
+  echo "SCOPE_CONFIG=false"
+  echo "SCOPE_MIGRATIONS=false"
+  echo "SCOPE_API=false"
+  echo "SCOPE_AUTH=false"
+  exit 0
+fi
+
+FRONTEND=false
+BACKEND=false
+PROMPTS=false
+TESTS=false
+DOCS=false
+CONFIG=false
+MIGRATIONS=false
+API=false
+AUTH=false
+
+while IFS= read -r f; do
+  case "$f" in
+    # Frontend: CSS, views, components, templates
+    *.css|*.scss|*.less|*.sass|*.pcss|*.module.css|*.module.scss) FRONTEND=true ;;
+    *.tsx|*.jsx|*.vue|*.svelte|*.astro) FRONTEND=true ;;
+    *.erb|*.haml|*.slim|*.hbs|*.ejs) FRONTEND=true ;;
+    *.html) FRONTEND=true ;;
+    tailwind.config.*|postcss.config.*) FRONTEND=true ;;
+    app/views/*|*/components/*|styles/*|css/*|app/assets/stylesheets/*) FRONTEND=true ;;
+
+    # Prompts: prompt builders, system prompts, generation services
+    *prompt_builder*|*generation_service*|*writer_service*|*designer_service*) PROMPTS=true ;;
+    *evaluator*|*scorer*|*classifier_service*|*analyzer*) PROMPTS=true ;;
+    *voice*.rb|*writing*.rb|*prompt*.rb|*token*.rb) PROMPTS=true ;;
+    app/services/chat_tools/*|app/services/x_thread_tools/*) PROMPTS=true ;;
+    config/system_prompts/*) PROMPTS=true ;;
+
+    # Tests
+    *.test.*|*.spec.*|*_test.*|*_spec.*) TESTS=true ;;
+    test/*|tests/*|spec/*|__tests__/*|cypress/*|e2e/*) TESTS=true ;;
+
+    # Docs
+    *.md) DOCS=true ;;
+
+    # Config
+    package.json|package-lock.json|yarn.lock|bun.lockb) CONFIG=true ;;
+    Gemfile|Gemfile.lock) CONFIG=true ;;
+    *.yml|*.yaml) CONFIG=true ;;
+    .github/*) CONFIG=true ;;
+    requirements.txt|pyproject.toml|go.mod|Cargo.toml|composer.json) CONFIG=true ;;
+
+    # Migrations: database migration files
+    db/migrate/*|*/migrations/*|alembic/*|prisma/migrations/*) MIGRATIONS=true ;;
+
+    # API: routes, controllers, endpoints, GraphQL/OpenAPI schemas
+    *controller*|*route*|*endpoint*|*/api/*) API=true ;;
+    *.graphql|*.gql|openapi.*|swagger.*) API=true ;;
+
+    # Auth: authentication, authorization, sessions, permissions
+    *auth*|*session*|*jwt*|*oauth*|*permission*|*role*) AUTH=true ;;
+
+    # Backend: everything else that's code (excluding views/components already matched)
+    *.rb|*.py|*.go|*.rs|*.java|*.php|*.ex|*.exs) BACKEND=true ;;
+    *.ts|*.js) BACKEND=true ;;  # Non-component TS/JS is backend
+  esac
+done <<< "$FILES"
+
+echo "SCOPE_FRONTEND=$FRONTEND"
+echo "SCOPE_BACKEND=$BACKEND"
+echo "SCOPE_PROMPTS=$PROMPTS"
+echo "SCOPE_TESTS=$TESTS"
+echo "SCOPE_DOCS=$DOCS"
+echo "SCOPE_CONFIG=$CONFIG"
+echo "SCOPE_MIGRATIONS=$MIGRATIONS"
+echo "SCOPE_API=$API"
+echo "SCOPE_AUTH=$AUTH"

bin/gstack-extension

@@ -0,0 +1,65 @@
+#!/bin/bash
+# gstack-extension — helper to install the Chrome extension
+#
+# When using $B connect, the extension auto-loads. This script is for
+# installing it in your regular Chrome (not the Playwright-controlled one).
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# Find the extension directory
+EXT_DIR=""
+if [ -f "$REPO_ROOT/extension/manifest.json" ]; then
+  EXT_DIR="$REPO_ROOT/extension"
+elif [ -f "$HOME/.claude/skills/gstack/extension/manifest.json" ]; then
+  EXT_DIR="$HOME/.claude/skills/gstack/extension"
+fi
+
+if [ -z "$EXT_DIR" ]; then
+  echo "Error: extension/ directory not found."
+  echo "Expected at: $REPO_ROOT/extension/ or ~/.claude/skills/gstack/extension/"
+  exit 1
+fi
+
+# Copy path to clipboard
+echo -n "$EXT_DIR" | pbcopy 2>/dev/null
+
+# Get browse server port
+PORT=""
+STATE_FILE="$REPO_ROOT/.gstack/browse.json"
+if [ -f "$STATE_FILE" ]; then
+  PORT=$(grep -o '"port":[0-9]*' "$STATE_FILE" | grep -o '[0-9]*')
+fi
+
+echo "gstack Chrome Extension Setup"
+echo "=============================="
+echo ""
+echo "Extension path (copied to clipboard):"
+echo "  $EXT_DIR"
+echo ""
+
+if [ -n "$PORT" ]; then
+  echo "Browse server port: $PORT"
+  echo ""
+fi
+
+echo "Quick install (if using \$B connect):"
+echo "  The extension auto-loads when you run \$B connect."
+echo "  No manual installation needed!"
+echo ""
+echo "Manual install (for your regular Chrome):"
+echo ""
+echo "  1. Opening chrome://extensions now..."
+
+# Open chrome://extensions
+osascript -e 'tell application "Google Chrome" to open location "chrome://extensions"' 2>/dev/null || \
+  open "chrome://extensions" 2>/dev/null || \
+  echo "     Could not open Chrome. Navigate to chrome://extensions manually."
+
+echo "  2. Toggle 'Developer mode' ON (top-right)"
+echo "  3. Click 'Load unpacked'"
+echo "  4. In the file picker: Cmd+Shift+G → paste (path is in your clipboard) → Enter → Select"
+echo "  5. Click the gstack puzzle icon in toolbar → enter port: ${PORT:-<check \$B status>}"
+echo "  6. Click 'Open Side Panel'"

bin/gstack-gbrain-detect

@@ -0,0 +1,223 @@
+#!/usr/bin/env -S bun run
+/**
+ * gstack-gbrain-detect — emit current gbrain/gstack-brain state as JSON.
+ *
+ * Rewritten from bash to TypeScript in v{X.Y.Z.0} to share the engine-status
+ * classifier with bin/gstack-gbrain-sync.ts. Single source of truth via
+ * lib/gbrain-local-status.ts. Filename and exec semantics unchanged: callers
+ * just shell out to the file path; the bun shebang resolves at runtime.
+ *
+ * Output (always valid JSON, even when every check is false):
+ *   {
+ *     "gbrain_on_path": true|false,
+ *     "gbrain_version": "0.18.2" | null,
+ *     "gbrain_config_exists": true|false,
+ *     "gbrain_engine": "pglite"|"postgres" | null,
+ *     "gbrain_doctor_ok": true|false,
+ *     "gbrain_mcp_mode": "local-stdio"|"remote-http"|"none",
+ *     "gstack_brain_sync_mode": "off"|"artifacts-only"|"full",
+ *     "gstack_brain_git": true|false,
+ *     "gstack_artifacts_remote": "https://..." | "",
+ *     "gbrain_local_status": "ok"|"no-cli"|"missing-config"|"broken-config"|"broken-db"
+ *   }
+ *
+ * Backward compatibility (per plan codex #5): the 9 pre-existing fields stay
+ * identical in name + type + value semantics. One new field added:
+ * gbrain_local_status. Key order may differ from the bash version's `jq -n`
+ * output — downstream parsers must not depend on key order (none currently do).
+ *
+ * Env:
+ *   GSTACK_HOME      — override ~/.gstack for state lookups (used by tests).
+ *   HOME             — effective user home (drives ~/.gbrain/config.json path).
+ *   GSTACK_DETECT_NO_CACHE=1 — bypass the 60s local-status cache.
+ */
+
+import { execFileSync } from "child_process";
+import { existsSync, readFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+
+import {
+  localEngineStatus,
+  resolveGbrainBin,
+  readGbrainVersion,
+} from "../lib/gbrain-local-status";
+
+const STATE_DIR = process.env.GSTACK_HOME || join(userHome(), ".gstack");
+const SCRIPT_DIR = __dirname;
+const CONFIG_BIN = join(SCRIPT_DIR, "gstack-config");
+const GBRAIN_CONFIG = join(userHome(), ".gbrain", "config.json");
+const CLAUDE_JSON = join(userHome(), ".claude.json");
+
+function userHome(): string {
+  return process.env.HOME || homedir();
+}
+
+function tryExec(cmd: string, args: string[], timeoutMs = 5_000): string | null {
+  try {
+    return execFileSync(cmd, args, {
+      encoding: "utf-8",
+      timeout: timeoutMs,
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function tryReadJSON(path: string): unknown | null {
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+// --- gbrain binary presence + version ---
+// Uses the shared memoized resolvers from lib/gbrain-local-status.ts so
+// detect and the classifier share probe results within one process.
+function detectGbrain(): { onPath: boolean; version: string | null } {
+  const bin = resolveGbrainBin();
+  if (!bin) return { onPath: false, version: null };
+  const verRaw = readGbrainVersion();
+  if (!verRaw) return { onPath: true, version: null };
+  // Match bash behavior: head -1 | tr -d '[:space:]'
+  const version = verRaw.split("\n")[0].replace(/\s+/g, "") || null;
+  return { onPath: true, version };
+}
+
+// --- gbrain config existence + engine kind ---
+function detectConfig(): { exists: boolean; engine: "pglite" | "postgres" | null } {
+  if (!existsSync(GBRAIN_CONFIG)) return { exists: false, engine: null };
+  const parsed = tryReadJSON(GBRAIN_CONFIG) as { engine?: string } | null;
+  if (!parsed) return { exists: true, engine: null };
+  if (parsed.engine === "pglite" || parsed.engine === "postgres") {
+    return { exists: true, engine: parsed.engine };
+  }
+  return { exists: true, engine: null };
+}
+
+// --- gbrain doctor health (any nonzero exit or non-"ok"/"warnings" status → false) ---
+//
+// Uses --fast to avoid hanging on a dead DB. Per the local-status classifier
+// (which probes DB directly via `gbrain sources list`), gbrain_doctor_ok is a
+// coarse health summary, not engine-reachability — that's gbrain_local_status.
+function detectDoctor(onPath: boolean): boolean {
+  if (!onPath) return false;
+  const out = tryExec("gbrain", ["doctor", "--json", "--fast"], 3_000);
+  if (!out) return false;
+  try {
+    const parsed = JSON.parse(out) as { status?: string };
+    return parsed.status === "ok" || parsed.status === "warnings";
+  } catch {
+    return false;
+  }
+}
+
+// --- artifacts sync mode ---
+function detectSyncMode(): "off" | "artifacts-only" | "full" {
+  if (!existsSync(CONFIG_BIN)) return "off";
+  const out = tryExec(CONFIG_BIN, ["get", "artifacts_sync_mode"], 2_000);
+  if (out === "off" || out === "artifacts-only" || out === "full") return out;
+  return "off";
+}
+
+// --- gstack-brain git repo present? ---
+function detectBrainGit(): boolean {
+  return existsSync(join(STATE_DIR, ".git"));
+}
+
+// --- MCP mode: local-stdio | remote-http | none ---
+//
+// Defense-in-depth fallback chain (same ordering as the bash version):
+//   1. `claude mcp get gbrain --json` — public CLI surface, structured output
+//   2. `claude mcp list` text-grep    — older claude versions without --json
+//   3. `~/.claude.json` jq read       — last resort if `claude` isn't on PATH
+function detectMcpMode(): "local-stdio" | "remote-http" | "none" {
+  const claudeOnPath = tryExec("sh", ["-c", "command -v claude"], 1_000) !== null;
+  if (claudeOnPath) {
+    // Tier 1: `claude mcp get gbrain --json`
+    const get = tryExec("claude", ["mcp", "get", "gbrain", "--json"], 3_000);
+    if (get) {
+      try {
+        const parsed = JSON.parse(get) as {
+          type?: string;
+          transport?: string;
+          command?: string;
+          url?: string;
+        };
+        const mtype = parsed.type || parsed.transport || "";
+        if (mtype === "http" || mtype === "sse") return "remote-http";
+        if (mtype === "stdio") return "local-stdio";
+        if (parsed.url) return "remote-http";
+        if (parsed.command) return "local-stdio";
+      } catch {
+        // fall through
+      }
+    }
+    // Tier 2: `claude mcp list` text-grep
+    const list = tryExec("claude", ["mcp", "list"], 3_000);
+    if (list) {
+      const line = list.split("\n").find((l) => /^gbrain:/.test(l));
+      if (line) {
+        if (/\b(http|HTTP)\b/.test(line)) return "remote-http";
+        return "local-stdio";
+      }
+    }
+  }
+  // Tier 3: read ~/.claude.json directly
+  const cj = tryReadJSON(CLAUDE_JSON) as
+    | { mcpServers?: { gbrain?: { type?: string; transport?: string; command?: string; url?: string } } }
+    | null;
+  const entry = cj?.mcpServers?.gbrain;
+  if (entry) {
+    const mtype = entry.type || entry.transport || "";
+    if (mtype === "url" || mtype === "http" || mtype === "sse") return "remote-http";
+    if (mtype === "stdio") return "local-stdio";
+    if (entry.url) return "remote-http";
+    if (entry.command) return "local-stdio";
+  }
+  return "none";
+}
+
+// --- artifacts remote URL with brain-* fallback during the rename migration window ---
+function detectArtifactsRemote(): string {
+  const newPath = join(userHome(), ".gstack-artifacts-remote.txt");
+  const oldPath = join(userHome(), ".gstack-brain-remote.txt");
+  for (const p of [newPath, oldPath]) {
+    if (existsSync(p)) {
+      try {
+        return readFileSync(p, "utf-8").split("\n")[0].trim();
+      } catch {
+        // fall through
+      }
+    }
+  }
+  return "";
+}
+
+function main(): void {
+  const gbrain = detectGbrain();
+  const config = detectConfig();
+  const noCache = process.env.GSTACK_DETECT_NO_CACHE === "1";
+
+  // Order MATCHES the bash version's jq output for callers that visually grep
+  // (key order doesn't affect JSON parsers, but minimizes review noise).
+  const out = {
+    gbrain_on_path: gbrain.onPath,
+    gbrain_version: gbrain.version,
+    gbrain_config_exists: config.exists,
+    gbrain_engine: config.engine,
+    gbrain_doctor_ok: detectDoctor(gbrain.onPath),
+    gbrain_mcp_mode: detectMcpMode(),
+    gstack_brain_sync_mode: detectSyncMode(),
+    gstack_brain_git: detectBrainGit(),
+    gstack_artifacts_remote: detectArtifactsRemote(),
+    gbrain_local_status: localEngineStatus({ noCache }),
+  };
+
+  process.stdout.write(JSON.stringify(out, null, 2) + "\n");
+}
+
+main();

bin/gstack-gbrain-install

@@ -0,0 +1,220 @@
+#!/usr/bin/env bash
+# gstack-gbrain-install — install the gbrain CLI on a local Mac.
+#
+# Usage:
+#   gstack-gbrain-install [--install-dir <dir>] [--pinned-commit <sha>] [--dry-run]
+#
+# D5 detect-first: before cloning anywhere, probe likely pre-existing
+# locations (~/git/gbrain and ~/gbrain) and reuse a working clone if one
+# exists. Falls back to a fresh clone of the pinned commit at ~/gbrain
+# (override with GBRAIN_INSTALL_DIR or --install-dir).
+#
+# D19 PATH-shadowing: after `bun link`, compare `gbrain --version` output
+# to the install-dir's package.json version. On mismatch, abort with an
+# actionable error listing every gbrain on PATH. Never "silently fixes"
+# PATH; setup skills should refuse broken environments.
+#
+# Prerequisites (checked before doing anything):
+#   - bun   (install: curl -fsSL https://bun.sh/install | bash)
+#   - git
+#   - network reachability to https://github.com
+#
+# The pinned commit is declared here rather than resolved dynamically so
+# upgrades are explicit and reviewable. Update PINNED_COMMIT when gstack
+# verifies compatibility with a new gbrain release.
+#
+# Env:
+#   GBRAIN_INSTALL_DIR — override default install path (~/gbrain)
+#
+# Exit codes:
+#   0 — success (or --dry-run printed the plan)
+#   2 — prerequisite missing or invalid argument
+#   3 — post-install validation failed (PATH shadow, broken binary, etc.)
+set -euo pipefail
+
+# --- defaults ---
+PINNED_COMMIT="08b3698e90532b7b66c445e6b1d8cdfe71822802"  # gbrain v0.18.2
+PINNED_TAG="v0.18.2"
+GBRAIN_REPO_URL="https://github.com/garrytan/gbrain.git"
+DEFAULT_INSTALL_DIR="${GBRAIN_INSTALL_DIR:-$HOME/gbrain}"
+INSTALL_DIR="$DEFAULT_INSTALL_DIR"
+DRY_RUN=false
+VALIDATE_ONLY=false
+
+die() { echo "gstack-gbrain-install: $*" >&2; exit 2; }
+fail() { echo "gstack-gbrain-install: $*" >&2; exit 3; }
+log()  { echo "gstack-gbrain-install: $*"; }
+
+# --- parse args ---
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --install-dir) INSTALL_DIR="$2"; shift 2 ;;
+    --pinned-commit) PINNED_COMMIT="$2"; PINNED_TAG=""; shift 2 ;;
+    --dry-run) DRY_RUN=true; shift ;;
+    --validate-only) VALIDATE_ONLY=true; shift ;;
+    --help|-h) sed -n '2,30p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    *) die "unknown flag: $1" ;;
+  esac
+done
+
+# --- prerequisites ---
+check_prereq() {
+  local bin="$1"
+  local hint="$2"
+  if ! command -v "$bin" >/dev/null 2>&1; then
+    fail "required tool '$bin' not found. $hint"
+  fi
+}
+
+if ! $VALIDATE_ONLY; then
+  check_prereq bun "Install: curl -fsSL https://bun.sh/install | bash"
+  check_prereq git "Install: xcode-select --install (macOS) or your package manager"
+
+  # GitHub reachability — fail fast if offline rather than hanging `git clone`.
+  # --max-time 10, --head (no body), quiet. Status code 200-4xx means we reached
+  # the server (even 404 is reachability proof).
+  if ! curl -s --head --max-time 10 https://github.com >/dev/null 2>&1; then
+    fail "cannot reach https://github.com. Check your network and try again."
+  fi
+fi
+
+# --- D5 detect-first: probe common locations before cloning fresh ---
+# Accept any directory that looks like a gbrain clone: has package.json
+# with name "gbrain" and a `bin.gbrain` entry. Don't accept version mismatches
+# here — we'll let bun link run and then D19-validate.
+is_valid_clone() {
+  local dir="$1"
+  [ -d "$dir" ] || return 1
+  [ -f "$dir/package.json" ] || return 1
+  local name
+  name=$(jq -r '.name // empty' "$dir/package.json" 2>/dev/null || true)
+  [ "$name" = "gbrain" ] || return 1
+  local bin
+  bin=$(jq -r '.bin.gbrain // empty' "$dir/package.json" 2>/dev/null || true)
+  [ -n "$bin" ] || return 1
+  return 0
+}
+
+DETECTED_CLONE=""
+if ! $VALIDATE_ONLY; then
+  for candidate in "$HOME/git/gbrain" "$HOME/gbrain" "$INSTALL_DIR"; do
+    if is_valid_clone "$candidate"; then
+      DETECTED_CLONE="$candidate"
+      break
+    fi
+  done
+fi
+
+if $VALIDATE_ONLY; then
+  log "validate-only mode: skipping detect + clone + install + link"
+elif [ -n "$DETECTED_CLONE" ]; then
+  log "detected existing gbrain clone at $DETECTED_CLONE — reusing"
+  INSTALL_DIR="$DETECTED_CLONE"
+else
+  # Fresh clone path.
+  if $DRY_RUN; then
+    log "DRY RUN: would clone $GBRAIN_REPO_URL @ $PINNED_COMMIT → $INSTALL_DIR"
+    exit 0
+  fi
+  if [ -d "$INSTALL_DIR" ]; then
+    fail "install dir $INSTALL_DIR exists but is not a valid gbrain clone. Remove it or pass --install-dir <other>."
+  fi
+  log "cloning $GBRAIN_REPO_URL → $INSTALL_DIR"
+  git clone --quiet "$GBRAIN_REPO_URL" "$INSTALL_DIR"
+  ( cd "$INSTALL_DIR" && git checkout --quiet "$PINNED_COMMIT" )
+  log "pinned to $PINNED_COMMIT${PINNED_TAG:+ ($PINNED_TAG)}"
+fi
+
+if $DRY_RUN; then
+  log "DRY RUN: would run bun install + bun link in $INSTALL_DIR"
+  exit 0
+fi
+
+# --- install + link ---
+# On Windows MSYS/Cygwin shells, bun's postinstall scripts (notably gbrain's
+# native-bindings setup) fail to parse path arguments correctly and abort
+# `bun install` with a non-zero exit. The package itself installs fine
+# without scripts, so detect Windows and pass --ignore-scripts there. The
+# `bun link` step below is unaffected.
+IS_WINDOWS=0
+case "$(uname -s)" in
+  MINGW*|MSYS*|CYGWIN*|Windows_NT) IS_WINDOWS=1 ;;
+esac
+
+if ! $VALIDATE_ONLY; then
+  if [ "$IS_WINDOWS" -eq 1 ]; then
+    log "running bun install --ignore-scripts in $INSTALL_DIR (Windows shell detected)"
+    ( cd "$INSTALL_DIR" && bun install --silent --ignore-scripts )
+  else
+    log "running bun install in $INSTALL_DIR"
+    ( cd "$INSTALL_DIR" && bun install --silent )
+  fi
+  log "running bun link in $INSTALL_DIR"
+  ( cd "$INSTALL_DIR" && bun link --silent )
+fi
+
+# --- D19 PATH-shadowing validation ---
+# Read the version from the install-dir's package.json; compare to
+# `gbrain --version`. If they disagree, PATH is returning a DIFFERENT
+# gbrain than the one we just linked. Fail hard with remediation.
+expected_version=$(jq -r '.version // empty' "$INSTALL_DIR/package.json" 2>/dev/null || true)
+if [ -z "$expected_version" ]; then
+  fail "cannot read version from $INSTALL_DIR/package.json (install may be broken)"
+fi
+
+if ! command -v gbrain >/dev/null 2>&1; then
+  fail "bun link completed but 'gbrain' is not on PATH. Ensure ~/.bun/bin is in your PATH."
+fi
+
+actual_version=$(gbrain --version 2>/dev/null | head -1 | awk '{print $NF}' | tr -d '[:space:]' || true)
+if [ -z "$actual_version" ]; then
+  fail "gbrain is on PATH but 'gbrain --version' produced no output — the binary may be broken."
+fi
+
+# Tolerate a leading "v" (gbrain may print either "0.18.2" or "v0.18.2").
+expected_norm="${expected_version#v}"
+actual_norm="${actual_version#v}"
+
+if [ "$actual_norm" != "$expected_norm" ]; then
+  echo "" >&2
+  echo "gstack-gbrain-install: PATH SHADOWING DETECTED" >&2
+  echo "" >&2
+  echo "  We just linked gbrain $expected_version from $INSTALL_DIR," >&2
+  echo "  but PATH is returning gbrain $actual_version." >&2
+  echo "" >&2
+  echo "  All gbrain binaries on PATH:" >&2
+  type -a gbrain 2>&1 | sed 's/^/    /' >&2 || true
+  echo "" >&2
+  echo "  Fix one of the following, then re-run /setup-gbrain:" >&2
+  echo "    a) rm the shadowing binary: rm \$(which gbrain)" >&2
+  echo "    b) prepend ~/.bun/bin to PATH in your shell rc" >&2
+  echo "    c) point GBRAIN_INSTALL_DIR at the shadowing binary's install dir" >&2
+  echo "" >&2
+  exit 3
+fi
+
+log "installed gbrain $actual_version from $INSTALL_DIR"
+
+# v1.40.0.0 post-install validation (T6 / codex review #19): --ignore-scripts
+# may skip artifacts gbrain needs at runtime, especially on Windows
+# MSYS/MINGW where we DID pass --ignore-scripts. `gbrain --version` above
+# already confirmed the binary runs; this second probe checks that the
+# subcommand surface is reachable (`sources` is the entry point the sync
+# stage hits first). If the probe fails, we warn but don't exit non-zero —
+# the user may still be able to use other commands.
+if ! gbrain sources --help >/dev/null 2>&1; then
+  echo "" >&2
+  echo "gstack-gbrain-install: WARNING — gbrain installed but 'gbrain sources --help' did not exit 0." >&2
+  if [ "$IS_WINDOWS" -eq 1 ]; then
+    echo "  Windows shells skip bun postinstall scripts; some gbrain features may need native build tools." >&2
+    echo "  If /sync-gbrain fails to find subcommands, install gbrain from a non-MSYS shell," >&2
+    echo "  or run: cd $INSTALL_DIR && bun install   (without --ignore-scripts)" >&2
+  else
+    echo "  This may be a transient gbrain CLI issue or a missing native dependency." >&2
+    echo "  If /sync-gbrain fails, re-run: cd $INSTALL_DIR && bun install" >&2
+  fi
+  echo "" >&2
+fi
+
+echo ""
+echo "Next: gbrain init --pglite   (or run /setup-gbrain for the full setup flow)"

bin/gstack-gbrain-lib.sh

@@ -0,0 +1,101 @@
+# gstack-gbrain-lib.sh — shared helpers for setup-gbrain bin scripts.
+#
+# This file is NOT executable; source it:
+#
+#   . "$(dirname "$0")/gstack-gbrain-lib.sh"
+#
+# Provides:
+#   read_secret_to_env <VARNAME> <prompt> [--echo-redacted <sed-expr>]
+#     — Read a secret from stdin into the named env var without echoing
+#     to the terminal. On SIGINT/SIGTERM/EXIT, restores terminal echo so
+#     future keystrokes are visible. Optionally emits a redacted preview
+#     of what was read so the user can visually confirm they pasted the
+#     right thing.
+#
+#     stdin handling: when stdin is a TTY, stty -echo suppresses echo
+#     while the user types. When stdin is piped (automated tests), the
+#     stty calls are skipped — piping into `read` is already invisible.
+#
+#     Var name must match [A-Z_][A-Z0-9_]* to prevent injection via
+#     `read -r "$varname"` expansion. Invalid names abort.
+#
+#     Exported after read so sub-processes inherit the secret. Caller
+#     is responsible for `unset <VARNAME>` when done.
+#
+# Load-bearing for D3-eng (shared secret helper across PAT + URL paste),
+# D10 (env-var handoff, never argv), D11 (PAT scope disclosure + SIGINT
+# restore), D16 (pooler URL paste hygiene with redacted preview).
+
+# _gstack_gbrain_validate_varname <name> — returns 0 if usable, 2 otherwise.
+_gstack_gbrain_validate_varname() {
+  local name="$1"
+  case "$name" in
+    [A-Z_][A-Z0-9_]*) return 0 ;;
+    *) return 2 ;;
+  esac
+}
+
+read_secret_to_env() {
+  local varname="" prompt="" redact_expr=""
+  # Parse leading positional args (varname, prompt), then optional flags.
+  if [ $# -lt 2 ]; then
+    echo "read_secret_to_env: usage: read_secret_to_env <VARNAME> <prompt> [--echo-redacted <sed-expr>]" >&2
+    return 2
+  fi
+  varname="$1"; shift
+  prompt="$1"; shift
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --echo-redacted) redact_expr="$2"; shift 2 ;;
+      *) echo "read_secret_to_env: unknown flag: $1" >&2; return 2 ;;
+    esac
+  done
+
+  if ! _gstack_gbrain_validate_varname "$varname"; then
+    echo "read_secret_to_env: invalid var name '$varname' (must match [A-Z_][A-Z0-9_]*)" >&2
+    return 2
+  fi
+
+  # stty manipulation only makes sense when stdin is a terminal. In CI /
+  # test / piped contexts we skip it — piped input doesn't echo anyway.
+  local is_tty=false
+  if [ -t 0 ]; then is_tty=true; fi
+
+  if $is_tty; then
+    # Save current stty state; restore on any exit path.
+    local saved_stty
+    saved_stty=$(stty -g 2>/dev/null || echo "")
+    # shellcheck disable=SC2064
+    trap "stty '$saved_stty' 2>/dev/null; printf '\n' >&2" INT TERM EXIT
+    stty -echo 2>/dev/null || true
+  fi
+
+  # Prompt on stderr so the caller can capture stdout cleanly.
+  printf '%s' "$prompt" >&2
+
+  # Read one line from stdin. `read -r` returns nonzero on EOF-without-
+  # newline but still populates `value` with whatever it saw — we want that
+  # content, so don't clear on failure.
+  local value=""
+  IFS= read -r value || true
+
+  if $is_tty; then
+    stty "$saved_stty" 2>/dev/null || true
+    trap - INT TERM EXIT
+    printf '\n' >&2
+  fi
+
+  # Assign + export to the named variable.
+  printf -v "$varname" '%s' "$value"
+  # shellcheck disable=SC2163
+  export "$varname"
+
+  # Optional redacted preview after successful read.
+  if [ -n "$redact_expr" ] && [ -n "$value" ]; then
+    local preview
+    preview=$(printf '%s' "$value" | sed "$redact_expr" 2>/dev/null || true)
+    if [ -n "$preview" ]; then
+      printf 'Got: %s\n' "$preview" >&2
+    fi
+  fi
+}

bin/gstack-gbrain-mcp-verify

@@ -0,0 +1,179 @@
+#!/usr/bin/env bash
+# gstack-gbrain-mcp-verify — probe a remote gbrain MCP endpoint.
+#
+# Usage:
+#   GBRAIN_MCP_TOKEN=<bearer> gstack-gbrain-mcp-verify <url>
+#
+# Output (always valid JSON):
+#   {
+#     "status": "success" | "network" | "auth" | "malformed",
+#     "server_name": "gbrain" | null,
+#     "server_version": "0.26.8" | null,
+#     "error_class": "NETWORK" | "AUTH" | "MALFORMED" | null,
+#     "error_text": "<remediation hint + raw>" | null,
+#     "sources_add_url_supported": true | false,
+#     "raw_initialize_body": "<full body for debugging>" | null
+#   }
+#
+# Token is consumed from the GBRAIN_MCP_TOKEN env var, never argv. Prevents
+# shell-history / `ps` exposure of the bearer.
+#
+# Three error classes:
+#   NETWORK   — DNS / TCP / no HTTP response
+#   AUTH      — 401, 403, or 500 with stale-token-shaped body
+#   MALFORMED — 2xx but missing serverInfo, OR `Not Acceptable` (the dual
+#               Accept-header gotcha)
+#
+# `sources_add_url_supported` probes capability via tools/list — true iff the
+# remote exposes `mcp__gbrain__sources_add` (gbrain hasn't shipped this as
+# of v0.26.x; field is forward-compatible).
+#
+# Exit codes: 0 on success, 1 on classified failure, 2 on usage error.
+set -euo pipefail
+
+die_usage() {
+  echo "Usage: GBRAIN_MCP_TOKEN=<bearer> gstack-gbrain-mcp-verify <url>" >&2
+  exit 2
+}
+
+[ $# -eq 1 ] || die_usage
+URL="$1"
+[ -n "${GBRAIN_MCP_TOKEN:-}" ] || { echo "gstack-gbrain-mcp-verify: GBRAIN_MCP_TOKEN env var required" >&2; exit 2; }
+
+command -v curl >/dev/null 2>&1 || { echo "gstack-gbrain-mcp-verify: curl is required" >&2; exit 2; }
+command -v jq >/dev/null 2>&1 || { echo "gstack-gbrain-mcp-verify: jq is required (brew install jq)" >&2; exit 2; }
+
+emit() {
+  # emit <status> <server_name> <server_version> <error_class> <error_text> <url_supported> <raw_body>
+  jq -n \
+    --arg status "$1" \
+    --arg server_name "${2:-}" \
+    --arg server_version "${3:-}" \
+    --arg error_class "${4:-}" \
+    --arg error_text "${5:-}" \
+    --argjson url_supported "${6:-false}" \
+    --arg raw "${7:-}" \
+    '{
+      status: $status,
+      server_name: (if $server_name == "" then null else $server_name end),
+      server_version: (if $server_version == "" then null else $server_version end),
+      error_class: (if $error_class == "" then null else $error_class end),
+      error_text: (if $error_text == "" then null else $error_text end),
+      sources_add_url_supported: $url_supported,
+      raw_initialize_body: (if $raw == "" then null else $raw end)
+    }'
+}
+
+# JSON-RPC initialize body. Both `application/json` AND `text/event-stream`
+# in Accept — the MCP server returns 406 Not Acceptable without both. The
+# transcript that motivated this script hit that exact failure.
+INIT_BODY='{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"gstack-mcp-verify","version":"1"}}}'
+
+# Capture HTTP code + body in one pass; --max-time 10 caps total wall time.
+TMPBODY=$(mktemp -t gstack-mcp-verify.XXXXXX)
+trap 'rm -f "$TMPBODY"' EXIT
+
+set +e
+HTTP_CODE=$(curl -s -o "$TMPBODY" -w '%{http_code}' \
+  --max-time 10 \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -H 'Accept: application/json, text/event-stream' \
+  -H "Authorization: Bearer $GBRAIN_MCP_TOKEN" \
+  -d "$INIT_BODY" \
+  "$URL" 2>/dev/null)
+CURL_EXIT=$?
+set -e
+
+BODY=$(cat "$TMPBODY" 2>/dev/null || echo "")
+
+# --- NETWORK class: curl exited nonzero, no HTTP response ---
+if [ "$CURL_EXIT" -ne 0 ] || [ -z "$HTTP_CODE" ] || [ "$HTTP_CODE" = "000" ]; then
+  HOST=$(echo "$URL" | sed -E 's|^https?://([^/:]+).*|\1|')
+  emit "network" "" "" "NETWORK" "check Tailscale/DNS to ${HOST} (curl exit=${CURL_EXIT})" false "$BODY"
+  exit 1
+fi
+
+# --- AUTH class: 401, 403, or 500 with stale-token-shaped body ---
+case "$HTTP_CODE" in
+  401|403)
+    emit "auth" "" "" "AUTH" "rotate token on the brain host, re-run /setup-gbrain (HTTP $HTTP_CODE)" false "$BODY"
+    exit 1
+    ;;
+  500)
+    if echo "$BODY" | grep -qiE '"(error_description|message)":[[:space:]]*"[^"]*(auth|token|unauthorized)' 2>/dev/null; then
+      emit "auth" "" "" "AUTH" "rotate token on the brain host, re-run /setup-gbrain (HTTP 500 stale-token shape)" false "$BODY"
+      exit 1
+    fi
+    ;;
+esac
+
+# Anything not 2xx that isn't auth-shaped → MALFORMED with raw HTTP code.
+case "$HTTP_CODE" in
+  2*) ;;
+  *)
+    emit "malformed" "" "" "MALFORMED" "server returned HTTP $HTTP_CODE; verify URL + version compatibility" false "$BODY"
+    exit 1
+    ;;
+esac
+
+# --- 2xx path: body may be JSON or SSE-wrapped JSON. Strip SSE if present. ---
+# MCP servers return SSE format: `event: message\ndata: {...}\n\n`. Extract
+# just the JSON payload from the data: line, falling back to the body as-is.
+if echo "$BODY" | head -1 | grep -q '^event:'; then
+  JSON_BODY=$(echo "$BODY" | sed -n 's/^data: //p' | head -1)
+else
+  JSON_BODY="$BODY"
+fi
+
+# `Not Acceptable` is a JSON-RPC error from the MCP server itself, returned
+# with HTTP 200 if the SSE Accept header was missing. Detect it explicitly.
+if echo "$JSON_BODY" | jq -e '.error.message | test("[Nn]ot [Aa]cceptable")' >/dev/null 2>&1; then
+  emit "malformed" "" "" "MALFORMED" "Accept-header gotcha: pass both 'application/json' AND 'text/event-stream'" false "$BODY"
+  exit 1
+fi
+
+SERVER_NAME=$(echo "$JSON_BODY" | jq -r '.result.serverInfo.name // empty' 2>/dev/null)
+SERVER_VERSION=$(echo "$JSON_BODY" | jq -r '.result.serverInfo.version // empty' 2>/dev/null)
+
+if [ -z "$SERVER_NAME" ] || [ -z "$SERVER_VERSION" ]; then
+  emit "malformed" "" "" "MALFORMED" "server may be on a newer gbrain version; missing result.serverInfo. Verify with: curl -H 'Accept: application/json, text/event-stream'" false "$BODY"
+  exit 1
+fi
+
+# --- Capability probe: tools/list to detect sources_add ---
+# Best-effort. A failure here doesn't fail the verify; we just default
+# sources_add_url_supported=false. Future gbrain versions that ship
+# mcp__gbrain__sources_add will flip this true and gstack-artifacts-init
+# will print the one-liner form instead of the clone-then-path form.
+URL_SUPPORTED=false
+TOOLS_BODY_FILE=$(mktemp -t gstack-mcp-tools.XXXXXX)
+TOOLS_REQ='{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
+
+set +e
+curl -s -o "$TOOLS_BODY_FILE" \
+  --max-time 10 \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -H 'Accept: application/json, text/event-stream' \
+  -H "Authorization: Bearer $GBRAIN_MCP_TOKEN" \
+  -d "$TOOLS_REQ" \
+  "$URL" >/dev/null 2>&1
+TOOLS_EXIT=$?
+set -e
+
+if [ "$TOOLS_EXIT" -eq 0 ]; then
+  TOOLS_BODY=$(cat "$TOOLS_BODY_FILE" 2>/dev/null || echo "")
+  if echo "$TOOLS_BODY" | head -1 | grep -q '^event:'; then
+    TOOLS_JSON=$(echo "$TOOLS_BODY" | sed -n 's/^data: //p' | head -1)
+  else
+    TOOLS_JSON="$TOOLS_BODY"
+  fi
+  if echo "$TOOLS_JSON" | jq -e '.result.tools[] | select(.name | test("sources_add"))' >/dev/null 2>&1; then
+    URL_SUPPORTED=true
+  fi
+fi
+rm -f "$TOOLS_BODY_FILE"
+
+emit "success" "$SERVER_NAME" "$SERVER_VERSION" "" "" "$URL_SUPPORTED" "$BODY"
+exit 0

bin/gstack-gbrain-repo-policy

@@ -0,0 +1,227 @@
+#!/usr/bin/env bash
+# gstack-gbrain-repo-policy — per-remote trust tier for gbrain repo ingest.
+#
+# Usage:
+#   gstack-gbrain-repo-policy get [<remote-url>]
+#     Print the tier for the given remote, or the current repo's origin
+#     if no URL is passed. Exits 0 with one of: read-write, read-only,
+#     deny, unset.
+#
+#   gstack-gbrain-repo-policy set <remote-url> <read-write|read-only|deny>
+#     Persist a tier for the given remote. Exits 0 on success.
+#
+#   gstack-gbrain-repo-policy list
+#     Print every entry as "<key>\t<tier>", sorted by key.
+#
+#   gstack-gbrain-repo-policy normalize <url>
+#     Print the normalized (canonical) key for a given remote URL.
+#     Use this when other skills or tests need the same collapsing logic.
+#
+#   gstack-gbrain-repo-policy --help
+#
+# Storage:
+#   ~/.gstack/gbrain-repo-policy.json, mode 0600.
+#
+# File format:
+#   {
+#     "_schema_version": 2,
+#     "github.com/foo/bar": "read-write",
+#     "github.com/baz/qux": "deny"
+#   }
+#
+# Tier semantics:
+#   read-write — agent may search AND write new pages from this repo.
+#   read-only  — agent may search but NEVER write pages from this repo.
+#                (Enforced at the caller level; this binary just stores the
+#                decision.)
+#   deny       — no gbrain interaction at all.
+#
+# Legacy migration:
+#   On any read of a file missing `_schema_version` (or with version < 2),
+#   legacy `allow` values are atomically rewritten to `read-write`, and
+#   `_schema_version: 2` is added. Log line emitted on stderr when the
+#   migration actually changes anything. Idempotent: running twice is safe.
+#
+# Env:
+#   GSTACK_HOME — override ~/.gstack state directory (aligns with other
+#                 gstack-* bins; used heavily in tests).
+set -euo pipefail
+
+STATE_DIR="${GSTACK_HOME:-$HOME/.gstack}"
+POLICY_FILE="$STATE_DIR/gbrain-repo-policy.json"
+SCHEMA_VERSION=2
+
+die() { echo "gstack-gbrain-repo-policy: $*" >&2; exit 2; }
+
+require_jq() {
+  if ! command -v jq >/dev/null 2>&1; then
+    die "jq is required. Install with: brew install jq"
+  fi
+}
+
+# normalize <url> — canonical form: lowercase host + path, no protocol,
+# no userinfo, no trailing .git or /. SSH shorthand (git@host:path) collapses
+# to the same key as https://host/path.
+normalize() {
+  local url="$1"
+  [ -z "$url" ] && { echo ""; return 0; }
+  # Strip protocol://
+  url="${url#*://}"
+  # Strip userinfo (git@, user:password@, etc.) — everything up to and
+  # including the first @ iff an @ appears before the first / or :.
+  case "$url" in
+    *@*)
+      local before_at="${url%%@*}"
+      case "$before_at" in
+        */*|*:*) : ;;  # @ is in the path, not userinfo — leave it
+        *) url="${url#*@}" ;;
+      esac
+      ;;
+  esac
+  # SSH shorthand: github.com:foo/bar → github.com/foo/bar. Only when the
+  # hostname-part (before first /) contains a colon. sed is clearer than
+  # bash's `${var/:/\/}` which has tricky escaping.
+  local head="${url%%/*}"
+  case "$head" in
+    *:*) url=$(printf '%s' "$url" | sed 's|:|/|') ;;
+  esac
+  # Strip trailing .git
+  url="${url%.git}"
+  # Strip trailing /
+  url="${url%/}"
+  # Lowercase the whole thing. GitHub and most hosts are case-insensitive on
+  # paths anyway; collapsing avoids duplicate entries for "Foo/Bar" vs
+  # "foo/bar".
+  printf '%s\n' "$url" | tr '[:upper:]' '[:lower:]'
+}
+
+# ensure_file — create the policy file if missing, migrate if legacy.
+# Emits the migration log line on stderr exactly once per run when a
+# migration actually rewrites values.
+ensure_file() {
+  require_jq
+  mkdir -p "$STATE_DIR"
+
+  if [ ! -f "$POLICY_FILE" ]; then
+    # Fresh file — just the schema version, no entries.
+    local tmp
+    tmp=$(mktemp "$POLICY_FILE.tmp.XXXXXX")
+    printf '{"_schema_version":%d}\n' "$SCHEMA_VERSION" > "$tmp"
+    mv "$tmp" "$POLICY_FILE"
+    chmod 0600 "$POLICY_FILE"
+    return 0
+  fi
+
+  # File exists — validate, migrate if needed.
+  local raw
+  if ! raw=$(cat "$POLICY_FILE" 2>/dev/null); then
+    die "Cannot read $POLICY_FILE"
+  fi
+
+  # Corrupt JSON → quarantine and start fresh.
+  if ! echo "$raw" | jq empty 2>/dev/null; then
+    local ts
+    ts=$(date +%Y%m%d-%H%M%S)
+    local quarantine="$POLICY_FILE.corrupt-$ts"
+    mv "$POLICY_FILE" "$quarantine"
+    echo "gstack-gbrain-repo-policy: corrupt policy file quarantined to $quarantine; starting fresh" >&2
+    local tmp
+    tmp=$(mktemp "$POLICY_FILE.tmp.XXXXXX")
+    printf '{"_schema_version":%d}\n' "$SCHEMA_VERSION" > "$tmp"
+    mv "$tmp" "$POLICY_FILE"
+    chmod 0600 "$POLICY_FILE"
+    return 0
+  fi
+
+  # Check schema version.
+  local version
+  version=$(echo "$raw" | jq -r '._schema_version // 0')
+  if [ "$version" -ge "$SCHEMA_VERSION" ]; then
+    return 0
+  fi
+
+  # Migrate: rename `allow` → `read-write`, add _schema_version.
+  local allow_count migrated
+  allow_count=$(echo "$raw" | jq '[to_entries[] | select(.key != "_schema_version" and .value == "allow")] | length')
+  migrated=$(echo "$raw" | jq --argjson v "$SCHEMA_VERSION" '
+    (to_entries | map(
+      if .key == "_schema_version" then empty
+      elif .value == "allow" then .value = "read-write"
+      else .
+      end
+    ) | from_entries) + {_schema_version: $v}
+  ')
+  local tmp
+  tmp=$(mktemp "$POLICY_FILE.tmp.XXXXXX")
+  printf '%s\n' "$migrated" > "$tmp"
+  mv "$tmp" "$POLICY_FILE"
+  chmod 0600 "$POLICY_FILE"
+  if [ "$allow_count" -gt 0 ]; then
+    echo "[gstack-gbrain-repo-policy] Migrated $allow_count legacy allow entries to read-write" >&2
+  fi
+}
+
+cmd_get() {
+  local url="${1:-}"
+  if [ -z "$url" ]; then
+    url=$(git remote get-url origin 2>/dev/null || true)
+    if [ -z "$url" ]; then
+      echo "unset"
+      return 0
+    fi
+  fi
+  local key
+  key=$(normalize "$url")
+  if [ -z "$key" ]; then
+    echo "unset"
+    return 0
+  fi
+  ensure_file
+  jq -r --arg key "$key" '.[$key] // "unset"' "$POLICY_FILE"
+}
+
+cmd_set() {
+  local url="${1:-}"
+  local tier="${2:-}"
+  [ -z "$url" ] && die "usage: set <remote-url> <tier>"
+  [ -z "$tier" ] && die "usage: set <remote-url> <tier>"
+  case "$tier" in
+    read-write|read-only|deny) ;;
+    *) die "invalid tier '$tier' (must be one of: read-write, read-only, deny)" ;;
+  esac
+  local key
+  key=$(normalize "$url")
+  [ -z "$key" ] && die "cannot normalize remote URL: $url"
+  ensure_file
+  local tmp
+  tmp=$(mktemp "$POLICY_FILE.tmp.XXXXXX")
+  jq --arg key "$key" --arg tier "$tier" '.[$key] = $tier' "$POLICY_FILE" > "$tmp"
+  mv "$tmp" "$POLICY_FILE"
+  chmod 0600 "$POLICY_FILE"
+  echo "Set $key → $tier"
+}
+
+cmd_list() {
+  if [ ! -f "$POLICY_FILE" ]; then
+    # Nothing to list; don't create the file just for a read.
+    return 0
+  fi
+  ensure_file
+  jq -r 'to_entries[] | select(.key != "_schema_version") | "\(.key)\t\(.value)"' "$POLICY_FILE" | sort
+}
+
+cmd_normalize() {
+  local url="${1:-}"
+  [ -z "$url" ] && die "usage: normalize <url>"
+  normalize "$url"
+}
+
+case "${1:-}" in
+  get) shift; cmd_get "$@" ;;
+  set) shift; cmd_set "$@" ;;
+  list) shift; cmd_list "$@" ;;
+  normalize) shift; cmd_normalize "$@" ;;
+  --help|-h|help) sed -n '2,47p' "$0" | sed 's/^# \{0,1\}//' ;;
+  "") die "usage: gstack-gbrain-repo-policy {get|set|list|normalize|--help}" ;;
+  *) die "unknown subcommand: $1" ;;
+esac

bin/gstack-gbrain-source-wireup

@@ -0,0 +1,362 @@
+#!/usr/bin/env bash
+# gstack-gbrain-source-wireup — register the gstack brain repo as a gbrain
+# federated source via `git worktree`, run an initial sync, hook into
+# subsequent skill-end syncs.
+#
+# Replaces the v1.12.2.0 dead `consumers.json + ingest_url + /ingest-repo`
+# wireup which depended on a gbrain HTTP endpoint that never shipped.
+#
+# Usage:
+#   gstack-gbrain-source-wireup [--strict] [--source-id <id>] [--no-pull]
+#                               [--database-url <url>]
+#   gstack-gbrain-source-wireup --uninstall [--source-id <id>]
+#                               [--database-url <url>]
+#   gstack-gbrain-source-wireup --probe
+#   gstack-gbrain-source-wireup --help
+#
+# Exit codes:
+#   0 — success, OR benign skip without --strict
+#   1 — hard failure (gbrain or git op errored on a real call)
+#   2 — missing prereqs (no gbrain >= 0.18.0, no .git or remote-file)
+#   3 — source-id derivation failed in --uninstall, no fallback worked
+#
+# Env:
+#   GSTACK_HOME — override ~/.gstack (test harness)
+#   GSTACK_BRAIN_WORKTREE — override worktree path (default ~/.gstack-brain-worktree)
+#   GSTACK_BRAIN_SOURCE_ID — id override; --source-id flag takes precedence
+#   GSTACK_BRAIN_NO_SYNC — skip the gbrain sync step (tests; helper still
+#                          ensures source registration)
+#
+# Defense against external rewrites of ~/.gbrain/config.json:
+# At helper startup we capture the database URL ONCE — from --database-url,
+# from GBRAIN_DATABASE_URL/DATABASE_URL env, or from ~/.gbrain/config.json —
+# and export it as GBRAIN_DATABASE_URL for every child `gbrain` invocation.
+# That env var overrides whatever's in config.json (per gbrain's loadConfig
+# at src/core/config.ts:53), so a process that flips config.json mid-sync
+# can't redirect us at a different brain mid-stream.
+#
+# Depends on: jq (transitive via gstack-gbrain-detect).
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+CONFIG_BIN="$SCRIPT_DIR/gstack-config"
+
+GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
+WORKTREE="${GSTACK_BRAIN_WORKTREE:-$HOME/.gstack-brain-worktree}"
+# v1.27.0.0+ canonical name; brain-remote is the legacy fallback during migration.
+if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
+  REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
+else
+  REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
+fi
+PLIST_PATH="$HOME/Library/LaunchAgents/com.gstack.brain-sync.plist"
+GBRAIN_CONFIG="$HOME/.gbrain/config.json"
+
+# ---- arg parse ----
+MODE="wireup"
+STRICT=0
+NO_PULL=0
+SOURCE_ID=""
+DATABASE_URL_ARG=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --uninstall)     MODE="uninstall"; shift ;;
+    --probe)         MODE="probe"; shift ;;
+    --strict)        STRICT=1; shift ;;
+    --no-pull)       NO_PULL=1; shift ;;
+    --source-id)     SOURCE_ID="$2"; shift 2 ;;
+    --database-url)  DATABASE_URL_ARG="$2"; shift 2 ;;
+    --help|-h)       sed -n '2,40p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    *)               echo "Unknown flag: $1" >&2; exit 1 ;;
+  esac
+done
+
+# ---- lock the database URL at startup ----
+# Precedence: --database-url flag > existing GBRAIN_DATABASE_URL/DATABASE_URL
+# env > read once from ~/.gbrain/config.json. Whichever wins gets exported as
+# GBRAIN_DATABASE_URL so every child `gbrain` invocation uses THAT brain even
+# if config.json is rewritten by another process during the wireup.
+_locked_url=""
+if [ -n "$DATABASE_URL_ARG" ]; then
+  _locked_url="$DATABASE_URL_ARG"
+elif [ -n "${GBRAIN_DATABASE_URL:-}" ]; then
+  _locked_url="$GBRAIN_DATABASE_URL"
+elif [ -n "${DATABASE_URL:-}" ]; then
+  _locked_url="$DATABASE_URL"
+elif [ -f "$GBRAIN_CONFIG" ]; then
+  # Python heredoc reads config.json. On JSON parse failure or any IO error,
+  # we WARN (not silently swallow) so the user knows the URL lock fell back
+  # to gbrain's own loadConfig (which would still read this same file).
+  _py_err=$(mktemp -t wireup-pyerr 2>/dev/null || mktemp /tmp/wireup-pyerr.XXXXXX)
+  _locked_url=$(GBRAIN_CONFIG_PATH="$GBRAIN_CONFIG" python3 -c '
+import json, os, sys
+try:
+    c = json.load(open(os.environ["GBRAIN_CONFIG_PATH"]))
+    print(c.get("database_url",""))
+except FileNotFoundError:
+    sys.exit(0)
+except Exception as e:
+    print(f"config.json parse error: {e}", file=sys.stderr)
+    sys.exit(1)
+' </dev/null 2>"$_py_err") || warn "could not read $GBRAIN_CONFIG ($(cat "$_py_err" 2>/dev/null)); URL not locked"
+  rm -f "$_py_err" 2>/dev/null
+fi
+if [ -n "$_locked_url" ]; then
+  export GBRAIN_DATABASE_URL="$_locked_url"
+fi
+
+prefix() { sed 's/^/gstack-gbrain-source-wireup: /' >&2; }
+warn()   { echo "$*" | prefix; }
+# die <message> [exit_code]: warn with just the message, exit with code (default 1).
+die()    { warn "$1"; exit "${2:-1}"; }
+
+# Refuse to rm anything outside $HOME/. Defends against GSTACK_BRAIN_WORKTREE=/
+# or empty-string overrides that would otherwise have line 169 / 161 nuke the
+# user's home or root.
+safe_rm_worktree() {
+  local target="$1"
+  case "$target" in
+    "" | "/" | "/Users" | "/Users/" | "$HOME" | "$HOME/" )
+      die "refusing to rm dangerous path: $target" 1 ;;
+  esac
+  case "$target" in
+    "$HOME"/*) rm -rf "$target" ;;
+    *) die "refusing to rm path outside \$HOME: $target" 1 ;;
+  esac
+}
+
+# ---- source-id derivation (D6 multi-fallback) ----
+derive_source_id() {
+  if [ -n "$SOURCE_ID" ]; then
+    echo "$SOURCE_ID"; return 0
+  fi
+  if [ -n "${GSTACK_BRAIN_SOURCE_ID:-}" ]; then
+    echo "$GSTACK_BRAIN_SOURCE_ID"; return 0
+  fi
+  local remote_url=""
+  remote_url=$(git -C "$GSTACK_HOME" remote get-url origin 2>/dev/null) || true
+  if [ -z "$remote_url" ] && [ -f "$REMOTE_FILE" ]; then
+    remote_url=$(head -1 "$REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
+  fi
+  [ -z "$remote_url" ] && return 3
+  basename "$remote_url" .git \
+    | tr '[:upper:]' '[:lower:]' \
+    | tr -c 'a-z0-9-' '-' \
+    | sed 's/--*/-/g; s/^-//; s/-$//' \
+    | cut -c1-32
+}
+
+# ---- gbrain version gate ----
+gbrain_version_ok() {
+  if ! command -v gbrain >/dev/null 2>&1; then
+    return 1
+  fi
+  local v
+  v=$(gbrain --version 2>/dev/null | awk '{print $2}')
+  [ -z "$v" ] && return 1
+  # 0.18.0 minimum (gbrain sources shipped here). Put the floor first in stdin
+  # so equal or greater $v sorts to position 2 — head -1 == "0.18.0" iff $v >= floor.
+  [ "$(printf '0.18.0\n%s\n' "$v" | sort -V | head -1)" = "0.18.0" ]
+}
+
+# ---- worktree management ----
+# A worktree is always created `--detach`ed at $GSTACK_HOME's HEAD. Detached
+# because a branch (main) can only be checked out in ONE worktree, and the
+# parent at $GSTACK_HOME already has it. To advance, we re-checkout the
+# parent's current HEAD into the detached worktree.
+_worktree_add_detached() {
+  local sha
+  sha=$(git -C "$GSTACK_HOME" rev-parse HEAD 2>/dev/null) || return 1
+  git -C "$GSTACK_HOME" worktree prune 2>/dev/null || true
+  # Surface git errors via prefix so users see WHY the add failed (disk, perms, etc).
+  git -C "$GSTACK_HOME" worktree add --detach "$WORKTREE" "$sha" 2>&1 | prefix
+  return "${PIPESTATUS[0]}"
+}
+
+ensure_worktree() {
+  if [ ! -d "$GSTACK_HOME/.git" ]; then
+    return 2
+  fi
+  if [ -d "$WORKTREE/.git" ] || [ -f "$WORKTREE/.git" ]; then
+    # already exists; advance the detached HEAD to parent's current HEAD
+    if [ "$NO_PULL" = "0" ]; then
+      local sha
+      sha=$(git -C "$GSTACK_HOME" rev-parse HEAD 2>/dev/null) || return 1
+      # Surface checkout errors via prefix so users see WHY the advance failed
+      # (uncommitted changes in the detached worktree, ref ambiguity, etc).
+      ( cd "$WORKTREE" && git checkout --detach "$sha" 2>&1 | prefix; exit "${PIPESTATUS[0]}" ) || {
+        warn "worktree at $WORKTREE could not advance to $sha; resetting via remove + re-add"
+        git -C "$GSTACK_HOME" worktree remove --force "$WORKTREE" 2>/dev/null || safe_rm_worktree "$WORKTREE"
+        _worktree_add_detached || return 1
+      }
+    fi
+    return 0
+  fi
+  # Stray non-git dir? Remove first.
+  [ -e "$WORKTREE" ] && safe_rm_worktree "$WORKTREE"
+  _worktree_add_detached || return 1
+}
+
+# ---- gbrain sources operations ----
+# Returns 0 if source with id exists at expected path. 1 if exists but path differs. 2 if absent.
+# Hard-fails (exits non-zero via die) if jq is missing — without jq we cannot
+# distinguish "absent" from "missing-tool" and would falsely re-add an existing
+# source. jq is documented as a dependency of gstack-gbrain-detect (transitive)
+# but adversarial review flagged the silent-fall-through path; this probe makes
+# the failure mode loud.
+check_source_state() {
+  local id="$1"
+  if ! command -v jq >/dev/null 2>&1; then
+    die "jq required for source state detection. Install jq (brew install jq) and re-run." 1
+  fi
+  local existing_path
+  existing_path=$(gbrain sources list --json 2>/dev/null \
+    | jq -r --arg id "$id" '.sources[] | select(.id==$id) | .local_path' 2>/dev/null \
+    | tr -d '[:space:]') || existing_path=""
+  if [ -z "$existing_path" ]; then
+    return 2
+  fi
+  if [ "$existing_path" = "$WORKTREE" ]; then
+    return 0
+  fi
+  return 1
+}
+
+# ---- modes ----
+do_probe() {
+  local id worktree_status="absent" gbrain_status="missing" source_status="absent"
+  id=$(derive_source_id 2>/dev/null) || id="(unknown)"
+  # Use explicit if-block so [ -d ] || [ -f ] doesn't get short-circuited by &&
+  # precedence (the `||` and `&&` chain has trap behavior in bash test syntax).
+  if [ -d "$WORKTREE/.git" ] || [ -f "$WORKTREE/.git" ]; then
+    worktree_status="present"
+  fi
+  if gbrain_version_ok; then
+    gbrain_status="ok ($(gbrain --version 2>/dev/null | awk '{print $2}'))"
+    # Capture check_source_state's return code explicitly. Relying on $? after
+    # an `if`-elif chain is fragile under set -e and undefined under some shells.
+    set +e
+    check_source_state "$id"
+    local css_rc=$?
+    set -e
+    case "$css_rc" in
+      0) source_status="registered ($WORKTREE)" ;;
+      1) source_status="registered (different path)" ;;
+    esac
+  fi
+  echo "source_id=$id"
+  echo "worktree=$WORKTREE"
+  echo "worktree_status=$worktree_status"
+  echo "gbrain=$gbrain_status"
+  echo "source_status=$source_status"
+}
+
+do_wireup() {
+  local id
+  id=$(derive_source_id) || die "cannot derive source id (no .git, no remote-file, no --source-id)" 2
+
+  if ! gbrain_version_ok; then
+    if [ "$STRICT" = "1" ]; then
+      die "gbrain not installed or < 0.18.0; install/upgrade gbrain and re-run" 2
+    fi
+    warn "gbrain not installed or < 0.18.0; skipping wireup (benign skip)"
+    exit 0
+  fi
+
+  # Capture ensure_worktree's return code explicitly. `$?` after `||` reflects
+  # the LAST command in the function under set -e, which is unreliable when the
+  # function has multiple internal exit paths.
+  set +e
+  ensure_worktree
+  ew_rc=$?
+  set -e
+  case "$ew_rc" in
+    0) : ;;  # success
+    2)
+      [ "$STRICT" = "1" ] && die "no $GSTACK_HOME/.git; run /setup-gbrain Step 7 (gstack-brain-init) first" 2
+      warn "no $GSTACK_HOME/.git; skipping (benign skip)"
+      exit 0
+      ;;
+    *) die "git worktree creation failed at $WORKTREE" 1 ;;
+  esac
+
+  # Source registration: probe state, then act.
+  set +e
+  check_source_state "$id"
+  local sstate=$?
+  set -e
+  case "$sstate" in
+    0) : ;;  # already correctly registered
+    1)
+      # Multi-Mac case: if the existing path also looks like another machine's
+      # brain-worktree (same basename, different parent), don't ping-pong the
+      # registration. Just sync from our local worktree — gbrain stores pages
+      # by content, not by local_path. The metadata is informational only.
+      local existing_path
+      existing_path=$(gbrain sources list --json 2>/dev/null \
+        | jq -r --arg id "$id" '.sources[] | select(.id==$id) | .local_path' 2>/dev/null \
+        | tr -d '[:space:]') || existing_path=""
+      if [ "$(basename "$existing_path")" = "$(basename "$WORKTREE")" ] \
+         && [ "$existing_path" != "$WORKTREE" ]; then
+        warn "source $id is registered at $existing_path (likely another machine's local copy of the same brain repo). Skipping re-registration; will sync from local worktree."
+      else
+        warn "source $id registered with different path; recreating (gbrain has no 'sources update')"
+        gbrain sources remove "$id" --yes 2>&1 | prefix || die "gbrain sources remove failed" 1
+        gbrain sources add "$id" --path "$WORKTREE" --federated 2>&1 | prefix \
+          || die "gbrain sources add failed" 1
+      fi
+      ;;
+    2)
+      gbrain sources add "$id" --path "$WORKTREE" --federated 2>&1 | prefix \
+        || die "gbrain sources add failed" 1
+      ;;
+  esac
+
+  if [ "${GSTACK_BRAIN_NO_SYNC:-0}" = "1" ]; then
+    echo "source_id=$id"
+    echo "worktree=$WORKTREE"
+    echo "pages_synced=skipped"
+    exit 0
+  fi
+
+  local sync_out sync_redacted
+  sync_out=$(gbrain sync --repo "$WORKTREE" 2>&1) || {
+    # Redact any postgres:// URLs from the error message in case gbrain logged
+    # a connection error containing the full DSN with password. The user sees
+    # "***REDACTED***" instead of credentials in their stderr or any log.
+    sync_redacted=$(echo "$sync_out" | tail -10 | sed -E 's#postgres(ql)?://[^[:space:]]+#postgres://***REDACTED***#g')
+    die "gbrain sync failed (last 10 lines, secrets redacted): $sync_redacted" 1
+  }
+  echo "$sync_out" | tail -3 | prefix
+
+  echo "source_id=$id"
+  echo "worktree=$WORKTREE"
+  echo "pages_synced=$(echo "$sync_out" | grep -oE '[0-9]+ pages? imported' | head -1 || echo 'incremental')"
+}
+
+do_uninstall() {
+  local id
+  id=$(derive_source_id) || die "cannot derive source id; pass --source-id <id> explicitly" 3
+
+  if command -v gbrain >/dev/null 2>&1; then
+    gbrain sources remove "$id" --yes 2>&1 | prefix || warn "gbrain sources remove failed (continuing)"
+  fi
+
+  if [ -d "$WORKTREE/.git" ] || [ -f "$WORKTREE/.git" ]; then
+    git -C "$GSTACK_HOME" worktree remove --force "$WORKTREE" 2>/dev/null \
+      || safe_rm_worktree "$WORKTREE"
+  fi
+
+  # Cron-stub: future launchd plist (not created today; safety net for D9 future).
+  rm -f "$PLIST_PATH" 2>/dev/null || true
+
+  echo "uninstalled source=$id worktree=$WORKTREE"
+}
+
+case "$MODE" in
+  probe)     do_probe ;;
+  wireup)    do_wireup ;;
+  uninstall) do_uninstall ;;
+esac

bin/gstack-gbrain-supabase-provision

@@ -0,0 +1,447 @@
+#!/usr/bin/env bash
+# gstack-gbrain-supabase-provision — Supabase Management API wrapper for
+# /setup-gbrain path 2a (auto-provision).
+#
+# Subcommands:
+#   list-orgs
+#     GET /v1/organizations. Output: {"orgs": [{"slug","name"}, ...]}
+#
+#   create <name> <region> <org-slug>
+#     POST /v1/projects with {name, db_pass, organization_slug, region}.
+#     db_pass must be in the DB_PASS env var (never argv — D8 grep test
+#     enforces this). Output: {"ref","name","region","organization_slug","status"}.
+#
+#     NOTE: does NOT send a `plan` field. Per verified Supabase Management
+#     API OpenAPI, the `plan` field is now deprecated at the project level
+#     — subscription tier is an org-level decision (D17 updated).
+#
+#   wait <ref> [--timeout <seconds>]
+#     Poll GET /v1/projects/{ref} every 5s until status=ACTIVE_HEALTHY,
+#     or fail on terminal states (INIT_FAILED, REMOVED). Default timeout
+#     180s. Output on success: {"ref","status","elapsed_s"}.
+#
+#   pooler-url <ref>
+#     GET /v1/projects/{ref}/config/database/pooler, construct the full
+#     Session Pooler URL using DB_PASS from env (the API response's
+#     connection_string is typically templated [PASSWORD] rather than the
+#     real value — we build from db_user/db_host/db_port/db_name instead).
+#     Output: {"ref","pooler_url"}.
+#
+#   list-orphans [--name-prefix <str>]
+#     GET /v1/projects. Filter to projects whose name starts with --name-prefix
+#     (default "gbrain") AND whose ref does NOT match the one in the local
+#     active ~/.gbrain/config.json pooler URL. Those are the gbrain-shaped
+#     projects that aren't pointed at by a working local config — candidates
+#     for /setup-gbrain --cleanup-orphans.
+#     Output: {"active_ref","orphans":[{"ref","name","created_at","region"}, ...]}.
+#
+#   delete-project <ref>
+#     DELETE /v1/projects/{ref}. Destructive, one-way — callers must
+#     double-confirm before invoking. This bin performs NO confirmation
+#     prompt; the skill's UI layer owns that responsibility.
+#     Output: {"deleted_ref"}.
+#
+# Secrets discipline (D8, D10, D11):
+#   - SUPABASE_ACCESS_TOKEN is read from env; never accepted as argv.
+#   - DB_PASS (for `create` and `pooler-url`) is read from env; never argv.
+#   - Forbidden strings (enforced by skill-validation grep test):
+#       --insecure, -k (curl), NODE_TLS_REJECT_UNAUTHORIZED
+#   - `set +x` default — debug mode requires explicit opt-in around
+#     non-secret lines.
+#
+# Env:
+#   SUPABASE_ACCESS_TOKEN — PAT for auth (required on all subcommands)
+#   DB_PASS               — database password (required for create + pooler-url)
+#   SUPABASE_API_BASE     — override the API host (tests point this at a
+#                           local mock server). Default: https://api.supabase.com
+#
+# Exit codes:
+#   0 — success
+#   2 — usage / invalid input
+#   3 — auth failure (401/403) — retry with fresh PAT
+#   4 — quota / billing (402) — user action needed
+#   5 — conflict (409) — duplicate name, user action needed
+#   6 — timeout (wait subcommand hit its deadline)
+#   7 — terminal failure state from Supabase (INIT_FAILED, REMOVED)
+#   8 — network / 5xx after retries
+set +x  # Defensive: never trace secrets in this helper.
+set -euo pipefail
+
+SUPABASE_API_BASE="${SUPABASE_API_BASE:-https://api.supabase.com}"
+API_VERSION="v1"
+DEFAULT_WAIT_TIMEOUT=180
+POLL_INTERVAL=5
+CURL_TIMEOUT=30
+
+die()     { echo "gstack-gbrain-supabase-provision: $*" >&2; exit 2; }
+die_auth() { echo "gstack-gbrain-supabase-provision: $*" >&2; exit 3; }
+die_quota(){ echo "gstack-gbrain-supabase-provision: $*" >&2; exit 4; }
+die_conflict(){ echo "gstack-gbrain-supabase-provision: $*" >&2; exit 5; }
+die_net() { echo "gstack-gbrain-supabase-provision: $*" >&2; exit 8; }
+
+require_jq() {
+  command -v jq >/dev/null 2>&1 || die "jq is required. Install with: brew install jq"
+}
+require_curl() {
+  command -v curl >/dev/null 2>&1 || die "curl is required"
+}
+
+require_pat() {
+  if [ -z "${SUPABASE_ACCESS_TOKEN:-}" ]; then
+    die_auth "SUPABASE_ACCESS_TOKEN is not set. Generate a PAT at https://supabase.com/dashboard/account/tokens"
+  fi
+}
+
+require_db_pass() {
+  if [ -z "${DB_PASS:-}" ]; then
+    die "DB_PASS env var is required (never passed as argv — that leaks via ps/history)"
+  fi
+}
+
+# api_call <method> <path> [<json-body-file>]
+# Handles: 401/403 → exit 3, 402 → 4, 409 → 5, 429 + 5xx → retry w/
+# exponential backoff up to 3 attempts. Returns the response body on
+# stdout and HTTP status on an internal variable via a pipe trick.
+#
+# Because bash lacks multi-value returns, we write response body to a
+# tmpfile + status to another tmpfile and the caller reads them.
+api_call() {
+  local method="$1"
+  local apipath="$2"
+  local body_file="${3:-}"
+
+  local url="$SUPABASE_API_BASE/$API_VERSION/$apipath"
+  local body_tmp
+  body_tmp=$(mktemp)
+  local status_tmp
+  status_tmp=$(mktemp)
+  # shellcheck disable=SC2064
+  trap "rm -f '$body_tmp' '$status_tmp'" RETURN
+
+  local attempt=0
+  local max_attempts=3
+  local backoff=2
+  while : ; do
+    attempt=$((attempt + 1))
+    local curl_args=(
+      --silent
+      --show-error
+      --max-time "$CURL_TIMEOUT"
+      -o "$body_tmp"
+      -w "%{http_code}"
+      -X "$method"
+      -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN"
+      -H "Accept: application/json"
+      -H "Content-Type: application/json"
+      -H "User-Agent: gstack-gbrain-supabase-provision"
+    )
+    if [ -n "$body_file" ]; then
+      curl_args+=(--data-binary "@$body_file")
+    fi
+    local status
+    if ! status=$(curl "${curl_args[@]}" "$url" 2>/dev/null); then
+      # curl itself failed (network, timeout, etc.). Retry.
+      if [ "$attempt" -ge "$max_attempts" ]; then
+        die_net "network failure calling $method $apipath after $attempt attempts"
+      fi
+      sleep "$backoff"
+      backoff=$((backoff * 2))
+      continue
+    fi
+
+    case "$status" in
+      2??)
+        cat "$body_tmp"
+        printf '%s' "$status" > "$status_tmp"
+        return 0
+        ;;
+      401)
+        die_auth "401 Unauthorized — your PAT is invalid or expired. Re-generate at https://supabase.com/dashboard/account/tokens"
+        ;;
+      403)
+        die_auth "403 Forbidden — your PAT lacks permission for $method $apipath. Regenerate with All Access scope."
+        ;;
+      402)
+        die_quota "402 Payment Required — Supabase project/organization quota exceeded. See https://supabase.com/dashboard"
+        ;;
+      409)
+        die_conflict "409 Conflict on $method $apipath — likely a duplicate project name. Pick a different name and re-run."
+        ;;
+      429|5??)
+        if [ "$attempt" -ge "$max_attempts" ]; then
+          die_net "$status after $attempt attempts on $method $apipath"
+        fi
+        sleep "$backoff"
+        backoff=$((backoff * 2))
+        continue
+        ;;
+      *)
+        # 400, 404, etc. — surface the error body for debugging.
+        local err
+        err=$(jq -r '.message // .error // empty' "$body_tmp" 2>/dev/null || true)
+        if [ -n "$err" ]; then
+          die "HTTP $status from $method $apipath: $err"
+        else
+          die "HTTP $status from $method $apipath (no error message in response)"
+        fi
+        ;;
+    esac
+  done
+}
+
+cmd_list_orgs() {
+  local json_mode=false
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --json) json_mode=true; shift ;;
+      *) die "list-orgs: unknown flag: $1" ;;
+    esac
+  done
+
+  require_jq; require_curl; require_pat
+  local resp
+  resp=$(api_call GET organizations)
+  if $json_mode; then
+    printf '%s' "$resp" | jq '{orgs: map({slug: .slug, name: .name})}'
+  else
+    printf '%s' "$resp" | jq -r '.[] | "\(.slug)\t\(.name)"'
+  fi
+}
+
+cmd_create() {
+  local name="" region="" org_slug=""
+  local json_mode=false
+  local instance_size=""
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --json) json_mode=true; shift ;;
+      --instance-size) instance_size="$2"; shift 2 ;;
+      --*) die "create: unknown flag: $1" ;;
+      *)
+        if   [ -z "$name" ]; then name="$1"
+        elif [ -z "$region" ]; then region="$1"
+        elif [ -z "$org_slug" ]; then org_slug="$1"
+        else die "create: too many positional arguments"
+        fi
+        shift
+        ;;
+    esac
+  done
+  [ -z "$name" ] && die "create: missing <name>"
+  [ -z "$region" ] && die "create: missing <region>"
+  [ -z "$org_slug" ] && die "create: missing <org-slug>"
+
+  require_jq; require_curl; require_pat; require_db_pass
+
+  local body_file
+  body_file=$(mktemp)
+  # shellcheck disable=SC2064
+  trap "rm -f '$body_file'" RETURN
+  if [ -n "$instance_size" ]; then
+    jq -n \
+      --arg name "$name" \
+      --arg db_pass "$DB_PASS" \
+      --arg organization_slug "$org_slug" \
+      --arg region "$region" \
+      --arg desired_instance_size "$instance_size" \
+      '{name: $name, db_pass: $db_pass, organization_slug: $organization_slug, region: $region, desired_instance_size: $desired_instance_size}' \
+      > "$body_file"
+  else
+    jq -n \
+      --arg name "$name" \
+      --arg db_pass "$DB_PASS" \
+      --arg organization_slug "$org_slug" \
+      --arg region "$region" \
+      '{name: $name, db_pass: $db_pass, organization_slug: $organization_slug, region: $region}' \
+      > "$body_file"
+  fi
+
+  local resp
+  resp=$(api_call POST projects "$body_file")
+  if $json_mode; then
+    printf '%s' "$resp" | jq '{ref, name, region, organization_slug, status}'
+  else
+    printf '%s' "$resp" | jq -r '"ref=\(.ref) status=\(.status) region=\(.region)"'
+  fi
+}
+
+cmd_wait() {
+  local ref="" timeout="$DEFAULT_WAIT_TIMEOUT"
+  local json_mode=false
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --timeout) timeout="$2"; shift 2 ;;
+      --json) json_mode=true; shift ;;
+      --*) die "wait: unknown flag: $1" ;;
+      *) ref="$1"; shift ;;
+    esac
+  done
+  [ -z "$ref" ] && die "wait: missing <ref>"
+
+  require_jq; require_curl; require_pat
+
+  local elapsed=0
+  while : ; do
+    local resp
+    resp=$(api_call GET "projects/$ref")
+    local status
+    status=$(printf '%s' "$resp" | jq -r '.status // "UNKNOWN"')
+    case "$status" in
+      ACTIVE_HEALTHY)
+        if $json_mode; then
+          jq -n --arg ref "$ref" --arg status "$status" --argjson elapsed "$elapsed" \
+            '{ref: $ref, status: $status, elapsed_s: $elapsed}'
+        else
+          echo "ready ref=$ref status=$status elapsed_s=$elapsed"
+        fi
+        return 0
+        ;;
+      INIT_FAILED|REMOVED|RESTORE_FAILED|PAUSE_FAILED)
+        echo "gstack-gbrain-supabase-provision: project $ref reached terminal failure state '$status'" >&2
+        exit 7
+        ;;
+      COMING_UP|INACTIVE|ACTIVE_UNHEALTHY|UNKNOWN|RESTORING|UPGRADING|PAUSING|RESTARTING|RESIZING|GOING_DOWN)
+        # Still provisioning — keep polling.
+        ;;
+      *)
+        # Unexpected status from Supabase. Log but keep polling.
+        echo "gstack-gbrain-supabase-provision: unexpected status '$status' — continuing to poll" >&2
+        ;;
+    esac
+
+    if [ "$elapsed" -ge "$timeout" ]; then
+      echo "gstack-gbrain-supabase-provision: wait timed out after ${timeout}s (last status: $status)" >&2
+      echo "gstack-gbrain-supabase-provision: re-run with /setup-gbrain --resume-provision $ref" >&2
+      exit 6
+    fi
+    sleep "$POLL_INTERVAL"
+    elapsed=$((elapsed + POLL_INTERVAL))
+  done
+}
+
+cmd_pooler_url() {
+  local ref=""
+  local json_mode=false
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --json) json_mode=true; shift ;;
+      --*) die "pooler-url: unknown flag: $1" ;;
+      *) ref="$1"; shift ;;
+    esac
+  done
+  [ -z "$ref" ] && die "pooler-url: missing <ref>"
+
+  require_jq; require_curl; require_pat; require_db_pass
+
+  local resp
+  resp=$(api_call GET "projects/$ref/config/database/pooler")
+
+  # Prefer the singular Session Pooler config when Supabase returns an
+  # array (response shape can vary by project state). Fall back to the
+  # first PRIMARY entry if no "session" pool_mode is present.
+  local db_user db_host db_port db_name
+  local first_or_session
+  if printf '%s' "$resp" | jq -e 'type == "array"' >/dev/null 2>&1; then
+    first_or_session=$(printf '%s' "$resp" | jq '[.[] | select(.pool_mode == "session")][0] // .[0]')
+  else
+    first_or_session="$resp"
+  fi
+
+  db_user=$(printf '%s' "$first_or_session" | jq -r '.db_user // empty')
+  db_host=$(printf '%s' "$first_or_session" | jq -r '.db_host // empty')
+  db_port=$(printf '%s' "$first_or_session" | jq -r '.db_port // empty')
+  db_name=$(printf '%s' "$first_or_session" | jq -r '.db_name // empty')
+
+  if [ -z "$db_user" ] || [ -z "$db_host" ] || [ -z "$db_port" ] || [ -z "$db_name" ]; then
+    die "pooler-url: missing pooler config fields (db_user/db_host/db_port/db_name); re-poll or check project state"
+  fi
+
+  local url="postgresql://${db_user}:${DB_PASS}@${db_host}:${db_port}/${db_name}"
+
+  if $json_mode; then
+    jq -n --arg ref "$ref" --arg pooler_url "$url" '{ref: $ref, pooler_url: $pooler_url}'
+  else
+    # Non-JSON mode prints the URL; callers capturing it into a variable
+    # keep it in process memory only.
+    echo "$url"
+  fi
+}
+
+cmd_list_orphans() {
+  local name_prefix="gbrain"
+  local json_mode=false
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --name-prefix) name_prefix="$2"; shift 2 ;;
+      --json) json_mode=true; shift ;;
+      --*) die "list-orphans: unknown flag: $1" ;;
+      *) die "list-orphans: unexpected arg: $1" ;;
+    esac
+  done
+
+  require_jq; require_curl; require_pat
+  local all
+  all=$(api_call GET projects)
+
+  # Extract the active brain's ref from ~/.gbrain/config.json if present.
+  # Pooler URL format: postgresql://postgres.<ref>:<pw>@...
+  local active_ref="null"
+  local gbrain_cfg="$HOME/.gbrain/config.json"
+  if [ -f "$gbrain_cfg" ]; then
+    local url
+    url=$(jq -r '.database_url // empty' "$gbrain_cfg" 2>/dev/null || true)
+    if [ -n "$url" ]; then
+      # Extract user portion before the colon: postgresql://USER:pw@...
+      local user
+      user=$(printf '%s' "$url" | sed -E 's|^[a-z]+://([^:]+):.*$|\1|')
+      # User format: postgres.<ref> — pull ref suffix
+      case "$user" in
+        postgres.*)
+          local ref="${user#postgres.}"
+          active_ref=$(jq -Rn --arg r "$ref" '$r')
+          ;;
+      esac
+    fi
+  fi
+
+  local orphans
+  orphans=$(printf '%s' "$all" | jq \
+    --arg prefix "$name_prefix" \
+    --argjson active "$active_ref" \
+    '[.[]
+       | select(.name | startswith($prefix))
+       | select(.ref != $active)
+       | {ref: .ref, name: .name, created_at: .created_at, region: .region}]')
+
+  jq -n --argjson active "$active_ref" --argjson orphans "$orphans" \
+    '{active_ref: $active, orphans: $orphans}'
+}
+
+cmd_delete_project() {
+  local ref=""
+  local json_mode=false
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --json) json_mode=true; shift ;;
+      --*) die "delete-project: unknown flag: $1" ;;
+      *) ref="$1"; shift ;;
+    esac
+  done
+  [ -z "$ref" ] && die "delete-project: missing <ref>"
+
+  require_jq; require_curl; require_pat
+  api_call DELETE "projects/$ref" >/dev/null
+  jq -n --arg ref "$ref" '{deleted_ref: $ref}'
+}
+
+case "${1:-}" in
+  list-orgs)        shift; cmd_list_orgs "$@" ;;
+  create)           shift; cmd_create "$@" ;;
+  wait)             shift; cmd_wait "$@" ;;
+  pooler-url)       shift; cmd_pooler_url "$@" ;;
+  list-orphans)     shift; cmd_list_orphans "$@" ;;
+  delete-project)   shift; cmd_delete_project "$@" ;;
+  --help|-h|help)   sed -n '2,80p' "$0" | sed 's/^# \{0,1\}//' ;;
+  "")  die "usage: gstack-gbrain-supabase-provision {list-orgs|create|wait|pooler-url|list-orphans|delete-project|--help}" ;;
+  *)   die "unknown subcommand: $1" ;;
+esac

bin/gstack-gbrain-supabase-verify

@@ -0,0 +1,126 @@
+#!/usr/bin/env bash
+# gstack-gbrain-supabase-verify — structural check on a Supabase Session
+# Pooler URL before handing it to `gbrain init`.
+#
+# Usage:
+#   gstack-gbrain-supabase-verify <url>
+#   echo "<url>" | gstack-gbrain-supabase-verify -
+#
+# Accepts ONLY Session Pooler URLs (port 6543, host *.pooler.supabase.com).
+# Rejects direct-connection URLs (db.*.supabase.co:5432) since those are
+# IPv6-only and fail in many environments — gbrain's init wizard warns
+# about this at init.ts:150-158.
+#
+# Canonical shape (per gbrain init.ts:266):
+#   postgresql://postgres.<ref>:<password>@aws-0-<region>.pooler.supabase.com:6543/postgres
+#
+# Exit codes:
+#   0 — URL passes structural check
+#   2 — invalid format (bad scheme, port, host, userinfo, or empty password)
+#   3 — direct-connection URL rejected (common mistake, special-cased for UX)
+#
+# The verifier never makes a network call; purely a regex match. Whether
+# the URL actually works (database up, password correct, host reachable)
+# is gbrain's problem at init time.
+#
+# Reads URL from:
+#   1. argv[1] if provided and not "-"
+#   2. stdin if argv[1] is "-" or missing
+#
+# Never echoes the URL to stderr (it contains a password). Error messages
+# refer to "the URL" generically.
+set -euo pipefail
+
+die()   { echo "gstack-gbrain-supabase-verify: $*" >&2; exit 2; }
+reject_direct() {
+  cat >&2 <<EOF
+gstack-gbrain-supabase-verify: rejected direct-connection URL
+
+  You pasted a Supabase direct-connection URL (db.*.supabase.co on port
+  5432). Direct connections are IPv6-only and fail in many environments.
+
+  Use the Session Pooler instead:
+    Supabase Dashboard → Settings → Database → Connection Pooler →
+    Transaction/Session → copy URI (port 6543)
+
+  Expected shape:
+    postgresql://postgres.<ref>:<password>@aws-0-<region>.pooler.supabase.com:6543/postgres
+EOF
+  exit 3
+}
+
+URL=""
+case "${1:-}" in
+  -)   URL=$(cat) ;;
+  "")  URL=$(cat) ;;
+  *)   URL="$1" ;;
+esac
+
+URL=$(printf '%s' "$URL" | tr -d '[:space:]')
+[ -z "$URL" ] && die "empty URL"
+
+# Scheme: must be postgresql:// or postgres://. Explicitly reject other
+# schemes rather than guess.
+case "$URL" in
+  postgresql://*|postgres://*) ;;
+  *) die "bad scheme (must start with postgresql:// or postgres://)" ;;
+esac
+
+# Strip scheme to expose userinfo + host + port + path.
+rest="${URL#*://}"
+
+# Userinfo portion: everything before the first @. Must contain a : (user:pass).
+case "$rest" in
+  *@*) ;;
+  *) die "missing userinfo (expected postgres.<ref>:<password>@host)" ;;
+esac
+userinfo="${rest%%@*}"
+after_at="${rest#*@}"
+
+# Userinfo must be user:password with neither part empty.
+case "$userinfo" in
+  *:*) ;;
+  *) die "userinfo missing password separator (expected user:password@)" ;;
+esac
+user_part="${userinfo%%:*}"
+pass_part="${userinfo#*:}"
+[ -z "$user_part" ] && die "empty user portion in userinfo"
+[ -z "$pass_part" ] && die "empty password in userinfo"
+
+# Host + port + path.
+# Direct-connection detection FIRST (specific error beats generic).
+case "$after_at" in
+  db.*.supabase.co:5432*|db.*.supabase.co/*|db.*.supabase.co) reject_direct ;;
+esac
+
+# Extract host:port (before first / if present).
+hostport="${after_at%%/*}"
+case "$hostport" in
+  *:*) ;;
+  *) die "missing port (Session Pooler requires :6543)" ;;
+esac
+host="${hostport%:*}"
+port="${hostport##*:}"
+
+# Host must be *.pooler.supabase.com (case-insensitive).
+host_lower=$(printf '%s' "$host" | tr '[:upper:]' '[:lower:]')
+case "$host_lower" in
+  *.pooler.supabase.com) ;;
+  *) die "host '$host' is not a Supabase Session Pooler (expected *.pooler.supabase.com)" ;;
+esac
+
+# Port must be 6543 (Session Pooler default).
+if [ "$port" != "6543" ]; then
+  die "port must be 6543 for Session Pooler (got $port)"
+fi
+
+# User portion should look like postgres.<ref> (20-char lowercase ref,
+# per the Supabase Management API contract). Not strictly required by
+# gbrain, but rejecting a plain "postgres" user catches a common paste
+# error where someone grabs the Direct URL userinfo by mistake.
+case "$user_part" in
+  postgres.*) ;;
+  *) die "user portion '$user_part' should be 'postgres.<project-ref>' (20-char ref)" ;;
+esac
+
+echo "ok"

bin/gstack-gbrain-sync.ts

@@ -0,0 +1,935 @@
+#!/usr/bin/env bun
+/**
+ * gstack-gbrain-sync — V1 unified sync verb.
+ *
+ * Orchestrates three storage tiers per plan §"Storage tiering":
+ *
+ *   1. Code (current repo)         → `gbrain sources add` (idempotent via
+ *                                    lib/gbrain-sources.ts) + `gbrain sync
+ *                                    --strategy code` (incremental) or
+ *                                    `gbrain reindex-code --yes` (--full).
+ *                                    NEVER `gbrain import` (markdown only).
+ *   2. Transcripts + curated memory → gstack-memory-ingest (typed put_page)
+ *   3. Curated artifacts to git    → gstack-brain-sync (existing pipeline)
+ *
+ * Modes:
+ *   --incremental (default) — mtime fast-path; runs all 3 stages with cache hits
+ *   --full                  — first-run; full walk + reindex; honest budget per ED2
+ *   --dry-run               — preview what would sync; no writes anywhere (incl. state file)
+ *
+ * Concurrency safety per /plan-eng-review D1:
+ *   - Lock file at ~/.gstack/.sync-gbrain.lock (PID + start ts).
+ *   - Stale-lock takeover after 5 min (process death).
+ *   - State file written via tmp+rename for atomicity.
+ *   - Lock released in finally; SIGINT/SIGTERM trapped for cleanup.
+ *
+ * --watch (V1.5 P0 TODO): file-watcher daemon. NOTE: gbrain v0.25.1 already
+ * ships `gbrain sync --watch [--interval N]` and `gbrain sync --install-cron`;
+ * when revisited, /sync-gbrain --watch wires through to the gbrain CLI rather
+ * than building a gstack-side daemon.
+ */
+
+import { existsSync, statSync, mkdirSync, writeFileSync, readFileSync, unlinkSync, renameSync } from "fs";
+import { join, dirname } from "path";
+import { execSync, spawnSync } from "child_process";
+import { homedir, hostname } from "os";
+import { createHash } from "crypto";
+
+import "../lib/conductor-env-shim";
+import { detectEngineTier, withErrorContext, canonicalizeRemote } from "../lib/gstack-memory-helpers";
+import { ensureSourceRegistered, sourcePageCount } from "../lib/gbrain-sources";
+import { localEngineStatus, type LocalEngineStatus } from "../lib/gbrain-local-status";
+import { buildGbrainEnv, spawnGbrain, execGbrainJson } from "../lib/gbrain-exec";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+type Mode = "incremental" | "full" | "dry-run";
+
+interface CliArgs {
+  mode: Mode;
+  quiet: boolean;
+  noCode: boolean;
+  noMemory: boolean;
+  noBrainSync: boolean;
+  codeOnly: boolean;
+}
+
+interface CodeStageDetail {
+  source_id?: string;
+  source_path?: string;
+  page_count?: number | null;
+  last_imported?: string;
+  status?: "ok" | "skipped" | "failed";
+}
+
+interface StageResult {
+  name: string;
+  ran: boolean;
+  ok: boolean;
+  duration_ms: number;
+  summary: string;
+  /** Stage-specific structured detail. Code stage carries source_id + page_count. */
+  detail?: CodeStageDetail;
+}
+
+// ── Constants ──────────────────────────────────────────────────────────────
+
+const HOME = homedir();
+const GSTACK_HOME = process.env.GSTACK_HOME || join(HOME, ".gstack");
+const STATE_PATH = join(GSTACK_HOME, ".gbrain-sync-state.json");
+const LOCK_PATH = join(GSTACK_HOME, ".sync-gbrain.lock");
+const STALE_LOCK_MS = 5 * 60 * 1000;
+
+// ── CLI ────────────────────────────────────────────────────────────────────
+
+function printUsage(): void {
+  console.error(`Usage: gstack-gbrain-sync [--incremental|--full|--dry-run] [options]
+
+Modes:
+  --incremental        Default. mtime fast-path; ~50ms steady-state.
+  --full               First-run; full walk + reindex. Honest ~25-35 min for big Macs (ED2).
+  --dry-run            Preview what would sync; no writes anywhere.
+
+Options:
+  --quiet              Suppress per-stage output.
+  --no-code            Skip the cwd code-import stage.
+  --no-memory          Skip the gstack-memory-ingest stage (transcripts + artifacts).
+  --no-brain-sync      Skip the gstack-brain-sync git pipeline stage.
+  --code-only          Only run the code-import stage (alias for --no-memory --no-brain-sync).
+  --help               This text.
+
+Stages run in order: code → memory ingest → curated git push.
+Each stage failure is non-fatal; subsequent stages still run.
+`);
+}
+
+function parseArgs(): CliArgs {
+  const args = process.argv.slice(2);
+  let mode: Mode = "incremental";
+  let quiet = false;
+  let noCode = false;
+  let noMemory = false;
+  let noBrainSync = false;
+  let codeOnly = false;
+
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    switch (a) {
+      case "--incremental": mode = "incremental"; break;
+      case "--full": mode = "full"; break;
+      case "--dry-run": mode = "dry-run"; break;
+      case "--quiet": quiet = true; break;
+      case "--no-code": noCode = true; break;
+      case "--no-memory": noMemory = true; break;
+      case "--no-brain-sync": noBrainSync = true; break;
+      case "--code-only":
+        codeOnly = true;
+        noMemory = true;
+        noBrainSync = true;
+        break;
+      case "--help":
+      case "-h":
+        printUsage();
+        process.exit(0);
+      default:
+        console.error(`Unknown argument: ${a}`);
+        printUsage();
+        process.exit(1);
+    }
+  }
+
+  return { mode, quiet, noCode, noMemory, noBrainSync, codeOnly };
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function repoRoot(): string | null {
+  try {
+    const out = execSync("git rev-parse --show-toplevel", { encoding: "utf-8", timeout: 2000 });
+    return out.trim();
+  } catch {
+    return null;
+  }
+}
+
+function originUrl(): string | null {
+  try {
+    const out = execSync("git remote get-url origin", { encoding: "utf-8", timeout: 2000 });
+    return out.trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Derive a host- and worktree-aware source id for the cwd code corpus.
+ *
+ * Pattern: `gstack-code-<slug>-<hostpathhash8>` where slug comes from origin
+ * (org/repo) and hostpathhash8 is the first 8 hex chars of
+ * sha1(`${hostname}::${absolute repo path}`). Folding hostname into the hash
+ * keeps Conductor worktrees of the same repo as distinct sources on one host
+ * AND keeps two machines that share an absolute layout (e.g. chezmoi-managed
+ * home dirs against a federated brain) from colliding on each other.
+ *
+ * Falls back to the repo basename when there is no origin (local repo).
+ *
+ * `GSTACK_HOSTNAME` env override is honored for deterministic tests; in
+ * production paths it is unset and `os.hostname()` is used.
+ *
+ * gbrain enforces source ids to be 1-32 lowercase alnum chars with
+ * optional interior hyphens. `constrainSourceId` handles the 32-char cap
+ * with a hashed-tail fallback when the combined slug exceeds budget.
+ */
+function deriveCodeSourceId(repoPath: string): string {
+  const host = process.env.GSTACK_HOSTNAME || hostname();
+  const hostPathHash = createHash("sha1").update(`${host}::${repoPath}`).digest("hex").slice(0, 8);
+  const remote = canonicalizeRemote(originUrl());
+  if (remote) {
+    const segs = remote.split("/").filter(Boolean);
+    const slugSource = segs.slice(-2).join("-");
+    const fullId = constrainSourceId("gstack-code", `${slugSource}-${hostPathHash}`);
+    // If the org+repo+hostpathhash fits cleanly (suffix preserved), use it.
+    if (fullId.endsWith(`-${hostPathHash}`)) return fullId;
+    // Otherwise drop the org prefix and retry with just repo+hostpathhash so
+    // the repo name stays readable. If that still doesn't fit,
+    // constrainSourceId falls back to a deterministic hash-only form.
+    const repoOnly = segs[segs.length - 1] || "repo";
+    return constrainSourceId("gstack-code", `${repoOnly}-${hostPathHash}`);
+  }
+  const base = repoPath.split("/").pop() || "repo";
+  return constrainSourceId("gstack-code", `${base}-${hostPathHash}`);
+}
+
+/**
+ * Pre-pathhash source id, kept for orphan detection only.
+ *
+ * Earlier /sync-gbrain versions registered `gstack-code-<slug>` (no pathhash
+ * suffix). On a multi-worktree repo, those collapsed onto a single source id
+ * with last-sync-wins semantics. The new path-keyed id leaves the legacy
+ * source orphaned in the brain — federated cross-source search would return
+ * stale duplicate hits. We remove the legacy id once, on the first new-format
+ * sync from any worktree of this repo, so users don't accumulate orphans.
+ */
+function deriveLegacyCodeSourceId(repoPath: string): string {
+  const remote = canonicalizeRemote(originUrl());
+  if (remote) {
+    const segs = remote.split("/").filter(Boolean);
+    const slugSource = segs.slice(-2).join("-");
+    return constrainSourceId("gstack-code", slugSource);
+  }
+  const base = repoPath.split("/").pop() || "repo";
+  return constrainSourceId("gstack-code", base);
+}
+
+/**
+ * Pre-#1468 path-only-hash source id, kept for hostname-fold migration only.
+ *
+ * Before the hostname fold, `deriveCodeSourceId` hashed only the absolute
+ * repo path: `gstack-code-<slug>-<sha1(path).slice(0,8)>`. After #1468 the
+ * hash key is `${hostname}::${path}`, so every existing user's brain has a
+ * legacy id that no longer matches what `deriveCodeSourceId` produces. We
+ * detect this form once, attempt rename-in-place if the gbrain CLI supports
+ * `sources rename`, and otherwise clean up after the new source successfully
+ * syncs. Distinct from `deriveLegacyCodeSourceId` (pre-pathhash v1.x form);
+ * both probes run.
+ */
+export function derivePathOnlyHashLegacyId(repoPath: string): string {
+  const pathHash = createHash("sha1").update(repoPath).digest("hex").slice(0, 8);
+  const remote = canonicalizeRemote(originUrl());
+  if (remote) {
+    const segs = remote.split("/").filter(Boolean);
+    const slugSource = segs.slice(-2).join("-");
+    return constrainSourceId("gstack-code", `${slugSource}-${pathHash}`);
+  }
+  const base = repoPath.split("/").pop() || "repo";
+  return constrainSourceId("gstack-code", `${base}-${pathHash}`);
+}
+
+/**
+ * Feature-check whether the installed gbrain CLI ships `sources rename <old> <new>`.
+ *
+ * Per the v1.40.0.0 design review: probing `gbrain sources rename --help` and
+ * matching for the exact argument shape catches the case where gbrain's
+ * `sources` parent help mentions a `rename` subcommand but the CLI doesn't
+ * accept the `<old> <new>` form (or vice versa). Cached for the lifetime
+ * of the process. As of gbrain 0.35.0.0 this command does not exist, so the
+ * function returns false and the migration path falls back to register-new
+ * + sync-OK + remove-old.
+ */
+let _gbrainSupportsRenameCache: boolean | null = null;
+export function _resetGbrainSupportsRenameCache(): void {
+  _gbrainSupportsRenameCache = null;
+}
+function gbrainSupportsSourcesRename(env?: NodeJS.ProcessEnv): boolean {
+  if (_gbrainSupportsRenameCache !== null) return _gbrainSupportsRenameCache;
+  try {
+    const r = spawnGbrain(["sources", "rename", "--help"], {
+      timeout: 5_000,
+      baseEnv: env,
+    });
+    const out = `${r.stdout || ""}\n${r.stderr || ""}`;
+    // Match the exact argument shape: `rename <old> <new>` (with literal
+    // angle brackets in usage strings) or `rename OLD NEW`.
+    const exact = /sources\s+rename\s+<old>\s+<new>/i.test(out)
+      || /sources\s+rename\s+OLD\s+NEW/.test(out)
+      || /sources\s+rename\s+<oldId>\s+<newId>/i.test(out);
+    _gbrainSupportsRenameCache = exact && r.status === 0;
+  } catch {
+    _gbrainSupportsRenameCache = false;
+  }
+  return _gbrainSupportsRenameCache;
+}
+
+/**
+ * Look up a source's `local_path` from `gbrain sources list --json`.
+ * Returns null when the source is absent or the listing fails.
+ *
+ * `env` is the environment passed to the spawned `gbrain` process; defaults
+ * to `process.env`. Tests inject a PATH that points at a gbrain shim so the
+ * helper can be exercised without a real gbrain CLI.
+ */
+export function sourceLocalPath(sourceId: string, env?: NodeJS.ProcessEnv): string | null {
+  const list = execGbrainJson<Array<{ id: string; local_path?: string }>>(
+    ["sources", "list", "--json"],
+    { baseEnv: env },
+  );
+  if (!list) return null;
+  const found = list.find((s) => s.id === sourceId);
+  return found?.local_path ?? null;
+}
+
+/** Result of `planHostnameFoldMigration` — informs `runCodeImport` of next steps. */
+export type HostnameFoldMigration =
+  | { kind: "none"; reason: "ids-match" | "no-legacy-source" }
+  | { kind: "skipped-path-drift"; oldId: string; oldPath: string; currentPath: string }
+  | { kind: "renamed"; oldId: string; newId: string }
+  | { kind: "pending-cleanup"; oldId: string };
+
+/**
+ * Decide how to migrate from the pre-#1468 path-only-hash source id to the
+ * new hostname-fold id.
+ *
+ * Order:
+ *   1. If old == new → no-op.
+ *   2. Look up old source's local_path. Absent → no legacy source to migrate.
+ *   3. local_path != currentRoot → user moved the repo or two machines share a
+ *      hash slot. Skip migration; let the user clean up manually. We will NOT
+ *      rename or remove anything; the new source is registered alongside.
+ *   4. Otherwise: feature-check `gbrain sources rename`. If supported and the
+ *      rename call exits 0 → renamed, pages preserved.
+ *   5. Else: pending-cleanup. Caller registers + syncs new source first; only
+ *      after sync succeeds with a non-zero page count does it remove the old.
+ *      This avoids a data-loss window where the old source is gone before the
+ *      new one is verifiably populated.
+ */
+export function planHostnameFoldMigration(
+  currentRoot: string,
+  newSourceId: string,
+  legacyPathHashId: string,
+  env?: NodeJS.ProcessEnv,
+): HostnameFoldMigration {
+  if (legacyPathHashId === newSourceId) {
+    return { kind: "none", reason: "ids-match" };
+  }
+  const oldPath = sourceLocalPath(legacyPathHashId, env);
+  if (oldPath === null) {
+    return { kind: "none", reason: "no-legacy-source" };
+  }
+  if (oldPath !== currentRoot) {
+    return {
+      kind: "skipped-path-drift",
+      oldId: legacyPathHashId,
+      oldPath,
+      currentPath: currentRoot,
+    };
+  }
+  if (gbrainSupportsSourcesRename(env)) {
+    const r = spawnGbrain(["sources", "rename", legacyPathHashId, newSourceId], { baseEnv: env });
+    if (r.status === 0) {
+      return { kind: "renamed", oldId: legacyPathHashId, newId: newSourceId };
+    }
+    // Rename failed at runtime — fall through to cleanup path.
+  }
+  return { kind: "pending-cleanup", oldId: legacyPathHashId };
+}
+
+/**
+ * Remove an orphaned source. Called only after new-source sync verifies pages
+ * exist, so the old source is provably redundant before deletion.
+ *
+ * Flag note: existing call sites used `--confirm-destructive` here and
+ * `--yes` in `lib/gbrain-sources.ts` — gbrain 0.35.0.0 accepts neither
+ * deterministically (the subcommand surface help is generic). We pass
+ * `--confirm-destructive` to match the existing call site convention; the
+ * flag-helper centralization in commit 4 (lib/gbrain-exec.ts) will resolve
+ * the inconsistency across the codebase.
+ */
+export function removeOrphanedSource(oldId: string, env?: NodeJS.ProcessEnv): boolean {
+  const r = spawnGbrain(["sources", "remove", oldId, "--confirm-destructive"], { baseEnv: env });
+  return r.status === 0;
+}
+
+/**
+ * Build a gbrain-valid source id (1-32 lowercase alnum + interior hyphens). Sanitizes
+ * `raw`, prefixes with `prefix`, and falls back to a hashed-tail form when total length
+ * would exceed 32 chars.
+ *
+ * Truncation cuts on hyphen boundaries (whole-word units) from the right, never
+ * mid-word. Inputs like "drummerms-av-sow-wiz-skill-270c0001" produce
+ * "${prefix}-270c0001-<hash>", not "${prefix}-kill-270c0001-<hash>".
+ */
+function constrainSourceId(prefix: string, raw: string): string {
+  const MAX = 32;
+  const slug = raw.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  // Empty slug after sanitize (e.g. raw was all non-alnum like "___") would
+  // produce "${prefix}-" which fails gbrain's validator on the trailing
+  // hyphen. Fall back to a deterministic hash of the original input so the
+  // result is stable across runs of the same repo.
+  if (!slug) {
+    const hash = createHash("sha1").update(raw || "_empty").digest("hex").slice(0, 6);
+    return `${prefix}-${hash}`;
+  }
+  const full = `${prefix}-${slug}`;
+  if (full.length <= MAX) return full;
+  const hash = createHash("sha1").update(slug).digest("hex").slice(0, 6);
+  // Total budget: prefix + "-" + tail + "-" + hash
+  const tailBudget = MAX - prefix.length - 2 - hash.length;
+  if (tailBudget < 1) return `${prefix}-${hash}`;
+  // Cut on hyphen boundaries instead of mid-word. Walk tokens from the right,
+  // accumulating until adding the next token would exceed tailBudget. This
+  // preserves readable suffixes (pathhash, repo name) and avoids embarrassing
+  // mid-word artifacts like "skill" → "kill".
+  const tokens = slug.split("-").filter(Boolean);
+  const kept: string[] = [];
+  let len = 0;
+  for (let i = tokens.length - 1; i >= 0; i--) {
+    const add = kept.length === 0 ? tokens[i].length : tokens[i].length + 1;
+    if (len + add > tailBudget) break;
+    kept.unshift(tokens[i]);
+    len += add;
+  }
+  const tail = kept.join("-");
+  return tail ? `${prefix}-${tail}-${hash}` : `${prefix}-${hash}`;
+}
+
+// ── Lock file (D1) ─────────────────────────────────────────────────────────
+
+interface LockInfo {
+  pid: number;
+  started_at: string;
+}
+
+function acquireLock(): boolean {
+  mkdirSync(GSTACK_HOME, { recursive: true });
+  if (existsSync(LOCK_PATH)) {
+    // Check if stale.
+    try {
+      const stat = statSync(LOCK_PATH);
+      const ageMs = Date.now() - stat.mtimeMs;
+      if (ageMs > STALE_LOCK_MS) {
+        // Stale; take over.
+        unlinkSync(LOCK_PATH);
+      } else {
+        return false;
+      }
+    } catch {
+      // Cannot stat; bail conservatively.
+      return false;
+    }
+  }
+  const info: LockInfo = { pid: process.pid, started_at: new Date().toISOString() };
+  try {
+    writeFileSync(LOCK_PATH, JSON.stringify(info), { encoding: "utf-8", flag: "wx" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function releaseLock(): void {
+  try {
+    if (!existsSync(LOCK_PATH)) return;
+    const raw = readFileSync(LOCK_PATH, "utf-8");
+    const info = JSON.parse(raw) as LockInfo;
+    if (info.pid === process.pid) {
+      unlinkSync(LOCK_PATH);
+    }
+  } catch {
+    // Best-effort cleanup.
+  }
+}
+
+// ── Stage runners ──────────────────────────────────────────────────────────
+
+/**
+ * Build a SKIP result for the code/memory stage when the local engine is
+ * not in 'ok' state (per plan D12). Surface the status verbatim so the
+ * verdict block tells the user exactly what's wrong without re-probing.
+ *
+ * Reasons mapped to user-actionable summaries:
+ *   no-cli         → "gbrain CLI not on PATH; install via /setup-gbrain"
+ *   missing-config → "no local engine; run /setup-gbrain to add local PGLite"
+ *   broken-config  → "config file at ~/.gbrain/config.json is malformed; see /setup-gbrain Step 1.5"
+ *   broken-db      → "config points at unreachable DB; see /setup-gbrain Step 1.5"
+ */
+function skipStageForLocalStatus(
+  stage: "code" | "memory",
+  status: LocalEngineStatus,
+  t0: number,
+): StageResult {
+  const reasons: Record<Exclude<LocalEngineStatus, "ok">, string> = {
+    "no-cli": "gbrain CLI not on PATH; install via /setup-gbrain",
+    "missing-config":
+      "no local engine; run /setup-gbrain to add local PGLite for code search",
+    "broken-config":
+      "config at ~/.gbrain/config.json is malformed; see /setup-gbrain Step 1.5",
+    "broken-db":
+      "config points at unreachable DB; see /setup-gbrain Step 1.5",
+  };
+  const reason = reasons[status as Exclude<LocalEngineStatus, "ok">];
+  return {
+    name: stage,
+    ran: false,
+    ok: true, // SKIP (per D12) — not a stage failure, just an unsatisfied prerequisite
+    duration_ms: Date.now() - t0,
+    summary: `skipped — local engine ${status} — ${reason}`,
+  };
+}
+
+
+async function runCodeImport(args: CliArgs): Promise<StageResult> {
+  const t0 = Date.now();
+  const root = repoRoot();
+  if (!root) {
+    return { name: "code", ran: false, ok: true, duration_ms: 0, summary: "skipped (not in git repo)" };
+  }
+
+  const sourceId = deriveCodeSourceId(root);
+
+  // dry-run preview always shows the would-do steps, regardless of local
+  // engine state. Useful for "what would /sync-gbrain do" without probing
+  // the engine.
+  if (args.mode === "dry-run") {
+    return {
+      name: "code",
+      ran: false,
+      ok: true,
+      duration_ms: 0,
+      summary: `would: gbrain sources add ${sourceId} --path ${root} --federated; gbrain sync --strategy code --source ${sourceId}; gbrain sources attach ${sourceId}`,
+      detail: { source_id: sourceId, source_path: root, status: "skipped" },
+    };
+  }
+
+  // Split-engine pre-flight (per plan D12): when local engine is not ok, SKIP
+  // code stage cleanly. Brain-sync stage still runs because it doesn't depend
+  // on local engine. The /sync-gbrain Step 1.5 pre-flight surfaces the user
+  // remediation message; this skip just keeps the orchestrator from crashing
+  // when the local DB is dead. Skipped on --dry-run (above) since dry-run
+  // never actually probes anything.
+  const localStatus = localEngineStatus({ noCache: false });
+  if (localStatus !== "ok") {
+    return skipStageForLocalStatus("code", localStatus, t0);
+  }
+
+  // Step 0a: Best-effort cleanup of pre-pathhash legacy source (v1.x form).
+  // Earlier /sync-gbrain versions registered `gstack-code-<slug>` (no path
+  // suffix). On a multi-worktree repo, those collapsed onto a single id
+  // with last-sync-wins. Federated search would return stale duplicate
+  // hits forever if we left the orphan in place. Remove the legacy id once
+  // here so users don't accumulate orphans.
+  // Failure is non-fatal — we still register the new id below.
+  // gbrainEnv seeds DATABASE_URL from gbrain's config so this stage works
+  // inside Next.js / Prisma / Rails projects with their own .env.local
+  // (codex review #7 — bug fix is wider than #1508 as filed).
+  const gbrainEnv = buildGbrainEnv({ announce: !args.quiet });
+  const legacyId = deriveLegacyCodeSourceId(root);
+  let legacyRemoved = false;
+  if (legacyId !== sourceId) {
+    const rm = spawnGbrain(["sources", "remove", legacyId, "--confirm-destructive"], {
+      timeout: 30_000,
+      baseEnv: gbrainEnv,
+    });
+    // Treat absent-source as success (clean state). gbrain emits "not found" on
+    // missing id; treat any non-zero exit without "not found" as a soft fail.
+    if (rm.status === 0) legacyRemoved = true;
+  }
+
+  // Step 0b: Hostname-fold migration (#1414).
+  // Before #1468 the source id hashed only the absolute repo path. After the
+  // hostname fold, every existing user has a legacy id that no longer matches
+  // what deriveCodeSourceId produces. Try rename-in-place first (preserves
+  // pages); fall back to register-new → sync-OK → remove-old. Path-drift
+  // (user moved the repo, etc.) skips migration with a warning.
+  const pathOnlyHashLegacyId = derivePathOnlyHashLegacyId(root);
+  const migration = planHostnameFoldMigration(root, sourceId, pathOnlyHashLegacyId, gbrainEnv);
+  if (migration.kind === "skipped-path-drift" && !args.quiet) {
+    console.error(
+      `[sync:code] hostname-fold migration skipped: legacy source ${migration.oldId} `
+      + `points at ${migration.oldPath}, current repo is ${migration.currentPath}. `
+      + `Clean up manually with: gbrain sources remove ${migration.oldId} --confirm-destructive`,
+    );
+  } else if (migration.kind === "renamed" && !args.quiet) {
+    console.error(`[sync:code] hostname-fold migration: renamed ${migration.oldId} → ${migration.newId} (pages preserved)`);
+  }
+
+  // Step 1: Ensure source registered (idempotent). Single source of truth in lib —
+  // no synchronous duplicate here (per /codex review #12).
+  let registered = false;
+  try {
+    const result = await ensureSourceRegistered(sourceId, root, { federated: true, env: gbrainEnv });
+    registered = result.changed;
+  } catch (err) {
+    return {
+      name: "code",
+      ran: true,
+      ok: false,
+      duration_ms: Date.now() - t0,
+      summary: `source registration failed: ${(err as Error).message}`,
+      detail: { source_id: sourceId, source_path: root, status: "failed" },
+    };
+  }
+
+  // Step 2: Run sync or reindex.
+  const syncArgs = args.mode === "full"
+    ? ["reindex-code", "--source", sourceId, "--yes"]
+    : ["sync", "--strategy", "code", "--source", sourceId];
+
+  const syncResult = spawnGbrain(syncArgs, {
+    stdio: args.quiet ? ["ignore", "ignore", "ignore"] : ["ignore", "inherit", "inherit"],
+    timeout: 35 * 60 * 1000,
+    baseEnv: gbrainEnv,
+  });
+
+  if (syncResult.status !== 0) {
+    return {
+      name: "code",
+      ran: true,
+      ok: false,
+      duration_ms: Date.now() - t0,
+      summary: `gbrain ${syncArgs.join(" ")} exited ${syncResult.status}`,
+      detail: { source_id: sourceId, source_path: root, status: "failed" },
+    };
+  }
+
+  // Step 3: Pin this worktree's CWD to the source via .gbrain-source. Subsequent
+  // gbrain code-def / code-refs / code-callers calls from anywhere under <root>
+  // route to this source by default — no --source flag needed.
+  //
+  // If attach fails the whole flow has a silent correctness problem: sync
+  // succeeded but unqualified `gbrain code-def` from this worktree will hit
+  // the wrong/default source. Treat it as a stage failure (ok=false) so the
+  // verdict block surfaces ERR and the user knows to retry rather than
+  // trusting stale results.
+  const attach = spawnGbrain(["sources", "attach", sourceId], {
+    timeout: 10_000,
+    cwd: root,
+    baseEnv: gbrainEnv,
+  });
+  const pageCount = sourcePageCount(sourceId, gbrainEnv);
+
+  // Step 4: Deferred hostname-fold cleanup.
+  // Only remove the pre-#1468 path-only-hash source NOW that the new source
+  // has registered + synced + has pages. Removing before sync would create a
+  // data-loss window if sync failed; removing without a page-count check would
+  // wipe pages when sync silently no-op'd. This is the codex-review-flagged
+  // safety: register → sync → verify → THEN delete.
+  let hostnameLegacyRemoved = false;
+  if (migration.kind === "pending-cleanup" && pageCount !== null && pageCount > 0) {
+    hostnameLegacyRemoved = removeOrphanedSource(migration.oldId, gbrainEnv);
+    if (hostnameLegacyRemoved && !args.quiet) {
+      console.error(`[sync:code] hostname-fold migration: removed legacy ${migration.oldId} after new source sync verified (page_count=${pageCount})`);
+    }
+  }
+
+  const legacyParts: string[] = [];
+  if (legacyRemoved) legacyParts.push(`removed legacy ${legacyId}`);
+  if (migration.kind === "renamed") legacyParts.push(`renamed ${migration.oldId}→${migration.newId}`);
+  if (hostnameLegacyRemoved) legacyParts.push(`removed pre-hostname-fold ${migration.kind === "pending-cleanup" ? migration.oldId : ""}`);
+  const legacyNote = legacyParts.length > 0 ? `, ${legacyParts.join(", ")}` : "";
+  const baseSummary = `${registered ? "registered + " : ""}synced ${sourceId} (page_count=${pageCount ?? "unknown"}${legacyNote})`;
+
+  if (attach.status !== 0) {
+    const reason = (attach.stderr || attach.stdout || "").trim().split("\n").pop() || `exit ${attach.status}`;
+    return {
+      name: "code",
+      ran: true,
+      ok: false,
+      duration_ms: Date.now() - t0,
+      summary: `${baseSummary}; attach FAILED (${reason}) — code-def queries from this worktree will hit the default source until /sync-gbrain succeeds`,
+      detail: {
+        source_id: sourceId,
+        source_path: root,
+        page_count: pageCount,
+        last_imported: new Date().toISOString(),
+        status: "failed",
+      },
+    };
+  }
+
+  // v1.29.0.0 changelog promised the per-worktree pin would be ignored in the
+  // consuming repo, but the change actually only added .gbrain-source to
+  // gstack's own .gitignore. Without the consumer-side entry, the pin gets
+  // committed and breaks the per-worktree promise: Conductor sibling worktrees
+  // step on each other's pin every time anyone commits (#1384).
+  ensureGbrainSourceGitignored(root);
+
+  return {
+    name: "code",
+    ran: true,
+    ok: true,
+    duration_ms: Date.now() - t0,
+    summary: baseSummary,
+    detail: {
+      source_id: sourceId,
+      source_path: root,
+      page_count: pageCount,
+      last_imported: new Date().toISOString(),
+      status: "ok",
+    },
+  };
+}
+
+/**
+ * Ensure `.gbrain-source` is listed in the consumer repo's `.gitignore`.
+ *
+ * Idempotent: only appends when the entry is not already present (matched on
+ * trimmed lines so a leading/trailing whitespace difference doesn't add a
+ * second copy). Wraps writes in try/catch so a read-only checkout or weird
+ * perms logs a warning and lets the rest of the sync continue.
+ */
+export function ensureGbrainSourceGitignored(root: string): void {
+  const gitignorePath = join(root, ".gitignore");
+  try {
+    let existing = "";
+    try {
+      existing = readFileSync(gitignorePath, "utf-8");
+    } catch {
+      // No .gitignore yet — we'll create it.
+    }
+    const alreadyIgnored = existing
+      .split("\n")
+      .some((line) => line.trim() === ".gbrain-source");
+    if (alreadyIgnored) {
+      return;
+    }
+    const sep = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+    writeFileSync(gitignorePath, existing + sep + ".gbrain-source\n");
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.warn(
+      `[sync:code] could not add .gbrain-source to ${gitignorePath}: ${msg}`,
+    );
+  }
+}
+
+function runMemoryIngest(args: CliArgs): StageResult {
+  const t0 = Date.now();
+
+  if (args.mode === "dry-run") {
+    return { name: "memory", ran: false, ok: true, duration_ms: 0, summary: "would: gstack-memory-ingest --probe" };
+  }
+
+  // Split-engine pre-flight (per plan D12). gstack-memory-ingest shells out
+  // to `gbrain import` which targets the LOCAL engine. When that engine is
+  // not ok, SKIP cleanly so brain-sync (the only stage that doesn't depend
+  // on local engine) still runs.
+  const localStatus = localEngineStatus({ noCache: false });
+  if (localStatus !== "ok") {
+    return skipStageForLocalStatus("memory", localStatus, t0);
+  }
+
+  const ingestPath = join(import.meta.dir, "gstack-memory-ingest.ts");
+  const ingestArgs = ["run", ingestPath];
+  if (args.mode === "full") ingestArgs.push("--bulk");
+  else ingestArgs.push("--incremental");
+  if (args.quiet) ingestArgs.push("--quiet");
+
+  // Thread the seeded env into the bun grandchild (codex review #7 — the
+  // .env.local footgun affects gstack-memory-ingest.ts too, not just the
+  // direct gbrain spawns in this file). The grandchild calls gbrain import
+  // internally and must see the DATABASE_URL from gbrain's own config.
+  const result = spawnSync("bun", ingestArgs, {
+    encoding: "utf-8",
+    timeout: 35 * 60 * 1000,
+    env: buildGbrainEnv({ announce: false }),
+  });
+
+  // D6: parse [memory-ingest] lines from the child's stderr. ERR-prefixed
+  // lines indicate a system-level failure (gbrain crashed or CLI missing)
+  // and the child exits non-zero. Per-file failures are summarized in the
+  // last non-ERR [memory-ingest] line but do NOT make the verdict ERR.
+  const stderrLines = (result.stderr || "").split("\n");
+  const memLines = stderrLines.filter((l) => l.includes("[memory-ingest]"));
+  const errLine = memLines.find((l) => l.includes("[memory-ingest] ERR"));
+  const lastMemLine = memLines.slice(-1)[0];
+  const rawSummary = errLine || lastMemLine || "ingest pass complete";
+  // Strip the "[memory-ingest] " prefix and any leading "ERR: " for cleaner
+  // verdict output. The orchestrator's own formatStage will prefix with OK/ERR.
+  const summary = rawSummary
+    .replace(/^.*\[memory-ingest\]\s*/, "")
+    .replace(/^ERR:\s*/, "");
+
+  const ok = result.status === 0;
+  return {
+    name: "memory",
+    ran: true,
+    ok,
+    duration_ms: Date.now() - t0,
+    summary: ok
+      ? summary
+      : `${summary}${result.status === null ? " (killed by signal / timeout)" : ` (exit ${result.status})`}`,
+  };
+}
+
+function runBrainSyncPush(args: CliArgs): StageResult {
+  const t0 = Date.now();
+
+  if (args.mode === "dry-run") {
+    return { name: "brain-sync", ran: false, ok: true, duration_ms: 0, summary: "would: gstack-brain-sync --discover-new --once" };
+  }
+
+  const brainSyncPath = join(import.meta.dir, "gstack-brain-sync");
+  if (!existsSync(brainSyncPath)) {
+    return { name: "brain-sync", ran: false, ok: true, duration_ms: 0, summary: "skipped (gstack-brain-sync not installed)" };
+  }
+
+  spawnSync(brainSyncPath, ["--discover-new"], {
+    stdio: args.quiet ? ["ignore", "ignore", "ignore"] : ["ignore", "inherit", "inherit"],
+    timeout: 60 * 1000,
+  });
+  const result = spawnSync(brainSyncPath, ["--once"], {
+    stdio: args.quiet ? ["ignore", "ignore", "ignore"] : ["ignore", "inherit", "inherit"],
+    timeout: 60 * 1000,
+  });
+
+  return {
+    name: "brain-sync",
+    ran: true,
+    ok: result.status === 0,
+    duration_ms: Date.now() - t0,
+    summary: result.status === 0 ? "curated artifacts pushed" : `gstack-brain-sync exited ${result.status}`,
+  };
+}
+
+// ── State file ─────────────────────────────────────────────────────────────
+
+interface SyncState {
+  schema_version: 1;
+  last_writer: string;
+  last_sync?: string;
+  last_full_sync?: string;
+  last_stages?: StageResult[];
+}
+
+function loadSyncState(): SyncState {
+  if (!existsSync(STATE_PATH)) {
+    return { schema_version: 1, last_writer: "gstack-gbrain-sync" };
+  }
+  try {
+    const raw = JSON.parse(readFileSync(STATE_PATH, "utf-8")) as SyncState;
+    if (raw.schema_version === 1) return raw;
+  } catch {
+    // fall through
+  }
+  return { schema_version: 1, last_writer: "gstack-gbrain-sync" };
+}
+
+/**
+ * Atomic state file write per /plan-eng-review D1: write tmp file then rename.
+ * rename(2) is atomic on POSIX filesystems.
+ */
+function saveSyncState(state: SyncState): void {
+  try {
+    mkdirSync(dirname(STATE_PATH), { recursive: true });
+    const tmp = `${STATE_PATH}.tmp.${process.pid}`;
+    writeFileSync(tmp, JSON.stringify(state, null, 2), "utf-8");
+    renameSync(tmp, STATE_PATH);
+  } catch {
+    // non-fatal
+  }
+}
+
+// ── Output ─────────────────────────────────────────────────────────────────
+
+function formatStage(s: StageResult): string {
+  const status = !s.ran ? "SKIP" : s.ok ? "OK" : "ERR";
+  const dur = s.duration_ms > 0 ? ` (${(s.duration_ms / 1000).toFixed(1)}s)` : "";
+  return `  ${status.padEnd(5)} ${s.name.padEnd(12)} ${s.summary}${dur}`;
+}
+
+// ── Main ───────────────────────────────────────────────────────────────────
+
+async function main(): Promise<void> {
+  const args = parseArgs();
+
+  if (!args.quiet) {
+    const engine = detectEngineTier();
+    console.error(`[gbrain-sync] mode=${args.mode} engine=${engine.engine}`);
+  }
+
+  // Acquire lock (skip on dry-run since dry-run never writes).
+  const needsLock = args.mode !== "dry-run";
+  let haveLock = false;
+  if (needsLock) {
+    haveLock = acquireLock();
+    if (!haveLock) {
+      console.error(
+        `[gbrain-sync] another /sync-gbrain is running (lock at ${LOCK_PATH}). ` +
+        `If that process died, the lock auto-clears after 5 min, or remove it manually.`
+      );
+      process.exit(2);
+    }
+  }
+
+  const cleanup = () => {
+    if (haveLock) releaseLock();
+  };
+  process.on("SIGINT", () => { cleanup(); process.exit(130); });
+  process.on("SIGTERM", () => { cleanup(); process.exit(143); });
+
+  let exitCode = 0;
+  try {
+    const state = loadSyncState();
+    const stages: StageResult[] = [];
+
+    if (!args.noCode) {
+      stages.push(await withErrorContext("sync:code", () => runCodeImport(args), "gstack-gbrain-sync"));
+    }
+    if (!args.noMemory) {
+      stages.push(await withErrorContext("sync:memory", () => runMemoryIngest(args), "gstack-gbrain-sync"));
+    }
+    if (!args.noBrainSync) {
+      stages.push(await withErrorContext("sync:brain-sync", () => runBrainSyncPush(args), "gstack-gbrain-sync"));
+    }
+
+    if (args.mode !== "dry-run") {
+      state.last_sync = new Date().toISOString();
+      if (args.mode === "full") state.last_full_sync = state.last_sync;
+      state.last_stages = stages;
+      saveSyncState(state);
+    }
+
+    if (!args.quiet || args.mode === "dry-run") {
+      console.log(`\ngstack-gbrain-sync (${args.mode}):`);
+      for (const s of stages) console.log(formatStage(s));
+      const okCount = stages.filter((s) => s.ok).length;
+      const errCount = stages.filter((s) => !s.ok && s.ran).length;
+      console.log(`\n  ${okCount} ok, ${errCount} error, ${stages.length - okCount - errCount} skipped`);
+    }
+
+    const anyError = stages.some((s) => s.ran && !s.ok);
+    exitCode = anyError ? 1 : 0;
+  } finally {
+    cleanup();
+  }
+
+  process.exit(exitCode);
+}
+
+if (import.meta.main) {
+  main().catch((err) => {
+    console.error(`gstack-gbrain-sync fatal: ${err instanceof Error ? err.message : String(err)}`);
+    releaseLock();
+    process.exit(1);
+  });
+}

bin/gstack-global-discover.ts

@@ -0,0 +1,602 @@
+#!/usr/bin/env bun
+/**
+ * gstack-global-discover — Discover AI coding sessions across Claude Code, Codex CLI, and Gemini CLI.
+ * Resolves each session's working directory to a git repo, deduplicates by normalized remote URL,
+ * and outputs structured JSON to stdout.
+ *
+ * Usage:
+ *   gstack-global-discover --since 7d [--format json|summary]
+ *   gstack-global-discover --help
+ */
+
+import { existsSync, readdirSync, statSync, readFileSync, openSync, readSync, closeSync } from "fs";
+import { join, basename } from "path";
+import { execSync } from "child_process";
+import { homedir } from "os";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+interface Session {
+  tool: "claude_code" | "codex" | "gemini";
+  cwd: string;
+}
+
+interface Repo {
+  name: string;
+  remote: string;
+  paths: string[];
+  sessions: { claude_code: number; codex: number; gemini: number };
+}
+
+interface DiscoveryResult {
+  window: string;
+  start_date: string;
+  repos: Repo[];
+  tools: {
+    claude_code: { total_sessions: number; repos: number };
+    codex: { total_sessions: number; repos: number };
+    gemini: { total_sessions: number; repos: number };
+  };
+  total_sessions: number;
+  total_repos: number;
+}
+
+// ── CLI parsing ────────────────────────────────────────────────────────────
+
+function printUsage(): void {
+  console.error(`Usage: gstack-global-discover --since <window> [--format json|summary]
+
+  --since <window>   Time window: e.g. 7d, 14d, 30d, 24h
+  --format <fmt>     Output format: json (default) or summary
+  --help             Show this help
+
+Examples:
+  gstack-global-discover --since 7d
+  gstack-global-discover --since 14d --format summary`);
+}
+
+function parseArgs(): { since: string; format: "json" | "summary" } {
+  const args = process.argv.slice(2);
+  let since = "";
+  let format: "json" | "summary" = "json";
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--help" || args[i] === "-h") {
+      printUsage();
+      process.exit(0);
+    } else if (args[i] === "--since" && args[i + 1]) {
+      since = args[++i];
+    } else if (args[i] === "--format" && args[i + 1]) {
+      const f = args[++i];
+      if (f !== "json" && f !== "summary") {
+        console.error(`Invalid format: ${f}. Use 'json' or 'summary'.`);
+        printUsage();
+        process.exit(1);
+      }
+      format = f;
+    } else {
+      console.error(`Unknown argument: ${args[i]}`);
+      printUsage();
+      process.exit(1);
+    }
+  }
+
+  if (!since) {
+    console.error("Error: --since is required.");
+    printUsage();
+    process.exit(1);
+  }
+
+  if (!/^\d+(d|h|w)$/.test(since)) {
+    console.error(`Invalid window format: ${since}. Use e.g. 7d, 24h, 2w.`);
+    process.exit(1);
+  }
+
+  return { since, format };
+}
+
+function windowToDate(window: string): Date {
+  const match = window.match(/^(\d+)(d|h|w)$/);
+  if (!match) throw new Error(`Invalid window: ${window}`);
+  const [, numStr, unit] = match;
+  const num = parseInt(numStr, 10);
+  const now = new Date();
+
+  if (unit === "h") {
+    return new Date(now.getTime() - num * 60 * 60 * 1000);
+  } else if (unit === "w") {
+    // weeks — midnight-aligned like days
+    const d = new Date(now);
+    d.setDate(d.getDate() - num * 7);
+    d.setHours(0, 0, 0, 0);
+    return d;
+  } else {
+    // days — midnight-aligned
+    const d = new Date(now);
+    d.setDate(d.getDate() - num);
+    d.setHours(0, 0, 0, 0);
+    return d;
+  }
+}
+
+// ── URL normalization ──────────────────────────────────────────────────────
+
+export function normalizeRemoteUrl(url: string): string {
+  let normalized = url.trim();
+
+  // SSH → HTTPS: git@github.com:user/repo → https://github.com/user/repo
+  const sshMatch = normalized.match(/^(?:ssh:\/\/)?git@([^:]+):(.+)$/);
+  if (sshMatch) {
+    normalized = `https://${sshMatch[1]}/${sshMatch[2]}`;
+  }
+
+  // Strip .git suffix
+  if (normalized.endsWith(".git")) {
+    normalized = normalized.slice(0, -4);
+  }
+
+  // Lowercase the host portion
+  try {
+    const parsed = new URL(normalized);
+    parsed.hostname = parsed.hostname.toLowerCase();
+    normalized = parsed.toString();
+    // Remove trailing slash
+    if (normalized.endsWith("/")) {
+      normalized = normalized.slice(0, -1);
+    }
+  } catch {
+    // Not a valid URL (e.g., local:<path>), return as-is
+  }
+
+  return normalized;
+}
+
+// ── Git helpers ────────────────────────────────────────────────────────────
+
+function isGitRepo(dir: string): boolean {
+  return existsSync(join(dir, ".git"));
+}
+
+function getGitRemote(cwd: string): string | null {
+  if (!existsSync(cwd) || !isGitRepo(cwd)) return null;
+  try {
+    const remote = execSync("git remote get-url origin", {
+      cwd,
+      encoding: "utf-8",
+      timeout: 5000,
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+    return remote || null;
+  } catch (err: any) {
+    // Expected: no remote configured, repo not found, git not installed
+    if (err?.status !== undefined) return null; // non-zero exit from git
+    if (err?.code === 'ENOENT') return null;    // git binary not found
+    throw err;
+  }
+}
+
+// ── Scanners ───────────────────────────────────────────────────────────────
+
+function scanClaudeCode(since: Date): Session[] {
+  const projectsDir = join(homedir(), ".claude", "projects");
+  if (!existsSync(projectsDir)) return [];
+
+  const sessions: Session[] = [];
+
+  let dirs: string[];
+  try {
+    dirs = readdirSync(projectsDir);
+  } catch (err: any) {
+    if (err?.code === 'ENOENT' || err?.code === 'EACCES') return [];
+    throw err;
+  }
+
+  for (const dirName of dirs) {
+    const dirPath = join(projectsDir, dirName);
+    try {
+      const stat = statSync(dirPath);
+      if (!stat.isDirectory()) continue;
+    } catch {
+      continue;
+    }
+
+    // Find JSONL files
+    let jsonlFiles: string[];
+    try {
+      jsonlFiles = readdirSync(dirPath).filter((f) => f.endsWith(".jsonl"));
+    } catch {
+      continue;
+    }
+    if (jsonlFiles.length === 0) continue;
+
+    // Coarse mtime pre-filter: check if any JSONL file is recent
+    const hasRecentFile = jsonlFiles.some((f) => {
+      try {
+        return statSync(join(dirPath, f)).mtime >= since;
+      } catch (err: any) {
+        if (err?.code === 'ENOENT' || err?.code === 'EACCES') return false;
+        throw err;
+      }
+    });
+    if (!hasRecentFile) continue;
+
+    // Resolve cwd
+    let cwd = resolveClaudeCodeCwd(dirPath, dirName, jsonlFiles);
+    if (!cwd) continue;
+
+    // Count only JSONL files modified within the window as sessions
+    const recentFiles = jsonlFiles.filter((f) => {
+      try {
+        return statSync(join(dirPath, f)).mtime >= since;
+      } catch (err: any) {
+        if (err?.code === 'ENOENT' || err?.code === 'EACCES') return false;
+        throw err;
+      }
+    });
+    for (let i = 0; i < recentFiles.length; i++) {
+      sessions.push({ tool: "claude_code", cwd });
+    }
+  }
+
+  return sessions;
+}
+
+function resolveClaudeCodeCwd(
+  dirPath: string,
+  dirName: string,
+  jsonlFiles: string[]
+): string | null {
+  // Fast-path: decode directory name
+  // e.g., -Users-garrytan-git-repo → /Users/garrytan/git/repo
+  const decoded = dirName.replace(/^-/, "/").replace(/-/g, "/");
+  if (existsSync(decoded)) return decoded;
+
+  // Fallback: read cwd from first JSONL file
+  // Sort by mtime descending, pick most recent
+  const sorted = jsonlFiles
+    .map((f) => {
+      try {
+        return { name: f, mtime: statSync(join(dirPath, f)).mtime.getTime() };
+      } catch (err: any) {
+        if (err?.code === 'ENOENT' || err?.code === 'EACCES') return null;
+        throw err;
+      }
+    })
+    .filter(Boolean)
+    .sort((a, b) => b!.mtime - a!.mtime) as { name: string; mtime: number }[];
+
+  for (const file of sorted.slice(0, 3)) {
+    const cwd = extractCwdFromJsonl(join(dirPath, file.name));
+    if (cwd && existsSync(cwd)) return cwd;
+  }
+
+  return null;
+}
+
+function extractCwdFromJsonl(filePath: string): string | null {
+  try {
+    // Read only the first 8KB to avoid loading huge JSONL files into memory
+    const fd = openSync(filePath, "r");
+    const buf = Buffer.alloc(8192);
+    const bytesRead = readSync(fd, buf, 0, 8192, 0);
+    closeSync(fd);
+    const text = buf.toString("utf-8", 0, bytesRead);
+    const lines = text.split("\n").slice(0, 15);
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      try {
+        const obj = JSON.parse(line);
+        if (obj.cwd) return obj.cwd;
+      } catch {
+        continue;
+      }
+    }
+  } catch {
+    // File read error
+  }
+  return null;
+}
+
+function scanCodex(since: Date): Session[] {
+  const sessionsDir = process.env.CODEX_SESSIONS_DIR || join(homedir(), ".codex", "sessions");
+  if (!existsSync(sessionsDir)) return [];
+
+  const sessions: Session[] = [];
+
+  // Walk YYYY/MM/DD directory structure
+  try {
+    const years = readdirSync(sessionsDir);
+    for (const year of years) {
+      const yearPath = join(sessionsDir, year);
+      if (!statSync(yearPath).isDirectory()) continue;
+
+      const months = readdirSync(yearPath);
+      for (const month of months) {
+        const monthPath = join(yearPath, month);
+        if (!statSync(monthPath).isDirectory()) continue;
+
+        const days = readdirSync(monthPath);
+        for (const day of days) {
+          const dayPath = join(monthPath, day);
+          if (!statSync(dayPath).isDirectory()) continue;
+
+          const files = readdirSync(dayPath).filter((f) =>
+            f.startsWith("rollout-") && f.endsWith(".jsonl")
+          );
+
+          for (const file of files) {
+            const filePath = join(dayPath, file);
+            try {
+              const stat = statSync(filePath);
+              if (stat.mtime < since) continue;
+            } catch {
+              continue;
+            }
+
+            // Codex session_meta lines embed the full system prompt in
+            // base_instructions (~15KB as of CLI v0.117+). A 4KB buffer
+            // truncates the line and JSON.parse fails. 128KB covers current
+            // sizes with room for growth.
+            try {
+              const fd = openSync(filePath, "r");
+              const buf = Buffer.alloc(131072);
+              const bytesRead = readSync(fd, buf, 0, 131072, 0);
+              closeSync(fd);
+              const firstLine = buf.toString("utf-8", 0, bytesRead).split("\n")[0];
+              if (!firstLine) continue;
+              const meta = JSON.parse(firstLine);
+              if (meta.type === "session_meta" && meta.payload?.cwd) {
+                sessions.push({ tool: "codex", cwd: meta.payload.cwd });
+              }
+            } catch {
+              console.error(`Warning: could not parse Codex session ${filePath}`);
+            }
+          }
+        }
+      }
+    }
+  } catch {
+    // Directory read error
+  }
+
+  return sessions;
+}
+
+function scanGemini(since: Date): Session[] {
+  const tmpDir = join(homedir(), ".gemini", "tmp");
+  if (!existsSync(tmpDir)) return [];
+
+  // Load projects.json for path mapping
+  const projectsPath = join(homedir(), ".gemini", "projects.json");
+  let projectsMap: Record<string, string> = {}; // name → path
+  if (existsSync(projectsPath)) {
+    try {
+      const data = JSON.parse(readFileSync(projectsPath, { encoding: "utf-8" }));
+      // Format: { projects: { "/path": "name" } } — we want name → path
+      const projects = data.projects || {};
+      for (const [path, name] of Object.entries(projects)) {
+        projectsMap[name as string] = path;
+      }
+    } catch {
+      console.error("Warning: could not parse ~/.gemini/projects.json");
+    }
+  }
+
+  const sessions: Session[] = [];
+  const seenTimestamps = new Map<string, Set<string>>(); // projectName → Set<startTime>
+
+  let projectDirs: string[];
+  try {
+    projectDirs = readdirSync(tmpDir);
+  } catch (err: any) {
+    if (err?.code === 'ENOENT' || err?.code === 'EACCES') return [];
+    throw err;
+  }
+
+  for (const projectName of projectDirs) {
+    const chatsDir = join(tmpDir, projectName, "chats");
+    if (!existsSync(chatsDir)) continue;
+
+    // Resolve cwd from projects.json
+    let cwd = projectsMap[projectName] || null;
+
+    // Fallback: check .project_root
+    if (!cwd) {
+      const projectRootFile = join(tmpDir, projectName, ".project_root");
+      if (existsSync(projectRootFile)) {
+        try {
+          cwd = readFileSync(projectRootFile, { encoding: "utf-8" }).trim();
+        } catch {}
+      }
+    }
+
+    if (!cwd || !existsSync(cwd)) continue;
+
+    const seen = seenTimestamps.get(projectName) || new Set<string>();
+    seenTimestamps.set(projectName, seen);
+
+    let files: string[];
+    try {
+      files = readdirSync(chatsDir).filter((f) =>
+        f.startsWith("session-") && f.endsWith(".json")
+      );
+    } catch {
+      continue;
+    }
+
+    for (const file of files) {
+      const filePath = join(chatsDir, file);
+      try {
+        const stat = statSync(filePath);
+        if (stat.mtime < since) continue;
+      } catch {
+        continue;
+      }
+
+      try {
+        const data = JSON.parse(readFileSync(filePath, { encoding: "utf-8" }));
+        const startTime = data.startTime || "";
+
+        // Deduplicate by startTime within project
+        if (startTime && seen.has(startTime)) continue;
+        if (startTime) seen.add(startTime);
+
+        sessions.push({ tool: "gemini", cwd });
+      } catch {
+        console.error(`Warning: could not parse Gemini session ${filePath}`);
+      }
+    }
+  }
+
+  return sessions;
+}
+
+// ── Deduplication ──────────────────────────────────────────────────────────
+
+async function resolveAndDeduplicate(sessions: Session[]): Promise<Repo[]> {
+  // Group sessions by cwd
+  const byCwd = new Map<string, Session[]>();
+  for (const s of sessions) {
+    const existing = byCwd.get(s.cwd) || [];
+    existing.push(s);
+    byCwd.set(s.cwd, existing);
+  }
+
+  // Resolve git remotes for each cwd
+  const cwds = Array.from(byCwd.keys());
+  const remoteMap = new Map<string, string>(); // cwd → normalized remote
+
+  for (const cwd of cwds) {
+    const raw = getGitRemote(cwd);
+    if (raw) {
+      remoteMap.set(cwd, normalizeRemoteUrl(raw));
+    } else if (existsSync(cwd) && isGitRepo(cwd)) {
+      remoteMap.set(cwd, `local:${cwd}`);
+    }
+  }
+
+  // Group by normalized remote
+  const byRemote = new Map<string, { paths: string[]; sessions: Session[] }>();
+  for (const [cwd, cwdSessions] of byCwd) {
+    const remote = remoteMap.get(cwd);
+    if (!remote) continue;
+
+    const existing = byRemote.get(remote) || { paths: [], sessions: [] };
+    if (!existing.paths.includes(cwd)) existing.paths.push(cwd);
+    existing.sessions.push(...cwdSessions);
+    byRemote.set(remote, existing);
+  }
+
+  // Build Repo objects
+  const repos: Repo[] = [];
+  for (const [remote, data] of byRemote) {
+    // Find first valid path
+    const validPath = data.paths.find((p) => existsSync(p) && isGitRepo(p));
+    if (!validPath) continue;
+
+    // Derive name from remote URL
+    let name: string;
+    if (remote.startsWith("local:")) {
+      name = basename(remote.replace("local:", ""));
+    } else {
+      try {
+        const url = new URL(remote);
+        name = basename(url.pathname);
+      } catch {
+        name = basename(remote);
+      }
+    }
+
+    const sessionCounts = { claude_code: 0, codex: 0, gemini: 0 };
+    for (const s of data.sessions) {
+      sessionCounts[s.tool]++;
+    }
+
+    repos.push({
+      name,
+      remote,
+      paths: data.paths,
+      sessions: sessionCounts,
+    });
+  }
+
+  // Sort by total sessions descending
+  repos.sort(
+    (a, b) =>
+      b.sessions.claude_code + b.sessions.codex + b.sessions.gemini -
+      (a.sessions.claude_code + a.sessions.codex + a.sessions.gemini)
+  );
+
+  return repos;
+}
+
+// ── Main ───────────────────────────────────────────────────────────────────
+
+async function main() {
+  const { since, format } = parseArgs();
+  const sinceDate = windowToDate(since);
+  const startDate = sinceDate.toISOString().split("T")[0];
+
+  // Run all scanners
+  const ccSessions = scanClaudeCode(sinceDate);
+  const codexSessions = scanCodex(sinceDate);
+  const geminiSessions = scanGemini(sinceDate);
+
+  const allSessions = [...ccSessions, ...codexSessions, ...geminiSessions];
+
+  // Summary to stderr
+  console.error(
+    `Discovered: ${ccSessions.length} CC sessions, ${codexSessions.length} Codex sessions, ${geminiSessions.length} Gemini sessions`
+  );
+
+  // Deduplicate
+  const repos = await resolveAndDeduplicate(allSessions);
+
+  console.error(`→ ${repos.length} unique repos`);
+
+  // Count per-tool repo counts
+  const ccRepos = new Set(repos.filter((r) => r.sessions.claude_code > 0).map((r) => r.remote)).size;
+  const codexRepos = new Set(repos.filter((r) => r.sessions.codex > 0).map((r) => r.remote)).size;
+  const geminiRepos = new Set(repos.filter((r) => r.sessions.gemini > 0).map((r) => r.remote)).size;
+
+  const result: DiscoveryResult = {
+    window: since,
+    start_date: startDate,
+    repos,
+    tools: {
+      claude_code: { total_sessions: ccSessions.length, repos: ccRepos },
+      codex: { total_sessions: codexSessions.length, repos: codexRepos },
+      gemini: { total_sessions: geminiSessions.length, repos: geminiRepos },
+    },
+    total_sessions: allSessions.length,
+    total_repos: repos.length,
+  };
+
+  if (format === "json") {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    // Summary format
+    console.log(`Window: ${since} (since ${startDate})`);
+    console.log(`Sessions: ${allSessions.length} total (CC: ${ccSessions.length}, Codex: ${codexSessions.length}, Gemini: ${geminiSessions.length})`);
+    console.log(`Repos: ${repos.length} unique`);
+    console.log("");
+    for (const repo of repos) {
+      const total = repo.sessions.claude_code + repo.sessions.codex + repo.sessions.gemini;
+      const tools = [];
+      if (repo.sessions.claude_code > 0) tools.push(`CC:${repo.sessions.claude_code}`);
+      if (repo.sessions.codex > 0) tools.push(`Codex:${repo.sessions.codex}`);
+      if (repo.sessions.gemini > 0) tools.push(`Gemini:${repo.sessions.gemini}`);
+      console.log(`  ${repo.name} (${total} sessions) — ${tools.join(", ")}`);
+      console.log(`    Remote: ${repo.remote}`);
+      console.log(`    Paths: ${repo.paths.join(", ")}`);
+    }
+  }
+}
+
+// Only run main when executed directly (not when imported for testing)
+if (import.meta.main) {
+  main().catch((err) => {
+    console.error(`Fatal error: ${err.message}`);
+    process.exit(1);
+  });
+}

bin/gstack-jsonl-merge

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+# gstack-jsonl-merge — git merge driver for append-only JSONL files.
+#
+# Usage (called by git, not by users):
+#   gstack-jsonl-merge <base> <ours> <theirs>
+#
+# Registered in local git config by bin/gstack-artifacts-init and
+# bin/gstack-brain-restore:
+#   git config merge.jsonl-append.driver \
+#       "$GSTACK_BIN/gstack-jsonl-merge %O %A %B"
+#
+# Behavior:
+#   Concatenate base + ours + theirs, dedup exact-duplicate lines, sort by
+#   ISO "ts" field when present, fall back to SHA-256 of the line for
+#   deterministic order. Write result to <ours> (the %A file per the git
+#   merge-driver contract).
+#
+#   Two machines appending to the same JSONL file between pushes produces
+#   a same-line conflict at the file tail. This driver resolves it cleanly:
+#   both appends survive, ordered by wall-clock timestamp where available,
+#   content hash otherwise.
+#
+# Exit codes:
+#   0 — merge succeeded, result written to <ours>
+#   1 — error; git treats as conflict and stops the merge
+
+set -uo pipefail
+
+if [ "$#" -lt 3 ]; then
+  echo "gstack-jsonl-merge: expected 3 args (base ours theirs), got $#" >&2
+  exit 1
+fi
+
+BASE="$1"
+OURS="$2"
+THEIRS="$3"
+
+TMP=$(mktemp /tmp/gstack-jsonl-merge.XXXXXX) || exit 1
+trap 'rm -f "$TMP" 2>/dev/null || true' EXIT
+
+python3 - "$BASE" "$OURS" "$THEIRS" > "$TMP" <<'PYEOF'
+import sys, json, hashlib
+
+paths = sys.argv[1:4]  # base, ours, theirs
+seen = {}  # line content -> sort_key
+
+for path in paths:
+    try:
+        with open(path, 'r', encoding='utf-8') as f:
+            for line in f:
+                line = line.rstrip('\n')
+                if not line:
+                    continue
+                if line in seen:
+                    continue
+                # Prefer ISO ts field for sort; fall back to SHA-256.
+                sort_key = None
+                try:
+                    obj = json.loads(line)
+                    ts = obj.get('ts') or obj.get('timestamp')
+                    if isinstance(ts, str):
+                        sort_key = (0, ts)
+                except (json.JSONDecodeError, ValueError, TypeError):
+                    pass
+                if sort_key is None:
+                    h = hashlib.sha256(line.encode('utf-8')).hexdigest()
+                    sort_key = (1, h)
+                seen[line] = sort_key
+    except FileNotFoundError:
+        # Absent base / absent ours / absent theirs are all valid.
+        continue
+    except OSError:
+        # Permission / IO errors are fatal — caller sees non-zero exit.
+        sys.exit(1)
+
+# Timestamp-ordered entries first (group 0), then hash-ordered (group 1).
+for line, _ in sorted(seen.items(), key=lambda item: item[1]):
+    print(line)
+PYEOF
+
+_PYEXIT=$?
+if [ "$_PYEXIT" != "0" ]; then
+  exit 1
+fi
+
+mv "$TMP" "$OURS" || exit 1
+trap - EXIT
+exit 0

bin/gstack-learnings-log

@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+# gstack-learnings-log — append a learning to the project learnings file
+# Usage: gstack-learnings-log '{"skill":"review","type":"pitfall","key":"n-plus-one","insight":"...","confidence":8,"source":"observed"}'
+# Valid types: pattern, pitfall, preference, architecture, tool, operational, investigation
+#
+# Append-only storage. Duplicates (same key+type) are resolved at read time
+# by gstack-learnings-search ("latest winner" per key+type).
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+eval "$("$SCRIPT_DIR/gstack-slug" 2>/dev/null)"
+GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
+mkdir -p "$GSTACK_HOME/projects/$SLUG"
+
+INPUT="$1"
+
+# Validate and sanitize input
+VALIDATED=$(printf '%s' "$INPUT" | bun -e "
+const raw = await Bun.stdin.text();
+let j;
+try { j = JSON.parse(raw); } catch { process.stderr.write('gstack-learnings-log: invalid JSON, skipping\n'); process.exit(1); }
+
+// Field validation: type must be from allowed list
+const ALLOWED_TYPES = ['pattern', 'pitfall', 'preference', 'architecture', 'tool', 'operational', 'investigation'];
+if (!j.type || !ALLOWED_TYPES.includes(j.type)) {
+  process.stderr.write('gstack-learnings-log: invalid type \"' + (j.type || '') + '\", must be one of: ' + ALLOWED_TYPES.join(', ') + '\n');
+  process.exit(1);
+}
+
+// Field validation: key must be alphanumeric, hyphens, underscores (no injection surface)
+if (!j.key || !/^[a-zA-Z0-9_-]+$/.test(j.key)) {
+  process.stderr.write('gstack-learnings-log: invalid key, must be alphanumeric with hyphens/underscores only\n');
+  process.exit(1);
+}
+
+// Field validation: confidence must be 1-10
+const conf = Number(j.confidence);
+if (!Number.isInteger(conf) || conf < 1 || conf > 10) {
+  process.stderr.write('gstack-learnings-log: confidence must be integer 1-10\n');
+  process.exit(1);
+}
+j.confidence = conf;
+
+// Field validation: source must be from allowed list
+const ALLOWED_SOURCES = ['observed', 'user-stated', 'inferred', 'cross-model'];
+if (j.source && !ALLOWED_SOURCES.includes(j.source)) {
+  process.stderr.write('gstack-learnings-log: invalid source, must be one of: ' + ALLOWED_SOURCES.join(', ') + '\n');
+  process.exit(1);
+}
+
+// Content sanitization: strip instruction-like patterns from insight field
+// These patterns could be used for prompt injection when learnings are loaded into agent context
+if (j.insight) {
+  const INJECTION_PATTERNS = [
+    /ignore\s+(all\s+)?previous\s+(instructions|context|rules)/i,
+    /you\s+are\s+now\s+/i,
+    /always\s+output\s+no\s+findings/i,
+    /skip\s+(all\s+)?(security|review|checks)/i,
+    /override[:\s]/i,
+    /\bsystem\s*:/i,
+    /\bassistant\s*:/i,
+    /\buser\s*:/i,
+    /do\s+not\s+(report|flag|mention)/i,
+    /approve\s+(all|every|this)/i,
+  ];
+  for (const pat of INJECTION_PATTERNS) {
+    if (pat.test(j.insight)) {
+      process.stderr.write('gstack-learnings-log: insight contains suspicious instruction-like content, rejected\n');
+      process.exit(1);
+    }
+  }
+}
+
+// Inject timestamp if not present
+if (!j.ts) j.ts = new Date().toISOString();
+
+// Mark trust level based on source
+// user-stated = user explicitly told the agent this. All others are AI-generated.
+j.trusted = j.source === 'user-stated';
+
+console.log(JSON.stringify(j));
+" 2>/dev/null)
+
+if [ $? -ne 0 ] || [ -z "$VALIDATED" ]; then
+  exit 1
+fi
+
+echo "$VALIDATED" >> "$GSTACK_HOME/projects/$SLUG/learnings.jsonl"
+
+# gbrain-sync: enqueue for cross-machine sync (no-op if sync is off).
+"$SCRIPT_DIR/gstack-brain-enqueue" "projects/$SLUG/learnings.jsonl" 2>/dev/null &

bin/gstack-learnings-search

@@ -0,0 +1,138 @@
+#!/usr/bin/env bash
+# gstack-learnings-search — read and filter project learnings
+# Usage: gstack-learnings-search [--type TYPE] [--query KEYWORD] [--limit N] [--cross-project]
+#
+# Reads ~/.gstack/projects/$SLUG/learnings.jsonl, applies confidence decay,
+# resolves duplicates (latest winner per key+type), and outputs formatted text.
+# Exit 0 silently if no learnings file exists.
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+eval "$("$SCRIPT_DIR/gstack-slug" 2>/dev/null)"
+GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
+
+TYPE=""
+QUERY=""
+LIMIT=10
+CROSS_PROJECT=false
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --type) TYPE="$2"; shift 2 ;;
+    --query) QUERY="$2"; shift 2 ;;
+    --limit) LIMIT="$2"; shift 2 ;;
+    --cross-project) CROSS_PROJECT=true; shift ;;
+    *) shift ;;
+  esac
+done
+
+LEARNINGS_FILE="$GSTACK_HOME/projects/$SLUG/learnings.jsonl"
+
+# Collect all JSONL files to search
+FILES=()
+[ -f "$LEARNINGS_FILE" ] && FILES+=("$LEARNINGS_FILE")
+
+if [ "$CROSS_PROJECT" = true ]; then
+  # Add other projects' learnings (max 5, sorted by mtime)
+  for f in $(find "$GSTACK_HOME/projects" -name "learnings.jsonl" -not -path "*/$SLUG/*" 2>/dev/null | head -5); do
+    FILES+=("$f")
+  done
+fi
+
+if [ ${#FILES[@]} -eq 0 ]; then
+  exit 0
+fi
+
+# Process all files through bun for JSON parsing, decay, dedup, filtering
+GSTACK_SEARCH_TYPE="$TYPE" GSTACK_SEARCH_QUERY="$QUERY" GSTACK_SEARCH_LIMIT="$LIMIT" GSTACK_SEARCH_SLUG="$SLUG" GSTACK_SEARCH_CROSS="$CROSS_PROJECT" \
+cat "${FILES[@]}" 2>/dev/null | GSTACK_SEARCH_TYPE="$TYPE" GSTACK_SEARCH_QUERY="$QUERY" GSTACK_SEARCH_LIMIT="$LIMIT" GSTACK_SEARCH_SLUG="$SLUG" GSTACK_SEARCH_CROSS="$CROSS_PROJECT" bun -e "
+const lines = (await Bun.stdin.text()).trim().split('\n').filter(Boolean);
+const now = Date.now();
+const type = process.env.GSTACK_SEARCH_TYPE || '';
+const queryRaw = (process.env.GSTACK_SEARCH_QUERY || '').toLowerCase();
+const queryTokens = queryRaw.split(/\s+/).filter(Boolean);
+const limit = parseInt(process.env.GSTACK_SEARCH_LIMIT || '10', 10);
+const slug = process.env.GSTACK_SEARCH_SLUG || '';
+
+const entries = [];
+for (const line of lines) {
+  try {
+    const e = JSON.parse(line);
+    if (!e.key || !e.type) continue;
+
+    // Apply confidence decay: observed/inferred lose 1pt per 30 days
+    let conf = e.confidence || 5;
+    if (e.source === 'observed' || e.source === 'inferred') {
+      const days = Math.floor((now - new Date(e.ts).getTime()) / 86400000);
+      conf = Math.max(0, conf - Math.floor(days / 30));
+    }
+    e._effectiveConfidence = conf;
+
+    // Determine if this is from the current project or cross-project
+    // Cross-project entries are tagged for display
+    const isCrossProject = !line.includes(slug) && process.env.GSTACK_SEARCH_CROSS === 'true';
+    e._crossProject = isCrossProject;
+
+    // Trust gate: cross-project learnings only loaded if trusted (user-stated)
+    // This prevents prompt injection from one project's AI-generated learnings
+    // silently influencing reviews in another project.
+    if (isCrossProject && e.trusted === false) continue;
+
+    entries.push(e);
+  } catch {}
+}
+
+// Dedup: latest winner per key+type
+const seen = new Map();
+for (const e of entries) {
+  const dk = e.key + '|' + e.type;
+  const existing = seen.get(dk);
+  if (!existing || new Date(e.ts) > new Date(existing.ts)) {
+    seen.set(dk, e);
+  }
+}
+let results = Array.from(seen.values());
+
+// Filter by type
+if (type) results = results.filter(e => e.type === type);
+
+// Filter by query (token-OR: match if ANY whitespace-split token appears in ANY haystack)
+if (queryTokens.length > 0) results = results.filter(e => {
+  const haystacks = [(e.key || '').toLowerCase(), (e.insight || '').toLowerCase(), ...(e.files || []).map(f => f.toLowerCase())];
+  return queryTokens.some(tok => haystacks.some(h => h.includes(tok)));
+});
+
+// Sort by effective confidence desc, then recency
+results.sort((a, b) => {
+  if (b._effectiveConfidence !== a._effectiveConfidence) return b._effectiveConfidence - a._effectiveConfidence;
+  return new Date(b.ts).getTime() - new Date(a.ts).getTime();
+});
+
+// Limit
+results = results.slice(0, limit);
+
+if (results.length === 0) process.exit(0);
+
+// Format output
+const byType = {};
+for (const e of results) {
+  const t = e.type || 'unknown';
+  if (!byType[t]) byType[t] = [];
+  byType[t].push(e);
+}
+
+// Summary line
+const counts = Object.entries(byType).map(([t, arr]) => arr.length + ' ' + t + (arr.length > 1 ? 's' : ''));
+console.log('LEARNINGS: ' + results.length + ' loaded (' + counts.join(', ') + ')');
+console.log('');
+
+for (const [t, arr] of Object.entries(byType)) {
+  console.log('## ' + t.charAt(0).toUpperCase() + t.slice(1) + 's');
+  for (const e of arr) {
+    const cross = e._crossProject ? ' [cross-project]' : '';
+    const files = e.files?.length ? ' (files: ' + e.files.join(', ') + ')' : '';
+    console.log('- [' + e.key + '] (confidence: ' + e._effectiveConfidence + '/10, ' + e.source + ', ' + (e.ts || '').split('T')[0] + ')' + cross);
+    console.log('  ' + e.insight + files);
+  }
+  console.log('');
+}
+" 2>/dev/null || exit 0

bin/gstack-model-benchmark

@@ -0,0 +1,169 @@
+#!/usr/bin/env bun
+/**
+ * gstack-model-benchmark — run the same prompt across multiple providers
+ * and compare latency, tokens, cost, quality, and tool-call count.
+ *
+ * Usage:
+ *   gstack-model-benchmark <skill-or-prompt-file> [options]
+ *
+ * Options:
+ *   --models claude,gpt,gemini   Comma-separated provider list (default: claude)
+ *   --prompt "<text>"            Inline prompt instead of a file
+ *   --workdir <path>             Working dir passed to each CLI (default: cwd)
+ *   --timeout-ms <n>             Per-provider timeout (default: 300000)
+ *   --output table|json|markdown Output format (default: table)
+ *   --skip-unavailable           Skip providers that fail available() check
+ *                                (default: include them with unavailable marker)
+ *   --judge                      Run Anthropic SDK judge on outputs for quality score
+ *                                (requires ANTHROPIC_API_KEY; adds ~$0.05 per call)
+ *   --dry-run                    Validate flags + resolve auth, don't invoke providers
+ *
+ * Examples:
+ *   gstack-model-benchmark --prompt "Write a haiku about databases" --models claude,gpt
+ *   gstack-model-benchmark ./test-prompt.txt --models claude,gpt,gemini --judge
+ *   gstack-model-benchmark --prompt "hi" --models claude,gpt,gemini --dry-run
+ */
+
+import '../lib/conductor-env-shim';
+import * as fs from 'fs';
+import * as path from 'path';
+import { runBenchmark, formatTable, formatJson, formatMarkdown, type BenchmarkInput } from '../test/helpers/benchmark-runner';
+import { ClaudeAdapter } from '../test/helpers/providers/claude';
+import { GptAdapter } from '../test/helpers/providers/gpt';
+import { GeminiAdapter } from '../test/helpers/providers/gemini';
+
+const ADAPTER_FACTORIES = {
+  claude: () => new ClaudeAdapter(),
+  gpt: () => new GptAdapter(),
+  gemini: () => new GeminiAdapter(),
+};
+
+type OutputFormat = 'table' | 'json' | 'markdown';
+
+function arg(name: string, def?: string): string | undefined {
+  const idx = process.argv.findIndex(a => a === name || a.startsWith(name + '='));
+  if (idx < 0) return def;
+  const eqIdx = process.argv[idx].indexOf('=');
+  if (eqIdx >= 0) return process.argv[idx].slice(eqIdx + 1);
+  return process.argv[idx + 1];
+}
+
+function flag(name: string): boolean {
+  return process.argv.includes(name);
+}
+
+function parseProviders(s: string | undefined): Array<'claude' | 'gpt' | 'gemini'> {
+  if (!s) return ['claude'];
+  const seen = new Set<'claude' | 'gpt' | 'gemini'>();
+  for (const p of s.split(',').map(x => x.trim()).filter(Boolean)) {
+    if (p === 'claude' || p === 'gpt' || p === 'gemini') seen.add(p);
+    else {
+      console.error(`WARN: unknown provider '${p}' — skipping. Valid: claude, gpt, gemini.`);
+    }
+  }
+  return seen.size ? Array.from(seen) : ['claude'];
+}
+
+function resolvePrompt(positional: string | undefined): string {
+  const inline = arg('--prompt');
+  if (inline) return inline;
+  if (!positional) {
+    console.error('ERROR: specify a prompt via positional path or --prompt "<text>"');
+    process.exit(1);
+  }
+  if (fs.existsSync(positional)) {
+    return fs.readFileSync(positional, 'utf-8');
+  }
+  // Not a file — treat as inline prompt
+  return positional;
+}
+
+async function main(): Promise<void> {
+  const positional = process.argv.slice(2).find(a => !a.startsWith('--'));
+  const prompt = resolvePrompt(positional);
+  const providers = parseProviders(arg('--models'));
+  const workdir = arg('--workdir', process.cwd())!;
+  const timeoutMs = parseInt(arg('--timeout-ms', '300000')!, 10);
+  const output = (arg('--output', 'table') as OutputFormat);
+  const skipUnavailable = flag('--skip-unavailable');
+  const doJudge = flag('--judge');
+  const dryRun = flag('--dry-run');
+
+  if (dryRun) {
+    await dryRunReport({ prompt, providers, workdir, timeoutMs, output, doJudge });
+    return;
+  }
+
+  const input: BenchmarkInput = {
+    prompt,
+    workdir,
+    providers,
+    timeoutMs,
+    skipUnavailable,
+  };
+
+  const report = await runBenchmark(input);
+
+  if (doJudge) {
+    try {
+      const { judgeEntries } = await import('../test/helpers/benchmark-judge');
+      await judgeEntries(report);
+    } catch (err) {
+      console.error(`WARN: judge unavailable: ${(err as Error).message}`);
+    }
+  }
+
+  let out: string;
+  switch (output) {
+    case 'json':     out = formatJson(report); break;
+    case 'markdown': out = formatMarkdown(report); break;
+    case 'table':
+    default:         out = formatTable(report); break;
+  }
+  process.stdout.write(out + '\n');
+}
+
+async function dryRunReport(opts: {
+  prompt: string;
+  providers: Array<'claude' | 'gpt' | 'gemini'>;
+  workdir: string;
+  timeoutMs: number;
+  output: OutputFormat;
+  doJudge: boolean;
+}): Promise<void> {
+  const lines: string[] = [];
+  lines.push('== gstack-model-benchmark --dry-run ==');
+  lines.push(`  prompt:     ${opts.prompt.length > 80 ? opts.prompt.slice(0, 80) + '…' : opts.prompt}`);
+  lines.push(`  providers:  ${opts.providers.join(', ')}`);
+  lines.push(`  workdir:    ${opts.workdir}`);
+  lines.push(`  timeout_ms: ${opts.timeoutMs}`);
+  lines.push(`  output:     ${opts.output}`);
+  lines.push(`  judge:      ${opts.doJudge ? 'on (Anthropic SDK)' : 'off'}`);
+  lines.push('');
+  lines.push('Adapter availability:');
+  let authFailures = 0;
+  for (const name of opts.providers) {
+    const factory = ADAPTER_FACTORIES[name];
+    if (!factory) {
+      lines.push(`  ${name}: UNKNOWN PROVIDER`);
+      authFailures += 1;
+      continue;
+    }
+    const adapter = factory();
+    const check = await adapter.available();
+    if (check.ok) {
+      lines.push(`  ${adapter.name}: OK`);
+    } else {
+      lines.push(`  ${adapter.name}: NOT READY — ${check.reason}`);
+      authFailures += 1;
+    }
+  }
+  lines.push('');
+  lines.push(`(--dry-run — no prompts sent. ${authFailures} provider(s) unavailable.)`);
+  process.stdout.write(lines.join('\n') + '\n');
+}
+
+main().catch(err => {
+  console.error('FATAL:', err);
+  process.exit(1);
+});

bin/gstack-next-version

@@ -0,0 +1,477 @@
+#!/usr/bin/env bun
+// gstack-next-version — host-aware VERSION allocator for /ship.
+//
+// Queries the PR queue (GitHub or GitLab), fetches each open PR's VERSION,
+// scans configurable Conductor sibling worktrees, picks the next free version
+// slot at the requested bump level, and emits the whole picture as JSON.
+//
+// Contract: util NEVER writes files or mutates state. Pure reader + reporter.
+// /ship consumes the JSON and decides what to do.
+//
+// Usage:
+//   gstack-next-version --base <branch> --bump <major|minor|patch|micro> \
+//     --current-version <X.Y.Z.W> [--workspace-root <path>|null] [--json]
+//
+// Exit codes:
+//   0 — emitted JSON successfully (may include "offline":true or "host":"unknown")
+//   2 — invalid arguments
+//   3 — util bug (unexpected exception)
+
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+type Bump = "major" | "minor" | "patch" | "micro";
+type Version = [number, number, number, number];
+
+type ClaimedPR = {
+  pr: number;
+  branch: string;
+  version: string;
+  url?: string;
+};
+
+type Sibling = {
+  path: string;
+  branch: string;
+  version: string;
+  last_commit_ts: number;
+  has_open_pr: boolean;
+  is_active: boolean;
+};
+
+type Output = {
+  version: string;
+  current_version: string;
+  base_version: string;
+  bump: Bump;
+  host: "github" | "gitlab" | "unknown";
+  offline: boolean;
+  claimed: ClaimedPR[];
+  siblings: Sibling[];
+  active_siblings: Sibling[];
+  reason: string;
+  warnings: string[];
+};
+
+const ACTIVE_SIBLING_MAX_AGE_S = 24 * 60 * 60;
+const GH_API_CONCURRENCY = 10;
+
+function parseVersion(s: string): Version | null {
+  const m = s.trim().match(/^(\d+)\.(\d+)\.(\d+)\.(\d+)$/);
+  if (!m) return null;
+  return [Number(m[1]), Number(m[2]), Number(m[3]), Number(m[4])];
+}
+
+function fmtVersion(v: Version): string {
+  return v.join(".");
+}
+
+function bumpVersion(v: Version, level: Bump): Version {
+  switch (level) {
+    case "major":
+      return [v[0] + 1, 0, 0, 0];
+    case "minor":
+      return [v[0], v[1] + 1, 0, 0];
+    case "patch":
+      return [v[0], v[1], v[2] + 1, 0];
+    case "micro":
+      return [v[0], v[1], v[2], v[3] + 1];
+  }
+}
+
+function cmpVersion(a: Version, b: Version): number {
+  for (let i = 0; i < 4; i++) {
+    if (a[i] !== b[i]) return a[i] - b[i];
+  }
+  return 0;
+}
+
+// Collision resolution: bump past the highest claimed within the same level.
+// Semantics: if my bump is MINOR and the queue claims 1.7.0.0, I advance to
+// 1.8.0.0 (still a MINOR relative to main). Preserves ship-time intent.
+function pickNextSlot(base: Version, claimed: Version[], level: Bump): { version: Version; reason: string } {
+  let candidate = bumpVersion(base, level);
+  const sortedClaimed = [...claimed].sort(cmpVersion);
+  const highest = sortedClaimed[sortedClaimed.length - 1];
+  if (highest && cmpVersion(highest, base) > 0) {
+    // Queue already advanced past base; bump past the highest claim.
+    const bumpedPastHighest = bumpVersion(highest, level);
+    if (cmpVersion(bumpedPastHighest, candidate) > 0) {
+      return { version: bumpedPastHighest, reason: `bumped past claimed ${fmtVersion(highest)}` };
+    }
+  }
+  return { version: candidate, reason: "no collision; clean bump from base" };
+}
+
+function runCommand(cmd: string, args: string[], timeoutMs = 15000): { ok: boolean; stdout: string; stderr: string } {
+  const r = spawnSync(cmd, args, { encoding: "utf8", timeout: timeoutMs });
+  return {
+    ok: r.status === 0 && !r.error,
+    stdout: r.stdout ?? "",
+    stderr: r.stderr ?? (r.error ? String(r.error) : ""),
+  };
+}
+
+function detectHost(): "github" | "gitlab" | "unknown" {
+  const remote = runCommand("git", ["remote", "get-url", "origin"]);
+  if (remote.ok) {
+    const url = remote.stdout.trim();
+    if (url.includes("github.com")) return "github";
+    if (url.includes("gitlab")) return "gitlab";
+  }
+  const gh = runCommand("gh", ["auth", "status"]);
+  if (gh.ok) return "github";
+  const glab = runCommand("glab", ["auth", "status"]);
+  if (glab.ok) return "gitlab";
+  return "unknown";
+}
+
+function readBaseVersion(base: string, warnings: string[]): string {
+  // git fetch is best-effort; we tolerate failure and fall back to whatever
+  // origin/<base> currently points at.
+  runCommand("git", ["fetch", "origin", base, "--quiet"], 10000);
+  const r = runCommand("git", ["show", `origin/${base}:VERSION`]);
+  if (!r.ok) {
+    warnings.push(`could not read VERSION at origin/${base}; assuming 0.0.0.0`);
+    return "0.0.0.0";
+  }
+  return r.stdout.trim();
+}
+
+async function fetchGithubClaimed(base: string, excludePR: number | null, warnings: string[]): Promise<{ claimed: ClaimedPR[]; offline: boolean }> {
+  const list = runCommand("gh", [
+    "pr",
+    "list",
+    "--state",
+    "open",
+    "--base",
+    base,
+    "--limit",
+    "200",
+    "--json",
+    "number,headRefName,headRepositoryOwner,url,isDraft",
+  ]);
+  if (!list.ok) {
+    warnings.push(`gh pr list failed: ${list.stderr.trim().slice(0, 200)}`);
+    return { claimed: [], offline: true };
+  }
+  let prs: {
+    number: number;
+    headRefName: string;
+    headRepositoryOwner?: { login: string };
+    url: string;
+    isDraft: boolean;
+  }[];
+  try {
+    prs = JSON.parse(list.stdout);
+  } catch (e) {
+    warnings.push(`gh pr list returned invalid JSON`);
+    return { claimed: [], offline: true };
+  }
+  // Determine our repo owner to filter out fork PRs. `gh api contents?ref=<branch>`
+  // resolves to OUR repo regardless of where the PR originated, so fork PRs would
+  // otherwise return our main's VERSION as a phantom claim.
+  const viewer = runCommand("gh", ["repo", "view", "--json", "owner", "-q", ".owner.login"]);
+  const myOwner = viewer.ok ? viewer.stdout.trim() : "";
+  const sameRepoPRs = (myOwner
+    ? prs.filter((p) => (p.headRepositoryOwner?.login ?? "") === myOwner)
+    : prs
+  ).filter((p) => excludePR === null || p.number !== excludePR);
+  // Fetch each PR's VERSION at its head in parallel (bounded concurrency).
+  const results: ClaimedPR[] = [];
+  const queue = [...sameRepoPRs];
+  const workers = Array.from({ length: Math.min(GH_API_CONCURRENCY, sameRepoPRs.length) }, async () => {
+    while (queue.length) {
+      const pr = queue.shift();
+      if (!pr) return;
+      // gh passes branch name via argv, not shell — safe.
+      const content = runCommand("gh", [
+        "api",
+        `repos/{owner}/{repo}/contents/VERSION?ref=${encodeURIComponent(pr.headRefName)}`,
+        "-q",
+        ".content",
+      ]);
+      if (!content.ok) {
+        warnings.push(`PR #${pr.number}: could not fetch VERSION (fork or private)`);
+        continue;
+      }
+      let versionStr: string;
+      try {
+        versionStr = Buffer.from(content.stdout.trim(), "base64").toString("utf8").trim();
+      } catch {
+        warnings.push(`PR #${pr.number}: VERSION is not valid base64`);
+        continue;
+      }
+      if (!parseVersion(versionStr)) {
+        warnings.push(`PR #${pr.number}: VERSION is malformed (${versionStr})`);
+        continue;
+      }
+      results.push({ pr: pr.number, branch: pr.headRefName, version: versionStr, url: pr.url });
+    }
+  });
+  await Promise.all(workers);
+  return { claimed: results, offline: false };
+}
+
+async function fetchGitlabClaimed(base: string, excludePR: number | null, warnings: string[]): Promise<{ claimed: ClaimedPR[]; offline: boolean }> {
+  const list = runCommand("glab", [
+    "mr",
+    "list",
+    "--opened",
+    "--target-branch",
+    base,
+    "--output",
+    "json",
+    "--per-page",
+    "200",
+  ]);
+  if (!list.ok) {
+    warnings.push(`glab mr list failed: ${list.stderr.trim().slice(0, 200)}`);
+    return { claimed: [], offline: true };
+  }
+  let mrs: { iid: number; source_branch: string; web_url: string }[];
+  try {
+    mrs = JSON.parse(list.stdout);
+  } catch {
+    warnings.push(`glab mr list returned invalid JSON`);
+    return { claimed: [], offline: true };
+  }
+  if (excludePR !== null) {
+    mrs = mrs.filter((mr) => mr.iid !== excludePR);
+  }
+  const results: ClaimedPR[] = [];
+  for (const mr of mrs) {
+    const content = runCommand("glab", [
+      "api",
+      `projects/:id/repository/files/VERSION?ref=${encodeURIComponent(mr.source_branch)}`,
+    ]);
+    if (!content.ok) {
+      warnings.push(`MR !${mr.iid}: could not fetch VERSION`);
+      continue;
+    }
+    try {
+      const j = JSON.parse(content.stdout);
+      const versionStr = Buffer.from(j.content, "base64").toString("utf8").trim();
+      if (!parseVersion(versionStr)) {
+        warnings.push(`MR !${mr.iid}: VERSION malformed (${versionStr})`);
+        continue;
+      }
+      results.push({ pr: mr.iid, branch: mr.source_branch, version: versionStr, url: mr.web_url });
+    } catch {
+      warnings.push(`MR !${mr.iid}: unexpected glab api response`);
+    }
+  }
+  return { claimed: results, offline: false };
+}
+
+function resolveWorkspaceRoot(override?: string): string | null {
+  if (override === "null") return null;
+  if (override) return override;
+  const r = runCommand(join(__dirname, "gstack-config"), ["get", "workspace_root"]);
+  const configured = r.ok ? r.stdout.trim() : "";
+  if (configured === "null") return null;
+  if (configured) return configured;
+  // Default: $HOME/conductor/workspaces/
+  return join(homedir(), "conductor", "workspaces");
+}
+
+function currentRepoSlug(): string {
+  const r = runCommand("git", ["remote", "get-url", "origin"]);
+  if (!r.ok) return "";
+  // Extract "owner/repo" from URL like git@github.com:owner/repo.git
+  const m = r.stdout.trim().match(/[:/]([^/]+\/[^/]+?)(?:\.git)?$/);
+  return m ? m[1] : "";
+}
+
+function scanSiblings(root: string | null, claimed: ClaimedPR[], warnings: string[]): Sibling[] {
+  if (!root || !existsSync(root)) return [];
+  const mySlug = currentRepoSlug();
+  if (!mySlug) {
+    warnings.push("could not determine current repo slug; skipping sibling scan");
+    return [];
+  }
+  const repoName = mySlug.split("/").pop() ?? "";
+  // Conductor layout: <root>/<repo>/<workspace>/
+  const repoDir = join(root, repoName);
+  if (!existsSync(repoDir)) return [];
+  const myAbsPath = resolve(process.cwd());
+  const results: Sibling[] = [];
+  for (const name of readdirSync(repoDir)) {
+    const p = join(repoDir, name);
+    if (resolve(p) === myAbsPath) continue;
+    try {
+      const s = statSync(p);
+      if (!s.isDirectory()) continue;
+    } catch {
+      continue;
+    }
+    if (!existsSync(join(p, ".git")) && !existsSync(join(p, ".git/HEAD"))) continue;
+    const versionFile = join(p, "VERSION");
+    if (!existsSync(versionFile)) continue;
+    let version: string;
+    try {
+      version = readFileSync(versionFile, "utf8").trim();
+      if (!parseVersion(version)) continue;
+    } catch {
+      continue;
+    }
+    const branchR = runCommand("git", ["-C", p, "rev-parse", "--abbrev-ref", "HEAD"]);
+    if (!branchR.ok) continue;
+    const branch = branchR.stdout.trim();
+    const commitTsR = runCommand("git", ["-C", p, "log", "-1", "--format=%ct"]);
+    const last_commit_ts = commitTsR.ok ? Number(commitTsR.stdout.trim()) : 0;
+    const has_open_pr = claimed.some((c) => c.branch === branch);
+    results.push({
+      path: p,
+      branch,
+      version,
+      last_commit_ts,
+      has_open_pr,
+      is_active: false,
+    });
+  }
+  return results;
+}
+
+function markActiveSiblings(siblings: Sibling[], baseVersion: Version): Sibling[] {
+  const now = Math.floor(Date.now() / 1000);
+  return siblings.map((s) => {
+    const v = parseVersion(s.version);
+    const isAhead = v ? cmpVersion(v, baseVersion) > 0 : false;
+    const isFresh = s.last_commit_ts > 0 && now - s.last_commit_ts < ACTIVE_SIBLING_MAX_AGE_S;
+    const is_active = isAhead && isFresh && !s.has_open_pr;
+    return { ...s, is_active };
+  });
+}
+
+function parseArgs(argv: string[]): { base: string; bump: Bump; current: string; workspaceRoot?: string; excludePR: number | null; help: boolean } {
+  let base = "";
+  let bump: Bump | "" = "";
+  let current = "";
+  let workspaceRoot: string | undefined;
+  let excludePR: number | null = null;
+  let help = false;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--base") base = argv[++i] ?? "";
+    else if (a === "--bump") bump = (argv[++i] ?? "") as Bump;
+    else if (a === "--current-version") current = argv[++i] ?? "";
+    else if (a === "--workspace-root") workspaceRoot = argv[++i];
+    else if (a === "--exclude-pr") {
+      const n = Number(argv[++i]);
+      excludePR = Number.isFinite(n) && n > 0 ? n : null;
+    }
+    else if (a === "-h" || a === "--help") help = true;
+  }
+  if (help) return { base: "", bump: "micro", current: "", excludePR: null, help: true };
+  if (!base) base = "main";
+  if (!bump) {
+    console.error("Error: --bump is required (major|minor|patch|micro)");
+    process.exit(2);
+  }
+  if (!["major", "minor", "patch", "micro"].includes(bump)) {
+    console.error(`Error: --bump must be major|minor|patch|micro (got ${bump})`);
+    process.exit(2);
+  }
+  return { base, bump: bump as Bump, current, workspaceRoot, excludePR, help: false };
+}
+
+// Auto-detect: if --exclude-pr wasn't passed, check whether the current branch
+// already has an open PR and exclude it by default. This prevents the self-
+// reference bug where /ship's own PR inflates the queue on rerun.
+function autoDetectExcludePR(): number | null {
+  const r = runCommand("gh", ["pr", "view", "--json", "number", "-q", ".number"]);
+  if (!r.ok) return null;
+  const n = Number(r.stdout.trim());
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    console.log(
+      "Usage: gstack-next-version --base <branch> --bump <level> --current-version <X.Y.Z.W> [--workspace-root <path|null>]",
+    );
+    process.exit(0);
+  }
+  const warnings: string[] = [];
+  const host = detectHost();
+  const baseVersion = args.current || readBaseVersion(args.base, warnings);
+  const baseParsed = parseVersion(baseVersion);
+  if (!baseParsed) {
+    console.error(`Error: could not parse base version '${baseVersion}'`);
+    process.exit(2);
+  }
+
+  const excludePR = args.excludePR ?? autoDetectExcludePR();
+  if (excludePR !== null && args.excludePR === null) {
+    warnings.push(`auto-excluded PR #${excludePR} (current branch's own PR)`);
+  }
+
+  let claimed: ClaimedPR[] = [];
+  let offline = false;
+  if (host === "github") {
+    ({ claimed, offline } = await fetchGithubClaimed(args.base, excludePR, warnings));
+  } else if (host === "gitlab") {
+    ({ claimed, offline } = await fetchGitlabClaimed(args.base, excludePR, warnings));
+  } else {
+    warnings.push("host unknown; queue-awareness unavailable");
+  }
+
+  // Only count PRs that actually bumped VERSION past base as real "claims".
+  // A PR whose VERSION equals base's VERSION hasn't claimed anything.
+  const realClaims = claimed.filter((c) => {
+    const v = parseVersion(c.version);
+    return v !== null && cmpVersion(v, baseParsed) > 0;
+  });
+  const claimedVersions = realClaims
+    .map((c) => parseVersion(c.version))
+    .filter((v): v is Version => v !== null);
+
+  const { version: picked, reason } = pickNextSlot(baseParsed, claimedVersions, args.bump);
+
+  const workspaceRoot = resolveWorkspaceRoot(args.workspaceRoot);
+  const siblings = markActiveSiblings(scanSiblings(workspaceRoot, claimed, warnings), baseParsed);
+  const activeSiblings = siblings.filter((s) => s.is_active);
+
+  // If an active sibling outranks our pick, bump past it (same bump level).
+  let finalVersion = picked;
+  let finalReason = reason;
+  const activeAhead = activeSiblings
+    .map((s) => parseVersion(s.version))
+    .filter((v): v is Version => v !== null)
+    .filter((v) => cmpVersion(v, finalVersion) >= 0);
+  if (activeAhead.length) {
+    const highest = activeAhead.sort(cmpVersion)[activeAhead.length - 1];
+    finalVersion = bumpVersion(highest, args.bump);
+    finalReason = `bumped past active sibling ${fmtVersion(highest)}`;
+  }
+
+  const out: Output = {
+    version: fmtVersion(finalVersion),
+    current_version: args.current || baseVersion,
+    base_version: baseVersion,
+    bump: args.bump,
+    host,
+    offline,
+    claimed: realClaims,
+    siblings,
+    active_siblings: activeSiblings,
+    reason: finalReason,
+    warnings,
+  };
+  process.stdout.write(JSON.stringify(out, null, 2) + "\n");
+}
+
+// Pure-function exports for testing
+export { parseVersion, fmtVersion, bumpVersion, cmpVersion, pickNextSlot, markActiveSiblings };
+
+// Only run main() when invoked as a script, not when imported by tests.
+if (import.meta.main) {
+  main().catch((e) => {
+    console.error("Unexpected error:", e?.stack ?? e);
+    process.exit(3);
+  });
+}

bin/gstack-open-url

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# gstack-open-url — cross-platform URL opener
+#
+# Usage: gstack-open-url <url>
+set -euo pipefail
+
+URL="${1:?Usage: gstack-open-url <url>}"
+
+case "$(uname -s)" in
+  Darwin)  open "$URL" ;;
+  Linux)   xdg-open "$URL" 2>/dev/null || echo "$URL" ;;
+  MINGW*|MSYS*|CYGWIN*) start "$URL" ;;
+  *)       echo "$URL" ;;
+esac

bin/gstack-patch-names

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# gstack-patch-names — patch name: field in SKILL.md frontmatter for prefix mode
+# Usage: gstack-patch-names <gstack-dir> <true|false|1|0>
+set -euo pipefail
+
+GSTACK_DIR="$1"
+DO_PREFIX="$2"
+
+# Normalize prefix arg
+case "$DO_PREFIX" in true|1) DO_PREFIX=1 ;; *) DO_PREFIX=0 ;; esac
+
+PATCHED=0
+for skill_dir in "$GSTACK_DIR"/*/; do
+  [ -f "$skill_dir/SKILL.md" ] || continue
+  dir_name="$(basename "$skill_dir")"
+  [ "$dir_name" = "node_modules" ] && continue
+  cur=$(grep -m1 '^name:' "$skill_dir/SKILL.md" 2>/dev/null | sed 's/^name:[[:space:]]*//' | tr -d '[:space:]' || true)
+  [ -z "$cur" ] && continue
+  [ "$cur" = "gstack" ] && continue  # never prefix root skill
+  if [ "$DO_PREFIX" -eq 1 ]; then
+    case "$cur" in gstack-*) continue ;; esac
+    new="gstack-$cur"
+  else
+    case "$cur" in gstack-*) ;; *) continue ;; esac
+    [ "$dir_name" = "$cur" ] && continue  # inherently prefixed (gstack-upgrade)
+    new="${cur#gstack-}"
+  fi
+  tmp="$(mktemp "${skill_dir}/SKILL.md.XXXXXX")"
+  sed "1,/^---$/s/^name:[[:space:]]*${cur}/name: ${new}/" "$skill_dir/SKILL.md" > "$tmp" && mv "$tmp" "$skill_dir/SKILL.md"
+  PATCHED=$((PATCHED + 1))
+done
+if [ "$PATCHED" -gt 0 ]; then
+  echo "  patched name: field in $PATCHED skills"
+fi

bin/gstack-paths

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+# gstack-paths — output portable state-root paths for skill bash blocks
+# Usage: eval "$(gstack-paths)"  → sets GSTACK_STATE_ROOT, PLAN_ROOT, TMP_ROOT
+# Or:    gstack-paths            → prints GSTACK_STATE_ROOT=... etc.
+#
+# Resolves three roots with explicit fallback chains so skills work the same
+# whether installed as a Claude Code plugin (CLAUDE_PLUGIN_DATA / CLAUDE_PLANS_DIR
+# set), a global ~/.claude/skills/gstack/ install, or a local checkout under
+# CI / container env where HOME may be unset.
+#
+# Chains:
+#   GSTACK_STATE_ROOT: GSTACK_HOME -> CLAUDE_PLUGIN_DATA -> $HOME/.gstack -> .gstack
+#   PLAN_ROOT:         GSTACK_PLAN_DIR -> CLAUDE_PLANS_DIR -> $HOME/.claude/plans -> .claude/plans
+#   TMP_ROOT:          TMPDIR -> TMP -> .gstack/tmp (and mkdir -p, best-effort)
+#
+# Security: output values are not sanitized — callers may receive paths with
+# shell-special characters if env vars contain them. Skills should always quote
+# expansions ("$GSTACK_STATE_ROOT", not $GSTACK_STATE_ROOT).
+set -u
+
+# State root: where gstack writes projects/, sessions/, analytics/.
+if [ -n "${GSTACK_HOME:-}" ]; then
+  _state_root="$GSTACK_HOME"
+elif [ -n "${CLAUDE_PLUGIN_DATA:-}" ]; then
+  _state_root="$CLAUDE_PLUGIN_DATA"
+elif [ -n "${HOME:-}" ]; then
+  _state_root="$HOME/.gstack"
+else
+  _state_root=".gstack"
+fi
+
+# Plan root: where /context-save and /codex consult write plan files.
+if [ -n "${GSTACK_PLAN_DIR:-}" ]; then
+  _plan_root="$GSTACK_PLAN_DIR"
+elif [ -n "${CLAUDE_PLANS_DIR:-}" ]; then
+  _plan_root="$CLAUDE_PLANS_DIR"
+elif [ -n "${HOME:-}" ]; then
+  _plan_root="$HOME/.claude/plans"
+else
+  _plan_root=".claude/plans"
+fi
+
+# Tmp root: where ephemeral files (codex stderr captures, etc.) live.
+# Honor TMPDIR / TMP for Windows + container compat; fall back to a
+# project-local .gstack/tmp so we never write to a system /tmp that may
+# be read-only or shared.
+if [ -n "${TMPDIR:-}" ]; then
+  _tmp_root="$TMPDIR"
+elif [ -n "${TMP:-}" ]; then
+  _tmp_root="$TMP"
+else
+  _tmp_root=".gstack/tmp"
+fi
+
+# Best-effort mkdir; if it fails (read-only fs, permission denied), the caller
+# will discover that on their own write attempt. Don't fail the eval here.
+mkdir -p "$_tmp_root" 2>/dev/null || true
+
+echo "GSTACK_STATE_ROOT=$_state_root"
+echo "PLAN_ROOT=$_plan_root"
+echo "TMP_ROOT=$_tmp_root"

bin/gstack-platform-detect

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# gstack-platform-detect: show which AI coding agents are installed and gstack status
+# Config-driven: reads host definitions from hosts/*.ts via host-config-export.ts
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+GSTACK_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+printf "%-16s %-10s %-40s %s\n" "Agent" "Version" "Skill Path" "gstack"
+printf "%-16s %-10s %-40s %s\n" "-----" "-------" "----------" "------"
+
+for host in $(bun run "$GSTACK_DIR/scripts/host-config-export.ts" list 2>/dev/null); do
+  cmd=$(bun run "$GSTACK_DIR/scripts/host-config-export.ts" get "$host" cliCommand 2>/dev/null)
+  root=$(bun run "$GSTACK_DIR/scripts/host-config-export.ts" get "$host" globalRoot 2>/dev/null)
+  spath="$HOME/$root"
+
+  if command -v "$cmd" >/dev/null 2>&1; then
+    ver=$("$cmd" --version 2>/dev/null | head -1 || echo "unknown")
+    if [ -d "$spath" ] || [ -L "$spath" ]; then
+      status="INSTALLED"
+    else
+      status="NOT INSTALLED"
+    fi
+    printf "%-16s %-10s %-40s %s\n" "$host" "$ver" "$spath" "$status"
+  fi
+done

bin/gstack-pr-title-rewrite.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# Rewrite a PR/MR title to start with v<NEW_VERSION>.
+#
+# Usage:  bin/gstack-pr-title-rewrite.sh <NEW_VERSION> <CURRENT_TITLE>
+# Output: corrected title on stdout.
+#
+# Rule: PR titles MUST start with v<NEW_VERSION>. Three cases:
+#   1. Already starts with "v<NEW_VERSION> " -> no change.
+#   2. Starts with a different "v<digits and dots> " prefix -> replace prefix.
+#   3. No version prefix -> prepend "v<NEW_VERSION> ".
+#
+# The version-prefix regex matches two or more dot-separated digit segments
+# (covers v1.2, v1.2.3, v1.2.3.4) so the rule is portable across repos that
+# use 3-part or 4-part versions, but does NOT strip plain words like
+# "version 5".
+
+set -euo pipefail
+
+if [ $# -lt 2 ]; then
+  echo "usage: $0 <NEW_VERSION> <CURRENT_TITLE>" >&2
+  exit 2
+fi
+
+NEW_VERSION="$1"
+TITLE="$2"
+
+# Reject malformed NEW_VERSION early. Real values are dot-separated digits;
+# anything with shell pattern metacharacters or whitespace is a caller bug.
+if ! printf '%s' "$NEW_VERSION" | grep -qE '^[0-9]+(\.[0-9]+)*$'; then
+  echo "error: NEW_VERSION must be dot-separated digits, got: $NEW_VERSION" >&2
+  exit 2
+fi
+
+# Literal prefix match (case statement is glob-quoted by bash, but our
+# regex-validated NEW_VERSION has no glob metacharacters so this is safe).
+case "$TITLE" in
+  "v$NEW_VERSION "*)
+    printf '%s\n' "$TITLE"
+    exit 0
+    ;;
+esac
+
+REST=$(printf '%s' "$TITLE" | sed -E 's/^v[0-9]+(\.[0-9]+)+ //')
+printf 'v%s %s\n' "$NEW_VERSION" "$REST"

bin/gstack-question-log

@@ -0,0 +1,171 @@
+#!/usr/bin/env bash
+# gstack-question-log — append an AskUserQuestion event to the project log.
+#
+# Usage:
+#   gstack-question-log '{"skill":"ship","question_id":"ship-test-failure-triage",\
+#     "question_summary":"Tests failed","options_count":3,"user_choice":"fix-now",\
+#     "recommended":"fix-now","session_id":"ppid"}'
+#
+# v1: log-only. Consumed by /plan-tune inspection and (in v2) by the
+# inferred-dimension derivation pipeline.
+#
+# Schema (all fields validated):
+#   skill              — skill name (kebab-case)
+#   question_id        — either a registered id (preferred) or ad-hoc `{skill}-{slug}`
+#   question_summary   — short one-liner of what was asked (<= 200 chars)
+#   category           — approval | clarification | routing | cherry-pick | feedback-loop
+#                        (optional — looked up from registry if omitted)
+#   door_type          — one-way | two-way
+#                        (optional — looked up from registry if omitted)
+#   options_count      — number of options presented (positive integer)
+#   user_choice        — key user selected (free string; registry-options preferred)
+#   recommended        — option key the agent recommended (optional)
+#   followed_recommendation — bool (optional — computed if both present)
+#   session_id         — stable session identifier
+#   ts                 — ISO 8601 timestamp (auto-injected if missing)
+#
+# Append-only JSONL. Dedup is at read time in gstack-question-sensitivity --read-log.
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+eval "$("$SCRIPT_DIR/gstack-slug" 2>/dev/null)"
+GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
+mkdir -p "$GSTACK_HOME/projects/$SLUG"
+
+INPUT="$1"
+
+# Validate and enrich from registry.
+TMPERR=$(mktemp)
+trap 'rm -f "$TMPERR"' EXIT
+set +e
+VALIDATED=$(printf '%s' "$INPUT" | bun -e "
+const path = require('path');
+const raw = await Bun.stdin.text();
+let j;
+try { j = JSON.parse(raw); } catch { process.stderr.write('gstack-question-log: invalid JSON\n'); process.exit(1); }
+
+// Required: skill (kebab-case)
+if (!j.skill || !/^[a-z0-9-]+\$/.test(j.skill)) {
+  process.stderr.write('gstack-question-log: invalid skill, must be kebab-case\n');
+  process.exit(1);
+}
+
+// Required: question_id (kebab-case, <=64 chars)
+if (!j.question_id || !/^[a-z0-9-]+\$/.test(j.question_id) || j.question_id.length > 64) {
+  process.stderr.write('gstack-question-log: invalid question_id, must be kebab-case <=64 chars\n');
+  process.exit(1);
+}
+
+// Required: question_summary (non-empty, <=200 chars, no newlines)
+if (typeof j.question_summary !== 'string' || !j.question_summary.length) {
+  process.stderr.write('gstack-question-log: question_summary required\n');
+  process.exit(1);
+}
+if (j.question_summary.length > 200) {
+  j.question_summary = j.question_summary.slice(0, 200);
+}
+if (j.question_summary.includes('\n')) {
+  j.question_summary = j.question_summary.replace(/\n+/g, ' ');
+}
+
+// Injection defense on the summary — same patterns as learnings-log.
+const INJECTION_PATTERNS = [
+  /ignore\s+(all\s+)?previous\s+(instructions|context|rules)/i,
+  /you\s+are\s+now\s+/i,
+  /always\s+output\s+no\s+findings/i,
+  /skip\s+(all\s+)?(security|review|checks)/i,
+  /override[:\s]/i,
+  /\bsystem\s*:/i,
+  /\bassistant\s*:/i,
+  /\buser\s*:/i,
+  /do\s+not\s+(report|flag|mention)/i,
+];
+for (const pat of INJECTION_PATTERNS) {
+  if (pat.test(j.question_summary)) {
+    process.stderr.write('gstack-question-log: question_summary contains suspicious instruction-like content, rejected\n');
+    process.exit(1);
+  }
+}
+
+// Registry lookup for category + door_type enrichment.
+// Registry file is at \$GSTACK_ROOT/scripts/question-registry.ts, but we don't import
+// TypeScript at runtime here — we pass through what was provided and fill in defaults.
+// The caller (the preamble resolver) is expected to pass category+door_type from
+// the registry when it knows them; for ad-hoc ids both can be omitted.
+
+const ALLOWED_CATEGORIES = ['approval', 'clarification', 'routing', 'cherry-pick', 'feedback-loop'];
+if (j.category !== undefined) {
+  if (!ALLOWED_CATEGORIES.includes(j.category)) {
+    process.stderr.write('gstack-question-log: invalid category, must be one of: ' + ALLOWED_CATEGORIES.join(', ') + '\n');
+    process.exit(1);
+  }
+}
+
+const ALLOWED_DOORS = ['one-way', 'two-way'];
+if (j.door_type !== undefined) {
+  if (!ALLOWED_DOORS.includes(j.door_type)) {
+    process.stderr.write('gstack-question-log: invalid door_type, must be one-way or two-way\n');
+    process.exit(1);
+  }
+}
+
+// options_count — positive integer if present
+if (j.options_count !== undefined) {
+  const n = Number(j.options_count);
+  if (!Number.isInteger(n) || n < 1 || n > 26) {
+    process.stderr.write('gstack-question-log: options_count must be integer in [1, 26]\n');
+    process.exit(1);
+  }
+  j.options_count = n;
+}
+
+// user_choice — required; <= 64 chars; single-line; no injection patterns
+if (typeof j.user_choice !== 'string' || !j.user_choice.length) {
+  process.stderr.write('gstack-question-log: user_choice required\n');
+  process.exit(1);
+}
+if (j.user_choice.length > 64) j.user_choice = j.user_choice.slice(0, 64);
+j.user_choice = j.user_choice.replace(/\n+/g, ' ');
+
+// recommended — optional, same constraints as user_choice
+if (j.recommended !== undefined) {
+  if (typeof j.recommended !== 'string') {
+    process.stderr.write('gstack-question-log: recommended must be string\n');
+    process.exit(1);
+  }
+  if (j.recommended.length > 64) j.recommended = j.recommended.slice(0, 64);
+}
+
+// followed_recommendation — compute if both sides present.
+if (j.recommended !== undefined && j.user_choice !== undefined) {
+  j.followed_recommendation = j.user_choice === j.recommended;
+}
+
+// session_id — kebab-friendly; <=64 chars
+if (j.session_id !== undefined) {
+  if (typeof j.session_id !== 'string') {
+    process.stderr.write('gstack-question-log: session_id must be string\n');
+    process.exit(1);
+  }
+  if (j.session_id.length > 64) j.session_id = j.session_id.slice(0, 64);
+}
+
+// Inject timestamp if not present.
+if (!j.ts) j.ts = new Date().toISOString();
+
+console.log(JSON.stringify(j));
+" 2>"$TMPERR")
+VALIDATE_RC=$?
+set -e
+
+if [ $VALIDATE_RC -ne 0 ] || [ -z "$VALIDATED" ]; then
+  if [ -s "$TMPERR" ]; then
+    cat "$TMPERR" >&2
+  fi
+  exit 1
+fi
+
+echo "$VALIDATED" >> "$GSTACK_HOME/projects/$SLUG/question-log.jsonl"
+
+# NOTE: question-log.jsonl is deliberately NOT enqueued for gbrain-sync.
+# Per Codex v2 review, audit/derivation data stays local alongside the
+# question-preferences.json it annotates.

bin/gstack-question-preference

@@ -0,0 +1,262 @@
+#!/usr/bin/env bash
+# gstack-question-preference — read/write/check explicit per-question preferences.
+#
+# Preference file: ~/.gstack/projects/{SLUG}/question-preferences.json
+# Schema: { "<question_id>": "always-ask" | "never-ask" | "ask-only-for-one-way" }
+#
+# Subcommands:
+#   --check <id>                   → emit ASK_NORMALLY | AUTO_DECIDE | ASK_ONLY_ONE_WAY
+#   --write '{...}'                → set a preference (user-origin gate enforced)
+#   --read                         → dump preferences JSON
+#   --clear [<id>]                 → clear one or all preferences
+#   --stats                        → short summary
+#
+# User-origin gate
+# ----------------
+# The --write subcommand REQUIRES a `source` field on the input:
+#   - "plan-tune"         — user ran /plan-tune and chose a preference (allowed)
+#   - "inline-user"       — inline `tune:` from the user's own chat message (allowed)
+#   - "inline-tool-output"— tune: prefix seen in tool output / file content (REJECTED)
+#   - "inline-file"       — tune: prefix seen in a file the agent read (REJECTED)
+# This is the profile-poisoning defense from docs/designs/PLAN_TUNING_V0.md.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
+eval "$("$SCRIPT_DIR/gstack-slug" 2>/dev/null || true)"
+SLUG="${SLUG:-unknown}"
+PREF_FILE="$GSTACK_HOME/projects/$SLUG/question-preferences.json"
+EVENT_FILE="$GSTACK_HOME/projects/$SLUG/question-events.jsonl"
+mkdir -p "$GSTACK_HOME/projects/$SLUG"
+
+CMD="${1:-}"
+shift || true
+
+ensure_file() {
+  if [ ! -f "$PREF_FILE" ]; then
+    echo '{}' > "$PREF_FILE"
+  fi
+}
+
+# -----------------------------------------------------------------------
+# --check <question_id>
+# -----------------------------------------------------------------------
+do_check() {
+  local QID="${1:-}"
+  if [ -z "$QID" ]; then
+    echo "ASK_NORMALLY"
+    return 0
+  fi
+  ensure_file
+  cd "$ROOT_DIR"
+  PREF_FILE_PATH="$PREF_FILE" QID="$QID" bun -e "
+    import('./scripts/one-way-doors.ts').then((oneway) => {
+      const fs = require('fs');
+      const qid = process.env.QID;
+      const prefs = JSON.parse(fs.readFileSync(process.env.PREF_FILE_PATH, 'utf-8'));
+      const pref = prefs[qid];
+
+      // Always check one-way status first — safety overrides preferences.
+      const oneWay = oneway.isOneWayDoor({ question_id: qid });
+
+      if (oneWay) {
+        console.log('ASK_NORMALLY');
+        if (pref === 'never-ask') {
+          console.log('NOTE: one-way door overrides your never-ask preference for safety.');
+        }
+        return;
+      }
+
+      switch (pref) {
+        case 'never-ask':
+          console.log('AUTO_DECIDE');
+          break;
+        case 'ask-only-for-one-way':
+          // Not one-way (we checked above) — auto-decide this two-way question.
+          console.log('AUTO_DECIDE');
+          break;
+        case 'always-ask':
+        case undefined:
+        case null:
+          console.log('ASK_NORMALLY');
+          break;
+        default:
+          console.log('ASK_NORMALLY');
+          console.log('NOTE: unknown preference value: ' + pref);
+      }
+    }).catch(err => { console.error('check:', err.message); process.exit(1); });
+  "
+}
+
+# -----------------------------------------------------------------------
+# --write '{...}' (with user-origin gate)
+# -----------------------------------------------------------------------
+do_write() {
+  local INPUT="${1:-}"
+  if [ -z "$INPUT" ]; then
+    echo "gstack-question-preference: --write requires a JSON payload" >&2
+    exit 1
+  fi
+  ensure_file
+  local TMPERR
+  TMPERR=$(mktemp)
+  # Use function-local cleanup via RETURN trap so variable lookup only happens
+  # while the function is on the stack (avoids EXIT-trap unbound-var race).
+  trap "rm -f '$TMPERR'" RETURN
+
+  set +e
+  local RESULT
+  RESULT=$(printf '%s' "$INPUT" | PREF_FILE_PATH="$PREF_FILE" EVENT_FILE_PATH="$EVENT_FILE" bun -e "
+    const fs = require('fs');
+    const raw = await Bun.stdin.text();
+    let j;
+    try { j = JSON.parse(raw); } catch { process.stderr.write('gstack-question-preference: invalid JSON\n'); process.exit(1); }
+
+    // Required: question_id (kebab-case, <=64)
+    if (!j.question_id || !/^[a-z0-9-]+\$/.test(j.question_id) || j.question_id.length > 64) {
+      process.stderr.write('gstack-question-preference: invalid question_id\n');
+      process.exit(1);
+    }
+
+    // Required: preference
+    const ALLOWED_PREFS = ['always-ask', 'never-ask', 'ask-only-for-one-way'];
+    if (!ALLOWED_PREFS.includes(j.preference)) {
+      process.stderr.write('gstack-question-preference: invalid preference (must be one of: ' + ALLOWED_PREFS.join(', ') + ')\n');
+      process.exit(1);
+    }
+
+    // user-origin gate — REQUIRED on every write.
+    // See docs/designs/PLAN_TUNING_V0.md §Security model
+    const ALLOWED_SOURCES = ['plan-tune', 'inline-user'];
+    const REJECTED_SOURCES = ['inline-tool-output', 'inline-file', 'inline-file-content', 'inline-unknown'];
+    if (!j.source) {
+      process.stderr.write('gstack-question-preference: source field required (one of: ' + ALLOWED_SOURCES.join(', ') + ')\n');
+      process.exit(1);
+    }
+    if (REJECTED_SOURCES.includes(j.source)) {
+      process.stderr.write('gstack-question-preference: rejected — source \"' + j.source + '\" is not user-originated (profile poisoning defense)\n');
+      process.exit(2);
+    }
+    if (!ALLOWED_SOURCES.includes(j.source)) {
+      process.stderr.write('gstack-question-preference: invalid source \"' + j.source + '\"; allowed: ' + ALLOWED_SOURCES.join(', ') + '\n');
+      process.exit(1);
+    }
+
+    // Optional free_text — sanitize (no injection patterns, no newlines, <=300 chars)
+    if (j.free_text !== undefined) {
+      if (typeof j.free_text !== 'string') {
+        process.stderr.write('gstack-question-preference: free_text must be string\n');
+        process.exit(1);
+      }
+      if (j.free_text.length > 300) j.free_text = j.free_text.slice(0, 300);
+      j.free_text = j.free_text.replace(/\n+/g, ' ');
+      const INJECTION_PATTERNS = [
+        /ignore\s+(all\s+)?previous\s+(instructions|context|rules)/i,
+        /you\s+are\s+now\s+/i,
+        /override[:\s]/i,
+        /\bsystem\s*:/i,
+        /\bassistant\s*:/i,
+        /do\s+not\s+(report|flag|mention)/i,
+      ];
+      for (const pat of INJECTION_PATTERNS) {
+        if (pat.test(j.free_text)) {
+          process.stderr.write('gstack-question-preference: free_text contains injection-like content, rejected\n');
+          process.exit(1);
+        }
+      }
+    }
+
+    // Write to preferences file
+    const prefs = JSON.parse(fs.readFileSync(process.env.PREF_FILE_PATH, 'utf-8'));
+    prefs[j.question_id] = j.preference;
+    fs.writeFileSync(process.env.PREF_FILE_PATH, JSON.stringify(prefs, null, 2));
+
+    // Also append a record to question-events.jsonl for audit + derivation.
+    const evt = {
+      ts: new Date().toISOString(),
+      event_type: 'preference-set',
+      question_id: j.question_id,
+      preference: j.preference,
+      source: j.source,
+      ...(j.free_text ? { free_text: j.free_text } : {}),
+    };
+    fs.appendFileSync(process.env.EVENT_FILE_PATH, JSON.stringify(evt) + '\n');
+
+    console.log('OK: ' + j.question_id + ' → ' + j.preference + ' (source: ' + j.source + ')');
+  " 2>"$TMPERR")
+  local RC=$?
+  set -e
+
+  if [ $RC -ne 0 ]; then
+    cat "$TMPERR" >&2
+    exit $RC
+  fi
+  echo "$RESULT"
+}
+
+# -----------------------------------------------------------------------
+# --read
+# -----------------------------------------------------------------------
+do_read() {
+  ensure_file
+  cat "$PREF_FILE"
+}
+
+# -----------------------------------------------------------------------
+# --clear [<id>]
+# -----------------------------------------------------------------------
+do_clear() {
+  local QID="${1:-}"
+  ensure_file
+  if [ -z "$QID" ]; then
+    echo '{}' > "$PREF_FILE"
+    echo "OK: cleared all preferences"
+  else
+    PREF_FILE_PATH="$PREF_FILE" QID="$QID" bun -e "
+      const fs = require('fs');
+      const prefs = JSON.parse(fs.readFileSync(process.env.PREF_FILE_PATH, 'utf-8'));
+      if (prefs[process.env.QID] !== undefined) {
+        delete prefs[process.env.QID];
+        fs.writeFileSync(process.env.PREF_FILE_PATH, JSON.stringify(prefs, null, 2));
+        console.log('OK: cleared ' + process.env.QID);
+      } else {
+        console.log('NOOP: no preference set for ' + process.env.QID);
+      }
+    "
+  fi
+}
+
+# -----------------------------------------------------------------------
+# --stats
+# -----------------------------------------------------------------------
+do_stats() {
+  ensure_file
+  cat "$PREF_FILE" | bun -e "
+    const prefs = JSON.parse(await Bun.stdin.text());
+    const entries = Object.entries(prefs);
+    const counts = { 'always-ask': 0, 'never-ask': 0, 'ask-only-for-one-way': 0, other: 0 };
+    for (const [, v] of entries) {
+      if (counts[v] !== undefined) counts[v]++;
+      else counts.other++;
+    }
+    console.log('TOTAL: ' + entries.length);
+    console.log('ALWAYS_ASK: ' + counts['always-ask']);
+    console.log('NEVER_ASK: ' + counts['never-ask']);
+    console.log('ASK_ONLY_ONE_WAY: ' + counts['ask-only-for-one-way']);
+    if (counts.other) console.log('OTHER: ' + counts.other);
+  "
+}
+
+case "$CMD" in
+  --check) do_check "$@" ;;
+  --write) do_write "$@" ;;
+  --read|"") do_read ;;
+  --clear) do_clear "$@" ;;
+  --stats) do_stats ;;
+  --help|-h) sed -n '1,/^set -euo/p' "$0" | sed 's|^# \?||' ;;
+  *)
+    echo "gstack-question-preference: unknown subcommand '$CMD'" >&2
+    exit 1
+    ;;
+esac

bin/gstack-relink

@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+# gstack-relink — re-create skill symlinks based on skill_prefix config
+#
+# Usage:
+#   gstack-relink
+#
+# Env overrides (for testing):
+#   GSTACK_STATE_DIR   — override ~/.gstack state directory
+#   GSTACK_INSTALL_DIR — override gstack install directory
+#   GSTACK_SKILLS_DIR  — override target skills directory
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+GSTACK_CONFIG="${SCRIPT_DIR}/gstack-config"
+
+# Detect install dir
+INSTALL_DIR="${GSTACK_INSTALL_DIR:-}"
+if [ -z "$INSTALL_DIR" ]; then
+  if [ -d "$HOME/.claude/skills/gstack" ]; then
+    INSTALL_DIR="$HOME/.claude/skills/gstack"
+  elif [ -d "${SCRIPT_DIR}/.." ] && [ -f "${SCRIPT_DIR}/../setup" ]; then
+    INSTALL_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
+  fi
+fi
+
+if [ -z "$INSTALL_DIR" ] || [ ! -d "$INSTALL_DIR" ]; then
+  echo "Error: gstack install directory not found." >&2
+  echo "Run: cd ~/.claude/skills/gstack && ./setup" >&2
+  exit 1
+fi
+
+# Detect target skills dir
+SKILLS_DIR="${GSTACK_SKILLS_DIR:-$(dirname "$INSTALL_DIR")}"
+[ -d "$SKILLS_DIR" ] || mkdir -p "$SKILLS_DIR"
+
+# Read prefix setting
+PREFIX=$("$GSTACK_CONFIG" get skill_prefix 2>/dev/null || echo "false")
+
+# Helper: remove old skill entry (symlink or real directory with symlinked SKILL.md)
+_cleanup_skill_entry() {
+  local entry="$1"
+  if [ -L "$entry" ]; then
+    rm -f "$entry"
+  elif [ -d "$entry" ] && [ -L "$entry/SKILL.md" ]; then
+    rm -rf "$entry"
+  fi
+}
+
+# Discover skills (directories with SKILL.md, excluding meta dirs)
+SKILL_COUNT=0
+for skill_dir in "$INSTALL_DIR"/*/; do
+  [ -d "$skill_dir" ] || continue
+  skill=$(basename "$skill_dir")
+  # Skip non-skill directories
+  case "$skill" in bin|browse|design|docs|extension|lib|node_modules|scripts|test|.git|.github) continue ;; esac
+  [ -f "$skill_dir/SKILL.md" ] || continue
+
+  if [ "$PREFIX" = "true" ]; then
+    # Don't double-prefix directories already named gstack-*
+    case "$skill" in
+      gstack-*) link_name="$skill" ;;
+      *)        link_name="gstack-$skill" ;;
+    esac
+    # Remove old flat entry if it exists (and isn't the same as the new link)
+    [ "$link_name" != "$skill" ] && _cleanup_skill_entry "$SKILLS_DIR/$skill"
+  else
+    link_name="$skill"
+    # Don't remove gstack-* dirs that are their real name (e.g., gstack-upgrade)
+    case "$skill" in
+      gstack-*) ;; # Already the real name, no old prefixed link to clean
+      *)        _cleanup_skill_entry "$SKILLS_DIR/gstack-$skill" ;;
+    esac
+  fi
+  target="$SKILLS_DIR/$link_name"
+  # Upgrade old directory symlinks to real directories
+  [ -L "$target" ] && rm -f "$target"
+  # Create real directory with symlinked SKILL.md (absolute path)
+  mkdir -p "$target"
+  ln -snf "$INSTALL_DIR/$skill/SKILL.md" "$target/SKILL.md"
+  SKILL_COUNT=$((SKILL_COUNT + 1))
+done
+
+# Patch SKILL.md name: fields to match prefix setting
+"$INSTALL_DIR/bin/gstack-patch-names" "$INSTALL_DIR" "$PREFIX"
+
+if [ "$PREFIX" = "true" ]; then
+  echo "Relinked $SKILL_COUNT skills as gstack-*"
+else
+  echo "Relinked $SKILL_COUNT skills as flat names"
+fi

bin/gstack-repo-mode

@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+# gstack-repo-mode — detect solo vs collaborative repo mode
+# Usage: source <(gstack-repo-mode)  → sets REPO_MODE variable
+# Or:    gstack-repo-mode           → prints REPO_MODE=... line
+#
+# Detection heuristic (90-day window):
+#   Solo:          top author >= 80% of commits
+#   Collaborative: top author < 80%
+#
+# Override: gstack-config set repo_mode solo|collaborative
+# Cache:    ~/.gstack/projects/$SLUG/repo-mode.json (7-day TTL)
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# Compute SLUG directly (avoid eval of gstack-slug — branch names can contain shell metacharacters)
+REMOTE_URL=$(git remote get-url origin 2>/dev/null || true)
+if [ -z "$REMOTE_URL" ]; then
+  echo "REPO_MODE=unknown"
+  exit 0
+fi
+SLUG=$(echo "$REMOTE_URL" | sed 's|.*[:/]\([^/]*/[^/]*\)\.git$|\1|;s|.*[:/]\([^/]*/[^/]*\)$|\1|' | tr '/' '-')
+[ -z "${SLUG:-}" ] && { echo "REPO_MODE=unknown"; exit 0; }
+
+# Validate: only allow known values (prevent shell injection via source <(...))
+validate_mode() {
+  case "$1" in solo|collaborative|unknown) echo "$1" ;; *) echo "unknown" ;; esac
+}
+
+# Config override takes precedence
+OVERRIDE=$("$SCRIPT_DIR/gstack-config" get repo_mode 2>/dev/null || true)
+if [ -n "$OVERRIDE" ] && [ "$OVERRIDE" != "null" ]; then
+  echo "REPO_MODE=$(validate_mode "$OVERRIDE")"
+  exit 0
+fi
+
+# Check cache (7-day TTL)
+CACHE_DIR="$HOME/.gstack/projects/$SLUG"
+CACHE_FILE="$CACHE_DIR/repo-mode.json"
+if [ -f "$CACHE_FILE" ]; then
+  CACHE_AGE=$(( $(date +%s) - $(stat -f %m "$CACHE_FILE" 2>/dev/null || stat -c %Y "$CACHE_FILE" 2>/dev/null || echo 0) ))
+  if [ "$CACHE_AGE" -lt 604800 ]; then  # 7 days in seconds
+    MODE=$(grep -o '"mode":"[^"]*"' "$CACHE_FILE" | head -1 | cut -d'"' -f4)
+    [ -n "$MODE" ] && echo "REPO_MODE=$(validate_mode "$MODE")" && exit 0
+  fi
+fi
+
+# Compute from git history (90-day window)
+# Use default branch (not HEAD) to avoid feature-branch sampling bias
+DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/||' || true)
+# Fallback: try origin/main, then origin/master, then HEAD
+if [ -z "$DEFAULT_BRANCH" ]; then
+  if git rev-parse --verify origin/main &>/dev/null; then
+    DEFAULT_BRANCH="origin/main"
+  elif git rev-parse --verify origin/master &>/dev/null; then
+    DEFAULT_BRANCH="origin/master"
+  else
+    DEFAULT_BRANCH="HEAD"
+  fi
+fi
+SHORTLOG=$(git shortlog -sn --since="90 days ago" --no-merges "$DEFAULT_BRANCH" 2>/dev/null)
+if [ -z "$SHORTLOG" ]; then
+  echo "REPO_MODE=unknown"
+  exit 0
+fi
+
+# Compute TOTAL from ALL authors (not truncated) to avoid solo bias
+TOTAL=$(echo "$SHORTLOG" | awk '{s+=$1} END {print s}')
+TOP=$(echo "$SHORTLOG" | head -1 | awk '{print $1}')
+AUTHORS=$(echo "$SHORTLOG" | wc -l | tr -d ' ')
+
+# Minimum sample: need at least 5 commits to classify
+if [ "$TOTAL" -lt 5 ]; then
+  echo "REPO_MODE=unknown"
+  exit 0
+fi
+
+TOP_PCT=$(( TOP * 100 / TOTAL ))
+
+# Solo: top author >= 80% of commits (occasional outside PRs don't change mode)
+if [ "$TOP_PCT" -ge 80 ]; then
+  MODE=solo
+else
+  MODE=collaborative
+fi
+
+# Cache result atomically (fail silently if ~/.gstack is unwritable)
+mkdir -p "$CACHE_DIR" 2>/dev/null || true
+CACHE_TMP=$(mktemp "$CACHE_DIR/.repo-mode-XXXXXX" 2>/dev/null || true)
+if [ -n "$CACHE_TMP" ]; then
+  echo "{\"mode\":\"$MODE\",\"top_pct\":$TOP_PCT,\"authors\":$AUTHORS,\"total\":$TOTAL,\"computed\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}" > "$CACHE_TMP" 2>/dev/null && mv "$CACHE_TMP" "$CACHE_FILE" 2>/dev/null || rm -f "$CACHE_TMP" 2>/dev/null
+fi
+
+echo "REPO_MODE=$MODE"

bin/gstack-review-log

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# gstack-review-log — atomically log a review result
+# Usage: gstack-review-log '{"skill":"...","timestamp":"...","status":"..."}'
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+eval "$("$SCRIPT_DIR/gstack-slug" 2>/dev/null)"
+GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
+mkdir -p "$GSTACK_HOME/projects/$SLUG"
+
+# Validate: input must be parseable JSON (reject malformed or injection attempts)
+INPUT="$1"
+if ! printf '%s' "$INPUT" | bun -e "JSON.parse(await Bun.stdin.text())" 2>/dev/null; then
+  # Not valid JSON — refuse to append
+  echo "gstack-review-log: invalid JSON, skipping" >&2
+  exit 1
+fi
+
+echo "$INPUT" >> "$GSTACK_HOME/projects/$SLUG/$BRANCH-reviews.jsonl"
+
+# gbrain-sync: enqueue for cross-machine sync (no-op if sync is off).
+"$SCRIPT_DIR/gstack-brain-enqueue" "projects/$SLUG/$BRANCH-reviews.jsonl" 2>/dev/null &

bin/gstack-review-read

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+# gstack-review-read — read review log and config for dashboard
+# Usage: gstack-review-read
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+eval "$("$SCRIPT_DIR/gstack-slug" 2>/dev/null)"
+GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
+cat "$GSTACK_HOME/projects/$SLUG/$BRANCH-reviews.jsonl" 2>/dev/null || echo "NO_REVIEWS"
+echo "---CONFIG---"
+"$SCRIPT_DIR/gstack-config" get skip_eng_review 2>/dev/null || echo "false"
+echo "---HEAD---"
+git rev-parse --short HEAD 2>/dev/null || echo "unknown"

bin/gstack-security-dashboard

@@ -0,0 +1,121 @@
+#!/usr/bin/env bash
+# gstack-security-dashboard — community prompt-injection attack stats
+#
+# Reads the `security` section of the community-pulse edge function response
+# (supabase/functions/community-pulse/index.ts). Shows aggregated attack
+# data across all gstack users on telemetry=community.
+#
+# Call signature:
+#   gstack-security-dashboard           # human-readable dashboard
+#   gstack-security-dashboard --json    # machine-readable (CI / scripts)
+#
+# Env overrides (for testing):
+#   GSTACK_DIR                    — override auto-detected gstack root
+#   GSTACK_SUPABASE_URL           — override Supabase project URL
+#   GSTACK_SUPABASE_ANON_KEY     — override Supabase anon key
+set -uo pipefail
+
+GSTACK_DIR="${GSTACK_DIR:-$(cd "$(dirname "$0")/.." && pwd)}"
+
+# Source Supabase config
+if [ -z "${GSTACK_SUPABASE_URL:-}" ] && [ -f "$GSTACK_DIR/supabase/config.sh" ]; then
+  . "$GSTACK_DIR/supabase/config.sh"
+fi
+SUPABASE_URL="${GSTACK_SUPABASE_URL:-}"
+ANON_KEY="${GSTACK_SUPABASE_ANON_KEY:-}"
+
+JSON_MODE=0
+[ "${1:-}" = "--json" ] && JSON_MODE=1
+
+if [ -z "$SUPABASE_URL" ] || [ -z "$ANON_KEY" ]; then
+  if [ "$JSON_MODE" = "1" ]; then
+    echo '{"error":"supabase_not_configured"}'
+    exit 0
+  fi
+  echo "gstack security dashboard"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo ""
+  echo "Supabase not configured. Local log at ~/.gstack/security/attempts.jsonl"
+  echo "still captures every attempt — tail it with:"
+  echo "  cat ~/.gstack/security/attempts.jsonl | tail -20"
+  exit 0
+fi
+
+DATA="$(curl -sf --max-time 15 \
+  "${SUPABASE_URL}/functions/v1/community-pulse" \
+  -H "apikey: ${ANON_KEY}" \
+  2>/dev/null || echo "{}")"
+
+# Extract the security section. Prefer jq for brace-balanced parsing of
+# nested arrays/objects (top_attack_domains etc.). Fall back to regex if
+# jq isn't installed — the regex is lossy but the dashboard degrades
+# gracefully to "0 attacks" rather than misreporting numbers.
+if command -v jq >/dev/null 2>&1; then
+  SEC_SECTION="$(echo "$DATA" | jq -rc '.security // empty | "\"security\":\(.)"' 2>/dev/null || echo "")"
+else
+  SEC_SECTION="$(echo "$DATA" | grep -o '"security":{[^}]*}' 2>/dev/null || echo "")"
+fi
+
+if [ "$JSON_MODE" = "1" ]; then
+  # Machine-readable — echo the whole security section (or empty object)
+  if [ -n "$SEC_SECTION" ]; then
+    echo "{${SEC_SECTION}}"
+  else
+    echo '{"security":{"attacks_last_7_days":0,"top_attack_domains":[],"top_attack_layers":[],"verdict_distribution":[]}}'
+  fi
+  exit 0
+fi
+
+# Human-readable dashboard
+echo "gstack security dashboard"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+
+TOTAL="$(echo "$DATA" | grep -o '"attacks_last_7_days":[0-9]*' | grep -o '[0-9]*' | head -1 || echo "0")"
+echo "Attacks detected last 7 days: ${TOTAL}"
+if [ "$TOTAL" = "0" ]; then
+  echo "  (No attack attempts reported by the community yet. Good news.)"
+fi
+echo ""
+
+# Top attacked domains — parse objects inside top_attack_domains array
+DOMAINS="$(echo "$DATA" | sed -n 's/.*"top_attack_domains":\(\[[^]]*\]\).*/\1/p' | head -1)"
+if [ -n "$DOMAINS" ] && [ "$DOMAINS" != "[]" ]; then
+  echo "Top attacked domains"
+  echo "────────────────────"
+  echo "$DOMAINS" | grep -o '{[^}]*}' | head -10 | while read -r OBJ; do
+    DOMAIN="$(echo "$OBJ" | grep -o '"domain":"[^"]*"' | awk -F'"' '{print $4}')"
+    COUNT="$(echo "$OBJ" | grep -o '"count":[0-9]*' | grep -o '[0-9]*')"
+    [ -n "$DOMAIN" ] && [ -n "$COUNT" ] && printf "  %-40s %s attempts\n" "$DOMAIN" "$COUNT"
+  done
+  echo ""
+fi
+
+# Which layer catches attacks
+LAYERS="$(echo "$DATA" | sed -n 's/.*"top_attack_layers":\(\[[^]]*\]\).*/\1/p' | head -1)"
+if [ -n "$LAYERS" ] && [ "$LAYERS" != "[]" ]; then
+  echo "Top detection layers"
+  echo "────────────────────"
+  echo "$LAYERS" | grep -o '{[^}]*}' | while read -r OBJ; do
+    LAYER="$(echo "$OBJ" | grep -o '"layer":"[^"]*"' | awk -F'"' '{print $4}')"
+    COUNT="$(echo "$OBJ" | grep -o '"count":[0-9]*' | grep -o '[0-9]*')"
+    [ -n "$LAYER" ] && [ -n "$COUNT" ] && printf "  %-28s %s\n" "$LAYER" "$COUNT"
+  done
+  echo ""
+fi
+
+# Verdict distribution
+VERDICTS="$(echo "$DATA" | sed -n 's/.*"verdict_distribution":\(\[[^]]*\]\).*/\1/p' | head -1)"
+if [ -n "$VERDICTS" ] && [ "$VERDICTS" != "[]" ]; then
+  echo "Verdict distribution"
+  echo "────────────────────"
+  echo "$VERDICTS" | grep -o '{[^}]*}' | while read -r OBJ; do
+    VERDICT="$(echo "$OBJ" | grep -o '"verdict":"[^"]*"' | awk -F'"' '{print $4}')"
+    COUNT="$(echo "$OBJ" | grep -o '"count":[0-9]*' | grep -o '[0-9]*')"
+    [ -n "$VERDICT" ] && [ -n "$COUNT" ] && printf "  %-14s %s\n" "$VERDICT" "$COUNT"
+  done
+  echo ""
+fi
+
+echo "Your local log: ~/.gstack/security/attempts.jsonl"
+echo "Your telemetry mode: $(${GSTACK_DIR}/bin/gstack-config get telemetry 2>/dev/null || echo unknown)"

bin/gstack-session-update

@@ -0,0 +1,116 @@
+#!/usr/bin/env bash
+# gstack-session-update — auto-update gstack on session start (team mode)
+#
+# Called by Claude Code SessionStart hook. Must be fast, silent, non-fatal.
+# The entire update runs in background (forked). The hook itself exits
+# immediately so session startup is never delayed.
+#
+# Exit 0 always — errors must never block a Claude Code session.
+
+set +e
+
+GSTACK_DIR="${GSTACK_DIR:-$HOME/.claude/skills/gstack}"
+STATE_DIR="${GSTACK_STATE_DIR:-$HOME/.gstack}"
+THROTTLE_FILE="$STATE_DIR/.last-session-update"
+LOCK_DIR="$STATE_DIR/.setup-lock"
+LOG_FILE="$STATE_DIR/analytics/session-update.log"
+THROTTLE_SECONDS=3600  # 1 hour
+
+log_entry() {
+  mkdir -p "$(dirname "$LOG_FILE")"
+  echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) $1" >> "$LOG_FILE" 2>/dev/null || true
+}
+
+# ── Guard: gstack must be a git repo ──
+if [ ! -d "$GSTACK_DIR/.git" ]; then
+  exit 0
+fi
+
+# ── Guard: team mode must be enabled ──
+AUTO=$("$GSTACK_DIR/bin/gstack-config" get auto_upgrade 2>/dev/null || true)
+if [ "$AUTO" != "true" ]; then
+  exit 0
+fi
+
+# ── Throttle: skip if checked recently ──
+if [ -f "$THROTTLE_FILE" ]; then
+  LAST=$(cat "$THROTTLE_FILE" 2>/dev/null || echo 0)
+  NOW=$(date +%s)
+  ELAPSED=$(( NOW - LAST ))
+  if [ "$ELAPSED" -lt "$THROTTLE_SECONDS" ]; then
+    exit 0
+  fi
+fi
+
+# ── Fork to background: zero latency on session start ──
+(
+  # Prevent git from prompting for credentials (would hang the background process)
+  export GIT_TERMINAL_PROMPT=0
+
+  mkdir -p "$STATE_DIR"
+
+  # ── Acquire lockfile (skip if another session is running setup) ──
+  if ! mkdir "$LOCK_DIR" 2>/dev/null; then
+    # Lock exists — check if stale (PID dead)
+    if [ -f "$LOCK_DIR/pid" ]; then
+      LOCK_PID=$(cat "$LOCK_DIR/pid" 2>/dev/null || echo 0)
+      if [ "$LOCK_PID" -gt 0 ] 2>/dev/null && ! kill -0 "$LOCK_PID" 2>/dev/null; then
+        # Stale lock — remove and re-acquire
+        rm -rf "$LOCK_DIR" 2>/dev/null
+        mkdir "$LOCK_DIR" 2>/dev/null || { log_entry "SKIP lock_contested"; exit 0; }
+      else
+        log_entry "SKIP locked_by=$LOCK_PID"
+        exit 0
+      fi
+    else
+      log_entry "SKIP locked_no_pid"
+      exit 0
+    fi
+  fi
+
+  # Write PID for stale lock detection
+  echo $$ > "$LOCK_DIR/pid" 2>/dev/null
+
+  # Clean up lock on exit
+  trap 'rm -rf "$LOCK_DIR" 2>/dev/null' EXIT
+
+  # ── Pull latest ──
+  OLD_HEAD=$(git -C "$GSTACK_DIR" rev-parse HEAD 2>/dev/null)
+  git -C "$GSTACK_DIR" pull --ff-only -q 2>/dev/null
+  PULL_EXIT=$?
+  NEW_HEAD=$(git -C "$GSTACK_DIR" rev-parse HEAD 2>/dev/null)
+
+  # Record check time regardless of outcome
+  date +%s > "$THROTTLE_FILE" 2>/dev/null
+
+  if [ "$PULL_EXIT" -ne 0 ]; then
+    log_entry "PULL_FAILED exit=$PULL_EXIT"
+    exit 0
+  fi
+
+  # ── If HEAD moved, run setup -q ──
+  if [ "$OLD_HEAD" != "$NEW_HEAD" ]; then
+    log_entry "UPDATING old=$OLD_HEAD new=$NEW_HEAD"
+
+    # bun must be available for setup
+    if command -v bun >/dev/null 2>&1; then
+      ( cd "$GSTACK_DIR" && ./setup -q ) >/dev/null 2>&1 || {
+        log_entry "SETUP_FAILED"
+      }
+    else
+      log_entry "SETUP_SKIPPED bun_missing"
+    fi
+
+    # Write marker so next skill preamble shows "just upgraded"
+    OLD_VER=$(git -C "$GSTACK_DIR" show "$OLD_HEAD:VERSION" 2>/dev/null || echo "unknown")
+    echo "$OLD_VER" > "$STATE_DIR/just-upgraded-from" 2>/dev/null
+    rm -f "$STATE_DIR/last-update-check" 2>/dev/null
+    rm -f "$STATE_DIR/update-snoozed" 2>/dev/null
+
+    log_entry "UPDATED from=$OLD_VER to=$(cat "$GSTACK_DIR/VERSION" 2>/dev/null || echo unknown)"
+  else
+    log_entry "UP_TO_DATE head=$OLD_HEAD"
+  fi
+) &
+
+exit 0

bin/gstack-settings-hook

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+# gstack-settings-hook — add/remove SessionStart hooks in Claude Code settings.json
+#
+# Usage:
+#   gstack-settings-hook add <hook-command>     # add SessionStart hook
+#   gstack-settings-hook remove <hook-command>  # remove SessionStart hook
+#
+# Requires: bun (already a gstack hard dependency)
+# Writes atomically: .tmp + rename to prevent corruption on crash/disk-full.
+
+set -euo pipefail
+
+ACTION="${1:-}"
+HOOK_CMD="${2:-}"
+SETTINGS_FILE="${GSTACK_SETTINGS_FILE:-$HOME/.claude/settings.json}"
+
+if [ -z "$ACTION" ] || [ -z "$HOOK_CMD" ]; then
+  echo "Usage: gstack-settings-hook {add|remove} <hook-command>" >&2
+  exit 1
+fi
+
+if ! command -v bun >/dev/null 2>&1; then
+  echo "Error: bun is required but not installed." >&2
+  exit 1
+fi
+
+case "$ACTION" in
+  add)
+    GSTACK_SETTINGS_PATH="$SETTINGS_FILE" GSTACK_HOOK_CMD="$HOOK_CMD" bun -e "
+      const fs = require('fs');
+      const settingsPath = process.env.GSTACK_SETTINGS_PATH;
+      const hookCmd = process.env.GSTACK_HOOK_CMD;
+
+      let settings = {};
+      try { settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8')); } catch {}
+
+      if (!settings.hooks) settings.hooks = {};
+      if (!settings.hooks.SessionStart) settings.hooks.SessionStart = [];
+
+      // Dedup: check if hook command already registered
+      const exists = settings.hooks.SessionStart.some(entry =>
+        entry.hooks && entry.hooks.some(h => h.command && h.command.includes('gstack-session-update'))
+      );
+
+      if (!exists) {
+        settings.hooks.SessionStart.push({
+          hooks: [{ type: 'command', command: hookCmd }]
+        });
+      }
+
+      const tmp = settingsPath + '.tmp';
+      fs.writeFileSync(tmp, JSON.stringify(settings, null, 2) + '\n');
+      fs.renameSync(tmp, settingsPath);
+    " 2>/dev/null
+    ;;
+  remove)
+    [ -f "$SETTINGS_FILE" ] || exit 1
+    GSTACK_SETTINGS_PATH="$SETTINGS_FILE" bun -e "
+      const fs = require('fs');
+      const settingsPath = process.env.GSTACK_SETTINGS_PATH;
+
+      let settings = {};
+      try { settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8')); } catch { process.exit(0); }
+
+      if (settings.hooks && settings.hooks.SessionStart) {
+        settings.hooks.SessionStart = settings.hooks.SessionStart.filter(entry =>
+          !(entry.hooks && entry.hooks.some(h => h.command && h.command.includes('gstack-session-update')))
+        );
+        if (settings.hooks.SessionStart.length === 0) delete settings.hooks.SessionStart;
+        if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+      }
+
+      const tmp = settingsPath + '.tmp';
+      fs.writeFileSync(tmp, JSON.stringify(settings, null, 2) + '\n');
+      fs.renameSync(tmp, settingsPath);
+    " 2>/dev/null
+    ;;
+  *)
+    echo "Unknown action: $ACTION (expected add or remove)" >&2
+    exit 1
+    ;;
+esac

bin/gstack-slug

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# gstack-slug — output project slug and sanitized branch name
+# Usage: eval "$(gstack-slug)"  → sets SLUG and BRANCH variables
+# Or:    gstack-slug            → prints SLUG=... and BRANCH=... lines
+#
+# Security: output is sanitized to [a-zA-Z0-9._-] only, preventing
+# shell injection when consumed via source or eval.
+set -euo pipefail
+
+CACHE_DIR="$HOME/.gstack/slug-cache"
+PROJECT_DIR="$(pwd)"
+# Encode absolute path as cache key: /Users/j/foo → _Users_j_foo
+CACHE_KEY=$(printf '%s' "$PROJECT_DIR" | tr '/' '_')
+CACHE_FILE="${CACHE_DIR}/${CACHE_KEY}"
+
+# 1. Try cached slug first (guarantees consistency across sessions)
+if [[ -f "$CACHE_FILE" ]]; then
+  SLUG=$(cat "$CACHE_FILE")
+fi
+
+# 2. If no cache, compute from git remote (separated from pipeline to avoid
+#    pipefail swallowing the error and producing an empty slug)
+if [[ -z "${SLUG:-}" ]]; then
+  REMOTE_URL=$(git remote get-url origin 2>/dev/null) || REMOTE_URL=""
+  if [[ -n "$REMOTE_URL" ]]; then
+    RAW_SLUG=$(printf '%s' "$REMOTE_URL" | sed 's|.*[:/]\([^/]*/[^/]*\)\.git$|\1|;s|.*[:/]\([^/]*/[^/]*\)$|\1|' | tr '/' '-')
+    SLUG=$(printf '%s' "$RAW_SLUG" | tr -cd 'a-zA-Z0-9._-')
+  fi
+fi
+
+# 3. Fallback to basename only when there's truly no git remote configured
+SLUG="${SLUG:-$(basename "$PWD" | tr -cd 'a-zA-Z0-9._-')}"
+
+# 4. Cache the slug for future sessions (atomic write, fail silently)
+if [[ -n "$SLUG" ]]; then
+  mkdir -p "$CACHE_DIR" 2>/dev/null || true
+  CACHE_TMP=$(mktemp "$CACHE_DIR/.slug-XXXXXX" 2>/dev/null) || CACHE_TMP=""
+  if [[ -n "$CACHE_TMP" ]]; then
+    printf '%s' "$SLUG" > "$CACHE_TMP" && mv "$CACHE_TMP" "$CACHE_FILE" 2>/dev/null || rm -f "$CACHE_TMP" 2>/dev/null
+  fi
+fi
+
+RAW_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null) || RAW_BRANCH=""
+BRANCH=$(printf '%s' "${RAW_BRANCH:-}" | tr -cd 'a-zA-Z0-9._-')
+BRANCH="${BRANCH:-unknown}"
+echo "SLUG=$SLUG"
+echo "BRANCH=$BRANCH"

bin/gstack-specialist-stats

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# gstack-specialist-stats — compute per-specialist hit rates from review history
+# Usage: gstack-specialist-stats
+#
+# Reads all *-reviews.jsonl files across branches, parses specialist fields,
+# and outputs hit rates. Tags specialists as GATE_CANDIDATE (0 findings in 10+
+# dispatches) or NEVER_GATE (security, data-migration — insurance policy).
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+eval "$("$SCRIPT_DIR/gstack-slug" 2>/dev/null)"
+GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
+PROJECT_DIR="$GSTACK_HOME/projects/$SLUG"
+
+if [ ! -d "$PROJECT_DIR" ]; then
+  echo "SPECIALIST_STATS: 0 reviews analyzed"
+  exit 0
+fi
+
+# Collect all review JSONL files (strip ---CONFIG--- and ---HEAD--- footers)
+COMBINED=""
+for f in "$PROJECT_DIR"/*-reviews.jsonl; do
+  [ -f "$f" ] || continue
+  COMBINED="$COMBINED$(sed '/^---/,$d' "$f" 2>/dev/null)
+"
+done
+
+if [ -z "$COMBINED" ]; then
+  echo "SPECIALIST_STATS: 0 reviews analyzed"
+  exit 0
+fi
+
+printf '%s' "$COMBINED" | bun -e "
+const lines = (await Bun.stdin.text()).trim().split('\n').filter(Boolean);
+const NEVER_GATE = new Set(['security', 'data-migration']);
+const stats = {};
+let reviewed = 0;
+
+for (const line of lines) {
+  try {
+    const e = JSON.parse(line);
+    if (!e.specialists) continue;
+    reviewed++;
+    for (const [name, info] of Object.entries(e.specialists)) {
+      if (!stats[name]) stats[name] = { dispatched: 0, findings: 0 };
+      if (info.dispatched) {
+        stats[name].dispatched++;
+        stats[name].findings += (info.findings || 0);
+      }
+    }
+  } catch {}
+}
+
+console.log('SPECIALIST_STATS: ' + reviewed + ' reviews analyzed');
+const sorted = Object.entries(stats).sort((a, b) => a[0].localeCompare(b[0]));
+for (const [name, s] of sorted) {
+  const pct = s.dispatched > 0 ? Math.round(100 * s.findings / s.dispatched) : 0;
+  let tag = '';
+  if (NEVER_GATE.has(name)) {
+    tag = ' [NEVER_GATE]';
+  } else if (s.dispatched >= 10 && s.findings === 0) {
+    tag = ' [GATE_CANDIDATE]';
+  }
+  console.log(name + ': ' + s.dispatched + '/' + reviewed + ' dispatched, ' + s.findings + ' findings (' + pct + '%)' + tag);
+}
+" 2>/dev/null || { echo "SPECIALIST_STATS: 0 reviews analyzed"; exit 0; }

bin/gstack-taste-update

@@ -0,0 +1,293 @@
+#!/usr/bin/env bun
+// gstack-taste-update — update the persistent taste profile at
+// ~/.gstack/projects/$SLUG/taste-profile.json
+//
+// Usage:
+//   gstack-taste-update approved <variant-path> [--reason "<why>"]
+//   gstack-taste-update rejected <variant-path> [--reason "<why>"]
+//   gstack-taste-update show                       — print current profile summary
+//   gstack-taste-update migrate                    — upgrade legacy approved.json to v1
+//
+// Schema v1 at ~/.gstack/projects/$SLUG/taste-profile.json:
+//
+//   {
+//     "version": 1,
+//     "updated_at": "<ISO 8601>",
+//     "dimensions": {
+//       "fonts":      { "approved": [...], "rejected": [...] },
+//       "colors":     { "approved": [...], "rejected": [...] },
+//       "layouts":    { "approved": [...], "rejected": [...] },
+//       "aesthetics": { "approved": [...], "rejected": [...] }
+//     },
+//     "sessions": [  // last 50 only — truncated via decay
+//       { "ts": "<ISO>", "action": "approved"|"rejected", "variant": "<path>", "reason": "<optional>" }
+//     ]
+//   }
+//
+// Each Preference entry:
+//   { value: string, confidence: number (0-1), approved_count, rejected_count, last_seen }
+//
+// Confidence is computed with Laplace smoothing + 5% weekly decay at read time.
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { execSync } from 'child_process';
+
+const STATE_DIR = process.env.GSTACK_STATE_DIR || path.join(process.env.HOME || '/', '.gstack');
+const SCHEMA_VERSION = 1;
+const SESSION_CAP = 50;
+const DECAY_PER_WEEK = 0.05;
+
+type Dimension = 'fonts' | 'colors' | 'layouts' | 'aesthetics';
+const DIMENSIONS: Dimension[] = ['fonts', 'colors', 'layouts', 'aesthetics'];
+
+interface Preference {
+  value: string;
+  confidence: number;
+  approved_count: number;
+  rejected_count: number;
+  last_seen: string;
+}
+
+interface SessionRecord {
+  ts: string;
+  action: 'approved' | 'rejected';
+  variant: string;
+  reason?: string;
+}
+
+interface TasteProfile {
+  version: number;
+  updated_at: string;
+  dimensions: Record<Dimension, { approved: Preference[]; rejected: Preference[] }>;
+  sessions: SessionRecord[];
+}
+
+function getSlug(): string {
+  try {
+    const output = execSync('git rev-parse --show-toplevel', { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+    return path.basename(output);
+  } catch {
+    return 'unknown';
+  }
+}
+
+function profilePath(slug: string): string {
+  return path.join(STATE_DIR, 'projects', slug, 'taste-profile.json');
+}
+
+function emptyProfile(): TasteProfile {
+  return {
+    version: SCHEMA_VERSION,
+    updated_at: new Date().toISOString(),
+    dimensions: {
+      fonts: { approved: [], rejected: [] },
+      colors: { approved: [], rejected: [] },
+      layouts: { approved: [], rejected: [] },
+      aesthetics: { approved: [], rejected: [] },
+    },
+    sessions: [],
+  };
+}
+
+function load(slug: string): TasteProfile {
+  const p = profilePath(slug);
+  if (!fs.existsSync(p)) return emptyProfile();
+  try {
+    const raw = JSON.parse(fs.readFileSync(p, 'utf-8'));
+    if (!raw.version || raw.version < SCHEMA_VERSION) {
+      return migrate(raw);
+    }
+    return raw as TasteProfile;
+  } catch (err) {
+    console.error(`WARN: could not parse ${p}:`, (err as Error).message);
+    return emptyProfile();
+  }
+}
+
+function save(slug: string, profile: TasteProfile): void {
+  const p = profilePath(slug);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  profile.updated_at = new Date().toISOString();
+  fs.writeFileSync(p, JSON.stringify(profile, null, 2) + '\n');
+}
+
+/**
+ * Migrate a legacy profile (no version or version < SCHEMA_VERSION) into the
+ * current schema, preserving data where possible. Legacy approved.json aggregates
+ * get normalized into empty-but-valid v1 profiles so the next write populates them.
+ */
+function migrate(legacy: unknown): TasteProfile {
+  const fresh = emptyProfile();
+  if (legacy && typeof legacy === 'object') {
+    const anyLegacy = legacy as Record<string, unknown>;
+    // Preserve sessions if present
+    if (Array.isArray(anyLegacy.sessions)) {
+      fresh.sessions = anyLegacy.sessions.slice(-SESSION_CAP) as SessionRecord[];
+    }
+    // Preserve dimensions if present and well-formed
+    if (anyLegacy.dimensions && typeof anyLegacy.dimensions === 'object') {
+      for (const dim of DIMENSIONS) {
+        const src = (anyLegacy.dimensions as Record<string, unknown>)[dim];
+        if (src && typeof src === 'object') {
+          const ss = src as Record<string, unknown>;
+          if (Array.isArray(ss.approved)) fresh.dimensions[dim].approved = ss.approved as Preference[];
+          if (Array.isArray(ss.rejected)) fresh.dimensions[dim].rejected = ss.rejected as Preference[];
+        }
+      }
+    }
+  }
+  return fresh;
+}
+
+/**
+ * Apply 5% per-week decay to confidence values at read/show time.
+ * Returns a copy; does NOT mutate or persist the input.
+ */
+function applyDecay(profile: TasteProfile): TasteProfile {
+  const now = Date.now();
+  const decayed = JSON.parse(JSON.stringify(profile)) as TasteProfile;
+  for (const dim of DIMENSIONS) {
+    for (const bucket of ['approved', 'rejected'] as const) {
+      for (const pref of decayed.dimensions[dim][bucket]) {
+        const lastSeen = new Date(pref.last_seen).getTime();
+        const weeks = Math.max(0, (now - lastSeen) / (7 * 24 * 60 * 60 * 1000));
+        pref.confidence = Math.max(0, pref.confidence * Math.pow(1 - DECAY_PER_WEEK, weeks));
+      }
+    }
+  }
+  return decayed;
+}
+
+/**
+ * Extract dimension values from a variant description. V1 keeps this simple:
+ * the variant is a path/name like "variant-A" — we can't extract real design
+ * tokens without the mockup's metadata. Callers should pass a reason string
+ * that mentions fonts/colors/layouts/aesthetics. If the reason is missing,
+ * the session is recorded but dimensions don't get updated.
+ *
+ * Future v2: parse the variant PNG's EXIF, or read an accompanying manifest
+ * that design-shotgun writes next to each variant.
+ */
+function extractSignals(reason?: string): Partial<Record<Dimension, string[]>> {
+  if (!reason) return {};
+  const out: Partial<Record<Dimension, string[]>> = {};
+  // naive pattern: "fonts: X, Y; colors: Z" — split by dimension label
+  const labelRe = /(fonts|colors|layouts|aesthetics):\s*([^;]+)/gi;
+  let m: RegExpExecArray | null;
+  while ((m = labelRe.exec(reason)) !== null) {
+    const dim = m[1].toLowerCase() as Dimension;
+    const values = m[2].split(',').map(s => s.trim()).filter(Boolean);
+    out[dim] = values;
+  }
+  return out;
+}
+
+function bumpPref(list: Preference[], value: string, opposite: Preference[], action: 'approved' | 'rejected'): Preference[] {
+  const now = new Date().toISOString();
+  let entry = list.find(p => p.value.toLowerCase() === value.toLowerCase());
+  if (!entry) {
+    entry = { value, confidence: 0, approved_count: 0, rejected_count: 0, last_seen: now };
+    list.push(entry);
+  }
+  if (action === 'approved') {
+    entry.approved_count += 1;
+  } else {
+    entry.rejected_count += 1;
+  }
+  entry.last_seen = now;
+  // Laplace-smoothed confidence
+  const total = entry.approved_count + entry.rejected_count;
+  entry.confidence = entry.approved_count / (total + 1);
+  // Flag conflict if the opposite bucket has a strong entry for this value
+  const opp = opposite.find(p => p.value.toLowerCase() === value.toLowerCase());
+  if (opp && opp.approved_count + opp.rejected_count >= 3 && opp.confidence >= 0.6) {
+    console.error(`NOTE: taste drift — "${value}" previously ${action === 'approved' ? 'rejected' : 'approved'} with confidence ${opp.confidence.toFixed(2)}. Keep both signals; aggregate confidence will rebalance.`);
+  }
+  return list;
+}
+
+function cmdUpdate(action: 'approved' | 'rejected', variant: string, reason?: string): void {
+  const slug = getSlug();
+  const profile = load(slug);
+  const signals = extractSignals(reason);
+
+  for (const dim of DIMENSIONS) {
+    const values = signals[dim];
+    if (!values) continue;
+    const bucket = profile.dimensions[dim][action];
+    const opposite = profile.dimensions[dim][action === 'approved' ? 'rejected' : 'approved'];
+    for (const v of values) bumpPref(bucket, v, opposite, action);
+  }
+
+  // Always record the session even if no dimensions were extracted
+  profile.sessions.push({ ts: new Date().toISOString(), action, variant, reason });
+  // Truncate sessions to last SESSION_CAP entries (FIFO)
+  if (profile.sessions.length > SESSION_CAP) {
+    profile.sessions = profile.sessions.slice(-SESSION_CAP);
+  }
+
+  save(slug, profile);
+  console.log(`${action}: ${variant} → ${profilePath(slug)}`);
+}
+
+function cmdShow(): void {
+  const slug = getSlug();
+  const profile = applyDecay(load(slug));
+  console.log(`taste-profile.json (slug: ${slug}, sessions: ${profile.sessions.length})`);
+  for (const dim of DIMENSIONS) {
+    const top = [...profile.dimensions[dim].approved]
+      .sort((a, b) => b.confidence * b.approved_count - a.confidence * a.approved_count)
+      .slice(0, 3);
+    const topRej = [...profile.dimensions[dim].rejected]
+      .sort((a, b) => b.confidence * b.rejected_count - a.confidence * a.rejected_count)
+      .slice(0, 3);
+    if (top.length || topRej.length) {
+      console.log(`\n[${dim}]`);
+      if (top.length) {
+        console.log('  approved (decayed):');
+        for (const p of top) console.log(`    ${p.value} — conf ${p.confidence.toFixed(2)} (+${p.approved_count}/-${p.rejected_count})`);
+      }
+      if (topRej.length) {
+        console.log('  rejected:');
+        for (const p of topRej) console.log(`    ${p.value} — conf ${p.confidence.toFixed(2)} (+${p.approved_count}/-${p.rejected_count})`);
+      }
+    }
+  }
+}
+
+function cmdMigrate(): void {
+  const slug = getSlug();
+  const profile = load(slug);
+  save(slug, profile);
+  console.log(`migrated taste profile to v${SCHEMA_VERSION} at ${profilePath(slug)}`);
+}
+
+// ─── CLI entry ────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+const cmd = args[0];
+
+switch (cmd) {
+  case 'approved':
+  case 'rejected': {
+    const variant = args[1];
+    if (!variant) {
+      console.error(`Usage: gstack-taste-update ${cmd} <variant-path> [--reason "<why>"]`);
+      process.exit(1);
+    }
+    const reasonIdx = args.indexOf('--reason');
+    const reason = reasonIdx >= 0 ? args[reasonIdx + 1] : undefined;
+    cmdUpdate(cmd as 'approved' | 'rejected', variant, reason);
+    break;
+  }
+  case 'show':
+    cmdShow();
+    break;
+  case 'migrate':
+    cmdMigrate();
+    break;
+  default:
+    console.error('Usage: gstack-taste-update {approved|rejected|show|migrate} [args]');
+    process.exit(1);
+}

bin/gstack-team-init

@@ -0,0 +1,192 @@
+#!/usr/bin/env bash
+# gstack-team-init — generate repo-level bootstrap files for team mode
+#
+# Usage:
+#   gstack-team-init optional   # gentle CLAUDE.md suggestion, one-time offer
+#   gstack-team-init required   # CLAUDE.md enforcement + PreToolUse hook
+#
+# Run from the root of your team's repo (not from the gstack directory).
+
+set -euo pipefail
+
+MODE="${1:-}"
+
+if [ "$MODE" != "optional" ] && [ "$MODE" != "required" ]; then
+  echo "Usage: gstack-team-init {optional|required}" >&2
+  echo "" >&2
+  echo "  optional  — suggest gstack install once per developer (gentle)" >&2
+  echo "  required  — enforce gstack install, block work without it" >&2
+  exit 1
+fi
+
+# Must be in a git repo
+if ! git rev-parse --show-toplevel >/dev/null 2>&1; then
+  echo "Error: not in a git repository. Run from your project root." >&2
+  exit 1
+fi
+
+REPO_ROOT=$(git rev-parse --show-toplevel)
+CLAUDE_MD="$REPO_ROOT/CLAUDE.md"
+GENERATED=()
+
+# ── Migrate vendored copy if present ──────────────────────────
+
+if [ -d "$REPO_ROOT/.claude/skills/gstack" ] && [ ! -L "$REPO_ROOT/.claude/skills/gstack" ]; then
+  if [ -f "$REPO_ROOT/.claude/skills/gstack/VERSION" ] || [ -d "$REPO_ROOT/.claude/skills/gstack/.git" ]; then
+    echo "  Found vendored gstack copy at $REPO_ROOT/.claude/skills/gstack"
+    echo "  Team mode uses the global install — removing vendored copy..."
+    ( cd "$REPO_ROOT" && git rm -r --cached .claude/skills/gstack/ 2>/dev/null ) || true
+    if [ -f "$REPO_ROOT/.gitignore" ]; then
+      if ! grep -qF '.claude/skills/gstack/' "$REPO_ROOT/.gitignore" 2>/dev/null; then
+        echo '.claude/skills/gstack/' >> "$REPO_ROOT/.gitignore"
+      fi
+    else
+      echo '.claude/skills/gstack/' > "$REPO_ROOT/.gitignore"
+    fi
+    rm -rf "$REPO_ROOT/.claude/skills/gstack"
+    GENERATED+=(".gitignore")
+    echo "  Removed vendored copy and added .claude/skills/gstack/ to .gitignore"
+  fi
+fi
+
+# ── CLAUDE.md snippet ──────────────────────────────────────────
+
+if [ "$MODE" = "optional" ]; then
+  SNIPPET='## gstack (recommended)
+
+This project uses [gstack](https://github.com/garrytan/gstack) for AI-assisted workflows.
+Install it for the best experience:
+
+```bash
+git clone --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack
+cd ~/.claude/skills/gstack && ./setup --team
+```
+
+Skills like /qa, /ship, /review, /investigate, and /browse become available after install.
+Use /browse for all web browsing. Use ~/.claude/skills/gstack/... for gstack file paths.'
+else
+  SNIPPET='## gstack (REQUIRED — global install)
+
+**Before doing ANY work, verify gstack is installed:**
+
+```bash
+test -d ~/.claude/skills/gstack/bin && echo "GSTACK_OK" || echo "GSTACK_MISSING"
+```
+
+If GSTACK_MISSING: STOP. Do not proceed. Tell the user:
+
+> gstack is required for all AI-assisted work in this repo.
+> Install it:
+> ```bash
+> git clone --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack
+> cd ~/.claude/skills/gstack && ./setup --team
+> ```
+> Then restart your AI coding tool.
+
+Do not skip skills, ignore gstack errors, or work around missing gstack.
+
+Using gstack skills: After install, skills like /qa, /ship, /review, /investigate,
+and /browse are available. Use /browse for all web browsing.
+Use ~/.claude/skills/gstack/... for gstack file paths (the global path).'
+fi
+
+# Check if CLAUDE.md already has a gstack section
+if [ -f "$CLAUDE_MD" ] && grep -q "## gstack" "$CLAUDE_MD" 2>/dev/null; then
+  echo "CLAUDE.md already has a gstack section. Skipping CLAUDE.md update."
+  echo "  To replace it, remove the existing ## gstack section and re-run."
+else
+  if [ -f "$CLAUDE_MD" ]; then
+    echo "" >> "$CLAUDE_MD"
+  fi
+  echo "$SNIPPET" >> "$CLAUDE_MD"
+  GENERATED+=("CLAUDE.md")
+  echo "  + CLAUDE.md — added gstack $MODE section"
+fi
+
+# ── Required mode: enforcement hook ────────────────────────────
+
+if [ "$MODE" = "required" ]; then
+  HOOKS_DIR="$REPO_ROOT/.claude/hooks"
+  SETTINGS="$REPO_ROOT/.claude/settings.json"
+
+  # Create enforcement hook script
+  mkdir -p "$HOOKS_DIR"
+  cat > "$HOOKS_DIR/check-gstack.sh" << 'HOOK_EOF'
+#!/bin/bash
+# Block skill usage when gstack is not installed globally.
+
+if [ ! -d "$HOME/.claude/skills/gstack/bin" ]; then
+  cat >&2 <<'MSG'
+BLOCKED: gstack is not installed globally.
+
+gstack is required for AI-assisted work in this repo.
+
+Install it:
+  git clone --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack
+  cd ~/.claude/skills/gstack && ./setup --team
+
+Then restart your AI coding tool.
+MSG
+  echo '{"permissionDecision":"deny","message":"gstack is required but not installed. See stderr for install instructions."}'
+  exit 0
+fi
+
+echo '{}'
+HOOK_EOF
+  chmod +x "$HOOKS_DIR/check-gstack.sh"
+  GENERATED+=(".claude/hooks/check-gstack.sh")
+  echo "  + .claude/hooks/check-gstack.sh — enforcement hook"
+
+  # Add hook to project-level settings.json
+  if command -v bun >/dev/null 2>&1; then
+    GSTACK_SETTINGS_PATH="$SETTINGS" bun -e "
+      const fs = require('fs');
+      const settingsPath = process.env.GSTACK_SETTINGS_PATH;
+
+      let settings = {};
+      try { settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8')); } catch {}
+
+      if (!settings.hooks) settings.hooks = {};
+      if (!settings.hooks.PreToolUse) settings.hooks.PreToolUse = [];
+
+      // Dedup
+      const exists = settings.hooks.PreToolUse.some(entry =>
+        entry.matcher === 'Skill' &&
+        entry.hooks && entry.hooks.some(h => h.command && h.command.includes('check-gstack'))
+      );
+
+      if (!exists) {
+        settings.hooks.PreToolUse.push({
+          matcher: 'Skill',
+          hooks: [{
+            type: 'command',
+            command: '\"\$CLAUDE_PROJECT_DIR/.claude/hooks/check-gstack.sh\"'
+          }]
+        });
+      }
+
+      const tmp = settingsPath + '.tmp';
+      fs.writeFileSync(tmp, JSON.stringify(settings, null, 2) + '\n');
+      fs.renameSync(tmp, settingsPath);
+    " 2>/dev/null
+    GENERATED+=(".claude/settings.json")
+    echo "  + .claude/settings.json — PreToolUse hook registered"
+  else
+    echo "  ! bun not found — manually add the PreToolUse hook to .claude/settings.json"
+  fi
+fi
+
+# ── Summary ────────────────────────────────────────────────────
+
+echo ""
+echo "Team mode ($MODE) initialized."
+echo ""
+if [ ${#GENERATED[@]} -gt 0 ]; then
+  echo "Commit the generated files:"
+  echo "  git add ${GENERATED[*]}"
+  echo "  git commit -m \"chore: require gstack for AI-assisted work\""
+fi
+echo ""
+echo "Each developer then runs:"
+echo "  git clone --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack"
+echo "  cd ~/.claude/skills/gstack && ./setup --team"

bin/gstack-telemetry-log

@@ -0,0 +1,241 @@
+#!/usr/bin/env bash
+# gstack-telemetry-log — append a telemetry event to local JSONL
+#
+# Data flow:
+#   preamble (start) ──▶ .pending marker
+#   preamble (epilogue) ──▶ gstack-telemetry-log ──▶ skill-usage.jsonl
+#                                                 └──▶ gstack-telemetry-sync (bg)
+#
+# Usage:
+#   gstack-telemetry-log --skill qa --duration 142 --outcome success \
+#     --used-browse true --session-id "12345-1710756600"
+#
+# Env overrides (for testing):
+#   GSTACK_STATE_DIR  — override ~/.gstack state directory
+#   GSTACK_DIR        — override auto-detected gstack root
+#
+# NOTE: Uses set -uo pipefail (no -e) — telemetry must never exit non-zero
+set -uo pipefail
+
+GSTACK_DIR="${GSTACK_DIR:-$(cd "$(dirname "$0")/.." && pwd)}"
+STATE_DIR="${GSTACK_STATE_DIR:-$HOME/.gstack}"
+ANALYTICS_DIR="$STATE_DIR/analytics"
+JSONL_FILE="$ANALYTICS_DIR/skill-usage.jsonl"
+PENDING_DIR="$ANALYTICS_DIR"  # .pending-* files live here
+CONFIG_CMD="$GSTACK_DIR/bin/gstack-config"
+VERSION_FILE="$GSTACK_DIR/VERSION"
+
+# ─── Parse flags ─────────────────────────────────────────────
+SKILL=""
+DURATION=""
+OUTCOME="unknown"
+USED_BROWSE="false"
+SESSION_ID=""
+ERROR_CLASS=""
+ERROR_MESSAGE=""
+FAILED_STEP=""
+EVENT_TYPE="skill_run"
+SOURCE=""
+# Security-event fields (populated only when --event-type attack_attempt)
+SEC_URL_DOMAIN=""
+SEC_PAYLOAD_HASH=""
+SEC_CONFIDENCE=""
+SEC_LAYER=""
+SEC_VERDICT=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --skill)         SKILL="$2"; shift 2 ;;
+    --duration)      DURATION="$2"; shift 2 ;;
+    --outcome)       OUTCOME="$2"; shift 2 ;;
+    --used-browse)   USED_BROWSE="$2"; shift 2 ;;
+    --session-id)    SESSION_ID="$2"; shift 2 ;;
+    --error-class)   ERROR_CLASS="$2"; shift 2 ;;
+    --error-message) ERROR_MESSAGE="$2"; shift 2 ;;
+    --failed-step)   FAILED_STEP="$2"; shift 2 ;;
+    --event-type)    EVENT_TYPE="$2"; shift 2 ;;
+    --source)        SOURCE="$2"; shift 2 ;;
+    # Security event fields — emitted by browse/src/security.ts logAttempt()
+    --url-domain)    SEC_URL_DOMAIN="$2"; shift 2 ;;
+    --payload-hash)  SEC_PAYLOAD_HASH="$2"; shift 2 ;;
+    --confidence)    SEC_CONFIDENCE="$2"; shift 2 ;;
+    --layer)         SEC_LAYER="$2"; shift 2 ;;
+    --verdict)       SEC_VERDICT="$2"; shift 2 ;;
+    *) shift ;;
+  esac
+done
+
+# Source: flag > env > default 'live'
+SOURCE="${SOURCE:-${GSTACK_TELEMETRY_SOURCE:-live}}"
+
+# ─── Read telemetry tier ─────────────────────────────────────
+TIER="$("$CONFIG_CMD" get telemetry 2>/dev/null || true)"
+TIER="${TIER:-off}"
+
+# Validate tier
+case "$TIER" in
+  off|anonymous|community) ;;
+  *) TIER="off" ;;  # invalid value → default to off
+esac
+
+if [ "$TIER" = "off" ]; then
+  # Still clear pending markers for this session even if telemetry is off
+  [ -n "$SESSION_ID" ] && rm -f "$PENDING_DIR/.pending-$SESSION_ID" 2>/dev/null || true
+  exit 0
+fi
+
+# ─── Finalize stale .pending markers ────────────────────────
+# Each session gets its own .pending-$SESSION_ID file to avoid races
+# between concurrent sessions. Finalize any that don't match our session.
+for PFILE in "$PENDING_DIR"/.pending-*; do
+  [ -f "$PFILE" ] || continue
+  # Skip our own session's marker (it's still in-flight)
+  PFILE_BASE="$(basename "$PFILE")"
+  PFILE_SID="${PFILE_BASE#.pending-}"
+  [ "$PFILE_SID" = "$SESSION_ID" ] && continue
+
+  PENDING_DATA="$(cat "$PFILE" 2>/dev/null || true)"
+  rm -f "$PFILE" 2>/dev/null || true
+  if [ -n "$PENDING_DATA" ]; then
+    # Extract fields from pending marker using grep -o + awk
+    P_SKILL="$(echo "$PENDING_DATA" | grep -o '"skill":"[^"]*"' | head -1 | awk -F'"' '{print $4}')"
+    P_TS="$(echo "$PENDING_DATA" | grep -o '"ts":"[^"]*"' | head -1 | awk -F'"' '{print $4}')"
+    P_SID="$(echo "$PENDING_DATA" | grep -o '"session_id":"[^"]*"' | head -1 | awk -F'"' '{print $4}')"
+    P_VER="$(echo "$PENDING_DATA" | grep -o '"gstack_version":"[^"]*"' | head -1 | awk -F'"' '{print $4}')"
+    P_OS="$(uname -s | tr '[:upper:]' '[:lower:]')"
+    P_ARCH="$(uname -m)"
+
+    # Write the stale event as outcome: unknown
+    mkdir -p "$ANALYTICS_DIR"
+    printf '{"v":1,"ts":"%s","event_type":"skill_run","skill":"%s","session_id":"%s","gstack_version":"%s","os":"%s","arch":"%s","duration_s":null,"outcome":"unknown","error_class":null,"used_browse":false,"sessions":1}\n' \
+      "$P_TS" "$P_SKILL" "$P_SID" "$P_VER" "$P_OS" "$P_ARCH" >> "$JSONL_FILE" 2>/dev/null || true
+  fi
+done
+
+# Clear our own session's pending marker (we're about to log the real event)
+[ -n "$SESSION_ID" ] && rm -f "$PENDING_DIR/.pending-$SESSION_ID" 2>/dev/null || true
+
+# ─── Collect metadata ────────────────────────────────────────
+TS="$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u +%Y-%m-%dT%H:%M:%S 2>/dev/null || echo "")"
+GSTACK_VERSION="$(cat "$VERSION_FILE" 2>/dev/null | tr -d '[:space:]' || echo "unknown")"
+OS="$(uname -s | tr '[:upper:]' '[:lower:]')"
+ARCH="$(uname -m)"
+SESSIONS="1"
+if [ -d "$STATE_DIR/sessions" ]; then
+  _SC="$(find "$STATE_DIR/sessions" -mmin -120 -type f 2>/dev/null | wc -l | tr -d ' \n\r\t')"
+  [ -n "$_SC" ] && [ "$_SC" -gt 0 ] 2>/dev/null && SESSIONS="$_SC"
+fi
+
+# Generate installation_id for community tier
+# Uses a random UUID stored locally — not derived from hostname/user so it
+# can't be guessed or correlated by someone who knows your machine identity.
+INSTALL_ID=""
+if [ "$TIER" = "community" ]; then
+  ID_FILE="$HOME/.gstack/installation-id"
+  if [ -f "$ID_FILE" ]; then
+    INSTALL_ID="$(cat "$ID_FILE" 2>/dev/null)"
+  fi
+  if [ -z "$INSTALL_ID" ]; then
+    # Generate a random UUID v4
+    if command -v uuidgen >/dev/null 2>&1; then
+      INSTALL_ID="$(uuidgen | tr '[:upper:]' '[:lower:]')"
+    elif [ -r /proc/sys/kernel/random/uuid ]; then
+      INSTALL_ID="$(cat /proc/sys/kernel/random/uuid)"
+    else
+      # Fallback: random hex from /dev/urandom
+      INSTALL_ID="$(od -An -tx1 -N16 /dev/urandom 2>/dev/null | tr -d ' \n')"
+    fi
+    if [ -n "$INSTALL_ID" ]; then
+      mkdir -p "$(dirname "$ID_FILE")" 2>/dev/null
+      printf '%s' "$INSTALL_ID" > "$ID_FILE" 2>/dev/null
+    fi
+  fi
+fi
+
+# Local-only fields (never sent remotely)
+REPO_SLUG=""
+BRANCH=""
+if command -v git >/dev/null 2>&1; then
+  REPO_SLUG="$(git remote get-url origin 2>/dev/null | sed 's|.*[:/]\([^/]*/[^/]*\)\.git$|\1|;s|.*[:/]\([^/]*/[^/]*\)$|\1|' | tr '/' '-' 2>/dev/null || true)"
+  BRANCH="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
+fi
+
+# ─── Construct and append JSON ───────────────────────────────
+mkdir -p "$ANALYTICS_DIR"
+
+# Sanitize string fields for JSON safety (strip quotes, backslashes, control chars)
+json_safe() { printf '%s' "$1" | tr -d '"\\\n\r\t' | head -c 200; }
+SKILL="$(json_safe "$SKILL")"
+OUTCOME="$(json_safe "$OUTCOME")"
+SESSION_ID="$(json_safe "$SESSION_ID")"
+SOURCE="$(json_safe "$SOURCE")"
+EVENT_TYPE="$(json_safe "$EVENT_TYPE")"
+REPO_SLUG="$(json_safe "$REPO_SLUG")"
+BRANCH="$(json_safe "$BRANCH")"
+
+# Escape null fields — sanitize ERROR_CLASS and FAILED_STEP via json_safe()
+ERR_FIELD="null"
+[ -n "$ERROR_CLASS" ] && ERR_FIELD="\"$(json_safe "$ERROR_CLASS")\""
+
+ERR_MSG_FIELD="null"
+[ -n "$ERROR_MESSAGE" ] && ERR_MSG_FIELD="\"$(printf '%s' "$ERROR_MESSAGE" | head -c 200 | sed -e 's/\\/\\\\/g' -e 's/"/\\"/g' -e 's/	/\\t/g' | tr '\n\r' '  ')\""
+
+STEP_FIELD="null"
+[ -n "$FAILED_STEP" ] && STEP_FIELD="\"$(json_safe "$FAILED_STEP")\""
+
+# Cap unreasonable durations
+if [ -n "$DURATION" ] && [ "$DURATION" -gt 86400 ] 2>/dev/null; then
+  DURATION=""  # null if > 24h
+fi
+if [ -n "$DURATION" ] && [ "$DURATION" -lt 0 ] 2>/dev/null; then
+  DURATION=""  # null if negative
+fi
+
+DUR_FIELD="null"
+[ -n "$DURATION" ] && DUR_FIELD="$DURATION"
+
+INSTALL_FIELD="null"
+[ -n "$INSTALL_ID" ] && INSTALL_FIELD="\"$INSTALL_ID\""
+
+BROWSE_BOOL="false"
+[ "$USED_BROWSE" = "true" ] && BROWSE_BOOL="true"
+
+# Sanitize security fields — they're salted hashes and controlled enum values,
+# but apply json_safe() defensively. Domain is limited to 253 chars (RFC 1035).
+SEC_URL_DOMAIN="$(json_safe "$SEC_URL_DOMAIN")"
+SEC_PAYLOAD_HASH="$(json_safe "$SEC_PAYLOAD_HASH")"
+SEC_LAYER="$(json_safe "$SEC_LAYER")"
+SEC_VERDICT="$(json_safe "$SEC_VERDICT")"
+
+# Confidence is numeric 0-1. Default null if unset or malformed.
+SEC_CONF_FIELD="null"
+if [ -n "$SEC_CONFIDENCE" ]; then
+  # awk validates + clamps to [0,1]. Falls back to null on parse failure.
+  _sc="$(awk -v v="$SEC_CONFIDENCE" 'BEGIN { if (v+0 >= 0 && v+0 <= 1) printf "%.4f", v+0; else print "" }' 2>/dev/null || echo "")"
+  [ -n "$_sc" ] && SEC_CONF_FIELD="$_sc"
+fi
+
+SEC_DOMAIN_FIELD="null"
+[ -n "$SEC_URL_DOMAIN" ] && SEC_DOMAIN_FIELD="\"$SEC_URL_DOMAIN\""
+SEC_HASH_FIELD="null"
+[ -n "$SEC_PAYLOAD_HASH" ] && SEC_HASH_FIELD="\"$SEC_PAYLOAD_HASH\""
+SEC_LAYER_FIELD="null"
+[ -n "$SEC_LAYER" ] && SEC_LAYER_FIELD="\"$SEC_LAYER\""
+SEC_VERDICT_FIELD="null"
+[ -n "$SEC_VERDICT" ] && SEC_VERDICT_FIELD="\"$SEC_VERDICT\""
+
+printf '{"v":1,"ts":"%s","event_type":"%s","skill":"%s","session_id":"%s","gstack_version":"%s","os":"%s","arch":"%s","duration_s":%s,"outcome":"%s","error_class":%s,"error_message":%s,"failed_step":%s,"used_browse":%s,"sessions":%s,"installation_id":%s,"source":"%s","security_url_domain":%s,"security_payload_hash":%s,"security_confidence":%s,"security_layer":%s,"security_verdict":%s,"_repo_slug":"%s","_branch":"%s"}\n' \
+  "$TS" "$EVENT_TYPE" "$SKILL" "$SESSION_ID" "$GSTACK_VERSION" "$OS" "$ARCH" \
+  "$DUR_FIELD" "$OUTCOME" "$ERR_FIELD" "$ERR_MSG_FIELD" "$STEP_FIELD" \
+  "$BROWSE_BOOL" "${SESSIONS:-1}" \
+  "$INSTALL_FIELD" "$SOURCE" \
+  "$SEC_DOMAIN_FIELD" "$SEC_HASH_FIELD" "$SEC_CONF_FIELD" "$SEC_LAYER_FIELD" "$SEC_VERDICT_FIELD" \
+  "$REPO_SLUG" "$BRANCH" >> "$JSONL_FILE" 2>/dev/null || true
+
+# ─── Trigger sync if tier is not off ─────────────────────────
+SYNC_CMD="$GSTACK_DIR/bin/gstack-telemetry-sync"
+if [ -x "$SYNC_CMD" ]; then
+  "$SYNC_CMD" 2>/dev/null &
+fi
+
+exit 0

bin/gstack-telemetry-sync

@@ -0,0 +1,142 @@
+#!/usr/bin/env bash
+# gstack-telemetry-sync — sync local JSONL events to Supabase
+#
+# Fire-and-forget, backgrounded, rate-limited to once per 5 minutes.
+# Strips local-only fields before sending. Respects privacy tiers.
+# Posts to the telemetry-ingest edge function (not PostgREST directly).
+#
+# Env overrides (for testing):
+#   GSTACK_STATE_DIR           — override ~/.gstack state directory
+#   GSTACK_DIR                 — override auto-detected gstack root
+#   GSTACK_SUPABASE_URL        — override Supabase project URL
+set -uo pipefail
+
+GSTACK_DIR="${GSTACK_DIR:-$(cd "$(dirname "$0")/.." && pwd)}"
+STATE_DIR="${GSTACK_STATE_DIR:-$HOME/.gstack}"
+ANALYTICS_DIR="$STATE_DIR/analytics"
+JSONL_FILE="$ANALYTICS_DIR/skill-usage.jsonl"
+CURSOR_FILE="$ANALYTICS_DIR/.last-sync-line"
+RATE_FILE="$ANALYTICS_DIR/.last-sync-time"
+CONFIG_CMD="$GSTACK_DIR/bin/gstack-config"
+
+# Source Supabase config if not overridden by env
+if [ -z "${GSTACK_SUPABASE_URL:-}" ] && [ -f "$GSTACK_DIR/supabase/config.sh" ]; then
+  . "$GSTACK_DIR/supabase/config.sh"
+fi
+SUPABASE_URL="${GSTACK_SUPABASE_URL:-}"
+ANON_KEY="${GSTACK_SUPABASE_ANON_KEY:-}"
+
+# ─── Pre-checks ──────────────────────────────────────────────
+# No Supabase URL configured yet → exit silently
+[ -z "$SUPABASE_URL" ] && exit 0
+
+# No JSONL file → nothing to sync
+[ -f "$JSONL_FILE" ] || exit 0
+
+# Rate limit: once per 5 minutes
+if [ -f "$RATE_FILE" ]; then
+  STALE=$(find "$RATE_FILE" -mmin +5 2>/dev/null || true)
+  [ -z "$STALE" ] && exit 0
+fi
+
+# ─── Read tier ───────────────────────────────────────────────
+TIER="$("$CONFIG_CMD" get telemetry 2>/dev/null || true)"
+TIER="${TIER:-off}"
+[ "$TIER" = "off" ] && exit 0
+
+# ─── Read cursor ─────────────────────────────────────────────
+CURSOR=0
+if [ -f "$CURSOR_FILE" ]; then
+  CURSOR="$(cat "$CURSOR_FILE" 2>/dev/null | tr -d ' \n\r\t')"
+  # Validate: must be a non-negative integer
+  case "$CURSOR" in *[!0-9]*) CURSOR=0 ;; esac
+fi
+
+# Safety: if cursor exceeds file length, reset
+TOTAL_LINES="$(wc -l < "$JSONL_FILE" | tr -d ' \n\r\t')"
+if [ "$CURSOR" -gt "$TOTAL_LINES" ] 2>/dev/null; then
+  CURSOR=0
+fi
+
+# Nothing new to sync
+[ "$CURSOR" -ge "$TOTAL_LINES" ] 2>/dev/null && exit 0
+
+# ─── Read unsent lines ───────────────────────────────────────
+SKIP=$(( CURSOR + 1 ))
+UNSENT="$(tail -n "+$SKIP" "$JSONL_FILE" 2>/dev/null || true)"
+[ -z "$UNSENT" ] && exit 0
+
+# ─── Strip local-only fields and build batch ─────────────────
+# Edge function expects raw JSONL field names (v, ts, sessions) —
+# no column renaming needed (the function maps them internally).
+BATCH="["
+FIRST=true
+COUNT=0
+
+while IFS= read -r LINE; do
+  # Skip empty or malformed lines
+  [ -z "$LINE" ] && continue
+  echo "$LINE" | grep -q '^{' || continue
+
+  # Strip local-only fields (keep v, ts, sessions as-is for edge function)
+  CLEAN="$(echo "$LINE" | sed \
+    -e 's/,"_repo_slug":"[^"]*"//g' \
+    -e 's/,"_branch":"[^"]*"//g' \
+    -e 's/,"repo":"[^"]*"//g')"
+
+  # If anonymous tier, strip installation_id
+  if [ "$TIER" = "anonymous" ]; then
+    CLEAN="$(echo "$CLEAN" | sed 's/,"installation_id":"[^"]*"//g; s/,"installation_id":null//g')"
+  fi
+
+  if [ "$FIRST" = "true" ]; then
+    FIRST=false
+  else
+    BATCH="$BATCH,"
+  fi
+  BATCH="$BATCH$CLEAN"
+  COUNT=$(( COUNT + 1 ))
+
+  # Batch size limit
+  [ "$COUNT" -ge 100 ] && break
+done <<< "$UNSENT"
+
+BATCH="$BATCH]"
+
+# Nothing to send after filtering
+[ "$COUNT" -eq 0 ] && exit 0
+
+# ─── POST to edge function ───────────────────────────────────
+RESP_FILE="$(mktemp /tmp/gstack-sync-XXXXXX 2>/dev/null || echo "/tmp/gstack-sync-$$")"
+HTTP_CODE="$(curl -s -w '%{http_code}' --max-time 10 \
+  -X POST "${SUPABASE_URL}/functions/v1/telemetry-ingest" \
+  -H "Content-Type: application/json" \
+  -H "apikey: ${ANON_KEY}" \
+  -o "$RESP_FILE" \
+  -d "$BATCH" 2>/dev/null || echo "000")"
+
+# ─── Update cursor on success (2xx) ─────────────────────────
+case "$HTTP_CODE" in
+  2*)
+    # Parse inserted count from response — only advance if events were actually inserted.
+    # Advance by SENT count (not inserted count) because we can't map inserted back to
+    # source lines. If inserted==0, something is systemically wrong — don't advance.
+    INSERTED="$(grep -o '"inserted":[0-9]*' "$RESP_FILE" 2>/dev/null | grep -o '[0-9]*' || echo "0")"
+    # Check for upsert errors (installation tracking failures) — log but don't block cursor advance
+    UPSERT_ERRORS="$(grep -o '"upsertErrors"' "$RESP_FILE" 2>/dev/null || true)"
+    if [ -n "$UPSERT_ERRORS" ]; then
+      echo "[gstack-telemetry-sync] Warning: installation upsert errors in response" >&2
+    fi
+    if [ "${INSERTED:-0}" -gt 0 ] 2>/dev/null; then
+      NEW_CURSOR=$(( CURSOR + COUNT ))
+      echo "$NEW_CURSOR" > "$CURSOR_FILE" 2>/dev/null || true
+    fi
+    ;;
+esac
+
+rm -f "$RESP_FILE" 2>/dev/null || true
+
+# Update rate limit marker
+touch "$RATE_FILE" 2>/dev/null || true
+
+exit 0

bin/gstack-timeline-log

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# gstack-timeline-log — append a timeline event to the project timeline
+# Usage: gstack-timeline-log '{"skill":"review","event":"started","branch":"main"}'
+#
+# Session timeline: local by default. If the user enables `artifacts_sync_mode`
+# with the `full` (not `artifacts-only`) privacy tier — via the first-run
+# stop-gate from `gstack-artifacts-init` or the preamble — timeline events are
+# published to the user's private GBrain sync repo. See docs/gbrain-sync.md.
+# Required fields: skill, event (started|completed).
+# Optional: branch, outcome, duration_s, session, ts.
+# Validation failure → skip silently (non-blocking).
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+eval "$("$SCRIPT_DIR/gstack-slug" 2>/dev/null)"
+GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
+mkdir -p "$GSTACK_HOME/projects/$SLUG"
+
+INPUT="$1"
+
+# Validate: input must be parseable JSON with required fields
+if ! printf '%s' "$INPUT" | bun -e "
+  const j = JSON.parse(await Bun.stdin.text());
+  if (!j.skill || !j.event) process.exit(1);
+" 2>/dev/null; then
+  exit 0  # skip silently, non-blocking
+fi
+
+# Inject timestamp if not present
+if ! printf '%s' "$INPUT" | bun -e "const j=JSON.parse(await Bun.stdin.text()); if(!j.ts) process.exit(1)" 2>/dev/null; then
+  INPUT=$(printf '%s' "$INPUT" | bun -e "
+    const j = JSON.parse(await Bun.stdin.text());
+    j.ts = new Date().toISOString();
+    console.log(JSON.stringify(j));
+  " 2>/dev/null) || true
+fi
+
+echo "$INPUT" >> "$GSTACK_HOME/projects/$SLUG/timeline.jsonl"
+
+# gbrain-sync: enqueue for cross-machine sync (no-op if sync is off).
+"$SCRIPT_DIR/gstack-brain-enqueue" "projects/$SLUG/timeline.jsonl" 2>/dev/null &

bin/gstack-timeline-read

@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+# gstack-timeline-read — read and format project timeline
+# Usage: gstack-timeline-read [--since "7 days ago"] [--limit N] [--branch NAME]
+#
+# Session timeline: local-only, never sent anywhere.
+# Reads ~/.gstack/projects/$SLUG/timeline.jsonl, filters, formats.
+# Exit 0 silently if no timeline file exists.
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+eval "$("$SCRIPT_DIR/gstack-slug" 2>/dev/null)"
+GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
+
+SINCE=""
+LIMIT=20
+BRANCH=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --since) SINCE="$2"; shift 2 ;;
+    --limit) LIMIT="$2"; shift 2 ;;
+    --branch) BRANCH="$2"; shift 2 ;;
+    *) shift ;;
+  esac
+done
+
+TIMELINE_FILE="$GSTACK_HOME/projects/$SLUG/timeline.jsonl"
+
+if [ ! -f "$TIMELINE_FILE" ]; then
+  exit 0
+fi
+
+cat "$TIMELINE_FILE" 2>/dev/null | bun -e "
+const lines = (await Bun.stdin.text()).trim().split('\n').filter(Boolean);
+const since = '${SINCE}';
+const branch = '${BRANCH}';
+const limit = ${LIMIT};
+
+let sinceMs = 0;
+if (since) {
+  // Parse relative time like '7 days ago'
+  const match = since.match(/(\d+)\s*(day|hour|minute|week|month)s?\s*ago/i);
+  if (match) {
+    const n = parseInt(match[1]);
+    const unit = match[2].toLowerCase();
+    const ms = { minute: 60000, hour: 3600000, day: 86400000, week: 604800000, month: 2592000000 };
+    sinceMs = Date.now() - n * (ms[unit] || 86400000);
+  }
+}
+
+const entries = [];
+for (const line of lines) {
+  try {
+    const e = JSON.parse(line);
+    if (sinceMs && new Date(e.ts).getTime() < sinceMs) continue;
+    if (branch && e.branch !== branch) continue;
+    entries.push(e);
+  } catch {}
+}
+
+if (entries.length === 0) process.exit(0);
+
+// Take last N entries
+const recent = entries.slice(-limit);
+
+// Skill counts (completed events only)
+const counts = {};
+const branches = new Set();
+for (const e of entries) {
+  if (e.event === 'completed') {
+    counts[e.skill] = (counts[e.skill] || 0) + 1;
+  }
+  if (e.branch) branches.add(e.branch);
+}
+
+// Output summary
+const countStr = Object.entries(counts)
+  .sort((a, b) => b[1] - a[1])
+  .map(([s, n]) => n + ' /' + s)
+  .join(', ');
+
+if (countStr) {
+  console.log('TIMELINE: ' + countStr + ' across ' + branches.size + ' branch' + (branches.size !== 1 ? 'es' : ''));
+}
+
+// Output recent events
+console.log('');
+console.log('## Recent Events');
+for (const e of recent) {
+  const ts = (e.ts || '').replace('T', ' ').replace(/\.\d+Z$/, 'Z');
+  const dur = e.duration_s ? ' (' + e.duration_s + 's)' : '';
+  const outcome = e.outcome ? ' [' + e.outcome + ']' : '';
+  console.log('- ' + ts + ' /' + e.skill + ' ' + e.event + outcome + dur + (e.branch ? ' on ' + e.branch : ''));
+}
+" 2>/dev/null || exit 0

bin/gstack-uninstall

@@ -0,0 +1,259 @@
+#!/usr/bin/env bash
+# gstack-uninstall — remove gstack skills, state, and browse daemons
+#
+# Usage:
+#   gstack-uninstall              — interactive uninstall (prompts before removing)
+#   gstack-uninstall --force      — remove everything without prompting
+#   gstack-uninstall --keep-state — remove skills but keep ~/.gstack/ data
+#
+# What gets REMOVED:
+#   ~/.claude/skills/gstack       — global Claude skill install (git clone or vendored)
+#   ~/.claude/skills/{skill}      — per-skill symlinks created by setup
+#   ~/.codex/skills/gstack*       — Codex skill install + per-skill symlinks
+#   ~/.factory/skills/gstack*     — Factory Droid skill install + per-skill symlinks
+#   ~/.kiro/skills/gstack*        — Kiro skill install + per-skill symlinks
+#   ~/.gstack/                    — global state (config, analytics, sessions, projects,
+#                                   repos, installation-id, browse error logs)
+#   .claude/skills/gstack*        — project-local skill install (--local installs)
+#   .gstack/                      — per-project browse state (in current git repo)
+#   .gstack-worktrees/            — per-project test worktrees (in current git repo)
+#   .agents/skills/gstack*        — Codex/Gemini/Cursor sidecar (in current git repo)
+#   Running browse daemons        — stopped via SIGTERM before cleanup
+#
+# What is NOT REMOVED:
+#   ~/Library/Caches/ms-playwright/  — Playwright Chromium (shared, may be used by other tools)
+#   ~/.gstack-dev/                   — developer eval artifacts (only present in gstack contributors)
+#
+# Env overrides (for testing):
+#   GSTACK_DIR        — override auto-detected gstack root
+#   GSTACK_STATE_DIR  — override ~/.gstack state directory
+#
+# NOTE: Uses set -uo pipefail (no -e) — uninstall must never abort partway.
+set -uo pipefail
+
+if [ -z "${HOME:-}" ]; then
+  echo "ERROR: \$HOME is not set" >&2
+  exit 1
+fi
+
+GSTACK_DIR="${GSTACK_DIR:-$(cd "$(dirname "$0")/.." && pwd)}"
+STATE_DIR="${GSTACK_STATE_DIR:-$HOME/.gstack}"
+_GIT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+
+# ─── Parse flags ─────────────────────────────────────────────
+FORCE=0
+KEEP_STATE=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --force) FORCE=1; shift ;;
+    --keep-state) KEEP_STATE=1; shift ;;
+    -h|--help)
+      sed -n '2,/^[^#]/{ /^#/s/^# \{0,1\}//p; }' "$0"
+      exit 0
+      ;;
+    *)
+      echo "Unknown option: $1" >&2
+      echo "Usage: gstack-uninstall [--force] [--keep-state]" >&2
+      exit 1
+      ;;
+  esac
+done
+
+# ─── Confirmation ────────────────────────────────────────────
+if [ "$FORCE" -eq 0 ]; then
+  echo "This will remove gstack from your system:"
+  { [ -d "$HOME/.claude/skills/gstack" ] || [ -L "$HOME/.claude/skills/gstack" ]; } && echo "  ~/.claude/skills/gstack (+ per-skill symlinks)"
+  [ -d "$HOME/.codex/skills" ] && echo "  ~/.codex/skills/gstack*"
+  [ -d "$HOME/.factory/skills" ] && echo "  ~/.factory/skills/gstack*"
+  [ -d "$HOME/.kiro/skills" ] && echo "  ~/.kiro/skills/gstack*"
+  [ "$KEEP_STATE" -eq 0 ] && [ -d "$STATE_DIR" ] && echo "  $STATE_DIR"
+
+  if [ -n "$_GIT_ROOT" ]; then
+    [ -d "$_GIT_ROOT/.claude/skills/gstack" ] && echo "  $_GIT_ROOT/.claude/skills/gstack (project-local)"
+    [ -d "$_GIT_ROOT/.gstack" ] && echo "  $_GIT_ROOT/.gstack/ (browse state + reports)"
+    [ -d "$_GIT_ROOT/.gstack-worktrees" ] && echo "  $_GIT_ROOT/.gstack-worktrees/"
+    [ -d "$_GIT_ROOT/.agents/skills" ] && echo "  $_GIT_ROOT/.agents/skills/gstack*"
+  fi
+
+  # Preview running daemons
+  if [ -n "$_GIT_ROOT" ] && [ -f "$_GIT_ROOT/.gstack/browse.json" ]; then
+    _PREVIEW_PID="$(awk -F'[:,]' '/"pid"/ { for(i=1;i<=NF;i++) if($i ~ /"pid"/) { gsub(/[^0-9]/, "", $(i+1)); print $(i+1); exit } }' "$_GIT_ROOT/.gstack/browse.json" 2>/dev/null || true)"
+    [ -n "$_PREVIEW_PID" ] && kill -0 "$_PREVIEW_PID" 2>/dev/null && echo "  browse daemon (PID $_PREVIEW_PID) will be stopped"
+  fi
+
+  printf "\nContinue? [y/N] "
+  read -r REPLY
+  case "$REPLY" in
+    y|Y|yes|YES) ;;
+    *) echo "Aborted."; exit 0 ;;
+  esac
+fi
+
+REMOVED=()
+
+# ─── Stop running browse daemons ─────────────────────────────
+# Browse servers write PID to {project}/.gstack/browse.json.
+# Stop any we can find before removing state directories.
+stop_browse_daemon() {
+  local state_file="$1"
+  if [ ! -f "$state_file" ]; then
+    return
+  fi
+  local pid
+  pid="$(awk -F'[:,]' '/"pid"/ { for(i=1;i<=NF;i++) if($i ~ /"pid"/) { gsub(/[^0-9]/, "", $(i+1)); print $(i+1); exit } }' "$state_file" 2>/dev/null || true)"
+  if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then
+    kill "$pid" 2>/dev/null || true
+    # Wait up to 2s for graceful shutdown
+    local waited=0
+    while [ "$waited" -lt 4 ] && kill -0 "$pid" 2>/dev/null; do
+      sleep 0.5
+      waited=$(( waited + 1 ))
+    done
+    if kill -0 "$pid" 2>/dev/null; then
+      kill -9 "$pid" 2>/dev/null || true
+    fi
+    REMOVED+=("browse daemon (PID $pid)")
+  fi
+}
+
+# Stop daemon in current project
+if [ -n "$_GIT_ROOT" ] && [ -f "$_GIT_ROOT/.gstack/browse.json" ]; then
+  stop_browse_daemon "$_GIT_ROOT/.gstack/browse.json"
+fi
+
+# Stop daemons tracked in global projects directory
+if [ -d "$STATE_DIR/projects" ]; then
+  while IFS= read -r _BJ; do
+    stop_browse_daemon "$_BJ"
+  done < <(find "$STATE_DIR/projects" -name browse.json -path '*/.gstack/*' 2>/dev/null || true)
+fi
+
+# ─── Remove global Claude skills ────────────────────────────
+CLAUDE_SKILLS="$HOME/.claude/skills"
+if [ -d "$CLAUDE_SKILLS/gstack" ] || [ -L "$CLAUDE_SKILLS/gstack" ]; then
+  # Remove per-skill symlinks that point into gstack/
+  for _LINK in "$CLAUDE_SKILLS"/*; do
+    [ -L "$_LINK" ] || continue
+    _NAME="$(basename "$_LINK")"
+    [ "$_NAME" = "gstack" ] && continue
+    _TARGET="$(readlink "$_LINK" 2>/dev/null || true)"
+    case "$_TARGET" in
+      gstack/*|*/gstack/*) rm -f "$_LINK"; REMOVED+=("claude/$_NAME") ;;
+    esac
+  done
+
+  rm -rf "$CLAUDE_SKILLS/gstack"
+  REMOVED+=("~/.claude/skills/gstack")
+fi
+
+# ─── Remove project-local Claude skills (--local installs) ──
+if [ -n "$_GIT_ROOT" ] && [ -d "$_GIT_ROOT/.claude/skills" ]; then
+  for _LINK in "$_GIT_ROOT/.claude/skills"/*; do
+    [ -L "$_LINK" ] || continue
+    _TARGET="$(readlink "$_LINK" 2>/dev/null || true)"
+    case "$_TARGET" in
+      gstack/*|*/gstack/*) rm -f "$_LINK"; REMOVED+=("local claude/$(basename "$_LINK")") ;;
+    esac
+  done
+  if [ -d "$_GIT_ROOT/.claude/skills/gstack" ] || [ -L "$_GIT_ROOT/.claude/skills/gstack" ]; then
+    rm -rf "$_GIT_ROOT/.claude/skills/gstack"
+    REMOVED+=("$_GIT_ROOT/.claude/skills/gstack")
+  fi
+fi
+
+# ─── Remove Codex skills ────────────────────────────────────
+CODEX_SKILLS="$HOME/.codex/skills"
+if [ -d "$CODEX_SKILLS" ]; then
+  for _ITEM in "$CODEX_SKILLS"/gstack*; do
+    [ -e "$_ITEM" ] || [ -L "$_ITEM" ] || continue
+    rm -rf "$_ITEM"
+    REMOVED+=("codex/$(basename "$_ITEM")")
+  done
+fi
+
+# ─── Remove Factory Droid skills ────────────────────────────
+FACTORY_SKILLS="$HOME/.factory/skills"
+if [ -d "$FACTORY_SKILLS" ]; then
+  for _ITEM in "$FACTORY_SKILLS"/gstack*; do
+    [ -e "$_ITEM" ] || [ -L "$_ITEM" ] || continue
+    rm -rf "$_ITEM"
+    REMOVED+=("factory/$(basename "$_ITEM")")
+  done
+fi
+
+# ─── Remove Kiro skills ─────────────────────────────────────
+KIRO_SKILLS="$HOME/.kiro/skills"
+if [ -d "$KIRO_SKILLS" ]; then
+  for _ITEM in "$KIRO_SKILLS"/gstack*; do
+    [ -e "$_ITEM" ] || [ -L "$_ITEM" ] || continue
+    rm -rf "$_ITEM"
+    REMOVED+=("kiro/$(basename "$_ITEM")")
+  done
+fi
+
+# ─── Remove per-project .agents/ sidecar ─────────────────────
+if [ -n "$_GIT_ROOT" ] && [ -d "$_GIT_ROOT/.agents/skills" ]; then
+  for _ITEM in "$_GIT_ROOT/.agents/skills"/gstack*; do
+    [ -e "$_ITEM" ] || [ -L "$_ITEM" ] || continue
+    rm -rf "$_ITEM"
+    REMOVED+=("agents/$(basename "$_ITEM")")
+  done
+
+  rmdir "$_GIT_ROOT/.agents/skills" 2>/dev/null || true
+  rmdir "$_GIT_ROOT/.agents" 2>/dev/null || true
+fi
+
+# ─── Remove per-project .factory/ sidecar ────────────────────
+if [ -n "$_GIT_ROOT" ] && [ -d "$_GIT_ROOT/.factory/skills" ]; then
+  for _ITEM in "$_GIT_ROOT/.factory/skills"/gstack*; do
+    [ -e "$_ITEM" ] || [ -L "$_ITEM" ] || continue
+    rm -rf "$_ITEM"
+    REMOVED+=("factory/$(basename "$_ITEM")")
+  done
+
+  rmdir "$_GIT_ROOT/.factory/skills" 2>/dev/null || true
+  rmdir "$_GIT_ROOT/.factory" 2>/dev/null || true
+fi
+
+# ─── Remove per-project state ───────────────────────────────
+if [ -n "$_GIT_ROOT" ]; then
+  if [ -d "$_GIT_ROOT/.gstack" ]; then
+    rm -rf "$_GIT_ROOT/.gstack"
+    REMOVED+=("$_GIT_ROOT/.gstack/")
+  fi
+  if [ -d "$_GIT_ROOT/.gstack-worktrees" ]; then
+    rm -rf "$_GIT_ROOT/.gstack-worktrees"
+    REMOVED+=("$_GIT_ROOT/.gstack-worktrees/")
+  fi
+fi
+
+# ─── Remove SessionStart hook from Claude Code settings ─────
+SETTINGS_HOOK="$(dirname "$0")/gstack-settings-hook"
+SESSION_UPDATE="$(dirname "$0")/gstack-session-update"
+if [ -x "$SETTINGS_HOOK" ]; then
+  "$SETTINGS_HOOK" remove "$SESSION_UPDATE" 2>/dev/null && REMOVED+=("SessionStart hook") || true
+fi
+
+# ─── Remove global state ────────────────────────────────────
+if [ "$KEEP_STATE" -eq 0 ] && [ -d "$STATE_DIR" ]; then
+  rm -rf "$STATE_DIR"
+  REMOVED+=("$STATE_DIR")
+fi
+
+# ─── Clean up temp files ────────────────────────────────────
+for _TMP in /tmp/gstack-latest-version /tmp/gstack-sketch-*.html /tmp/gstack-sketch.png /tmp/gstack-sync-*; do
+  if [ -e "$_TMP" ]; then
+    rm -f "$_TMP"
+    REMOVED+=("$(basename "$_TMP")")
+  fi
+done
+
+# ─── Summary ────────────────────────────────────────────────
+if [ ${#REMOVED[@]} -gt 0 ]; then
+  echo "Removed: ${REMOVED[*]}"
+  echo "gstack uninstalled."
+else
+  echo "Nothing to remove — gstack is not installed."
+fi
+
+exit 0

bin/gstack-update-check

@@ -0,0 +1,248 @@
+#!/usr/bin/env bash
+# gstack-update-check — periodic version check for all skills.
+#
+# Output (one line, or nothing):
+#   JUST_UPGRADED <old> <new>       — marker found from recent upgrade
+#   UPGRADE_AVAILABLE <old> <new>   — remote VERSION differs from local
+#   (nothing)                       — up to date, snoozed, disabled, or check skipped
+#
+# Env overrides (for testing):
+#   GSTACK_DIR          — override auto-detected gstack root
+#   GSTACK_REMOTE_URL   — override remote VERSION URL (branch-pinned fallback)
+#   GSTACK_REMOTE_REPO  — override remote git URL for ls-remote SHA resolution
+#   GSTACK_STATE_DIR    — override ~/.gstack state directory
+set -euo pipefail
+
+GSTACK_DIR="${GSTACK_DIR:-$(cd "$(dirname "$0")/.." && pwd)}"
+STATE_DIR="${GSTACK_STATE_DIR:-$HOME/.gstack}"
+CACHE_FILE="$STATE_DIR/last-update-check"
+MARKER_FILE="$STATE_DIR/just-upgraded-from"
+SNOOZE_FILE="$STATE_DIR/update-snoozed"
+VERSION_FILE="$GSTACK_DIR/VERSION"
+REMOTE_URL="${GSTACK_REMOTE_URL:-https://raw.githubusercontent.com/garrytan/gstack/main/VERSION}"
+REMOTE_REPO="${GSTACK_REMOTE_REPO:-https://github.com/garrytan/gstack.git}"
+
+# ─── Force flag (busts cache + snooze for standalone /gstack-upgrade) ──
+if [ "${1:-}" = "--force" ]; then
+  rm -f "$CACHE_FILE"
+  rm -f "$SNOOZE_FILE"
+fi
+
+# ─── Step 0: Check if updates are disabled ────────────────────
+_UC=$("$GSTACK_DIR/bin/gstack-config" get update_check 2>/dev/null || true)
+if [ "$_UC" = "false" ]; then
+  exit 0
+fi
+
+# ─── Migration: fix stale Codex descriptions (one-time) ───────
+# Existing installs may have .agents/skills/gstack/SKILL.md with oversized
+# descriptions (>1024 chars) that Codex rejects. We can't regenerate from
+# the runtime root (no bun/scripts), so delete oversized files — the next
+# ./setup or /gstack-upgrade will regenerate them properly.
+# Marker file ensures this runs at most once per install.
+if [ ! -f "$STATE_DIR/.codex-desc-healed" ]; then
+  for _AGENTS_SKILL in "$GSTACK_DIR"/.agents/skills/*/SKILL.md; do
+    [ -f "$_AGENTS_SKILL" ] || continue
+    _DESC=$(awk '/^---$/{n++;next}n==1&&/^description:/{d=1;sub(/^description:\s*/,"");if(length>0)print;next}d&&/^  /{sub(/^  /,"");print;next}d{d=0}' "$_AGENTS_SKILL" | wc -c | tr -d ' ')
+    if [ "${_DESC:-0}" -gt 1024 ]; then
+      rm -f "$_AGENTS_SKILL"
+    fi
+  done
+  mkdir -p "$STATE_DIR"
+  touch "$STATE_DIR/.codex-desc-healed"
+fi
+
+# ─── Snooze helper ──────────────────────────────────────────
+# check_snooze <remote_version>
+#   Returns 0 if snoozed (should stay quiet), 1 if not snoozed (should output).
+#
+#   Snooze file format: <version> <level> <epoch>
+#   Level durations: 1=24h, 2=48h, 3+=7d
+#   New version (version mismatch) resets snooze.
+check_snooze() {
+  local remote_ver="$1"
+  if [ ! -f "$SNOOZE_FILE" ]; then
+    return 1  # no snooze file → not snoozed
+  fi
+  local snoozed_ver snoozed_level snoozed_epoch
+  snoozed_ver="$(awk '{print $1}' "$SNOOZE_FILE" 2>/dev/null || true)"
+  snoozed_level="$(awk '{print $2}' "$SNOOZE_FILE" 2>/dev/null || true)"
+  snoozed_epoch="$(awk '{print $3}' "$SNOOZE_FILE" 2>/dev/null || true)"
+
+  # Validate: all three fields must be non-empty
+  if [ -z "$snoozed_ver" ] || [ -z "$snoozed_level" ] || [ -z "$snoozed_epoch" ]; then
+    return 1  # corrupt file → not snoozed
+  fi
+
+  # Validate: level and epoch must be integers
+  case "$snoozed_level" in *[!0-9]*) return 1 ;; esac
+  case "$snoozed_epoch" in *[!0-9]*) return 1 ;; esac
+
+  # New version dropped? Ignore snooze.
+  if [ "$snoozed_ver" != "$remote_ver" ]; then
+    return 1
+  fi
+
+  # Compute snooze duration based on level
+  local duration
+  case "$snoozed_level" in
+    1) duration=86400 ;;   # 24 hours
+    2) duration=172800 ;;  # 48 hours
+    *) duration=604800 ;;  # 7 days (level 3+)
+  esac
+
+  local now
+  now="$(date +%s)"
+  local expires=$(( snoozed_epoch + duration ))
+  if [ "$now" -lt "$expires" ]; then
+    return 0  # still snoozed
+  fi
+
+  return 1  # snooze expired
+}
+
+# ─── Step 1: Read local version ──────────────────────────────
+LOCAL=""
+if [ -f "$VERSION_FILE" ]; then
+  LOCAL="$(cat "$VERSION_FILE" 2>/dev/null | tr -d '[:space:]')"
+fi
+if [ -z "$LOCAL" ]; then
+  exit 0  # No VERSION file → skip check
+fi
+
+# ─── Step 2: Check "just upgraded" marker ─────────────────────
+if [ -f "$MARKER_FILE" ]; then
+  OLD="$(cat "$MARKER_FILE" 2>/dev/null | tr -d '[:space:]')"
+  rm -f "$MARKER_FILE"
+  rm -f "$SNOOZE_FILE"
+  if [ -n "$OLD" ]; then
+    echo "JUST_UPGRADED $OLD $LOCAL"
+  fi
+  # Don't exit — fall through to remote check in case
+  # more updates landed since the upgrade
+fi
+
+# ─── Step 3: Check cache freshness ──────────────────────────
+# UP_TO_DATE: 60 min TTL (detect new releases quickly)
+# UPGRADE_AVAILABLE: 720 min TTL (keep nagging)
+if [ -f "$CACHE_FILE" ]; then
+  CACHED="$(cat "$CACHE_FILE" 2>/dev/null || true)"
+  case "$CACHED" in
+    UP_TO_DATE*)        CACHE_TTL=60 ;;
+    UPGRADE_AVAILABLE*) CACHE_TTL=720 ;;
+    *)                  CACHE_TTL=0 ;;  # corrupt → force re-fetch
+  esac
+
+  STALE=$(find "$CACHE_FILE" -mmin +$CACHE_TTL 2>/dev/null || true)
+  if [ -z "$STALE" ] && [ "$CACHE_TTL" -gt 0 ]; then
+    case "$CACHED" in
+      UP_TO_DATE*)
+        CACHED_VER="$(echo "$CACHED" | awk '{print $2}')"
+        if [ "$CACHED_VER" = "$LOCAL" ]; then
+          exit 0
+        fi
+        ;;
+      UPGRADE_AVAILABLE*)
+        CACHED_OLD="$(echo "$CACHED" | awk '{print $2}')"
+        if [ "$CACHED_OLD" = "$LOCAL" ]; then
+          CACHED_NEW="$(echo "$CACHED" | awk '{print $3}')"
+          if check_snooze "$CACHED_NEW"; then
+            exit 0  # snoozed — stay quiet
+          fi
+          echo "$CACHED"
+          exit 0
+        fi
+        ;;
+    esac
+  fi
+fi
+
+# ─── Step 4: Slow path — fetch remote version ────────────────
+mkdir -p "$STATE_DIR"
+
+# Fire Supabase install ping in background (parallel, non-blocking)
+# This logs an update check event for community health metrics via edge function.
+# If Supabase is not configured or telemetry is off, this is a no-op.
+if [ -z "${GSTACK_SUPABASE_URL:-}" ] && [ -f "$GSTACK_DIR/supabase/config.sh" ]; then
+  . "$GSTACK_DIR/supabase/config.sh"
+fi
+_SUPA_URL="${GSTACK_SUPABASE_URL:-}"
+_SUPA_KEY="${GSTACK_SUPABASE_ANON_KEY:-}"
+# Respect telemetry opt-out — don't ping Supabase if user set telemetry: off
+_TEL_TIER="$("$GSTACK_DIR/bin/gstack-config" get telemetry 2>/dev/null || true)"
+if [ -n "$_SUPA_URL" ] && [ -n "$_SUPA_KEY" ] && [ "${_TEL_TIER:-off}" != "off" ]; then
+  _OS="$(uname -s | tr '[:upper:]' '[:lower:]')"
+  curl -sf --max-time 5 \
+    -X POST "${_SUPA_URL}/functions/v1/update-check" \
+    -H "Content-Type: application/json" \
+    -H "apikey: ${_SUPA_KEY}" \
+    -d "{\"version\":\"$LOCAL\",\"os\":\"$_OS\"}" \
+    >/dev/null 2>&1 &
+fi
+
+# Resolve VERSION via a SHA-pinned raw URL. GitHub's branch-raw CDN
+# (raw.githubusercontent.com/<owner>/<repo>/<branch>/...) can serve stale
+# content for several minutes after a push, which previously caused
+# /gstack-upgrade to silently report "up to date" right after a release
+# landed. git ls-remote always returns the live HEAD; SHA-pinned raw URLs
+# are immediately consistent.
+#
+# An explicit GSTACK_REMOTE_URL override (tests, mirrors) skips this path
+# so the override is honored verbatim.
+REMOTE=""
+if [ -z "${GSTACK_REMOTE_URL:-}" ]; then
+  # Disable credential prompts and apply a 5-second low-speed timeout so a
+  # flaky network or captive portal can't hang every skill preamble.
+  _LSR_LINE="$(GIT_TERMINAL_PROMPT=0 GIT_HTTP_LOW_SPEED_LIMIT=1000 GIT_HTTP_LOW_SPEED_TIME=5 \
+    git ls-remote "$REMOTE_REPO" refs/heads/main 2>/dev/null || true)"
+  _REMOTE_SHA="$(echo "$_LSR_LINE" | awk '{print $1}')"
+  if echo "$_REMOTE_SHA" | grep -qE '^[0-9a-f]{40}$'; then
+    _SHA_URL="https://raw.githubusercontent.com/garrytan/gstack/${_REMOTE_SHA}/VERSION"
+    REMOTE="$(curl -sf --max-time 5 "$_SHA_URL" 2>/dev/null || true)"
+  fi
+fi
+
+# Fallback: branch-pinned URL when ls-remote is unavailable (no git, no
+# network, mirror without refs/heads/main) or when GSTACK_REMOTE_URL was
+# explicitly overridden.
+if [ -z "$REMOTE" ]; then
+  REMOTE="$(curl -sf --max-time 5 "$REMOTE_URL" 2>/dev/null || true)"
+fi
+REMOTE="$(echo "$REMOTE" | tr -d '[:space:]')"
+
+# Validate: must look like a version number (reject HTML error pages)
+if ! echo "$REMOTE" | grep -qE '^[0-9]+\.[0-9.]+$'; then
+  # Invalid or empty response — assume up to date
+  echo "UP_TO_DATE $LOCAL" > "$CACHE_FILE"
+  exit 0
+fi
+
+if [ "$LOCAL" = "$REMOTE" ]; then
+  echo "UP_TO_DATE $LOCAL" > "$CACHE_FILE"
+  exit 0
+fi
+
+# Semver-order guard: only flag an upgrade when REMOTE sorts higher than
+# LOCAL. Protects against transient stale-CDN regressions (REMOTE < LOCAL)
+# and dev installs running ahead of main, both of which would otherwise
+# emit a backwards UPGRADE_AVAILABLE line.
+_HIGHER="$(printf '%s\n%s\n' "$LOCAL" "$REMOTE" | sort -V | tail -1)"
+if [ "$_HIGHER" != "$REMOTE" ]; then
+  echo "UP_TO_DATE $LOCAL" > "$CACHE_FILE"
+  exit 0
+fi
+
+# REMOTE is strictly newer — upgrade available
+echo "UPGRADE_AVAILABLE $LOCAL $REMOTE" > "$CACHE_FILE"
+if check_snooze "$REMOTE"; then
+  exit 0  # snoozed — stay quiet
+fi
+
+# Log upgrade_prompted event (only on slow-path fetch, not cached replays)
+TEL_CMD="$GSTACK_DIR/bin/gstack-telemetry-log"
+if [ -x "$TEL_CMD" ]; then
+  "$TEL_CMD" --event-type upgrade_prompted --skill "" --duration 0 \
+    --outcome success --session-id "update-$$-$(date +%s)" 2>/dev/null &
+fi
+
+echo "UPGRADE_AVAILABLE $LOCAL $REMOTE"