setup

#!/usr/bin/env bash
# The Last Stack — setup / installer
#
# Registers each skill in skills/ into whatever agent harnesses you have
# installed (Claude Code, Codex, Factory/droid, OpenCode, Antigravity CLI/agy).
# Skills stay in this repo; the harness gets a real directory with a
# symlinked SKILL.md, so a later `git pull` updates every installed skill at
# once. Host-track last-stack post_install runs this with --host auto.
#
# Usage:
#   ./setup                 # auto-detect harnesses, install where present
#   ./setup --host claude   # claude | codex | factory | opencode | grok | agy | auto
#   ./setup --local         # install into ./.claude/skills (this project only)
#   ./setup --uninstall     # remove installed skill links (see bin/last-stack-uninstall)
#
# Re-running is idempotent.
set -e
umask 077

ROOT="$(cd "$(dirname "$0")" && pwd -P)"

resolve_source_root() {
  local candidate
  for candidate in \
    "${LAST_STACK_ROOT:-}" \
    "${HOST_TRACK_INSTALL_ROOT:+$HOST_TRACK_INSTALL_ROOT/current}" \
    "$HOME/.local/state/last-stack/artifacts/current" \
    "$HOME/.last-stack/.artifacts/current" \
    "$ROOT" \
    "$HOME/.last-stack"
  do
    [ -n "$candidate" ] || continue
    if [ -f "$candidate/VERSION" ] && [ -d "$candidate/skills" ]; then
      cd "$candidate" && pwd -P
      return 0
    fi
  done
  printf '%s\n' "$ROOT"
}

SOURCE_ROOT="$(resolve_source_root)"
ARTIFACT_INSTALL=0
artifact_roots=()
[ -n "${HOST_TRACK_INSTALL_ROOT:-}" ] && artifact_roots+=("$HOST_TRACK_INSTALL_ROOT")
artifact_roots+=("$HOME/.local/state/last-stack/artifacts" "$HOME/.last-stack/.artifacts")
for artifact_root in "${artifact_roots[@]}"; do
  [ -n "$artifact_root" ] || continue
  artifact_root="$(cd "$artifact_root" 2>/dev/null && pwd -P || printf '%s\n' "$artifact_root")"
  case "$SOURCE_ROOT" in
    "$artifact_root"|"$artifact_root"/*) ARTIFACT_INSTALL=1 ;;
  esac
done
SKILLS_SRC="$SOURCE_ROOT/skills"
HOOKS_SRC="$SOURCE_ROOT/hooks"
SOURCE_TOP_LOADED=0
SOURCE_TOP=""
SOURCE_WORKTREES=""

HOST="auto"
LOCAL_INSTALL=0
while [ $# -gt 0 ]; do
  case "$1" in
    --host) HOST="$2"; shift 2 ;;
    --host=*) HOST="${1#*=}"; shift ;;
    --local) LOCAL_INSTALL=1; shift ;;
    --uninstall) exec "$SOURCE_ROOT/bin/last-stack-uninstall" ;;
    -h|--help) sed -n '2,18p' "$0"; exit 0 ;;
    *) echo "unknown flag: $1" >&2; exit 2 ;;
  esac
done

# ── Windows lacks reliable symlinks without Developer Mode; copy there instead ─
IS_WINDOWS=0
case "$(uname -s)" in MINGW*|MSYS*|CYGWIN*|Windows_NT) IS_WINDOWS=1 ;; esac

_link_or_copy() {
  # $1 = source file, $2 = destination path
  if [ "$IS_WINDOWS" -eq 1 ] || is_transient_last_stack_target "$1"; then
    cp -f "$1" "$2"
  else
    ln -snf "$1" "$2"
  fi
}

is_transient_last_stack_target() {
  local target="$1"
  case "$target" in
    "$HOME/.kanban/worktrees"/*|*/.kanban/worktrees/*) return 0 ;;
    "$HOME/.fkanban/worktrees"/*|*/.fkanban/worktrees/*) return 0 ;;
  esac

  if [ "$SOURCE_TOP_LOADED" -eq 0 ]; then
    SOURCE_TOP="$(git -C "$SOURCE_ROOT" rev-parse --show-toplevel 2>/dev/null || true)"
    if [ -n "$SOURCE_TOP" ]; then
      SOURCE_WORKTREES="$(git -C "$SOURCE_TOP" worktree list --porcelain 2>/dev/null | awk '/^worktree /{print substr($0, 10)}')"
    fi
    SOURCE_TOP_LOADED=1
  fi
  [ -n "$SOURCE_TOP" ] || return 1

  local wt
  while IFS= read -r wt; do
    [ -n "$wt" ] || continue
    [ "$wt" = "$SOURCE_TOP" ] && continue
    case "$target" in
      "$wt"/*) return 0 ;;
    esac
  done <<< "$SOURCE_WORKTREES"

  return 1
}

assert_safe_skill_links() {
  local target_dir="$1"
  local link dest abs_dest
  [ -d "$target_dir" ] || return 0
  find "$target_dir" -type l -print | while IFS= read -r link; do
    dest="$(readlink "$link" 2>/dev/null || true)"
    [ -n "$dest" ] || continue
    case "$dest" in
      /*) abs_dest="$dest" ;;
      *) abs_dest="$(cd "$(dirname "$link")" && cd "$(dirname "$dest")" && pwd -P)/$(basename "$dest")" ;;
    esac
    if is_transient_last_stack_target "$abs_dest"; then
      echo "refusing transient Last Stack skill link: $link -> $abs_dest" >&2
      echo "run setup from or with LAST_STACK_ROOT pointing at the canonical ~/.last-stack checkout" >&2
      exit 1
    fi
  done
}

upsert_pretool_hook() {
  local settings="$1"
  local matcher="$2"
  local command="$3"
  local timeout="$4"
  local tmp
  tmp="$(mktemp)"
  jq \
    --arg matcher "$matcher" \
    --arg command "$command" \
    --argjson timeout "$timeout" '
      .hooks //= {}
      | .hooks.PreToolUse //= []
      | .hooks.PreToolUse =
        (if any(.hooks.PreToolUse[]?; .matcher == $matcher) then
          [.hooks.PreToolUse[] |
            if .matcher == $matcher then
              .hooks = (((.hooks // []) | map(select(.command != $command))) + [{
                type: "command",
                command: $command,
                timeout: $timeout
              }])
            else
              .
            end
          ]
        else
          .hooks.PreToolUse + [{
            matcher: $matcher,
            hooks: [{
              type: "command",
              command: $command,
              timeout: $timeout
            }]
          }]
        end)
    ' "$settings" > "$tmp"
  mv "$tmp" "$settings"
}

remove_pretool_hook_by_script() {
  # Strip every PreToolUse command entry whose command references the given
  # script name, dropping matcher groups left empty.
  local settings="$1"
  local script="$2"
  local tmp
  tmp="$(mktemp)"
  jq \
    --arg script "$script" '
      if (.hooks.PreToolUse // []) == [] then . else
        .hooks.PreToolUse =
          [.hooks.PreToolUse[]
            | .hooks = ((.hooks // []) | map(select((.command // "") | contains($script) | not)))
            | select((.hooks | length) > 0)]
      end
    ' "$settings" > "$tmp"
  mv "$tmp" "$settings"
}

upsert_permission_allow() {
  local settings="$1"
  local rule="$2"
  local tmp
  tmp="$(mktemp)"
  jq \
    --arg rule "$rule" '
      .permissions //= {}
      | .permissions.allow //= []
      | if any(.permissions.allow[]?; . == $rule) then
          .
        else
          .permissions.allow += [$rule]
        end
    ' "$settings" > "$tmp"
  mv "$tmp" "$settings"
}

install_claude_hooks() {
  local hooks_dir="$HOME/.claude/hooks"
  local settings="$HOME/.claude/settings.json"
  mkdir -p "$hooks_dir" "$(dirname "$settings")"

  for hook in unsafe-inline-json.sh no-home-root-scan.sh no-unbounded-workspace-walk.sh; do
    [ -f "$HOOKS_SRC/$hook" ] || continue
    cp -f "$HOOKS_SRC/$hook" "$hooks_dir/$hook"
    chmod 700 "$hooks_dir/$hook"
  done

  if ! command -v jq >/dev/null 2>&1; then
    echo "  claude hooks: installed scripts; skipped settings.json registration (jq not found)" >&2
    return 0
  fi

  if [ ! -s "$settings" ]; then
    printf '{}\n' > "$settings"
  fi

  # read-before-edit.sh is RETIRED and must never be re-registered here. Its
  # deny ended the whole turn, freezing unattended runs mid-task; Tom removed
  # it on 2026-07-28 and a later setup run silently re-armed it from this
  # function on 2026-07-29. De-register so already-armed machines heal on the
  # next run. History: brain papercut-read-before-edit-hook-denied-write-then-edit.
  remove_pretool_hook_by_script "$settings" "read-before-edit.sh"

  upsert_pretool_hook "$settings" "Bash" \
    "$hooks_dir/unsafe-inline-json.sh  # keep parsed JSON stdout clean; block brittle inline parsing and merged stderr" \
    5

  # macOS TCC: a walk of $HOME steps into Desktop/Documents/Downloads/Pictures.
  # Under routinesd the prompt is attributed to `routines` and the command
  # BLOCKS until a human clicks it — the cause of the "find $HOME hung past
  # 15 min" stalls. Escape hatch: '# home-scan-ok: <reason>'.
  upsert_pretool_hook "$settings" "Bash" \
    "$hooks_dir/no-home-root-scan.sh  # macOS TCC: deny home-root walks and Desktop/Documents/Downloads/Pictures reads; they prompt the owner and block the run" \
    5

  # A depth-free find/fd/tree or a Python rglob/os.walk over ~/code/edgevector
  # or ~/.fkanban crosses ~20 checkouts and their cargo target/ trees. It runs
  # for minutes and the timeout reads as a product failure
  # (papercut-agent-zero-llm-cli-bash-python-heredoc-rglob). The deny hands
  # back last-stack-locate-file / -maxdepth. Escape hatch: '# walk-ok: <reason>'.
  upsert_pretool_hook "$settings" "Bash" \
    "$hooks_dir/no-unbounded-workspace-walk.sh  # deny a depth-free walk of a workspace root (find/fd/tree, rglob/os.walk); it runs for minutes and times out" \
    5

  for tool in \
    mcp__brain__brain_get \
    mcp__brain__brain_search \
    mcp__brain__brain_list \
    mcp__brain__brain_ask \
    mcp__brain__brain_put
  do
    upsert_permission_allow "$settings" "$tool"
  done

  echo "  claude hooks: unsafe-inline-json.sh + no-home-root-scan.sh + no-unbounded-workspace-walk.sh (inline parsing guard; home-root/TCC walk guard; workspace walk guard; read-before-edit retired)"
  echo "  claude permissions: brain MCP get/search/list/ask/put"
}

# ── Harness instruction blocks (brain-kanban + ASD-STE100) ────────────────────
# Managed block targets:
#   Claude Code → ~/.claude/CLAUDE.md
#   Codex       → ~/.codex/AGENTS.md
#   Factory     → ~/.factory/AGENTS.md
#   OpenCode    → ~/.config/opencode/AGENTS.md
#   Grok        → ~/.grok/AGENTS.md
#   Antigravity CLI (agy) → ~/.gemini/GEMINI.md and ~/.gemini/config/GEMINI.md
BK_START='<!-- last-stack:brain-kanban:start (managed by last-stack setup; edits inside are overwritten) -->'
BK_END='<!-- last-stack:brain-kanban:end -->'
STE_START='<!-- last-stack:asd-ste100:start (managed by last-stack setup; edits inside are overwritten) -->'
STE_END='<!-- last-stack:asd-ste100:end -->'
HS_START='<!-- last-stack:no-home-root-scan:start (managed by last-stack setup; edits inside are overwritten) -->'
HS_END='<!-- last-stack:no-home-root-scan:end -->'
BA_START='<!-- last-stack:bin-authoring:start (managed by last-stack setup; edits inside are overwritten) -->'
BA_END='<!-- last-stack:bin-authoring:end -->'

strip_managed_md_block() {
  # $1 file  $2 start  $3 end
  local file="$1"
  local start="$2"
  local end="$3"
  [ -f "$file" ] || return 0
  local tmp
  tmp="$(mktemp)"
  awk -v s="$start" -v e="$end" '
    $0 == s { ib = 1; next }
    $0 == e { ib = 0; next }
    !ib { lines[++n] = $0 }
    END {
      while (n > 0 && lines[n] == "") n--
      for (i = 1; i <= n; i++) print lines[i]
    }
  ' "$file" > "$tmp"
  mv "$tmp" "$file"
}

append_managed_md_block() {
  # $1 file  $2 src  $3 start  $4 end
  local file="$1"
  local src="$2"
  local start="$3"
  local end="$4"
  [ -f "$src" ] || return 0
  {
    echo ""
    printf '%s\n' "$start"
    cat "$src"
    printf '%s\n' "$end"
  } >> "$file"
}

upsert_harness_instruction_blocks() {
  # Strip both blocks, then append in a stable order so re-runs are byte-identical.
  local file="$1"
  local label="$2"
  mkdir -p "$(dirname "$file")"
  [ -f "$file" ] || : > "$file"
  strip_managed_md_block "$file" "$BK_START" "$BK_END"
  strip_managed_md_block "$file" "$STE_START" "$STE_END"
  strip_managed_md_block "$file" "$HS_START" "$HS_END"
  strip_managed_md_block "$file" "$BA_START" "$BA_END"
  append_managed_md_block "$file" "$SOURCE_ROOT/instructions/brain-kanban.md" "$BK_START" "$BK_END"
  append_managed_md_block "$file" "$SOURCE_ROOT/instructions/asd-ste100.md" "$STE_START" "$STE_END"
  append_managed_md_block "$file" "$SOURCE_ROOT/instructions/no-home-root-scan.md" "$HS_START" "$HS_END"
  append_managed_md_block "$file" "$SOURCE_ROOT/instructions/bin-authoring.md" "$BA_START" "$BA_END"
  echo "  ${label} instructions: brain-kanban + asd-ste100 + no-home-root-scan + bin-authoring -> $file"
}

ensure_codex_mcp_servers() {
  # brain and kanban are bun shims. GUI-launched MCP hosts (the Codex desktop
  # app) spawn servers with a bare PATH that lacks ~/.bun/bin, so without an
  # explicit env the server exits 127 and the client reports "transport closed".
  local cfg="$HOME/.codex/config.toml"
  local mcp_path="$HOME/.bun/bin:$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
  local added=()
  mkdir -p "$(dirname "$cfg")"
  [ -f "$cfg" ] || : > "$cfg"
  local name cmd
  for name in brain kanban; do
    case "$name" in
      brain)  cmd="$HOME/.bun/bin/brain" ;;
      kanban) cmd="$HOME/.local/bin/kanban" ;;
    esac
    if [ ! -x "$cmd" ]; then
      cmd="$(command -v "$name" 2>/dev/null || true)"
    fi
    if [ -z "$cmd" ]; then
      echo "  codex mcp: $name CLI not found; skipped its MCP registration" >&2
      continue
    fi
    if ! grep -q "^\[mcp_servers\.$name\]" "$cfg"; then
      {
        echo ""
        echo "[mcp_servers.$name]"
        echo "args = [\"mcp\"]"
        echo "command = \"$cmd\""
        echo "startup_timeout_sec = 120"
      } >> "$cfg"
      added+=("$name")
    fi
    if ! grep -q "^\[mcp_servers\.$name\.env\]" "$cfg"; then
      {
        echo ""
        echo "# $name is a bun shim; GUI-spawned MCP servers get a bare PATH (no ~/.bun/bin)"
        echo "# and exit 127 -> 'transport closed' without this."
        echo "[mcp_servers.$name.env]"
        echo "PATH = \"$mcp_path\""
      } >> "$cfg"
      added+=("$name.env")
    fi
  done
  if [ ${#added[@]} -gt 0 ]; then
    echo "  codex mcp: added ${added[*]} to $cfg"
  else
    echo "  codex mcp: brain + kanban already registered"
  fi
}

agy_detected() {
  command -v agy >/dev/null 2>&1 && return 0
  [ -x "$HOME/.local/bin/agy" ] && return 0
  [ -d "$HOME/.gemini/antigravity-cli" ] && return 0
  return 1
}

ensure_agy_mcp_servers() {
  # agy reads ~/.gemini/config/mcp_config.json. An empty file is invalid JSON
  # and blocks later `agy mcp add`. Heal that, then upsert brain + kanban
  # without clobbering other servers. Prefer brain-mcp (Claude-shaped) over
  # `brain mcp` because that is the dedicated stdio entrypoint.
  local cfg="$HOME/.gemini/config/mcp_config.json"
  local mcp_path="$HOME/.bun/bin:$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
  local added=()
  mkdir -p "$(dirname "$cfg")"
  if [ ! -s "$cfg" ]; then
    printf '{}\n' > "$cfg"
  fi
  if ! command -v jq >/dev/null 2>&1; then
    echo "  agy mcp: skipped settings write (jq not found)" >&2
    return 0
  fi
  if ! jq -e . "$cfg" >/dev/null 2>&1; then
    echo "  agy mcp: $cfg is not JSON; skipped" >&2
    return 0
  fi

  local brain_cmd="" brain_args='[]'
  if [ -x "$HOME/.local/bin/brain-mcp" ]; then
    brain_cmd="$HOME/.local/bin/brain-mcp"
  elif command -v brain-mcp >/dev/null 2>&1; then
    brain_cmd="$(command -v brain-mcp)"
  elif [ -x "$HOME/.local/bin/brain" ]; then
    brain_cmd="$HOME/.local/bin/brain"
    brain_args='["mcp"]'
  elif command -v brain >/dev/null 2>&1; then
    brain_cmd="$(command -v brain)"
    brain_args='["mcp"]'
  fi

  local kanban_cmd=""
  if [ -x "$HOME/.local/bin/kanban" ]; then
    kanban_cmd="$HOME/.local/bin/kanban"
  elif command -v kanban >/dev/null 2>&1; then
    kanban_cmd="$(command -v kanban)"
  fi

  local tmp
  tmp="$(mktemp)"
  if [ -n "$brain_cmd" ]; then
    if jq -e '.mcpServers.brain.command? // empty | length > 0' "$cfg" >/dev/null 2>&1; then
      :
    else
      jq --arg cmd "$brain_cmd" --argjson args "$brain_args" --arg path "$mcp_path" '
        .mcpServers //= {}
        | .mcpServers.brain = {
            command: $cmd,
            disabled: false,
            env: { PATH: $path }
          }
        | if ($args | length) > 0 then .mcpServers.brain.args = $args else . end
      ' "$cfg" > "$tmp"
      mv "$tmp" "$cfg"
      added+=("brain")
    fi
  else
    echo "  agy mcp: brain CLI not found; skipped its MCP registration" >&2
  fi

  tmp="$(mktemp)"
  if [ -n "$kanban_cmd" ]; then
    if jq -e '.mcpServers.kanban.command? // empty | length > 0' "$cfg" >/dev/null 2>&1; then
      :
    else
      jq --arg cmd "$kanban_cmd" --arg path "$mcp_path" '
        .mcpServers //= {}
        | .mcpServers.kanban = {
            command: $cmd,
            args: ["mcp"],
            disabled: false,
            env: { PATH: $path }
          }
      ' "$cfg" > "$tmp"
      mv "$tmp" "$cfg"
      added+=("kanban")
    fi
  else
    echo "  agy mcp: kanban CLI not found; skipped its MCP registration" >&2
  fi

  if [ ${#added[@]} -gt 0 ]; then
    echo "  agy mcp: added ${added[*]} to $cfg"
  else
    echo "  agy mcp: brain + kanban already registered"
  fi
}

install_host_track_shim() {
  local src="$SOURCE_ROOT/bin/host-track"
  local dest="$HOME/.local/bin/host-track"
  local registry_src="$SOURCE_ROOT/config/host-track/apps.json"
  local registry_dest="$HOME/.local/share/last-stack/config/host-track/apps.json"
  [ -f "$src" ] || return 0
  mkdir -p "$(dirname "$dest")"
  [ -L "$dest" ] && rm -f "$dest"
  _link_or_copy "$src" "$dest"
  chmod 700 "$dest" 2>/dev/null || true
  if [ -f "$registry_src" ]; then
    mkdir -p "$(dirname "$registry_dest")"
    cp -f "$registry_src" "$registry_dest"
    chmod 600 "$registry_dest" 2>/dev/null || true
  fi
  echo "  host-track: $dest"
}

install_shared_checkout_guards() {
  local local_bin="$HOME/.local/bin"
  local name src dest
  mkdir -p "$local_bin"
  for name in last-stack-shared-checkout-guard last-stack-install-shared-checkout-guards; do
    src="$SOURCE_ROOT/bin/$name"
    dest="$local_bin/$name"
    [ -f "$src" ] || continue
    [ -L "$dest" ] && rm -f "$dest"
    _link_or_copy "$src" "$dest"
    chmod 700 "$dest" 2>/dev/null || true
  done
  if [ -x "$local_bin/last-stack-install-shared-checkout-guards" ]; then
    "$local_bin/last-stack-install-shared-checkout-guards" \
      "${LAST_STACK_SHARED_WORKSPACE:-$HOME/code/edgevector}" \
      || echo "  shared-checkout guards: install failed" >&2
  fi
}

xml_escape() {
  sed \
    -e 's/&/\&amp;/g' \
    -e 's/</\&lt;/g' \
    -e 's/>/\&gt;/g' \
    -e 's/"/\&quot;/g' \
    -e "s/'/\&apos;/g"
}

host_track_launchd_plist_path() {
  printf '%s\n' "${LAST_STACK_HOST_TRACK_PLIST:-$HOME/.last-stack/launchd/com.edgevector.host-track-refresh.plist}"
}

host_track_real_home_matches() {
  local real_home
  real_home="$(eval "printf '%s' ~$(id -un)" 2>/dev/null || true)"
  [ -n "$real_home" ] && [ "$HOME" = "$real_home" ]
}

host_track_refresh_watch_paths() {
  local registry="$SOURCE_ROOT/config/host-track/apps.json"
  local raw path git_dir
  [ -f "$registry" ] || return 0
  command -v jq >/dev/null 2>&1 || return 0
  command -v git >/dev/null 2>&1 || return 0

  jq -r '.apps[]? | select(.gate == "forgejo") | .host_track // empty' "$registry" |
    while IFS= read -r raw; do
      [ -n "$raw" ] || continue
      case "$raw" in
        '$HOME') path="$HOME" ;;
        '$HOME'/*) path="$HOME/${raw#\$HOME/}" ;;
        "~") path="$HOME" ;;
        "~"/*) path="$HOME/${raw#~/}" ;;
        *) path="$raw" ;;
      esac
      [ -d "$path" ] || continue
      git_dir="$(git -C "$path" rev-parse --git-dir 2>/dev/null || true)"
      [ -n "$git_dir" ] || continue
      case "$git_dir" in
        /*) ;;
        *) git_dir="$path/$git_dir" ;;
      esac
      if [ -e "$git_dir/FETCH_HEAD" ]; then
        printf '%s\n' "$git_dir/FETCH_HEAD"
      fi
    done
}

write_host_track_refresh_agent_plist() {
  local plist="$1"
  local program="$HOME/.local/bin/host-track"
  local log_dir="$HOME/Library/Logs/last-stack"
  local watch_paths
  mkdir -p "$(dirname "$plist")" "$log_dir"
  watch_paths="$(host_track_refresh_watch_paths | awk '!seen[$0]++')"

  {
    cat <<EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.edgevector.host-track-refresh</string>
  <key>ProgramArguments</key>
  <array>
    <string>$(printf '%s' "$program" | xml_escape)</string>
    <string>refresh</string>
    <string>--force-if-stale</string>
    <string>--all</string>
  </array>
  <key>EnvironmentVariables</key>
  <dict>
    <key>PATH</key>
    <string>$HOME/.local/bin:$HOME/.bun/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
  </dict>
  <key>StartInterval</key>
  <integer>1200</integer>
  <key>StandardOutPath</key>
  <string>$(printf '%s' "$log_dir/host-track-refresh.log" | xml_escape)</string>
  <key>StandardErrorPath</key>
  <string>$(printf '%s' "$log_dir/host-track-refresh.err.log" | xml_escape)</string>
EOF
    if [ -n "$watch_paths" ]; then
      cat <<'EOF'
  <key>WatchPaths</key>
  <array>
EOF
      printf '%s\n' "$watch_paths" | while IFS= read -r watch_path; do
        [ -n "$watch_path" ] || continue
        printf '    <string>%s</string>\n' "$(printf '%s' "$watch_path" | xml_escape)"
      done
      cat <<'EOF'
  </array>
EOF
    fi
    cat <<'EOF'
</dict>
</plist>
EOF
  } > "$plist"
  chmod 600 "$plist" 2>/dev/null || true
}

install_host_track_refresh_agent() {
  [ "$(uname -s)" = "Darwin" ] || return 0
  local plist label="com.edgevector.host-track-refresh"
  plist="$(host_track_launchd_plist_path)"
  write_host_track_refresh_agent_plist "$plist"
  echo "  host-track refresh agent: $plist"

  if ! host_track_real_home_matches; then
    echo "  host-track refresh agent: launchctl skipped for non-login HOME"
    return 0
  fi
  command -v launchctl >/dev/null 2>&1 || {
    echo "  host-track refresh agent: launchctl not found; plist written only" >&2
    return 0
  }

  launchctl bootout "gui/$(id -u)/$label" >/dev/null 2>&1 || true
  if launchctl bootstrap "gui/$(id -u)" "$plist" >/dev/null 2>&1; then
    launchctl enable "gui/$(id -u)/$label" >/dev/null 2>&1 || true
    echo "  host-track refresh agent: loaded $label"
  else
    echo "  host-track refresh agent: launchctl bootstrap failed; plist written only" >&2
  fi
}

install_routines_cli() {
  local routines_bin=""
  if [ "${LAST_STACK_SKIP_ROUTINES_INSTALL:-0}" = "1" ]; then
    echo "  routines CLI: skipped (LAST_STACK_SKIP_ROUTINES_INSTALL=1)"
    return 0
  fi

  routines_bin="$(command -v routines 2>/dev/null || true)"
  [ -x "$routines_bin" ] || routines_bin="$HOME/.local/bin/routines"
  if [ -x "$routines_bin" ] && "$routines_bin" --help >/dev/null 2>&1; then
    echo "  routines CLI: already installed ($routines_bin)"
    return 0
  fi

  # Test/sandbox HOME values must never clone into or relink the login user's
  # real app tree. Production callers can override only for a deliberate
  # hermetic install proof.
  if ! host_track_real_home_matches && [ "${LAST_STACK_ROUTINES_FORCE_INSTALL:-0}" != "1" ]; then
    echo "  routines CLI: install skipped for non-login HOME"
    return 0
  fi

  local installer
  installer="${LAST_STACK_ROUTINES_INSTALLER:-$SOURCE_ROOT/bin/last-stack-install-routines}"
  [ -x "$installer" ] || {
    echo "routines CLI installer is missing or not executable: $installer" >&2
    return 1
  }

  echo "  routines CLI: installing ..."
  "$installer"
}

# ── Register every skills/<name>/SKILL.md into a target skills dir ────────────
register_into() {
  local skills_dir="$1"
  local label="$2"
  local linked=()
  mkdir -p "$skills_dir"
  for skill_dir in "$SKILLS_SRC"/*/; do
    [ -f "$skill_dir/SKILL.md" ] || continue
    local dir_name skill_name target
    dir_name="$(basename "$skill_dir")"
    [ "$dir_name" = "node_modules" ] && continue
    # Prefer the frontmatter `name:` so the slash-command matches the skill name.
    skill_name="$(grep -m1 '^name:' "$skill_dir/SKILL.md" 2>/dev/null | sed 's/^name:[[:space:]]*//' | tr -d '[:space:]')"
    [ -z "$skill_name" ] && skill_name="$dir_name"
    target="$skills_dir/$skill_name"
    # Replace stale dir-symlinks from older layouts.
    [ -L "$target" ] && rm -f "$target"
    mkdir -p "$target"
    [ -L "$target/SKILL.md" ] && rm -f "$target/SKILL.md"
    _link_or_copy "${skill_dir%/}/SKILL.md" "$target/SKILL.md"
    # Mirror any sidecar files (helper scripts, references/) so skills with more
    # than a SKILL.md work fully from the source repo — not just their SKILL.md.
    local base="${skill_dir%/}"
    find "$base" -type f ! -name SKILL.md | while IFS= read -r src; do
      rel="${src#"$base"/}"
      dest="$target/$rel"
      mkdir -p "$(dirname "$dest")"
      [ -L "$dest" ] && rm -f "$dest"
      _link_or_copy "$src" "$dest"
    done
    assert_safe_skill_links "$target"
    linked+=("$skill_name")
  done
  if [ ${#linked[@]} -gt 0 ]; then
    echo "  ${label}: ${linked[*]}"
  else
    echo "  ${label}: (no skills found)" >&2
  fi
}

# ── --local: vendor into the current project's .claude/skills ─────────────────
if [ "$LOCAL_INSTALL" -eq 1 ]; then
  echo "Installing The Last Stack (v$(cat "$SOURCE_ROOT/VERSION")) into ./.claude/skills ..."
  register_into "$(pwd)/.claude/skills" "claude (project)"
  echo "Done."
  exit 0
fi

# ── Detect which harnesses are present ────────────────────────────────────────
INSTALL_CLAUDE=0; INSTALL_CODEX=0; INSTALL_FACTORY=0; INSTALL_OPENCODE=0; INSTALL_GROK=0; INSTALL_AGY=0
case "$HOST" in
  claude)   INSTALL_CLAUDE=1 ;;
  codex)    INSTALL_CODEX=1 ;;
  factory)  INSTALL_FACTORY=1 ;;
  opencode) INSTALL_OPENCODE=1 ;;
  grok)     INSTALL_GROK=1 ;;
  agy)      INSTALL_AGY=1 ;;
  auto)
    { command -v claude   >/dev/null 2>&1 || [ -d "$HOME/.claude" ]; } && INSTALL_CLAUDE=1
    { command -v codex    >/dev/null 2>&1 || [ -d "$HOME/.codex" ]; }  && INSTALL_CODEX=1
    { command -v droid    >/dev/null 2>&1 || [ -d "$HOME/.factory" ]; } && INSTALL_FACTORY=1
    { command -v opencode >/dev/null 2>&1 || [ -d "$HOME/.config/opencode" ]; } && INSTALL_OPENCODE=1
    { command -v grok     >/dev/null 2>&1 || [ -d "$HOME/.grok" ]; } && INSTALL_GROK=1
    agy_detected && INSTALL_AGY=1
    # Nothing detected → default to Claude Code.
    if [ $((INSTALL_CLAUDE+INSTALL_CODEX+INSTALL_FACTORY+INSTALL_OPENCODE+INSTALL_GROK+INSTALL_AGY)) -eq 0 ]; then
      INSTALL_CLAUDE=1
    fi
    ;;
  *) echo "unknown --host: $HOST (use claude|codex|factory|opencode|grok|agy|auto)" >&2; exit 2 ;;
esac

echo "Installing The Last Stack (v$(cat "$SOURCE_ROOT/VERSION")) ..."
[ "$INSTALL_CLAUDE"   -eq 1 ] && register_into "$HOME/.claude/skills"          "claude"
[ "$INSTALL_CLAUDE"   -eq 1 ] && install_claude_hooks
[ "$INSTALL_CLAUDE"   -eq 1 ] && upsert_harness_instruction_blocks "$HOME/.claude/CLAUDE.md" "claude"
[ "$INSTALL_CODEX"    -eq 1 ] && register_into "$HOME/.codex/skills"           "codex"
[ "$INSTALL_CODEX"    -eq 1 ] && upsert_harness_instruction_blocks "$HOME/.codex/AGENTS.md" "codex"
[ "$INSTALL_CODEX"    -eq 1 ] && ensure_codex_mcp_servers
[ "$INSTALL_FACTORY"  -eq 1 ] && register_into "$HOME/.factory/skills"         "factory"
[ "$INSTALL_FACTORY"  -eq 1 ] && upsert_harness_instruction_blocks "$HOME/.factory/AGENTS.md" "factory"
[ "$INSTALL_OPENCODE" -eq 1 ] && register_into "$HOME/.config/opencode/skills" "opencode"
[ "$INSTALL_OPENCODE" -eq 1 ] && upsert_harness_instruction_blocks "$HOME/.config/opencode/AGENTS.md" "opencode"
[ "$INSTALL_GROK"     -eq 1 ] && upsert_harness_instruction_blocks "$HOME/.grok/AGENTS.md" "grok"
[ "$INSTALL_AGY"      -eq 1 ] && register_into "$HOME/.gemini/config/skills"  "agy"
[ "$INSTALL_AGY"      -eq 1 ] && upsert_harness_instruction_blocks "$HOME/.gemini/GEMINI.md" "agy"
[ "$INSTALL_AGY"      -eq 1 ] && upsert_harness_instruction_blocks "$HOME/.gemini/config/GEMINI.md" "agy (config)"
[ "$INSTALL_AGY"      -eq 1 ] && ensure_agy_mcp_servers
install_host_track_shim
install_routines_cli
install_shared_checkout_guards
install_host_track_refresh_agent

# Zero-LLM board closeout (merged PR/CR → done) — survives low-credit watch pause.
# Point LaunchAgents at the stable public root, not SOURCE_ROOT's version hash.
if [ -x "$SOURCE_ROOT/bin/last-stack-board-closeout-install" ]; then
  LAST_STACK_PUBLIC_ROOT="${LAST_STACK_PUBLIC_ROOT:-$HOME/.last-stack}" \
    "$SOURCE_ROOT/bin/last-stack-board-closeout-install" install || \
    echo "  board-closeout LaunchAgent: install failed (non-fatal)" >&2
fi

# Hourly zero-LLM Loom recovery. The runner fixes the five-minute grace and
# one-resume cap, and it calls the Host Track binary through ~/.local/bin.
if [ -x "$SOURCE_ROOT/bin/last-stack-loom-reaper-install" ]; then
  LAST_STACK_PUBLIC_ROOT="${LAST_STACK_PUBLIC_ROOT:-$HOME/.last-stack}" \
    "$SOURCE_ROOT/bin/last-stack-loom-reaper-install" install || \
    echo "  loom-reaper LaunchAgent: install failed (non-fatal)" >&2
fi

# Weekly VM sparse-disk trim (returns in-VM freed blocks to the host volume).
# A LaunchAgent, not a routine step: the scheduled routine sandbox may not
# reach the docker socket. The helper self-throttles to one trim per week.
if [ -x "$SOURCE_ROOT/bin/last-stack-vm-disk-trim-install" ]; then
  LAST_STACK_PUBLIC_ROOT="${LAST_STACK_PUBLIC_ROOT:-$HOME/.last-stack}" \
    "$SOURCE_ROOT/bin/last-stack-vm-disk-trim-install" install || \
    echo "  vm-disk-trim LaunchAgent: install failed (non-fatal)" >&2
fi

# Hourly factory health (bands + ra notify).
if [ -x "$SOURCE_ROOT/bin/last-stack-factory-health-install" ]; then
  LAST_STACK_PUBLIC_ROOT="${LAST_STACK_PUBLIC_ROOT:-$HOME/.last-stack}" \
    "$SOURCE_ROOT/bin/last-stack-factory-health-install" install || \
    echo "  factory-health LaunchAgent: install failed (non-fatal)" >&2
fi

# Demand-based ready buffer (zero LLM). The installer loads the shipped
# controller before it removes the old host-local idle ladder.
if [ -x "$SOURCE_ROOT/bin/last-stack-factory-ready-buffer-install" ]; then
  LAST_STACK_PUBLIC_ROOT="${LAST_STACK_PUBLIC_ROOT:-$HOME/.last-stack}" \
    "$SOURCE_ROOT/bin/last-stack-factory-ready-buffer-install" install || \
    echo "  factory-ready-buffer LaunchAgent: install failed (non-fatal)" >&2
fi

# Host-side memory guards (GUI Activity Monitor, cargo test binaries, sentinel).
# Does not touch the primary lastdbd process or its 16 GiB footprint guard.
if [ -x "$SOURCE_ROOT/bin/last-stack-host-memory-guards-install" ]; then
  LAST_STACK_PUBLIC_ROOT="${LAST_STACK_PUBLIC_ROOT:-$HOME/.last-stack}" \
    "$SOURCE_ROOT/bin/last-stack-host-memory-guards-install" install || \
    echo "  host-memory-guards LaunchAgents: install failed (non-fatal)" >&2
fi

# Hourly Brain and Routines admin SPA deliveries. Recipient identity remains in
# ~/.lastdb/admin-deliver-recipient.env; no key material enters a plist.
if [ -x "$SOURCE_ROOT/bin/last-stack-admin-deliver-install" ]; then
  LAST_STACK_PUBLIC_ROOT="${LAST_STACK_PUBLIC_ROOT:-$HOME/.last-stack}" \
    "$SOURCE_ROOT/bin/last-stack-admin-deliver-install" install || \
    echo "  admin deliverer LaunchAgents: install failed (non-fatal)" >&2
fi

# Seed missing registry TOMLs only. Existing ~/.routines/registry entries are
# the canonical live registry and are not rewritten on host-track refresh.
#
# Every bin/last-stack-*-routine script is a seed-if-missing registry
# installer with the same no-argument contract, so iterate the directory
# instead of listing them by hand. A hand-maintained list silently drops any
# seeder added later: bin/last-stack-lastdb-canary-build-main-routine shipped
# on 2026-09-03 and was never called here, so no host ever registered
# lastdb-canary-build-main, nothing built a canary stage for fold main, and
# lastdb-local-smoke-test fell back to a stale binary with sha_drift=true on
# every run. tests/last-stack-setup-seeds-every-routine.sh holds this shape.
for routine_seeder in "$SOURCE_ROOT"/bin/last-stack-*-routine; do
  [ -x "$routine_seeder" ] || continue
  seeder_name="$(basename "$routine_seeder")"
  "$routine_seeder" || \
    echo "  $seeder_name: registry install failed (non-fatal)" >&2
done
unset routine_seeder seeder_name

# Zero-LLM self-upgrade healer (every 30m) — checkout installs only.
# Artifact runtime (one rule): host-track refresh agent is the only upgrader.
if [ -x "$SOURCE_ROOT/bin/last-stack-self-upgrade-install" ]; then
  if [ "$ARTIFACT_INSTALL" -eq 1 ]; then
    "$SOURCE_ROOT/bin/last-stack-self-upgrade-install" uninstall || \
      echo "  last-stack-self-upgrade LaunchAgent: uninstall failed (non-fatal)" >&2
  else
    "$SOURCE_ROOT/bin/last-stack-self-upgrade-install" install || \
      echo "  last-stack-self-upgrade LaunchAgent: install failed (non-fatal)" >&2
  fi
fi

# One rule: when this setup is running from the Host Track artifact, ensure
# ~/.last-stack/{bin,skills,routines,...} are compatibility symlinks into
# .artifacts/current — never a second mutable copy agents can dirty.
# Nested call from last-stack-activate-artifact-layout sets SKIP=1.
if [ "$ARTIFACT_INSTALL" -eq 1 ] && \
   [ "${LAST_STACK_SKIP_ARTIFACT_LAYOUT:-0}" != "1" ] && \
   [ -x "$SOURCE_ROOT/bin/last-stack-activate-artifact-layout" ]; then
  compat_root="${LAST_STACK_COMPAT_ROOT:-$HOME/.last-stack}"
  need_layout=0
  if [ ! -L "$compat_root/bin" ]; then
    need_layout=1
  else
    link="$(readlink "$compat_root/bin" 2>/dev/null || true)"
    case "$link" in
      */.artifacts/current/bin|*/.artifacts/current/bin/) ;;
      *) need_layout=1 ;;
    esac
  fi
  if [ "$need_layout" -eq 1 ]; then
    echo "  activating artifact compatibility layout under $compat_root ..."
    # Always allow replacing a residual git-owned ~/.last-stack when setup is
    # installing from the Host Track artifact (the live stack is not a checkout).
    LAST_STACK_SKIP_ARTIFACT_LAYOUT=1 \
    LAST_STACK_ARTIFACT_LAYOUT_ALLOW_GIT_WORKTREE=1 \
      "$SOURCE_ROOT/bin/last-stack-activate-artifact-layout" || \
      echo "  artifact layout activation failed (non-fatal this run)" >&2
  fi
fi

# ── Guard against foreign installers (e.g. gstack) stomping our skill links ────
# Another installer that ships a same-named skill (gstack shipped a `diagram`
# skill colliding with our hand-drawn one) silently re-points that SKILL.md at
# its own tree. Registering above already re-points our links, but verify + emit
# any collisions so re-running setup AFTER gstack setup provably restores us.
guard="$SOURCE_ROOT/bin/last-stack-verify-skill-links"
if [ -x "$guard" ]; then
  guard_dirs=()
  [ "$INSTALL_CLAUDE"   -eq 1 ] && guard_dirs+=("$HOME/.claude/skills")
  [ "$INSTALL_CODEX"    -eq 1 ] && guard_dirs+=("$HOME/.codex/skills")
  [ "$INSTALL_FACTORY"  -eq 1 ] && guard_dirs+=("$HOME/.factory/skills")
  [ "$INSTALL_OPENCODE" -eq 1 ] && guard_dirs+=("$HOME/.config/opencode/skills")
  [ "$INSTALL_AGY"      -eq 1 ] && guard_dirs+=("$HOME/.gemini/config/skills")
  [ ${#guard_dirs[@]} -gt 0 ] && "$guard" --quiet "${guard_dirs[@]}" || true
fi

echo
if [ "$ARTIFACT_INSTALL" -eq 1 ]; then
  echo "Done. Upgrade later with:  host-track refresh last-stack"
else
  echo "Done. Upgrade later with:  cd \"$SOURCE_ROOT\" && git pull && ./setup"
fi
echo "  (run this AFTER any gstack ./setup — it re-points Last Stack skill links"
echo "   that a colliding gstack skill name would otherwise stomp)"
echo "Uninstall with:           \"$SOURCE_ROOT/setup\" --uninstall"