@tyroneross/build-loop 0.30.3

package/hooks/hooks.json

@@ -0,0 +1,126 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}/hooks/session-start-architecture.sh\" </dev/null >/dev/null 2>&1; exit 0",
+            "timeout": 2000
+          },
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}/hooks/session-start-retrieval.sh\" </dev/null >/dev/null 2>&1; exit 0",
+            "timeout": 2000
+          },
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}/hooks/session-start-rally-point.sh\" </dev/null 2>/dev/null; exit 0",
+            "timeout": 2000
+          },
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}/hooks/session-start-worktree-gc.sh\" </dev/null >/dev/null 2>&1; exit 0",
+            "timeout": 2000
+          },
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}/hooks/session-start-git-hooks.sh\" </dev/null >/dev/null 2>&1; exit 0",
+            "timeout": 2000
+          },
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}/hooks/session-start-plugin-drift.sh\" </dev/null >/dev/null 2>&1; exit 0",
+            "timeout": 2000
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}/hooks/pre-edit-architecture.sh\" >/dev/null 2>&1; exit 0",
+            "timeout": 2000
+          },
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}/hooks/pre-edit-rally-point.sh\"; exit 0",
+            "timeout": 2000
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "root=\"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}\"; hook=\"$root/scripts/hooks/pre_bash_autonomy.sh\"; if [ -x \"$hook\" ]; then \"$hook\"; else printf '{}'; fi",
+            "timeout": 2000
+          },
+          {
+            "type": "command",
+            "command": "root=\"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}\"; hook=\"$root/scripts/hooks/pre_bash_dependency_cooldown.sh\"; if [ -x \"$hook\" ]; then \"$hook\"; else printf '{}'; fi",
+            "timeout": 2000
+          },
+          {
+            "type": "command",
+            "command": "root=\"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}\"; hook=\"$root/scripts/audit_before_commit.py\"; if [ -f \"$hook\" ]; then python3 \"$hook\"; else printf '{}'; fi",
+            "timeout": 5000
+          },
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}/hooks/pre-edit-rally-point.sh\"; exit 0",
+            "timeout": 2000
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "[ -f .build-loop/state.json ] || exit 0; python3 -c \"import json,sys; s=json.load(open('.build-loop/state.json')); p7=s.get('phases',{}).get('fact_check',{}).get('completed',False); active=s.get('active',False); sys.exit(0 if (not active or p7) else 1)\" 2>/dev/null && exit 0; echo \"$TOOL_INPUT\" | grep -qE '\\b(git\\s+push|npm\\s+publish|vercel\\s+deploy|gh\\s+release)\\b' && echo 'Build loop Phase 7 (fact-check) has not completed. Run fact-check before deploying.'; exit 0"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [ -n \"$CLAUDE_TRANSCRIPT_PATH\" ]; then nohup python3 \"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}/scripts/scan_transcript_for_decisions.py\" --workdir \"$CLAUDE_PROJECT_DIR\" --transcript \"$CLAUDE_TRANSCRIPT_PATH\" --log-file \"${XDG_STATE_HOME:-$HOME/.local/state}/build-loop/scan.log\" </dev/null >/dev/null 2>&1 & fi; printf '{}'",
+            "timeout": 5000
+          },
+          {
+            "type": "command",
+            "command": "if [ -n \"$CLAUDE_TRANSCRIPT_PATH\" ]; then root=\"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}\"; nohup env PYTHONPATH=\"$root/scripts\" python3 -m scan_corrections --workdir \"$CLAUDE_PROJECT_DIR\" --transcript \"$CLAUDE_TRANSCRIPT_PATH\" --source stop-hook </dev/null >/dev/null 2>&1 & fi; printf '{}'",
+            "timeout": 5000
+          },
+          {
+            "type": "command",
+            "command": "python3 \"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}/scripts/state_finalize.py\" --workdir \"$CLAUDE_PROJECT_DIR\" --mark-incomplete-as-crashed </dev/null >/dev/null 2>&1; printf '{}'",
+            "timeout": 2000
+          },
+          {
+            "type": "command",
+            "command": "root=\"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}\"; hook=\"$root/scripts/hooks/stop_finalize.sh\"; if [ -x \"$hook\" ]; then \"$hook\"; else printf '{}'; fi",
+            "timeout": 30000
+          },
+          {
+            "type": "command",
+            "command": "if [ -f \"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}/scripts/commit_state_check.py\" ]; then python3 \"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}/scripts/commit_state_check.py\" --workdir \"${CLAUDE_PROJECT_DIR}\" --hook; else printf '{}'; fi",
+            "timeout": 5000
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/post-commit

@@ -0,0 +1,30 @@
+#!/bin/sh
+# Rally Point post-commit capture (cross-tool).
+#
+# git fires this regardless of which tool (Claude / Codex / plain git)
+# made the commit, so it is the durable cross-tool capture boundary.
+# Fire-and-forget: all real work is backgrounded and the hook returns 0
+# immediately so it can NEVER slow down or fail a commit.
+#
+# Identity comes from the environment when present:
+#   RALLY_POINT_TOOL   (default: unknown; APP_PULSE_TOOL fallback supported)
+#   RALLY_POINT_RUN_ID (default: unknown; APP_PULSE_RUN_ID fallback supported)
+#   RALLY_POINT_MODEL  (default: unknown; APP_PULSE_MODEL fallback supported)
+#
+# Idempotent installer chains this after any pre-existing post-commit;
+# this body is the Rally Point segment only.
+
+# --- BEGIN rally-point post-commit ---
+RALLY_POINT_TOPLEVEL="$(git rev-parse --show-toplevel 2>/dev/null)"
+if [ -z "$RALLY_POINT_TOPLEVEL" ]; then
+  echo "rally-point post-commit: cannot resolve repo toplevel" >&2
+  exit 2
+fi
+RALLY_POINT_CAPTURE="$RALLY_POINT_TOPLEVEL/.git/hooks/.rally-point-capture.py"
+if [ -f "$RALLY_POINT_CAPTURE" ]; then
+  (
+    python3 "$RALLY_POINT_CAPTURE" >/dev/null 2>&1
+  ) </dev/null >/dev/null 2>&1 &
+fi
+# --- END rally-point post-commit ---
+exit 0

package/hooks/pre-commit

@@ -0,0 +1,29 @@
+#!/bin/sh
+# Public-repo hygiene pre-commit hook.
+#
+# build-loop is open source. This hook blocks a commit that stages a
+# private app slug (see scripts/check_private_slugs.py for the editable
+# denylist) or runtime memory/state files. Unlike post-commit, this hook
+# MUST be able to fail the commit, so it is NOT fire-and-forget — a
+# non-zero exit aborts the commit by design.
+#
+# Idempotent installer chains this after any pre-existing pre-commit;
+# this body is the private-slug-guard segment only.
+
+# --- BEGIN private-slug-guard pre-commit ---
+RALLY_POINT_TOPLEVEL="$(git rev-parse --show-toplevel 2>/dev/null)"
+if [ -z "$RALLY_POINT_TOPLEVEL" ]; then
+  echo "private-slug-guard: cannot resolve repo toplevel — refusing to skip the guard" >&2
+  exit 2
+fi
+PRIVATE_SLUG_GUARD="$RALLY_POINT_TOPLEVEL/.git/hooks/.private-slug-check.py"
+if [ -f "$PRIVATE_SLUG_GUARD" ]; then
+  python3 "$PRIVATE_SLUG_GUARD" || exit 1
+fi
+RUNTIME_MEMORY_GUARD="$RALLY_POINT_TOPLEVEL/.git/hooks/.runtime-memory-tracking-check.py"
+if [ -f "$RUNTIME_MEMORY_GUARD" ]; then
+  python3 "$RUNTIME_MEMORY_GUARD" || exit 1
+fi
+# --- END private-slug-guard pre-commit ---
+
+exit 0

package/hooks/pre-edit-apppulse.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com>
+# SPDX-License-Identifier: Apache-2.0
+# Deprecated alias; use pre-edit-rally-point.sh.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+exec bash "$SCRIPT_DIR/pre-edit-rally-point.sh" "$@"

package/hooks/pre-edit-architecture.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com>
+# SPDX-License-Identifier: Apache-2.0
+# PreToolUse hook (matcher: Edit|Write) — incremental scan trigger.
+#
+# Contract:
+#   - command-type only (NEVER prompt-type)
+#   - no stdout, no stderr (exit 0 always — never blocks the Edit/Write)
+#   - fire-and-forget via `nohup ... &`; hook returns in <100ms
+#   - tool input arrives on stdin as JSON: {"tool_input": {"file_path": "..."}}
+#
+# Behavior:
+#   1. Bail silently if `.build-loop/architecture/file_map.json` does not exist
+#      (engine not initialized).
+#   2. Parse `file_path` from stdin JSON; bail on missing/invalid input.
+#   3. Dependency-manifest edit (package.json, requirements.txt, uv.lock, …):
+#      mark `.build-loop/architecture/.enrich-needed` and EXIT — DEFER the
+#      actual enriched scan to the scout pass (OQ3); never run it inline.
+#   4. Else bail silently if file extension is not in the source-code
+#      allowlist (.py .ts .tsx .js .jsx .mjs .cjs). Doc-only edits (.md,
+#      .txt, plain .json, images) never mark architecture stale or fire a scan.
+#   5. Resolve to repo-relative path; bail if not in file_map.
+#   5. Mark stale (always — even if a scan is in flight, orchestrator must see
+#      stale=true before reading ACP).
+#   6. Fire `_arch_scan_bg.py` (single-flight flock inside the worker).
+
+WORKDIR="${CLAUDE_PROJECT_DIR:-$PWD}"
+ARCH_DIR="$WORKDIR/.build-loop/architecture"
+FILE_MAP="$ARCH_DIR/file_map.json"
+FRESHNESS_SCRIPT="$WORKDIR/scripts/architecture_freshness.py"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORKER="$SCRIPT_DIR/_arch_scan_bg.py"
+
+# Fast bail-out: arch engine not initialized.
+[ -f "$FILE_MAP" ] || exit 0
+[ -f "$FRESHNESS_SCRIPT" ] || exit 0
+[ -f "$WORKER" ] || exit 0
+
+# Read stdin (may be empty — bail cleanly).
+STDIN_JSON=$(cat 2>/dev/null)
+[ -n "$STDIN_JSON" ] || exit 0
+
+# Classify the edited path. Emits one of:
+#   "MANIFEST"  → dependency manifest changed: mark enrich-needed, DEFER the
+#                 actual enrich to the scout pass (OQ3) — do NOT scan inline.
+#   "<rel>"     → tracked source file: the existing mark-stale + bg-scan path.
+#   ""          → bail (doc-only, untracked, unparseable).
+# The manifest check runs BEFORE the source-extension allowlist so a
+# package.json / requirements.txt edit is no longer excluded.
+REL_PATH=$(WORKDIR="$WORKDIR" FILE_MAP="$FILE_MAP" STDIN_JSON="$STDIN_JSON" python3 - <<'PYEOF' 2>/dev/null
+import json, os, sys
+from pathlib import Path
+ALLOWED_EXTS = {".py", ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"}
+MANIFESTS = {
+    "package.json", "package-lock.json", "pnpm-lock.yaml", "requirements.txt",
+    "pyproject.toml", "uv.lock", "Cargo.toml", "Cargo.lock", "go.mod", "Gemfile",
+}
+try:
+    payload = json.loads(os.environ["STDIN_JSON"])
+except (KeyError, json.JSONDecodeError):
+    sys.exit(0)
+ti = payload.get("tool_input") or {}
+fp = ti.get("file_path") or ti.get("path") or ti.get("filename")
+if not fp:
+    sys.exit(0)
+# Dependency-manifest unblock (OQ3) — runs before the extension allowlist.
+if Path(fp).name in MANIFESTS:
+    print("MANIFEST")
+    sys.exit(0)
+# Extension allowlist gate — bail on .md/.txt/.json/etc. before any I/O.
+ext = Path(fp).suffix.lower()
+if ext not in ALLOWED_EXTS:
+    sys.exit(0)
+workdir = Path(os.environ["WORKDIR"]).resolve()
+abs_path = (workdir / fp).resolve() if not os.path.isabs(fp) else Path(fp).resolve()
+try:
+    rel = abs_path.relative_to(workdir).as_posix()
+except ValueError:
+    sys.exit(0)
+try:
+    file_map = json.loads(Path(os.environ["FILE_MAP"]).read_text(encoding="utf-8"))
+except (OSError, json.JSONDecodeError):
+    sys.exit(0)
+files = file_map.get("files") or {}
+if rel in files:
+    print(rel)
+PYEOF
+)
+
+[ -n "$REL_PATH" ] || exit 0
+
+# Dependency-manifest edit: mark enrich-needed and EXIT. The actual enriched
+# scan is deferred to the scout pass (OQ3) — never run inline here.
+if [ "$REL_PATH" = "MANIFEST" ]; then
+  : > "$ARCH_DIR/.enrich-needed" 2>/dev/null || true
+  exit 0
+fi
+
+# Mark stale immediately (cheap, atomic).
+python3 "$FRESHNESS_SCRIPT" --mark-stale --file "$REL_PATH" --workdir "$WORKDIR" >/dev/null 2>&1 || true
+
+# Fire the background worker. Single-flight handled inside the worker.
+nohup python3 "$WORKER" --workdir "$WORKDIR" </dev/null >/dev/null 2>&1 &
+disown 2>/dev/null || true
+
+exit 0

package/hooks/pre-edit-rally-point.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com>
+# SPDX-License-Identifier: Apache-2.0
+# PreToolUse(Edit|Write|Bash) hook — Rally Point throttled per-tool-use re-join
+# + cheap revision-stat hint.
+#
+# Contract:
+#   - command-type only (NEVER prompt-type)
+#   - exit 0 ALWAYS — NEVER blocks the tool use
+#   - cheap: a single `revision` stat+read for the legacy hint, a single
+#     presence stat+read for the throttled re-join, NO tail read, NO lock
+#   - prints one short hint ONLY when the channel revision is ahead of
+#     this reader's last-seen revision; silent otherwise
+#   - graceful absence: no channel -> silent exit 0
+#
+# Codex-parity hardening (2026-06-07):
+# Beyond the legacy revision hint, this hook now ALSO resolves the
+# OPERATIVE repo from the tool event (Edit/Write file_path, Bash leading
+# ``cd <path>``) and writes a throttled heartbeat presence in THAT repo's
+# room. SessionStart misregisters (or no-ops) when the agent launches
+# outside the repo it actually edits; this re-join recovers presence on
+# the first tool-use without a flock on the hot path.
+
+WORKDIR="${CLAUDE_PROJECT_DIR:-$PWD}"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PKG="$SCRIPT_DIR/../scripts/rally_point"
+
+[ -d "$PKG" ] || exit 0
+
+# Read stdin (Claude Code PreToolUse JSON event). Best-effort; an empty
+# or malformed payload simply means "no operative-repo hint" — the legacy
+# revision-stat hint still fires using the workdir's channel.
+# Cap at 64 KB: a pathological Bash command must not exhaust ARG_MAX when
+# the payload is forwarded to Python via the environment.
+STDIN_JSON=""
+if [ ! -t 0 ]; then
+    STDIN_JSON=$(cat 2>/dev/null || true)
+    STDIN_JSON=$(printf '%s' "$STDIN_JSON" | head -c 65536)
+fi
+
+# Extract file_path (Edit/Write) and command (Bash) from the event JSON.
+# Both are optional; pre-edit treats them as resolution hints, not gates.
+# Print them on two separate lines so the shell does not have to deal
+# with NUL handling across portable awk/read.
+FILE_PATH=""
+TOOL_CMD=""
+if [ -n "$STDIN_JSON" ]; then
+    EXTRACTED=$(STDIN_JSON="$STDIN_JSON" python3 - <<'PYEOF' 2>/dev/null
+import json, os, sys
+raw = os.environ.get("STDIN_JSON") or ""
+try:
+    d = json.loads(raw)
+except (ValueError, TypeError):
+    sys.exit(0)
+ti = (d.get("tool_input") or {}) if isinstance(d.get("tool_input"), dict) else {}
+fp = ti.get("file_path") or ti.get("path") or ti.get("filename") or ""
+cmd = ti.get("command") or ""
+# Emit fp as base64 (single line, no newlines), then cmd as base64. The
+# bash side decodes; this avoids embedded-newline parsing entirely.
+import base64
+b64 = lambda s: base64.b64encode(s.encode("utf-8", "replace")).decode("ascii") if s else ""
+sys.stdout.write(b64(fp) + "\n" + b64(cmd) + "\n")
+PYEOF
+)
+    if [ -n "$EXTRACTED" ]; then
+        FILE_PATH_B64=$(printf '%s\n' "$EXTRACTED" | sed -n '1p')
+        TOOL_CMD_B64=$(printf '%s\n' "$EXTRACTED" | sed -n '2p')
+        if [ -n "$FILE_PATH_B64" ]; then
+            FILE_PATH=$(printf '%s' "$FILE_PATH_B64" | base64 --decode 2>/dev/null || true)
+        fi
+        if [ -n "$TOOL_CMD_B64" ]; then
+            TOOL_CMD=$(printf '%s' "$TOOL_CMD_B64" | base64 --decode 2>/dev/null || true)
+        fi
+    fi
+fi
+
+# Single call: pre_edit_hint (legacy, workdir channel) + pre_edit_join
+# (throttled, operative-repo channel). Both are advisory and fail-open.
+# Empty strings on the Python side are treated as "no hint" (falsy).
+#
+# Stderr routing (f1): quiet on the happy path; let stderr through only
+# when BUILD_LOOP_RALLY_DEBUG=1 so diagnostics are available on demand
+# without polluting the terminal by default.
+if [ "${BUILD_LOOP_RALLY_DEBUG:-0}" = "1" ]; then
+    python3 "$PKG/hooks.py" pre-edit --workdir "$WORKDIR" --tool claude_code \
+        --file-path "$FILE_PATH" --command "$TOOL_CMD" || exit 0
+else
+    python3 "$PKG/hooks.py" pre-edit --workdir "$WORKDIR" --tool claude_code \
+        --file-path "$FILE_PATH" --command "$TOOL_CMD" 2>/dev/null || exit 0
+fi
+
+exit 0

package/hooks/session-start-apppulse.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com>
+# SPDX-License-Identifier: Apache-2.0
+# Deprecated alias; use session-start-rally-point.sh.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+exec bash "$SCRIPT_DIR/session-start-rally-point.sh" "$@"

package/hooks/session-start-architecture.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: Apache-2.0
+# Incremental architecture scan when manifest is missing or >24h old.
+D="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+. "$D/_session_start_lib.sh"
+W="${CLAUDE_PROJECT_DIR:-$PWD}"
+[ -d "$W/.build-loop/architecture" ] && [ -f "$D/_arch_scan_bg.py" ] || exit 0
+[ "$(bl_stale "$W/.build-loop/architecture/manifest.json" 86400)" = "yes" ] || exit 0
+bl_fire_bg "$D/_arch_scan_bg.py" --workdir "$W"
+exit 0

package/hooks/session-start-git-hooks.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: Apache-2.0
+# Auto-install build-loop git hooks on session start (idempotent).
+# Installs: pre-push (push-HOLD gate).
+# Skips silently when: not inside a git repo, Python unavailable, hook
+# source not found, or a foreign (non-build-loop) pre-push is already
+# installed (requires --force to overwrite; we never force on auto-install).
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-${CLAUDE_PROJECT_DIR:-$PWD}}"
+cd "${CLAUDE_PROJECT_DIR:-$PWD}" 2>/dev/null || exit 0
+git rev-parse --git-dir >/dev/null 2>&1 || exit 0
+python3 "${PLUGIN_ROOT}/scripts/install_git_hooks.py" --install >/dev/null 2>&1 || true
+exit 0

package/hooks/session-start-plugin-drift.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: Apache-2.0
+# Plugin-cache maintenance, fire-and-forget, HOST-AWARE. This hook runs on BOTH
+# hosts — Claude (SessionStart) and Codex (hooks/hooks.json session_start); both
+# set CLAUDE_PLUGIN_ROOT, but Codex's resolves under ~/.codex. So derive the host
+# from that path and prune the RUNNING host's cache (never the other host's).
+#   1. DRIFT  — cached-install-behind-upstream check. Claude only (worker keys on
+#               ~/.claude/plugins).
+#   2. PRUNE  — auto-remove stale cache versions for the running host via the
+#               canonical engine scripts/prune_plugin_cache.py. Engine protects the
+#               in-use dir (CLAUDE_PLUGIN_ROOT, default-on) + installed pins
+#               (--protect-installed); re-fetched on demand, so prunes are
+#               reversible. Opt out: BUILDLOOP_NO_CACHE_GC=1.
+D="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+. "$D/_session_start_lib.sh"
+ROOT="${CLAUDE_PLUGIN_ROOT:-$D/..}"
+case "$ROOT" in
+  */.codex/*) HOST=codex ;;
+  *)          HOST=claude ;;
+esac
+if [ "$HOST" = claude ] && [ -d "$HOME/.claude/plugins" ] && [ -f "$D/_plugin_drift_check_bg.py" ]; then
+  bl_fire_bg "$D/_plugin_drift_check_bg.py"
+fi
+if [ "${BUILDLOOP_NO_CACHE_GC:-}" != "1" ] && [ -f "$ROOT/scripts/prune_plugin_cache.py" ]; then
+  bl_fire_bg "$ROOT/scripts/prune_plugin_cache.py" --source "$ROOT" --host "$HOST" --apply --protect-installed
+fi
+exit 0

package/hooks/session-start-rally-point.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: Apache-2.0
+# Rally Point R2 announce + listen. Surfaces deltas/peers, then advances cursor.
+#
+# Codex-parity hardening (2026-06-07):
+# When ``CLAUDE_PROJECT_DIR`` is unset AND ``$PWD`` is NOT a git repo
+# (e.g. ``$HOME`` for a Claude Code launched outside a repo), do NOT
+# write presence to the launch dir's room. The per-tool-use rally hook
+# (pre-edit-rally-point.sh, also registered on the Bash matcher) joins
+# the OPERATIVE repo's room on the first tool-use, recovering from a
+# cross-repo launch without polluting the home / ``_unscoped`` room.
+D="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+. "$D/_session_start_lib.sh"
+W="${CLAUDE_PROJECT_DIR:-$PWD}"
+PKG="$(dirname "$D")/scripts/rally_point"
+[ -d "$PKG" ] || exit 0
+
+# Guard: if CLAUDE_PROJECT_DIR is unset and $PWD is not a git repo, the
+# launch cwd is not a rally room — defer the join to pre-edit (operative
+# repo resolution from the first Edit/Write/Bash). This is the no-op path.
+if [ -z "${CLAUDE_PROJECT_DIR:-}" ]; then
+    if ! git -C "$W" rev-parse --git-dir >/dev/null 2>&1; then
+        exit 0
+    fi
+fi
+
+# Step 1: checkpoint_read restore line (verbose: surface delta if any).
+# ``session-start-safe`` no-ops cleanly when the resolved workdir is not a
+# git repo (belt-and-braces — the shell guard above already filters).
+python3 "$PKG/hooks.py" session-start-safe --workdir "$W" --verbose 2>/dev/null || true
+
+# Step 2: probe announce + listen (fully detached watcher).
+if [ "${BUILD_LOOP_RALLY_POINT_SKIP_WATCH:-}" = "1" ]; then
+    [ -f "$PKG/session_probe.py" ] && WORKDIR="$W" python3 "$PKG/session_probe.py" \
+        --workdir "$W" --tool claude_code --mode hook >/dev/null 2>&1 || true
+else
+    [ -f "$PKG/session_probe.py" ] && WORKDIR="$W" python3 "$PKG/session_probe.py" \
+        --workdir "$W" --tool claude_code --mode hook --start-watch >/dev/null 2>&1 || true
+fi
+
+# Step 3: advance cursor past probe's own writes (silent; same script, no VERBOSE).
+python3 "$PKG/hooks.py" session-start-advance --workdir "$W" 2>/dev/null || true
+
+exit 0

package/hooks/session-start-retrieval.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: Apache-2.0
+# Retrieval warmup + silent-failure canary. Fire-and-forget.
+set +e
+D="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+. "$D/_session_start_lib.sh"
+W="${CLAUDE_PROJECT_DIR:-$PWD}"
+S="${CLAUDE_PLUGIN_ROOT:-$W}/scripts"
+LD="${XDG_STATE_HOME:-$HOME/.local/state}/build-loop"
+mkdir -p "$LD" 2>/dev/null
+
+# Ollama daemon ping (warms loaded models in RAM).
+( command -v ollama >/dev/null 2>&1 && nohup ollama list </dev/null >/dev/null 2>&1 & )
+
+# Long-running rerank + embed daemons (single-flight).
+bl_spawn_daemon "$S/rerank_daemon.py" "${RERANK_DAEMON_PORT:-8765}" rerank-daemon rerank-daemon "$LD"
+bl_spawn_daemon "$S/embed_daemon.py"  "${EMBED_DAEMON_PORT:-8766}"  embed-daemon  embed-daemon  "$LD"
+
+# Health canary -> state.json + rotating log.
+[ -f "$S/backend_health.py" ] && nohup python3 "$S/backend_health.py" \
+    --workdir "$W" --include-retrieval --quiet \
+    </dev/null >>"$LD/retrieval-health.log" 2>&1 & disown 2>/dev/null || true
+
+exit 0

package/hooks/session-start-worktree-gc.sh

@@ -0,0 +1,105 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: Apache-2.0
+# Worktree GC: remove merged+clean stale worktrees/branches, AUTO-PRUNE orphans.
+# ACT mode (bundle-first removal of merged worktrees + branches) is ON by default
+# so cross-run residue self-heals (intent.md A5); set BUILDLOOP_GC_ACT=0 to opt out
+# (report-only). Locked, dirty, or unmerged worktrees are never removed either way.
+cd "${CLAUDE_PROJECT_DIR:-$PWD}" 2>/dev/null || exit 0
+git rev-parse --git-dir >/dev/null 2>&1 || exit 0
+R=".build-loop/worktree-gc-last.txt"
+mkdir -p "$(dirname "$R")"
+_bundle_done=0
+
+# Rally exclusion (defense-in-depth, optional). If `rally` is on PATH and
+# `rally sessions --json` returns a list of live sessions, collect their
+# `cwd` paths so we can skip any worktree owned by an active session in
+# addition to the path-prefix guard below. Rally owns its own worktree
+# lifecycle; build-loop's GC must never reap a rally-owned worktree (force-
+# removing it deletes the cwd of a live agent process and every subsequent
+# hook fails with posix_spawn ENOENT). The path-prefix exclusion is the
+# PRIMARY guard and works even when `rally` is not installed.
+_rally_cwds=""
+if command -v rally >/dev/null 2>&1; then
+  _rally_cwds=$(rally sessions --json 2>/dev/null \
+    | awk 'match($0, /"cwd"[[:space:]]*:[[:space:]]*"[^"]+"/){
+             s=substr($0,RSTART,RLENGTH);
+             sub(/^"cwd"[[:space:]]*:[[:space:]]*"/,"",s);
+             sub(/"$/,"",s);
+             print s
+           }' 2>/dev/null || true)
+fi
+
+{
+  printf '# Worktree GC report — %s\n\n## Stale candidates (REPORT-ONLY)\n' "$(date -u +%FT%TZ)"
+
+  # Collect candidates; in ACT mode, acted-on items are echoed inline (ACT:removed)
+  # and split into their own report section by the awk pass below.
+  git worktree list --porcelain 2>/dev/null \
+    | awk '/^worktree /{p=$2} /^branch /{b=$2; sub("refs/heads/","",b); if(p && b){print p" "b}; p=""; b=""}' \
+    | while read -r path branch; do
+        [ "$branch" = main ] && continue
+        # Rally-owned worktrees are NEVER touched by build-loop's GC.
+        # Primary guard: path-prefix exclusion (works without rally on PATH).
+        case "$path" in
+          */.rally/worktrees/*)
+            echo "  SKIP:rally-owned  $path  branch=$branch"
+            continue
+            ;;
+        esac
+        # Defense-in-depth: live rally session cwd cross-check.
+        if [ -n "$_rally_cwds" ]; then
+          _skip=0
+          while IFS= read -r _cwd; do
+            [ -z "$_cwd" ] && continue
+            if [ "$_cwd" = "$path" ]; then
+              _skip=1
+              break
+            fi
+          done <<EOF
+$_rally_cwds
+EOF
+          if [ "$_skip" = "1" ]; then
+            echo "  SKIP:rally-live-session  $path  branch=$branch"
+            continue
+          fi
+        fi
+        git merge-base --is-ancestor "$branch" main 2>/dev/null || continue
+        dirty=$(git -C "$path" status --porcelain 2>/dev/null | wc -l | tr -d ' ')
+        locked=unlocked
+        [ -f "$path/.git" ] && grep -q locked "$path/.git" 2>/dev/null && locked=locked
+        echo "  $path  branch=$branch  merged=yes  dirty=$dirty  $locked"
+
+        if [ "${BUILDLOOP_GC_ACT:-1}" = "1" ] && [ "$dirty" = "0" ] && [ "$locked" = "unlocked" ]; then
+          # Reversibility: one bundle per run, created before first removal.
+          if [ "$_bundle_done" = "0" ]; then
+            mkdir -p ".build-loop/bundles"
+            git bundle create ".build-loop/bundles/gc-$(date -u +%Y%m%dT%H%M%SZ).bundle" --all >/dev/null 2>&1
+            _bundle_done=1
+          fi
+          git worktree remove -f -f "$path" >/dev/null 2>&1
+          git branch -D "$branch" >/dev/null 2>&1
+          echo "  ACT:removed  $path  branch=$branch"
+        fi
+      done
+
+  printf '\n## Auto-prune (Git-proven orphans only)\n'
+  git worktree prune -v 2>/dev/null
+} > "$R" 2>&1
+
+# Rewrite report to split REPORT-ONLY from Auto-removed sections cleanly.
+if [ "${BUILDLOOP_GC_ACT:-1}" = "1" ] && grep -q 'ACT:removed' "$R" 2>/dev/null; then
+  tmp=$(mktemp)
+  awk '
+    /^## Stale candidates/ { in_stale=1 }
+    in_stale && /  ACT:removed / {
+      sub("  ACT:removed  ", "  ")
+      if (!printed_hdr) { removed=removed "\n## Auto-removed (merged, bundled)\n"; printed_hdr=1 }
+      removed=removed $0 "\n"
+      next
+    }
+    { print }
+    END { printf "%s", removed }
+  ' "$R" > "$tmp" && mv "$tmp" "$R"
+fi
+
+exit 0

package/hooks/test_apppulse_hooks.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com>
+# SPDX-License-Identifier: Apache-2.0
+# Deprecated alias; use test_rally_point_hooks.sh.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+exec bash "$SCRIPT_DIR/test_rally_point_hooks.sh" "$@"