fix: avoid recall lock errors and harden core coverage

Keep concurrent agent reads from tripping SQLite open-time locks and add direct tests around output, resume, and handoff behaviour so regressions surface closer to the affected packages.

Author: danjdewhurst

docs/mvp-status.md

@@ -1,6 +1,6 @@
 # MVP Status
 
-Last updated: 2026-04-14
+Last updated: 2026-04-15
 
 This file is the repo's explicit implementation tracker.
 
@@ -23,7 +23,7 @@ If you are resuming work in a new session:
 
 ## Current Summary
 
-The core local-memory workflow is implemented end to end, and the previously listed follow-up gaps around task state control, history indexing cost, and resume / handoff reuse have now been closed.
+The core local-memory workflow is implemented end to end, and the previously listed follow-up gaps around task state control, history indexing cost, resume / handoff reuse, and real-repo FTS validation have now been closed.
 
 Working commands:
 
@@ -82,6 +82,8 @@ Working global flags:
 - SQLite migrations now use an explicit schema version.
 - The Go module path is now the canonical `github.com/forjd/aid`.
 - The repo now explicitly stays FTS-first; optional embeddings are deferred until real recall gaps justify the added complexity.
+- FTS-only recall has now been validated in larger real repos; exact and near-exact lexical queries perform well enough to keep embeddings deferred for now.
+- Concurrent `aid recall` runs against the same repo no longer trip transient SQLite `database is locked` failures during store open.
 
 ## Partial
 
@@ -106,11 +108,12 @@ Working global flags:
 
 ## Recommended Next Work
 
-1. Validate the FTS-only recall path in larger real repos before revisiting embeddings.
+1. Start the coverage-hardening pass in [docs/plans/code-coverage-improvement.md](./plans/code-coverage-improvement.md), beginning with direct tests for `internal/output`, `internal/resume`, and `internal/handoff`.
 2. Decide whether post-MVP expansion should go toward a TUI, background automation, or multi-user sync instead of keeping the tool intentionally CLI-only.
 
 ## Open Notes
 
 - The current implementation already satisfies the practical MVP command surface.
 - Remaining work is now product-expansion work rather than missing core command behavior.
+- Recent validation in larger repos suggests the main recall misses are tokenisation and phrasing gaps such as `town house` vs `townhouse` or `optimise` vs `speed up`, rather than a broad need for embeddings.
 - Future sessions should treat this file as the source of truth for implementation status.

internal/cli/cli_test.go

@@ -8,6 +8,7 @@ import (
 	"os/exec"
 	"path/filepath"
 	"strings"
+	"sync"
 	"testing"
 
 	"github.com/forjd/aid/internal/app"
@@ -94,6 +95,83 @@ func TestLeafCommandAllowsHelpAsArgument(t *testing.T) {
 	}
 }
 
+func TestConcurrentRecallSubprocessesDoNotHitDatabaseLocked(t *testing.T) {
+	repoDir := t.TempDir()
+	dataDir := filepath.Join(t.TempDir(), "aid-data")
+
+	runGit(t, repoDir, "init", "-q")
+	writeFile(t, filepath.Join(repoDir, "README.md"), []byte("repo\n"))
+	runGitWithIdentity(t, repoDir, "add", "README.md")
+	runGitWithIdentity(t, repoDir, "commit", "-m", "feat: add readme")
+
+	env := []string{"AID_DATA_DIR=" + dataDir}
+
+	for _, args := range [][]string{
+		{"init"},
+		{"note", "add", "Refresh retry investigation"},
+		{"decide", "add", "Use single refresh retry"},
+		{"handoff", "generate"},
+		{"history", "index"},
+	} {
+		output, err := runCLISubprocess(t, repoDir, env, args...)
+		if err != nil {
+			t.Fatalf("seed command %v failed: %v\n%s", args, err, output)
+		}
+	}
+
+	type recallResult struct {
+		output string
+		err    error
+		args   []string
+	}
+
+	queries := [][]string{
+		{"recall", "refresh retry", "--json"},
+		{"recall", "token refresh", "--json"},
+	}
+
+	for i := 0; i < 20; i++ {
+		results := make(chan recallResult, len(queries))
+		var wg sync.WaitGroup
+
+		for _, args := range queries {
+			args := append([]string(nil), args...)
+			wg.Add(1)
+			go func() {
+				defer wg.Done()
+				output, err := runCLISubprocess(t, repoDir, env, args...)
+				results <- recallResult{output: output, err: err, args: args}
+			}()
+		}
+
+		wg.Wait()
+		close(results)
+
+		for result := range results {
+			if result.err != nil {
+				t.Fatalf("concurrent recall %v failed on iteration %d: %v\n%s", result.args, i+1, result.err, result.output)
+			}
+
+			var payload struct {
+				OK    bool `json:"ok"`
+				Error *struct {
+					Message string `json:"message"`
+				} `json:"error"`
+			}
+			if err := json.Unmarshal([]byte(result.output), &payload); err != nil {
+				t.Fatalf("unmarshal recall output for %v on iteration %d: %v\n%s", result.args, i+1, err, result.output)
+			}
+			if !payload.OK {
+				message := ""
+				if payload.Error != nil {
+					message = payload.Error.Message
+				}
+				t.Fatalf("concurrent recall %v returned error payload on iteration %d: %s\n%s", result.args, i+1, message, result.output)
+			}
+		}
+	}
+}
+
 func TestInitAndCrudFlow(t *testing.T) {
 	repoDir := t.TempDir()
 	dataDir := filepath.Join(t.TempDir(), "aid-data")
@@ -1247,6 +1325,38 @@ func runCLI(t *testing.T, args ...string) string {
 	return stdout.String()
 }
 
+func TestCLIHelperProcess(t *testing.T) {
+	if os.Getenv("AID_TEST_SUBPROCESS") != "1" {
+		return
+	}
+
+	separator := -1
+	for i, arg := range os.Args {
+		if arg == "--" {
+			separator = i
+			break
+		}
+	}
+	if separator == -1 {
+		os.Exit(2)
+	}
+
+	exitCode := Run(os.Args[separator+1:], os.Stdout, os.Stderr)
+	os.Exit(exitCode)
+}
+
+func runCLISubprocess(t *testing.T, cwd string, env []string, args ...string) (string, error) {
+	t.Helper()
+
+	cmdArgs := append([]string{"-test.run=TestCLIHelperProcess", "--"}, args...)
+	cmd := exec.Command(os.Args[0], cmdArgs...)
+	cmd.Dir = cwd
+	cmd.Env = append(append(os.Environ(), "AID_TEST_SUBPROCESS=1"), env...)
+
+	output, err := cmd.CombinedOutput()
+	return string(output), err
+}
+
 func runGit(t *testing.T, cwd string, args ...string) {
 	t.Helper()
 

internal/handoff/handoff_test.go

@@ -0,0 +1,188 @@
+package handoff
+
+import (
+	"testing"
+	"time"
+
+	"github.com/forjd/aid/internal/git"
+	resumepkg "github.com/forjd/aid/internal/resume"
+	"github.com/forjd/aid/internal/store"
+)
+
+func TestBuild(t *testing.T) {
+	nextAction := "inspect retry middleware"
+	snapshot := Build(
+		"feat/auth",
+		git.WorktreeStatus{Dirty: true, Changed: 2, Untracked: 1},
+		resumepkg.Bundle{
+			ActiveTask: taskPointer(handoffTask(1, "feat/auth", store.TaskInProgress, "Fix refresh retry path")),
+			Notes: []store.Note{
+				handoffNote(1, "Retry still fails after 401"),
+			},
+			Decisions: []store.Decision{
+				handoffDecision(1, "Use a single refresh retry"),
+			},
+			RecentCommits: []store.Commit{
+				handoffCommit("abc123456789", "fix: refresh retry path"),
+			},
+			OpenQuestions: []string{
+				"Which retry path is still failing?",
+				"Should the API return a clearer auth error?",
+			},
+			NextAction: &nextAction,
+		},
+		[]store.Task{
+			handoffTask(1, "feat/auth", store.TaskInProgress, "Fix refresh retry path"),
+			handoffTask(2, "feat/auth", store.TaskOpen, "Review retry logging"),
+			handoffTask(3, "feat/auth", store.TaskDone, "Ignore completed work"),
+		},
+	)
+
+	want := "Branch: feat/auth\n" +
+		"Worktree: dirty (2 changed, 1 untracked)\n" +
+		"Active task: Fix refresh retry path\n" +
+		"Open tasks:\n" +
+		"- Fix refresh retry path [in_progress]\n" +
+		"- Review retry logging [open]\n" +
+		"Recent notes:\n" +
+		"- Retry still fails after 401\n" +
+		"Key decisions:\n" +
+		"- Use a single refresh retry\n" +
+		"Recent commits:\n" +
+		"- abc1234 fix: refresh retry path\n" +
+		"Open questions:\n" +
+		"- Which retry path is still failing?\n" +
+		"- Should the API return a clearer auth error?\n" +
+		"- Should the current uncommitted changes be kept, finished, or discarded?\n" +
+		"Recommended next action:\n" +
+		"- inspect retry middleware"
+
+	if snapshot.Branch != "feat/auth" {
+		t.Fatalf("unexpected branch: %#v", snapshot)
+	}
+	if snapshot.Summary != want {
+		t.Fatalf("unexpected handoff summary:\n%s", snapshot.Summary)
+	}
+}
+
+func TestBuildWithAmbiguousTaskAndCleanWorktree(t *testing.T) {
+	snapshot := Build(
+		"feat/auth",
+		git.WorktreeStatus{},
+		resumepkg.Bundle{ActiveTaskAmbiguous: true},
+		nil,
+	)
+
+	want := "Branch: feat/auth\nWorktree: clean\nActive task: ambiguous"
+	if snapshot.Summary != want {
+		t.Fatalf("unexpected minimal handoff summary:\n%s", snapshot.Summary)
+	}
+}
+
+func TestLimitOpenTasks(t *testing.T) {
+	tasks := []store.Task{
+		handoffTask(1, "", store.TaskOpen, "One"),
+		handoffTask(2, "", store.TaskDone, "Done"),
+		handoffTask(3, "", store.TaskBlocked, "Two"),
+		handoffTask(4, "", store.TaskOpen, "Three"),
+		handoffTask(5, "", store.TaskOpen, "Four"),
+		handoffTask(6, "", store.TaskOpen, "Five"),
+		handoffTask(7, "", store.TaskOpen, "Six"),
+	}
+
+	limited := limitOpenTasks(tasks, 5)
+	if len(limited) != 5 {
+		t.Fatalf("expected 5 open tasks, got %#v", limited)
+	}
+	for _, task := range limited {
+		if task.Status == store.TaskDone {
+			t.Fatalf("did not expect done task in open task list: %#v", limited)
+		}
+	}
+	if limited[4].Text != "Five" {
+		t.Fatalf("expected limit to preserve task order, got %#v", limited)
+	}
+}
+
+func TestWorktreeLine(t *testing.T) {
+	tests := []struct {
+		name   string
+		status git.WorktreeStatus
+		want   string
+	}{
+		{name: "clean", status: git.WorktreeStatus{}, want: "clean"},
+		{name: "untracked only", status: git.WorktreeStatus{Dirty: true, Untracked: 2}, want: "dirty (2 untracked)"},
+		{name: "changed only", status: git.WorktreeStatus{Dirty: true, Changed: 3}, want: "dirty (3 changed)"},
+		{name: "changed and untracked", status: git.WorktreeStatus{Dirty: true, Changed: 3, Untracked: 2}, want: "dirty (3 changed, 2 untracked)"},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			if got := worktreeLine(test.status); got != test.want {
+				t.Fatalf("worktreeLine(%#v) = %q, want %q", test.status, got, test.want)
+			}
+		})
+	}
+}
+
+func TestShortSHA(t *testing.T) {
+	if got := shortSHA("abc1234"); got != "abc1234" {
+		t.Fatalf("expected unchanged short sha, got %q", got)
+	}
+	if got := shortSHA("abc123456789"); got != "abc1234" {
+		t.Fatalf("expected shortened sha, got %q", got)
+	}
+}
+
+func TestHandoffOpenQuestions(t *testing.T) {
+	questions := handoffOpenQuestions([]string{"One", "Two", "Three"}, git.WorktreeStatus{Dirty: true})
+	if len(questions) != 3 || questions[2] != "Three" {
+		t.Fatalf("expected existing questions to be kept when already at limit, got %#v", questions)
+	}
+
+	questions = handoffOpenQuestions([]string{"One", "Two"}, git.WorktreeStatus{Dirty: true})
+	want := []string{"One", "Two", "Should the current uncommitted changes be kept, finished, or discarded?"}
+	if len(questions) != len(want) {
+		t.Fatalf("unexpected handoff questions: %#v", questions)
+	}
+	for i := range want {
+		if questions[i] != want[i] {
+			t.Fatalf("unexpected handoff questions: %#v", questions)
+		}
+	}
+	questions = handoffOpenQuestions(nil, git.WorktreeStatus{})
+	if len(questions) != 0 {
+		t.Fatalf("expected no questions for clean worktree, got %#v", questions)
+	}
+}
+
+func taskPointer(task store.Task) *store.Task {
+	return &task
+}
+
+func handoffTask(id int64, branch string, status store.TaskStatus, text string) store.Task {
+	return store.Task{
+		ID:        id,
+		Branch:    branch,
+		Text:      text,
+		Status:    status,
+		CreatedAt: handoffTime(),
+		UpdatedAt: handoffTime(),
+	}
+}
+
+func handoffNote(id int64, text string) store.Note {
+	return store.Note{ID: id, Text: text, CreatedAt: handoffTime()}
+}
+
+func handoffDecision(id int64, text string) store.Decision {
+	return store.Decision{ID: id, Text: text, CreatedAt: handoffTime()}
+}
+
+func handoffCommit(sha, summary string) store.Commit {
+	return store.Commit{SHA: sha, Summary: summary, CommittedAt: handoffTime()}
+}
+
+func handoffTime() time.Time {
+	return time.Date(2026, 4, 15, 10, 0, 0, 0, time.UTC)
+}