@thebassclef/lite 1.9.3 → 1.9.5

package/README.md

@@ -63,7 +63,7 @@ your browser.
 
 ## Current release
 
-<!-- version-start -->1.9.3<!-- version-end -->
+<!-- version-start -->1.9.5<!-- version-end -->
 
 See [CHANGELOG.md](CHANGELOG.md) for the full changelog. Adopter-facing
 release notes live at [docs.bassclef.dev/docs/whats-new/releases](https://docs.bassclef.dev/docs/whats-new/releases).

package/dist/index.cjs

@@ -1,4 +1,4 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const version = "1.9.3";
+const version = "1.9.5";
 exports.version = version;

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export declare const version: "1.9.3";
+export declare const version: "1.9.5";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,4 +1,4 @@
-const version = "1.9.3";
+const version = "1.9.5";
 export {
   version
 };

package/dist/lite/.claude/bassclef-orientation.md

@@ -145,3 +145,23 @@ Pick the tier that matches your trust + budget. Upgrade path is additive — no
 - `/skills` — phase-grouped skill catalog
 - `/luminary` — design-lens catalog
 - `/hooks` — mechanical-enforcement layer
+
+## Statusline (opt-in)
+
+Bassclef ships a statusline reader at `lib/statusline-version.sh`. When enabled, terminal Claude Code sessions render `bassclef v1.6.2 · up-to-date` at the bottom of every prompt. The reader consults `state/bassclef-sync-status.json` (written by `bassclef-sync.sh` at end-of-run) and `bassclef-version.json` at the repo root.
+
+Bassclef does not set the statusline at project scope. Adopter statusline choices survive untouched. To enable, add this block to your user-scope `~/.claude/settings.json`:
+
+```json
+{
+  "statusLine": {
+    "command": "bash /path/to/your/repo/lib/statusline-version.sh"
+  }
+}
+```
+
+Replace `/path/to/your/repo` with the actual repo root. Multiple repos work — the reader resolves `CLAUDE_PROJECT_DIR` at each invocation.
+
+Fallback behavior: if the state file is absent, the reader emits `bassclef · initializing`. If the version file is absent OR either file is malformed, the reader emits `bassclef · not synced`. Every path exits 0 with no stderr on the happy path.
+
+Ships bassclef-upstream#1961.

package/dist/lite/.claude/hooks/session-reflection.sh

@@ -111,6 +111,29 @@ blocked_banner() {
   echo ""
 }
 
+# Vendor-swap constant — the AI in the harness running bassclef. Adopter
+# swaps via BASSCLEF_AI_NAME env var; default reads as "Claude". Per
+# #1930 Category A design lock (2026-09-27T19:20:00Z ticket comment).
+AI_NAME="${BASSCLEF_AI_NAME:-Claude}"
+
+# guardrail_banner — sibling of blocked_banner() with softer tone for
+# discipline gates (chronicle stale, architect-review overdue, etc.).
+# Label ⚙ BASSCLEF DISCIPLINE GATE signals "pause + apply discipline",
+# not "something broke". Per #1930 Category A. Callers stay on
+# blocked_banner() until each is migrated one at a time; this helper
+# ships additive.
+guardrail_banner() {
+  local hook_name="$1"
+  local step="$2"
+  local retry="$3"
+  echo ""
+  echo "⚙ BASSCLEF DISCIPLINE GATE — $hook_name"
+  echo "────────────────────────────────────────────"
+  echo "bassclef is steering $AI_NAME to $step — $retry"
+  echo "────────────────────────────────────────────"
+  echo ""
+}
+
 # RFC-0008 F6 — this block is steering aimed at the agent, but the adopter
 # reads it too. Three imperatives and two shouted negations, before a single
 # check has run, read as "you already did something wrong". Say who it is

package/dist/lite/.claude/rules/blocked-items.md

@@ -8,6 +8,24 @@ description: "Session-start hook output may contain lines prefixed with BLOCKED:
 Session-start hook output may contain lines prefixed with `BLOCKED:`.
 These are not suggestions. They are mandatory scope.
 
+## Banner header shapes — two siblings
+
+Two banner shapes signal a blocked item. Both are valid discipline-gate
+signals. Machine readers grep the `BLOCKED:` prefix on body lines; both
+shapes preserve that prefix.
+
+- `🛑🛑🛑 BLOCKED 🛑🛑🛑` — historical shape from `blocked_banner()`.
+  Continues to fire for real defects (schema violation, dangling ref,
+  state corruption) and for gate hooks not yet migrated.
+- `⚙ BASSCLEF DISCIPLINE GATE — <hook>` — softer shape from
+  `guardrail_banner()`. Fires for discipline gates that ask the agent
+  to pause and apply discipline (chronicle stale, architect-review
+  overdue, temperance missing). Per sunj-labs/bassclef-upstream#1930
+  Category A.
+
+The agent treats both header shapes as siblings and follows the same
+resolve-or-explicitly-defer protocol regardless of which shape fires.
+
 ## Protocol
 
 1. **Before proposing any new work**, scan session-start output for

package/dist/lite/.claude/skills/longrun/SKILL.md

@@ -251,6 +251,72 @@ Rule: `.claude/rules/longrun-prep-plan-doc-compression.md`. Anchor luminaries: @
 Rationale: `/longrun prep` output ran too long. One shape did not fit every situation. Operator asked for a shape that reads clean in under 15 seconds. #1598 filed 2026-09-10; design session at 2026-09-12 picked the three presets under Path 2.
 <!-- /FKGL-EXEMPT -->
 
+<!-- FKGL-EXEMPT: Step 0.86 taxonomy — technical scope-class reference; short SVO loses precision on the class boundaries per bassclef-upstream#1978 -->
+**Step 0.86 — Scope class taxonomy (per bassclef-upstream#1978).** After the preset picks discipline shape, `/longrun` picks discipline depth per ticket. Preset (converged / exploratory / reversible-small) and class (a / b / c / d) are **orthogonal** — preset shapes how prep renders; class shapes how each ticket runs. A single `/longrun` may ship class-a and class-b tickets in the same converged prep.
+
+**Class label is optional.** When the ticket body or plan doc names a class, `/longrun` reads it. When neither names one, `/longrun` infers from the ticket body plus the preset (converged → class b or c; exploratory → class a; reversible-small → class a). Prior invocations without labels keep working through the grace window per `.claude/rules/we-dont-break-adopters.md`.
+
+## Scope class taxonomy
+
+Three base classes plus one modifier. Every ticket in scope carries one base class label. Class d layers on top when the ticket crosses a repo boundary.
+
+| Class | Fires when | Steps | Base ceremony |
+|---|---|---|---|
+| **class a — small fix** | ≤20 turns; single file; no adopter surface change | 5 | OOAD casual (commit body sentence) + `/luminary` lead + Beck RED-first + impl + `/verify` + PR |
+| **class b — script or hook extension** | adopter-facing script body change OR hook body change | 6 | brief use case + `/luminary consult` (lead + 1 supporting) + `/pre-mortem light` (2 lenses × 3-5 risks) + Beck RED-first + impl + `/verify` + PR |
+| **class c — new building block** | new hook / lib / skill / rule / standard / ADR | 8 | fully-dressed use case + `/decompose` + `/luminary consult` (lead + 2 supporting) + `/pre-mortem light` (3 lenses × 5-8 risks) + `/rfc adversarial` (3 outside lenses) + bootstrap pair + Beck RED-first + impl + `/verify` + PR + CI + admin merge |
+| **class d — cross-repo cure** | additive on top of a/b/c; ticket touches sibling repo | +3 | names sibling repos + release cascade + peer coordination via SendMessage + cold-adopter smoke post-merge |
+
+Ceremony rows cross-reference `.claude/rules/oo-ad-entry-point.md` matrix (existing ceremony-per-code-class rows). Class labels here map 1:1 to matrix rows there.
+
+## Discipline overrides
+
+Three named override patterns fire regardless of base class:
+
+- **/rfc adversarial when 2+ sister rules touched.** When the ticket changes behavior at 2+ rules (e.g., `.claude/rules/oo-ad-entry-point.md` + `.claude/rules/bootstrap-pair-discipline.md` + `.claude/rules/loop-discipline.md` together), dispatch `/rfc adversarial` with 3 outside lenses. Fold or reject per RFC council synthesis.
+- **Elevated consult when new decision surface.** When the ticket introduces a new operator-facing decision menu, picker, gate, OR class boundary, elevate `/luminary consult` from base (1 supporting) to elevated (2 supporting). The new decision surface deserves a wider lens set.
+- **Sibling smoke when adopter-observable Tier 0.** When the ticket touches adopter-observable Tier 0 substrate (e.g., `.claude/hooks/`, `.claude/skills/`, sync template), fire sibling smoke on a downstream adopter after PR merges but before release cascade. Runs the changed hook or skill on a real cold adopter clone; smokes the acceptance criteria.
+
+Every override composes with the base class — never replaces it. A class-b ticket with 2+ sister rules touched runs class-b discipline plus `/rfc adversarial`.
+
+## Luminary tier ladder
+
+`/longrun` runs on whatever tier the adopter's credentials support. Three-row fallback:
+
+| Tier | Prereq keys | Behavior | Notify shape |
+|---|---|---|---|
+| **ultra** | ANTHROPIC + VOYAGE | LLM picker + Voyage embeddings for luminary re-rank | stderr: `[longrun] tier=ultra (Voyage shortlist + Anthropic judge)`; inline: none |
+| **standard** | ANTHROPIC only | LLM picker against full catalog | stderr: `[longrun] tier=standard (Anthropic full catalog)`; inline: none |
+| **lite** | none | deterministic stub; skill dispatches without LLM signal | stderr: `[longrun] tier=lite (deterministic fallback; add ANTHROPIC_API_KEY for LLM picking)`; inline: one-line reminder that tier=lite fired |
+
+Tier detection lives in `lib/tier-check.sh`. This ladder is guidance for readers; the actual detection stays in the lib per @luminary david-parnas (information hiding — the ladder is what changes; mechanism stays hidden).
+
+## Class d cross-repo cure
+
+Class d is a **modifier**, not a base class. It layers on top of a/b/c whenever the ticket crosses a repo boundary. Three obligations fire in addition to the base class discipline:
+
+- **Name sibling repos.** In the PR body's Refs section, name every sibling repo the cure touches (e.g., `bassclef-cli#274`, `bassclef-web#256`). Cite the sister ticket URL when the sibling holds its own.
+- **Release cascade.** After the upstream PR merges, run `/release` dry-run + andon + live to ship the fix downstream. Per `.claude/skills/release/SKILL.md`.
+- **Peer coordination via SendMessage.** After the release page goes live, send a `SendMessage` to each affected sibling repo agent with the release URL + rebase-pin ask + smoke test ask. Address by `uds:/tmp/cc-socks/*.sock` per bassclef agent-to-agent protocol.
+- **Cold-adopter smoke post-merge.** For every substrate change that reaches an adopter, verify on a fresh cold-adopter install (peer runs docker smoke against the new package pinning the fresh release tag).
+
+## Refs
+
+- `.claude/rules/oo-ad-entry-point.md` — ceremony-per-code-class matrix; class labels here map 1:1
+- `.claude/rules/bootstrap-pair-discipline.md` — every new primitive ships with its paired bootstrap
+- `.claude/rules/loop-discipline.md` — 6-step + 3-substep cycle per PR
+- `.claude/rules/we-dont-break-adopters.md` — grace window keeps unlabeled prior invocations working
+- `docs/rfcs/2026-09-27-longrun-4class-taxonomy.md` — 3-outside-lens RFC (Torvalds + Feathers + Parnas)
+- `docs/risk-ledgers/2026-09-27-amend-1978-longrun-4class-taxonomy.md` — 3-lens pre-mortem (Ousterhout + Cooper + Prater)
+- `docs/use-cases/UC-skill-longrun-4class-taxonomy.md` — brief use case
+- @luminary john-ousterhout — lead (deep module — one lookup for discipline depth)
+- @luminary alan-cooper — supporting (satisficing default — 3 base classes fit the scan ceiling)
+- @luminary sophia-prater — supporting (progressive disclosure — orientation → labels → mechanisms)
+- @luminary linus-torvalds — outside lens (adopter contract preserved via grace window)
+- @luminary michael-feathers — outside lens (characterization test on the amended shape)
+- @luminary david-parnas — outside lens (SKILL body hides mechanism paths behind rule cross-references)
+<!-- /FKGL-EXEMPT -->
+
 **Step 0.87 — Amendment A1: OOAD chain read at pre-flight (per #1150 + #1167 + #1414).** When the goal doc references touch adopter app paths (`src/`, `apps/`, `packages/`, `app/`) OR substrate paths (`lib/`, `scripts/`, `.claude/hooks/`, `.claude/skills/`, `.claude/rules/`, `.claude/luminaries/`, `standards/state-spine/schemas/`, `presence/install/`) OR scope prose names UI or code work, read the design chain per `.claude/bassclef-orientation.md` L100-108. Ceremony depth scales per `.claude/rules/oo-ad-entry-point.md` matrix — script bug fix = skip tier; script extension = brief use case; hook + lib = fully-dressed:
 
 ```

package/dist/lite/.claude/skills/onboard-repo/SKILL.md

@@ -34,6 +34,39 @@ Run once per new consumer repo.
 - Re-onboarding a repo that pre-dates the bassclef substrate
 - Refreshing substrate wiring in an existing consumer (idempotent)
 
+## First-run greeting (state-detected)
+
+When the adopter just ran `bassclef init` and no other setup has advanced, the two most common paths are (a) share on GitHub and (b) top up local files. The full 4-option picker below covers every case; on a fresh install it reads longer than it needs to.
+
+**State detection.** The greeting fires when ALL three hold:
+
+- `.bassclef/init.manifest.json` exists at the repo root AND its `mtime` is under 24 hours old
+- `git remote get-url origin` fails OR no upstream is configured on the current branch
+- Current branch is `main` (or the repo's default)
+
+When any condition fails, the greeting is silent and the full picker below fires unchanged. This preserves the current path for older repos, existing remotes, and feature branches.
+
+**The greeting.** When state matches, emit:
+
+```
+Just ran bassclef init — welcome. Two most common paths from here:
+
+  1. I'll set up the GitHub remote and standard wiring.
+     (Same as Path A in the full picker.)
+  2. I'll top up the missing files on a `chore/bassclef-bootstrap`
+     branch. No remote work.
+     (Same as Path C in the full picker.)
+
+Neither of these? Type `skip` for the full picker (adds `browse` and
+`just me on this Mac` greenfield-from-intent options).
+```
+
+**Routing.** Answer `1` runs Path A. Answer `2` runs Path C. Answer `skip` — or any other input — falls through to the current 4-option picker below.
+
+Anchor luminaries — @luminary don-norman (signifier + affordance) + @luminary alan-cooper (state detection matches the fresh-init user model).
+
+Per `docs/use-cases/UC-skill-onboard-repo-friendlier-lead.md`.
+
 ## Which preset fits your setup?
 
 Pick the shape that matches how you plan to work. The picker is the first fork. The procedure below runs the phases that match your pick.

package/dist/lite/bassclef-version.json

@@ -1,7 +1,7 @@
 {
-  "version": "v1.5.2",
-  "marker_tag": "release-2026-09-25-26328f36",
-  "release_date": "2026-09-25T17:01:41Z",
-  "release_sha": "26328f36",
-  "release_tag": "release-2026-09-25-26328f36"
+  "version": "v1.6.3",
+  "marker_tag": "release-2026-09-27-39c21000",
+  "release_date": "2026-09-27T23:49:28Z",
+  "release_sha": "39c21000",
+  "release_tag": "release-2026-09-27-39c21000"
 }

package/dist/lite/lib/ancestor-claude-check.sh

@@ -22,8 +22,13 @@
 # Adopter cure hint printed to stderr per match — non-blocking:
 #   "cure: mv <path> <path>.stale-<date>"
 #
-# Ships bassclef-upstream#573. Sister to sibling ticket that adds the manual
-# audit step to the onboarding checklist.
+# Guard (bassclef-upstream#1958): the ceiling match on $HOME/.claude is
+# suppressed. $HOME/.claude is Claude Code's per-user config home; suggesting
+# `mv` on it would wipe adopter settings. Mid-walk cures for stale ancestor
+# .claude/ dirs still fire. Env override BASSCLEF_ANCESTOR_CHECK_SKIP_HOME_CLAUDE=0
+# disables the guard (used only by regression tests).
+#
+# Ships bassclef-upstream#573. Guard shipped bassclef-upstream#1958.
 #
 # Anchors:
 #   @luminary saltzer-schroeder — complete mediation (every ancestor level checked)
@@ -76,6 +81,19 @@ ancestor_claude_check() {
     return 1
   }
 
+  # Guard against destructive suggestions on $HOME/.claude (bassclef-upstream#1958).
+  # Claude Code stores per-user config under $HOME/.claude for every install.
+  # Suggesting `mv` on that path would wipe adopter settings. When the walker
+  # hits the canonicalized $HOME, skip both stdout and stderr for the .claude/
+  # match; mid-walk cures still fire. Env override
+  # BASSCLEF_ANCESTOR_CHECK_SKIP_HOME_CLAUDE=0 disables the guard (regression
+  # path for tests). Default = guard on (Nygard fail-safe default).
+  local guard_home_claude="${BASSCLEF_ANCESTOR_CHECK_SKIP_HOME_CLAUDE:-1}"
+  local protect_abs=""
+  if [ "$guard_home_claude" = "1" ] && [ -n "${HOME:-}" ] && [ -d "${HOME:-}" ]; then
+    protect_abs=$(cd "$HOME" && pwd -P)
+  fi
+
   # Walk from parent of start up to (and including) ceiling
   local cur="$start_abs"
   local today
@@ -83,8 +101,12 @@ ancestor_claude_check() {
   while [ "$cur" != "/" ]; do
     cur=$(dirname "$cur")
     if [ -d "$cur/.claude" ]; then
-      echo "$cur/.claude"
-      echo "cure: mv \"$cur/.claude\" \"$cur/.claude.stale-$today\"" >&2
+      if [ -n "$protect_abs" ] && [ "$cur" = "$protect_abs" ]; then
+        : # guarded — $cur is canonicalized $HOME; skip emit per bassclef-upstream#1958
+      else
+        echo "$cur/.claude"
+        echo "cure: mv \"$cur/.claude\" \"$cur/.claude.stale-$today\"" >&2
+      fi
     fi
     # Stop after processing ceiling — do not walk above it
     if [ "$cur" = "$ceiling_abs" ]; then

package/dist/lite/lib/bassclef-dir-resolver.sh

@@ -8,14 +8,17 @@
 # file at $HOME/.claude/hooks/, not a symlink to a checkout).
 #
 # The resolver probes four paths in order per Chain-of-Responsibility:
-#   1. Peer-checkout — $CWD/../bassclef with sentinel file present
-#   2. $HOME/bassclef — tarball adopter path with sentinel file present
-#   3. Bundled path — walk up from $HOOK_REAL_PATH with sentinel present
+#   1. Bundled path — walk up from $HOOK_REAL_PATH with sentinel present
+#      (was Check 3 pre-#1954; moved to Check 1 for #1953 shadow class cure —
+#       adopters with adjacent bassclef checkouts now get the npm install path)
+#   2. Peer-checkout — $CWD/../bassclef with sentinel file present
+#   3. $HOME/bassclef — tarball adopter path with sentinel file present
 #   4. Fallback — $CWD (adopter repo); safer than $HOME because the files
 #      fragments want ship into the repo via bassclef init
 #
 # The sentinel file is presence/install/bassclef-hook-connect.sh. Every
 # probe requires it — an empty peer dir or empty $HOME/bassclef does NOT win.
+# Nygard R1 fold — bundled probe fail-through preserves peer-checkout adopters.
 #
 # Silent contract: never crashes, never writes to stderr on the resolve path.
 # Consumers (13 fragments plus session-reflection.sh coordinator) treat the
@@ -42,17 +45,9 @@ resolve_bassclef_dir() {
   local home_dir="${HOME_OVERRIDE:-${HOME:-/nonexistent}}"
   local sentinel="presence/install/bassclef-hook-connect.sh"
 
-  # 1. Peer-checkout — sibling bassclef dir next to $CWD
-  if [ -d "$cwd/../bassclef" ] && [ -f "$cwd/../bassclef/$sentinel" ]; then
-    ( cd "$cwd/../bassclef" 2>/dev/null && pwd ) && return 0
-  fi
-
-  # 2. $HOME/bassclef — tarball adopter path
-  if [ -d "$home_dir/bassclef" ] && [ -f "$home_dir/bassclef/$sentinel" ]; then
-    printf '%s\n' "$home_dir/bassclef" && return 0
-  fi
-
-  # 3. Bundled path — walk up two levels from dispatcher
+  # 1. Bundled path — walk up two levels from dispatcher (SWAPPED to Check 1
+  #    per #1954 Layer 1a — closes #1953 shadow class where an adjacent
+  #    bassclef checkout at $CWD/../bassclef was winning over the npm install).
   if [ -n "$hook_path" ]; then
     local candidate
     candidate="$( cd "$(dirname "$hook_path")/../.." 2>/dev/null && pwd )" || candidate=""
@@ -61,6 +56,17 @@ resolve_bassclef_dir() {
     fi
   fi
 
+  # 2. Peer-checkout — sibling bassclef dir next to $CWD (Nygard R1 fold —
+  #    preserves peer-checkout adopters when bundled probe fails).
+  if [ -d "$cwd/../bassclef" ] && [ -f "$cwd/../bassclef/$sentinel" ]; then
+    ( cd "$cwd/../bassclef" 2>/dev/null && pwd ) && return 0
+  fi
+
+  # 3. $HOME/bassclef — tarball adopter path
+  if [ -d "$home_dir/bassclef" ] && [ -f "$home_dir/bassclef/$sentinel" ]; then
+    printf '%s\n' "$home_dir/bassclef" && return 0
+  fi
+
   # 4. Fallback — $CWD (adopter repo). Safer than $HOME because the files
   #    fragments want (init manifest, presence/install/*) ship into the repo.
   ( cd "$cwd" 2>/dev/null && pwd ) || printf '%s\n' "$cwd"

package/dist/lite/lib/capability-probe.sh

@@ -121,20 +121,14 @@ announce_mode() {
   echo "${skill}: running in \`${mode}\` mode — ${reason}. Say \`--mode=<other>\` to override." >&2
 }
 
-# --- Lib self-check on source ------------------------------------------------
-# Per R13 folded (Nygard stability): a broken lib should not silently return
-# FALSE for everything. Emit a WARN if any required function is missing.
-__bassclef_capability_probe_self_check() {
-  local missing=""
-  local f
-  for f in probe_git probe_gh_auth probe_mcp_playwright probe_network resolve_mode validate_mode announce_mode; do
-    type -t "$f" >/dev/null 2>&1 || missing="$missing $f"
-  done
-  if [ -n "$missing" ]; then
-    echo "WARN: lib/capability-probe.sh is missing functions:$missing" >&2
-    return 1
-  fi
-  return 0
-}
-
-__bassclef_capability_probe_self_check || true
+# --- Lib self-check removed (bassclef-upstream#1962) -------------------------
+# The runtime self-check at this location fired a false WARN against cold
+# `@thebassclef/lite@1.6.2` on bassclef-cli-aa smoke — every named function
+# was defined earlier in the same file yet `type -t` returned non-zero. Root
+# cause not reproduced in bassclef-upstream root. The Tier 0 test at
+# lib/tests/capability-probe.test.sh T02 already asserts every function
+# resolves after source. That test is a stricter signal (blocks merge on
+# regression) and lands more precisely (names missing functions) than the
+# runtime WARN. Per @luminary michael-nygard — a warning that fires on healthy
+# state erodes trust. Per @luminary michael-feathers — the characterization
+# test is the single source of truth for the contract.

package/dist/lite/lib/statusline-version.sh

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# tier: lite
+# lib/statusline-version.sh — bassclef statusline reader.
+#
+# Emits one plain-text line under 80 characters describing bassclef substrate
+# version + sync status. Called by Claude Code's statusLine.command hook every
+# ~300 ms; must be fast (< 20 ms typical) and fail-soft (exit 0 on every path).
+#
+# Reads:
+#   $REPO_ROOT/bassclef-version.json          — repo-root version file
+#   $REPO_ROOT/state/bassclef-sync-status.json — sync state (written by
+#                                                bassclef-sync.sh at end-of-run)
+#
+# Output shapes:
+#   bassclef v<version> · <sync_status>   — happy path (both files valid)
+#   bassclef · initializing               — state file absent
+#   bassclef · not synced                 — version file absent OR either
+#                                           file malformed JSON
+#
+# Adopter opt-in — user-scope ~/.claude/settings.json:
+#   {
+#     "statusLine": {
+#       "command": "bash /path/to/repo/lib/statusline-version.sh"
+#     }
+#   }
+#
+# Ships bassclef-upstream#1961.
+# Anchors:
+#   @luminary don-norman — signifier (always-visible substrate state)
+#   @luminary alan-cooper — persistent status over modal announcement
+#   @luminary michael-nygard — fail-soft; exit 0 on every path
+
+set +e  # fail-soft on every read; never crash the statusline
+
+# --- Resolve repo root ---
+_resolve_repo_root() {
+  if [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -d "${CLAUDE_PROJECT_DIR:-}" ]; then
+    echo "$CLAUDE_PROJECT_DIR"
+    return
+  fi
+  local root
+  root=$(git rev-parse --show-toplevel 2>/dev/null)
+  if [ -n "$root" ] && [ -d "$root" ]; then
+    echo "$root"
+    return
+  fi
+  pwd
+}
+
+# --- Emit under 80-char cap ---
+_emit() {
+  local line="$1"
+  # Cap at 80 chars per pre-mortem R1 fold.
+  if [ "${#line}" -gt 80 ]; then
+    line="${line:0:77}..."
+  fi
+  echo "$line"
+}
+
+# --- Main ---
+statusline_version() {
+  local root
+  root=$(_resolve_repo_root)
+
+  local version_file="$root/bassclef-version.json"
+  local status_file="$root/state/bassclef-sync-status.json"
+
+  # Version file — required for happy path
+  if [ ! -f "$version_file" ]; then
+    _emit "bassclef · not synced"
+    return 0
+  fi
+
+  local version
+  version=$(jq -r '.version // ""' "$version_file" 2>/dev/null)
+  if [ -z "$version" ]; then
+    # jq returned empty (malformed JSON or missing .version)
+    _emit "bassclef · not synced"
+    return 0
+  fi
+
+  # State file — absent means "sync has not run this session"
+  if [ ! -f "$status_file" ]; then
+    _emit "bassclef · initializing"
+    return 0
+  fi
+
+  local sync_status
+  sync_status=$(jq -r '.sync_status // ""' "$status_file" 2>/dev/null)
+  if [ -z "$sync_status" ]; then
+    # Malformed state file OR missing .sync_status field
+    _emit "bassclef · not synced"
+    return 0
+  fi
+
+  _emit "bassclef ${version} · ${sync_status}"
+  return 0
+}
+
+# When invoked directly (not sourced), emit the line.
+if [ "${BASH_SOURCE[0]:-}" = "${0}" ]; then
+  statusline_version
+fi

package/dist/lite/presence/cli/bassclef-statusline.dispatcher.sh

@@ -48,21 +48,40 @@ __bassclef_statusline_version() {
   echo "thin-pointer-statusline-2026-06-22"
 }
 
-# Read all of stdin so we can pipe it through to the rich impl
-INPUT=$(cat 2>/dev/null || echo "{}")
+# Read stdin only when it is a pipe. When stdin is a TTY (operator direct-
+# invokes for debugging), `cat` would block forever. Per bassclef-upstream#1981
+# defect A2: treat terminal stdin as empty input.
+if [ -t 0 ]; then
+  INPUT="{}"
+else
+  INPUT=$(cat 2>/dev/null || echo "{}")
+fi
 
-# Resolve this dispatcher's directory for the script-relative fallback.
-# `cd $(dirname); pwd` is portable across macOS (BSD readlink lacks -f) and
-# Linux (GNU readlink -f works but we don't need it).
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# Resolve this dispatcher's directory + canonical path for the script-relative
+# fallback + self-loop guard. `cd $(dirname); pwd -P` is portable across macOS
+# (BSD readlink lacks -f) and Linux, and resolves symlinks so a symlinked
+# install still matches the underlying rich-impl file.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+SELF_PATH="$SCRIPT_DIR/$(basename "${BASH_SOURCE[0]}")"
 
-# Find rich impl via sibling fast-path, then script-relative fallback
+# Find rich impl via sibling fast-path, then script-relative fallback. Self-
+# loop guard per bassclef-upstream#1981 defect A1: skip any candidate that
+# canonicalizes to this dispatcher's own path. Real adopter case — `bassclef
+# init` installs this dispatcher AS `~/.claude/bassclef-statusline.sh` (same
+# basename as the rich impl in the tarball). Without the guard, the script-
+# relative candidate resolves to the dispatcher itself; `bash $CANDIDATE`
+# then exec's the dispatcher forever.
 RICH_IMPL=""
 for CANDIDATE in \
     "$HOME/src/sunj-labs/bassclef/presence/cli/bassclef-statusline.sh" \
     "$HOME/src/sunj-labs/bassclef-upstream/presence/cli/bassclef-statusline.sh" \
     "$SCRIPT_DIR/bassclef-statusline.sh"; do
   if [ -x "$CANDIDATE" ]; then
+    # Canonicalize the candidate; skip when it matches SELF_PATH.
+    CAND_ABS="$(cd "$(dirname "$CANDIDATE")" 2>/dev/null && pwd -P)/$(basename "$CANDIDATE")"
+    if [ "$CAND_ABS" = "$SELF_PATH" ]; then
+      continue
+    fi
     RICH_IMPL="$CANDIDATE"
     break
   fi

package/dist/lite/presence/install/bassclef-hook-connect.sh

@@ -241,13 +241,58 @@ bassclef_hook_connect_apply() {
     echo "[bassclef-hook-connect] no tier declared in .bassclef-source.json — merging all wires (grace window). Set tier: lite to filter." >&2
   fi
 
+  # === Filter-on-read (bassclef-upstream#1954) ===
+  # For each bassclef hook command, verify the target file exists at
+  # $bassclef_root/.claude/hooks/<basename>. Skip any entry whose target is
+  # missing. Log every skip to stderr. Emit warn banner over threshold.
+  # Saltzer-Schroeder R4 fold — matches both $CLAUDE_PROJECT_DIR- and
+  # $HOME-prefixed commands via basename extraction from .claude/hooks/ path.
+  # Nygard R2 mitigation — [ -f ] with symlink follow.
+  local present_re=""
+  local skip_count=0
+  local skipped_targets_file="$adopter_cwd/.bassclef-hook-connect-skipped.$$.tmp"
+  : > "$skipped_targets_file"
+  local present_basenames_file="$adopter_cwd/.bassclef-hook-connect-present.$$.tmp"
+  : > "$present_basenames_file"
+  local bhc_cmd bhc_base bhc_target
+  while IFS= read -r bhc_cmd; do
+    [ -z "$bhc_cmd" ] && continue
+    bhc_base=$(echo "$bhc_cmd" | grep -oE '\.claude/hooks/[^"'"'"'[:space:]\\]+\.sh' | head -1 | sed 's#\.claude/hooks/##')
+    if [ -z "$bhc_base" ]; then
+      continue
+    fi
+    bhc_target="$bassclef_root/.claude/hooks/$bhc_base"
+    if [ -f "$bhc_target" ] || [ -L "$bhc_target" ]; then
+      echo "$bhc_base" >> "$present_basenames_file"
+    else
+      echo "$bhc_target" >> "$skipped_targets_file"
+      skip_count=$((skip_count + 1))
+      echo "[bassclef-hook-connect] skip — target missing at $bhc_target" >&2
+    fi
+  done < <(jq -r '.hooks // {} | to_entries[] | .value[]? | .hooks[]? | .command // empty' "$bassclef_settings" 2>/dev/null)
+
+  if [ -s "$present_basenames_file" ]; then
+    present_re=$(sort -u "$present_basenames_file" | sed 's/\.sh$//' | paste -sd'|' -)
+  fi
+
+  # Warn banner over threshold. Threshold=0 disables banner but per-skip
+  # stderr above still fires.
+  local warn_threshold="${BASSCLEF_HOOK_CONNECT_SKIP_WARN:-5}"
+  if [ "$skip_count" -gt 0 ] && [ "$warn_threshold" -gt 0 ] && [ "$skip_count" -gt "$warn_threshold" ]; then
+    echo "[bassclef-hook-connect] WARN — $skip_count entries skipped (target files missing). Top 3:" >&2
+    sort -u "$skipped_targets_file" | head -3 | sed 's/^/  - /' >&2
+    echo "  Set BASSCLEF_HOOK_CONNECT_SKIP_WARN=N to change threshold, or 0 to disable banner." >&2
+  fi
+  rm -f "$present_basenames_file" "$skipped_targets_file"
+
   # Merge every hook entry from every event type. Preserves operator-owned
   # entries. Adds bassclef entries under matching (event, matcher) pairs
   # without duplicating commands. Skips Lane 3 hooks at $CLAUDE_PROJECT_DIR
   # per <consumer-repo>#1262. Filters off-tier entries when tier_re non-empty
-  # per bassclef-upstream#1946.
+  # per bassclef-upstream#1946. Filters missing-target entries when
+  # present_re non-empty per bassclef-upstream#1954.
   local merged
-  merged=$(jq --slurpfile bassclef "$bassclef_settings" --arg lane3re "$lane3_re" --arg tierre "$tier_re" '
+  merged=$(jq --slurpfile bassclef "$bassclef_settings" --arg lane3re "$lane3_re" --arg tierre "$tier_re" --arg presentre "$present_re" '
     . as $adopter
     | ($bassclef[0].hooks // {}) as $bhooks
     | .hooks //= {}
@@ -264,6 +309,15 @@ bassclef_hook_connect_apply() {
             # tier manifest set. Empty tier_re means no filter (fallback).
             ($tierre == "") or
             ((.command // "") | test("\\.claude/hooks/(" + $tierre + ")\\.sh"))
+          )) | map(select(
+            # Filter-on-read (bassclef-upstream#1954): keep only entries whose
+            # target hook file exists at $bassclef_root/.claude/hooks/<basename>.
+            # Empty present_re means no filter (fallback merge-all — matches
+            # the tier filter fallback shape). Non-.claude/hooks commands pass
+            # through (not our target class).
+            ($presentre == "") or
+            ((.command // "") | test("\\.claude/hooks/[a-zA-Z0-9._-]+\\.sh") | not) or
+            ((.command // "") | test("\\.claude/hooks/(" + $presentre + ")\\.sh"))
           ))) as $bhookslist |
           if ($bhookslist | length) == 0 then .
           elif any(.hooks[$event][]; (.matcher // "") == $bmatcher) then