@thebassclef/lite 1.0.4 → 1.1.1

package/dist/lite/presence/install/bassclef-sync.dispatcher.template.sh

@@ -0,0 +1,841 @@
+#!/bin/bash
+# tier: lite
+# description: Retagged standard → lite per #1301 concentric rule (ADR-052 D1) —
+# Retagged standard → lite per #1301 concentric rule (ADR-052 D1) —
+# this dispatcher IS the sync entry point every adopter vendors into
+# .claude/hooks/bassclef-sync.sh. Without ship at lite, lite adopters
+# have no sync at all. Closes #1301 sister file.
+# BASSCLEF_SYNC_VERSION=thin-pointer-2026-07-28a
+# ^^ DO NOT REMOVE — used by bassclef's drift check + Layer 3 self-heal
+#    detection (per ADR-032). Version string format: descriptor-YYYY-MM-DD.
+#
+# Thin-pointer bassclef-sync dispatcher.
+#
+# Source of truth for the dispatcher consumers vendor into their
+# .claude/hooks/bassclef-sync.sh. See standards/bassclef-source-config.md
+# for the .bassclef-source.json schema this dispatcher reads.
+#
+# Two paths, tried in order:
+#
+#   1. Sibling fast-path (local dev, desktop, multi-repo workspaces)
+#      — if $CWD/../bassclef/presence/install/bassclef-sync.template.sh
+#        exists, exec it directly. Always-current because the file is
+#        read fresh on every fire.
+#
+#   2. Curl fallback (Cloud Env, mobile, fresh sandboxes, CI)
+#      — read .bassclef-source.json for upstream URL + auth metadata,
+#        fetch the tarball, extract, exec the included template.
+#
+# When neither path works, the dispatcher prints a plain-language
+# explanation with three resolution paths (public adopter / local dev
+# / private fork). Always exits 0 so SessionStart hooks don't crash;
+# consumers that want CI fail-fast behavior should pre-check inside
+# their workflow.
+#
+# Versioning: bump BASSCLEF_SYNC_VERSION when the dispatcher's
+# semantics change. Format: YYYY-MM-DD or descriptor-YYYY-MM-DD.
+#
+#   thin-pointer-2026-07-09: pointer-file rename cure (bet 2026-07-09a).
+#                            Adopters onboarded before 2026-06-20 rename carry
+#                            .canonical-source.json. Dispatcher now reads new
+#                            name first, falls back to old, and self-heals
+#                            (writes new name from old content; removes old on
+#                            second cycle per Hoare two-step atomic). Fires
+#                            before auto_sync check + Path 2 curl fallback.
+#                            Overrides: SKIP_SELF_HEAL_POINTER=1 skips write.
+#                            Prior version: thin-pointer-2026-06-29c.
+#   thin-pointer-2026-06-29c: fallback message names the cure (bet 29e WU-10).
+#                              emit_error() now lists option 4 — the curl
+#                              one-liner that runs migrate-adopter-references.sh
+#                              for adopters whose tree carries leftover
+#                              canonical-* references from the 2026-06-20 rename
+#                              event. Discoverable cure inside the error itself;
+#                              the adopter does not need to read the wiki.
+#                              Prior version: thin-pointer-2026-06-29b.
+#   thin-pointer-2026-06-29b: auto-invocation added (bet 29e WU-4). Detection
+#                              step now runs the migrate script automatically
+#                              via curl-pipe + continues to Path 1/Path 2.
+#                              SKIP_AUTO_INVOKE=1 falls back to WU-2's BLOCKED
+#                              behavior. Passes BASSCLEF_DISPATCHER_TEMPLATE
+#                              to migrate when sibling template available.
+#                              Prior version: thin-pointer-2026-06-29.
+#   thin-pointer-2026-06-29: canonical-* reference detection step added
+#                            (bet 29e WU-2). Scans adopter .claude/settings.json
+#                            + vendored bassclef-sync.sh for refs surviving the
+#                            2026-06-20 rename. Emits BLOCKED + exits 0. WU-4 will
+#                            replace exit with auto-invocation of migrate-adopter-
+#                            references.sh. Override: SKIP_CANONICAL_DETECTION=1.
+#                            Prior version: thin-pointer-2026-06-22.
+#   thin-pointer-2026-06-22: version-detection helper added per ADR-032
+#                            (Layer 2 two-stage rocket). __bassclef_dispatcher_version
+#                            function exposes BASSCLEF_SYNC_VERSION to external
+#                            tooling (Layer 3 self-heal in WU-4). No protocol
+#                            break; purely additive. Prior version: thin-pointer-2026-06-13.
+#   thin-pointer-2026-06-13: auto_sync flag check — dispatcher short-
+#                            circuits when .bassclef-source.json has
+#                            auto_sync:false or the field absent. Per
+#                            bassclef#939. Prior version: 2026-05-15.
+#   thin-pointer-2026-05-15: friendly error messages with three
+#                            resolution paths. Closes bassclef#715
+#                            Layer A. Prior version: 2026-05-02.
+
+# === Version-detection helper (per ADR-032) ===
+# Layer 3 self-heal (WU-4 of bet 2026-06-22b) calls this to detect
+# bootstrap version drift. External tooling can also grep
+# BASSCLEF_SYNC_VERSION from line 3, but the function gives a stable
+# programmatic interface that survives header-comment reformatting.
+__bassclef_dispatcher_version() {
+  echo "thin-pointer-2026-07-09"
+}
+
+# === Pointer-file fallback + self-heal (bet 2026-07-09a) ===
+#
+# Every adopter onboarded before the 2026-06-20 canonical → bassclef
+# rename carries .canonical-source.json. The dispatcher previously read
+# .bassclef-source.json only; stale adopters saw substrate refuse to
+# load. These two functions cure the class:
+#
+#   bassclef_sync_resolve_pointer_file(cwd)
+#     Echoes the path of the pointer file to use. Prefers new name;
+#     falls back to old name; echoes empty when neither exists.
+#
+#   bassclef_sync_self_heal_pointer(cwd)
+#     Two-step atomic rename per Tony Hoare. First cycle: writes new
+#     name from old content, keeps old file for safety. Second cycle:
+#     removes old file when new already exists. Never deletes new.
+#     Honors SKIP_SELF_HEAL_POINTER=1 for one-shot recovery scenarios.
+#
+# Composing luminaries:
+#   @luminary linus-torvalds — we-dont-break-adopters (ADR-031)
+#   @luminary jerome-saltzer-and-michael-schroeder — complete mediation
+#   @luminary tony-hoare — pre/post conditions on two-step rename
+#   @luminary michael-feathers — characterization tests using real Quorum
+#
+# Tests: .claude/hooks/tests/bassclef-sync-pointer-fallback.test.sh
+# Refs: bassclef-upstream#679
+bassclef_sync_resolve_pointer_file() {
+  local cwd="${1:-$CWD}"
+  local new="$cwd/.bassclef-source.json"
+  local old="$cwd/.canonical-source.json"
+  if [ -f "$new" ]; then
+    echo "$new"
+  elif [ -f "$old" ]; then
+    echo "$old"
+  else
+    echo ""
+  fi
+}
+
+bassclef_sync_self_heal_pointer() {
+  local cwd="${1:-$CWD}"
+  if [ "${SKIP_SELF_HEAL_POINTER:-0}" = "1" ]; then
+    return 0
+  fi
+  local new="$cwd/.bassclef-source.json"
+  local old="$cwd/.canonical-source.json"
+  # Second cycle: both exist → remove old, keep new (Hoare postcondition)
+  if [ -f "$new" ] && [ -f "$old" ]; then
+    rm -f "$old"
+    return 0
+  fi
+  # First cycle: only old exists → write new from old content, keep old for safety
+  if [ ! -f "$new" ] && [ -f "$old" ]; then
+    cp "$old" "$new" 2>/dev/null || return 0
+    # Emit a one-line note so operator sees the self-heal firing
+    echo "bassclef-sync: renamed .canonical-source.json → .bassclef-source.json (auto-heal; original kept for one session)" >&2
+    return 0
+  fi
+  # Only new exists OR neither exists → no-op
+  return 0
+}
+
+# bassclef_sync_self_heal_pointer_content(cwd)
+#   Rewrites drift in .bassclef-source.json content on adopters onboarded
+#   before the 2026-06-20 canonical → bassclef rename.
+#     - source_url: sunj-labs/canonical -> sunj-labs/bassclef
+#     - token_env:  CANONICAL_TOKEN     -> BASSCLEF_TOKEN
+#   Preserves auth_method (Bearer during beta), auto_sync flag, and every
+#   other field. Idempotent — no-op when content already uses new names.
+#   Honors SKIP_SELF_HEAL_POINTER_CONTENT=1 for one-shot recovery cases.
+#   Per bet 2026-07-09c WU-2 (bassclef-upstream#680). Sister to
+#   bassclef_sync_self_heal_pointer (filename cure from bet 09a).
+bassclef_sync_self_heal_pointer_content() {
+  local cwd="${1:-$CWD}"
+  if [ "${SKIP_SELF_HEAL_POINTER_CONTENT:-0}" = "1" ]; then
+    return 0
+  fi
+  local pointer="$cwd/.bassclef-source.json"
+  if [ ! -f "$pointer" ]; then
+    return 0
+  fi
+  # Detect drift — cheap grep before invoking jq
+  local drift=0
+  if grep -q "sunj-labs/canonical" "$pointer" 2>/dev/null; then
+    drift=1
+  fi
+  if grep -q "CANONICAL_TOKEN" "$pointer" 2>/dev/null; then
+    drift=1
+  fi
+  if [ "$drift" = "0" ]; then
+    return 0
+  fi
+  # Rewrite via jq — preserves JSON structure and untouched fields
+  local new_json
+  new_json=$(jq '
+    (if (.source_url // "" | contains("sunj-labs/canonical"))
+      then .source_url = (.source_url | sub("sunj-labs/canonical"; "sunj-labs/bassclef"))
+      else . end)
+    | (if (.token_env // "") == "CANONICAL_TOKEN"
+      then .token_env = "BASSCLEF_TOKEN"
+      else . end)
+    | (if (.comment // "" | contains("sunj-labs/canonical"))
+      then .comment = (.comment | gsub("sunj-labs/canonical"; "sunj-labs/bassclef"))
+      else . end)
+  ' "$pointer" 2>/dev/null)
+  if [ -n "$new_json" ]; then
+    echo "$new_json" > "$pointer.tmp" 2>/dev/null && mv "$pointer.tmp" "$pointer" 2>/dev/null
+    echo "bassclef-sync: cured .bassclef-source.json content drift (source_url + token_env → bassclef names)" >&2
+  fi
+  return 0
+}
+
+# bassclef_sync_self_heal_claude_md_content(cwd)
+#   Inserts @.claude/bassclef-orientation.md after the first heading in
+#   adopter CLAUDE.md when missing. Rewrites stale sunj-labs/canonical
+#   URL references + ../canonical path references. Preserves adopter-
+#   authored sections. Backs up to CLAUDE.md.bak.<ts> before edit.
+#   Idempotent — no-op on cured content.
+#   Honors SKIP_SELF_HEAL_CLAUDE_MD_CONTENT=1 for adopters who want to
+#   own their CLAUDE.md fully.
+#   Per bet 2026-07-09c WU-3 (bassclef-upstream#687 Path 2). Sister to
+#   bassclef_sync_self_heal_pointer_content (WU-2 pointer content cure).
+bassclef_sync_self_heal_claude_md_content() {
+  local cwd="${1:-$CWD}"
+  if [ "${SKIP_SELF_HEAL_CLAUDE_MD_CONTENT:-0}" = "1" ]; then
+    return 0
+  fi
+  local file="$cwd/CLAUDE.md"
+  if [ ! -f "$file" ]; then
+    return 0
+  fi
+  local drift_import=0
+  local drift_url=0
+  local drift_path=0
+  if ! grep -q "@.claude/bassclef-orientation.md" "$file" 2>/dev/null; then
+    drift_import=1
+  fi
+  if grep -q "sunj-labs/canonical" "$file" 2>/dev/null; then
+    drift_url=1
+  fi
+  if grep -q "\\.\\./canonical" "$file" 2>/dev/null; then
+    drift_path=1
+  fi
+  if [ "$drift_import" = "0" ] && [ "$drift_url" = "0" ] && [ "$drift_path" = "0" ]; then
+    return 0
+  fi
+  local backup_ts
+  backup_ts=$(date +%s)
+  cp "$file" "${file}.bak.${backup_ts}" 2>/dev/null
+  if [ "$drift_import" = "1" ]; then
+    awk 'BEGIN{added=0} /^# / && added==0 {print; print ""; print "@.claude/bassclef-orientation.md"; added=1; next} {print}' \
+      "$file" > "${file}.tmp" 2>/dev/null && mv "${file}.tmp" "$file" 2>/dev/null
+  fi
+  sed 's|sunj-labs/canonical|sunj-labs/bassclef|g; s|\.\./canonical|../bassclef|g' \
+    "$file" > "${file}.tmp" 2>/dev/null && mv "${file}.tmp" "$file" 2>/dev/null
+  echo "bassclef-sync: cured CLAUDE.md content drift (@import + canonical references → bassclef; backup at ${file}.bak.${backup_ts})" >&2
+  return 0
+}
+
+INPUT=$(cat)
+CWD=$(echo "$INPUT" | jq -r '.cwd // "."')
+cd "$CWD"
+
+# Opt-out sentinel (bassclef#119): repos that must NOT inherit substrate.
+if [ -f "$CWD/.no-bassclef-sync" ]; then
+  echo "Bassclef substrate sync: skipped (.no-bassclef-sync sentinel present)."
+  exit 0
+fi
+
+# === SELF_MODE detection (#929 — closes dispatcher-level bypass of #915) ===
+# Sister to Section 0a in .claude/hooks/bassclef-sync.sh (which shipped in
+# #915 PR #920 and guards the sync flow). This guard sits earlier in the
+# call chain — at the dispatcher — so canonical-* auto-invoke + auto_sync
+# fetch + Path 1 / Path 2 branches ALL skip when the current repo is the
+# substrate source (bassclef or bassclef-upstream).
+#
+# Rationale: session 26g SessionStart re-symlinked ~63 hooks in
+# bassclef-upstream despite #915. The project hook's SELF_MODE fired but
+# only AFTER the dispatcher had already invoked the migrate script + fired
+# other paths that touched the tree. Guard early = complete mediation.
+#
+# Env override SKIP_SELF_MODE_DETECTION=1 forces SELF_MODE=0 regardless
+# of remote — for adopter forks of bassclef-upstream that legitimately
+# want the sync flow.
+#
+# Non-breaking for adopters per ADR-031: SELF_MODE returns 0 for any repo
+# whose git remote is NOT sunj-labs/bassclef or sunj-labs/bassclef-upstream.
+# All 5 existing adopters keep their normal recovery + sync paths.
+__bassclef_dispatcher_detect_self_mode() {
+  local cwd="${1:-.}"
+
+  # Env override wins
+  if [ "${SKIP_SELF_MODE_DETECTION:-0}" = "1" ]; then
+    echo "0"
+    return 0
+  fi
+
+  # No git → not substrate source
+  command -v git >/dev/null 2>&1 || { echo "0"; return 0; }
+
+  # Get remote origin URL
+  local remote_url
+  remote_url=$(git -C "$cwd" config --get remote.origin.url 2>/dev/null)
+  if [ -z "$remote_url" ]; then
+    echo "0"
+    return 0
+  fi
+
+  # Match sunj-labs/(bassclef|bassclef-upstream) with optional .git suffix
+  # HTTPS: https://github.com/sunj-labs/bassclef.git
+  # SSH:   git@github.com:sunj-labs/bassclef-upstream.git
+  if echo "$remote_url" | grep -qE 'sunj-labs/(bassclef|bassclef-upstream)(\.git)?$'; then
+    echo "1"
+    return 0
+  fi
+
+  echo "0"
+  return 0
+}
+
+__DISPATCHER_SELF_MODE=$(__bassclef_dispatcher_detect_self_mode "$CWD")
+if [ "$__DISPATCHER_SELF_MODE" = "1" ]; then
+  # #895: park user-scope orphans that shadow project scope before exit.
+  # Without this, pre-existing symlinks planted by sibling syncs (POA,
+  # twoDo, utilities) shadow bassclef-upstream's project scope in the
+  # Claude Code menu — 92 skills appear twice. The parking helper leaves
+  # real user-scope dirs (operator-authored content) untouched per its
+  # v3 contract. Adopters never hit this path (SELF_MODE=0 for their
+  # remotes per __bassclef_dispatcher_detect_self_mode).
+  #
+  # Override: SKIP_SELF_MODE_PARKING=1 for one-shot recovery scenarios.
+  if [ "${SKIP_SELF_MODE_PARKING:-0}" != "1" ]; then
+    __parking_helper="$CWD/scripts/bassclef-orphan-parking.sh"
+    if [ -x "$__parking_helper" ]; then
+      for __surface in skills agents hooks; do
+        __user_surface="$HOME/.claude/$__surface"
+        __project_surface="$CWD/.claude/$__surface"
+        if [ -d "$__user_surface" ] && [ -d "$__project_surface" ]; then
+          # v4 (bassclef-upstream#1077): pass BOTH user + project settings.json
+          # as variadic 5th+ args. Parking helper unions the $HOME wirings
+          # across both files. Any hook wired at $HOME by either settings
+          # scope is preserved. Missing paths silently skip (helper v4 contract).
+          bash "$__parking_helper" "$__user_surface" "$__project_surface" "$HOME/.claude" "$__surface" "$HOME/.claude/settings.json" "$CWD/.claude/settings.json" 2>/dev/null || true
+        fi
+      done
+    fi
+  fi
+  echo "Bassclef dispatcher SELF_MODE — skipping sync in substrate source repo." >&2
+  echo "  (Override with SKIP_SELF_MODE_DETECTION=1 for adopter forks;" >&2
+  echo "   SKIP_SELF_MODE_PARKING=1 to skip user-scope orphan parking.)" >&2
+  exit 0
+fi
+
+# === auto_sync flag check (bassclef#939) ===
+#
+# Per bassclef#939, fresh consumers default to OFF — the dispatcher
+# only fetches when the consumer explicitly opts in via auto_sync: true
+# in .bassclef-source.json. Cold adopters get a one-line note + the
+# opt-in path instead of opaque auto-fetch.
+#
+# Default behavior on absence (file or field): OFF.
+#
+# Self-heal first (bet 2026-07-09a): stale adopters carrying
+# .canonical-source.json get the file renamed to .bassclef-source.json
+# so this pre-check sees the correct file. Second cycle drops the old.
+bassclef_sync_self_heal_pointer "$CWD"
+# Content-drift cure runs AFTER filename cure so the file we rewrite exists at the new name.
+bassclef_sync_self_heal_pointer_content "$CWD"
+# CLAUDE.md content cure runs at same lifecycle point — before Path 1 / Path 2 pick.
+bassclef_sync_self_heal_claude_md_content "$CWD"
+SOURCE_FILE_PRECHECK=$(bassclef_sync_resolve_pointer_file "$CWD")
+if [ -n "$SOURCE_FILE_PRECHECK" ] && [ -f "$SOURCE_FILE_PRECHECK" ]; then
+  AUTO_SYNC=$(jq -r '.auto_sync // false' "$SOURCE_FILE_PRECHECK" 2>/dev/null)
+  if [ "$AUTO_SYNC" != "true" ]; then
+    cat <<NOTE
+### bassclef-sync — auto-update is OFF
+
+Bassclef can keep your skills, rules, and agents current at every
+session start by pulling its latest substrate. It's off by default
+for fresh repos so nothing fetches without your say-so.
+
+Turn on anytime by saying "enable auto-sync" or by setting:
+
+    "auto_sync": true
+
+in .bassclef-source.json. Run a manual sync once with:
+
+    bash .claude/hooks/bassclef-sync.sh
+
+More: https://github.com/sunj-labs/bassclef/blob/main/standards/bassclef-source-config.md
+
+NOTE
+    exit 0
+  fi
+fi
+
+# === Plain-language error printer ===
+#
+# Args: $1 = short heading, $2 = context paragraph (one or more sentences).
+# Always exits 0 to keep SessionStart hooks non-blocking.
+emit_error() {
+  local heading="$1"
+  local context="$2"
+  cat <<HEADER
+
+### bassclef-sync — $heading
+
+$context
+
+Three ways to fix this:
+
+  1) PUBLIC adopters (most common)
+     Edit .bassclef-source.json to point at the public release tarball:
+
+       {
+         "source_url":  "https://github.com/sunj-labs/bassclef/releases/latest/download/substrate.tar.gz",
+         "auth_method": "none",
+         "token_env":   "",
+         "comment":     "Public bassclef substrate. No auth needed."
+       }
+
+     Pre-launch note: while bassclef is still private, the public
+     release URL above may not yet exist. Until it does, use option 3.
+
+  2) LOCAL DEV — clone bassclef alongside this repo
+
+       cd ../ && git clone https://github.com/sunj-labs/bassclef.git
+
+     Re-run your session. The dispatcher uses the local checkout via
+     the sibling fast-path; no auth needed.
+
+  3) PRIVATE / pre-launch — create a fine-grained GitHub PAT
+
+       a) GitHub -> Settings -> Developer settings -> Personal access tokens
+          -> Fine-grained -> Generate new token
+       b) Resource owner: sunj-labs
+       c) Repository access: select sunj-labs/bassclef only
+       d) Permissions -> Repository -> Contents -> Read
+       e) Set the token as BASSCLEF_TOKEN in your environment:
+            CI:         gh secret set BASSCLEF_TOKEN -R <your-org/your-repo>
+            Local:      export BASSCLEF_TOKEN=<paste>
+            Cloud Code: set BASSCLEF_TOKEN in your environment config
+
+  4) STALE REFERENCES — your repo installed bassclef before 2026-06-29
+
+       If your tree carries leftover canonical-* references from the
+       2026-06-20 rename event, refresh them in place by running the
+       migrate script directly:
+
+         curl -sL https://raw.githubusercontent.com/sunj-labs/bassclef/main/scripts/migrate-adopter-references.sh \\
+           | bash -s -- --apply "\$CWD"
+
+       Open a fresh Claude Code session afterward. The fresh dispatcher
+       carries detection that runs the cure automatically when needed.
+
+  More: https://github.com/sunj-labs/bassclef/blob/main/standards/bassclef-source-config.md
+        https://github.com/sunj-labs/bassclef/wiki/Troubleshooting#substrate-fails-to-load-and-you-do-not-see-the-self-heal-banner
+
+HEADER
+  exit 0
+}
+
+# === Recovery script resolver + checksum verifier ===
+#
+# Per goal 2026-08-27 step 7 PR #1 — cures external security review HIGH
+# finding on the self-heal curl|bash fallback (source audit tracked in
+# operator-only artifact; not shipped to public bassclef).
+#
+# Two functions cover Adam's Options A (bundle local) + B (checksum on curl).
+#
+# @pattern strategy (RecoveryScriptResolver picks one of three sources)
+# @pattern guard-clause (verify_checksum fails loud on mismatch)
+
+# resolve_recovery_script — prints one of:
+#   LOCAL:<path>        env override set + file exists
+#   SIBLING:<path>      sibling checkout has the script
+#   CURL:<url>|<sha>    neither available; use curl with checksum
+#
+# Priority chain per docs/decompositions/2026-08-27-step-7-pr-1-dispatcher-cure-responsibilities.md
+resolve_recovery_script() {
+  # Priority 1 — env override
+  if [ -n "${BASSCLEF_RECOVERY_SCRIPT_PATH:-}" ] && [ -f "$BASSCLEF_RECOVERY_SCRIPT_PATH" ]; then
+    printf 'LOCAL:%s\n' "$BASSCLEF_RECOVERY_SCRIPT_PATH"
+    return 0
+  fi
+
+  # Priority 2 — sibling checkout (matches SIBLING_TEMPLATE pattern at L594)
+  local sibling_script="${CWD:-$(pwd)}/../bassclef/scripts/migrate-adopter-references.sh"
+  if [ -f "$sibling_script" ]; then
+    printf 'SIBLING:%s\n' "$sibling_script"
+    return 0
+  fi
+
+  # Priority 3 — curl fallback with checksum sidecar
+  local recovery_url="https://raw.githubusercontent.com/sunj-labs/bassclef/main/scripts/migrate-adopter-references.sh"
+  local sha_url="${recovery_url}.sha256"
+  printf 'CURL:%s|%s\n' "$recovery_url" "$sha_url"
+  return 0
+}
+
+# verify_checksum <file> <expected_sha256>
+# Returns 0 on match; non-zero + loud stderr on mismatch or missing tool.
+# @luminary saltzer-schroeder — complete mediation; no silent pass.
+verify_checksum() {
+  local file="$1"
+  local expected="$2"
+  local computed=""
+
+  if command -v shasum >/dev/null 2>&1; then
+    computed=$(shasum -a 256 "$file" 2>/dev/null | awk '{print $1}')
+  elif command -v sha256sum >/dev/null 2>&1; then
+    computed=$(sha256sum "$file" 2>/dev/null | awk '{print $1}')
+  else
+    echo "verify_checksum: neither shasum nor sha256sum found in PATH" >&2
+    echo "verify_checksum: install one before continuing" >&2
+    return 2
+  fi
+
+  if [ -z "$computed" ]; then
+    echo "verify_checksum: could not compute SHA-256 of $file" >&2
+    return 3
+  fi
+
+  if [ "$computed" = "$expected" ]; then
+    return 0
+  fi
+
+  echo "verify_checksum: SHA-256 mismatch on $file" >&2
+  echo "verify_checksum: expected: $expected" >&2
+  echo "verify_checksum: computed: $computed" >&2
+  return 1
+}
+
+# === Canonical-* reference detection (per bet 29e WU-2) ===
+#
+# Self-heal for adopters carrying canonical-* references from the
+# 2026-06-20 rename. Scans the adopter .claude/ tree at session-start
+# BEFORE Path 1 / Path 2. When canonical-* refs are found, emits a
+# BLOCKED block naming the recovery command (curl one-liner shipped
+# in WU-3 of bet 29e) and exits 0 so SessionStart stays non-blocking.
+#
+# WU-2 emits BLOCKED + exits. WU-4 will rewrite this block to auto-
+# invoke the recovery and continue the dispatcher chain.
+#
+# Override: SKIP_CANONICAL_DETECTION=1 bypasses the scan. Reserved for
+# migration scripts; not for routine adopter use.
+#
+# Primary lens: @luminary michael-nygard — self-healing integration
+# point per Release It! Stability Patterns. Composing lenses:
+# @luminary jerome-saltzer-and-michael-schroeder (complete mediation —
+# every session-start sees the scan), @luminary tony-hoare (when no
+# canonical refs found, scan is silent; postcondition holds), @luminary
+# john-ousterhout (deep dispatcher hides migration complexity).
+if [ "${SKIP_CANONICAL_DETECTION:-0}" != "1" ]; then
+  CANONICAL_FINDINGS=()
+
+  # Surface 2: settings.json additionalDirectories contains "canonical"
+  SETTINGS_PATH="$CWD/.claude/settings.json"
+  if [ -f "$SETTINGS_PATH" ]; then
+    STALE_DIRS=$(jq -r '.permissions.additionalDirectories // [] | .[] | select(test("canonical"))' "$SETTINGS_PATH" 2>/dev/null || true)
+    if [ -n "$STALE_DIRS" ]; then
+      CANONICAL_FINDINGS+=(".claude/settings.json additionalDirectories contains canonical")
+    fi
+  fi
+
+  # Surface 3: vendored dispatcher BASSCLEF_SYNC_VERSION drift
+  # (per ADR-032 Layer 3 self-heal; mirrors migrate-adopter-references.sh Surface 3)
+  # Read the current version from the helper to avoid drift between the
+  # comment header, the function, and this constant.
+  CURRENT_VERSION=$(__bassclef_dispatcher_version)
+  for CANDIDATE in "$CWD/.claude/hooks/bassclef-sync.sh" "$CWD/.claude/hooks/canonical-sync.sh"; do
+    if [ -f "$CANDIDATE" ] && [ ! -L "$CANDIDATE" ]; then
+      VENDORED_VERSION=$(grep -m1 'BASSCLEF_SYNC_VERSION=' "$CANDIDATE" 2>/dev/null | sed 's/.*BASSCLEF_SYNC_VERSION=\([^ ]*\).*/\1/' | head -1)
+      if [ -z "$VENDORED_VERSION" ] || [[ "$VENDORED_VERSION" < "$CURRENT_VERSION" ]]; then
+        BASENAME=$(basename "$CANDIDATE")
+        DISPLAY_VERSION="${VENDORED_VERSION:-<missing>}"
+        CANONICAL_FINDINGS+=(".claude/hooks/$BASENAME stale (BASSCLEF_SYNC_VERSION=$DISPLAY_VERSION; current=$CURRENT_VERSION)")
+      fi
+      break
+    fi
+  done
+
+  if [ "${#CANONICAL_FINDINGS[@]}" -gt 0 ]; then
+    RECOVERY_URL="https://raw.githubusercontent.com/sunj-labs/bassclef/main/scripts/migrate-adopter-references.sh"
+    SIBLING_DISPATCHER_TEMPLATE="$CWD/../bassclef/presence/install/bassclef-sync.dispatcher.template.sh"
+    # Per bet 30a WU-5 (F7 cure): the migrate script reads three env vars
+    # for path overrides. Local layout sibling files for each.
+    SIBLING_RENAME_MAP="$CWD/../bassclef/standards/file-renames.json"
+    SIBLING_STATUSLINE_TEMPLATE="$CWD/../bassclef/presence/cli/bassclef-statusline.dispatcher.sh"
+
+    # Decide auto-invoke vs BLOCKED-only path (per bet 29e WU-4)
+    AUTO_INVOKE_READY=0
+    if [ "${SKIP_AUTO_INVOKE:-0}" != "1" ]; then
+      if [ -n "${BASSCLEF_RECOVERY_SCRIPT_PATH:-}" ] && [ -f "$BASSCLEF_RECOVERY_SCRIPT_PATH" ]; then
+        AUTO_INVOKE_READY=1
+      elif command -v curl >/dev/null 2>&1; then
+        AUTO_INVOKE_READY=1
+      fi
+    fi
+
+    if [ "$AUTO_INVOKE_READY" = "1" ]; then
+      # === Leg 3 of self-healing — auto-invocation (WU-4) ===
+      # Detection found canonical-* refs; run the migrate script
+      # automatically; continue the dispatcher chain afterward so the
+      # adopter sees one clean session-start (no second paste needed).
+      echo ""
+      echo "🩹 bassclef self-heal — canonical-* references detected; running recovery automatically"
+      for finding in "${CANONICAL_FINDINGS[@]}"; do
+        echo "  - $finding"
+      done
+
+      # Source the migrate script (env-var override for tests, curl in prod).
+      # Per bet 30a WU-5 (F7 cure): pass all three env vars the migrate
+      # script reads — DISPATCHER_TEMPLATE + RENAME_MAP + STATUSLINE_TEMPLATE
+      # — when their sibling files exist. Without these, the script's
+      # fallback expansion `$(cd "$(dirname "$0")/..")` resolves wrong
+      # under curl-pipe ($0 = bash), and Surfaces 5 + 6 silently no-op.
+      # POA was broken for 8+ days because only the dispatcher template
+      # env var was passed.
+      ENV_ARGS=()
+      [ -f "$SIBLING_DISPATCHER_TEMPLATE" ] && ENV_ARGS+=("BASSCLEF_DISPATCHER_TEMPLATE=$SIBLING_DISPATCHER_TEMPLATE")
+      [ -f "$SIBLING_RENAME_MAP" ] && ENV_ARGS+=("BASSCLEF_RENAME_MAP=$SIBLING_RENAME_MAP")
+      [ -f "$SIBLING_STATUSLINE_TEMPLATE" ] && ENV_ARGS+=("BASSCLEF_STATUSLINE_TEMPLATE=$SIBLING_STATUSLINE_TEMPLATE")
+
+      # Per bet 2026-08-27 step 7 PR #1 — resolver picks source with priority
+      # env override → sibling → curl+checksum. Verifier gates curl path.
+      RESOLVED=$(resolve_recovery_script)
+      RESOLVED_KIND="${RESOLVED%%:*}"
+      RESOLVED_REST="${RESOLVED#*:}"
+
+      case "$RESOLVED_KIND" in
+        LOCAL|SIBLING)
+          echo "🩹 recovery source: $RESOLVED_KIND ($RESOLVED_REST)" >&2
+          if [ "${#ENV_ARGS[@]}" -gt 0 ]; then
+            cat "$RESOLVED_REST" | env "${ENV_ARGS[@]}" bash -s -- --apply "$CWD" || true
+          else
+            cat "$RESOLVED_REST" | bash -s -- --apply "$CWD" || true
+          fi
+          ;;
+        CURL)
+          RECOVERY_URL_RESOLVED="${RESOLVED_REST%|*}"
+          SHA_URL="${RESOLVED_REST#*|}"
+          echo "🩹 recovery source: CURL ($RECOVERY_URL_RESOLVED)" >&2
+          TMP_SCRIPT=$(mktemp -t bassclef-recovery.XXXXXX.sh) || {
+            echo "⚠ bassclef self-heal: mktemp failed; skipping recovery" >&2
+            true
+          }
+          TMP_SHA=$(mktemp -t bassclef-recovery.XXXXXX.sha) || {
+            rm -f "$TMP_SCRIPT" 2>/dev/null
+            echo "⚠ bassclef self-heal: mktemp failed; skipping recovery" >&2
+            true
+          }
+          # Fetch both files; abort verify path if either fetch fails
+          if curl -sL --fail "$RECOVERY_URL_RESOLVED" -o "$TMP_SCRIPT" 2>/dev/null \
+             && curl -sL --fail "$SHA_URL" -o "$TMP_SHA" 2>/dev/null; then
+            EXPECTED_SHA=$(awk '{print $1}' "$TMP_SHA")
+            if verify_checksum "$TMP_SCRIPT" "$EXPECTED_SHA"; then
+              echo "🩹 recovery: checksum verified; executing" >&2
+              if [ "${#ENV_ARGS[@]}" -gt 0 ]; then
+                cat "$TMP_SCRIPT" | env "${ENV_ARGS[@]}" bash -s -- --apply "$CWD" || true
+              else
+                cat "$TMP_SCRIPT" | bash -s -- --apply "$CWD" || true
+              fi
+            else
+              echo "🛑 recovery: SHA-256 mismatch; refusing to execute" >&2
+              echo "   URL: $RECOVERY_URL_RESOLVED" >&2
+              echo "   To retry manually after investigating:" >&2
+              echo "   SKIP_CANONICAL_DETECTION=1 <re-run session>" >&2
+            fi
+          else
+            echo "⚠ bassclef self-heal: fetch failed for recovery or checksum" >&2
+            echo "   Falls back to manual recovery via BLOCKED path below" >&2
+          fi
+          rm -f "$TMP_SCRIPT" "$TMP_SHA" 2>/dev/null
+          ;;
+        *)
+          echo "⚠ bassclef self-heal: resolver returned unknown kind ($RESOLVED_KIND); skipping" >&2
+          ;;
+      esac
+
+      echo "🩹 bassclef self-heal: recovery applied; continuing"
+      echo ""
+      # Fall through to Path 1 / Path 2 — substrate now loadable
+    else
+      # === Fall back: BLOCKED + exit (WU-2 behavior) ===
+      # SKIP_AUTO_INVOKE=1 set, OR neither curl nor BASSCLEF_RECOVERY_SCRIPT_PATH
+      # available. Surface the recovery shape and stop here.
+      cat <<DETECT
+
+🛑 BLOCKED: bassclef substrate — canonical-* references detected
+
+Your adopter tree carries references from before the 2026-06-20
+canonical→bassclef rename. Bassclef cannot load substrate cleanly
+until these are repaired.
+
+Found:
+DETECT
+      for finding in "${CANONICAL_FINDINGS[@]}"; do
+        echo "  - $finding"
+      done
+      cat <<RECOVERY
+
+Recovery — one paste, no extra setup:
+
+  curl -sL $RECOVERY_URL | bash -s -- --apply "$CWD"
+
+After it runs, open a fresh Claude Code session in this repo.
+
+To skip this check once (override):  SKIP_CANONICAL_DETECTION=1
+To skip auto-invocation (manual recovery): SKIP_AUTO_INVOKE=1
+
+Refs: scripts/migrate-adopter-references.sh, .claude/rules/we-dont-break-adopters.md
+
+RECOVERY
+      exit 0
+    fi
+  fi
+fi
+
+# === Path 1. Sibling fast-path ===
+SIBLING_TEMPLATE="$CWD/../bassclef/presence/install/bassclef-sync.template.sh"
+if [ -f "$SIBLING_TEMPLATE" ]; then
+  echo "$INPUT" | bash "$SIBLING_TEMPLATE"
+  exit $?
+fi
+
+# === Path 2. Curl fallback ===
+# Uses the same resolver as auto_sync pre-check so old-name adopters
+# still get here (self-heal already fired above, but resolve for safety
+# in case self-heal was skipped via SKIP_SELF_HEAL_POINTER).
+SOURCE_FILE=$(bassclef_sync_resolve_pointer_file "$CWD")
+if [ -z "$SOURCE_FILE" ] || [ ! -f "$SOURCE_FILE" ]; then
+  emit_error "couldn't find bassclef substrate" \
+"This repo doesn't have a sibling bassclef checkout at ../bassclef AND
+doesn't have a .bassclef-source.json file to fetch from a remote source.
+
+The dispatcher needs ONE of those to load bassclef's substrate (skills,
+rules, hooks, luminaries) into your session."
+fi
+
+SOURCE_URL=$(jq -r '.source_url // empty' "$SOURCE_FILE")
+AUTH_METHOD=$(jq -r '.auth_method // "none"' "$SOURCE_FILE")
+TOKEN_ENV=$(jq -r '.token_env // "BASSCLEF_TOKEN"' "$SOURCE_FILE")
+
+if [ -z "$SOURCE_URL" ]; then
+  emit_error ".bassclef-source.json is missing source_url" \
+"Your .bassclef-source.json file exists but doesn't specify where to fetch
+bassclef from. The 'source_url' field is required.
+
+See standards/bassclef-source-config.md for the schema and provider
+examples (GitHub public release, GitHub private repo, Azure DevOps, GitLab)."
+fi
+
+# Resolve auth header from env-stored token.
+TOKEN_VALUE=""
+AUTH_HEADER=""
+if [ "$AUTH_METHOD" != "none" ]; then
+  TOKEN_VALUE=$(printenv "$TOKEN_ENV" 2>/dev/null || true)
+  if [ -z "$TOKEN_VALUE" ]; then
+    emit_error "auth token not set in environment" \
+"Your .bassclef-source.json uses auth_method '$AUTH_METHOD' and expects the
+'$TOKEN_ENV' environment variable to hold the token. That variable isn't set
+in this environment.
+
+If you're in CI:        the secret needs to be configured on the repo
+                        (gh secret set $TOKEN_ENV -R <repo>).
+If you're on a laptop:  export $TOKEN_ENV=<token> in your shell.
+If you're in Cloud Code: set $TOKEN_ENV in your environment config.
+
+If you don't have a token yet, follow option 3 below to create one."
+  fi
+  case "$AUTH_METHOD" in
+    Bearer) AUTH_HEADER="Authorization: Bearer $TOKEN_VALUE" ;;
+    Basic)  AUTH_HEADER="Authorization: Basic $(printf ':%s' "$TOKEN_VALUE" | base64)" ;;
+    *)      AUTH_HEADER="Authorization: $AUTH_METHOD $TOKEN_VALUE" ;;
+  esac
+fi
+
+# Fetch tarball
+TARBALL="/tmp/bassclef-thin-pointer-$$.tar.gz"
+if [ -n "$AUTH_HEADER" ]; then
+  HTTP_CODE=$(curl -sS -L -H "$AUTH_HEADER" -w "%{http_code}" -o "$TARBALL" "$SOURCE_URL" 2>/dev/null || echo "000")
+else
+  HTTP_CODE=$(curl -sS -L -w "%{http_code}" -o "$TARBALL" "$SOURCE_URL" 2>/dev/null || echo "000")
+fi
+
+if [ "$HTTP_CODE" != "200" ]; then
+  rm -f "$TARBALL" 2>/dev/null
+  emit_error "fetch returned HTTP $HTTP_CODE" \
+"The dispatcher tried to download bassclef from:
+
+    $SOURCE_URL
+
+The server returned HTTP $HTTP_CODE instead of 200. Common causes:
+
+  HTTP 401: token is invalid or expired. Regenerate it.
+  HTTP 403: token is valid but doesn't have the required permission
+            (needs Contents:read on the bassclef repo).
+  HTTP 404: source_url is wrong, OR the bassclef repo / release
+            doesn't exist at that URL.
+  HTTP 000: network couldn't reach the host. Check DNS / firewall /
+            whether you're offline."
+fi
+
+# Extract to a stable per-user location.
+BASSCLEF_FRESH="$HOME/bassclef-fresh"
+rm -rf "$BASSCLEF_FRESH" 2>/dev/null
+mkdir -p "$BASSCLEF_FRESH"
+if ! tar -xzf "$TARBALL" -C "$BASSCLEF_FRESH" --strip-components=1 2>/dev/null; then
+  rm -f "$TARBALL"
+  emit_error "couldn't extract the downloaded tarball" \
+"The dispatcher downloaded the file from $SOURCE_URL but tar -xzf failed.
+
+This usually means the response wasn't a real tarball. Check:
+
+  - Is source_url correct? It should return a gzipped tarball, not HTML.
+  - Is a network proxy / SSO portal injecting a login page instead?
+  - To inspect what the server is actually sending, run:
+
+      curl -sSL -H \"Authorization: ...\" \"$SOURCE_URL\" | file -
+
+    If the output says 'HTML document' instead of 'gzip compressed data',
+    you're being intercepted."
+fi
+rm -f "$TARBALL"
+
+# Exec the big template.
+#
+# Export the extracted tarball root so §3c-hooks (dynamic-derive hook connect,
+# per bassclef-upstream#625) can read bassclef's own .claude/settings.json.
+# The template sources presence/install/bassclef-hook-connect.sh and calls
+# bassclef_hook_connect_apply "$CWD" — the function reads
+# $BASSCLEF_SOURCE_ROOT/.claude/settings.json to learn the current hook list
+# across every event type, then merges every entry additively into the
+# adopter's settings.json.
+export BASSCLEF_SOURCE_ROOT="$BASSCLEF_FRESH"
+
+FALLBACK_TEMPLATE="$BASSCLEF_FRESH/presence/install/bassclef-sync.template.sh"
+if [ ! -f "$FALLBACK_TEMPLATE" ]; then
+  emit_error "tarball is missing bassclef-sync.template.sh" \
+"The dispatcher downloaded and extracted the tarball, but it doesn't
+contain presence/install/bassclef-sync.template.sh — bassclef's
+main sync logic.
+
+This usually means source_url points at a tarball that isn't bassclef
+(e.g., a different repo, or a branch / tag that's missing the template
+file). Verify the URL in .bassclef-source.json points at bassclef's
+main branch or a release that includes strategy/templates/."
+fi
+
+echo "$INPUT" | bash "$FALLBACK_TEMPLATE"
+exit $?