fix(mcp): tighten ambiguous project recovery

Author: Alan-TheGentleman

docs/AGENT-SETUP.md

@@ -50,7 +50,7 @@ If a write tool returns `ambiguous_project`, the agent must not guess. Ask the u
 }
 ```
 
-This recovery path is accepted only after cwd detection is ambiguous and only when `project` exactly matches one of the reported `available_projects`. In all non-ambiguous cases, `.engram/config.json`/git/cwd detection remains authoritative and the explicit `project` is ignored. Alternatives: `cd` into the target repo before starting the MCP server, or add repo `.engram/config.json`.
+This recovery path is accepted only after cwd detection is ambiguous and only when `project`, after trimming surrounding whitespace, exactly matches one of the reported `available_projects`. Do not send normalized variants or guesses: if `available_projects` contains `foo--bar`, the retry must use `foo--bar`, not `foo-bar`; empty/whitespace choices are rejected. In all non-ambiguous cases, `.engram/config.json`/git/cwd detection remains authoritative and the explicit `project` is ignored. Alternatives: `cd` into the target repo before starting the MCP server, or add repo `.engram/config.json`.
 
 **Read tools** (`mem_search`, `mem_context`, `mem_get_observation`, `mem_stats`, `mem_timeline`) accept an optional `project` override validated against the store. Omit it to auto-detect.
 

internal/mcp/mcp.go

@@ -19,6 +19,7 @@ import (
 	"errors"
 	"fmt"
 	"os"
+	"path/filepath"
 	"strings"
 	"time"
 
@@ -1921,7 +1922,7 @@ func resolveWriteProjectWithChoice(projectChoice, reason string) (projectpkg.Det
 		return res, err
 	}
 
-	choice, _ := store.NormalizeProject(projectChoice)
+	choice := strings.TrimSpace(projectChoice)
 	if choice == "" || !containsProjectChoice(res.AvailableProjects, choice) {
 		return res, &invalidProjectChoiceError{
 			Name:              choice,
@@ -1931,20 +1932,54 @@ func resolveWriteProjectWithChoice(projectChoice, reason string) (projectpkg.Det
 
 	res.Project = choice
 	res.Source = projectpkg.SourceUserSelectedAfterAmbiguousProject
+	res.Path = resolveAmbiguousChoicePath(res.Path, choice)
 	res.Warning = "project selected by user after ambiguous_project recovery"
 	return res, nil
 }
 
 func containsProjectChoice(available []string, choice string) bool {
+	choice = strings.TrimSpace(choice)
 	for _, candidate := range available {
-		normalized, _ := store.NormalizeProject(candidate)
-		if normalized == choice {
+		if strings.TrimSpace(candidate) == choice {
 			return true
 		}
 	}
 	return false
 }
 
+func resolveAmbiguousChoicePath(ambiguousParent, choice string) string {
+	parent := strings.TrimSpace(ambiguousParent)
+	if parent == "" || strings.TrimSpace(choice) == "" {
+		return ""
+	}
+
+	entries, err := os.ReadDir(parent)
+	if err != nil {
+		return ""
+	}
+	for _, entry := range entries {
+		if !entry.IsDir() {
+			continue
+		}
+		// Match the same name shape used by project.DetectProjectFull for
+		// available_projects: trim + lowercase only. Do not use store.NormalizeProject
+		// here because it collapses repeated '-'/'_' and can create collisions.
+		if strings.TrimSpace(strings.ToLower(entry.Name())) != choice {
+			continue
+		}
+		childPath := filepath.Join(parent, entry.Name())
+		if _, err := os.Stat(filepath.Join(childPath, ".git")); err != nil {
+			continue
+		}
+		absChild, err := filepath.Abs(childPath)
+		if err != nil {
+			return childPath
+		}
+		return absChild
+	}
+	return ""
+}
+
 // resolveReadProject validates an optional project override against the store.
 // If override is empty, falls back to auto-detection from cwd.
 // JW2: normalizes the override (lowercase+trim) before ProjectExists lookup so
@@ -2001,6 +2036,12 @@ func writeProjectErrorResult(res projectpkg.DetectionResult, err error) *mcp.Cal
 	}
 	var choiceErr *invalidProjectChoiceError
 	if errors.As(err, &choiceErr) {
+		if choiceErr.Name == "" {
+			return errorWithMeta("invalid_project_choice",
+				"Project choice is empty; choose exactly one value from available_projects and retry with project_choice_reason=user_selected_after_ambiguous_project",
+				choiceErr.AvailableProjects,
+			)
+		}
 		return errorWithMeta("invalid_project_choice",
 			fmt.Sprintf("Project choice %q is not one of available_projects", choiceErr.Name),
 			choiceErr.AvailableProjects,

internal/mcp/mcp_test.go

@@ -2791,7 +2791,7 @@ func TestSessionStartWithExplicitDirectoryResolvesProjectFromDirectory(t *testin
 
 // TestWriteSchema_ProjectFieldOnlyForAmbiguousRecovery asserts that only the
 // write tools with explicit ambiguous-project recovery expose project fields.
-func TestWriteSchema_NoProjectField(t *testing.T) {
+func TestWriteSchema_ProjectFieldOnlyForAmbiguousRecovery(t *testing.T) {
 	s := newMCPTestStore(t)
 	srv := NewServer(s)
 
@@ -2976,12 +2976,110 @@ func TestMemSave_AmbiguousWithValidUserChoiceSucceeds(t *testing.T) {
 	if body["project"] != "repo-choice-b" || body["project_source"] != project.SourceUserSelectedAfterAmbiguousProject {
 		t.Fatalf("expected explicit user choice envelope, got %v", body)
 	}
+	if body["project_path"] != filepath.Join(parent, "repo-choice-b") {
+		t.Fatalf("expected project_path to point at selected repo root, got %v", body)
+	}
 	obs, err := s.Search("chosen project memory", store.SearchOptions{Project: "repo-choice-b", Limit: 5})
 	if err != nil || len(obs) != 1 {
 		t.Fatalf("expected observation in selected project, obs=%d err=%v", len(obs), err)
 	}
 }
 
+func TestMemSave_AmbiguousChoiceRequiresExactAvailableProject(t *testing.T) {
+	parent := t.TempDir()
+	for _, name := range []string{"foo--bar", "baz__qux"} {
+		child := filepath.Join(parent, name)
+		if err := os.MkdirAll(child, 0o755); err != nil {
+			t.Fatal(err)
+		}
+		initTestGitRepo(t, child)
+	}
+	t.Chdir(parent)
+
+	s := newMCPTestStore(t)
+	h := handleSave(s, MCPConfig{}, NewSessionActivity(10*time.Minute))
+	res, err := h(context.Background(), mcppkg.CallToolRequest{Params: mcppkg.CallToolParams{Arguments: map[string]any{
+		"title":                 "normalized choice must fail",
+		"content":               "must not save under normalized collision",
+		"project":               "foo-bar",
+		"project_choice_reason": project.SourceUserSelectedAfterAmbiguousProject,
+	}}})
+	if err != nil {
+		t.Fatalf("handler error: %v", err)
+	}
+	if !res.IsError {
+		t.Fatal("expected invalid project choice for normalized-but-not-exact value")
+	}
+	body := callResultJSON(t, res)
+	if body["error_code"] != "invalid_project_choice" {
+		t.Fatalf("expected invalid_project_choice, got %v", body)
+	}
+	available, ok := body["available_projects"].([]any)
+	foundFooBar := false
+	for _, candidate := range available {
+		if candidate == "foo--bar" {
+			foundFooBar = true
+			break
+		}
+	}
+	if !ok || !foundFooBar {
+		t.Fatalf("expected exact available project names, got %v", body["available_projects"])
+	}
+	if strings.Contains(body["message"].(string), "foo--bar") {
+		t.Fatalf("message should report the rejected trimmed choice, not a normalized available value: %v", body)
+	}
+	obs, searchErr := s.Search("normalized choice must fail", store.SearchOptions{Project: "foo-bar", Limit: 5})
+	if searchErr != nil || len(obs) != 0 {
+		t.Fatalf("normalized collision must not receive writes, obs=%d err=%v", len(obs), searchErr)
+	}
+
+	res, err = h(context.Background(), mcppkg.CallToolRequest{Params: mcppkg.CallToolParams{Arguments: map[string]any{
+		"title":                 "exact choice succeeds",
+		"content":               "saved after exact available project choice",
+		"project":               "  baz__qux  ",
+		"project_choice_reason": project.SourceUserSelectedAfterAmbiguousProject,
+	}}})
+	if err != nil || res.IsError {
+		t.Fatalf("exact trimmed choice should succeed: err=%v isError=%v text=%q", err, res.IsError, callResultText(t, res))
+	}
+	body = callResultJSON(t, res)
+	if body["project_path"] != filepath.Join(parent, "baz__qux") {
+		t.Fatalf("expected project_path to selected exact repo root, got %v", body)
+	}
+}
+
+func TestMemSave_AmbiguousEmptyProjectChoiceIsActionable(t *testing.T) {
+	parent := t.TempDir()
+	for _, name := range []string{"repo-empty-a", "repo-empty-b"} {
+		child := filepath.Join(parent, name)
+		if err := os.MkdirAll(child, 0o755); err != nil {
+			t.Fatal(err)
+		}
+		initTestGitRepo(t, child)
+	}
+	t.Chdir(parent)
+
+	s := newMCPTestStore(t)
+	h := handleSave(s, MCPConfig{}, NewSessionActivity(10*time.Minute))
+	res, err := h(context.Background(), mcppkg.CallToolRequest{Params: mcppkg.CallToolParams{Arguments: map[string]any{
+		"title":                 "empty choice must fail",
+		"content":               "must not save",
+		"project":               " \t\n ",
+		"project_choice_reason": project.SourceUserSelectedAfterAmbiguousProject,
+	}}})
+	if err != nil {
+		t.Fatalf("handler error: %v", err)
+	}
+	if !res.IsError {
+		t.Fatal("expected invalid project choice for whitespace project")
+	}
+	body := callResultJSON(t, res)
+	message, _ := body["message"].(string)
+	if body["error_code"] != "invalid_project_choice" || !strings.Contains(message, "Project choice is empty") || !strings.Contains(message, "available_projects") {
+		t.Fatalf("expected actionable empty choice error, got %v", body)
+	}
+}
+
 func TestMemSave_AmbiguousWithInventedProjectRejected(t *testing.T) {
 	parent := t.TempDir()
 	for _, name := range []string{"repo-valid-a", "repo-valid-b"} {
@@ -3045,6 +3143,9 @@ func TestMemSavePrompt_AmbiguousWithValidUserChoiceSucceeds(t *testing.T) {
 	if body["project"] != "repo-prompt-a" || body["project_source"] != project.SourceUserSelectedAfterAmbiguousProject {
 		t.Fatalf("expected explicit user choice envelope, got %v", body)
 	}
+	if body["project_path"] != filepath.Join(parent, "repo-prompt-a") {
+		t.Fatalf("expected project_path to point at selected prompt repo root, got %v", body)
+	}
 	prompts, err := s.RecentPrompts("repo-prompt-a", 5)
 	if err != nil || len(prompts) != 1 {
 		t.Fatalf("expected prompt in selected project, prompts=%d err=%v", len(prompts), err)