fix(index): purge stale donor-seeded file records + freshness TTL cache + debug logging

.github/workflows/ci.yml

@@ -10,6 +10,7 @@ jobs:
   test:
     name: Test
     runs-on: ubuntu-latest
+    timeout-minutes: 30
     steps:
       - uses: actions/checkout@v4
 
@@ -18,10 +19,24 @@ jobs:
           go-version: '1.26'
           cache: true
 
+      - name: Setup ccache
+        uses: hendrikmuhs/ccache-action@v1.2
+        with:
+          key: ${{ runner.os }}-go-cgo
+          max-size: 500M
+
       - name: Test
-        run:
-          CGO_ENABLED=1 go test -tags=fts5 -coverprofile=coverage.out
-          -covermode=atomic ./...
+        run: |
+          # Use ccache to speed up repeated CGO (C) compilation of sqlite3/tree-sitter.
+          export CC="ccache gcc"
+          export CXX="ccache g++"
+          # Print a heartbeat every 60 s so GitHub Actions does not kill the
+          # runner during the silent CGO (sqlite3) compilation phase.
+          (while true; do echo "[ci] tests still running…"; sleep 60; done) &
+          HEARTBEAT=$!
+          trap "kill $HEARTBEAT 2>/dev/null || true" EXIT
+          CGO_ENABLED=1 go test -p 1 -tags=fts5 -timeout=30m \
+            -coverprofile=coverage.out -covermode=atomic ./...
 
       - name: Upload coverage to Coveralls
         uses: coverallsapp/github-action@v2

.gitignore

@@ -12,10 +12,14 @@ dist/
 .DS_Store
 
 # Claude
-.claude/*.local.json
+**/.claude/*.local.json
 .worktrees/
 
 lumen
 
 bench-swe/bench-swe
 bench-swe/overview.txt
+
+**/.claude/worktrees
+**/.claire
+.worktrees

README.md

@@ -64,6 +64,10 @@ _Claude Code asking about the
 
 **Prerequisites:**
 
+> **Platform support:** Linux, macOS, and Windows. File locking for background
+> indexing coordination uses `flock(2)` on Unix and `LockFileEx` on Windows
+> (via [gofrs/flock](https://github.com/gofrs/flock)).
+
 1. [Ollama](https://ollama.com/) installed and running, then pull the default
    embedding model:
    ```bash

cmd/hook.go

@@ -18,7 +18,6 @@ import (
 	"encoding/json"
 	"fmt"
 	"os"
-	"os/exec"
 	"path/filepath"
 	"strings"
 
@@ -80,6 +79,10 @@ func runHookSessionStart(_ *cobra.Command, args []string) error {
 		cwd, _ = os.Getwd()
 	}
 
+	// Kick off a background incremental re-index so the index is fresh
+	// by the time the first semantic_search arrives.
+	spawnBackgroundIndexer(cwd)
+
 	content := generateSessionContext(mcpName, cwd)
 
 	out := hookOutput{
@@ -150,18 +153,6 @@ func generateSessionContextInternal(mcpName, cwd string, findDonor func(string,
 	return sb.String()
 }
 
-// spawnBackgroundIndexer runs "lumen index <cwd>" as a detached background
-// process. Errors are silently ignored — the MCP server will index on demand
-// if pre-warming fails or hasn't finished by the time the first search arrives.
-func spawnBackgroundIndexer(cwd string) {
-	exe, err := os.Executable()
-	if err != nil {
-		return
-	}
-	cmd := exec.Command(exe, "index", cwd)
-	_ = cmd.Start()
-}
-
 // --- PreToolUse hook ---
 
 var hookPreToolUseCmd = &cobra.Command{

cmd/hook_spawn_unix.go

@@ -0,0 +1,56 @@
+//go:build !windows
+
+// Copyright 2026 Aeneas Rekkas
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package cmd
+
+import (
+	"os"
+	"os/exec"
+	"path/filepath"
+	"syscall"
+
+	"github.com/ory/lumen/internal/config"
+)
+
+// spawnBackgroundIndexer launches "lumen index <projectPath>" as a fully
+// detached background process (new session via Setsid). The spawned process
+// acquires an advisory flock before indexing, so concurrent calls from
+// multiple Claude terminals are safe — only one indexer runs at a time.
+//
+// Errors are silently ignored: background indexing is best-effort. If it
+// fails, the MCP server falls back to its normal lazy EnsureFresh path.
+func spawnBackgroundIndexer(projectPath string) {
+	exe, err := os.Executable()
+	if err != nil {
+		return
+	}
+	cmd := exec.Command(exe, "index", projectPath)
+	cmd.SysProcAttr = &syscall.SysProcAttr{Setsid: true}
+	cmd.Stdout = nil
+
+	logPath := filepath.Join(config.XDGDataDir(), "lumen", "debug.log")
+	if f, err := os.OpenFile(logPath, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o644); err == nil {
+		cmd.Stderr = f
+		defer func() { _ = f.Close() }()
+	}
+
+	if err := cmd.Start(); err != nil {
+		return
+	}
+	// Reap the child to avoid a zombie process entry. The goroutine exits
+	// when the detached indexer terminates (or immediately if Start failed).
+	go func() { _ = cmd.Wait() }()
+}

cmd/hook_spawn_windows.go

@@ -0,0 +1,56 @@
+//go:build windows
+
+// Copyright 2026 Aeneas Rekkas
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package cmd
+
+import (
+	"os"
+	"os/exec"
+	"path/filepath"
+	"syscall"
+
+	"github.com/ory/lumen/internal/config"
+)
+
+// spawnBackgroundIndexer launches "lumen index <projectPath>" as a detached
+// background process on Windows using CREATE_NEW_PROCESS_GROUP and
+// DETACHED_PROCESS flags. The spawned process acquires an advisory lock
+// (via LockFileEx) before indexing, so concurrent calls are safe.
+//
+// Errors are silently ignored: background indexing is best-effort.
+func spawnBackgroundIndexer(projectPath string) {
+	exe, err := os.Executable()
+	if err != nil {
+		return
+	}
+	cmd := exec.Command(exe, "index", projectPath)
+	cmd.SysProcAttr = &syscall.SysProcAttr{
+		CreationFlags: syscall.CREATE_NEW_PROCESS_GROUP | 0x00000008, // DETACHED_PROCESS
+	}
+	cmd.Stdout = nil
+
+	logPath := filepath.Join(config.XDGDataDir(), "lumen", "debug.log")
+	if f, err := os.OpenFile(logPath, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o644); err == nil {
+		cmd.Stderr = f
+		defer f.Close()
+	}
+
+	if err := cmd.Start(); err != nil {
+		return
+	}
+	// Reap the child to avoid resource leaks.
+	go func() { _ = cmd.Wait() }()
+}

cmd/hook_test.go

@@ -24,6 +24,21 @@ import (
 	"github.com/ory/lumen/internal/config"
 )
 
+// TestMain detects when the cmd test binary is invoked as a background
+// indexer subprocess (via spawnBackgroundIndexer → os.Executable()) and exits
+// immediately instead of running the full test suite.  Without this guard,
+// TestSpawnBackgroundIndexer_DoesNotPanic would create a fork-bomb: the
+// spawned test binary runs all tests, which spawns more binaries, etc.
+func TestMain(m *testing.M) {
+	// spawnBackgroundIndexer calls: exec.Command(exe, "index", projectPath)
+	// where exe == os.Executable() == this test binary.
+	// Detect that pattern and exit cleanly so no tests run in the subprocess.
+	if len(os.Args) > 1 && os.Args[1] == "index" {
+		os.Exit(0)
+	}
+	os.Exit(m.Run())
+}
+
 func TestGenerateSessionContext_NoIndex(t *testing.T) {
 	// Use the internal version with a no-op bgIndexer to avoid spawning the
 	// test binary as a background process (which would trigger a fork bomb:
@@ -283,3 +298,12 @@ func TestHookOutputJSON(t *testing.T) {
 		t.Error("additionalContext should contain tool reference")
 	}
 }
+
+// TestSpawnBackgroundIndexer_DoesNotPanic verifies that spawnBackgroundIndexer
+// does not panic or block on a path that contains no indexable files.
+// The spawned process will acquire the lock, find nothing to index, and exit.
+func TestSpawnBackgroundIndexer_DoesNotPanic(t *testing.T) {
+	// Use a temp directory — no Go files, so the indexer exits quickly.
+	spawnBackgroundIndexer(t.TempDir())
+	// If we reach here without panic or deadlock, the test passes.
+}

cmd/index.go

@@ -18,12 +18,15 @@ import (
 	"context"
 	"fmt"
 	"os"
+	"os/signal"
 	"path/filepath"
+	"syscall"
 	"time"
 
 	"github.com/ory/lumen/internal/config"
 	"github.com/ory/lumen/internal/embedder"
 	"github.com/ory/lumen/internal/index"
+	"github.com/ory/lumen/internal/indexlock"
 	"github.com/ory/lumen/internal/tui"
 	"github.com/spf13/cobra"
 )
@@ -56,17 +59,47 @@ func runIndex(cmd *cobra.Command, args []string) error {
 		return fmt.Errorf("resolve path: %w", err)
 	}
 
-	idx, err := setupIndexer(&cfg, projectPath)
+	dbPath := config.DBPathForProject(projectPath, cfg.Model)
+	if err := os.MkdirAll(filepath.Dir(dbPath), 0o755); err != nil {
+		return fmt.Errorf("create db directory: %w", err)
+	}
+
+	lockPath := indexlock.LockPathForDB(dbPath)
+	lock, err := indexlock.TryAcquire(lockPath)
+	if err != nil {
+		return fmt.Errorf("acquire index lock: %w", err)
+	}
+	if lock == nil {
+		// Another indexer is already running for this project — skip silently.
+		// This is the normal case when multiple Claude terminals are open.
+		fmt.Fprintln(os.Stderr, "Another indexer is already running for this project. Skipping.")
+		return nil
+	}
+	defer lock.Release()
+
+	// Cancel context on SIGTERM or SIGINT so the indexer stops cleanly and
+	// the deferred lock.Release() runs before exit.
+	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGTERM, syscall.SIGINT)
+	defer stop()
+
+	idx, err := setupIndexer(&cfg, dbPath)
 	if err != nil {
 		return err
 	}
+	defer func() { _ = idx.Close() }()
 
 	p := tui.NewProgress(os.Stderr)
 	p.Info(fmt.Sprintf("Indexing %s (model: %s, dims: %d)", projectPath, cfg.Model, cfg.Dims))
 
 	start := time.Now()
-	stats, err := performIndexing(cmd, idx, projectPath, p)
+	stats, err := performIndexing(ctx, cmd, idx, projectPath, p)
 	if err != nil {
+		if ctx.Err() != nil {
+			// A signal arrived; treat as clean exit. If an unrelated error
+			// also occurred in the same instant, it is intentionally dropped —
+			// the cancellation is the primary cause and the lock will be released.
+			return nil
+		}
 		return err
 	}
 
@@ -90,43 +123,30 @@ func applyModelFlag(cmd *cobra.Command, cfg *config.Config) error {
 	return nil
 }
 
-func setupIndexer(cfg *config.Config, projectPath string) (*index.Indexer, error) {
+// setupIndexer receives dbPath so it is computed exactly once in runIndex.
+func setupIndexer(cfg *config.Config, dbPath string) (*index.Indexer, error) {
 	emb, err := newEmbedder(*cfg)
 	if err != nil {
 		return nil, fmt.Errorf("create embedder: %w", err)
 	}
 
-	dbPath := config.DBPathForProject(projectPath, cfg.Model)
-	if err := os.MkdirAll(filepath.Dir(dbPath), 0o755); err != nil {
-		return nil, fmt.Errorf("create db directory: %w", err)
-	}
-
-	// Seed from a sibling worktree index if this is a brand-new index.
-	if _, statErr := os.Stat(dbPath); os.IsNotExist(statErr) {
-		if donorPath := config.FindDonorIndex(projectPath, cfg.Model); donorPath != "" {
-			if _, seedErr := index.SeedFromDonor(donorPath, dbPath); seedErr != nil {
-				_, _ = fmt.Fprintf(os.Stderr, "lumen: seed from worktree failed: %v\n", seedErr)
-			}
-		}
-	}
-
 	idx, err := index.NewIndexer(dbPath, emb, cfg.MaxChunkTokens)
 	if err != nil {
 		return nil, fmt.Errorf("create indexer: %w", err)
 	}
 	return idx, nil
 }
 
-func performIndexing(cmd *cobra.Command, idx *index.Indexer, projectPath string, p *tui.Progress) (index.Stats, error) {
+func performIndexing(ctx context.Context, cmd *cobra.Command, idx *index.Indexer, projectPath string, p *tui.Progress) (index.Stats, error) {
 	force, _ := cmd.Flags().GetBool("force")
 
 	progress := p.AsProgressFunc()
 
 	if force {
-		return idx.Index(context.Background(), projectPath, true, progress)
+		return idx.Index(ctx, projectPath, true, progress)
 	}
 
-	reindexed, stats, err := idx.EnsureFresh(context.Background(), projectPath, progress)
+	reindexed, stats, err := idx.EnsureFresh(ctx, projectPath, progress)
 	if err != nil {
 		return stats, fmt.Errorf("indexing: %w", err)
 	}