feat: add frecency sort that ranks sessions by launch frequency and recency

Records a launch count and last-launched time per session from the TUI and
dispatch open, then adds a frecency sort field that blends launch frequency
with a recency decay. Sessions with no launch history keep updated-time order.

Closes #230

Co-authored-by: Copilot App <[email protected]>

Author: jongio

internal/config/config.go

@@ -79,7 +79,7 @@ func (v *NamedView) Validate() error {
 	}
 	if v.Sort != "" {
 		switch v.Sort {
-		case SortFieldUpdated, SortFieldCreated, SortFieldTurns, SortFieldName, SortFieldFolder:
+		case SortFieldUpdated, SortFieldCreated, SortFieldTurns, SortFieldName, SortFieldFolder, SortFieldFrecency:
 		default:
 			return fmt.Errorf("named view %q: invalid sort %q", v.Name, v.Sort)
 		}
@@ -202,6 +202,11 @@ type Config struct {
 	// by a marker in the session list.
 	SessionNotes map[string]string `json:"sessionNotes,omitempty"`
 
+	// SessionLaunches maps session IDs to their launch statistics. It is
+	// used by the frecency sort to rank sessions the user launches often
+	// and recently ahead of ones they rarely open.
+	SessionLaunches map[string]SessionLaunch `json:"sessionLaunches,omitempty"`
+
 	// AISearch enables Copilot SDK-powered AI search. When false (the
 	// default), only the local FTS5 index is used.  Set to true to also
 	// query the Copilot backend for semantically relevant sessions.
@@ -338,11 +343,12 @@ const (
 
 // Sort field constants for NamedView.Sort and DefaultSort.
 const (
-	SortFieldUpdated = "updated"
-	SortFieldCreated = "created"
-	SortFieldTurns   = "turns"
-	SortFieldName    = "name"
-	SortFieldFolder  = "folder"
+	SortFieldUpdated  = "updated"
+	SortFieldCreated  = "created"
+	SortFieldTurns    = "turns"
+	SortFieldName     = "name"
+	SortFieldFolder   = "folder"
+	SortFieldFrecency = "frecency"
 )
 
 // Pivot mode constants for NamedView.Pivot.

internal/config/frecency.go

@@ -0,0 +1,54 @@
+package config
+
+import (
+	"math"
+	"time"
+)
+
+// frecencyHalfLife is the age at which a session's launch weight decays to
+// half. A week strikes a balance between surfacing recent work and keeping
+// long-running favorites near the top.
+const frecencyHalfLife = 7 * 24 * time.Hour
+
+// SessionLaunch records how many times a session has been launched from
+// Dispatch and when it was last launched. It powers the frecency sort.
+type SessionLaunch struct {
+	// Count is the total number of times the session has been launched.
+	Count int `json:"count"`
+
+	// Last is the Unix time (seconds) of the most recent launch.
+	Last int64 `json:"last"`
+}
+
+// RecordLaunch increments the launch count for a session and stamps the launch
+// time. now is passed in so callers and tests control the clock. Empty session
+// IDs are ignored so new sessions started without an ID do not pollute stats.
+func (c *Config) RecordLaunch(sessionID string, now time.Time) {
+	if sessionID == "" {
+		return
+	}
+	if c.SessionLaunches == nil {
+		c.SessionLaunches = make(map[string]SessionLaunch)
+	}
+	st := c.SessionLaunches[sessionID]
+	st.Count++
+	st.Last = now.Unix()
+	c.SessionLaunches[sessionID] = st
+}
+
+// FrecencyScore returns a ranking score for a session's launch history. Higher
+// scores rank first. The score is the launch count scaled by an exponential
+// recency decay, so a session launched often and recently outranks one that is
+// launched often but long ago, or recently but only once. A session with no
+// launches scores zero, which lets the sort fall back to its incoming order.
+func FrecencyScore(st SessionLaunch, now time.Time) float64 {
+	if st.Count <= 0 {
+		return 0
+	}
+	age := now.Sub(time.Unix(st.Last, 0))
+	if age < 0 {
+		age = 0
+	}
+	decay := math.Exp2(-age.Hours() / frecencyHalfLife.Hours())
+	return float64(st.Count) * decay
+}

internal/config/frecency_test.go

@@ -0,0 +1,89 @@
+package config
+
+import (
+	"testing"
+	"time"
+)
+
+func TestRecordLaunch(t *testing.T) {
+	c := &Config{}
+	base := time.Unix(1_000_000, 0)
+	c.RecordLaunch("s1", base)
+	if got := c.SessionLaunches["s1"].Count; got != 1 {
+		t.Fatalf("Count = %d, want 1", got)
+	}
+	if got := c.SessionLaunches["s1"].Last; got != base.Unix() {
+		t.Errorf("Last = %d, want %d", got, base.Unix())
+	}
+	later := base.Add(time.Hour)
+	c.RecordLaunch("s1", later)
+	if got := c.SessionLaunches["s1"].Count; got != 2 {
+		t.Errorf("Count = %d, want 2", got)
+	}
+	if got := c.SessionLaunches["s1"].Last; got != later.Unix() {
+		t.Errorf("Last = %d, want %d", got, later.Unix())
+	}
+}
+
+func TestRecordLaunchIgnoresEmptyID(t *testing.T) {
+	c := &Config{}
+	c.RecordLaunch("", time.Now())
+	if len(c.SessionLaunches) != 0 {
+		t.Errorf("empty ID should not be recorded, got %d entries", len(c.SessionLaunches))
+	}
+}
+
+func TestFrecencyScoreZeroWithoutLaunches(t *testing.T) {
+	if s := FrecencyScore(SessionLaunch{}, time.Now()); s != 0 {
+		t.Errorf("score = %v, want 0 for no launches", s)
+	}
+}
+
+func TestFrecencyScoreRanksMoreLaunchesHigher(t *testing.T) {
+	now := time.Now()
+	last := now.Unix()
+	few := FrecencyScore(SessionLaunch{Count: 1, Last: last}, now)
+	many := FrecencyScore(SessionLaunch{Count: 5, Last: last}, now)
+	if many <= few {
+		t.Errorf("more launches should score higher: many=%v few=%v", many, few)
+	}
+}
+
+func TestFrecencyScoreRanksRecentHigher(t *testing.T) {
+	now := time.Now()
+	recent := FrecencyScore(SessionLaunch{Count: 3, Last: now.Unix()}, now)
+	old := FrecencyScore(SessionLaunch{Count: 3, Last: now.Add(-30 * 24 * time.Hour).Unix()}, now)
+	if recent <= old {
+		t.Errorf("more recent should score higher: recent=%v old=%v", recent, old)
+	}
+}
+
+func TestFrecencyScoreHalfLifeDecay(t *testing.T) {
+	now := time.Now()
+	fresh := FrecencyScore(SessionLaunch{Count: 4, Last: now.Unix()}, now)
+	oneHalfLife := FrecencyScore(SessionLaunch{Count: 4, Last: now.Add(-frecencyHalfLife).Unix()}, now)
+	ratio := oneHalfLife / fresh
+	if ratio < 0.45 || ratio > 0.55 {
+		t.Errorf("half-life decay ratio = %v, want ~0.5", ratio)
+	}
+}
+
+func TestSessionLaunchesRoundTrip(t *testing.T) {
+	withTempConfigDir(t)
+	original := &Config{
+		SessionLaunches: map[string]SessionLaunch{
+			"s1": {Count: 3, Last: 1_700_000_000},
+		},
+	}
+	if err := Save(original); err != nil {
+		t.Fatalf("Save: %v", err)
+	}
+	loaded, err := Load()
+	if err != nil {
+		t.Fatalf("Load: %v", err)
+	}
+	got := loaded.SessionLaunches["s1"]
+	if got.Count != 3 || got.Last != 1_700_000_000 {
+		t.Errorf("round-trip = %+v, want {Count:3 Last:1700000000}", got)
+	}
+}

internal/data/models.go

@@ -239,6 +239,10 @@ const (
 	// (Waiting > Active > Stale > Idle). This is applied post-load
 	// in the TUI layer since attention status is computed at runtime.
 	SortByAttention SortField = "attention"
+	// SortByFrecency ranks sessions by how often and how recently the user
+	// has launched them. Like attention, it is applied post-load in the TUI
+	// layer because launch statistics live in the user config, not the store.
+	SortByFrecency SortField = "frecency"
 )
 
 // SortOrder indicates ascending or descending sort direction.

internal/tui/frecency_sort_test.go

@@ -0,0 +1,69 @@
+package tui
+
+import (
+	"testing"
+	"time"
+
+	"github.com/jongio/dispatch/internal/config"
+	"github.com/jongio/dispatch/internal/data"
+)
+
+func TestSortByFrecency_WrongField(t *testing.T) {
+	m := newTestModel()
+	m.sort.Field = data.SortByUpdated
+	m.cfg.SessionLaunches = map[string]config.SessionLaunch{"s2": {Count: 9, Last: time.Now().Unix()}}
+	sessions := []data.Session{{ID: "s1"}, {ID: "s2"}}
+	m.sortByFrecency(sessions)
+	if sessions[0].ID != "s1" {
+		t.Errorf("no-op expected when field != frecency, got %s first", sessions[0].ID)
+	}
+}
+
+func TestSortByFrecency_RanksMostUsedFirst(t *testing.T) {
+	m := newTestModel()
+	m.sort.Field = data.SortByFrecency
+	m.sort.Order = data.Descending
+	now := time.Now().Unix()
+	m.cfg.SessionLaunches = map[string]config.SessionLaunch{
+		"low":  {Count: 1, Last: now},
+		"high": {Count: 10, Last: now},
+	}
+	sessions := []data.Session{{ID: "low"}, {ID: "high"}}
+	m.sortByFrecency(sessions)
+	if sessions[0].ID != "high" {
+		t.Errorf("most-used should be first, got %s", sessions[0].ID)
+	}
+}
+
+func TestSortByFrecency_NoHistoryFallbackKeepsOrder(t *testing.T) {
+	m := newTestModel()
+	m.sort.Field = data.SortByFrecency
+	m.sort.Order = data.Descending
+	m.cfg.SessionLaunches = map[string]config.SessionLaunch{
+		"b": {Count: 4, Last: time.Now().Unix()},
+	}
+	sessions := []data.Session{{ID: "a"}, {ID: "c"}, {ID: "b"}}
+	m.sortByFrecency(sessions)
+	if sessions[0].ID != "b" {
+		t.Errorf("launched session should be first, got %s", sessions[0].ID)
+	}
+	if sessions[1].ID != "a" || sessions[2].ID != "c" {
+		t.Errorf("no-history order should be stable a,c; got %s,%s", sessions[1].ID, sessions[2].ID)
+	}
+}
+
+func TestSortByFrecency_RecencyDecayOrders(t *testing.T) {
+	m := newTestModel()
+	m.sort.Field = data.SortByFrecency
+	m.sort.Order = data.Descending
+	now := time.Now()
+	m.cfg.SessionLaunches = map[string]config.SessionLaunch{
+		"stale":  {Count: 3, Last: now.Add(-60 * 24 * time.Hour).Unix()},
+		"recent": {Count: 3, Last: now.Unix()},
+	}
+	sessions := []data.Session{{ID: "stale"}, {ID: "recent"}}
+	m.sortByFrecency(sessions)
+	if sessions[0].ID != "recent" {
+		t.Errorf("recent should outrank stale at equal counts, got %s", sessions[0].ID)
+	}
+}

internal/tui/handlers.go

@@ -196,6 +196,7 @@ func (m Model) handleSessionsLoaded(msg sessionsLoadedMsg) (Model, tea.Cmd) {
 	prevID := m.selectedSessionID()
 	m.sessions = m.applySessionFilters(msg.sessions)
 	m.sortByAttention(m.sessions)
+	m.sortByFrecency(m.sessions)
 	m.groups = nil
 	m.syncSessionListStatuses()
 	m.sessionList.SetSessions(m.sessions)
@@ -221,6 +222,7 @@ func (m Model) handleGroupsLoaded(msg groupsLoadedMsg) (Model, tea.Cmd) {
 	m.groups = m.applyGroupFilters(msg.groups)
 	for i := range m.groups {
 		m.sortByAttention(m.groups[i].Sessions)
+		m.sortByFrecency(m.groups[i].Sessions)
 	}
 	m.sessions = nil
 	m.syncSessionListStatuses()
@@ -716,6 +718,7 @@ func (m Model) handleAISessionsLoaded(msg aiSessionsLoadedMsg) (Model, tea.Cmd)
 			}
 		}
 		m.sortByAttention(m.sessions)
+		m.sortByFrecency(m.sessions)
 		m.syncSessionListStatuses()
 		m.sessionList.SetSessions(m.sessions)
 		m.searchBar.SetResultCount(m.sessionList.SessionCount())

internal/tui/model.go

@@ -3148,6 +3148,25 @@ func attentionPriority(status data.AttentionStatus) int {
 	}
 }
 
+// sortByFrecency re-sorts the session slice by frecency when the current
+// sort field is SortByFrecency. Sessions the user launches often and
+// recently sort first; sessions with no launch history keep their incoming
+// (updated-time) order via a stable sort.
+func (m *Model) sortByFrecency(sessions []data.Session) {
+	if m.sort.Field != data.SortByFrecency {
+		return
+	}
+	now := time.Now()
+	slices.SortStableFunc(sessions, func(a, b data.Session) int {
+		sa := config.FrecencyScore(m.cfg.SessionLaunches[a.ID], now)
+		sb := config.FrecencyScore(m.cfg.SessionLaunches[b.ID], now)
+		if m.sort.Order == data.Ascending {
+			return cmp.Compare(sa, sb)
+		}
+		return cmp.Compare(sb, sa)
+	})
+}
+
 // ---------------------------------------------------------------------------
 // Sort / pivot cycling
 // ---------------------------------------------------------------------------
@@ -3157,6 +3176,7 @@ var sortFields = []data.SortField{
 	data.SortByFolder,
 	data.SortByName,
 	data.SortByAttention,
+	data.SortByFrecency,
 }
 
 func (m *Model) cycleSort() {
@@ -3254,6 +3274,8 @@ func sortDisplayLabel(f data.SortField) string {
 		return "name"
 	case data.SortByAttention:
 		return "attention"
+	case data.SortByFrecency:
+		return "frecency"
 	default:
 		return "updated"
 	}
@@ -3439,6 +3461,7 @@ func (m *Model) resolveShellAndLaunchDirect(sessionID, cwd, mode string) tea.Cmd
 // runs the Copilot CLI session resume in the current terminal, and quits
 // the TUI when the session ends.
 func (m *Model) launchInPlace(sessionID, cwd string) tea.Cmd {
+	m.recordLaunch(sessionID)
 	cfg := m.resumeConfigForSession(cwd)
 	cmd, err := platform.NewResumeCmd(sessionID, cfg)
 	if err != nil {
@@ -3464,6 +3487,7 @@ func launchStyleForMode(mode string) string {
 
 // launchExternal opens the session in a new tab, window, or pane depending on launchStyle.
 func (m *Model) launchExternal(shell platform.ShellInfo, sessionID, cwd, launchStyle string) tea.Cmd {
+	m.recordLaunch(sessionID)
 	cfg := m.resumeConfigForSession(cwd)
 	cfg.LaunchStyle = launchStyle
 	return func() tea.Msg {
@@ -3488,6 +3512,17 @@ func (m Model) resumeConfigForSession(cwd string) platform.ResumeConfig {
 	}
 }
 
+// recordLaunch stamps a session launch in the config so the frecency sort
+// can rank frequently and recently launched sessions first. Empty IDs (new
+// sessions started from a folder) are ignored.
+func (m *Model) recordLaunch(sessionID string) {
+	if sessionID == "" {
+		return
+	}
+	m.cfg.RecordLaunch(sessionID, time.Now())
+	m.saveConfig()
+}
+
 func (m Model) selectedSessionID() string {
 	if sess, ok := m.sessionList.Selected(); ok {
 		return sess.ID
@@ -4300,6 +4335,8 @@ func sortFieldFromConfig(s string) data.SortField {
 		return data.SortByName
 	case pivotFolder, "cwd":
 		return data.SortByFolder
+	case "frecency":
+		return data.SortByFrecency
 	default:
 		return data.SortByUpdated
 	}
@@ -4315,6 +4352,8 @@ func sortFieldToConfig(f data.SortField) string {
 		return "name"
 	case data.SortByFolder:
 		return "folder"
+	case data.SortByFrecency:
+		return "frecency"
 	default:
 		return "updated"
 	}

internal/tui/model_coverage_test.go

@@ -479,8 +479,8 @@ func TestCovCycleSortFullCycle(t *testing.T) {
 	m := newTestModel()
 	m.sort.Field = data.SortByUpdated
 
-	// sortFields = [SortByUpdated, SortByFolder, SortByName, SortByAttention]
-	expected := []data.SortField{data.SortByFolder, data.SortByName, data.SortByAttention, data.SortByUpdated}
+	// sortFields = [SortByUpdated, SortByFolder, SortByName, SortByAttention, SortByFrecency]
+	expected := []data.SortField{data.SortByFolder, data.SortByName, data.SortByAttention, data.SortByFrecency, data.SortByUpdated}
 	for _, exp := range expected {
 		m.cycleSort()
 		if m.sort.Field != exp {