happy-stacks 0.1.2 → 0.2.0

package/docs/menubar.md

@@ -32,6 +32,26 @@ SwiftBar runs a script on an interval and renders its output as native macOS men
   - Each component includes a **Worktrees** submenu listing all worktrees, with actions to switch/open
   - Quick actions: `wt status/sync/update`, PR worktree prompt, open shells/editors (`wt shell/code/cursor`)
   - Shows **origin** and **upstream** comparisons for the component repo’s main branch (based on your last `git fetch`)
+  - Uses a **Git cache** by default so SwiftBar refresh stays fast even with many stacks/worktrees
+
+## Modes: selfhost vs dev
+
+The menu supports two modes:
+
+- **Selfhost mode** (`selfhost`): lightweight “control panel” for running Happy.
+  - Shows only the main stack essentials (Server/Daemon/Autostart/Tailscale) plus a small **Maintenance** section.
+  - Hides developer-oriented sections like stacks enumeration, components git/worktrees, and worktree tooling.
+- **Dev mode** (`dev`): full happy-stacks control plane (stacks + components + worktrees).
+
+### How to switch modes
+
+- In the menu, use the **Mode** section at the top, or
+- From a terminal:
+
+```bash
+happys menubar mode selfhost
+happys menubar mode dev
+```
 
 ## Stacks (multiple instances)
 
@@ -125,6 +145,40 @@ The plugin defaults to a slower interval (recommended), and also sets:
 
 You can also change the interval directly from the menu via **Refresh interval** (it renames the plugin file and restarts SwiftBar).
 
+## Git cache (important for performance)
+
+Git/worktree inspection is the most expensive part of the menu when you have many stacks.
+By default, the plugin runs in **cached mode**:
+
+- It renders git/worktree info from an on-disk cache under `~/.happy-stacks/cache/swiftbar/git`.
+- Normal menu refreshes do **not** run git commands (so refresh stays snappy).
+- The cache is refreshed explicitly (via menu actions), and can optionally refresh on TTL expiry.
+
+Controls and settings:
+
+- **Refresh now**: open **Components → Git cache** and run:
+  - “Refresh now (main components)”
+  - “Refresh now (all stacks/components)”
+  - or “Refresh now (this stack)” from a stack’s Components menu
+- **TTL**: `HAPPY_STACKS_SWIFTBAR_GIT_TTL_SEC` (default `3600` seconds)
+- **TTL**: `HAPPY_STACKS_SWIFTBAR_GIT_TTL_SEC` (default `21600` seconds = 6 hours)
+- **Mode**: `HAPPY_STACKS_SWIFTBAR_GIT_MODE=cached|live` (default `cached`)
+- (Optional) **Background auto-refresh**: `HAPPY_STACKS_SWIFTBAR_GIT_AUTO_REFRESH_SCOPE=main|all|off` (default `main`)
+
+Notes:
+
+- Cached git info can be stale; it’s meant for at-a-glance signal.
+- Actions like worktree switching/build/dev are always live (they use `happys`); only *displayed git status* is cached.
+
+## Maintenance (selfhost mode)
+
+In **selfhost** mode, the menu includes a **Maintenance** section that can:
+
+- show whether a `happy-stacks` update is available (from cached `~/.happy-stacks/cache/update.json`)
+- run:
+  - `happys self check`
+  - `happys self update`
+
 ## Terminal preference for interactive actions
 
 Many menu actions open a terminal (interactive wizards, long-running dev servers, etc).

package/docs/paths-and-env.md

@@ -0,0 +1,141 @@
+# Paths, folders, and env precedence
+
+This doc explains the **directories** that Happy Stacks uses (home/workspace/runtime/stacks), and the **environment file precedence** used by `happys`.
+
+If you’re ever unsure what your machine is actually using, run:
+
+```bash
+happys where
+```
+
+---
+
+## Quick glossary
+
+- **CLI root dir**
+  - The directory containing the `happy-stacks` scripts (`scripts/*.mjs`) that your `happys` command is currently executing.
+  - This is *not* necessarily your current shell `cwd`.
+  - It can be:
+    - a cloned repo checkout (e.g. `/Users/<you>/.../happy-local`), or
+    - the installed runtime package under `~/.happy-stacks/runtime/node_modules/happy-stacks` (see “Runtime dir”).
+
+- **Home dir** (`HAPPY_STACKS_HOME_DIR`)
+  - Default: `~/.happy-stacks`
+  - Stores **global user config** + caches, and may include a runtime install.
+
+- **Runtime dir** (`HAPPY_STACKS_RUNTIME_DIR`)
+  - Default: `~/.happy-stacks/runtime`
+  - Used by `happys self update` to install/upgrade a pinned `happy-stacks` runtime package.
+
+- **Workspace dir** (`HAPPY_STACKS_WORKSPACE_DIR`)
+  - Default: `~/.happy-stacks/workspace` (when it exists).
+  - This is the **storage workspace for component repos and worktrees** used by Happy Stacks.
+  - Important: this is **not your IDE workspace**; it’s where Happy Stacks keeps `components/` by default.
+  - Back-compat: before you run `happys init` (cloned repo usage), we fall back to using the CLI root dir as the workspace, so `components/` lives inside the repo checkout.
+
+- **Components dir**
+  - Computed as: `<workspaceDir>/components`
+  - Contains `happy`, `happy-cli`, `happy-server-light`, `happy-server`, plus `.worktrees/`.
+
+- **Stacks storage dir**
+  - Default: `~/.happy/stacks`
+  - Each stack lives under `~/.happy/stacks/<name>/...` and has its own env file:
+    - `~/.happy/stacks/<name>/env`
+  - Legacy stacks path is also supported:
+    - `~/.happy/local/stacks/<name>/env`
+
+---
+
+## “Where am I actually running from?”
+
+`happys` may **re-exec** to a different CLI root dir (for example, when you use an installed shim but want it to run a local checkout).
+
+- Run `happys where` to see:
+  - **rootDir** (CLI root dir)
+  - **homeDir** (stacks home dir)
+  - **runtimeDir**
+  - **workspaceDir**
+  - resolved env file paths
+
+Tip: `happys where --json` is easier to parse.
+
+---
+
+## Env files + precedence (lowest → highest)
+
+Happy Stacks loads env in `scripts/utils/env.mjs`.
+
+### 0) “Canonical pointer” env (discovery)
+
+If `HAPPY_STACKS_HOME_DIR` is *not* set, we first try to read the **canonical pointer** env file to discover the intended home dir (useful for LaunchAgents / SwiftBar / minimal shells).
+
+- Default canonical pointer path: `~/.happy-stacks/.env`
+- Override canonical pointer location:
+  - `HAPPY_STACKS_CANONICAL_HOME_DIR=/some/dir` (pointer becomes `<dir>/.env`)
+
+### 1) Global defaults (home config) OR cloned-repo defaults
+
+If home config exists, we load:
+
+- `~/.happy-stacks/.env` (**defaults**)
+- `~/.happy-stacks/env.local` (**overrides**, prefix-aware for `HAPPY_STACKS_*` / `HAPPY_LOCAL_*`)
+
+If home config does *not* exist (cloned repo usage before `happys init`), we load:
+
+- `<cliRootDir>/.env`
+- `<cliRootDir>/env.local` (prefix-aware for `HAPPY_STACKS_*` / `HAPPY_LOCAL_*`)
+
+### 2) Repo `.env` fallback (dev convenience)
+
+Even when home config exists, we also load:
+
+- `<cliRootDir>/.env` (non-overriding fallback)
+
+This exists so repo-local dev settings (example: `HAPPY_CODEX_BIN`) can work without forcing everyone to duplicate them into `~/.happy-stacks/env.local`.
+
+Notes:
+- This is a **fallback only** (`override: false`): it won’t stomp on values already provided by the environment or home config.
+- We intentionally do **not** auto-load `<cliRootDir>/env.local` in this “home config exists” path, because it’s higher-precedence and can unexpectedly fight stack config.
+
+### 3) Stack env overlay (highest precedence)
+
+Finally, we load the active stack env file (override = true):
+
+- `HAPPY_STACKS_ENV_FILE` (or legacy `HAPPY_LOCAL_ENV_FILE`)
+- if neither is set, we auto-select the env file for the current stack (defaults to `main`) if it exists
+
+Stack env files are allowed to contain **non-prefixed keys** (like `DATABASE_URL`) because that’s required for per-stack isolation.
+
+---
+
+## What should go where? (rules of thumb)
+
+- Put **global, machine-wide defaults** in `~/.happy-stacks/.env`.
+- Put **your personal overrides** in `~/.happy-stacks/env.local`.
+- Put **per-stack isolation config** in the stack env file `~/.happy/stacks/<name>/env` (this is what `happys stack edit` and `happys stack wt` mutate).
+- Put **repo-local dev-only defaults** in `<cliRootDir>/.env` (works best when you’re actually running from that checkout as the CLI root dir).
+
+---
+
+## Sandbox / test installs (fully isolated)
+
+If you want to test the full install + setup flows without touching your real installation, run with:
+
+```bash
+npx happy-stacks --sandbox-dir /tmp/happy-stacks-sandbox where
+```
+
+In sandbox mode, Happy Stacks redirects **home/workspace/runtime/storage** under the sandbox folder (so you can `rm -rf` it to reset).
+
+Global OS side effects (PATH edits, SwiftBar plugin install, LaunchAgents/systemd services) are **disabled by default** in sandbox mode.
+To explicitly allow them for testing, set:
+
+- `HAPPY_STACKS_SANDBOX_ALLOW_GLOBAL=1`
+
+---
+
+## Related docs
+
+- `docs/stacks.md` (stacks lifecycle + commands)
+- `docs/worktrees-and-forks.md` (worktrees layout + upstream/fork workflows)
+

package/docs/stacks.md

@@ -41,6 +41,43 @@ Auto-pick a port:
 happys stack new exp2
 ```
 
+## Create a PR test stack (copy/paste friendly)
+
+If you want maintainers to be able to try your PR quickly, you can give them a single command that:
+
+- creates an isolated stack
+- checks out PR(s) into worktrees
+- pins those worktrees to the stack
+- optionally seeds auth
+- optionally starts the stack in dev mode
+
+Example (most common):
+
+```bash
+happys stack pr pr123 \
+  --happy=https://github.com/slopus/happy/pull/123 \
+  --happy-cli=https://github.com/slopus/happy-cli/pull/456 \
+  --seed-auth --copy-auth-from=dev-auth --link-auth \
+  --dev
+```
+
+Notes:
+
+- `--remote` (default `upstream`) controls which Git remote is used to fetch `refs/pull/<n>/head`.
+- `--seed-auth` uses `happys stack auth <stack> copy-from <source>` under the hood, which also best-effort seeds DB Account rows (avoids FK errors like Prisma `P2003`).
+- You can use your existing non-stacks Happy install as an auth seed source with:
+  - `--copy-auth-from=legacy` (reads from `~/.happy/{cli,server-light}` best-effort)
+- `--link-auth` symlinks auth files instead of copying them (keeps credentials in sync, but reduces isolation).
+- For full-server stacks (`happy-server`), seeding may need Docker infra:
+
+```bash
+happys stack pr pr789 \
+  --server=happy-server \
+  --happy-server=https://github.com/slopus/happy-server/pull/789 \
+  --seed-auth --copy-auth-from=dev-auth --with-infra \
+  --dev
+```
+
 Interactive wizard (TTY only):
 
 ```bash
@@ -193,6 +230,8 @@ On startup, `happy-stacks` loads env in this order:
 
 `happys stack ...` sets `HAPPY_STACKS_ENV_FILE=~/.happy/stacks/<name>/env` (and also sets legacy `HAPPY_LOCAL_ENV_FILE`) and clears any already-exported `HAPPY_STACKS_*` / `HAPPY_LOCAL_*` variables so the stack env stays authoritative.
 
+For a full explanation of the different folders/paths (`home` vs `workspace` vs `runtime` vs stack storage) and the exact env precedence rules, see: `[docs/paths-and-env.md](docs/paths-and-env.md)`.
+
 Cloned-repo fallback (before you run `happys init`):
 
 1. `<repo>/.env` (defaults)

package/extras/swiftbar/auth-login.sh

@@ -15,8 +15,11 @@ _server_url="${2:-}"   # ignored (kept for backwards compatibility)
 _webapp_url="${3:-}"   # ignored (kept for backwards compatibility)
 _cli_home_dir="${4:-}" # ignored (kept for backwards compatibility)
 
-HAPPY_STACKS_HOME_DIR="${HAPPY_STACKS_HOME_DIR:-$HOME/.happy-stacks}"
-HAPPY_LOCAL_DIR="${HAPPY_LOCAL_DIR:-$HAPPY_STACKS_HOME_DIR}"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+DEFAULT_HOME_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+HAPPY_LOCAL_DIR="${HAPPY_LOCAL_DIR:-${HAPPY_STACKS_HOME_DIR:-$DEFAULT_HOME_DIR}}"
+HAPPY_STACKS_HOME_DIR="${HAPPY_STACKS_HOME_DIR:-$HAPPY_LOCAL_DIR}"
 
 HAPPYS_TERM="$HAPPY_LOCAL_DIR/extras/swiftbar/happys-term.sh"
 if [[ ! -x "$HAPPYS_TERM" ]]; then

package/extras/swiftbar/git-cache-refresh.sh

@@ -0,0 +1,130 @@
+#!/bin/bash
+set -euo pipefail
+
+# Refresh SwiftBar Git/worktree cache.
+#
+# Usage:
+#   ./git-cache-refresh.sh all
+#   ./git-cache-refresh.sh main
+#   ./git-cache-refresh.sh stack <name>
+#   ./git-cache-refresh.sh component <context:main|stack> <stackName> <component>
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+DEFAULT_HOME_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+HAPPY_LOCAL_DIR="${HAPPY_LOCAL_DIR:-${HAPPY_STACKS_HOME_DIR:-$DEFAULT_HOME_DIR}}"
+HAPPY_STACKS_HOME_DIR="${HAPPY_STACKS_HOME_DIR:-$HAPPY_LOCAL_DIR}"
+
+LIB_DIR="$HAPPY_LOCAL_DIR/extras/swiftbar/lib"
+if [[ ! -f "$LIB_DIR/utils.sh" ]]; then
+  echo "missing SwiftBar libs at: $LIB_DIR" >&2
+  exit 1
+fi
+
+# shellcheck source=/dev/null
+source "$LIB_DIR/utils.sh"
+HAPPY_LOCAL_DIR="$(resolve_happy_local_dir)"
+LIB_DIR="$HAPPY_LOCAL_DIR/extras/swiftbar/lib"
+# shellcheck source=/dev/null
+source "$LIB_DIR/git.sh"
+
+components=(happy happy-cli happy-server-light happy-server)
+
+refresh_one() {
+  local context="$1"
+  local stack="$2"
+  local component="$3"
+  local env_file="$4"
+
+  local active_dir=""
+  if [[ -n "$env_file" && -f "$env_file" ]]; then
+    active_dir="$(resolve_component_dir_from_env_file "$env_file" "$component")"
+  else
+    active_dir="$(resolve_component_dir_from_env "$component")"
+  fi
+
+  git_cache_refresh_one "$context" "$stack" "$component" "$active_dir" >/dev/null
+}
+
+refresh_stack() {
+  local stack="$1"
+  local env_file=""
+  if [[ "$stack" == "main" ]]; then
+    env_file="$(resolve_main_env_file)"
+    [[ -z "$env_file" ]] && env_file="$(resolve_stack_env_file main)"
+  else
+    env_file="$(resolve_stack_env_file "$stack")"
+  fi
+
+  for c in "${components[@]}"; do
+    refresh_one "stack" "$stack" "$c" "$env_file"
+  done
+}
+
+cmd="${1:-}"
+case "$cmd" in
+  all)
+    refresh_stack "main"
+    STACKS_DIR="$(resolve_stacks_storage_root)"
+    LEGACY_STACKS_DIR="$HOME/.happy/local/stacks"
+    if swiftbar_is_sandboxed; then
+      LEGACY_STACKS_DIR=""
+    fi
+    STACK_NAMES="$(
+      {
+        ls -1 "$STACKS_DIR" 2>/dev/null || true
+        [[ -n "$LEGACY_STACKS_DIR" ]] && ls -1 "$LEGACY_STACKS_DIR" 2>/dev/null || true
+      } | sort -u
+    )"
+    while IFS= read -r s; do
+      [[ -n "$s" ]] || continue
+      [[ "$s" == "main" ]] && continue
+      refresh_stack "$s"
+    done <<<"$STACK_NAMES"
+    git_cache_touch_last_refresh "all"
+    echo "ok: git cache refreshed (all)"
+    ;;
+  main)
+    # Main stack only (fast).
+    local_env="$(resolve_main_env_file)"
+    for c in "${components[@]}"; do
+      refresh_one "main" "main" "$c" "$local_env"
+    done
+    git_cache_touch_last_refresh "main"
+    echo "ok: git cache refreshed (main)"
+    ;;
+  stack)
+    stack="${2:-}"
+    if [[ -z "$stack" ]]; then
+      echo "usage: $0 stack <name>" >&2
+      exit 2
+    fi
+    refresh_stack "$stack"
+    git_cache_touch_last_refresh "stack:${stack}"
+    echo "ok: git cache refreshed (stack $stack)"
+    ;;
+  component)
+    context="${2:-}"
+    stack="${3:-}"
+    component="${4:-}"
+    if [[ -z "$context" || -z "$stack" || -z "$component" ]]; then
+      echo "usage: $0 component <main|stack> <stackName> <component>" >&2
+      exit 2
+    fi
+    env_file=""
+    if [[ "$stack" == "main" ]]; then
+      env_file="$(resolve_main_env_file)"
+      [[ -z "$env_file" ]] && env_file="$(resolve_stack_env_file main)"
+    else
+      env_file="$(resolve_stack_env_file "$stack")"
+    fi
+    refresh_one "$context" "$stack" "$component" "$env_file"
+    git_cache_touch_last_refresh "component:${context}:${stack}:${component}"
+    echo "ok: git cache refreshed ($context/$stack/$component)"
+    ;;
+  *)
+    echo "usage: $0 all|main|stack <name>|component <context> <stackName> <component>" >&2
+    exit 2
+    ;;
+esac
+

package/extras/swiftbar/happy-stacks.5s.sh

@@ -19,8 +19,10 @@
 
 # SwiftBar runs with a minimal environment, so users often won't have
 # HAPPY_STACKS_HOME_DIR / HAPPY_STACKS_WORKSPACE_DIR exported.
-# Treat ~/.happy-stacks/.env as the canonical pointer file (written by `happys init`).
-CANONICAL_ENV_FILE="$HOME/.happy-stacks/.env"
+# Treat <canonicalHomeDir>/.env as the canonical pointer file (written by `happys init`).
+# Default: ~/.happy-stacks/.env
+CANONICAL_HOME_DIR="${HAPPY_STACKS_CANONICAL_HOME_DIR:-${HAPPY_LOCAL_CANONICAL_HOME_DIR:-$HOME/.happy-stacks}}"
+CANONICAL_ENV_FILE="$CANONICAL_HOME_DIR/.env"
 
 _dotenv_get_quick() {
   # Usage: _dotenv_get_quick /path/to/env KEY
@@ -54,7 +56,7 @@ if [[ -f "$CANONICAL_ENV_FILE" ]]; then
 fi
 _home_from_canonical="$(_expand_home_quick "${_home_from_canonical:-}")"
 
-HAPPY_STACKS_HOME_DIR="${HAPPY_STACKS_HOME_DIR:-${_home_from_canonical:-$HOME/.happy-stacks}}"
+HAPPY_STACKS_HOME_DIR="${HAPPY_STACKS_HOME_DIR:-${_home_from_canonical:-$CANONICAL_HOME_DIR}}"
 HAPPY_LOCAL_DIR="${HAPPY_LOCAL_DIR:-$HAPPY_STACKS_HOME_DIR}"
 HAPPY_LOCAL_PORT="${HAPPY_LOCAL_PORT:-3005}"
 
@@ -104,7 +106,12 @@ PNPM_BIN="$(resolve_pnpm_bin)"
 MAIN_PORT="$(resolve_main_port)"
 MAIN_SERVER_COMPONENT="$(resolve_main_server_component)"
 TAILSCALE_URL="$(get_tailscale_url)"
+if swiftbar_is_sandboxed; then
+  # Never probe Tailscale (global machine state) when sandboxing.
+  TAILSCALE_URL=""
+fi
 MAIN_ENV_FILE="$(resolve_main_env_file)"
+MENUBAR_MODE="$(resolve_menubar_mode)"
 
 ensure_launchctl_cache
 
@@ -142,6 +149,21 @@ echo "---"
 echo "Happy Stacks | size=14 font=SF Pro Display"
 echo "---"
 
+# Mode (selfhost vs dev)
+if [[ "$MENUBAR_MODE" == "selfhost" ]]; then
+  echo "Mode: Selfhost | sfimage=house"
+else
+  echo "Mode: Dev | sfimage=hammer"
+fi
+if [[ -n "$PNPM_BIN" ]]; then
+  if [[ "$MENUBAR_MODE" == "selfhost" ]]; then
+    echo "--Switch to Dev mode | bash=$PNPM_BIN param1=menubar param2=mode param3=dev dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
+  else
+    echo "--Switch to Selfhost mode | bash=$PNPM_BIN param1=menubar param2=mode param3=selfhost dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
+  fi
+fi
+echo "---"
+
 # Main stack (inline)
 echo "Main stack"
 echo "---"
@@ -153,90 +175,118 @@ render_component_autostart "" "main" "$MAIN_LABEL" "$MAIN_LAUNCHAGENT_STATUS" "$
 render_component_tailscale "" "main" "$TAILSCALE_URL"
 
 echo "---"
-echo "Stacks"
-echo "---"
-
-if [[ -n "$PNPM_BIN" ]]; then
-  HAPPYS_TERM="$HAPPY_LOCAL_DIR/extras/swiftbar/happys-term.sh"
-  echo "New stack (interactive) | bash=$HAPPYS_TERM param1=stack param2=new param3=--interactive dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
-  echo "List stacks | bash=$HAPPYS_TERM param1=stack param2=list dir=$HAPPY_LOCAL_DIR terminal=false"
-  echo "---"
-fi
+if [[ "$MENUBAR_MODE" == "selfhost" ]]; then
+  echo "Maintenance | sfimage=wrench.and.screwdriver"
+  if [[ -n "$PNPM_BIN" ]]; then
+    UPDATE_JSON="${HAPPY_LOCAL_DIR}/cache/update.json"
+    update_available=""
+    latest=""
+    current=""
+    if [[ -f "$UPDATE_JSON" ]]; then
+      update_available="$(grep -oE '\"updateAvailable\"[[:space:]]*:[[:space:]]*(true|false)' "$UPDATE_JSON" 2>/dev/null | head -1 | grep -oE '(true|false)' || true)"
+      latest="$(grep -oE '\"latest\"[[:space:]]*:[[:space:]]*\"[^\"]+\"' "$UPDATE_JSON" 2>/dev/null | head -1 | sed -E 's/.*\"latest\"[[:space:]]*:[[:space:]]*\"([^\"]+)\".*/\\1/' || true)"
+      current="$(grep -oE '\"current\"[[:space:]]*:[[:space:]]*\"[^\"]+\"' "$UPDATE_JSON" 2>/dev/null | head -1 | sed -E 's/.*\"current\"[[:space:]]*:[[:space:]]*\"([^\"]+)\".*/\\1/' || true)"
+    fi
+    if [[ "$update_available" == "true" && -n "$latest" ]]; then
+      echo "--Update available: ${current:-current} → ${latest} | color=$YELLOW"
+    else
+      echo "--Updates: up to date | color=$GRAY"
+    fi
+    echo "--Check for updates | bash=$PNPM_BIN param1=self param2=check dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
+    echo "--Update happy-stacks runtime | bash=$PNPM_BIN param1=self param2=update dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
+    echo "--Doctor | bash=$PNPM_BIN param1=doctor dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
+  else
+    echo "--⚠️ happys not found (run: npx happy-stacks setup)" 
+  fi
+else
+  echo "Stacks | sfimage=server.rack"
+  STACKS_PREFIX="--"
+
+  if [[ -n "$PNPM_BIN" ]]; then
+    HAPPYS_TERM="$HAPPY_LOCAL_DIR/extras/swiftbar/happys-term.sh"
+    echo "${STACKS_PREFIX}New stack (interactive) | bash=$HAPPYS_TERM param1=stack param2=new param3=--interactive dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
+    echo "${STACKS_PREFIX}List stacks | bash=$HAPPYS_TERM param1=stack param2=list dir=$HAPPY_LOCAL_DIR terminal=false"
+    print_sep "$STACKS_PREFIX"
+  fi
 
-STACKS_DIR="$(resolve_stacks_storage_root)"
-LEGACY_STACKS_DIR="$HOME/.happy/local/stacks"
-if [[ -d "$STACKS_DIR" ]] || [[ -d "$LEGACY_STACKS_DIR" ]]; then
-  STACK_NAMES="$(
-    {
-      ls -1 "$STACKS_DIR" 2>/dev/null || true
-      ls -1 "$LEGACY_STACKS_DIR" 2>/dev/null || true
-    } | sort -u
-  )"
-  if [[ -z "$STACK_NAMES" ]]; then
-    echo "No stacks found | color=$GRAY"
+  STACKS_DIR="$(resolve_stacks_storage_root)"
+  LEGACY_STACKS_DIR="$HOME/.happy/local/stacks"
+  if swiftbar_is_sandboxed; then
+    LEGACY_STACKS_DIR=""
   fi
-  for s in $STACK_NAMES; do
-    env_file="$(resolve_stack_env_file "$s")"
-    [[ -f "$env_file" ]] || continue
-
-    port="$(dotenv_get "$env_file" "HAPPY_STACKS_SERVER_PORT")"
-    [[ -z "$port" ]] && port="$(dotenv_get "$env_file" "HAPPY_LOCAL_SERVER_PORT")"
-    [[ -n "$port" ]] || continue
-
-    server_component="$(dotenv_get "$env_file" "HAPPY_STACKS_SERVER_COMPONENT")"
-    [[ -z "$server_component" ]] && server_component="$(dotenv_get "$env_file" "HAPPY_LOCAL_SERVER_COMPONENT")"
-    [[ -n "$server_component" ]] || server_component="happy-server-light"
-
-    base_dir="$(resolve_stack_base_dir "$s" "$env_file")"
-    cli_home_dir="$(resolve_stack_cli_home_dir "$s" "$env_file")"
-    label="$(resolve_stack_label "$s")"
-
-    COLLECT="$(collect_stack_status "$port" "$cli_home_dir" "$label" "$base_dir")"
-    IFS=$'\t' read -r LEVEL SERVER_STATUS SERVER_PID SERVER_METRICS DAEMON_STATUS DAEMON_PID DAEMON_METRICS DAEMON_UPTIME LAST_HEARTBEAT LAUNCHAGENT_STATUS AUTOSTART_PID AUTOSTART_METRICS <<<"$COLLECT"
-    for v in SERVER_PID SERVER_METRICS DAEMON_PID DAEMON_METRICS DAEMON_UPTIME LAST_HEARTBEAT AUTOSTART_PID AUTOSTART_METRICS; do
-      if [[ "${!v}" == "-" ]]; then
-        printf -v "$v" '%s' ""
-      fi
+  if [[ -d "$STACKS_DIR" ]] || [[ -n "$LEGACY_STACKS_DIR" && -d "$LEGACY_STACKS_DIR" ]]; then
+    STACK_NAMES="$(
+      {
+        ls -1 "$STACKS_DIR" 2>/dev/null || true
+        [[ -n "$LEGACY_STACKS_DIR" ]] && ls -1 "$LEGACY_STACKS_DIR" 2>/dev/null || true
+      } | sort -u
+    )"
+    if [[ -z "$STACK_NAMES" ]]; then
+      echo "${STACKS_PREFIX}No stacks found | color=$GRAY"
+    fi
+    for s in $STACK_NAMES; do
+      env_file="$(resolve_stack_env_file "$s")"
+      [[ -f "$env_file" ]] || continue
+
+      # Ports may be ephemeral (runtime-only). Do not skip stacks if the env file does not pin a port.
+      port="$(resolve_stack_server_port "$s" "$env_file")"
+
+      server_component="$(dotenv_get "$env_file" "HAPPY_STACKS_SERVER_COMPONENT")"
+      [[ -z "$server_component" ]] && server_component="$(dotenv_get "$env_file" "HAPPY_LOCAL_SERVER_COMPONENT")"
+      [[ -n "$server_component" ]] || server_component="happy-server-light"
+
+      base_dir="$(resolve_stack_base_dir "$s" "$env_file")"
+      cli_home_dir="$(resolve_stack_cli_home_dir "$s" "$env_file")"
+      label="$(resolve_stack_label "$s")"
+
+      COLLECT="$(collect_stack_status "$port" "$cli_home_dir" "$label" "$base_dir")"
+      IFS=$'\t' read -r LEVEL SERVER_STATUS SERVER_PID SERVER_METRICS DAEMON_STATUS DAEMON_PID DAEMON_METRICS DAEMON_UPTIME LAST_HEARTBEAT LAUNCHAGENT_STATUS AUTOSTART_PID AUTOSTART_METRICS <<<"$COLLECT"
+      for v in SERVER_PID SERVER_METRICS DAEMON_PID DAEMON_METRICS DAEMON_UPTIME LAST_HEARTBEAT AUTOSTART_PID AUTOSTART_METRICS; do
+        if [[ "${!v}" == "-" ]]; then
+          printf -v "$v" '%s' ""
+        fi
+      done
+
+      render_stack_overview_item "Stack: $s" "$LEVEL" "$STACKS_PREFIX"
+      export STACK_LEVEL="$LEVEL"
+      render_stack_info "${STACKS_PREFIX}--" "$s" "$port" "$server_component" "$base_dir" "$cli_home_dir" "$label" "$env_file" ""
+      render_component_server "${STACKS_PREFIX}--" "$s" "$port" "$server_component" "$SERVER_STATUS" "$SERVER_PID" "$SERVER_METRICS" "" "$label"
+      render_component_daemon "${STACKS_PREFIX}--" "$DAEMON_STATUS" "$DAEMON_PID" "$DAEMON_METRICS" "$DAEMON_UPTIME" "$LAST_HEARTBEAT" "$cli_home_dir/daemon.state.json" "$s"
+      render_component_autostart "${STACKS_PREFIX}--" "$s" "$label" "$LAUNCHAGENT_STATUS" "$AUTOSTART_PID" "$AUTOSTART_METRICS" "$base_dir/logs"
+      render_component_tailscale "${STACKS_PREFIX}--" "$s" ""
+      render_components_menu "${STACKS_PREFIX}--" "stack" "$s" "$env_file"
     done
+  else
+    echo "${STACKS_PREFIX}No stacks dir found at: $(shorten_path "$STACKS_DIR" 52) | color=$GRAY"
+  fi
 
-    render_stack_overview_item "Stack: $s" "$LEVEL" ""
-    export STACK_LEVEL="$LEVEL"
-    render_stack_info "--" "$s" "$port" "$server_component" "$base_dir" "$cli_home_dir" "$label" "$env_file" ""
-    render_component_server "--" "$s" "$port" "$server_component" "$SERVER_STATUS" "$SERVER_PID" "$SERVER_METRICS" "" "$label"
-    render_component_daemon "--" "$DAEMON_STATUS" "$DAEMON_PID" "$DAEMON_METRICS" "$DAEMON_UPTIME" "$LAST_HEARTBEAT" "$cli_home_dir/daemon.state.json" "$s"
-    render_component_autostart "--" "$s" "$label" "$LAUNCHAGENT_STATUS" "$AUTOSTART_PID" "$AUTOSTART_METRICS" "$base_dir/logs"
-    render_component_tailscale "--" "$s" ""
-    render_components_menu "--" "stack" "$s" "$env_file"
-  done
-else
-  echo "No stacks dir found at: $(shorten_path "$STACKS_DIR" 52) | color=$GRAY"
-fi
-
-echo "---"
-render_components_menu "" "main" "main" "$MAIN_ENV_FILE"
+  echo "---"
+  render_components_menu "" "main" "main" "$MAIN_ENV_FILE"
 
-echo "Worktrees | sfimage=arrow.triangle.branch"
-if [[ -z "$PNPM_BIN" ]]; then
-  echo "--⚠️ happys not found (run: npx happy-stacks init, or install happy-stacks globally)"
-else
-  HAPPYS_TERM="$HAPPY_LOCAL_DIR/extras/swiftbar/happys-term.sh"
-  echo "--Use (interactive) | bash=$HAPPYS_TERM param1=wt param2=use param3=--interactive dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
-  echo "--New (interactive) | bash=$HAPPYS_TERM param1=wt param2=new param3=--interactive dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
-  echo "--PR worktree (prompt) | bash=$HAPPY_LOCAL_DIR/extras/swiftbar/wt-pr.sh dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
-  echo "--Sync mirrors (all) | bash=$PNPM_BIN param1=wt param2=sync-all dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
-  echo "--Update all (dry-run) | bash=$HAPPYS_TERM param1=wt param2=update-all param3=--dry-run dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
-  echo "--Update all (apply) | bash=$PNPM_BIN param1=wt param2=update-all dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
-fi
+  echo "Worktrees | sfimage=arrow.triangle.branch"
+  if [[ -z "$PNPM_BIN" ]]; then
+    echo "--⚠️ happys not found (run: npx happy-stacks setup)"
+  else
+    HAPPYS_TERM="$HAPPY_LOCAL_DIR/extras/swiftbar/happys-term.sh"
+    echo "--Use (interactive) | bash=$HAPPYS_TERM param1=wt param2=use param3=--interactive dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
+    echo "--New (interactive) | bash=$HAPPYS_TERM param1=wt param2=new param3=--interactive dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
+    echo "--PR worktree (prompt) | bash=$HAPPY_LOCAL_DIR/extras/swiftbar/wt-pr.sh dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
+    echo "--Sync mirrors (all) | bash=$PNPM_BIN param1=wt param2=sync-all dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
+    echo "--Update all (dry-run) | bash=$HAPPYS_TERM param1=wt param2=update-all param3=--dry-run dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
+    echo "--Update all (apply) | bash=$PNPM_BIN param1=wt param2=update-all dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
+  fi
 
-echo "---"
-echo "Setup / Tools"
-if [[ -z "$PNPM_BIN" ]]; then
-  echo "--⚠️ happys not found (run: npx happy-stacks init, or install happy-stacks globally)"
-else
-  HAPPYS_TERM="$HAPPY_LOCAL_DIR/extras/swiftbar/happys-term.sh"
-  echo "--Bootstrap (clone/install) | bash=$HAPPYS_TERM param1=bootstrap dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
-  echo "--CLI link (install happy wrapper) | bash=$HAPPYS_TERM param1=cli:link dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
-  echo "--Mobile dev helper | bash=$HAPPYS_TERM param1=mobile dir=$HAPPY_LOCAL_DIR terminal=false"
+  echo "---"
+  echo "Setup / Tools"
+  if [[ -z "$PNPM_BIN" ]]; then
+    echo "--⚠️ happys not found (run: npx happy-stacks setup)"
+  else
+    HAPPYS_TERM="$HAPPY_LOCAL_DIR/extras/swiftbar/happys-term.sh"
+    echo "--Setup (guided) | bash=$HAPPYS_TERM param1=setup dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
+    echo "--Bootstrap (clone/install) | bash=$HAPPYS_TERM param1=bootstrap dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
+    echo "--CLI link (install happy wrapper) | bash=$HAPPYS_TERM param1=cli:link dir=$HAPPY_LOCAL_DIR terminal=false refresh=true"
+    echo "--Mobile dev helper | bash=$HAPPYS_TERM param1=mobile dir=$HAPPY_LOCAL_DIR terminal=false"
+  fi
 fi
 
 echo "---"