brainlayer 1.3.0__tar.gz → 1.4.1__tar.gz

{brainlayer-1.3.0 → brainlayer-1.4.1}/.gitignore

@@ -29,6 +29,9 @@ htmlcov/
 *.db-wal
 *.db-shm
 data/
+!src/brainlayer/data/
+!src/brainlayer/data/sandbox_seeds/
+!src/brainlayer/data/sandbox_seeds/*.json
 
 # Secrets
 .env

{brainlayer-1.3.0 → brainlayer-1.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: brainlayer
-Version: 1.3.0
+Version: 1.4.1
 Summary: Persistent memory MCP server for AI agents — 13 tools, semantic search, knowledge graph, on-device SQLite
 Project-URL: Homepage, https://brainlayer.etanheyman.com
 Project-URL: Repository, https://github.com/EtanHey/brainlayer

{brainlayer-1.3.0 → brainlayer-1.4.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "brainlayer"
-version = "1.3.0"
+version = "1.4.1"
 description = "Persistent memory MCP server for AI agents — 13 tools, semantic search, knowledge graph, on-device SQLite"
 license = {text = "Apache-2.0"}
 readme = "README.md"
@@ -97,6 +97,7 @@ Issues = "https://github.com/EtanHey/brainlayer/issues"
 [project.scripts]
 brainlayer = "brainlayer.cli:app"
 brainlayer-mcp = "brainlayer.mcp:serve"
+brainlayer-mcp-stdio-bridge = "brainlayer.mcp_stdio_bridge:main"
 
 [build-system]
 requires = ["hatchling"]
@@ -129,6 +130,15 @@ exclude = [
 ]
 
 [tool.hatch.build.targets.sdist]
+only-include = [
+    "src/brainlayer",
+    "scripts/launchd",
+    "README.md",
+    "LICENSE",
+    "server.json",
+]
 exclude = [
+    "docs.local/**",
+    "brain-bar/docs.local/**",
     "src/brainlayer/dashboard/**",
 ]

{brainlayer-1.3.0 → brainlayer-1.4.1}/scripts/launchd/brainlayer-env-run.sh

@@ -3,6 +3,7 @@
 set -euo pipefail
 
 ENV_FILE="${BRAINLAYER_ENV_FILE:-$HOME/.config/brainlayer/brainlayer.env}"
+export PATH="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$HOME/.local/bin:${PATH:-}"
 
 if [ ! -f "$ENV_FILE" ]; then
     echo "ERROR: BrainLayer env file not found at $ENV_FILE" >&2
@@ -22,10 +23,66 @@ if [ -n "$(find "$ENV_FILE" -prune -perm -0002 -print 2>/dev/null)" ]; then
     exit 78
 fi
 
-set -a
-# shellcheck disable=SC1090
-source "$ENV_FILE"
-set +a
+valid_env_key() {
+    case "$1" in
+        ""|[0-9]*|*[!A-Za-z0-9_]*)
+            return 1
+            ;;
+        *)
+            return 0
+            ;;
+    esac
+}
+
+strip_matching_quotes() {
+    local value="$1"
+    if [[ "$value" == \"*\" && "$value" == *\" ]]; then
+        printf '%s' "${value:1:${#value}-2}"
+    elif [[ "$value" == \'*\' && "$value" == *\' ]]; then
+        printf '%s' "${value:1:${#value}-2}"
+    else
+        printf '%s' "$value"
+    fi
+}
+
+load_simple_env_file() {
+    local raw_line line key value
+    while IFS= read -r raw_line || [ -n "$raw_line" ]; do
+        line="${raw_line#"${raw_line%%[![:space:]]*}"}"
+        line="${line%"${line##*[![:space:]]}"}"
+        case "$line" in
+            ""|\#*)
+                continue
+                ;;
+            export\ *)
+                line="${line#export }"
+                ;;
+        esac
+        case "$line" in
+            *=*) ;;
+            *) continue ;;
+        esac
+        key="${line%%=*}"
+        value="${line#*=}"
+        key="${key%"${key##*[![:space:]]}"}"
+        value="${value#"${value%%[![:space:]]*}"}"
+        if ! valid_env_key "$key"; then
+            continue
+        fi
+        case "$value" in
+            *'$('*|*'`'*)
+                continue
+                ;;
+        esac
+        export "$key=$(strip_matching_quotes "$value")"
+    done < "$ENV_FILE"
+}
+
+env_file_declares_google_key() {
+    grep -Eq '^[[:space:]]*(export[[:space:]]+)?GOOGLE(_GENERATIVE_AI)?_API_KEY[[:space:]]*=' "$ENV_FILE"
+}
+
+load_simple_env_file
 
 is_false() {
     case "${1:-}" in
@@ -68,7 +125,9 @@ if [ "${BRAINLAYER_SKIP_DISABLE_GATES:-0}" != "1" ]; then
     fi
 fi
 
-if [ "${BRAINLAYER_REQUIRE_GOOGLE_API_KEY:-0}" = "1" ] && [ -z "${GOOGLE_API_KEY:-${GOOGLE_GENERATIVE_AI_API_KEY:-}}" ]; then
+if [ "${BRAINLAYER_REQUIRE_GOOGLE_API_KEY:-0}" = "1" ] \
+    && [ -z "${GOOGLE_API_KEY:-${GOOGLE_GENERATIVE_AI_API_KEY:-}}" ] \
+    && ! env_file_declares_google_key; then
     echo "ERROR: GOOGLE_API_KEY not set by $ENV_FILE" >&2
     exit 78
 fi

{brainlayer-1.3.0 → brainlayer-1.4.1}/scripts/launchd/com.brainlayer.drain.plist

@@ -25,13 +25,9 @@
 		<string>__BRAINLAYER_ENV_FILE__</string>
 		<key>BRAINLAYER_LAUNCHD_SERVICE</key>
 		<string>drain</string>
-		<!-- Write chunks WITHOUT computing embeddings inside the drain's write
-		     transaction. Inline embedding lengthens the write-lock hold time and,
-		     under multi-writer contention (BrainBar/daemon/hybrid/watcher), starves
-		     the drain on SQLITE_BUSY so the realtime queue backs up. Vectors are
-		     backfilled out-of-band by enrichment/hotlane. (M1/throughput fix.) -->
-		<key>BRAINLAYER_DRAIN_EMBED</key>
-		<string>0</string>
+		<!-- Production leaves drain embedding enabled. Embeddings are precomputed
+		     before BEGIN IMMEDIATE, so vector coverage does not depend on hotlane
+		     liveness and the write-lock window stays bounded. -->
 	</dict>
 	<key>StandardOutPath</key>
 	<string>__HOME__/Library/Logs/brainlayer/drain.out.log</string>

{brainlayer-1.3.0 → brainlayer-1.4.1}/scripts/launchd/com.brainlayer.enrichment.plist

@@ -30,7 +30,9 @@
 		<key>BRAINLAYER_STALL_TIMEOUT</key>
 		<string>300</string>
 		<key>BRAINLAYER_ENRICHMENT_QUEUE_WRITES</key>
-		<string>0</string>
+		<string>1</string>
+		<key>BRAINLAYER_ENRICH_IDLE_BACKLOG</key>
+		<string>1</string>
 		<key>BRAINLAYER_ENV_FILE</key>
 		<string>__BRAINLAYER_ENV_FILE__</string>
 		<key>BRAINLAYER_REQUIRE_GOOGLE_API_KEY</key>

brainlayer-1.4.1/scripts/launchd/com.brainlayer.hotlane-brainbar.plist

@@ -0,0 +1,74 @@
+<?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.brainlayer.hotlane-brainbar</string>
+	<key>ProgramArguments</key>
+	<array>
+		<string>__BRAINLAYER_ENV_RUN__</string>
+		<string>__BRAINLAYER_PYTHON__</string>
+		<string>__BRAINLAYER_DIR__/scripts/hotlane_brainbar_daemon.py</string>
+		<string>--interval</string>
+		<string>1.0</string>
+		<string>--recent-limit</string>
+		<string>5</string>
+		<string>--backlog-interval</string>
+		<string>10.0</string>
+		<string>--backlog-batch</string>
+		<string>4</string>
+		<string>--enrich-interval</string>
+		<string>10.0</string>
+		<string>--enrich-limit</string>
+		<string>0</string>
+		<string>--enrich-since-hours</string>
+		<string>87600</string>
+	</array>
+	<key>WorkingDirectory</key>
+	<string>__BRAINLAYER_DIR__</string>
+	<key>KeepAlive</key>
+	<true/>
+	<key>StandardOutPath</key>
+	<string>__HOME__/Library/Logs/brainlayer/hotlane-brainbar.out.log</string>
+	<key>StandardErrorPath</key>
+	<string>__HOME__/Library/Logs/brainlayer/hotlane-brainbar.err.log</string>
+	<key>EnvironmentVariables</key>
+	<dict>
+		<key>PATH</key>
+		<string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:__HOME__/.local/bin</string>
+		<key>PYTHONUNBUFFERED</key>
+		<string>1</string>
+		<key>BRAINLAYER_ENV_FILE</key>
+		<string>__BRAINLAYER_ENV_FILE__</string>
+		<key>BRAINLAYER_REQUIRE_GOOGLE_API_KEY</key>
+		<string>1</string>
+		<key>BRAINLAYER_REPO_ROOT</key>
+		<string>__BRAINLAYER_DIR__</string>
+		<key>BRAINLAYER_GEMINI_SERVICE_TIER</key>
+		<string>flex</string>
+		<key>BRAINLAYER_ENRICH_CONCURRENCY</key>
+		<string>4</string>
+		<key>BRAINLAYER_ENRICH_RATE</key>
+		<string>15</string>
+		<key>BRAINLAYER_LAUNCHD_SERVICE</key>
+		<string>hotlane-brainbar</string>
+	</dict>
+	<key>RunAtLoad</key>
+	<true/>
+	<key>ThrottleInterval</key>
+	<integer>5</integer>
+	<key>Nice</key>
+	<integer>10</integer>
+	<key>ProcessType</key>
+	<string>Background</string>
+	<key>ExitTimeOut</key>
+	<integer>30</integer>
+	<key>LowPriorityIO</key>
+	<true/>
+	<key>SoftResourceLimits</key>
+	<dict>
+		<key>NumberOfFiles</key>
+		<integer>4096</integer>
+	</dict>
+</dict>
+</plist>

{brainlayer-1.3.0 → brainlayer-1.4.1}/scripts/launchd/install.sh

@@ -16,19 +16,49 @@
 #   ./scripts/launchd/install.sh jsonl-backup # Install daily JSONL backup only
 #   ./scripts/launchd/install.sh maintenance  # Install recurring maintenance jobs
 #   ./scripts/launchd/install.sh health-check # Install stability health check only
+#   ./scripts/launchd/install.sh hotlane      # Install BrainBar hotlane embed/enrich daemon only
 #   ./scripts/launchd/install.sh remove       # Unload and remove all
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+stable_brainlayer_path() {
+    local value="${1:-}"
+    local prefix
+    local after_cellar
+    local after_version
+
+    if [ -z "$value" ]; then
+        printf "%s" "$value"
+        return 0
+    fi
+
+    case "$value" in
+        */Cellar/brainlayer/*)
+            prefix="${value%%/Cellar/brainlayer/*}"
+            after_cellar="${value#*/Cellar/brainlayer/}"
+            after_version="${after_cellar#*/}"
+            if [ "$after_version" = "$after_cellar" ]; then
+                printf "%s/opt/brainlayer" "$prefix"
+            else
+                printf "%s/opt/brainlayer/%s" "$prefix" "$after_version"
+            fi
+            ;;
+        *)
+            printf "%s" "$value"
+            ;;
+    esac
+}
+
 LAUNCH_DIR="$HOME/Library/LaunchAgents"
 LOG_DIR="$HOME/Library/Logs"
 BRAINLAYER_LOG_DIR="$HOME/.local/share/brainlayer/logs"
 BRAINLAYER_LIB_DIR="$HOME/.local/lib/brainlayer"
-BRAINLAYER_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
-BRAINLAYER_LAUNCHD_DIR="${BRAINLAYER_LAUNCHD_DIR:-$SCRIPT_DIR}"
-BRAINLAYER_BIN="${BRAINLAYER_BIN:-$(which brainlayer 2>/dev/null || echo "$HOME/.local/bin/brainlayer")}"
-PYTHON_BIN="${PYTHON_BIN:-$(command -v python3)}"
-BRAINLAYER_PYTHON="${BRAINLAYER_PYTHON:-$PYTHON_BIN}"
+BRAINLAYER_DIR="$(stable_brainlayer_path "$(cd "$SCRIPT_DIR/../.." && pwd)")"
+BRAINLAYER_LAUNCHD_DIR="$(stable_brainlayer_path "${BRAINLAYER_LAUNCHD_DIR:-$SCRIPT_DIR}")"
+BRAINLAYER_BIN="$(stable_brainlayer_path "${BRAINLAYER_BIN:-$(which brainlayer 2>/dev/null || echo "$HOME/.local/bin/brainlayer")}")"
+PYTHON_BIN="$(stable_brainlayer_path "${PYTHON_BIN:-$(command -v python3)}")"
+BRAINLAYER_PYTHON="$(stable_brainlayer_path "${BRAINLAYER_PYTHON:-$PYTHON_BIN}")"
 BRAINLAYER_ENV_FILE="${BRAINLAYER_ENV_FILE:-$HOME/.config/brainlayer/brainlayer.env}"
 BRAINLAYER_ENV_RUN="$BRAINLAYER_LIB_DIR/brainlayer-env-run.sh"
 
@@ -56,7 +86,7 @@ install_env_runner() {
         return 1
     fi
 
-    install -m 0755 "$src" "$BRAINLAYER_ENV_RUN"
+    install -m 0755 "$src" "$BRAINLAYER_ENV_RUN" || return 1
     echo "Installed: $BRAINLAYER_ENV_RUN"
 }
 
@@ -107,10 +137,33 @@ load_plist() {
     local name="$1"
     local dst="$LAUNCH_DIR/com.brainlayer.${name}.plist"
     local label="com.brainlayer.${name}"
-    launchctl enable "gui/$UID/$label"
+    local enable_error=""
+    local retry_enable_after_bootstrap=0
     launchctl bootout "gui/$UID/$label" 2>/dev/null || true
-    launchctl bootstrap "gui/$UID" "$dst"
-    launchctl print "gui/$UID/$label" >/dev/null
+    if ! enable_error="$(launchctl enable "gui/$UID/$label" 2>&1)"; then
+        if printf "%s" "$enable_error" | grep -qi "could not find service"; then
+            echo "WARN: launchctl enable could not find $label before bootstrap; retrying after bootstrap" >&2
+            retry_enable_after_bootstrap=1
+        else
+            printf "%s\n" "$enable_error" >&2
+            echo "ERROR: launchctl enable failed for $label" >&2
+            return 1
+        fi
+    fi
+    if ! launchctl bootstrap "gui/$UID" "$dst"; then
+        echo "ERROR: launchctl bootstrap failed for $label" >&2
+        return 1
+    fi
+    if [ "$retry_enable_after_bootstrap" -ne 0 ]; then
+        if ! launchctl enable "gui/$UID/$label"; then
+            echo "ERROR: launchctl enable failed for $label after bootstrap" >&2
+            return 1
+        fi
+    fi
+    if ! launchctl print "gui/$UID/$label" >/dev/null; then
+        echo "ERROR: launchctl print failed for $label after bootstrap" >&2
+        return 1
+    fi
     echo "  Loaded: com.brainlayer.${name}"
 }
 
@@ -131,11 +184,11 @@ install_plist() {
         return 1
     fi
 
-    install_env_runner
-    verify_config_file
+    install_env_runner || return 1
+    verify_config_file || return 1
 
     if [ "$name" = "enrichment" ] || [ "$name" = "enrich" ]; then
-        verify_gemini_env_file
+        verify_gemini_env_file || return 1
     fi
 
     # Replace placeholders
@@ -149,12 +202,31 @@ install_plist() {
         -e "s|__REPO_ROOT__|$BRAINLAYER_DIR|g" \
         -e "s|__BRAINLAYER_ENV_FILE__|$BRAINLAYER_ENV_FILE|g" \
         -e "s|__BRAINLAYER_ENV_RUN__|$BRAINLAYER_ENV_RUN|g" \
-        "$src" > "$dst"
+        "$src" > "$dst" || return 1
 
     echo "Installed: $dst"
     echo "  Logs: $LOG_DIR/ and $BRAINLAYER_LOG_DIR/"
 
-    load_plist "$name"
+    if ! load_plist "$name"; then
+        return 1
+    fi
+}
+
+install_many() {
+    local failures=0
+    local name
+
+    for name in "$@"; do
+        if ! install_plist "$name"; then
+            echo "ERROR: failed to install/load com.brainlayer.${name}" >&2
+            failures=$((failures + 1))
+        fi
+    done
+
+    if [ "$failures" -ne 0 ]; then
+        echo "ERROR: failed to install/load $failures launchd service(s)" >&2
+        return 1
+    fi
 }
 
 install_backup_script() {
@@ -167,11 +239,11 @@ install_backup_script() {
         return 1
     fi
 
-    escaped_brainlayer_dir="$(printf '%s' "$BRAINLAYER_DIR" | sed 's/[\\&|]/\\&/g')"
+    escaped_brainlayer_dir="$(printf '%s' "$BRAINLAYER_DIR" | sed 's/[\\&|]/\\&/g')" || return 1
     sed \
         -e "s|__BRAINLAYER_DIR_VALUE__|$escaped_brainlayer_dir|g" \
-        "$src" > "$dst"
-    chmod 755 "$dst"
+        "$src" > "$dst" || return 1
+    chmod 755 "$dst" || return 1
     echo "Installed: $dst"
 }
 
@@ -185,11 +257,11 @@ install_jsonl_backup_script() {
         return 1
     fi
 
-    escaped_brainlayer_dir="$(printf '%s' "$BRAINLAYER_DIR" | sed 's/[\\&|]/\\&/g')"
+    escaped_brainlayer_dir="$(printf '%s' "$BRAINLAYER_DIR" | sed 's/[\\&|]/\\&/g')" || return 1
     sed \
         -e "s|__BRAINLAYER_DIR_VALUE__|$escaped_brainlayer_dir|g" \
-        "$src" > "$dst"
-    chmod 755 "$dst"
+        "$src" > "$dst" || return 1
+    chmod 755 "$dst" || return 1
     echo "Installed: $dst"
 }
 
@@ -249,32 +321,52 @@ case "${1:-all}" in
         install_plist maintenance-weekly
         ;;
     maintenance)
-        install_plist maintenance-nightly
-        install_plist maintenance-weekly
+        install_many maintenance-nightly maintenance-weekly
         ;;
     health-check)
         install_plist health-check
         ;;
+    hotlane|hotlane-brainbar)
+        verify_gemini_env_file
+        install_plist hotlane-brainbar
+        ;;
     all)
         install_env_runner
         verify_config_file
         verify_gemini_env_file
-        install_plist index
-        install_plist drain
-        install_plist watch
-        install_plist enrichment
-        install_plist decay
-        install_plist wal-checkpoint
-        install_plist repair-fts
-        install_backup_script
-        install_plist backup-daily
-        install_jsonl_backup_script
-        install_plist jsonl-backup
-        install_plist maintenance-nightly
-        install_plist maintenance-weekly
-        install_plist health-check
-        # Remove old enrich plist if present
-        remove_plist enrich 2>/dev/null || true
+        failures=0
+        enrichment_ok=0
+        if ! install_many index drain watch hotlane-brainbar; then
+            failures=1
+        fi
+        if install_plist enrichment; then
+            enrichment_ok=1
+        else
+            failures=1
+        fi
+        if ! install_many decay wal-checkpoint repair-fts; then
+            failures=1
+        fi
+        if ! install_backup_script; then
+            failures=1
+        elif ! install_many backup-daily; then
+            failures=1
+        fi
+        if ! install_jsonl_backup_script; then
+            failures=1
+        elif ! install_many jsonl-backup; then
+            failures=1
+        fi
+        if ! install_many maintenance-nightly maintenance-weekly health-check; then
+            failures=1
+        fi
+        # Remove old enrich plist only after the replacement enrichment service loads.
+        if [ "$enrichment_ok" -eq 1 ]; then
+            remove_plist enrich 2>/dev/null || true
+        fi
+        if [ "$failures" -ne 0 ]; then
+            exit 1
+        fi
         ;;
     remove)
         remove_plist index
@@ -290,11 +382,12 @@ case "${1:-all}" in
         remove_plist maintenance-nightly 2>/dev/null || true
         remove_plist maintenance-weekly 2>/dev/null || true
         remove_plist health-check 2>/dev/null || true
+        remove_plist hotlane-brainbar 2>/dev/null || true
         rm -f "$BRAINLAYER_LIB_DIR/backup-daily.sh"
         rm -f "$BRAINLAYER_LIB_DIR/jsonl-backup.sh"
         ;;
     *)
-        echo "Usage: $0 [index|watch|enrich|enrichment|decay|drain|repair-fts|load [name]|unload [name]|checkpoint|backup|jsonl-backup|maintenance|maintenance-nightly|maintenance-weekly|health-check|all|remove]"
+        echo "Usage: $0 [index|watch|enrich|enrichment|decay|drain|hotlane|repair-fts|load [name]|unload [name]|checkpoint|backup|jsonl-backup|maintenance|maintenance-nightly|maintenance-weekly|health-check|all|remove]"
         exit 1
         ;;
 esac

{brainlayer-1.3.0 → brainlayer-1.4.1}/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.etanhey/brainlayer",
   "title": "BrainLayer",
   "description": "Persistent memory for AI agents — local-first semantic search, knowledge graph, and 12 MCP tools with ToolAnnotations. One SQLite file, no cloud, no API keys.",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "websiteUrl": "https://brainlayer.etanheyman.com",
   "repository": {
     "url": "https://github.com/EtanHey/brainlayer",
@@ -14,7 +14,7 @@
       "registryType": "pypi",
       "registryBaseUrl": "https://pypi.org",
       "identifier": "brainlayer",
-      "version": "1.3.0",
+      "version": "1.4.1",
       "runtimeHint": "pipx",
       "transport": {
         "type": "stdio"

{brainlayer-1.3.0 → brainlayer-1.4.1}/src/brainlayer/__init__.py

@@ -1,3 +1,3 @@
 """BrainLayer (זיכרון) - Local knowledge pipeline for Claude Code conversations."""
 
-__version__ = "1.3.0"
+__version__ = "1.4.1"

brainlayer-1.4.1/src/brainlayer/alarm.py

@@ -0,0 +1,115 @@
+"""Loud persistent alarms for never-silent degradation paths."""
+
+from __future__ import annotations
+
+import json
+import logging
+import sys
+import threading
+from typing import Any, NoReturn
+
+logger = logging.getLogger(__name__)
+
+ALARM_DATASET = "brainlayer-alarms"
+_TELEMETRY_JOIN_TIMEOUT_S = 0.05
+
+
+class BrainLayerAlarm(BaseException):
+    """Alarm that bypasses broad ``except Exception`` handlers."""
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        context: dict[str, Any] | None = None,
+        *,
+        severity: str = "fatal",
+        exit_code: int = 1,
+    ) -> None:
+        super().__init__(f"{code}: {message}")
+        self.code = code
+        self.message = message
+        self.context = dict(context or {})
+        self.severity = severity
+        self.exit_code = exit_code
+
+    @property
+    def details(self) -> dict[str, Any]:
+        return self.context
+
+    def to_event(self) -> dict[str, Any]:
+        return {
+            "_type": "alarm",
+            "code": self.code,
+            "severity": self.severity,
+            "message": self.message,
+            "context": self.context,
+            "exit_code": self.exit_code,
+        }
+
+    def human_message(self) -> str:
+        context = ""
+        if self.context:
+            context = f" context={json.dumps(self.context, sort_keys=True, default=str)}"
+        return f"BRAINLAYER_ALARM {self.code}: {self.message}{context}"
+
+
+def build_alarm(
+    code: str,
+    message: str,
+    context: dict[str, Any] | None = None,
+    *,
+    severity: str = "fatal",
+    exit_code: int = 1,
+) -> BrainLayerAlarm:
+    return BrainLayerAlarm(code, message, context, severity=severity, exit_code=exit_code)
+
+
+def emit_alarm(alarm: BrainLayerAlarm) -> bool:
+    """Emit local loud alarm output and best-effort non-blocking telemetry.
+
+    stderr/logging are the guaranteed fatal alarm paths. Axiom telemetry stays
+    off the caller thread so a stalled network path cannot delay the alarm raise.
+    """
+    human_message = alarm.human_message()
+    logger.critical(human_message)
+    try:
+        print(human_message, file=sys.stderr, flush=True)
+    except Exception as exc:
+        logger.debug("Alarm stderr emit failed: %s", exc)
+
+    result: dict[str, bool] = {"ok": False}
+    event = alarm.to_event()
+
+    def emit_telemetry() -> None:
+        try:
+            from .telemetry import emit
+
+            result["ok"] = emit(ALARM_DATASET, event)
+        except Exception as exc:
+            logger.debug("Alarm telemetry emit failed: %s", exc)
+
+    try:
+        thread = threading.Thread(target=emit_telemetry, name=f"brainlayer-alarm-{alarm.code}", daemon=True)
+        thread.start()
+        thread.join(_TELEMETRY_JOIN_TIMEOUT_S)
+        if thread.is_alive():
+            logger.debug("Alarm telemetry emit still running in background: %s", alarm.code)
+            return True
+        return result["ok"]
+    except Exception as exc:
+        logger.debug("Alarm telemetry dispatch failed: %s", exc)
+        return False
+
+
+def raise_alarm(
+    code: str,
+    message: str,
+    context: dict[str, Any] | None = None,
+    *,
+    severity: str = "fatal",
+    exit_code: int = 1,
+) -> NoReturn:
+    alarm = build_alarm(code, message, context, severity=severity, exit_code=exit_code)
+    emit_alarm(alarm)
+    raise alarm