secondbrain-py 0.2.1__py3-none-any.whl

brain/tags.py

@@ -0,0 +1,56 @@
+"""Tag normalization rules used across brain (DB writes, file writes, ingest).
+
+Single source of truth for the canonical tag form: lowercase
+(``str.casefold`` for proper Unicode handling), hyphen-separated, deduped,
+empty inputs dropped. Every tag-write boundary in the codebase
+(``ingest.apply_tags``, ``vault.frontmatter.rewrite_tags``,
+``vault.sync._coerce_tag_list``, the ``brain backfill normalize-tags``
+subcommand) feeds inputs through :func:`normalize_tags` before persisting,
+so future writes can never re-introduce uppercase / separator / duplicate
+drift.
+"""
+import re
+from collections.abc import Iterable
+
+_SEPARATOR_RE = re.compile(r"[\s_]+")
+_HYPHEN_RUN_RE = re.compile(r"-+")
+
+
+def normalize_tag(tag: str) -> str:
+    """Canonicalize a single tag string.
+
+    Steps, in order:
+
+    1. ``str.strip`` to drop leading/trailing whitespace.
+    2. ``str.casefold`` so Unicode edge cases collapse correctly
+       (German ``ß`` → ``ss``, Greek final sigma → ``σ``, etc.).
+    3. Replace runs of whitespace + underscores with a single hyphen so
+       ``Interview Prep`` and ``interview_prep`` both canonicalize to
+       ``interview-prep``.
+    4. Collapse runs of hyphens to a single hyphen, then strip leading /
+       trailing hyphens — ``"  --foo--  "`` → ``"foo"``.
+
+    An all-whitespace input (or an input that becomes empty after the
+    cleanup, e.g. ``"---"``) returns the empty string. Callers that work
+    with collections should use :func:`normalize_tags` which drops empties
+    automatically.
+    """
+    folded = tag.strip().casefold()
+    hyphenated = _SEPARATOR_RE.sub("-", folded)
+    return _HYPHEN_RUN_RE.sub("-", hyphenated).strip("-")
+
+
+def normalize_tags(tags: Iterable[str]) -> list[str]:
+    """Canonicalize, dedupe, and drop empties from an iterable of tags.
+
+    Order is the first-seen order of the canonicalized form: the first
+    occurrence of each canonical tag wins, later duplicates (regardless of
+    casing or separator variant) are silently dropped. Empty / whitespace-
+    only entries — and entries that canonicalize to the empty string — are
+    dropped.
+
+    The return value is always a fresh ``list[str]``; callers can mutate it
+    safely.
+    """
+    cleaned = (normalize_tag(t) for t in tags)
+    return [t for t in dict.fromkeys(cleaned) if t]

brain/templates/Caddyfile.j2

@@ -0,0 +1,9 @@
+# Jinja variables: wiki_port, vault_path
+:{{ wiki_port }} {
+    root * {{ vault_path }}/.quartz/current
+    file_server
+    encode gzip
+    # ETag-driven reload (P6.1) — keep cache short on the build-id file
+    @buildid path /.build-id
+    header @buildid Cache-Control "max-age=2, must-revalidate"
+}

brain/templates/__init__.py

@@ -0,0 +1 @@
+"""Marker so importlib.resources can resolve this subdirectory in pipx-installed wheels."""

brain/templates/bin/__init__.py

@@ -0,0 +1 @@
+"""Marker so importlib.resources can resolve this subdirectory in pipx-installed wheels."""

brain/templates/bin/_brain-brief-fg.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# One-shot wrapper for the daily brief, intended to run under launchd's
+# StartCalendarInterval (07:00 local). Unlike _brain-watcher-fg / _brain-build-fg
+# this does NOT supervise a long-running daemon and writes no pid file — it runs
+# `brain brief --wiki` once and exits. launchd's StandardOut/ErrorPath capture
+# the digest + any warnings.
+#
+# Env contract:
+#   BRAIN_VAULT_PATH  (default: $HOME/brain-vault) — passed through to brief.
+#   BRAIN_PY          pins the Python interpreter that has `brain` importable
+#                     (exported by the launchd plist); falls back to python3.
+
+set -euo pipefail
+
+# Pick the Python interpreter once. BRAIN_PY wins; otherwise prefer python3.
+if [[ -n "${BRAIN_PY:-}" ]]; then
+    PY="$BRAIN_PY"
+elif command -v python3 >/dev/null 2>&1; then
+    PY="$(command -v python3)"
+else
+    echo "no python interpreter found (set BRAIN_PY=… to override)" >&2
+    exit 1
+fi
+
+exec "$PY" -m brain brief --wiki

brain/templates/bin/_brain-build-fg.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# Foreground wrapper for the Quartz build watcher, intended to run under
+# launchd. Mirrors `_brain-watcher-fg`'s contract — see that file's header
+# for the rationale + pid-file semantics.
+#
+# This wrapper specifically supervises `python -m brain.wiki.build_watcher`,
+# which re-renders the Quartz site into a fresh `<vault>/.quartz/builds/<id>/`
+# and atomically retargets `current/` on every vault change. Pre-launchd it
+# was started via `nohup ... &` from `bin/brain-up`, with the same drift
+# problem (silent death + no supervisor).
+#
+# Env contract:
+#   BRAIN_VAULT_PATH        (default: $HOME/brain-vault) — passed to `--vault`.
+#   BRAIN_WIKI_KEEP_BUILDS  (default: 3) — old build dirs retained per swap.
+#   The wrapper sets BRAIN_WIKI_RELOAD=1 itself, matching the bin/brain-up
+#   invocation, so the LaunchAgent plist doesn't have to know about it.
+
+set -euo pipefail
+
+VAULT="${BRAIN_VAULT_PATH:-$HOME/brain-vault}"
+KEEP="${BRAIN_WIKI_KEEP_BUILDS:-3}"
+# Resolve $BRAIN_HOME from this script's location ($BRAIN_HOME/.shims/ under a
+# pipx install, $repo_root/bin/ in a dev checkout) so the pid file lands in a
+# stable, non-reaped dir. Honor an explicit BRAIN_HOME override if set.
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+BRAIN_HOME_RESOLVED="${BRAIN_HOME:-$( cd "$SCRIPT_DIR/.." && pwd )}"
+# Pid path defaults to $BRAIN_HOME/run/ — NOT /tmp. macOS's tmp_cleaner reaps
+# files left untouched for 3 days; this daemon writes the pid once at launch
+# then runs for weeks, so a /tmp pid file silently vanishes and brain-status
+# misreports the live daemon as stopped. Overridable (unset = unchanged) so
+# tests run this wrapper hermetically against a tmp pid dir.
+BUILD_PID="${BRAIN_BUILD_PID:-$BRAIN_HOME_RESOLVED/run/brain-build.pid}"
+
+# Pick the Python interpreter once. BRAIN_PY (env var) wins; otherwise
+# prefer python3 on PATH. The installed-shim flow (in $BRAIN_HOME/bin/)
+# always has BRAIN_PY exported by the Python launcher in
+# src/brain/bin/_launcher.py — but we keep the python3 fallback for
+# users who invoke the shims directly outside the launcher (e.g. via
+# launchd plists that themselves set PATH but not BRAIN_PY).
+if [[ -n "${BRAIN_PY:-}" ]]; then
+    PY="$BRAIN_PY"
+elif command -v python3 >/dev/null 2>&1; then
+    PY="$(command -v python3)"
+else
+    echo "no python interpreter found (set BRAIN_PY=… to override)" >&2
+    exit 1
+fi
+
+export BRAIN_WIKI_RELOAD=1
+
+mkdir -p "$(dirname "$BUILD_PID")"
+echo "$$" >"$BUILD_PID"
+exec "$PY" -m brain.wiki.build_watcher --vault "$VAULT" --keep "$KEEP"

brain/templates/bin/_brain-watcher-fg.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# Foreground wrapper for the vault sync watcher, intended to run under launchd.
+#
+# Why a wrapper:
+#   The historical `bin/brain-up` flow uses `nohup ... &` to background-spawn
+#   the watcher, then writes the spawned pid into the pid file for
+#   `brain-status` to pick up. That works in a shell session but doesn't
+#   survive the next "what kills my daemons silently?" round (terminal close,
+#   sleep/wake, OOM, …) because nothing supervises the daemon.
+#
+#   This script flips the pattern: it stays in the foreground, writes the
+#   pid file, then `exec`s the watcher so the watcher inherits the same pid.
+#   A LaunchAgent (com.brain.watcher) wraps THIS script with `KeepAlive=true`
+#   so launchd respawns us within `ThrottleInterval` seconds whenever the
+#   underlying watcher dies — no manual `brain-up` after every crash.
+#
+# PID-file contract:
+#   We write `$$` into the pid file ($BRAIN_HOME/run/brain-watch.pid) BEFORE
+#   the exec. `exec` replaces
+#   the current process image but keeps the pid, so the file points at the
+#   still-running watcher. `brain-status`'s `kill -0 $(cat …)` check then
+#   reports "running" exactly as it does for the legacy nohup path. When
+#   launchd kills us out-of-band the file becomes stale; that's fine, the
+#   `kill -0` check fails and the row flips to "stopped".
+#
+# Env contract:
+#   BRAIN_VAULT_PATH  (default: $HOME/brain-vault) — passed to `--vault`.
+#   PATH must include the pipx bin dir (or wherever `brain` is installed)
+#   so `brain` resolves; the LaunchAgent plist's EnvironmentVariables block
+#   sets this explicitly.
+
+set -euo pipefail
+
+VAULT="${BRAIN_VAULT_PATH:-$HOME/brain-vault}"
+
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+PROJECT_ROOT="$( cd "$SCRIPT_DIR/.." && pwd )"
+VENV_BIN="$PROJECT_ROOT/.venv/bin"
+# Pid path defaults to $BRAIN_HOME/run/ — NOT /tmp. macOS's tmp_cleaner reaps
+# files left untouched for 3 days; this daemon writes the pid once at launch
+# then runs for weeks, so a /tmp pid file silently vanishes and brain-status
+# misreports the live daemon as stopped. $BRAIN_HOME resolves to an explicit
+# BRAIN_HOME override if set, else PROJECT_ROOT (== the script's parent: the
+# script lives in $BRAIN_HOME/.shims/ or $repo_root/bin/); kept consistent with
+# the build fg wrapper and brain-{status,down,up}. Overridable (unset =
+# unchanged) so tests run this wrapper hermetically against a tmp pid dir.
+WATCH_PID="${BRAIN_WATCH_PID:-${BRAIN_HOME:-$PROJECT_ROOT}/run/brain-watch.pid}"
+# brain: tests set BRAIN_SKIP_VENV_AUTOLOAD=1 to keep the wrapper from
+# silently prepending the developer's real `.venv/bin` (and thus the real
+# `brain`) ahead of the test stub on PATH. Same shape as the BRAIN_PY
+# override in `bin/brain-up`. In production the variable is unset and the
+# venv prepend just works (for dev-checkout users with a local .venv;
+# pipx-installed users have brain on PATH via the launchd plist already).
+if [[ "${BRAIN_SKIP_VENV_AUTOLOAD:-0}" != "1" && -d "$VENV_BIN" ]]; then
+    export PATH="$VENV_BIN:$PATH"
+fi
+
+if ! command -v brain >/dev/null 2>&1; then
+    echo "brain CLI not on PATH (expected via launchd PATH or local .venv)" >&2
+    exit 1
+fi
+
+mkdir -p "$(dirname "$WATCH_PID")"
+echo "$$" >"$WATCH_PID"
+exec brain vault sync --watch --vault "$VAULT"

brain/templates/bin/brain-down.sh

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+# Stop the second-brain wiki build watcher + sync watcher (blue/green serve edition).
+# Idempotent — safe to re-run.
+#
+# Caddy is intentionally left running: it keeps serving the last-good build
+# from <vault>/.quartz/current so brain.test stays healthy across restarts.
+#
+# Env overrides (default to the production values when unset — production
+# behavior is unchanged unless you explicitly set these; mirrors the
+# BRAIN_LAUNCHCTL / BRAIN_LAUNCHD_DIR pattern below). They exist so the test
+# suite can run this shim HERMETICALLY — pointing the pid files at a tmp dir
+# and the orphan-killer at a stub — so the real `brain-up` watchers on a dev
+# machine are never touched:
+#   BRAIN_WATCH_PID  (default: $BRAIN_HOME/run/brain-watch.pid)
+#   BRAIN_BUILD_PID  (default: $BRAIN_HOME/run/brain-build.pid)
+#   BRAIN_WIKI_PID   (default: $BRAIN_HOME/run/brain-wiki.pid)
+#   BRAIN_PKILL      (default: pkill) — binary used for the orphan sweep
+
+set -euo pipefail
+
+# Resolve $BRAIN_HOME from this script's location ($BRAIN_HOME/.shims/ under a
+# pipx install, $repo_root/bin/ in a dev checkout) so the pid paths match where
+# the fg wrappers write them. Honor an explicit BRAIN_HOME override if set.
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+BRAIN_HOME_RESOLVED="${BRAIN_HOME:-$( cd "$SCRIPT_DIR/.." && pwd )}"
+
+# Pid paths default to $BRAIN_HOME/run/ — NOT /tmp. macOS's tmp_cleaner reaps
+# files left untouched for 3 days, which silently vanishes a long-lived
+# daemon's pid file; $BRAIN_HOME/run/ is not reaped. Must match the fg
+# wrappers' defaults. Overridable (unset = unchanged) for hermetic tests.
+WATCH_PID="${BRAIN_WATCH_PID:-$BRAIN_HOME_RESOLVED/run/brain-watch.pid}"   # `brain vault sync --watch`
+BUILD_PID="${BRAIN_BUILD_PID:-$BRAIN_HOME_RESOLVED/run/brain-build.pid}"   # `python -m brain.wiki.build_watcher`
+WIKI_PID="${BRAIN_WIKI_PID:-$BRAIN_HOME_RESOLVED/run/brain-wiki.pid}"      # legacy: pre-blue/green `npx quartz --serve`
+PKILL="${BRAIN_PKILL:-pkill}"                          # orphan-sweep binary (tests stub it)
+
+LAUNCHD_DIR="${BRAIN_LAUNCHD_DIR:-$HOME/Library/LaunchAgents}"
+LAUNCHCTL="${BRAIN_LAUNCHCTL:-launchctl}"
+
+# brain: if the user installed launchd supervision via
+# `bin/brain-install-launchd`, plain `kill $pid` is ineffective — launchd
+# respawns each daemon within ThrottleInterval seconds. Bootout the
+# LaunchAgents first so the kills below actually stick. We don't remove
+# the .plist files here (that's `bin/brain-uninstall-launchd`'s job);
+# bootout-only means a subsequent `bin/brain-up` won't re-supervise, but
+# `launchctl bootstrap gui/$UID <plist>` (or rerunning the install
+# script) will restore supervision without rewriting the plists.
+bootout_one() {
+    local label="$1"
+    local domain="gui/$UID/${label}"
+    if "$LAUNCHCTL" print "$domain" >/dev/null 2>&1; then
+        "$LAUNCHCTL" bootout "$domain" 2>/dev/null || true
+        echo "unloaded launchd: $domain"
+    fi
+}
+
+bootout_one com.brain.watcher
+bootout_one com.brain.build
+
+stop_one() {
+    local pid_file="$1"
+    local label="$2"
+    if [[ ! -f "$pid_file" ]]; then
+        return 0
+    fi
+    local pid
+    pid=$(cat "$pid_file")
+    if kill -0 "$pid" 2>/dev/null; then
+        kill "$pid" 2>/dev/null || true
+        sleep 1
+        if kill -0 "$pid" 2>/dev/null; then
+            kill -9 "$pid" 2>/dev/null || true
+        fi
+        echo "stopped $label (pid $pid)"
+    fi
+    rm -f "$pid_file"
+}
+
+stop_one "$WATCH_PID" 'watcher (vault sync)'
+stop_one "$BUILD_PID" 'build watcher'
+# Belt-and-suspenders: only stop a legacy wiki pid file if a stale install
+# left one behind. Brand-new clones won't have this file.
+stop_one "$WIKI_PID"  'wiki (legacy quartz --serve)'
+
+# Belt + suspenders: any orphaned processes from prior crashed runs.
+"$PKILL" -f 'brain.wiki.build_watcher' 2>/dev/null || true
+"$PKILL" -f 'brain vault sync --watch' 2>/dev/null || true
+
+echo '🧠 brain is down'
+echo '   (caddy left running — brain.test continues to serve last good build)'

brain/templates/bin/brain-status.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# Report on what the brain is currently running (blue/green serve edition).
+
+set -euo pipefail
+
+VAULT="${BRAIN_VAULT_PATH:-$HOME/brain-vault}"
+QUARTZ_DIR="$VAULT/.quartz"
+PORT="${BRAIN_WIKI_PORT:-8080}"
+URL="http://localhost:$PORT"
+
+# Shim is installed at $BRAIN_HOME/.shims/brain-status, so $BRAIN_HOME is
+# two parent-traversals up (.shims/ → $BRAIN_HOME). Honor an explicit
+# BRAIN_HOME override if the launcher set one.
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+BRAIN_HOME_RESOLVED="${BRAIN_HOME:-$( cd "$SCRIPT_DIR/.." && pwd )}"
+
+# Pid paths default to $BRAIN_HOME/run/ — NOT /tmp. macOS's tmp_cleaner reaps
+# files left untouched for 3 days; the build/watch daemons write their pid file
+# once at launch and then run for weeks, so a /tmp pid file silently vanishes
+# and this very script misreports a live daemon as "stopped". $BRAIN_HOME/run/
+# is not reaped. Overridable (unset = unchanged) so the test suite can run this
+# shim hermetically against a tmp pid dir, never colliding with a live
+# brain-up install on a dev machine.
+WATCH_PID="${BRAIN_WATCH_PID:-$BRAIN_HOME_RESOLVED/run/brain-watch.pid}"
+BUILD_PID="${BRAIN_BUILD_PID:-$BRAIN_HOME_RESOLVED/run/brain-build.pid}"
+WIKI_PID="${BRAIN_WIKI_PID:-$BRAIN_HOME_RESOLVED/run/brain-wiki.pid}"   # legacy quartz --serve install
+# T1.7 plist templates redirect StandardOut to $BRAIN_HOME/logs/com.brain.*.out.log,
+# not the legacy /tmp paths the pre-launchd nohup era used.
+WATCH_LOG="$BRAIN_HOME_RESOLVED/logs/com.brain.watcher.out.log"
+BUILD_LOG="$BRAIN_HOME_RESOLVED/logs/com.brain.build.out.log"
+
+check_one() {
+    local pid_file="$1"
+    local label="$2"
+    local extra="$3"
+    if [[ -f "$pid_file" ]] && kill -0 "$(cat "$pid_file")" 2>/dev/null; then
+        printf '  %-9s ✅ running  pid=%-7s %s\n' "$label:" "$(cat "$pid_file")" "$extra"
+    else
+        printf '  %-9s ⛔ stopped  %s\n' "$label:" "$extra"
+    fi
+}
+
+echo '🧠 brain status'
+check_one "$WATCH_PID" 'watcher' "(logs: $WATCH_LOG)"
+check_one "$BUILD_PID" 'build'   "(logs: $BUILD_LOG)"
+
+# Legacy row — only show if a stale pid file from the pre-blue/green
+# install is still on disk. Helps diagnose half-migrated machines.
+if [[ -f "$WIKI_PID" ]]; then
+    if kill -0 "$(cat "$WIKI_PID")" 2>/dev/null; then
+        printf '  %-9s ⚠️  legacy quartz --serve still running pid=%s — kill with brain-down\n' \
+            'wiki:' "$(cat "$WIKI_PID")"
+    else
+        printf '  %-9s ⛔ stopped (legacy quartz --serve was here — pid file %s)\n' \
+            'wiki:' "$WIKI_PID"
+    fi
+fi
+
+# Current build pointer — what Caddy is serving right now.
+CURRENT="$QUARTZ_DIR/current"
+if [[ -L "$CURRENT" ]]; then
+    target="$(readlink "$CURRENT")"
+    if resolved="$(cd "$CURRENT" 2>/dev/null && pwd -P)"; then
+        if [[ -f "$resolved/.build-id" ]]; then
+            build_id="$(cat "$resolved/.build-id")"
+        else
+            build_id='(no .build-id)'
+        fi
+        printf '  current   → %s\n' "$target"
+        printf '  build-id  %s\n' "$build_id"
+    else
+        printf '  current   ⚠️  symlink dangles → %s\n' "$target"
+    fi
+else
+    printf '  current   ⛔ no symlink at %s (run brain-up to bootstrap)\n' "$CURRENT"
+fi
+
+# Quick health check on the wiki socket — Caddy now answers, not Quartz.
+if curl -fsS -o /dev/null --max-time 2 "$URL/" 2>/dev/null; then
+    echo '  wiki url  reachable ✅'
+else
+    echo '  wiki url  unreachable ⚠️ '
+fi

brain/templates/bin/brain-up.sh

@@ -0,0 +1,221 @@
+#!/usr/bin/env bash
+# Start the second-brain wiki + sync watcher (blue/green serve edition).
+# Idempotent — safe to re-run.
+#
+# Architecture (post blue/green migration + 2026-05-08 launchd handoff):
+#   - Caddy serves <vault>/.quartz/current/ statically on :8080 + brain.test.
+#     This script does NOT spawn Quartz's --serve dev server anymore.
+#   - Watcher A: `brain vault sync --watch` — DB <-> vault mirror.
+#   - Cold start: if <vault>/.quartz/current is missing or unhealthy, run a
+#     synchronous one-shot `python -m brain.wiki.build_swap` so the wiki has
+#     something to serve before Watcher B comes up.
+#   - Watcher B: `python -m brain.wiki.build_watcher` — re-renders the site
+#     into a fresh build dir and atomically retargets `current` on every
+#     vault change.
+#
+# Daemon supervision: BOTH watchers run under launchd via the LaunchAgents
+# installed by `bin/brain-install-launchd` (KeepAlive=true → respawn within
+# ~10s of any death). The pre-launchd nohup paths were removed because
+# they silently lost daemons to terminal close / sleep-wake / unexplained
+# crashes — `brain-status` would just go quiet and the user had to notice.
+# This script delegates to install-launchd unconditionally; install-launchd
+# is idempotent (rewrites + reboots the plists every run, no-ops if already
+# loaded), so re-running brain-up is safe and self-healing if launchd has
+# booted out the agents for any reason.
+#
+# Applies the brain Quartz overlay (`quartz_overrides/`) into the workspace
+# BEFORE the cold-start build so the reload-signal transformer is wired in.
+# Set BRAIN_NO_OVERLAY=1 to skip the overlay (use whatever's already in the
+# workspace).
+#
+# Env overrides:
+#   BRAIN_VAULT_PATH        (default: ~/brain-vault)
+#   BRAIN_WIKI_PORT         (default: 8080 — for the URL we curl/open)
+#   BRAIN_OPEN_BROWSER      (default: 1; set 0 to skip)
+#   BRAIN_NO_OVERLAY        (default: 0; set 1 to skip the overlay step)
+#   BRAIN_WIKI_KEEP_BUILDS  (default: 3 — old build dirs retained per swap)
+#   BRAIN_NO_BUILD_WATCHER  (default: 0; set 1 to skip launchd supervision —
+#                            used by the bin-script tests so they don't
+#                            install LaunchAgents on the developer's
+#                            machine. Name kept for backward compat with
+#                            the pre-launchd nohup era.)
+#   BRAIN_LAUNCHCTL         (default: launchctl on PATH) — passed through
+#                            to install-launchd; tests stub it.
+#   BRAIN_LAUNCHD_DIR       (default: ~/Library/LaunchAgents) — same.
+
+set -euo pipefail
+
+VAULT="${BRAIN_VAULT_PATH:-$HOME/brain-vault}"
+QUARTZ_DIR="$VAULT/.quartz"
+PORT="${BRAIN_WIKI_PORT:-8080}"
+URL="http://localhost:$PORT"
+KEEP="${BRAIN_WIKI_KEEP_BUILDS:-3}"
+
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+# Resolve $BRAIN_HOME from this script's location ($BRAIN_HOME/.shims/ under a
+# pipx install, $repo_root/bin/ in a dev checkout). Honor an explicit
+# BRAIN_HOME override if the launcher set one.
+BRAIN_HOME_RESOLVED="${BRAIN_HOME:-$( cd "$SCRIPT_DIR/.." && pwd )}"
+
+# Pid paths default to $BRAIN_HOME/run/ — NOT /tmp. macOS's tmp_cleaner reaps
+# files left untouched for 3 days, silently vanishing a long-lived daemon's
+# pid file so brain-status misreports it as stopped; $BRAIN_HOME/run/ is not
+# reaped, and must match the fg wrappers' defaults. Log paths keep their legacy
+# /tmp fallback (the launchd plists redirect real output to $BRAIN_HOME/logs/).
+# Overridable (unset = unchanged) so the test suite can run this shim
+# hermetically against a tmp dir, never colliding with a live brain-up install.
+WATCH_PID="${BRAIN_WATCH_PID:-$BRAIN_HOME_RESOLVED/run/brain-watch.pid}"
+WATCH_LOG="${BRAIN_WATCH_LOG:-/tmp/brain-watch.log}"
+BUILD_PID="${BRAIN_BUILD_PID:-$BRAIN_HOME_RESOLVED/run/brain-build.pid}"
+BUILD_LOG="${BRAIN_BUILD_LOG:-/tmp/brain-build.log}"
+
+# Pick the Python interpreter once. BRAIN_PY (env var) wins; otherwise
+# prefer python3 on PATH. The installed-shim flow (in $BRAIN_HOME/bin/)
+# always has BRAIN_PY exported by the Python launcher in
+# src/brain/bin/_launcher.py — but we keep the python3 fallback for
+# users who invoke the shims directly outside the launcher (e.g. via
+# launchd plists that themselves set PATH but not BRAIN_PY).
+if [[ -n "${BRAIN_PY:-}" ]]; then
+    PY="$BRAIN_PY"
+elif command -v python3 >/dev/null 2>&1; then
+    PY="$(command -v python3)"
+else
+    echo "no python interpreter found (set BRAIN_PY=… to override)" >&2
+    exit 1
+fi
+
+apply_overlay() {
+    if [[ "${BRAIN_NO_OVERLAY:-0}" == '1' ]]; then
+        echo 'overlay: skipped (BRAIN_NO_OVERLAY=1)'
+        return 0
+    fi
+    if ! command -v brain >/dev/null 2>&1; then
+        echo 'overlay: skipped (brain CLI not on PATH)'
+        return 0
+    fi
+    # `--no-build` applies the overlay to the workspace without running
+    # `npx quartz build` — the build watcher does its own builds on every
+    # vault change, and we run a cold-start build below if needed.
+    if ! brain vault render --overlay --no-build --vault "$VAULT" 2>&1; then
+        echo 'overlay: failed — wiki will start with whatever is in the workspace' >&2
+        return 0
+    fi
+}
+
+current_healthy() {
+    # Healthy = `current` is a symlink, resolves to a directory, and that
+    # directory contains both `index.html` AND `.build-id`. Anything else
+    # (no symlink, dangling target, empty target, missing `.build-id`)
+    # means we need a cold-start build before the watcher comes up.
+    local cur="$QUARTZ_DIR/current"
+    if [[ ! -L "$cur" ]]; then
+        return 1
+    fi
+    local resolved
+    resolved="$(cd "$cur" 2>/dev/null && pwd -P)" || return 1
+    if [[ -z "$resolved" || ! -d "$resolved" ]]; then
+        return 1
+    fi
+    if [[ ! -f "$resolved/index.html" || ! -f "$resolved/.build-id" ]]; then
+        return 1
+    fi
+    return 0
+}
+
+cold_start_build() {
+    if current_healthy; then
+        echo 'cold-start build: skipping cold-start build (current/ is healthy)'
+        return 0
+    fi
+    if [[ ! -d "$QUARTZ_DIR" ]]; then
+        echo "quartz workspace not found at $QUARTZ_DIR" >&2
+        echo 'set up once with:' >&2
+        echo "  git clone https://github.com/jackyzha0/quartz.git \"$QUARTZ_DIR\"" >&2
+        echo "  cd \"$QUARTZ_DIR\" && npm install" >&2
+        echo "  cp \"$SCRIPT_DIR/../quartz.config.ts\" ./quartz.config.ts  # optional brain-tuned config" >&2
+        return 1
+    fi
+    echo 'cold-start build: running first-time build, this takes ~40s...'
+    local started
+    started="$(date +%s)"
+    if ! BRAIN_WIKI_RELOAD=1 "$PY" -m brain.wiki.build_swap \
+            --vault "$VAULT" --keep "$KEEP"; then
+        echo 'cold-start build: failed — aborting brain-up' >&2
+        return 1
+    fi
+    local elapsed=$(( $(date +%s) - started ))
+    echo "cold-start build: first build done in ${elapsed}s"
+}
+
+ensure_supervised() {
+    # brain (2026-05-08): single source of truth for daemon lifecycle.
+    # `bin/brain-install-launchd` writes both LaunchAgent plists, boots out
+    # any prior incarnation (so the script self-heals if launchd has the
+    # labels in a half-loaded state), and bootstraps them into the
+    # gui/$UID domain. From there on launchd's KeepAlive=true keeps both
+    # daemons alive across crashes, terminal-close, sleep/wake — the very
+    # failure modes the pre-launchd nohup paths used to lose.
+    #
+    # `BRAIN_NO_BUILD_WATCHER=1` keeps its name (back-compat with tests
+    # that use the pre-launchd flag) but its meaning is now "don't install
+    # LaunchAgents during this brain-up run." Tests rely on this so they
+    # don't accidentally drop plists into the developer's
+    # ~/Library/LaunchAgents.
+    if [[ "${BRAIN_NO_BUILD_WATCHER:-0}" == '1' ]]; then
+        echo 'launchd supervision: skipped (BRAIN_NO_BUILD_WATCHER=1)'
+        return 0
+    fi
+    if ! "${BRAIN_INSTALL_LAUNCHD:-brain-install-launchd}"; then
+        echo 'launchd supervision: brain-install-launchd failed — daemons NOT supervised' >&2
+        return 1
+    fi
+}
+
+wait_for_url() {
+    local tries=30
+    while ((tries-- > 0)); do
+        if curl -fsS -o /dev/null "$URL/"; then
+            return 0
+        fi
+        sleep 1
+    done
+    echo "warning: $URL did not respond within 30s — is Caddy running and serving $QUARTZ_DIR/current?" >&2
+    return 1
+}
+
+apply_overlay
+cold_start_build
+ensure_supervised
+
+if [[ "${BRAIN_OPEN_BROWSER:-1}" == '1' ]]; then
+    if wait_for_url; then
+        if command -v open >/dev/null 2>&1; then
+            open "$URL"
+        elif command -v xdg-open >/dev/null 2>&1; then
+            xdg-open "$URL" >/dev/null 2>&1 &
+        fi
+    fi
+fi
+
+WATCH_PID_VALUE='?'
+BUILD_PID_VALUE='?'
+[[ -f "$WATCH_PID" ]] && WATCH_PID_VALUE="$(cat "$WATCH_PID")"
+[[ -f "$BUILD_PID" ]] && BUILD_PID_VALUE="$(cat "$BUILD_PID")"
+
+# brain (2026-05-08): note the supervisor in the report so the user
+# knows their daemons survive terminal close + crashes. The pid '?'
+# fallback handles the brief race between launchctl bootstrap and the
+# wrapper writing the pid file (it's almost always populated by the
+# time wait_for_url succeeds, but the fallback keeps the report
+# readable in the unlikely race).
+SUPERVISOR='launchd (KeepAlive)'
+[[ "${BRAIN_NO_BUILD_WATCHER:-0}" == '1' ]] && SUPERVISOR='unsupervised (BRAIN_NO_BUILD_WATCHER=1)'
+
+echo
+echo '🧠 brain is up:'
+echo "   wiki:       $URL  (also brain.test if Caddy is configured)"
+echo "   vault:      re-syncing on file changes (pid $WATCH_PID_VALUE)"
+echo "   build:      re-rendering on vault changes (pid $BUILD_PID_VALUE)"
+echo "   supervisor: $SUPERVISOR"
+echo '   stop:       brain-down'
+echo '   status:     brain-status'