gstack/bin/gstack-settings-hook

#!/usr/bin/env bash
# gstack-settings-hook — manage Claude Code hooks in ~/.claude/settings.json
#
# Three shapes:
#
#   1. Legacy (SessionStart only — kept so old installs still clean up):
#        gstack-settings-hook add <cmd>            # adds SessionStart hook
#        gstack-settings-hook remove <cmd>         # removes gstack-session-update items
#                                                  # (the <cmd> arg is accepted for
#                                                  # interface compat; matching is by
#                                                  # the gstack-session-update basename)
#
#   2. Schema-aware (plan-tune cathedral T3):
#        gstack-settings-hook add-event --event <name — see the validator in add-event> \
#          --command <cmd> --source <tag> [--matcher <regex>] [--timeout <s>]
#        gstack-settings-hook ensure-event --event ... --command ... --source ... [--matcher ...] [--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 (single-step undo)
#        gstack-settings-hook list-sources # show all gstack-tagged hook entries
#
#   3. Self-heal (phantom-hooks fix):
#        gstack-settings-hook prune-stale                     # prune dead gstack hook items
#        gstack-settings-hook prune-stale --repoint <root>    # re-point gstack items at <root>, prune still-dead
#        gstack-settings-hook prune-stale --all               # remove ALL gstack hook items (uninstall sweep)
#
# ensure-event is the update-in-place verb: same flags as add-event, but keyed
# on (event, source) — any entry carrying our source tag for the event is THE
# registration to compare/update, so a matcher change re-points in place
# instead of pushing a second entry, and duplicate same-source twins from the
# old matcher-keyed dedup collapse to one (reported on stderr). Identical
# payload → no write, no backup ("unchanged"); a re-run of ./setup stays a
# true no-op. This heals a stale absolute hook path (e.g. a deleted dev
# worktree) baked into settings.json by an earlier setup.
#
# Ownership model (KNOWN_HOOKS identity table): a hook ITEM is gstack-owned iff
# its command basename + relpath suffix + event (+ matcher where the table row
# defines one) match a table row. Entry-level `_gstack_source` tags are
# best-effort metadata — Claude Code strips unknown keys when it rewrites
# settings.json, so identity is intrinsic (the table), never tag-only. A tag
# NEVER claims foreign items: in a tagged multi-item entry, unrecognized items
# are always preserved; only a tagged SINGLE-item entry with no table match is
# treated as an owned legacy stray.
#
# Mutation safety:
#   - every mutation runs under a mkdir lock (<settings>.lock/) with an owner
#     token; release is ownership-checked; stale locks (>30s) are taken over
#     via atomic rename. On lock give-up the mutation is SKIPPED with a warning
#     (the next setup retries — the system is convergent).
#   - parse failure fails CLOSED: a corrupt settings.json is never overwritten
#     (only ENOENT starts fresh). Exit 3.
#   - backup-on-change: a backup (unique name, .bak-latest pointer) is written
#     only when the file content actually changes. No-op mutations are silent
#     on disk. `rollback` is a single-step undo of the last real mutation.
#   - writes are atomic: unique tmp file + rename (a fixed tmp name would let
#     two concurrent writers rename a half-written file into place).
set -euo pipefail

ACTION="${1:-}"
SETTINGS_FILE="${GSTACK_SETTINGS_FILE:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}/settings.json}"

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 ensure-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 prune-stale [--repoint <root>] [--all]
  gstack-settings-hook rollback
  gstack-settings-hook list-sources
EOF
  exit 1
fi

if ! command -v bun >/dev/null 2>&1; then
  echo "Error: bun is required but not installed." >&2
  exit 1
fi

# ─── Shared JS prelude ────────────────────────────────────────────────
# Single source of truth for the KNOWN_HOOKS identity table and the
# ownership/liveness/IO helpers, interpolated into EVERY bun -e script as
#   bun -e "$_HOOK_JS_PRELUDE"' <single-quoted body>'
# so the dedupe key and the prune predicate cannot drift. The prelude MUST NOT
# contain single quotes (this assignment is single-quoted).
_HOOK_JS_PRELUDE='
// Umbrella fail-closed guard: bun in -e mode swallows uncaught exceptions
// thrown after a require() call and exits 0 (verified on bun 1.3.13;
// uncaughtException handlers never fire in -e mode either). Every script body
// below runs inside gsMain so a runtime throw becomes a LOUD exit 4 instead
// of a silent success that reports a mutation as clean.
function gsMain(fn) {
  try {
    fn();
  } catch (e) {
    process.stderr.write("gstack-settings-hook: internal error (" + (e && e.message) + ") -- refusing to mutate\n");
    process.exit(4);
  }
}
var KNOWN_HOOKS = {
  "question-log-hook":        { source: "plan-tune-cathedral", event: "PostToolUse",  matcher: "(AskUserQuestion|mcp__.*__AskUserQuestion)", relpath: "hosts/claude/hooks/question-log-hook" },
  "question-preference-hook": { source: "plan-tune-cathedral", event: "PreToolUse",   matcher: "(AskUserQuestion|mcp__.*__AskUserQuestion)", relpath: "hosts/claude/hooks/question-preference-hook" },
  "auq-error-fallback-hook":  { source: "auq-error-fallback",  event: "PostToolUse",  matcher: "(AskUserQuestion|mcp__.*__AskUserQuestion)", relpath: "hosts/claude/hooks/auq-error-fallback-hook" },
  "timeline-stop-hook":       { source: "gstack-timeline-stop", event: "Stop",        matcher: "", relpath: "hosts/claude/hooks/timeline-stop-hook" },
  "gstack-session-update":    { source: "gstack-session-update", event: "SessionStart", matcher: "", relpath: "bin/gstack-session-update" },
  "gstack-verify-gate":       { source: "verify-gate", event: "Stop", matcher: "", relpath: "bin/gstack-verify-gate" }
};
function gsHadBashPrefix(c) { return String(c == null ? "" : c).trim().indexOf("bash ") === 0; }
function gsStripWrap(c) {
  var s = String(c == null ? "" : c).trim();
  if (s.indexOf("bash ") === 0) s = s.slice(5).trim();
  if (s.length >= 2 && s.charAt(0) === "\"" && s.charAt(s.length - 1) === "\"") {
    // Unescape the gsQuoteCmd form so a re-pointed escaped command is still
    // recognized as ours on later passes (identity round-trips).
    s = s.slice(1, -1).replace(/\\([\\"$\x60])/g, "$1");
  }
  // Separator normalization is Windows-only (a rare-but-legal Unix path
  // containing a backslash must not be rewritten and mis-stat-ed).
  if (process.platform === "win32" || /^[A-Za-z]:[\\\/]/.test(s)) {
    s = s.replace(/\\/g, "/");
  }
  return s;
}
function gsBaseOf(c) { var p = gsStripWrap(c); return p.split("/").pop(); }
function gsOwnedRow(cmd, event, matcher) {
  var p = gsStripWrap(cmd);
  var b = p.split("/").pop();
  // hasOwnProperty guard: a foreign hook basename like "toString" or
  // "constructor" must not resolve to an inherited Object.prototype member.
  var row = Object.prototype.hasOwnProperty.call(KNOWN_HOOKS, b) ? KNOWN_HOOKS[b] : null;
  if (!row) return null;
  if (p !== row.relpath && p.slice(-(row.relpath.length + 1)) !== "/" + row.relpath) return null;
  if (row.event !== event) return null;
  if (row.matcher && (matcher || "") !== row.matcher) return null;
  return row;
}
function gsWinPath(p) {
  // Git Bash writes MSYS-form paths (/c/Users/...) into settings.json, but
  // native bun resolves them drive-relative (C:\c\Users\...) -- translate for
  // fs calls only; stored commands keep the form the firing shell expects.
  if (process.platform === "win32" && /^\/[A-Za-z]\//.test(p)) {
    return p.charAt(1) + ":" + p.slice(2);
  }
  return p;
}
function gsIsAlive(cmd) {
  var fs = require("fs");
  var p = gsWinPath(gsStripWrap(cmd));
  if (!p) return false;
  try {
    if (process.platform === "win32") return fs.existsSync(p);
    var st = fs.statSync(p);
    if (!st.isFile()) return false;
    fs.accessSync(p, fs.constants.X_OK);
    return true;
  } catch (e) {
    // Only provable absence counts as dead. EACCES/EIO/unmounted-volume
    // errors are transient unreachability -- pruning on those would be a
    // one-way ratchet, so conservatively treat the item as alive.
    var code = e && e.code;
    return !(code === "ENOENT" || code === "ENOTDIR");
  }
}
function gsQuoteCmd(target, hadBash) {
  // Shell-metacharacter hardening: the command string is executed by a shell
  // when Claude Code fires the hook, so a path containing $, backtick (x60 --
  // written as an escape so the prelude itself stays backtick-free), or a
  // quote must be neutralized, not just space-wrapped.
  var needsQuote = /[\s$\x60"\\]/.test(target);
  var quoted = needsQuote
    ? "\"" + target.replace(/[\\"$\x60]/g, function (ch) { return "\\" + ch; }) + "\""
    : target;
  return (hadBash ? "bash " : "") + quoted;
}
function gsRotateBackups(settingsPath, keep) {
  // Backup files are change-gated but unbounded across months of setups --
  // keep the most recent N so ~/.claude does not accumulate forever.
  var fs = require("fs");
  var path = require("path");
  try {
    var dir = path.dirname(settingsPath);
    var base = path.basename(settingsPath) + ".bak.";
    var baks = fs.readdirSync(dir)
      .filter(function (f) { return f.indexOf(base) === 0; })
      .map(function (f) {
        var full = path.join(dir, f);
        var m = 0;
        try { m = fs.statSync(full).mtimeMs; } catch (e3) {}
        return { full: full, m: m };
      })
      .sort(function (a, b) { return a.m - b.m; });
    for (var i = 0; i < baks.length - keep; i++) {
      try { fs.unlinkSync(baks[i].full); } catch (e2) {}
    }
  } catch (e) {}
}
function gsLoadSettings(path) {
  var fs = require("fs");
  var raw = null;
  try { raw = fs.readFileSync(path, "utf8"); }
  catch (e) {
    if (e && e.code === "ENOENT") return { settings: {}, existed: false };
    process.stderr.write("gstack-settings-hook: cannot read " + path + ": " + e.message + " -- refusing to mutate\n");
    process.exit(3);
  }
  try { return { settings: JSON.parse(raw), existed: true }; }
  catch (e) {
    process.stderr.write("gstack-settings-hook: " + path + " is not valid JSON (" + e.message + ") -- refusing to mutate; fix or restore it (.bak files / rollback)\n");
    process.exit(3);
  }
}
function gsWriteIfChanged(path, beforeText, settings, existed) {
  var fs = require("fs");
  var afterText = JSON.stringify(settings, null, 2);
  if (afterText === beforeText) return false;
  // Preserve the live file mode across the tmp+rename (settings.json can
  // carry API keys in its env block -- a user-tightened 0600 must never be
  // silently broadened to the default 0644). Fresh files start 0600.
  var mode = 0o600;
  if (existed) {
    try { mode = fs.statSync(path).mode & 0o777; } catch (e) {}
    fs.copyFileSync(path, process.env.GSTACK_BACKUP_PATH);
    fs.writeFileSync(process.env.GSTACK_BAK_LATEST, process.env.GSTACK_BACKUP_PATH + "\n");
    gsRotateBackups(path, 10);
  }
  var tmp = process.env.GSTACK_TMP_PATH;
  fs.writeFileSync(tmp, afterText + "\n");
  try { fs.chmodSync(tmp, mode); } catch (e) {}
  fs.renameSync(tmp, path);
  return true;
}
'

# ─── Mutation lock ────────────────────────────────────────────────────
# Accepted tradeoffs (adversarial-reviewed): (1) the lock serializes gstack
# writers only -- Claude Code rewrites settings.json without honoring it, so a
# lost update against a live session remains possible (convergent: the next
# heal repairs); (2) stale takeover is mtime-based -- a holder legitimately
# slower than the stale window can be stolen from, and a fresh crash stalls
# callers for the give-up window. PID-aware takeover was considered and
# deferred (owner file already carries $$ if it becomes worth it).
_LOCK_DIR="$SETTINGS_FILE.lock"
_LOCK_TOKEN=""

_release_lock() {
  if [ -n "$_LOCK_TOKEN" ] && [ -d "$_LOCK_DIR" ]; then
    # Ownership-checked: never remove a lock another process re-acquired
    # after a stale takeover.
    _OWNER_CONTENT="$(cat "$_LOCK_DIR/owner" 2>/dev/null || true)"
    if [ "$_OWNER_CONTENT" = "$_LOCK_TOKEN" ] || [ -z "$_OWNER_CONTENT" ]; then
      rm -rf "$_LOCK_DIR" 2>/dev/null || true
    fi
  fi
  _LOCK_TOKEN=""
}

_acquire_lock() {
  # GSTACK_SETTINGS_LOCK_TIMEOUT_MS: test-only override for the give-up
  # (a contention test should not stall the suite for 10 real seconds).
  local waited_ms=0 token stale mtime now
  local give_up_ms="${GSTACK_SETTINGS_LOCK_TIMEOUT_MS:-10000}"
  local stale_after_s=30   # lock older than this belongs to a crashed holder
  local poll_ms=50         # retry cadence; sleep below derives from this
  token="$$-$RANDOM$RANDOM"
  while :; do
    if mkdir "$_LOCK_DIR" 2>/dev/null; then
      printf '%s\n' "$token" > "$_LOCK_DIR/owner" 2>/dev/null || true
      _LOCK_TOKEN="$token"
      trap _release_lock EXIT
      trap 'exit 129' INT
      trap 'exit 143' TERM
      return 0
    fi
    # mkdir failed but no lock dir exists: NOT contention (unwritable parent,
    # read-only fs, missing directory) -- waiting cannot help, so give up
    # loudly now instead of spinning out the full timeout. (Tiny race: a
    # contender could acquire+release between our mkdir and this check; that
    # transient reads as an environment failure and the next run converges.)
    if [ ! -e "$_LOCK_DIR" ]; then
      echo "gstack-settings-hook: cannot create lock $_LOCK_DIR (unwritable parent?) -- skipping this mutation, exit 5" >&2
      return 1
    fi
    # Stale takeover: atomic rename means exactly one contender wins; the
    # loser loops and re-contends against the winner's fresh mkdir.
    # GNU stat (-c %Y) first: on Linux, BSD-style `stat -f %m` prints a
    # multi-line FILESYSTEM block to stdout before failing, and the || chain
    # would capture that garbage alongside the real epoch. BSD stat rejects
    # -c with no stdout, so macOS falls through cleanly. The numeric guard
    # below makes any residual garbage inert (no takeover, normal give-up)
    # instead of an arithmetic abort under set -e.
    mtime=$(stat -c %Y "$_LOCK_DIR" 2>/dev/null || stat -f %m "$_LOCK_DIR" 2>/dev/null || echo "")
    case "$mtime" in *[!0-9]*) mtime="" ;; esac
    now=$(date +%s)
    if [ -n "$mtime" ] && [ $(( now - mtime )) -gt "$stale_after_s" ]; then
      stale="$_LOCK_DIR.stale.$$-$RANDOM"
      if mv "$_LOCK_DIR" "$stale" 2>/dev/null; then rm -rf "$stale" 2>/dev/null || true; fi
      continue
    fi
    if [ "$waited_ms" -ge "$give_up_ms" ]; then
      echo "gstack-settings-hook: could not acquire lock $_LOCK_DIR -- skipping this mutation, exit 5 (the next setup retries it)" >&2
      return 1
    fi
    sleep "$(printf '0.%03d' "$poll_ms")"
    waited_ms=$(( waited_ms + poll_ms ))
  done
}

# Per-invocation unique backup + tmp paths, exported for gsWriteIfChanged.
_mutation_env() {
  GSTACK_BACKUP_PATH="$SETTINGS_FILE.bak.$(date +%Y%m%d-%H%M%S).$$.$RANDOM"
  GSTACK_BAK_LATEST="$SETTINGS_FILE.bak-latest"
  GSTACK_TMP_PATH="$SETTINGS_FILE.tmp.$$.$RANDOM"
  export GSTACK_BACKUP_PATH GSTACK_BAK_LATEST GSTACK_TMP_PATH
}

case "$ACTION" in
  # --- legacy SessionStart add/remove (backwards compat) -----------------
  add)
    HOOK_CMD="${2:-}"
    if [ -z "$HOOK_CMD" ]; then
      echo "Usage: gstack-settings-hook add <hook-command>" >&2
      exit 1
    fi
    _acquire_lock || exit 5
    _mutation_env
    GSTACK_SETTINGS_PATH="$SETTINGS_FILE" GSTACK_HOOK_CMD="$HOOK_CMD" bun -e "$_HOOK_JS_PRELUDE"'gsMain(function () {
      const settingsPath = process.env.GSTACK_SETTINGS_PATH;
      const hookCmd = process.env.GSTACK_HOOK_CMD;
      const loaded = gsLoadSettings(settingsPath);
      const settings = loaded.settings;
      const before = JSON.stringify(settings, null, 2);
      if (!settings.hooks) settings.hooks = {};
      if (!settings.hooks.SessionStart) settings.hooks.SessionStart = [];
      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 }]
        });
      }
      gsWriteIfChanged(settingsPath, before, settings, loaded.existed);
    });
    '
    ;;

  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
    _acquire_lock || exit 5
    _mutation_env
    GSTACK_SETTINGS_PATH="$SETTINGS_FILE" bun -e "$_HOOK_JS_PRELUDE"'gsMain(function () {
      const settingsPath = process.env.GSTACK_SETTINGS_PATH;
      const loaded = gsLoadSettings(settingsPath);
      const settings = loaded.settings;
      const before = JSON.stringify(settings, null, 2);
      if (settings.hooks && settings.hooks.SessionStart) {
        // Item-aware: remove only matching hook items; foreign items in the
        // same entry survive; an entry is dropped ONLY when this pass emptied
        // it. Malformed/foreign entries (hooks absent, non-array, or already
        // empty) are preserved verbatim -- they are not ours to judge.
        settings.hooks.SessionStart = settings.hooks.SessionStart
          .filter(entry => {
            if (!Array.isArray(entry.hooks)) return true;
            const beforeLen = entry.hooks.length;
            entry.hooks = entry.hooks.filter(h =>
              !(h && h.command && h.command.includes("gstack-session-update"))
            );
            if (entry.hooks.length === 0 && beforeLen > 0) return false;
            return true;
          });
        if (settings.hooks.SessionStart.length === 0) delete settings.hooks.SessionStart;
        if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
      }
      gsWriteIfChanged(settingsPath, before, settings, loaded.existed);
    });
    '
    ;;

  add-event|diff-event|ensure-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/ensure-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
    DIFF_ONLY=""
    ENSURE=""
    if [ "$ACTION" = "diff-event" ]; then
      DIFF_ONLY=1
    else
      [ "$ACTION" = "ensure-event" ] && ENSURE=1
      _acquire_lock || exit 5
    fi
    _mutation_env
    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" \
    GSTACK_ENSURE="$ENSURE" \
    bun -e "$_HOOK_JS_PRELUDE"'gsMain(function () {
      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";
      const ensure = process.env.GSTACK_ENSURE === "1";

      const loaded = gsLoadSettings(settingsPath);
      const settings = loaded.settings;
      const before = JSON.stringify(settings, null, 2);

      if (!settings.hooks) settings.hooks = {};
      if (!settings.hooks[event]) settings.hooks[event] = [];

      // add-event is the single quoting authority: normalize the command
      // through the same round-trip the healer uses so metachar paths are
      // registered in the escaped-quoted form from the start (a caller-side
      // quoting step would drift per call site).
      const cmdNorm = gsQuoteCmd(gsStripWrap(cmd), gsHadBashPrefix(cmd));
      const hookEntry = { type: "command", command: cmdNorm };
      if (timeoutRaw) {
        const n = Number(timeoutRaw);
        if (Number.isFinite(n) && n > 0) hookEntry.timeout = n;
      }

      // Identity is item-level and two-layer:
      //  - a same-event entry carrying OUR source tag is ours even under a
      //    DIFFERENT matcher (a matcher change must re-point in place, never
      //    push a second registration -- the old matcher-keyed dedupe
      //    duplicated the entry on every matcher change), and
      //  - a same-matcher entry containing our exact command or a table-owned
      //    item with our basename is OUR registration under a stale path
      //    (Claude Code strips _gstack_source on its own rewrites, so
      //    tag-based dedupe degrades).
      // A tag never claims foreign items: in a multi-item entry only the
      // identified item is touched; entries where no item can be identified
      // as ours are left alone entirely.
      const ourItemIdx = (entry) => {
        if (!Array.isArray(entry.hooks)) return -1;
        let idx = entry.hooks.findIndex(h => h && h.command === cmdNorm);
        if (idx < 0) {
          idx = entry.hooks.findIndex(h => {
            if (!h || !h.command) return false;
            const row = gsOwnedRow(h.command, event, entry.matcher || "");
            return !!row && gsBaseOf(h.command) === gsBaseOf(cmdNorm);
          });
        }
        if (idx < 0 && entry._gstack_source === source && entry.hooks.length === 1 && entry.hooks[0] && entry.hooks[0].command) idx = 0;
        return idx;
      };
      const cands = [];
      for (const entry of settings.hooks[event]) {
        const idx = ourItemIdx(entry);
        if (idx < 0) continue;
        if (entry._gstack_source === source || (entry.matcher || "") === matcher) cands.push({ entry: entry, idx: idx });
      }

      let placed = false;
      let collapsed = 0;
      if (cands.length > 0) {
        const primary = cands[0];
        if ((primary.entry.matcher || "") === matcher) {
          primary.entry.hooks[primary.idx] = hookEntry;
          // Mixed-version ratchet guard: tag ONLY single-item entries (the
          // item we just placed). Old gstack versions in sibling worktrees do
          // entry-level ownership (remove-source deletes the whole tagged
          // entry; add-event clobbers entry.hooks wholesale) -- a tag on a
          // mixed entry hands them permission to destroy the user items in it.
          if (primary.entry.hooks.length === 1) primary.entry._gstack_source = source;
          else delete primary.entry._gstack_source;
          placed = true;
        } else if (primary.entry.hooks.length === 1) {
          // Tagged single-item entry under a stale matcher: the entry is
          // exclusively ours, so re-point payload AND matcher in place.
          primary.entry.hooks = [hookEntry];
          primary.entry._gstack_source = source;
          if (matcher) primary.entry.matcher = matcher;
          else delete primary.entry.matcher;
          placed = true;
        } else {
          // Our item sits in a MIXED entry under a different matcher: the
          // entry-level matcher also governs the foreign siblings, so pull
          // our item out and register separately below.
          primary.entry.hooks.splice(primary.idx, 1);
          delete primary.entry._gstack_source;
        }
        // Duplicate registrations (e.g. same-source twins from the old
        // matcher-keyed dedupe): remove OUR item from every other candidate.
        for (let i = 1; i < cands.length; i++) {
          cands[i].entry.hooks.splice(cands[i].idx, 1);
          delete cands[i].entry._gstack_source;
          collapsed++;
        }
        // Drop only entries WE emptied; started-empty foreign entries are
        // never candidates, so they are preserved verbatim.
        settings.hooks[event] = settings.hooks[event].filter(e =>
          !(Array.isArray(e.hooks) && e.hooks.length === 0 && cands.some(c => c.entry === e)));
      }
      if (!placed) {
        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);
      }

      if (ensure && before === after) {
        // Registered payload already matches the canonical one -- no write,
        // no backup, no churn. Re-running ./setup stays a true no-op.
        console.log("OK: " + event + " hook unchanged (source: " + source + ")");
        process.exit(0);
      }

      gsWriteIfChanged(settingsPath, before, settings, loaded.existed);
      if (collapsed > 0) {
        console.error("collapsed " + collapsed + " duplicate (event, source) hook entr" + (collapsed === 1 ? "y" : "ies") + " for " + event + " (source: " + source + ")");
      }
      if (ensure && cands.length > 0) {
        console.log("OK: " + event + " hook re-pointed (source: " + source + ")");
      } else {
        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
    _acquire_lock || exit 5
    _mutation_env
    GSTACK_SETTINGS_PATH="$SETTINGS_FILE" GSTACK_SOURCE="$SOURCE" bun -e "$_HOOK_JS_PRELUDE"'gsMain(function () {
      const settingsPath = process.env.GSTACK_SETTINGS_PATH;
      const source = process.env.GSTACK_SOURCE;
      const loaded = gsLoadSettings(settingsPath);
      const settings = loaded.settings;
      if (!settings.hooks) { console.log("OK: removed 0 hook entry/entries tagged source=" + source); process.exit(0); }
      const before = JSON.stringify(settings, null, 2);
      let removed = 0;
      for (const event of Object.keys(settings.hooks)) {
        const kept = [];
        for (const entry of settings.hooks[event]) {
          if (entry._gstack_source !== source) { kept.push(entry); continue; }
          if (!Array.isArray(entry.hooks) || entry.hooks.length === 0) { removed++; continue; }
          // Item-aware: remove table-owned items (or the single item of a
          // tagged legacy-stray entry); foreign items in a tagged multi-item
          // entry are preserved and the tag is dropped with the last owned item.
          const single = entry.hooks.length === 1;
          const remain = entry.hooks.filter(h => {
            // Command-less items cannot be ours (gstack only writes
            // type:command items) -- preserve them.
            const owned = (h && h.command)
              ? gsOwnedRow(h.command, event, entry.matcher || "") !== null
              : false;
            // The single-item stray claim requires a command item (gstack
            // never writes command-less items).
            if (owned || (single && h && h.command)) { removed++; return false; }
            return true;
          });
          if (remain.length === 0) continue;
          entry.hooks = remain;
          delete entry._gstack_source;
          kept.push(entry);
        }
        settings.hooks[event] = kept;
        if (settings.hooks[event].length === 0) delete settings.hooks[event];
      }
      if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
      gsWriteIfChanged(settingsPath, before, settings, loaded.existed);
      console.log("OK: removed " + removed + " hook entry/entries tagged source=" + source);
    });
    '
    ;;

  prune-stale)
    REPOINT_ROOT=""
    PRUNE_ALL=""
    shift
    while [ $# -gt 0 ]; do
      case "$1" in
        --repoint) REPOINT_ROOT="$2"; shift 2 ;;
        --all)     PRUNE_ALL=1; shift ;;
        *) echo "unknown flag: $1" >&2; exit 1 ;;
      esac
    done
    if [ -n "$REPOINT_ROOT" ] && [ -n "$PRUNE_ALL" ]; then
      echo "prune-stale: --repoint and --all are mutually exclusive" >&2
      exit 1
    fi
    if [ ! -f "$SETTINGS_FILE" ]; then
      echo "OK: removed 0 gstack hook entries (repointed 0)"
      exit 0
    fi
    # Explicit plan_tune_hooks opt-out: dead plan-tune items are still pruned,
    # but live ones are never re-pointed (re-activation needs consent; removal
    # of live ones is --no-team/uninstall territory).
    GSTACK_PT_OPTOUT=0
    # The opt-out lookup is repoint/heal-only — the --all sweep never
    # re-points, and uninstall must not depend on a sibling gstack-config.
    if [ -z "$PRUNE_ALL" ]; then
      _CFG_BIN="$(cd "$(dirname "$0")" && pwd)/gstack-config"
      if [ -x "$_CFG_BIN" ] && "$_CFG_BIN" has plan_tune_hooks 2>/dev/null; then
        _PT_VAL=$("$_CFG_BIN" get plan_tune_hooks 2>/dev/null || true)
        _PT_VAL=$(printf '%s' "$_PT_VAL" | tr '[:upper:]' '[:lower:]' | tr -d '[:space:]')
        case "$_PT_VAL" in
          n|no|false|skip|off|0) GSTACK_PT_OPTOUT=1 ;;
        esac
      fi
    fi
    _acquire_lock || exit 5
    _mutation_env
    GSTACK_SETTINGS_PATH="$SETTINGS_FILE" \
    GSTACK_REPOINT_ROOT="$REPOINT_ROOT" \
    GSTACK_PRUNE_ALL="$PRUNE_ALL" \
    GSTACK_PT_OPTOUT="$GSTACK_PT_OPTOUT" \
    GSTACK_SWEEP_EXCLUDE_SOURCES="${GSTACK_SWEEP_EXCLUDE_SOURCES:-}" \
    bun -e "$_HOOK_JS_PRELUDE"'gsMain(function () {
      const settingsPath = process.env.GSTACK_SETTINGS_PATH;
      const root = (process.env.GSTACK_REPOINT_ROOT || "").replace(/\/+$/, "");
      const all = process.env.GSTACK_PRUNE_ALL === "1";
      const ptOptout = process.env.GSTACK_PT_OPTOUT === "1";
      const PT_SOURCES = { "plan-tune-cathedral": true, "auq-error-fallback": true };
      // Sources a sweep must leave alone (e.g. `setup --no-team` excludes the
      // user-registered verify-gate hook: turning team mode off must not
      // delete an unrelated opt-in whose binary still exists).
      const sweepExclude = {};
      (process.env.GSTACK_SWEEP_EXCLUDE_SOURCES || "").split(",").forEach(function (sName) {
        if (sName.trim()) sweepExclude[sName.trim()] = true;
      });

      const loaded = gsLoadSettings(settingsPath);
      const settings = loaded.settings;
      const before = JSON.stringify(settings, null, 2);
      let removed = 0;
      let repointed = 0;

      if (settings.hooks) {
        for (const event of Object.keys(settings.hooks)) {
          const rebuilt = [];
          for (const entry of settings.hooks[event]) {
            if (!Array.isArray(entry.hooks)) { rebuilt.push(entry); continue; }
            const matcher = entry.matcher || "";
            const wasSingle = entry.hooks.length === 1;
            const remain = [];
            const seenInEntry = new Set();
            if (entry.hooks.length === 0) {
              // Started-empty entries are foreign data we never touched --
              // preserve them (only a gstack-tagged empty entry is claimable,
              // and only by the --all sweep).
              if (all && entry._gstack_source && !sweepExclude[entry._gstack_source]) { removed++; continue; }
              rebuilt.push(entry);
              continue;
            }
            for (const h of entry.hooks) {
              const cmdRaw = h && h.command;
              const row = cmdRaw ? gsOwnedRow(cmdRaw, event, matcher) : null;
              // A tagged SINGLE-item entry with no table match is an owned
              // legacy stray (command items only -- gstack never writes
              // command-less items); tags never claim items in multi-item entries.
              const stray = !row && !!cmdRaw && !!entry._gstack_source && wasSingle;
              if (!row && !stray) { remain.push(h); continue; }   // foreign: never touched
              if (all) {
                if ((row && sweepExclude[row.source]) || (!row && entry._gstack_source && sweepExclude[entry._gstack_source])) { remain.push(h); continue; }
                removed++; continue;
              }
              if (row && root && !(ptOptout && PT_SOURCES[row.source])) {
                const target = root + "/" + row.relpath;
                if (gsIsAlive(target)) {
                  const newCmd = gsQuoteCmd(target, gsHadBashPrefix(cmdRaw));
                  if (h.command !== newCmd) { h.command = newCmd; repointed++; }
                  // Within-entry twin collapse: two dead copies of the same
                  // hook re-point to the same canonical command -- keeping
                  // both would fire the hook twice per event, forever.
                  if (seenInEntry.has(newCmd)) { removed++; continue; }
                  seenInEntry.add(newCmd);
                  if (wasSingle) entry._gstack_source = row.source;   // tag restore
                  remain.push(h);
                  continue;
                }
              }
              // No re-point target (or plan-tune opt-out): keep live, prune dead.
              if (gsIsAlive(cmdRaw)) remain.push(h); else { removed++; }
            }
            if (remain.length === 0) continue;   // entry emptied → dropped
            entry.hooks = remain;
            // Tag hygiene: a tag must never sit on an entry containing foreign
            // items (old gstack versions in sibling worktrees treat tags as
            // entry-level ownership and would destroy the user items). Drop
            // the tag from any mixed entry; single-item strays keep theirs.
            if (entry._gstack_source && entry.hooks.length > 0
                && !entry.hooks.every(h => h && h.command && gsOwnedRow(h.command, event, matcher))
                && !(entry.hooks.length === 1 && wasSingle)) {
              delete entry._gstack_source;
            }
            rebuilt.push(entry);
          }
          // Collapse exact duplicates among FULLY-owned entries (same matcher,
          // same item commands). Prefer the tagged twin so stripped tags heal.
          const seen = new Map();
          const out = [];
          for (const entry of rebuilt) {
            const items = Array.isArray(entry.hooks) ? entry.hooks : [];
            const fullyOwned = items.length > 0 && items.every(h =>
              h && h.command && gsOwnedRow(h.command, event, entry.matcher || ""));
            if (!fullyOwned) { out.push(entry); continue; }
            const key = JSON.stringify([entry.matcher || ""].concat(items.map(function (h) { return h.command; }).sort()));
            const at = seen.get(key);
            if (at === undefined) { seen.set(key, out.length); out.push(entry); }
            else {
              if (!out[at]._gstack_source && entry._gstack_source) out[at] = entry;
              removed++;
            }
          }
          settings.hooks[event] = out;
          if (out.length === 0) delete settings.hooks[event];
        }
        if (settings.hooks && Object.keys(settings.hooks).length === 0) delete settings.hooks;
      }

      gsWriteIfChanged(settingsPath, before, settings, loaded.existed);
      console.log("OK: removed " + removed + " gstack hook entries (repointed " + repointed + ")");
    });
    '
    ;;

  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")
    LATEST=$(printf '%s' "$LATEST" | tr -d '\n')
    # Defense in depth: only ever restore a sibling settings.json.bak.* file
    # (a corrupted/hostile pointer must not install an arbitrary file as the
    # live settings.json).
    case "$LATEST" in
      "$SETTINGS_FILE".bak.*) ;;
      *)
        echo "rollback: pointer target $LATEST is not a $SETTINGS_FILE.bak.* file -- refusing" >&2
        exit 1
        ;;
    esac
    case "${LATEST#"$SETTINGS_FILE".bak.}" in
      */*)
        echo "rollback: pointer suffix contains a path separator -- refusing" >&2
        exit 1
        ;;
    esac
    if [ ! -f "$LATEST" ]; then
      echo "rollback: pointer references missing backup $LATEST" >&2
      exit 1
    fi
    _acquire_lock || exit 1
    _RB_TMP="$SETTINGS_FILE.tmp.$$.$RANDOM"
    cp "$LATEST" "$_RB_TMP"
    mv "$_RB_TMP" "$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 "$_HOOK_JS_PRELUDE"'gsMain(function () {
      const fs = require("fs");
      let settings = {};
      try { settings = JSON.parse(fs.readFileSync(process.env.GSTACK_SETTINGS_PATH, "utf8")); }
      catch (e) {
        // Read-only surface: report loudly (setup guards read this output and
        // must not mistake corrupt-file for no-hooks) but exit 0.
        process.stderr.write("gstack-settings-hook: settings.json unparseable (" + e.message + ") -- fix or rollback\n");
        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" >&2
    exit 1
    ;;
esac