feat: TUI remote support (#130) (#138)

## The Problem

msgvault already supports remote CLI commands (`stats`, `search`,
`show-message`) against a NAS server. But the TUI—the primary way to
explore your archive—only works locally. If your archive lives on a NAS,
you can't browse it from your laptop.

## What This PR Does

Enables `msgvault tui` to work transparently against a remote server.
When `[remote].url` is configured, the TUI connects to your NAS and
gives you the full browsing experience: aggregate views, drill-down
navigation, search, filtering—everything works identically to local
mode.

```bash
# In config.toml
[remote]
url = "https://nas:8080"
api_key = "your-key"

# Then just run TUI as normal
msgvault tui              # Connects to NAS automatically
msgvault tui --local      # Force local if needed
```

## Implementation

**Server side:** 6 new API endpoints that expose the `query.Engine`
capabilities needed by the TUI:
- `/api/v1/aggregates` – sender/domain/label/time aggregations
- `/api/v1/aggregates/sub` – drill-down into sub-aggregations  
- `/api/v1/messages/filter` – filtered message lists with pagination
- `/api/v1/stats/total` – stats with filter context
- `/api/v1/search/fast` – metadata search (subject, sender, recipient)
- `/api/v1/search/deep` – full-text body search via FTS5

**Client side:** `remote.Engine` implements the full `query.Engine`
interface over HTTP, so the TUI code doesn't change at all—it just gets
a different engine.

**Safety:** Deletion staging and attachment export are disabled in
remote mode. These require local file access and are potentially
destructive, so they're local-only operations.

## Testing
- [x] All handler tests pass (10 new tests for aggregate endpoints)
- [x] Remote engine unit tests pass
- [x] TUI builds with remote support
- [ ] Manual end-to-end testing against NAS

---

Closes #130

---------

Co-authored-by: Wes McKinney <[email protected]>
Co-authored-by: Claude Opus 4.6 <[email protected]>

Author: 3 people

.roborev.toml

@@ -14,6 +14,12 @@ HTTP remote defaults, plaintext key display in interactive CLI,
 enabled=true override on account creation, and page-aligned pagination
 are documented design decisions — see code comments at each site.
 
+Remote engine query string reconstruction in buildSearchQueryString is
+intentionally simplified — phrase quoting edge cases are acceptable since
+the search parser on the server re-parses the query. Empty search queries
+sending q= is expected; the server returns empty results gracefully.
+TimeGranularity defaults to "month" when unspecified, which is correct.
+
 This is a single-user personal tool with no privilege separation, no
 setuid, no shared directories, and no multi-tenant access. Do not flag
 symlink-following, local file overwrites, or similar CWE patterns that

CLAUDE.md

@@ -53,6 +53,7 @@ make lint                     # Run linter
 # TUI and analytics
 ./msgvault tui                                        # Launch TUI
 ./msgvault tui --account [email protected]                # Filter by account
+./msgvault tui --local                                # Force local (override remote config)
 ./msgvault build-cache                                # Build Parquet cache
 ./msgvault build-cache --full-rebuild                 # Full rebuild
 ./msgvault stats                                      # Show archive stats
@@ -63,6 +64,9 @@ make lint                     # Run linter
 ./msgvault import-emlx --account [email protected]         # Specific account(s)
 ./msgvault import-emlx /path/to/dir --identifier [email protected]  # Manual fallback
 
+# Daemon mode (NAS/server deployment)
+./msgvault serve                                      # Start HTTP API + scheduled syncs
+
 # Maintenance
 ./msgvault repair-encoding                            # Fix UTF-8 encoding issues
 ```

README.md

@@ -81,15 +81,20 @@ msgvault tui
 | `add-account EMAIL` | Authorize a Gmail account (use `--headless` for servers) |
 | `sync-full EMAIL` | Full sync (`--limit N`, `--after`/`--before` for date ranges) |
 | `sync EMAIL` | Sync only new/changed messages |
-| `tui` | Launch the interactive TUI (`--account` to filter) |
+| `tui` | Launch the interactive TUI (`--account` to filter, `--local` to force local) |
 | `search QUERY` | Search messages (`--json` for machine output) |
+| `show-message ID` | View full message details (`--json` for machine output) |
 | `mcp` | Start the MCP server for AI assistant integration |
+| `serve` | Run daemon with scheduled sync and HTTP API for remote TUI |
 | `stats` | Show archive statistics |
+| `list-accounts` | List synced email accounts |
 | `verify EMAIL` | Verify archive integrity against Gmail |
 | `export-eml` | Export a message as `.eml` |
 | `import-mbox` | Import email from an MBOX export or `.zip` of MBOX files |
 | `import-emlx` | Import email from an Apple Mail directory tree |
 | `build-cache` | Rebuild the Parquet analytics cache |
+| `update` | Update msgvault to the latest version |
+| `setup` | Interactive first-run configuration wizard |
 | `repair-encoding` | Fix UTF-8 encoding issues |
 | `list-senders` / `list-domains` / `list-labels` | Explore metadata |
 
@@ -125,6 +130,30 @@ See the [Configuration Guide](https://msgvault.io/configuration/) for all option
 
 msgvault includes an MCP server that lets AI assistants search, analyze, and read your archived messages. Connect it to Claude Desktop or any MCP-capable agent and query your full message history conversationally. See the [MCP documentation](https://msgvault.io/usage/chat/) for setup instructions.
 
+## Daemon Mode (NAS/Server)
+
+Run msgvault as a long-running daemon for scheduled syncs and remote access:
+
+```bash
+msgvault serve
+```
+
+Configure scheduled syncs in `config.toml`:
+
+```toml
+[[accounts]]
+email = "[email protected]"
+schedule = "0 2 * * *"   # 2am daily (cron)
+enabled = true
+
+[server]
+api_port = 8080
+bind_addr = "0.0.0.0"
+api_key = "your-secret-key"
+```
+
+The TUI can connect to a remote server by configuring `[remote].url`. Use `--local` to force local database when remote is configured. See [docs/api.md](docs/api.md) for the HTTP API reference.
+
 ## Documentation
 
 - [Setup Guide](https://msgvault.io/guides/oauth-setup/): OAuth, first sync, headless servers

cmd/msgvault/cmd/build_cache.go

@@ -27,10 +27,11 @@ var fullRebuild bool
 // files (_last_sync.json, parquet directories) can corrupt the cache.
 var buildCacheMu sync.Mutex
 
-// syncState tracks the last exported message ID for incremental updates.
+// syncState tracks the message and sync-run watermarks covered by the cache.
 type syncState struct {
-	LastMessageID int64     `json:"last_message_id"`
-	LastSyncAt    time.Time `json:"last_sync_at"`
+	LastMessageID          int64     `json:"last_message_id"`
+	LastSyncAt             time.Time `json:"last_sync_at"`
+	LastCompletedSyncRunID int64     `json:"last_completed_sync_run_id,omitempty"`
 }
 
 var buildCacheCmd = &cobra.Command{
@@ -116,13 +117,39 @@ func buildCache(dbPath, analyticsDir string, fullRebuild bool) (*buildResult, er
 	}
 
 	var maxMessageID sql.NullInt64
+	var lastCompletedSyncRunID int64
 	// Use indexed query: id is PRIMARY KEY, sent_at has an index
 	maxIDQuery := `SELECT MAX(id) FROM messages WHERE sent_at IS NOT NULL`
 	if err := sqliteDB.QueryRow(maxIDQuery).Scan(&maxMessageID); err != nil {
-		sqliteDB.Close()
+		if closeErr := sqliteDB.Close(); closeErr != nil {
+			return nil, fmt.Errorf("get max message id: %w; close sqlite: %v", err, closeErr)
+		}
 		return nil, fmt.Errorf("get max message id: %w", err)
 	}
-	sqliteDB.Close()
+	var hasSyncRunsTable int
+	if err := sqliteDB.QueryRow(`
+		SELECT COUNT(*) FROM sqlite_master
+		WHERE type = 'table' AND name = 'sync_runs'
+	`).Scan(&hasSyncRunsTable); err != nil {
+		if closeErr := sqliteDB.Close(); closeErr != nil {
+			return nil, fmt.Errorf("check sync_runs table: %w; close sqlite: %v", err, closeErr)
+		}
+		return nil, fmt.Errorf("check sync_runs table: %w", err)
+	}
+	if hasSyncRunsTable > 0 {
+		if err := sqliteDB.QueryRow(`
+			SELECT COALESCE(MAX(id), 0) FROM sync_runs
+			WHERE status = 'completed' AND completed_at IS NOT NULL
+		`).Scan(&lastCompletedSyncRunID); err != nil {
+			if closeErr := sqliteDB.Close(); closeErr != nil {
+				return nil, fmt.Errorf("get last completed sync run id: %w; close sqlite: %v", err, closeErr)
+			}
+			return nil, fmt.Errorf("get last completed sync run id: %w", err)
+		}
+	}
+	if err := sqliteDB.Close(); err != nil {
+		return nil, fmt.Errorf("close sqlite after metadata check: %w", err)
+	}
 
 	maxID := int64(0)
 	if maxMessageID.Valid {
@@ -180,6 +207,12 @@ func buildCache(dbPath, analyticsDir string, fullRebuild bool) (*buildResult, er
 	fmt.Println("Building cache...")
 	buildStart := time.Now()
 
+	// Capture deletion watermark before export starts. Any deletion
+	// with deleted_from_source_at after this timestamp may not be
+	// reflected in the exported Parquet data and will trigger a
+	// cache rebuild on the next freshness check.
+	cacheWatermark := time.Now().UTC().Truncate(time.Second)
+
 	// Build WHERE clause for incremental exports
 	idFilter := ""
 	if !fullRebuild && lastMessageID > 0 {
@@ -391,10 +424,12 @@ func buildCache(dbPath, analyticsDir string, fullRebuild bool) (*buildResult, er
 		exportedCount = 0
 	}
 
-	// Save sync state
+	// Save sync state using the pre-export watermark so any deletion
+	// that occurs during or after the build is detected as stale.
 	state := syncState{
-		LastMessageID: maxID,
-		LastSyncAt:    time.Now(),
+		LastMessageID:          maxID,
+		LastSyncAt:             cacheWatermark,
+		LastCompletedSyncRunID: lastCompletedSyncRunID,
 	}
 	stateData, _ := json.Marshal(state)
 	if err := os.WriteFile(stateFile, stateData, 0644); err != nil {