release: v9.1.0 — LIP v2.1 utilisation, index status UX, bug-pattern fix

Wire up three LIP v2.1 RPCs (stream_context, query_expansion,
explain_match), probe LIP index status on handshake and surface a
clear warning in `ckb review` when the daemon has no content.

Fix Lock() false positive in bug-patterns checker and eliminate err
shadowing in subscribe.go.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: SimplyLiz

CHANGELOG.md

@@ -4,79 +4,58 @@ All notable changes to CKB will be documented in this file.
 
 ## [Unreleased]
 
+## [9.1.0] - 2026-04-16
+
 ### Added
 
-- **`explainFile` surfaces semantically-related symbols** via LIP v2.1's
-  `stream_context` RPC (`internal/query/lip_stream_context.go`). The daemon
-  ranks symbols across the whole file within a 2048-token budget; CKB
-  returns the top 10 in the new `facts.related` field with per-symbol
-  relevance and token cost. Gated on the handshake's `supported_messages`
-  — older daemons fall through and the field is absent. New streaming
-  transport `internal/lip/stream_context.go` reads the daemon's N
-  `symbol_info` frames plus the `end_stream` terminator; previous LIP
-  client was unary-only.
-- **`searchSymbols` expands short queries** via LIP's `query_expansion`
-  RPC (`internal/query/query_expansion.go`). Queries of ≤ 2 tokens get up
-  to 5 related terms appended before hitting FTS5, recovering recall on
-  vocabulary-mismatch misses ("auth" → "authenticate authorization
-  principal…"). Gated on the handshake and on the same mixed-models flag
-  that protects the rerank path. Longer queries are passed through
-  unchanged — the expansion is a rescue, not a rewrite.
-- **Semantic hits carry evidence chunks** when LIP v2.0+'s `explain_match`
-  is advertised (`SemanticSearchWithLIPExplained` in
-  `internal/query/lip_ranker.go`). Each hit returned by the semantic
-  fallback path now includes up to two ranked chunks with line ranges,
-  text, and per-chunk scores — the caller can cite specific lines instead
-  of a bare file URL. Capped at the top-5 hits to bound round-trip cost.
+- **LIP v2.1 utilisation** — three high-ROI LIP RPCs wired into the query
+  engine, gated on the handshake's `supported_messages`:
+  - `stream_context` (v2.1) → `explainFile` attaches up to 10
+    semantically-related symbols (2048-token budget) in `facts.related`.
+    New streaming transport reads N `symbol_info` frames + `end_stream`.
+  - `query_expansion` (v1.6) → `searchSymbols` expands ≤ 2-token queries
+    with up to 5 related terms before FTS5, recovering vocabulary-mismatch
+    recall without touching precision on compound queries.
+  - `explain_match` (v2.0) → semantic search hits carry up to two ranked
+    evidence chunks with line ranges, text, and per-chunk scores (top-5
+    hits, bounded round-trip cost).
 - **`lip.Handshake` runs on engine startup** and the daemon's
   `supported_messages` list is stashed for feature gating
-  (`Engine.lipSupports`). The daemon version and supported-count are
-  logged on connect.
-
+  (`Engine.lipSupports`). Daemon version and supported-count logged.
+- **LIP index status probing** — `probeHandshake` now follows up with
+  `IndexStatus` and caches the result. New `Engine.LIPStatus()` returns
+  `{Reachable, IndexedFiles}` so consumers can distinguish "daemon down"
+  from "daemon up, nothing indexed."
+- **`ckb review` warns when LIP index is empty** — stderr advisory with
+  `lip index <repo>` command when daemon is reachable but has no content.
+  Suppressed in `--ci` to keep CI logs clean.
+- `NoAutoFetch` option on `SummarizePROptions` and `SummarizeDiffOptions`
+  for parity with `ReviewPROptions`.
+- Troubleshooting section in `docs/plans/review-cicd.md` covering shallow
+  CI clones, auth-failure remediation, air-gapped pipelines, and depth-0
+  checkout alternatives.
+- Auth-error detection on auto-fetch with clear remediation guidance.
+- `ckb review --no-auto-fetch` flag for air-gapped pipelines.
+- Test coverage for `GitAdapter.EnsureRef` — happy path, missing-ref
+  auto-fetch, unreachable origin, and empty-input guard.
 ### Changed
 
-- **`lipFileURI` path normalisation** — the helper that builds
-  `file://`-URIs for LIP requests used to naive-`filepath.Join` whatever
-  `Location.FileId` a backend supplied. Now handles absolute paths and
-  already-prefixed `file://` URIs without producing malformed results
-  like `file:///repo//abs/path`. Backends today return relative paths, so
-  this is a hardening fix for contracts that are nominally open.
-
-### Changed
+- **LIP health: push-driven, not polled** — Engine opens a long-lived
+  connection to the daemon at startup (`internal/lip/subscribe.go`) with
+  `index_changed` frames and per-ping `index_status` snapshots instead of
+  60 s TTL polling. Worst-case staleness drops from 60 s to ~3 s.
+- **`lipFileURI` path normalisation** — handles absolute paths and
+  already-prefixed `file://` URIs without producing malformed results.
 
-- **LIP health: push-driven, not polled** — the Engine now opens a long-lived
-  connection to the LIP daemon at startup (`internal/lip/subscribe.go`) and
-  receives `index_changed` frames plus per-ping `index_status` snapshots
-  instead of issuing a fresh `IndexStatus` RPC on a 60 s TTL. Worst-case
-  staleness for the mixed-models gate drops from 60 s to ~3 s, the hot query
-  path is lock-free (no RPC, no dial, no TTL check), and the subscriber
-  reconnects with exponential backoff when the daemon restarts. The old
-  `lipHealthTTL` constant is gone; callers read the cached flag directly.
+### Fixed
 
-### Added
+- **Bug-pattern false positive on `sync.Mutex.Lock()`** — removed `"Lock"`
+  from `LikelyReturnsError` heuristic patterns; `sync.Mutex.Lock` returns
+  nothing and dominated real-world matches with false positives.
+- **`err` shadowing in `subscribe.go`** — four shadow sites eliminated by
+  reusing outer `err` or renaming to `pingErr`/`readErr` where scope
+  isolation requires it.
 
-- `NoAutoFetch` option on `SummarizePROptions` and `SummarizeDiffOptions`
-  for parity with `ReviewPROptions`. Previously the air-gapped opt-out
-  applied only to `ckb review`; MCP/HTTP callers of `summarizePr` and
-  `summarizeDiff` had no way to disable auto-fetch.
-- Troubleshooting section in `docs/plans/review-cicd.md` covering shallow
-  CI clones, auth-failure remediation (`persistCredentials`), air-gapped
-  pipelines, and depth-0 checkout alternatives.
-- Auth-error detection on auto-fetch: when `git fetch` fails with
-  `Authentication failed`, `could not read Username`, `terminal prompts
-  disabled`, `401 Unauthorized`, `403 Forbidden`, `Permission denied
-  (publickey)`, or `repository ... not found`, the review error now names
-  the root cause (stripped CI credentials) and points at
-  `persistCredentials` / `--no-auto-fetch` as remediations, instead of
-  dumping raw git stderr.
-- `ckb review --no-auto-fetch` flag disables the automatic fetch of a
-  missing base ref introduced in 9.0.1. Also exposed on `ReviewPROptions`
-  as `noAutoFetch` for MCP / HTTP callers. Useful in air-gapped pipelines
-  where network activity outside the checkout step is forbidden; review
-  fails with a clear "ref not present locally" error instead.
-- Test coverage for `GitAdapter.EnsureRef` — happy path, missing-ref
-  auto-fetch, unreachable origin, and empty-input guard — using isolated
-  bare+clone repo pairs in temp dirs.
 - **LIP rerank: coherence gate + position-weighted seeding** (#209) — the
   Fast-tier semantic rerank (`internal/query/lip_ranker.go`) used to average the
   top-5 seed embeddings with uniform weight and always apply the result. When

cmd/ckb/review.go

@@ -233,6 +233,8 @@ func runReview(cmd *cobra.Command, args []string) {
 		NoAutoFetch: reviewNoAutoFetch,
 	}
 
+	warnIfLIPIndexEmpty(engine, repoRoot)
+
 	response, err := engine.ReviewPR(ctx, opts)
 	if err != nil {
 		fmt.Fprintf(os.Stderr, "Error running review: %v\n", err)
@@ -314,6 +316,27 @@ func runReview(cmd *cobra.Command, args []string) {
 	}
 }
 
+// warnIfLIPIndexEmpty prints a stderr advisory when the LIP daemon is
+// reachable but has no content indexed. Semantic enrichment (stream_context,
+// query_expansion, explain_match) silently returns empty in that case, which
+// is indistinguishable from "feature disabled" from the user's side — so we
+// tell them and show the exact command to build the index.
+//
+// The warning goes to stderr so it doesn't pollute JSON/SARIF stdout that
+// CI pipelines parse. Suppressed in --ci mode to keep CI logs tight.
+func warnIfLIPIndexEmpty(engine *query.Engine, repoRoot string) {
+	if reviewCI {
+		return
+	}
+	s := engine.LIPStatus()
+	if !s.Reachable || s.IndexedFiles > 0 {
+		return
+	}
+	fmt.Fprintln(os.Stderr, "⚠ LIP daemon reachable but has no index for this workspace.")
+	fmt.Fprintln(os.Stderr, "  Semantic enrichment (related symbols, query expansion, explain-match) will be skipped.")
+	fmt.Fprintf(os.Stderr, "  Run:  lip index %s\n\n", repoRoot)
+}
+
 // --- Output Formatters ---
 
 func formatReviewHuman(resp *query.ReviewPRResponse) string {

internal/backends/scip/symbols.go

@@ -513,14 +513,17 @@ func LikelyReturnsError(symbolName string) bool {
 		return false
 	}
 
-	// Common Go stdlib/convention patterns for error-returning functions
+	// Common Go stdlib/convention patterns for error-returning functions.
+	// "Lock" is deliberately absent: sync.{Mutex,RWMutex}.Lock dominates real
+	// code and returns nothing, so the rule produces far more false positives
+	// than the rare file-lock true positive it would catch.
 	errorPatterns := []string{
 		"Open", "Read", "Write", "Close", "Create",
 		"Dial", "Listen", "Accept", "Connect",
 		"Parse", "Unmarshal", "Marshal", "Decode", "Encode",
 		"Execute", "Exec", "Query",
 		"Send", "Recv", "Flush",
-		"Lock", "Acquire",
+		"Acquire",
 		"Start", "Stop", "Init", "Setup",
 	}
 

internal/lip/subscribe.go

@@ -110,7 +110,7 @@ func runSession(ctx context.Context, h SubscribeHandler) error {
 		defer writeMu.Unlock()
 		return writeFrame(conn, map[string]any{"type": "index_status"})
 	}
-	if err := ping(); err != nil {
+	if err = ping(); err != nil {
 		return err
 	}
 
@@ -123,7 +123,7 @@ func runSession(ctx context.Context, h SubscribeHandler) error {
 			case <-sessCtx.Done():
 				return
 			case <-t.C:
-				if err := ping(); err != nil {
+				if pingErr := ping(); pingErr != nil {
 					cancel()
 					return
 				}
@@ -136,11 +136,11 @@ func runSession(ctx context.Context, h SubscribeHandler) error {
 		if sessCtx.Err() != nil {
 			break
 		}
-		frame, err := readFrame(conn)
-		if err != nil {
+		frame, readErr := readFrame(conn)
+		if readErr != nil {
 			cancel()
 			wg.Wait()
-			return err
+			return readErr
 		}
 		dispatchFrame(frame, h)
 	}
@@ -206,7 +206,7 @@ func writeFrame(conn net.Conn, payload any) error {
 	lenBuf := make([]byte, 4)
 	binary.BigEndian.PutUint32(lenBuf, uint32(len(b)))
 	_ = conn.SetWriteDeadline(time.Now().Add(2 * time.Second))
-	if _, err := conn.Write(append(lenBuf, b...)); err != nil {
+	if _, err = conn.Write(append(lenBuf, b...)); err != nil {
 		return err
 	}
 	return nil

internal/query/engine.go

@@ -80,6 +80,12 @@ type Engine struct {
 	lipHealthCheckedAt time.Time
 	lipSupported       map[string]struct{}
 	lipSubCancel       context.CancelFunc
+	// lipIndexProbed is true once probeHandshake has attempted an IndexStatus
+	// call. lipIndexedFiles==0 with lipIndexProbed==true means the daemon is
+	// reachable but has nothing indexed — surface this to the user so semantic
+	// enrichment silence doesn't look like a bug.
+	lipIndexProbed  bool
+	lipIndexedFiles int
 
 	// Cache stats
 	cacheStatsMu sync.RWMutex

internal/query/lip_health.go

@@ -96,14 +96,58 @@ func (e *Engine) probeHandshake() {
 	for _, m := range info.SupportedMessages {
 		supported[m] = struct{}{}
 	}
+
+	// Follow up with a cheap IndexStatus probe so callers can distinguish
+	// "daemon down" from "daemon up but has no content for this workspace".
+	// Failures here are non-fatal — we just leave lipIndexProbed=false and
+	// consumers treat that as "unknown, don't warn".
+	status, _ := lip.IndexStatus()
+
 	e.lipHealthMu.Lock()
 	e.lipSupported = supported
+	if status != nil {
+		e.lipIndexProbed = true
+		e.lipIndexedFiles = status.IndexedFiles
+	}
 	e.lipHealthMu.Unlock()
+
 	if e.logger != nil {
+		files := -1
+		if status != nil {
+			files = status.IndexedFiles
+		}
 		e.logger.Info("LIP handshake",
 			"daemon_version", info.DaemonVersion,
 			"protocol_version", info.ProtocolVersion,
 			"supported_count", len(info.SupportedMessages),
+			"indexed_files", files,
 		)
 	}
 }
+
+// LIPIndexStatus is a UX-facing snapshot of LIP daemon reachability and
+// workspace coverage. Consumers (e.g. `ckb review`, `ckb status`) call this
+// after engine startup to decide whether to show a "no LIP index" warning.
+//
+//   - Reachable=false: daemon not running or handshake didn't complete.
+//     Silence is expected; no warning.
+//   - Reachable=true, IndexedFiles=0: daemon up, nothing indexed. Semantic
+//     enrichment will silently return empty — warn the user and offer the
+//     `lip index` command.
+//   - Reachable=true, IndexedFiles>0: happy path.
+type LIPIndexStatus struct {
+	Reachable     bool
+	IndexedFiles  int
+	DaemonVersion string
+}
+
+// LIPStatus returns the cached handshake + IndexStatus snapshot captured at
+// engine startup. Cheap — no RPC on the hot path.
+func (e *Engine) LIPStatus() LIPIndexStatus {
+	e.lipHealthMu.RLock()
+	defer e.lipHealthMu.RUnlock()
+	return LIPIndexStatus{
+		Reachable:    e.lipIndexProbed,
+		IndexedFiles: e.lipIndexedFiles,
+	}
+}

internal/version/version.go

@@ -6,7 +6,7 @@ package version
 // go build -ldflags "-X github.com/SimplyLiz/CodeMCP/internal/version.Version=1.0.0 -X github.com/SimplyLiz/CodeMCP/internal/version.Commit=abc123"
 var (
 	// Version is the semantic version of CKB
-	Version = "9.0.1"
+	Version = "9.1.0"
 
 	// Commit is the git commit hash (set at build time)
 	Commit = "unknown"

npm/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tastehub/ckb",
   "mcpName": "io.github.SimplyLiz/ckb",
-  "version": "9.0.1",
+  "version": "9.1.0",
   "description": "Code intelligence for AI assistants (MCP), CLI, and HTTP API - symbol navigation, impact analysis, architecture",
   "keywords": [
     "mcp",

testdata/review/sarif.json

@@ -268,8 +268,8 @@
               }
             }
           ],
-          "semanticVersion": "9.0.1",
-          "version": "9.0.1"
+          "semanticVersion": "9.1.0",
+          "version": "9.1.0"
         }
       }
     }