fix(sync): stabilize imports, project lock, and TUI ordering

Merge local dependency-safe import, repo-scoped project lock, and stable recent ordering.

Author: Alan-TheGentleman

docs/AGENT-SETUP.md

@@ -27,7 +27,17 @@ Engram works with **any MCP-compatible agent**. Pick your agent below.
 
 ### Project auto-detection (important)
 
-**Do not pass `project` to write tools.** Engram auto-detects the project from the server's working directory (cwd) using git remote URL, repo root name, or directory basename. Agents that include `project` in `mem_save` or similar calls will have that argument silently discarded.
+**Do not pass `project` to write tools.** Engram auto-detects the project from the server's working directory (cwd) using `.engram/config.json`, git remote URL, repo root name, or directory basename. Agents that include `project` in `mem_save` or similar calls will have that argument silently discarded.
+
+To lock write tools to the canonical project for a repo, add `.engram/config.json` at the repo root:
+
+```json
+{
+  "project_name": "sias-app"
+}
+```
+
+When present, `project_name` is used for writes from the repo and its subdirectories and overrides lower-confidence cwd/git detection. This is a write lock only: read tools can still use an explicit `project` filter when you need to query another existing project. Empty or invalid `project_name` values fail writes loudly instead of falling back silently.
 
 **Recommended first call:** `mem_current_project` — confirms which project Engram detected before you start writing. Returns `project_source` (how it was detected) and `available_projects` (if cwd is ambiguous).
 

internal/mcp/mcp.go

@@ -1001,12 +1001,7 @@ func handleSave(s *store.Store, cfg MCPConfig, activity *SessionActivity) server
 		// Auto-detect project from cwd; fail fast on ambiguous (REQ-308, REQ-309)
 		detRes, err := resolveWriteProject()
 		if err != nil {
-			// JW1: use AvailableProjects from detection result (repos in cwd),
-			// NOT stats.Projects (all store projects).
-			return errorWithMeta("ambiguous_project",
-				fmt.Sprintf("Cannot determine project: %s", err),
-				detRes.AvailableProjects,
-			), nil
+			return writeProjectErrorResult(detRes, err), nil
 		}
 		project := detRes.Project
 
@@ -1241,11 +1236,7 @@ func handleSavePrompt(s *store.Store, cfg MCPConfig) server.ToolHandlerFunc {
 
 		detRes, err := resolveWriteProject()
 		if err != nil {
-			// JW1: use AvailableProjects from detection result (repos in cwd).
-			return errorWithMeta("ambiguous_project",
-				fmt.Sprintf("Cannot determine project: %s", err),
-				detRes.AvailableProjects,
-			), nil
+			return writeProjectErrorResult(detRes, err), nil
 		}
 		project, _ := store.NormalizeProject(detRes.Project)
 
@@ -1523,11 +1514,7 @@ func handleSessionSummary(s *store.Store, cfg MCPConfig, activity *SessionActivi
 		// Auto-detect project from cwd; fail fast on ambiguous (REQ-308, REQ-309)
 		detRes, err := resolveWriteProject()
 		if err != nil {
-			// JW1: use AvailableProjects from detection result (repos in cwd).
-			return errorWithMeta("ambiguous_project",
-				fmt.Sprintf("Cannot determine project: %s", err),
-				detRes.AvailableProjects,
-			), nil
+			return writeProjectErrorResult(detRes, err), nil
 		}
 		project, _ := store.NormalizeProject(detRes.Project)
 
@@ -1567,11 +1554,7 @@ func handleSessionStart(s *store.Store, cfg MCPConfig, activity *SessionActivity
 
 		detRes, err := resolveSessionStartProject(explicitDirectory)
 		if err != nil {
-			// JW1: use AvailableProjects from detection result (repos in cwd).
-			return errorWithMeta("ambiguous_project",
-				fmt.Sprintf("Cannot determine project: %s", err),
-				detRes.AvailableProjects,
-			), nil
+			return writeProjectErrorResult(detRes, err), nil
 		}
 		project, _ := store.NormalizeProject(detRes.Project)
 
@@ -1614,6 +1597,9 @@ func handleSessionEnd(s *store.Store, cfg MCPConfig, activity *SessionActivity)
 
 		detRes, err := resolveWriteProject()
 		if err != nil {
+			if errors.Is(err, projectpkg.ErrInvalidConfig) {
+				return writeProjectErrorResult(detRes, err), nil
+			}
 			// For session end, still complete the operation even if project resolution fails.
 			// Use basename fallback.
 			cwd, _ := os.Getwd()
@@ -1645,11 +1631,7 @@ func handleCapturePassive(s *store.Store, cfg MCPConfig, activity *SessionActivi
 
 		detRes, err := resolveWriteProject()
 		if err != nil {
-			// JW1: use AvailableProjects from detection result (repos in cwd).
-			return errorWithMeta("ambiguous_project",
-				fmt.Sprintf("Cannot determine project: %s", err),
-				detRes.AvailableProjects,
-			), nil
+			return writeProjectErrorResult(detRes, err), nil
 		}
 		project, _ := store.NormalizeProject(detRes.Project)
 
@@ -1947,6 +1929,14 @@ func respondWithProject(res projectpkg.DetectionResult, text string, extra map[s
 	return mcp.NewToolResultText(string(out))
 }
 
+func writeProjectErrorResult(res projectpkg.DetectionResult, err error) *mcp.CallToolResult {
+	code := "ambiguous_project"
+	if errors.Is(err, projectpkg.ErrInvalidConfig) {
+		code = "invalid_project_config"
+	}
+	return errorWithMeta(code, fmt.Sprintf("Cannot determine project: %s", err), res.AvailableProjects)
+}
+
 // errorWithMeta returns a structured tool error result with error_code,
 // message, available_projects, and a hint for resolution.
 func errorWithMeta(code, msg string, availableProjects []string) *mcp.CallToolResult {
@@ -1960,6 +1950,8 @@ func errorWithMeta(code, msg string, availableProjects []string) *mcp.CallToolRe
 		envelope["hint"] = "Use mem_current_project to inspect detection results, or cd into one of the listed repositories."
 	case "unknown_project":
 		envelope["hint"] = "Use one of the available_projects values, or omit project to auto-detect."
+	case "invalid_project_config":
+		envelope["hint"] = "Fix .engram/config.json so project_name is a non-empty project name."
 	}
 	out, _ := jsonMarshal(envelope)
 	result := mcp.NewToolResultText(string(out))

internal/mcp/mcp_test.go

@@ -3258,6 +3258,127 @@ func TestResolveWriteProject_AutoDetects(t *testing.T) {
 	}
 }
 
+func TestResolveWriteProject_UsesConfigFromRepoRootSubdir(t *testing.T) {
+	root := t.TempDir()
+	initTestGitRepo(t, root)
+	configDir := filepath.Join(root, ".engram")
+	if err := os.MkdirAll(configDir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(configDir, "config.json"), []byte(`{"project_name":"canonical-project"}`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	subdir := filepath.Join(root, "cmd", "tool")
+	if err := os.MkdirAll(subdir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	t.Chdir(subdir)
+
+	res, err := resolveWriteProject()
+	if err != nil {
+		t.Fatalf("resolveWriteProject: %v", err)
+	}
+	if res.Source != project.SourceConfig || res.Project != "canonical-project" {
+		t.Fatalf("expected config project, got source=%q project=%q", res.Source, res.Project)
+	}
+}
+
+func TestResolveWriteProject_InvalidConfigFailsClearly(t *testing.T) {
+	dir := t.TempDir()
+	configDir := filepath.Join(dir, ".engram")
+	if err := os.MkdirAll(configDir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(configDir, "config.json"), []byte(`{"project_name":"bad/name"}`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	t.Chdir(dir)
+
+	_, err := resolveWriteProject()
+	if !errors.Is(err, project.ErrInvalidConfig) || !strings.Contains(err.Error(), "project_name") {
+		t.Fatalf("expected clear invalid config project_name error, got %v", err)
+	}
+}
+
+func TestHandleSaveInvalidConfigFailsClearly(t *testing.T) {
+	dir := t.TempDir()
+	configDir := filepath.Join(dir, ".engram")
+	if err := os.MkdirAll(configDir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(configDir, "config.json"), []byte(`{"project_name":""}`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	t.Chdir(dir)
+
+	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": "should fail", "content": "invalid config", "type": "decision",
+	}}})
+	if err != nil {
+		t.Fatalf("handleSave: %v", err)
+	}
+	if !res.IsError {
+		t.Fatalf("expected invalid config to fail write, got %q", callResultText(t, res))
+	}
+	body := callResultJSON(t, res)
+	if body["error_code"] != "invalid_project_config" || !strings.Contains(body["message"].(string), "project_name") {
+		t.Fatalf("expected clear invalid project config error, got %v", body)
+	}
+}
+
+func TestHandleSaveAndPromptUseConfigProjectForWrites(t *testing.T) {
+	root := t.TempDir()
+	initTestGitRepo(t, root)
+	configDir := filepath.Join(root, ".engram")
+	if err := os.MkdirAll(configDir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(configDir, "config.json"), []byte(`{"project_name":"config-locked"}`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	subdir := filepath.Join(root, "internal", "pkg")
+	if err := os.MkdirAll(subdir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	t.Chdir(subdir)
+
+	s := newMCPTestStore(t)
+	save := handleSave(s, MCPConfig{}, NewSessionActivity(10*time.Minute))
+	res, err := save(context.Background(), mcppkg.CallToolRequest{Params: mcppkg.CallToolParams{Arguments: map[string]any{
+		"title": "config write", "content": "memory saved under config project", "type": "decision",
+	}}})
+	if err != nil || res.IsError {
+		t.Fatalf("mem_save failed: err=%v isError=%v text=%q", err, res.IsError, callResultText(t, res))
+	}
+	body := callResultJSON(t, res)
+	if body["project"] != "config-locked" || body["project_source"] != project.SourceConfig {
+		t.Fatalf("expected mem_save config envelope, got %v", body)
+	}
+
+	prompt := handleSavePrompt(s, MCPConfig{})
+	res, err = prompt(context.Background(), mcppkg.CallToolRequest{Params: mcppkg.CallToolParams{Arguments: map[string]any{
+		"content": "prompt saved under config project",
+	}}})
+	if err != nil || res.IsError {
+		t.Fatalf("mem_save_prompt failed: err=%v isError=%v text=%q", err, res.IsError, callResultText(t, res))
+	}
+	body = callResultJSON(t, res)
+	if body["project"] != "config-locked" || body["project_source"] != project.SourceConfig {
+		t.Fatalf("expected mem_save_prompt config envelope, got %v", body)
+	}
+
+	obs, err := s.Search("memory saved under config project", store.SearchOptions{Project: "config-locked", Limit: 5})
+	if err != nil || len(obs) != 1 {
+		t.Fatalf("expected observation written to config project, obs=%d err=%v", len(obs), err)
+	}
+	prompts, err := s.RecentPrompts("config-locked", 5)
+	if err != nil || len(prompts) != 1 {
+		t.Fatalf("expected prompt written to config project, prompts=%d err=%v", len(prompts), err)
+	}
+}
+
 // TestResolveWriteProject_AmbiguousError: assert errors.Is(err, ErrAmbiguousProject)
 func TestResolveWriteProject_AmbiguousError(t *testing.T) {
 	parent := t.TempDir()

internal/project/detect.go

@@ -7,7 +7,9 @@ package project
 
 import (
 	"context"
+	"encoding/json"
 	"errors"
+	"fmt"
 	"os"
 	"os/exec"
 	"path/filepath"
@@ -19,6 +21,10 @@ import (
 // multiple git repositories and we cannot auto-select one.
 var ErrAmbiguousProject = errors.New("ambiguous project: multiple git repos found in cwd")
 
+// ErrInvalidConfig is returned when .engram/config.json exists but cannot be
+// used as a project write lock.
+var ErrInvalidConfig = errors.New("invalid .engram/config.json")
+
 // Source constants describe how the project name was resolved.
 const (
 	SourceGitRemote        = "git_remote"        // derived from git remote origin URL
@@ -28,6 +34,7 @@ const (
 	SourceAmbiguous        = "ambiguous"         // cwd contains multiple git repos (Case 4)
 	SourceExplicitOverride = "explicit_override" // JR2-2: caller explicitly supplied a project name
 	SourceRequestBody      = "request_body"      // REQ-414: project came from the request body (server-side, no filesystem path)
+	SourceConfig           = "config"            // derived from .engram/config.json project_name
 )
 
 // noiseSet lists directory names that are skipped during child-repo scanning.
@@ -76,6 +83,10 @@ func DetectProjectFull(dir string) DetectionResult {
 		dir = "./" + dir
 	}
 
+	if res, ok := detectFromConfig(dir); ok {
+		return res
+	}
+
 	// ── Case 1: git_remote ──────────────────────────────────────────────
 	if name := detectFromGitRemote(dir); name != "" {
 		// JS2: use repo root as Path for consistency with Case 2 (git_root).
@@ -154,6 +165,75 @@ basename:
 	}
 }
 
+type configFile struct {
+	ProjectName string `json:"project_name"`
+}
+
+func detectFromConfig(dir string) (DetectionResult, bool) {
+	absDir, err := filepath.Abs(dir)
+	if err != nil {
+		absDir = dir
+	}
+
+	// Project config is a project/repo lock, not a global ancestor setting. When
+	// cwd is inside git, only the repository root may define the lock. This keeps
+	// ~/.engram/config.json (the global data directory) from being inherited by
+	// every directory under $HOME.
+	if gitRoot := detectGitRootDir(absDir); gitRoot != "" {
+		return readConfigAt(gitRoot)
+	}
+
+	// Outside git, accept only the current directory's config. Do not walk to
+	// arbitrary parents such as $HOME.
+	return readConfigAt(absDir)
+}
+
+func readConfigAt(projectDir string) (DetectionResult, bool) {
+	configPath := filepath.Join(projectDir, ".engram", "config.json")
+	data, err := os.ReadFile(configPath)
+	if err != nil {
+		if errors.Is(err, os.ErrNotExist) {
+			return DetectionResult{}, false
+		}
+		return invalidConfigResult(projectDir, fmt.Errorf("read %s: %w", configPath, err)), true
+	}
+
+	var cfg configFile
+	if err := json.Unmarshal(data, &cfg); err != nil {
+		return invalidConfigResult(projectDir, fmt.Errorf("parse %s: %w", configPath, err)), true
+	}
+	projectName, err := normalizeConfigProjectName(cfg.ProjectName)
+	if err != nil {
+		return invalidConfigResult(projectDir, err), true
+	}
+	return DetectionResult{Project: projectName, Source: SourceConfig, Path: projectDir}, true
+}
+
+func invalidConfigResult(path string, err error) DetectionResult {
+	return DetectionResult{
+		Project: "",
+		Source:  SourceConfig,
+		Path:    path,
+		Error:   fmt.Errorf("%w: %v", ErrInvalidConfig, err),
+	}
+}
+
+func normalizeConfigProjectName(projectName string) (string, error) {
+	trimmed := strings.TrimSpace(projectName)
+	if trimmed == "" {
+		return "", fmt.Errorf("%w: project_name is required", ErrInvalidConfig)
+	}
+	if strings.ContainsAny(trimmed, `/\\`) {
+		return "", fmt.Errorf("%w: project_name must be a name, not a path", ErrInvalidConfig)
+	}
+	for _, r := range trimmed {
+		if r < 0x20 || r == 0x7f {
+			return "", fmt.Errorf("%w: project_name contains control characters", ErrInvalidConfig)
+		}
+	}
+	return normalize(trimmed), nil
+}
+
 // detectGitRootDir returns the git repository root for dir, or "" if not in a repo.
 func detectGitRootDir(dir string) string {
 	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)