test(tui): close coverage gaps and harden env-var tests

docs/engram-cloud/troubleshooting.md

@@ -49,7 +49,7 @@ Cloud auth token is runtime config:
 export ENGRAM_CLOUD_TOKEN="your-token"
 ```
 
-The local `~/.engram/cloud.json` stores the server URL. The token is intentionally read from the environment.
+The local `~/.engram/cloud.json` stores the server URL and may also store a `token` fallback. `ENGRAM_CLOUD_TOKEN` takes precedence over any token in `cloud.json`; if the env var is unset, Engram falls back to `cloud.json.token`. This fallback is intentional (issue #343) for use cases such as background autosync where exporting the env var on every shell is not practical.
 
 ---
 

internal/store/store.go

@@ -483,6 +483,11 @@ func (s *Store) MaxObservationLength() int {
 	return s.cfg.MaxObservationLength
 }
 
+// DataDir returns the configured data directory for the store.
+func (s *Store) DataDir() string {
+	return s.cfg.DataDir
+}
+
 // ─── Store ───────────────────────────────────────────────────────────────────
 
 type Store struct {
@@ -3761,6 +3766,25 @@ func (s *Store) CountPendingNonEnrolledSyncMutations(targetKey string) ([]Pendin
 	return counts, rows.Err()
 }
 
+// CountPendingSyncMutations returns the number of unacknowledged mutations for
+// the given target that are currently eligible to sync (global/project-empty or
+// enrolled projects).
+func (s *Store) CountPendingSyncMutations(targetKey string) (int64, error) {
+	targetKey = normalizeSyncTargetKey(targetKey)
+	var count int64
+	row := s.db.QueryRow(`
+		SELECT COUNT(*)
+		FROM sync_mutations sm
+		LEFT JOIN sync_enrolled_projects sep ON sm.project = sep.project
+		WHERE sm.target_key = ? AND sm.acked_at IS NULL
+		  AND (sm.project = '' OR sep.project IS NOT NULL)
+	`, targetKey)
+	if err := row.Scan(&count); err != nil {
+		return 0, err
+	}
+	return count, nil
+}
+
 // SkipAckNonEnrolledMutations acks (marks as skipped) all pending mutations
 // that belong to non-enrolled projects, preventing journal bloat. Empty-project
 // mutations are never skipped — they always sync regardless of enrollment.

internal/store/store_test.go

@@ -1382,6 +1382,59 @@ func TestSessionObservationsAddPromptImportAndSyncChunks(t *testing.T) {
 	}
 }
 
+func TestStoreDataDir(t *testing.T) {
+	s := newTestStore(t)
+	if got := s.DataDir(); got == "" {
+		t.Fatal("DataDir should not be empty")
+	}
+}
+
+func TestCountPendingSyncMutations(t *testing.T) {
+	s := newTestStore(t)
+
+	count, err := s.CountPendingSyncMutations(DefaultSyncTargetKey)
+	if err != nil {
+		t.Fatalf("CountPendingSyncMutations empty: %v", err)
+	}
+	if count != 0 {
+		t.Fatalf("count = %d, want 0", count)
+	}
+
+	if err := s.EnrollProject("engram"); err != nil {
+		t.Fatalf("enroll: %v", err)
+	}
+	if err := s.CreateSession("s1", "engram", "/tmp/engram"); err != nil {
+		t.Fatalf("create session: %v", err)
+	}
+
+	count, err = s.CountPendingSyncMutations(DefaultSyncTargetKey)
+	if err != nil {
+		t.Fatalf("CountPendingSyncMutations after session: %v", err)
+	}
+	if count != 1 {
+		t.Fatalf("count = %d, want 1", count)
+	}
+
+	if _, err := s.AddObservation(AddObservationParams{
+		SessionID: "s1",
+		Type:      "bugfix",
+		Title:     "one",
+		Content:   "content",
+		Project:   "engram",
+		Scope:     "project",
+	}); err != nil {
+		t.Fatalf("add observation: %v", err)
+	}
+
+	count, err = s.CountPendingSyncMutations(DefaultSyncTargetKey)
+	if err != nil {
+		t.Fatalf("CountPendingSyncMutations after observation: %v", err)
+	}
+	if count != 2 {
+		t.Fatalf("count = %d, want 2", count)
+	}
+}
+
 func TestStoreLocalSyncFoundationEnqueuesCoreMutations(t *testing.T) {
 	s := newTestStore(t)
 

internal/tui/cloud.go

@@ -0,0 +1,156 @@
+package tui
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	tea "github.com/charmbracelet/bubbletea"
+)
+
+const (
+	cloudConfigFileName = "cloud.json"
+	cloudHealthPath     = "/health"
+)
+
+// Token source labels displayed on the Cloud Config screen.
+const (
+	TokenSourceEnv  = "set via ENGRAM_CLOUD_TOKEN"
+	TokenSourceFile = "read from cloud.json"
+	TokenSourceNone = "not set"
+)
+
+type tuiCloudConfig struct {
+	ServerURL string `json:"server_url"`
+	Token     string `json:"token,omitempty"`
+}
+
+func cloudConfigPath(dataDir string) string {
+	return filepath.Join(dataDir, cloudConfigFileName)
+}
+
+func loadCloudConfig(dataDir string) (*tuiCloudConfig, error) {
+	path := cloudConfigPath(dataDir)
+	b, err := os.ReadFile(path)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return &tuiCloudConfig{}, nil
+		}
+		return nil, err
+	}
+	var cc tuiCloudConfig
+	if err := json.Unmarshal(b, &cc); err != nil {
+		return nil, err
+	}
+	return &cc, nil
+}
+
+func saveCloudConfig(dataDir, serverURL string) error {
+	if err := os.MkdirAll(dataDir, 0o755); err != nil {
+		return err
+	}
+	cc, err := loadCloudConfig(dataDir)
+	if err != nil {
+		return err
+	}
+	cc.ServerURL = serverURL
+	b, err := json.MarshalIndent(cc, "", "  ")
+	if err != nil {
+		return err
+	}
+	return os.WriteFile(cloudConfigPath(dataDir), b, 0o644)
+}
+
+func tokenSourceMessage(dataDir string) string {
+	if strings.TrimSpace(os.Getenv("ENGRAM_CLOUD_TOKEN")) != "" {
+		return TokenSourceEnv
+	}
+	cc, err := loadCloudConfig(dataDir)
+	if err == nil && strings.TrimSpace(cc.Token) != "" {
+		return TokenSourceFile
+	}
+	return TokenSourceNone
+}
+
+func effectiveCloudToken(dataDir string) string {
+	if token := strings.TrimSpace(os.Getenv("ENGRAM_CLOUD_TOKEN")); token != "" {
+		return token
+	}
+	cc, err := loadCloudConfig(dataDir)
+	if err != nil {
+		return ""
+	}
+	return strings.TrimSpace(cc.Token)
+}
+
+// pingCloudTransport can be overridden in tests to avoid real network calls.
+var pingCloudTransport http.RoundTripper = http.DefaultTransport
+
+func pingCloudServer(serverURL, token string) tea.Cmd {
+	return func() tea.Msg {
+		status, err := pingCloudServerStatus(serverURL, token)
+		return cloudPingMsg{status: status, err: err}
+	}
+}
+
+func pingCloudServerStatus(serverURL, token string) (string, error) {
+	validatedURL, err := validateCloudServerURL(serverURL)
+	if err != nil {
+		return "unreachable", err
+	}
+
+	req, err := http.NewRequest(http.MethodGet, validatedURL+cloudHealthPath, nil)
+	if err != nil {
+		return "unreachable", err
+	}
+	if token != "" {
+		req.Header.Set("Authorization", "Bearer "+token)
+	}
+
+	client := &http.Client{Timeout: 3 * time.Second, Transport: pingCloudTransport}
+	resp, err := client.Do(req)
+	if err != nil {
+		return "unreachable", err
+	}
+	defer resp.Body.Close()
+
+	switch {
+	case resp.StatusCode == http.StatusUnauthorized:
+		return "unauthorized", nil
+	case resp.StatusCode >= 200 && resp.StatusCode < 300:
+		return "reachable", nil
+	default:
+		return "unreachable", fmt.Errorf("unexpected status %d", resp.StatusCode)
+	}
+}
+
+func validateCloudServerURL(raw string) (string, error) {
+	trimmed := strings.TrimSpace(raw)
+	parsed, err := url.ParseRequestURI(trimmed)
+	if err != nil {
+		return "", err
+	}
+	scheme := strings.ToLower(strings.TrimSpace(parsed.Scheme))
+	if scheme != "http" && scheme != "https" {
+		return "", fmt.Errorf("scheme must be http or https")
+	}
+	if strings.TrimSpace(parsed.Host) == "" || strings.TrimSpace(parsed.Hostname()) == "" {
+		return "", fmt.Errorf("host is required")
+	}
+	if strings.TrimSpace(parsed.RawQuery) != "" {
+		return "", fmt.Errorf("query is not allowed")
+	}
+	if strings.TrimSpace(parsed.Fragment) != "" {
+		return "", fmt.Errorf("fragment is not allowed")
+	}
+	parsed.RawQuery = ""
+	parsed.Fragment = ""
+	return parsed.String(), nil
+}
+
+