fix(launchd): revivers and install.sh respect an operator launchctl disable

scripts/launchd/install.sh

@@ -22,9 +22,18 @@
 #   ./scripts/launchd/install.sh p0-counter   # Install daily P0 longitudinal counter only
 #   ./scripts/launchd/install.sh t3-ingest    # Install T3 thread ingestion only
 #   ./scripts/launchd/install.sh remove       # Unload and remove all
+#
+# Operator disable is a standing order. Any reviver of a com.brainlayer.* label
+# (this installer, throughput-watchdog.py, fleet watchdogs) checks
+# `launchctl print-disabled gui/$UID` FIRST and leaves a `=> disabled` label
+# alone: no enable, no bootstrap, no kickstart. Re-arm explicitly with
+# `launchctl enable gui/$UID/<label>`. (w11, 2026-09-02: com.brainlayer.watch
+# was disabled for burning a core and two revivers kept fighting the disable.)
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# Set by load_plist when an operator-disabled label was left alone (callers skip runtime verification).
+LOAD_PLIST_SKIPPED=0
 
 stable_brainlayer_path() {
     local value="${1:-}"
@@ -234,6 +243,22 @@ verify_config_file() {
     fi
 }
 
+# 0 = disabled, 1 = enabled, 2 = state unreadable (callers must fail closed: never enable/bootstrap).
+label_disabled_by_operator() {
+    local label="$1"
+    local listing=""
+    local rc=0
+    listing="$(launchctl print-disabled "gui/$UID" 2>/dev/null)" || rc=$?
+    if [ "$rc" -ne 0 ]; then
+        echo "ERROR: could not read launchd disabled state for $label (launchctl print-disabled rc=$rc); refusing to load" >&2
+        return 2
+    fi
+    case "$listing" in
+        *"\"$label\" => disabled"*|*"\"$label\" => true"*) return 0 ;;
+    esac
+    return 1
+}
+
 load_plist() {
     local name="$1"
     local dst="$LAUNCH_DIR/com.brainlayer.${name}.plist"
@@ -306,6 +331,21 @@ if isinstance(value, (int, float)) and value >= 0:
         echo "ERROR: unload attempts must be a positive integer for $label; got '$unload_attempts'" >&2
         return 1
     fi
+    # Operator-disable check runs only after argument/override validation, so a rejected
+    # invocation exits before any launchctl call.
+    LOAD_PLIST_SKIPPED=0
+    local disabled_rc=0
+    label_disabled_by_operator "$label" || disabled_rc=$?
+    case "$disabled_rc" in
+        0)
+            echo "SKIP: $label disabled by operator (launchctl enable gui/$UID/$label to re-arm)"
+            LOAD_PLIST_SKIPPED=1
+            return 0
+            ;;
+        1) ;;
+        *) return 1 ;;
+    esac
+
     if [ "$supervisor_managed" -eq 1 ]; then
         if initial_output="$(launchctl print "$domain" 2>/dev/null)"; then
             initial_pid="$(
@@ -526,7 +566,7 @@ install_plist() {
     if ! load_plist "$name"; then
         return 1
     fi
-    if [ "$name" = "hotlane-brainbar" ] && ! verify_hotlane_runtime; then
+    if [ "$name" = "hotlane-brainbar" ] && [ "$LOAD_PLIST_SKIPPED" -ne 1 ] && ! verify_hotlane_runtime; then
         return 1
     fi
 }

scripts/launchd/throughput-watchdog.py

@@ -426,6 +426,24 @@ def _launchctl_running(output: str) -> bool:
     return any(line.strip() == "state = running" for line in output.splitlines())
 
 
+def _watch_disabled_state(config: Config, command_runner: CommandRunner) -> str:
+    """An operator `launchctl disable` is a standing order: revivers check print-disabled first.
+
+    Returns "disabled", "enabled", or "unknown". Unknown must be treated as disabled (fail closed).
+    """
+    try:
+        completed = command_runner(["launchctl", "print-disabled", f"gui/{os.getuid()}"])
+    except Exception:
+        return "unknown"
+    if int(getattr(completed, "returncode", 0)) != 0:
+        return "unknown"
+    # Current macOS prints `=> disabled`; older releases print `=> true`. Both mean disabled.
+    needles = {f'"{config.watch_label}" => disabled', f'"{config.watch_label}" => true'}
+    if any(line.strip() in needles for line in str(getattr(completed, "stdout", "") or "").splitlines()):
+        return "disabled"
+    return "enabled"
+
+
 def _restart_watch(
     config: Config,
     command_runner: CommandRunner,
@@ -618,11 +636,17 @@ def run_once(
     elif evidence.pending_files == 0:
         action = "idle"
         stalled_ticks = 0
+    elif (disabled_state := _watch_disabled_state(config, command_runner)) != "enabled":
+        # The queue growing while ingestion is intentionally off is not a stall:
+        # never bootstrap or kickstart a label the operator disabled — or one whose
+        # disabled state could not be read (fail closed).
+        action = "disabled_by_operator" if disabled_state == "disabled" else "disabled_state_unknown"
+        stalled_ticks = 0
     else:
         action = "stalled"
         stalled_ticks = previous_stalled + 1
 
-    if action in {"baseline", "progress", "idle"}:
+    if action in {"baseline", "progress", "idle", "disabled_by_operator", "disabled_state_unknown"}:
         previous_checkpoint_deferred = 0
         checkpoint_deferral_alerted = False
 
@@ -649,6 +673,14 @@ def run_once(
         drained_total_delta=drained_total_delta,
     )
 
+    if result.action == "disabled_state_unknown" and state.get("last_action") != "disabled_state_unknown":
+        # Fail closed, never silently: page once per episode when launchd's disabled state is unreadable.
+        try:
+            alert_fn(config, result)
+        except Exception as exc:
+            result.alert_error = str(exc)
+            print(f"throughput-watchdog disabled-state alert failed: {exc}", file=sys.stderr)
+
     previous_last_progress = state.get("last_progress_epoch")
     if action in {"baseline", "progress", "idle"} or not isinstance(previous_last_progress, int):
         last_progress_epoch = checked_at
@@ -868,7 +900,13 @@ def main(argv: list[str] | None = None) -> int:
             fcntl.flock(lock_file.fileno(), fcntl.LOCK_UN)
 
     print(json.dumps(asdict(result), sort_keys=True) if args.json else f"{result.action}: {result}")
-    return 1 if result.action in {"recovery_failed", "checkpoint_guard_error", "checkpoint_deferral_alert"} else 0
+    failure_actions = {
+        "recovery_failed",
+        "checkpoint_guard_error",
+        "checkpoint_deferral_alert",
+        "disabled_state_unknown",
+    }
+    return 1 if result.action in failure_actions else 0
 
 
 if __name__ == "__main__":

src/brainlayer/launchd_primitive.py

@@ -147,10 +147,13 @@ def is_launchd_label_disabled(
     result = command_runner(["launchctl", "print-disabled", domain])
     if _command_returncode(result) != 0:
         return None
-    match = re.search(rf'["\']?{re.escape(label)}["\']?\s*=>\s*(true|false)', _command_stdout(result), re.I)
+    # launchctl prints `=> disabled|enabled` on current macOS and `=> true|false` on older releases.
+    match = re.search(
+        rf'["\']?{re.escape(label)}["\']?\s*=>\s*(true|false|disabled|enabled)', _command_stdout(result), re.I
+    )
     if match is None:
         return False
-    return match.group(1).lower() == "true"
+    return match.group(1).lower() in {"true", "disabled"}
 
 
 def verify_launchd_label_loaded(

tests/test_installable_build.py

@@ -2817,6 +2817,7 @@ def test_launchd_enable_missing_service_is_retried_after_bootstrap(tmp_path: Pat
     commands = launchctl_log.read_text(encoding="utf-8").splitlines()
     assert result.returncode == 0, result.stdout + result.stderr
     assert [command.split()[0] for command in commands] == [
+        "print-disabled",
         "bootout",
         "print",
         "enable",

tests/test_launchd_hygiene.py

@@ -7,6 +7,7 @@
 import subprocess
 from pathlib import Path
 
+import pytest
 from typer.testing import CliRunner
 
 from brainlayer.cli import app
@@ -565,3 +566,172 @@ def test_launchd_installer_uses_bootstrap_not_legacy_load_unload():
     assert "launchctl print" in load_plist_body
     assert "launchctl load" not in load_plist_body
     assert "launchctl unload" not in load_plist_body
+
+
+@pytest.mark.parametrize("form", ["disabled", "true"])
+@pytest.mark.parametrize("name", ["watch", "hotlane-brainbar", "enrichment"])
+def test_launchd_installer_load_plist_skips_operator_disabled_label(tmp_path, name, form):
+    """An operator `launchctl disable` is a standing order: load_plist must not enable/bootstrap it."""
+    install_source = (REPO_ROOT / "scripts/launchd/install.sh").read_text(encoding="utf-8")
+    load_plist_body = (
+        "load_plist() {" + install_source.split("\nload_plist() {", 1)[1].split("\nunload_plist() {", 1)[0]
+    )
+    helper_name = "label_disabled_by_operator() {"
+    assert helper_name in install_source, "install.sh must define label_disabled_by_operator()"
+    helper_body = helper_name + install_source.split("\n" + helper_name, 1)[1].split("\n}\n", 1)[0] + "\n}\n"
+
+    fake_bin = tmp_path / "bin"
+    fake_bin.mkdir()
+    launchctl_log = tmp_path / "launchctl.log"
+    fake_launchctl = fake_bin / "launchctl"
+    fake_launchctl.write_text(
+        "#!/usr/bin/env bash\n"
+        'printf "%s\\n" "$*" >> "$LAUNCHCTL_LOG"\n'
+        '[ "$1" = "print-disabled" ] && printf "%s\\n" "$LAUNCHCTL_LISTING"\n'
+        "exit 0\n",
+        encoding="utf-8",
+    )
+    listing = (
+        "\tdisabled services = {\n"
+        f'\t\t"com.brainlayer.watch" => {form}\n\t\t"com.brainlayer.hotlane-brainbar" => {form}\n'
+        f'\t\t"com.brainlayer.enrichment" => {form}\n\t\t"com.brainlayer.drain" => enabled\n'
+        "\t}"
+    )
+    fake_launchctl.chmod(0o755)
+    harness = tmp_path / "harness.sh"
+    harness.write_text(
+        "set -euo pipefail\n"
+        f'LAUNCH_DIR="{tmp_path}"\nPYTHON_BIN=/usr/bin/true\nLOAD_PLIST_SKIPPED=0\n'
+        + helper_body
+        + load_plist_body
+        + '\nload_plist "$1"\n',
+        encoding="utf-8",
+    )
+    env = {
+        **os.environ,
+        "PATH": f"{fake_bin}:{os.environ['PATH']}",
+        "LAUNCHCTL_LOG": str(launchctl_log),
+        "LAUNCHCTL_LISTING": listing,
+    }
+
+    result = subprocess.run(["/bin/bash", str(harness), name], env=env, capture_output=True, text=True, check=False)
+
+    assert result.returncode == 0, result.stderr
+    uid = os.getuid()
+    assert (
+        f"SKIP: com.brainlayer.{name} disabled by operator (launchctl enable gui/{uid}/com.brainlayer.{name} to re-arm)"
+        in result.stdout
+    )
+    calls = launchctl_log.read_text(encoding="utf-8").splitlines()
+    assert calls == [f"print-disabled gui/{uid}"], calls
+
+
+def test_launchd_primitive_reads_current_print_disabled_vocabulary():
+    """macOS 14+ prints `=> disabled|enabled`; older releases print `=> true|false`. Both must be honored."""
+    from types import SimpleNamespace
+
+    from brainlayer.launchd_primitive import is_launchd_label_disabled
+
+    listing = (
+        "\tdisabled services = {\n"
+        '\t\t"com.brainlayer.watch" => disabled\n'
+        '\t\t"com.brainlayer.drain" => enabled\n'
+        '\t\t"com.legacy.off" => true\n'
+        '\t\t"com.legacy.on" => false\n'
+        "\t}\n"
+    )
+    runner = lambda _args: SimpleNamespace(returncode=0, stdout=listing, stderr="")  # noqa: E731
+
+    assert is_launchd_label_disabled("com.brainlayer.watch", command_runner=runner) is True
+    assert is_launchd_label_disabled("com.brainlayer.drain", command_runner=runner) is False
+    assert is_launchd_label_disabled("com.legacy.off", command_runner=runner) is True
+    assert is_launchd_label_disabled("com.legacy.on", command_runner=runner) is False
+    assert is_launchd_label_disabled("com.absent", command_runner=runner) is False
+
+
+def test_launchd_installer_hotlane_skip_bypasses_runtime_verification(tmp_path):
+    """install.sh hotlane-brainbar on an operator-disabled label: rc 0, no verify_hotlane_runtime, no bootout."""
+    install_source = (REPO_ROOT / "scripts/launchd/install.sh").read_text(encoding="utf-8")
+
+    def _fn(name: str) -> str:
+        head = name + "() {"
+        return head + install_source.split("\n" + head, 1)[1].split("\n}\n", 1)[0] + "\n}\n"
+
+    fake_bin = tmp_path / "bin"
+    fake_bin.mkdir()
+    launchctl_log = tmp_path / "launchctl.log"
+    (fake_bin / "launchctl").write_text(
+        "#!/usr/bin/env bash\n"
+        'printf "%s\\n" "$*" >> "$LAUNCHCTL_LOG"\n'
+        '[ "$1" = "print-disabled" ] && printf \'\\t"com.brainlayer.hotlane-brainbar" => disabled\\n\'\n'
+        "exit 0\n",
+        encoding="utf-8",
+    )
+    (fake_bin / "launchctl").chmod(0o755)
+    script_dir = tmp_path / "launchd"
+    script_dir.mkdir()
+    (script_dir / "com.brainlayer.hotlane-brainbar.plist").write_text("<plist/>\n", encoding="utf-8")
+    verify_marker = tmp_path / "verify-ran"
+    harness = tmp_path / "harness.sh"
+    harness.write_text(
+        "set -euo pipefail\n"
+        f'SCRIPT_DIR="{script_dir}"\nLAUNCH_DIR="{tmp_path}"\nLOG_DIR="{tmp_path}"\nBRAINLAYER_LOG_DIR="{tmp_path}"\n'
+        "PYTHON_BIN=/usr/bin/true\nBRAINLAYER_BIN=x\nBRAINLAYER_DIR=x\nBRAINLAYER_LAUNCHD_DIR=x\nBRAINLAYER_PYTHON=x\n"
+        "BRAINLAYER_ENV_FILE=x\nBRAINLAYER_ENV_RUN=x\nHOTLANE_BRAINBAR_DST=x\nLOAD_PLIST_SKIPPED=0\n"
+        "install_hotlane_brainbar_daemon() { :; }\ninstall_env_runner() { :; }\nverify_config_file() { :; }\n"
+        f'verify_hotlane_runtime() {{ touch "{verify_marker}"; return 1; }}\n'
+        + _fn("label_disabled_by_operator")
+        + _fn("load_plist")
+        + _fn("install_plist")
+        + "\ninstall_plist hotlane-brainbar\n",
+        encoding="utf-8",
+    )
+    env = {**os.environ, "PATH": f"{fake_bin}:{os.environ['PATH']}", "LAUNCHCTL_LOG": str(launchctl_log)}
+
+    result = subprocess.run(["/bin/bash", str(harness)], env=env, capture_output=True, text=True, check=False)
+
+    assert result.returncode == 0, result.stderr
+    assert "SKIP: com.brainlayer.hotlane-brainbar disabled by operator" in result.stdout
+    assert not verify_marker.exists(), "verify_hotlane_runtime must not run after an operator-disable skip"
+    assert launchctl_log.read_text(encoding="utf-8").splitlines() == [f"print-disabled gui/{os.getuid()}"]
+
+
+def test_launchd_installer_refuses_to_load_when_disabled_state_is_unreadable(tmp_path):
+    """`launchctl print-disabled` failing must fail closed: no enable, no bootstrap, rc 1 with a clear error."""
+    install_source = (REPO_ROOT / "scripts/launchd/install.sh").read_text(encoding="utf-8")
+
+    def _fn(name: str) -> str:
+        head = name + "() {"
+        return head + install_source.split("\n" + head, 1)[1].split("\n}\n", 1)[0] + "\n}\n"
+
+    fake_bin = tmp_path / "bin"
+    fake_bin.mkdir()
+    launchctl_log = tmp_path / "launchctl.log"
+    (fake_bin / "launchctl").write_text(
+        "#!/usr/bin/env bash\n"
+        'printf "%s\\n" "$*" >> "$LAUNCHCTL_LOG"\n'
+        '[ "$1" = "print-disabled" ] && { echo "Could not find domain" >&2; exit 1; }\n'
+        "exit 0\n",
+        encoding="utf-8",
+    )
+    (fake_bin / "launchctl").chmod(0o755)
+    harness = tmp_path / "harness.sh"
+    harness.write_text(
+        "set -euo pipefail\n"
+        f'LAUNCH_DIR="{tmp_path}"\nPYTHON_BIN=/usr/bin/true\nLOAD_PLIST_SKIPPED=0\n'
+        + _fn("label_disabled_by_operator")
+        + _fn("load_plist")
+        + "\nload_plist watch\n",
+        encoding="utf-8",
+    )
+    env = {**os.environ, "PATH": f"{fake_bin}:{os.environ['PATH']}", "LAUNCHCTL_LOG": str(launchctl_log)}
+
+    result = subprocess.run(["/bin/bash", str(harness)], env=env, capture_output=True, text=True, check=False)
+
+    assert result.returncode == 1
+    assert (
+        "ERROR: could not read launchd disabled state for com.brainlayer.watch "
+        "(launchctl print-disabled rc=1); refusing to load"
+    ) in result.stderr
+    assert "SKIP:" not in result.stdout
+    assert launchctl_log.read_text(encoding="utf-8").splitlines() == [f"print-disabled gui/{os.getuid()}"]