Merge origin/main into garrytan/upgrade-gstack-gbrain-v1

Catch up to main (1.52.0.0, plan-tune cathedral + browse memory work).
Branch bumps to 1.52.1.0 — PATCH above main.

Conflict resolutions:
- VERSION / package.json → 1.52.1.0 (monotonic above main's 1.52.0.0)
- CHANGELOG.md → reconstructed reverse-chronological: this branch's
  brain-aware-planning + save-results entry renumbered 1.51.1.0 →
  1.52.1.0 on top, then main's 1.52.0.0 / 1.51.0.0 / 1.49.0.0 entries,
  then shared history. No entries dropped or orphaned.
- setup → kept both endgame blocks (my gbrain detection + main's
  plan-tune cathedral hook install); they're independent.
- SKILL.md files → regenerated from merged templates via
  bun run gen:skill-docs (canonical no-gbrain), not accepted from
  either merge side, per CLAUDE.md. Idempotent (0 STALE on re-run).
- bin/gstack-config → both sides' additions present (main's
  GSTACK_STATE_ROOT support + this branch's gbrain-refresh subcommand).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

bin/gstack-codex-session-import

@@ -0,0 +1,223 @@
+#!/usr/bin/env bash
+# gstack-codex-session-import — backfill question-log.jsonl from Codex sessions.
+#
+# Codex has no AskUserQuestion tool (per docs/spikes/codex-session-format.md).
+# gstack skills running on Codex emit Decision Briefs as plain agent_message
+# text, and the user's response shows up in the next user_message. This
+# importer reconstructs those question/answer pairs from the structured
+# JSONL session files at ~/.codex/sessions/<date>/.
+#
+# Usage:
+#   gstack-codex-session-import                   # latest session under ~/.codex/sessions/
+#   gstack-codex-session-import <path/to.jsonl>   # explicit session file
+#   gstack-codex-session-import --since <iso>     # all sessions newer than <iso>
+#
+# Recovery strategy (two-tier per D5/T4 spike):
+#   1. Marker-first: extract <gstack-qid:foo-bar> from agent_message → stable id.
+#   2. Pattern fallback: detect D<N> header + numbered options → hash id
+#      (source=codex-import-pattern, never used as preference key per D18).
+#
+# Writes via bin/gstack-question-log so source tagging, dedup, and async
+# derive all apply uniformly.
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+GSTACK_HOME="${GSTACK_STATE_ROOT:-${GSTACK_HOME:-$HOME/.gstack}}"
+CODEX_SESSIONS_ROOT="${CODEX_SESSIONS_ROOT:-$HOME/.codex/sessions}"
+
+MODE="latest"
+EXPLICIT_PATH=""
+SINCE_ISO=""
+
+if [ $# -gt 0 ]; then
+  case "$1" in
+    --since)
+      MODE="since"
+      SINCE_ISO="${2:-}"
+      ;;
+    --help|-h)
+      sed -n '1,/^set -euo/p' "$0" | sed 's|^# \?||'
+      exit 0
+      ;;
+    -*)
+      echo "unknown flag: $1" >&2
+      exit 1
+      ;;
+    *)
+      MODE="explicit"
+      EXPLICIT_PATH="$1"
+      ;;
+  esac
+fi
+
+# Resolve list of session files to process.
+SESSION_FILES=()
+case "$MODE" in
+  explicit)
+    if [ ! -f "$EXPLICIT_PATH" ]; then
+      echo "gstack-codex-session-import: file not found: $EXPLICIT_PATH" >&2
+      exit 1
+    fi
+    SESSION_FILES=("$EXPLICIT_PATH")
+    ;;
+  latest)
+    if [ ! -d "$CODEX_SESSIONS_ROOT" ]; then
+      echo "NO_SESSIONS: $CODEX_SESSIONS_ROOT does not exist"
+      exit 0
+    fi
+    LATEST=$(find "$CODEX_SESSIONS_ROOT" -type f -name "rollout-*.jsonl" -print 2>/dev/null \
+      | xargs ls -t 2>/dev/null | head -1 || true)
+    if [ -z "$LATEST" ]; then
+      echo "NO_SESSIONS: no rollout-*.jsonl files under $CODEX_SESSIONS_ROOT"
+      exit 0
+    fi
+    SESSION_FILES=("$LATEST")
+    ;;
+  since)
+    if [ -z "$SINCE_ISO" ]; then
+      echo "--since requires an ISO 8601 timestamp" >&2
+      exit 1
+    fi
+    while IFS= read -r f; do
+      SESSION_FILES+=("$f")
+    done < <(find "$CODEX_SESSIONS_ROOT" -type f -name "rollout-*.jsonl" -newer <(date -u -d "$SINCE_ISO" 2>/dev/null || date -u) 2>/dev/null)
+    ;;
+esac
+
+if [ ${#SESSION_FILES[@]} -eq 0 ]; then
+  echo "NO_SESSIONS: nothing to import"
+  exit 0
+fi
+
+# Parse + extract via bun. Emits one line per question found, ready to pipe
+# into gstack-question-log. Tagged with source so downstream consumers
+# (/plan-tune stats, dream cycle) can distinguish backfilled events from
+# live captures.
+IMPORTED=0
+SKIPPED_NO_ANSWER=0
+
+for SESSION_FILE in "${SESSION_FILES[@]}"; do
+  COUNT_LINE=$(SESSION_FILE_PATH="$SESSION_FILE" QLOG_BIN="$SCRIPT_DIR/gstack-question-log" bun -e '
+    const fs = require("fs");
+    const path = require("path");
+    const { spawnSync } = require("child_process");
+    const crypto = require("crypto");
+
+    const sessionPath = process.env.SESSION_FILE_PATH;
+    const qlogBin = process.env.QLOG_BIN;
+    const lines = fs.readFileSync(sessionPath, "utf-8").trim().split("\n").filter(Boolean);
+
+    let meta = null;
+    const stream = [];
+    for (const ln of lines) {
+      try {
+        const e = JSON.parse(ln);
+        if (e.type === "session_meta") meta = e.payload;
+        else stream.push(e);
+      } catch {}
+    }
+    if (!meta) {
+      console.error("WARN: no session_meta in " + sessionPath);
+      console.log("0 0");
+      process.exit(0);
+    }
+
+    const cwd = meta.cwd || "";
+    const sessionId = (meta.id || path.basename(sessionPath)).slice(0, 64);
+
+    // Walk for agent_message → next user_message pairs.
+    const briefs = [];
+    for (let i = 0; i < stream.length; i++) {
+      const e = stream[i];
+      if (e.type !== "event_msg" || e.payload?.type !== "agent_message") continue;
+      const text = String(e.payload?.message || "");
+      if (!text) continue;
+      // Detect D-numbered brief or marker. Markers are sufficient on their own.
+      const markerMatch = text.match(/<gstack-qid:([a-z0-9-]{1,64})>/i);
+      const dMatch = text.match(/^D\d+[\.\d]*\s*[—\-]\s*(.+?)$/m);
+      if (!markerMatch && !dMatch) continue;
+
+      // Find the next user_message in the stream.
+      let answer = null;
+      for (let j = i + 1; j < stream.length; j++) {
+        const e2 = stream[j];
+        if (e2.type === "event_msg" && e2.payload?.type === "user_message") {
+          answer = String(e2.payload?.message || "").trim();
+          break;
+        }
+      }
+      if (!answer) continue;
+
+      // Extract options A) ... B) ... from the brief.
+      const optMatches = [...text.matchAll(/^([A-Z])\)\s+(.+?)(?:\s+\(recommended\))?$/gm)];
+      const options = optMatches.map((m) => m[2].trim());
+
+      // Identify recommended option (label first, prose fallback).
+      let recommended;
+      const recLabel = [...text.matchAll(/^([A-Z])\)\s+(.+?)\s+\(recommended\)$/gm)];
+      if (recLabel.length === 1) recommended = recLabel[0][2].trim();
+
+      // Identify which option the user picked from their answer.
+      // Look for "A" / "A) ..." / option-label prefix match.
+      let userChoice = "__unknown__";
+      const letterMatch = answer.match(/^\s*([A-Z])\b/);
+      if (letterMatch) {
+        const idx = letterMatch[1].charCodeAt(0) - 65;
+        if (idx >= 0 && idx < options.length) userChoice = options[idx];
+        else userChoice = letterMatch[1];
+      } else if (options.length > 0) {
+        const lower = answer.toLowerCase();
+        const m = options.find((o) => lower.includes(o.toLowerCase().slice(0, 12)));
+        if (m) userChoice = m;
+      }
+      if (userChoice === "__unknown__") {
+        userChoice = answer.slice(0, 64);
+      }
+
+      const summary = (dMatch?.[1] || text.split("\n")[0]).slice(0, 200);
+
+      let questionId, source;
+      if (markerMatch) {
+        questionId = markerMatch[1];
+        source = "codex-import-marker";
+      } else {
+        const sortedOpts = [...options].sort().join("|");
+        const h = crypto.createHash("sha1").update("codex::" + summary + "::" + sortedOpts).digest("hex").slice(0, 10);
+        questionId = "hook-" + h;
+        source = "codex-import-pattern";
+      }
+
+      briefs.push({
+        skill: "codex",
+        question_id: questionId,
+        question_summary: summary,
+        options_count: options.length || 1,
+        user_choice: userChoice.slice(0, 64),
+        ...(recommended ? { recommended: recommended.slice(0, 64) } : {}),
+        source,
+        session_id: sessionId,
+        // Use ts_nanos+ts shape from the event itself if available; else null.
+        ts: e.timestamp || undefined,
+      });
+    }
+
+    let imported = 0;
+    for (const b of briefs) {
+      const res = spawnSync(qlogBin, [JSON.stringify(b)], {
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "pipe"],
+        // Run from the originating cwd so gstack-slug bucks events into the
+        // right project. Falls back to the importer cwd if the session cwd
+        // no longer exists.
+        cwd: cwd && fs.existsSync(cwd) ? cwd : undefined,
+        timeout: 5000,
+      });
+      if (res.status === 0) imported++;
+    }
+    console.log(imported + " 0");
+  ' 2>&1)
+
+  IMP=$(echo "$COUNT_LINE" | awk "{print \$1}")
+  IMPORTED=$((IMPORTED + IMP))
+done
+
+echo "IMPORTED: $IMPORTED events from ${#SESSION_FILES[@]} session(s)"

bin/gstack-config

@@ -8,11 +8,13 @@
 #   gstack-config defaults           — show just the defaults table
 #
 # Env overrides (for testing):
+#   GSTACK_STATE_ROOT — override ~/.gstack state directory (highest priority,
+#                       matches D16 cathedral isolation convention)
 #   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}}"
+STATE_DIR="${GSTACK_STATE_ROOT:-${GSTACK_HOME:-${GSTACK_STATE_DIR:-$HOME/.gstack}}}"
 CONFIG_FILE="$STATE_DIR/config.yaml"
 
 # Annotated header for new config files. Written once on first `set`.

bin/gstack-developer-profile

@@ -28,7 +28,8 @@ set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
-GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
+# GSTACK_STATE_ROOT takes precedence over GSTACK_HOME (test isolation per D16).
+GSTACK_HOME="${GSTACK_STATE_ROOT:-${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)"

bin/gstack-distill-apply

@@ -0,0 +1,181 @@
+#!/usr/bin/env bash
+# gstack-distill-apply — apply a single distillation proposal after user Y.
+#
+# Plan-tune cathedral T11. Reads distillation-proposals.json, applies the
+# Nth proposal to the right surface:
+#
+#   preference     → gstack-question-preference --write
+#   declared-nudge → atomic update to ~/.gstack/developer-profile.json declared
+#   memory-nugget  → append to ~/.gstack/free-text-memory.json (local fallback)
+#
+# Always confirm before calling this from the skill — the bin assumes the user
+# already approved (Codex #15 trust boundary). The skill template (/plan-tune
+# distill review section) handles the confirm UX.
+#
+# gbrain integration: when gbrain is configured, the skill template ALSO
+# invokes mcp__gbrain__put_page / extract_facts / add_tag in the same turn
+# (those are MCP tools, not CLI-callable). Pass --gbrain-published true to
+# mark the proposal as mirrored to gbrain. The local file always gets the
+# write so it's the durable source-of-truth even on machines without gbrain.
+#
+# Usage:
+#   gstack-distill-apply --proposal <N>                # apply Nth proposal
+#   gstack-distill-apply --proposal <N> --gbrain-published true
+#   gstack-distill-apply --list                        # show pending proposals
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+GSTACK_HOME="${GSTACK_STATE_ROOT:-${GSTACK_HOME:-$HOME/.gstack}}"
+eval "$("$SCRIPT_DIR/gstack-slug" 2>/dev/null || true)"
+SLUG="${SLUG:-unknown}"
+PROJECT_DIR="$GSTACK_HOME/projects/$SLUG"
+PROPOSAL_FILE="$PROJECT_DIR/distillation-proposals.json"
+MEMORY_FILE="$GSTACK_HOME/free-text-memory.json"
+PROFILE_FILE="$GSTACK_HOME/developer-profile.json"
+
+ACTION="apply"
+PROPOSAL_IDX=""
+GBRAIN_PUBLISHED="false"
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --proposal) PROPOSAL_IDX="$2"; shift 2 ;;
+    --gbrain-published) GBRAIN_PUBLISHED="$2"; shift 2 ;;
+    --list) ACTION="list"; shift ;;
+    --help|-h)
+      sed -n '1,/^set -euo/p' "$0" | sed 's|^# \?||'
+      exit 0
+      ;;
+    *) echo "unknown arg: $1" >&2; exit 1 ;;
+  esac
+done
+
+if [ ! -f "$PROPOSAL_FILE" ]; then
+  echo "NO_PROPOSALS: $PROPOSAL_FILE missing — run gstack-distill-free-text first"
+  exit 0
+fi
+
+if [ "$ACTION" = "list" ]; then
+  PROPOSAL_FILE_PATH="$PROPOSAL_FILE" bun -e '
+    const fs = require("fs");
+    const p = JSON.parse(fs.readFileSync(process.env.PROPOSAL_FILE_PATH, "utf-8"));
+    const proposals = p.proposals || [];
+    if (proposals.length === 0) { console.log("(no proposals)"); process.exit(0); }
+    console.log("GENERATED: " + p.generated_at);
+    console.log("SOURCE_EVENTS: " + (p.source_event_count || 0));
+    proposals.forEach((pr, i) => {
+      console.log("");
+      console.log("[" + i + "] " + (pr.kind || "?") + " (confidence: " + (pr.confidence || "?") + ")");
+      if (pr.rationale) console.log("    rationale: " + pr.rationale);
+      if (pr.kind === "preference") {
+        console.log("    question_id: " + pr.question_id);
+        console.log("    preference: " + pr.preference);
+      } else if (pr.kind === "declared-nudge") {
+        console.log("    dimension: " + pr.dimension);
+        console.log("    direction: " + pr.direction + " (" + (pr.magnitude || "?") + ")");
+      } else if (pr.kind === "memory-nugget") {
+        console.log("    nugget: " + pr.nugget);
+        console.log("    signal_keys: " + JSON.stringify(pr.applies_to_signal_keys || []));
+      }
+      if (pr.source_quotes && pr.source_quotes.length) {
+        console.log("    quotes:");
+        pr.source_quotes.forEach((q) => console.log("      - \"" + q + "\""));
+      }
+    });
+  '
+  exit 0
+fi
+
+if [ -z "$PROPOSAL_IDX" ]; then
+  echo "--proposal <N> required" >&2
+  exit 1
+fi
+
+# Apply via bun. Each kind has its own surface.
+mkdir -p "$PROJECT_DIR"
+PROPOSAL_IDX="$PROPOSAL_IDX" \
+PROPOSAL_FILE_PATH="$PROPOSAL_FILE" \
+MEMORY_FILE_PATH="$MEMORY_FILE" \
+PROFILE_FILE_PATH="$PROFILE_FILE" \
+PREF_BIN="$SCRIPT_DIR/gstack-question-preference" \
+GBRAIN_PUBLISHED="$GBRAIN_PUBLISHED" \
+bun -e '
+  const fs = require("fs");
+  const { spawnSync } = require("child_process");
+  const idx = parseInt(process.env.PROPOSAL_IDX, 10);
+  const p = JSON.parse(fs.readFileSync(process.env.PROPOSAL_FILE_PATH, "utf-8"));
+  const proposals = p.proposals || [];
+  if (!Number.isInteger(idx) || idx < 0 || idx >= proposals.length) {
+    process.stderr.write("invalid --proposal index " + idx + " (have " + proposals.length + ")\n");
+    process.exit(1);
+  }
+  const pr = proposals[idx];
+
+  const stamp = new Date().toISOString();
+
+  // Memory-nugget: always write to local file (durable source-of-truth even
+  // when gbrain is configured — gbrain is mirror, file is canon for the
+  // PreToolUse hook injection path in Layer 8).
+  if (pr.kind === "memory-nugget") {
+    const memPath = process.env.MEMORY_FILE_PATH;
+    let mem = { nuggets: [] };
+    try { mem = JSON.parse(fs.readFileSync(memPath, "utf-8")); } catch {}
+    if (!Array.isArray(mem.nuggets)) mem.nuggets = [];
+    mem.nuggets.push({
+      nugget: pr.nugget,
+      applies_to_signal_keys: pr.applies_to_signal_keys || [],
+      applied_at: stamp,
+      gbrain_published: process.env.GBRAIN_PUBLISHED === "true",
+      source_quotes: pr.source_quotes || [],
+    });
+    const tmp = memPath + ".tmp";
+    fs.writeFileSync(tmp, JSON.stringify(mem, null, 2));
+    fs.renameSync(tmp, memPath);
+    console.log("APPLIED: memory-nugget appended to " + memPath);
+  }
+
+  // Preference: route through gstack-question-preference for the user-origin
+  // gate + event audit trail. source=plan-tune is the allowed value since
+  // the user opt-in came from inside /plan-tune.
+  if (pr.kind === "preference") {
+    const res = spawnSync(process.env.PREF_BIN, [
+      "--write",
+      JSON.stringify({
+        question_id: pr.question_id,
+        preference: pr.preference,
+        source: "plan-tune",
+        free_text: (pr.source_quotes || []).join(" | ").slice(0, 300),
+      }),
+    ], { encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], timeout: 5000 });
+    if (res.status !== 0) {
+      process.stderr.write("preference apply failed: " + (res.stderr || res.stdout) + "\n");
+      process.exit(1);
+    }
+    console.log("APPLIED: preference " + pr.question_id + " → " + pr.preference);
+  }
+
+  // Declared-nudge: atomic update to developer-profile.json declared. Magnitude
+  // tiers: small=0.05, medium=0.10, large=0.15. Clamp to [0, 1].
+  if (pr.kind === "declared-nudge") {
+    const mag = { small: 0.05, medium: 0.10, large: 0.15 }[pr.magnitude || "small"] || 0.05;
+    const delta = pr.direction === "down" ? -mag : mag;
+    const profilePath = process.env.PROFILE_FILE_PATH;
+    let profile = {};
+    try { profile = JSON.parse(fs.readFileSync(profilePath, "utf-8")); } catch {}
+    profile.declared = profile.declared || {};
+    const cur = typeof profile.declared[pr.dimension] === "number" ? profile.declared[pr.dimension] : 0.5;
+    const next = Math.max(0, Math.min(1, cur + delta));
+    profile.declared[pr.dimension] = +next.toFixed(3);
+    profile.declared_at = stamp;
+    const tmp = profilePath + ".tmp";
+    fs.writeFileSync(tmp, JSON.stringify(profile, null, 2));
+    fs.renameSync(tmp, profilePath);
+    console.log("APPLIED: declared." + pr.dimension + " " + cur + " → " + profile.declared[pr.dimension]);
+  }
+
+  // Mark the proposal as applied so /plan-tune list shows it consumed.
+  pr.applied_at = stamp;
+  pr.gbrain_published = process.env.GBRAIN_PUBLISHED === "true";
+  const tmp = process.env.PROPOSAL_FILE_PATH + ".tmp";
+  fs.writeFileSync(tmp, JSON.stringify(p, null, 2));
+  fs.renameSync(tmp, process.env.PROPOSAL_FILE_PATH);
+'

bin/gstack-distill-free-text

@@ -0,0 +1,272 @@
+#!/usr/bin/env bash
+# gstack-distill-free-text — Layer 8 "dream cycle" batch distiller.
+#
+# Reads auq-other free-text events from this project's question-log.jsonl,
+# sends them to Claude via the Anthropic SDK, and writes structured proposals
+# the user can review via /plan-tune distill. Proposals require explicit
+# user Y before applying — never autonomous (Codex #15 trust boundary).
+#
+# Usage:
+#   gstack-distill-free-text                       # sync, prompts at end
+#   gstack-distill-free-text --background          # spawn detached; results
+#                                                  # surface on next /plan-tune
+#   gstack-distill-free-text --dry-run             # show prompt, no API call
+#   gstack-distill-free-text --status              # show last-run stats
+#
+# No rate cap — the natural rate of free-text events (rare; user has to type
+# "Other" then content) bounds this loop already. Each Haiku call is ~$0.01,
+# so even a runaway at one-per-minute would be ~$14/day worst case. The
+# cumulative cost log at $GSTACK_STATE_ROOT/distill-cost.jsonl gives full
+# auditability via --status when you want it.
+# Per D6: Anthropic SDK direct call, fail-loud on missing ANTHROPIC_API_KEY.
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+GSTACK_HOME="${GSTACK_STATE_ROOT:-${GSTACK_HOME:-$HOME/.gstack}}"
+eval "$("$SCRIPT_DIR/gstack-slug" 2>/dev/null || true)"
+SLUG="${SLUG:-unknown}"
+PROJECT_DIR="$GSTACK_HOME/projects/$SLUG"
+LOG_FILE="$PROJECT_DIR/question-log.jsonl"
+PROPOSAL_FILE="$PROJECT_DIR/distillation-proposals.json"
+COST_LOG="$GSTACK_HOME/distill-cost.jsonl"
+mkdir -p "$PROJECT_DIR"
+
+MODE="sync"
+case "${1:-}" in
+  --background) MODE="background" ;;
+  --dry-run)    MODE="dry-run" ;;
+  --status)     MODE="status" ;;
+  --help|-h)
+    sed -n '1,/^set -euo/p' "$0" | sed 's|^# \?||'
+    exit 0
+    ;;
+  '') ;;
+  *) echo "unknown arg: $1" >&2; exit 1 ;;
+esac
+
+# --- Status subcommand --------------------------------------------------
+
+if [ "$MODE" = "status" ]; then
+  COST_LOG_PATH="$COST_LOG" SLUG_PATH="$SLUG" bun -e '
+    const fs = require("fs");
+    const slug = process.env.SLUG_PATH;
+    const path = process.env.COST_LOG_PATH;
+    if (!fs.existsSync(path)) { console.log("no distill runs yet"); process.exit(0); }
+    const lines = fs.readFileSync(path, "utf-8").trim().split("\n").filter(Boolean);
+    const mine = lines.map((l) => JSON.parse(l)).filter((e) => e.slug === slug);
+    if (mine.length === 0) { console.log("no distill runs yet for slug=" + slug); process.exit(0); }
+    const totalUsd = mine.reduce((a, e) => a + (e.cost_usd_est || 0), 0);
+    const todayIso = new Date().toISOString().slice(0, 10);
+    const today = mine.filter((e) => (e.ts || "").startsWith(todayIso));
+    const todayUsd = today.reduce((a, e) => a + (e.cost_usd_est || 0), 0);
+    console.log("RUNS: " + mine.length);
+    console.log("TODAY: " + today.length + " run(s), $" + todayUsd.toFixed(4));
+    console.log("ESTIMATED_TOTAL_USD: $" + totalUsd.toFixed(4));
+    const last = mine[mine.length - 1];
+    console.log("LAST_RUN: " + (last.ts || "?") + " | " + (last.proposals_count || 0) + " proposals");
+  '
+  exit 0
+fi
+
+# --- Background mode: detach + invoke self synchronously ---------------
+
+if [ "$MODE" = "background" ]; then
+  nohup "$0" >/dev/null 2>&1 &
+  echo "DISTILL_SPAWNED: pid=$!"
+  exit 0
+fi
+
+# No rate cap. Natural input rate (free-text events are rare) + Haiku price
+# (~$0.01/run) keep this bounded. Use --status to audit spend.
+
+# --- Gather unprocessed auq-other events from this project -------------
+
+if [ ! -f "$LOG_FILE" ]; then
+  echo "NO_LOG: no question-log.jsonl in $PROJECT_DIR"
+  exit 0
+fi
+
+EVENTS_JSON=$(LOG_FILE_PATH="$LOG_FILE" bun -e '
+  const fs = require("fs");
+  const lines = fs.readFileSync(process.env.LOG_FILE_PATH, "utf-8").trim().split("\n").filter(Boolean);
+  const out = [];
+  for (const l of lines) {
+    try {
+      const e = JSON.parse(l);
+      if (e.source === "auq-other" && !e.distilled_at && e.free_text) {
+        out.push({
+          ts: e.ts,
+          question_id: e.question_id,
+          question_summary: e.question_summary,
+          free_text: e.free_text,
+          session_id: e.session_id,
+        });
+      }
+    } catch {}
+  }
+  process.stdout.write(JSON.stringify(out));
+')
+
+EVENT_COUNT=$(printf '%s' "$EVENTS_JSON" | bun -e 'const a = JSON.parse(await Bun.stdin.text()); console.log(a.length);')
+if [ "$EVENT_COUNT" -eq 0 ]; then
+  echo "NO_FREE_TEXT: nothing to distill"
+  exit 0
+fi
+
+# --- Build distill prompt ---------------------------------------------
+
+# Heredoc into temp file (avoids $(cat <<'PROMPT'...) which choked the
+# bash parser on apostrophes elsewhere in the script).
+DISTILL_PROMPT_FILE=$(mktemp)
+trap 'rm -f "$DISTILL_PROMPT_FILE"' EXIT
+cat > "$DISTILL_PROMPT_FILE" <<'PROMPT'
+You are gstack dream-cycle distiller. Below are free-text responses the
+user typed into AskUserQuestion prompts (option "Other") across recent gstack
+sessions. For each response, extract structured signal that should update the
+user plan-tune profile or preferences.
+
+Return strict JSON with this shape:
+{
+  "proposals": [
+    {
+      "kind": "preference" | "declared-nudge" | "memory-nugget",
+      "confidence": 0.0-1.0,
+      "source_quotes": ["<verbatim quote 1>", "<verbatim quote 2>"],
+      "question_id": "<id>",
+      "preference": "never-ask" | "always-ask" | "ask-only-for-one-way",
+      "dimension": "scope_appetite | risk_tolerance | detail_preference | autonomy | architecture_care",
+      "direction": "up | down",
+      "magnitude": "small | medium | large",
+      "rationale": "<one sentence>",
+      "nugget": "<one-line memory>",
+      "applies_to_signal_keys": ["scope-appetite", "..."]
+    }
+  ]
+}
+
+Rules:
+- Reject any proposal where confidence < 0.7.
+- Quote VERBATIM from the user free_text. Never paraphrase a source quote.
+- A single user response may produce multiple proposals.
+- If nothing meaningful to extract, return {"proposals": []}.
+- No commentary outside the JSON.
+PROMPT
+DISTILL_PROMPT=$(cat "$DISTILL_PROMPT_FILE")
+
+# --- Dry-run: emit prompt + events, exit ------------------------------
+
+if [ "$MODE" = "dry-run" ]; then
+  echo "=== DISTILL PROMPT ==="
+  echo "$DISTILL_PROMPT"
+  echo
+  echo "=== EVENTS ($EVENT_COUNT) ==="
+  echo "$EVENTS_JSON" | bun -e 'console.log(JSON.stringify(JSON.parse(await Bun.stdin.text()), null, 2));'
+  exit 0
+fi
+
+# --- SDK call: fail-loud on missing key -------------------------------
+
+if [ -z "${ANTHROPIC_API_KEY:-}" ]; then
+  cat <<EOF >&2
+gstack-distill-free-text: ANTHROPIC_API_KEY not set.
+
+Dream-cycle distillation needs an API key for the SDK call. Set
+ANTHROPIC_API_KEY in your environment, or run with --dry-run to see
+what would be sent without actually calling.
+
+Note: this is a separate billing/auth surface from your interactive
+Claude Code session (per Codex correction in D6).
+EOF
+  exit 1
+fi
+
+# Run the SDK call in bun. Emits JSON: {proposals_count, cost_usd_est}.
+RESULT=$(EVENTS_JSON="$EVENTS_JSON" DISTILL_PROMPT="$DISTILL_PROMPT" \
+         PROPOSAL_FILE_PATH="$PROPOSAL_FILE" LOG_FILE_PATH="$LOG_FILE" \
+         ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
+         bun --cwd "$ROOT_DIR" -e '
+  const fs = require("fs");
+  const Anthropic = require("@anthropic-ai/sdk").default;
+  const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
+
+  const events = JSON.parse(process.env.EVENTS_JSON);
+  const prompt = process.env.DISTILL_PROMPT + "\n\nFREE-TEXT RESPONSES (JSON array):\n" + JSON.stringify(events, null, 2);
+
+  // Pricing (Haiku 4.5 — cheap, fast, sufficient for structured extraction).
+  // Per token, USD: input $0.001/1k = 1e-6, output $0.005/1k = 5e-6.
+  const INPUT_PER_TOKEN = 1e-6;
+  const OUTPUT_PER_TOKEN = 5e-6;
+
+  const resp = await client.messages.create({
+    model: "claude-haiku-4-5-20251001",
+    max_tokens: 4096,
+    messages: [{ role: "user", content: prompt }],
+  });
+
+  const text = resp.content.map((b) => (b.type === "text" ? b.text : "")).join("");
+
+  // Strip optional fenced code blocks the model may wrap JSON in.
+  const stripped = text.replace(/^```(?:json)?\s*/i, "").replace(/```\s*$/i, "").trim();
+  let parsed;
+  try { parsed = JSON.parse(stripped); } catch (e) {
+    process.stderr.write("DISTILL: model returned non-JSON: " + text.slice(0, 200) + "\n");
+    process.exit(1);
+  }
+
+  const proposals = Array.isArray(parsed.proposals) ? parsed.proposals : [];
+  // Keep only proposals with confidence >= 0.7 (model is told this rule;
+  // double-check in case it slipped).
+  const filtered = proposals.filter((p) => typeof p.confidence === "number" && p.confidence >= 0.7);
+
+  // Write proposals file (overwrite — only the latest run is reviewable).
+  fs.writeFileSync(process.env.PROPOSAL_FILE_PATH, JSON.stringify({
+    generated_at: new Date().toISOString(),
+    source_event_count: events.length,
+    proposals: filtered,
+  }, null, 2));
+
+  // Mark source events as distilled_at so they do not re-propose.
+  // Update question-log.jsonl in place: read all, rewrite with distilled_at
+  // set on the matching events. Match by ts + question_id.
+  const logPath = process.env.LOG_FILE_PATH;
+  const distilledAt = new Date().toISOString();
+  const matchKeys = new Set(events.map((e) => (e.ts || "") + "::" + (e.question_id || "")));
+  const lines = fs.readFileSync(logPath, "utf-8").split("\n");
+  const out = [];
+  for (const ln of lines) {
+    if (!ln.trim()) { out.push(ln); continue; }
+    try {
+      const e = JSON.parse(ln);
+      const key = (e.ts || "") + "::" + (e.question_id || "");
+      if (matchKeys.has(key)) {
+        e.distilled_at = distilledAt;
+        out.push(JSON.stringify(e));
+      } else {
+        out.push(ln);
+      }
+    } catch { out.push(ln); }
+  }
+  fs.writeFileSync(logPath, out.join("\n"));
+
+  // Cost estimate from usage tokens.
+  const usage = resp.usage || {};
+  const inTok = usage.input_tokens || 0;
+  const outTok = usage.output_tokens || 0;
+  const cost = inTok * INPUT_PER_TOKEN + outTok * OUTPUT_PER_TOKEN;
+
+  process.stdout.write(JSON.stringify({
+    proposals_count: filtered.length,
+    rejected_low_confidence: proposals.length - filtered.length,
+    input_tokens: inTok,
+    output_tokens: outTok,
+    cost_usd_est: cost,
+  }));
+')
+
+# Append cost log line.
+TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+echo "{\"ts\":\"$TS\",\"slug\":\"$SLUG\",$(echo "$RESULT" | sed 's/^{//; s/}$//')}" >> "$COST_LOG"
+
+echo "DISTILL_COMPLETE:"
+echo "  proposals_file: $PROPOSAL_FILE"
+echo "  $RESULT"

bin/gstack-question-log

@@ -28,7 +28,8 @@
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 eval "$("$SCRIPT_DIR/gstack-slug" 2>/dev/null)"
-GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
+# GSTACK_STATE_ROOT takes precedence over GSTACK_HOME (test isolation per D16).
+GSTACK_HOME="${GSTACK_STATE_ROOT:-${GSTACK_HOME:-$HOME/.gstack}}"
 mkdir -p "$GSTACK_HOME/projects/$SLUG"
 
 INPUT="$1"
@@ -49,12 +50,48 @@ if (!j.skill || !/^[a-z0-9-]+\$/.test(j.skill)) {
   process.exit(1);
 }
 
-// Required: question_id (kebab-case, <=64 chars)
+// Required: question_id (kebab-case, <=64 chars).
+// Cathedral T5: hook-sourced events use 'hook-<10-char-hash>' which is
+// kebab-case-compatible and passes the same regex.
 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);
 }
 
+// Optional: source — tags which writer produced this event.
+//   'agent' (default) — preamble-driven write from inside the running agent
+//   'hook'             — PostToolUse hook captured it deterministically (T5)
+//   'auq-other'        — user picked 'Other' and typed free text (Layer 8)
+//   'auto-decided'     — PreToolUse enforcement hook substituted the answer (T6)
+//   'codex-import-marker' / 'codex-import-pattern' — T9 backfill from Codex
+const ALLOWED_SOURCES = ['agent', 'hook', 'auq-other', 'auto-decided', 'codex-import-marker', 'codex-import-pattern'];
+if (j.source !== undefined) {
+  if (!ALLOWED_SOURCES.includes(j.source)) {
+    process.stderr.write('gstack-question-log: invalid source, must be one of: ' + ALLOWED_SOURCES.join(', ') + '\n');
+    process.exit(1);
+  }
+} else {
+  j.source = 'agent';
+}
+
+// Optional: tool_use_id — Claude Code hook stdin field; used for dedup.
+if (j.tool_use_id !== undefined) {
+  if (typeof j.tool_use_id !== 'string' || j.tool_use_id.length > 128) {
+    process.stderr.write('gstack-question-log: tool_use_id must be string <=128 chars\n');
+    process.exit(1);
+  }
+}
+
+// Optional: free_text — sanitize (no newlines, <=300 chars).
+if (j.free_text !== undefined) {
+  if (typeof j.free_text !== 'string') {
+    process.stderr.write('gstack-question-log: 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, ' ');
+}
+
 // 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');
@@ -164,7 +201,49 @@ if [ $VALIDATE_RC -ne 0 ] || [ -z "$VALIDATED" ]; then
   exit 1
 fi
 
-echo "$VALIDATED" >> "$GSTACK_HOME/projects/$SLUG/question-log.jsonl"
+LOG_FILE="$GSTACK_HOME/projects/$SLUG/question-log.jsonl"
+
+# Cathedral T5: composite-source dedup. If this exact (source, tool_use_id)
+# was already logged within the last 100 lines, skip — protects against
+# hook + agent both writing the same fire (D3 plan-tune cathedral decision).
+# Lookup is bounded so the bin stays cheap on hot paths.
+DEDUP_SKIP=""
+if [ -f "$LOG_FILE" ]; then
+  DEDUP_SKIP=$(VALIDATED_JSON="$VALIDATED" LOG_FILE_PATH="$LOG_FILE" bun -e '
+    const fs = require("fs");
+    const j = JSON.parse(process.env.VALIDATED_JSON);
+    if (!j.tool_use_id) { console.log(""); process.exit(0); }
+    const want = j.source + ":" + j.tool_use_id;
+    const lines = fs.readFileSync(process.env.LOG_FILE_PATH, "utf-8").trim().split("\n").slice(-100);
+    for (const ln of lines) {
+      try {
+        const p = JSON.parse(ln);
+        if (p.source && p.tool_use_id && (p.source + ":" + p.tool_use_id) === want) {
+          console.log("dup");
+          process.exit(0);
+        }
+      } catch {}
+    }
+    console.log("");
+  ' 2>/dev/null)
+fi
+
+if [ "$DEDUP_SKIP" = "dup" ]; then
+  echo "DEDUP: skipped (source=$(echo "$VALIDATED" | bun -e 'const j=JSON.parse(await Bun.stdin.text()); console.log(j.source);'), tool_use_id duplicate)"
+  exit 0
+fi
+
+echo "$VALIDATED" >> "$LOG_FILE"
+
+# Cathedral T5: fire-and-forget --derive so inferred dimensions stay current
+# without per-event latency (D17). Sub-second op; output suppressed; never
+# blocks the hook caller. Skipped via GSTACK_QUESTION_LOG_NO_DERIVE=1 for
+# tests that don't want the side effect.
+if [ -z "${GSTACK_QUESTION_LOG_NO_DERIVE:-}" ]; then
+  (
+    nohup "$SCRIPT_DIR/gstack-developer-profile" --derive >/dev/null 2>&1 &
+  ) >/dev/null 2>&1
+fi
 
 # NOTE: question-log.jsonl is deliberately NOT enqueued for gbrain-sync.
 # Per Codex v2 review, audit/derivation data stays local alongside the

bin/gstack-question-preference

@@ -23,7 +23,8 @@ set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
-GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
+# GSTACK_STATE_ROOT takes precedence over GSTACK_HOME (test isolation per D16).
+GSTACK_HOME="${GSTACK_STATE_ROOT:-${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"

bin/gstack-settings-hook

@@ -1,21 +1,44 @@
 #!/usr/bin/env bash
-# gstack-settings-hook — add/remove SessionStart hooks in Claude Code settings.json
+# gstack-settings-hook — manage Claude Code hooks in ~/.claude/settings.json
 #
-# Usage:
-#   gstack-settings-hook add <hook-command>     # add SessionStart hook
-#   gstack-settings-hook remove <hook-command>  # remove SessionStart hook
+# Two shapes:
+#
+#   1. Legacy (SessionStart only — used by setup --team and gstack-uninstall):
+#        gstack-settings-hook add <cmd>            # adds SessionStart hook
+#        gstack-settings-hook remove <cmd>         # removes matching SessionStart hook
+#
+#   2. Schema-aware (plan-tune cathedral T3 — supports PreToolUse + PostToolUse):
+#        gstack-settings-hook add-event --event <SessionStart|PreToolUse|PostToolUse> \
+#          --command <cmd> --source <tag> [--matcher <regex>] [--timeout <s>]
+#        gstack-settings-hook remove-source --source <tag>
+#        gstack-settings-hook diff-event   --event ... --command ... --source ... [--matcher ...]
+#        gstack-settings-hook rollback     # restore latest backup
+#        gstack-settings-hook list-sources # show all gstack-tagged hook entries
+#
+# Every add-event/remove-source writes a backup to ~/.claude/settings.json.bak.<ts>
+# before mutating (Codex correction — silent settings.json mutation is wrong).
+#
+# Dedup: legacy `add`/`remove` dedupe by the historical `gstack-session-update`
+# substring. Schema-aware `add-event` dedupes by (event, matcher, _gstack_source) so
+# multiple gstack registrations (plan-tune, ...) don't collide.
 #
-# 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
+if [ -z "$ACTION" ]; then
+  cat <<EOF >&2
+Usage:
+  gstack-settings-hook add <hook-command>             # legacy SessionStart add
+  gstack-settings-hook remove <hook-command>          # legacy SessionStart remove
+  gstack-settings-hook add-event --event <name> --command <cmd> --source <tag> [--matcher <re>] [--timeout <s>]
+  gstack-settings-hook remove-source --source <tag>
+  gstack-settings-hook diff-event --event <name> --command <cmd> --source <tag> [--matcher <re>] [--timeout <s>]
+  gstack-settings-hook rollback
+  gstack-settings-hook list-sources
+EOF
   exit 1
 fi
 
@@ -24,59 +47,239 @@ if ! command -v bun >/dev/null 2>&1; then
   exit 1
 fi
 
+backup_settings() {
+  if [ -f "$SETTINGS_FILE" ]; then
+    local ts
+    ts=$(date +%Y%m%d-%H%M%S)
+    cp "$SETTINGS_FILE" "$SETTINGS_FILE.bak.$ts"
+    echo "$SETTINGS_FILE.bak.$ts" > "$SETTINGS_FILE.bak-latest"
+  fi
+}
+
+# --- legacy SessionStart add/remove (backwards compat) -----------------
+
 case "$ACTION" in
   add)
-    GSTACK_SETTINGS_PATH="$SETTINGS_FILE" GSTACK_HOOK_CMD="$HOOK_CMD" bun -e "
-      const fs = require('fs');
+    HOOK_CMD="${2:-}"
+    if [ -z "$HOOK_CMD" ]; then
+      echo "Usage: gstack-settings-hook add <hook-command>" >&2
+      exit 1
+    fi
+    backup_settings
+    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 {}
-
+      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'))
+        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 }]
+          hooks: [{ type: "command", command: hookCmd }]
         });
       }
-
-      const tmp = settingsPath + '.tmp';
-      fs.writeFileSync(tmp, JSON.stringify(settings, null, 2) + '\n');
+      const tmp = settingsPath + ".tmp";
+      fs.writeFileSync(tmp, JSON.stringify(settings, null, 2) + "\n");
       fs.renameSync(tmp, settingsPath);
-    " 2>/dev/null
+    ' 2>/dev/null
     ;;
+
   remove)
+    HOOK_CMD="${2:-}"
+    if [ -z "$HOOK_CMD" ]; then
+      echo "Usage: gstack-settings-hook remove <hook-command>" >&2
+      exit 1
+    fi
     [ -f "$SETTINGS_FILE" ] || exit 1
-    GSTACK_SETTINGS_PATH="$SETTINGS_FILE" bun -e "
-      const fs = require('fs');
+    backup_settings
+    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); }
-
+      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')))
+          !(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');
+      const tmp = settingsPath + ".tmp";
+      fs.writeFileSync(tmp, JSON.stringify(settings, null, 2) + "\n");
       fs.renameSync(tmp, settingsPath);
-    " 2>/dev/null
+    ' 2>/dev/null
     ;;
+
+  add-event|diff-event)
+    EVENT=""
+    COMMAND=""
+    SOURCE=""
+    MATCHER=""
+    TIMEOUT=""
+    shift
+    while [ $# -gt 0 ]; do
+      case "$1" in
+        --event)   EVENT="$2"; shift 2 ;;
+        --command) COMMAND="$2"; shift 2 ;;
+        --source)  SOURCE="$2"; shift 2 ;;
+        --matcher) MATCHER="$2"; shift 2 ;;
+        --timeout) TIMEOUT="$2"; shift 2 ;;
+        *) echo "unknown flag: $1" >&2; exit 1 ;;
+      esac
+    done
+    if [ -z "$EVENT" ] || [ -z "$COMMAND" ] || [ -z "$SOURCE" ]; then
+      echo "add-event/diff-event require --event, --command, --source" >&2
+      exit 1
+    fi
+    case "$EVENT" in
+      SessionStart|PreToolUse|PostToolUse|UserPromptSubmit|Stop|Notification) ;;
+      *) echo "invalid --event '$EVENT'; must be one of SessionStart|PreToolUse|PostToolUse|UserPromptSubmit|Stop|Notification" >&2; exit 1 ;;
+    esac
+    if [ "$ACTION" = "add-event" ]; then
+      backup_settings
+    fi
+    DIFF_ONLY=""
+    if [ "$ACTION" = "diff-event" ]; then DIFF_ONLY=1; fi
+    GSTACK_SETTINGS_PATH="$SETTINGS_FILE" \
+    GSTACK_EVENT="$EVENT" \
+    GSTACK_COMMAND="$COMMAND" \
+    GSTACK_SOURCE="$SOURCE" \
+    GSTACK_MATCHER="$MATCHER" \
+    GSTACK_TIMEOUT="$TIMEOUT" \
+    GSTACK_DIFF_ONLY="$DIFF_ONLY" \
+    bun -e '
+      const fs = require("fs");
+      const settingsPath = process.env.GSTACK_SETTINGS_PATH;
+      const event = process.env.GSTACK_EVENT;
+      const cmd = process.env.GSTACK_COMMAND;
+      const source = process.env.GSTACK_SOURCE;
+      const matcher = process.env.GSTACK_MATCHER || "";
+      const timeoutRaw = process.env.GSTACK_TIMEOUT || "";
+      const diffOnly = process.env.GSTACK_DIFF_ONLY === "1";
+
+      let settings = {};
+      try { settings = JSON.parse(fs.readFileSync(settingsPath, "utf8")); } catch {}
+
+      const before = JSON.stringify(settings, null, 2);
+
+      if (!settings.hooks) settings.hooks = {};
+      if (!settings.hooks[event]) settings.hooks[event] = [];
+
+      const matchesEntry = (entry) => {
+        const sameMatcher = (entry.matcher || "") === matcher;
+        const sameSource = entry._gstack_source === source;
+        return sameMatcher && sameSource;
+      };
+
+      let existing = settings.hooks[event].find(matchesEntry);
+      const hookEntry = { type: "command", command: cmd };
+      if (timeoutRaw) {
+        const n = Number(timeoutRaw);
+        if (Number.isFinite(n) && n > 0) hookEntry.timeout = n;
+      }
+
+      if (existing) {
+        existing.hooks = [hookEntry];
+      } else {
+        const newEntry = { _gstack_source: source, hooks: [hookEntry] };
+        if (matcher) newEntry.matcher = matcher;
+        settings.hooks[event].push(newEntry);
+      }
+
+      const after = JSON.stringify(settings, null, 2);
+
+      if (diffOnly) {
+        console.log("--- BEFORE");
+        console.log(before);
+        console.log("--- AFTER");
+        console.log(after);
+        process.exit(0);
+      }
+
+      const tmp = settingsPath + ".tmp";
+      fs.writeFileSync(tmp, after + "\n");
+      fs.renameSync(tmp, settingsPath);
+      console.log("OK: " + event + " hook registered (source: " + source + ")");
+    '
+    ;;
+
+  remove-source)
+    SOURCE=""
+    shift
+    while [ $# -gt 0 ]; do
+      case "$1" in
+        --source) SOURCE="$2"; shift 2 ;;
+        *) echo "unknown flag: $1" >&2; exit 1 ;;
+      esac
+    done
+    if [ -z "$SOURCE" ]; then
+      echo "remove-source requires --source <tag>" >&2
+      exit 1
+    fi
+    [ -f "$SETTINGS_FILE" ] || exit 0
+    backup_settings
+    GSTACK_SETTINGS_PATH="$SETTINGS_FILE" GSTACK_SOURCE="$SOURCE" bun -e '
+      const fs = require("fs");
+      const settingsPath = process.env.GSTACK_SETTINGS_PATH;
+      const source = process.env.GSTACK_SOURCE;
+      let settings = {};
+      try { settings = JSON.parse(fs.readFileSync(settingsPath, "utf8")); } catch { process.exit(0); }
+      if (!settings.hooks) { process.exit(0); }
+      let removed = 0;
+      for (const event of Object.keys(settings.hooks)) {
+        const before = settings.hooks[event].length;
+        settings.hooks[event] = settings.hooks[event].filter(entry => entry._gstack_source !== source);
+        removed += before - settings.hooks[event].length;
+        if (settings.hooks[event].length === 0) delete settings.hooks[event];
+      }
+      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);
+      console.log("OK: removed " + removed + " hook entry/entries tagged source=" + source);
+    '
+    ;;
+
+  rollback)
+    if [ ! -f "$SETTINGS_FILE.bak-latest" ]; then
+      echo "rollback: no backup pointer at $SETTINGS_FILE.bak-latest" >&2
+      exit 1
+    fi
+    LATEST=$(cat "$SETTINGS_FILE.bak-latest")
+    if [ ! -f "$LATEST" ]; then
+      echo "rollback: pointer references missing backup $LATEST" >&2
+      exit 1
+    fi
+    cp "$LATEST" "$SETTINGS_FILE"
+    echo "OK: restored $SETTINGS_FILE from $LATEST"
+    ;;
+
+  list-sources)
+    [ -f "$SETTINGS_FILE" ] || { echo "(no settings file)"; exit 0; }
+    GSTACK_SETTINGS_PATH="$SETTINGS_FILE" bun -e '
+      const fs = require("fs");
+      let settings = {};
+      try { settings = JSON.parse(fs.readFileSync(process.env.GSTACK_SETTINGS_PATH, "utf8")); } catch { process.exit(0); }
+      const hooks = settings.hooks || {};
+      let any = false;
+      for (const event of Object.keys(hooks)) {
+        for (const entry of hooks[event]) {
+          if (entry._gstack_source) {
+            any = true;
+            console.log(event + "\t" + entry._gstack_source + "\t" + (entry.matcher || "(no matcher)"));
+          }
+        }
+      }
+      if (!any) console.log("(no gstack-tagged hooks)");
+    '
+    ;;
+
   *)
-    echo "Unknown action: $ACTION (expected add or remove)" >&2
+    echo "Unknown action: $ACTION" >&2
     exit 1
     ;;
 esac

bin/gstack-uninstall

@@ -232,6 +232,10 @@ 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
+  # Cathedral T8 cleanup: also remove plan-tune PreToolUse + PostToolUse hooks.
+  if "$SETTINGS_HOOK" remove-source --source plan-tune-cathedral 2>/dev/null | grep -q "removed [1-9]"; then
+    REMOVED+=("plan-tune cathedral hooks")
+  fi
 fi
 
 # ─── Remove global state ────────────────────────────────────