feat(forgecode): v3-cleanup — FTS5 message snippets, ConversationSort SSOT, perf audit

crates/forge_api/src/api.rs

@@ -140,6 +140,16 @@ pub trait API: Sync + Send {
         limit: Option<usize>,
     ) -> Result<Option<Vec<Conversation>>>;
 
+    /// Return an FTS5 snippet for a (conversation, query) pair — a short
+    /// highlighted excerpt of the matched passage. Used by the search UI
+    /// to render a preview pane when the user picks a search hit.
+    async fn get_conversation_snippet(
+        &self,
+        conversation_id: &ConversationId,
+        query: &str,
+        token_count: usize,
+    ) -> Result<Option<String>>;
+
     /// Renames a conversation by setting its title
     ///
     /// # Arguments

crates/forge_api/src/forge_api.rs

@@ -260,6 +260,17 @@ impl<
         self.services.get_conversations_by_cwd(cwd, limit).await
     }
 
+    async fn get_conversation_snippet(
+        &self,
+        conversation_id: &ConversationId,
+        query: &str,
+        token_count: usize,
+    ) -> Result<Option<String>> {
+        self.services
+            .get_conversation_snippet(conversation_id, query, token_count)
+            .await
+    }
+
     async fn rename_conversation(
         &self,
         conversation_id: &ConversationId,

crates/forge_app/src/services.rs

@@ -316,6 +316,16 @@ pub trait ConversationService: Send + Sync {
         cwd: &str,
         limit: Option<usize>,
     ) -> anyhow::Result<Option<Vec<Conversation>>>;
+
+    /// Return an FTS5 snippet for a (conversation, query) pair — a short
+    /// highlighted excerpt of the matched passage. Used by the search UI
+    /// to render a preview pane when the user picks a search hit.
+    async fn get_conversation_snippet(
+        &self,
+        conversation_id: &ConversationId,
+        query: &str,
+        token_count: usize,
+    ) -> anyhow::Result<Option<String>>;
 }
 
 #[async_trait::async_trait]
@@ -761,6 +771,17 @@ impl<I: Services> ConversationService for I {
             .get_conversations_by_cwd(cwd, limit)
             .await
     }
+
+    async fn get_conversation_snippet(
+        &self,
+        conversation_id: &ConversationId,
+        query: &str,
+        token_count: usize,
+    ) -> anyhow::Result<Option<String>> {
+        self.conversation_service()
+            .get_conversation_snippet(conversation_id, query, token_count)
+            .await
+    }
 }
 #[async_trait::async_trait]
 impl<I: Services> ProviderService for I {

crates/forge_domain/src/conversation.rs

@@ -75,6 +75,61 @@ impl MetaData {
     }
 }
 
+/// Sort key for the session viewer selector.
+///
+/// Each variant maps to an `ORDER BY` clause in the `conversations` table.
+/// `Default` is `Updated` because the most common workflow is "show me what
+/// I was working on most recently" — especially after a crash recovery when
+/// the user is trying to find the parent session of a stranded subagent.
+#[derive(Debug, Default, Display, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum ConversationSort {
+    /// Sort by `updated_at` DESC (most recent first). Default.
+    #[default]
+    #[display("updated")]
+    Updated,
+    /// Sort by `created_at` DESC (newest first).
+    #[display("created")]
+    Created,
+    /// Sort by `message_count` DESC, then `updated_at` DESC.
+    /// This is the canonical "turns" view the user asked for.
+    #[display("turns")]
+    Turns,
+    /// Sort by `title` ASC, NULLS LAST.
+    #[display("title")]
+    Title,
+    /// Sort by `cwd` ASC, NULLS LAST, then `updated_at` DESC.
+    /// Useful for finding all sessions in a specific repo.
+    #[display("cwd")]
+    Cwd,
+}
+
+impl ConversationSort {
+    /// Stable lowercase identifier used for CLI parsing and storage.
+    /// Also used by the UI handler for `:sort <key>` echo.
+    pub fn name(self) -> &'static str {
+        match self {
+            ConversationSort::Updated => "updated",
+            ConversationSort::Created => "created",
+            ConversationSort::Turns => "turns",
+            ConversationSort::Title => "title",
+            ConversationSort::Cwd => "cwd",
+        }
+    }
+
+    /// Parse a sort key from a user-supplied string. Unknown keys fall
+    /// back to `Updated` and the caller is expected to print a hint.
+    pub fn parse(s: &str) -> Self {
+        match s.trim().to_ascii_lowercase().as_str() {
+            "created" => ConversationSort::Created,
+            "turns" | "messages" | "msgs" => ConversationSort::Turns,
+            "title" | "name" | "alphabetical" => ConversationSort::Title,
+            "cwd" | "dir" | "directory" => ConversationSort::Cwd,
+            _ => ConversationSort::Updated,
+        }
+    }
+}
+
 impl Conversation {
     pub fn new(id: ConversationId) -> Self {
         let created_at = Utc::now();

crates/forge_domain/src/repo.rs

@@ -170,6 +170,28 @@ pub trait ConversationRepository: Send + Sync {
         limit: Option<usize>,
     ) -> Result<Vec<Conversation>>;
 
+    /// Returns a short FTS5 snippet (~32 tokens) for a single
+    /// `(conversation_id, query)` pair, with the matched terms wrapped in
+    /// `[…]` and the surrounding text wrapped in `…`. Used by the UI to
+    /// render a "matched passage" preview for the currently selected
+    /// search hit without forcing the main search query to include the
+    /// snippet column (which would couple the row layout to
+    /// `ConversationRecord`).
+    ///
+    /// Returns `Ok(None)` when the query does not match that conversation
+    /// — callers should treat `None` as "no preview available" and fall
+    /// back to the conversation title.
+    ///
+    /// # Errors
+    /// Returns an error if the FTS query is malformed or the database
+    /// call fails.
+    async fn get_conversation_snippet(
+        &self,
+        conversation_id: &ConversationId,
+        query: &str,
+        token_count: usize,
+    ) -> Result<Option<String>>;
+
     /// Reclaims FTS5 segment shadow data by running
     /// `INSERT INTO conversations_fts(conversations_fts) VALUES('optimize')`.
     ///

crates/forge_main/src/conversation_selector.rs

@@ -133,6 +133,8 @@ mod tests {
             context: None,
             metrics: Metrics::default().started_at(now),
             metadata: MetaData { created_at: now, updated_at: Some(now) },
+            cwd: None,
+            message_count: None,
             parent_id: None,
             source: None,
         }

crates/forge_main/src/info.rs

@@ -979,6 +979,8 @@ mod tests {
             context: None,
             metrics,
             metadata: forge_domain::MetaData::new(Utc::now()),
+            cwd: None,
+            message_count: None,
             parent_id: None,
             source: None,
         };
@@ -1008,6 +1010,8 @@ mod tests {
             context: None,
             metrics,
             metadata: forge_domain::MetaData::new(Utc::now()),
+            cwd: None,
+            message_count: None,
             parent_id: None,
             source: None,
         };
@@ -1055,6 +1059,8 @@ mod tests {
             context: Some(context),
             metrics,
             metadata: forge_domain::MetaData::new(Utc::now()),
+            cwd: None,
+            message_count: None,
             parent_id: None,
             source: None,
         };

crates/forge_main/src/model.rs

@@ -712,6 +712,18 @@ pub enum AppCommand {
         target: Vec<String>,
     },
 
+    /// Sort the conversation selector. Usage: `:sort <key>` where key is
+    /// one of `updated`, `created`, `turns`, `title`. Persists in
+    /// `UIState.sort` until the session exits or another `:sort` is run.
+    #[strum(props(usage = "Sort the conversation selector. Usage: :sort <key> (updated|created|turns|title)"))]
+    #[command(alias = "so")]
+    Sort {
+        /// Sort key: `updated` (default), `created`, `turns`, or `title`.
+        /// Anything else falls back to `updated` and prints a hint.
+        #[arg(trailing_var_arg = true, num_args = 0..)]
+        target: Vec<String>,
+    },
+
     /// Full-text search over conversation titles and contents (FTS5 BM25).
     /// Usage: `:search <query>` or `:search "rust refactor"`.
     #[strum(props(usage = "Search conversation history. Usage: :search <query>"))]
@@ -812,6 +824,7 @@ impl AppCommand {
             AppCommand::Parent => "parent",
             AppCommand::Reparent { .. } => "reparent",
             AppCommand::Cwd { .. } => "cwd",
+            AppCommand::Sort { .. } => "sort",
             AppCommand::Search { .. } => "search",
             AppCommand::Delete => "delete",
             AppCommand::Rename { .. } => "rename",

crates/forge_main/src/state.rs

@@ -3,6 +3,7 @@ use std::time::Instant;
 
 use derive_setters::Setters;
 use forge_api::{ConversationId, Environment};
+use forge_domain::ConversationSort;
 
 //TODO: UIState and ForgePrompt seem like the same thing and can be merged
 /// State information for the UI
@@ -18,6 +19,10 @@ pub struct UIState {
     /// scopes its results to conversations whose `cwd` column matches.
     /// This is the "filter by project directory" UX.
     pub cwd_filter: Option<String>,
+    /// Sort key for the conversation selector. Re-exported from
+    /// `forge_domain::ConversationSort` so there's one canonical enum
+    /// across the repo / service / UI layers.
+    pub sort: ConversationSort,
 }
 
 impl Default for UIState {
@@ -29,6 +34,7 @@ impl Default for UIState {
             loop_enabled: false,
             last_activity: Instant::now(),
             cwd_filter: None,
+            sort: ConversationSort::default(),
         }
     }
 }
@@ -42,6 +48,7 @@ impl UIState {
             loop_enabled: false,
             last_activity: Instant::now(),
             cwd_filter: None,
+            sort: ConversationSort::default(),
         }
     }
 }

crates/forge_main/src/ui.rs

@@ -2317,6 +2317,21 @@ impl<A: API + ConsoleWriter + 'static, F: Fn(ForgeConfig) -> A + Send + Sync> UI
         .await?
         {
             let conversation_id = conversation.id;
+
+            // Fetch a short FTS5 snippet (~32 tokens) so the user can see
+            // *why* this conversation matched. `None` means no preview —
+            // fall through silently (the title is already shown above).
+            if let Ok(Some(snippet)) = self
+                .api
+                .get_conversation_snippet(&conversation_id, &query, 32)
+                .await
+            {
+                self.writeln_title(TitleFormat::info(format!(
+                    "  matched: {}",
+                    snippet.dimmed()
+                )))?;
+            }
+
             self.state.conversation_id = Some(conversation_id);
             self.on_show_last_message(conversation, false).await?;
             self.writeln_title(TitleFormat::info(format!(
@@ -2423,6 +2438,49 @@ impl<A: API + ConsoleWriter + 'static, F: Fn(ForgeConfig) -> A + Send + Sync> UI
         Ok(())
     }
 
+    async fn handle_sort(&mut self, target: Vec<String>) -> anyhow::Result<()> {
+        use forge_domain::ConversationSort;
+
+        if target.is_empty() || target.iter().any(|t| t == "--help" || t == "-h") {
+            self.writeln_title(TitleFormat::info(
+                "Usage: :sort <turns|updated|created|title|cwd> | :sort --reset",
+            ))?;
+            return Ok(());
+        }
+
+        if target.iter().any(|t| t == "--reset") {
+            self.state.sort = ConversationSort::default();
+            self.writeln_title(TitleFormat::info(format!(
+                "Sort reset to {}",
+                ConversationSort::default().name().bold()
+            )))?;
+            return Ok(());
+        }
+
+        let requested = target.join(" ").trim().to_lowercase();
+        let new_sort = match requested.as_str() {
+            "turns" | "messages" | "msg" | "count" => ConversationSort::Turns,
+            "updated" | "updated_at" | "recent" => ConversationSort::Updated,
+            "created" | "created_at" | "oldest" => ConversationSort::Created,
+            "title" | "name" => ConversationSort::Title,
+            "cwd" | "dir" | "directory" => ConversationSort::Cwd,
+            other => {
+                self.writeln_title(TitleFormat::error(format!(
+                    "Unknown sort key: {} (use: turns|updated|created|title|cwd)",
+                    other
+                )))?;
+                return Ok(());
+            }
+        };
+
+        self.state.sort = new_sort;
+        self.writeln_title(TitleFormat::info(format!(
+            "Sort set to {}",
+            new_sort.name().bold()
+        )))?;
+        Ok(())
+    }
+
     fn user_initiated_conversations(conversations: Vec<Conversation>) -> Vec<Conversation> {
         let related_ids: HashSet<ConversationId> = conversations
             .iter()
@@ -2483,6 +2541,9 @@ impl<A: API + ConsoleWriter + 'static, F: Fn(ForgeConfig) -> A + Send + Sync> UI
             AppCommand::Cwd { target } => {
                 self.handle_cwd(target).await?;
             }
+            AppCommand::Sort { target } => {
+                self.handle_sort(target).await?;
+            }
             AppCommand::Search { query } => {
                 self.handle_search(query).await?;
             }