@zgeoff/atc 0.1.8 → 0.1.9

package/README.md

@@ -27,7 +27,10 @@ atc
 ```
 
 Needs [Bun](https://bun.sh) (atc runs from source through it) and the `claude` CLI on your PATH.
-From a checkout, `bun src/cli.ts` runs the same thing.
+From a checkout, `bun src/cli.ts` runs the same thing. atc is built to pair with
+[zoxide](https://github.com/ajeetdsouza/zoxide): the spawn directory picker feeds on its frecency
+list, so with zoxide installed every directory you visit is two keystrokes from a session. Without
+it the picker falls back to atc's own spawn history.
 
 The first invocation auto-spawns the daemon (`atc daemon` runs it in the foreground for systemd or
 debugging); the TUI is a thin client, so quitting or crashing it leaves every session running. Runs
@@ -38,7 +41,7 @@ fine nested inside zellij/tmux (give the pane locked mode so Ctrl-Space reaches
 | Key             | Where          | Action                                                                                         |
 | --------------- | -------------- | ---------------------------------------------------------------------------------------------- |
 | leader          | anywhere       | toggle session overlay — `Ctrl-Space` by default, configurable (see Config)                    |
-| `n`             | home/overlay   | spawn: pick dir (zoxide + history, fuzzy) → name → optional group → optional first prompt      |
+| `n`             | home/overlay   | spawn: pick dir (zoxide + history, fuzzy) → name → optional first prompt                       |
 | `r`             | home/overlay   | adopt: pick dir → name → `claude --resume` (Claude's session picker opens in the new PTY)      |
 | `R`             | home           | restore last fleet after a daemon death — respawns every session via `claude --resume <id>`    |
 | `j`/`k`/`↑`/`↓` | overlay/picker | move                                                                                           |
@@ -46,6 +49,8 @@ fine nested inside zellij/tmux (give the pane locked mode so Ctrl-Space reaches
 | `Tab`           | overlay        | attach the most urgent needs-you session, else the latest turn-done one                        |
 | `/`             | overlay        | fuzzy filter by name/dir (chars in order), `⏎` attach top match, `esc` clear                   |
 | `a`             | overlay        | ack notification without attaching                                                             |
+| `p`             | overlay        | pin or unpin the selected session — pinned sessions stay at the top of the list                |
+| `g`             | overlay        | toggle the grouped view: sessions cluster under repository headers                             |
 | `H`             | overlay        | eject to headless: the terminal dies, a headless Agent SDK run resumes the same session        |
 | `P`             | overlay        | revive: a fresh terminal resumes a headless or killed session in place                         |
 | `y`             | overlay        | yank `cd <dir> && claude --resume <id>` to clipboard (OSC 52 + clip.exe/wl-copy/xclip)         |
@@ -55,10 +60,12 @@ fine nested inside zellij/tmux (give the pane locked mode so Ctrl-Space reaches
 | `u`             | overlay        | restart an outdated daemon and restore the fleet — offered only while `⟳ update ready` shows   |
 | `q`             | home/overlay   | quit the client — sessions keep running in the daemon                                          |
 
-The overlay clusters sessions under dim headers when more than one group exists: a session's
-explicit group wins, and sessions without one fall back to the directory they were spawned from.
-Groups also come from outside — the `atc_session_update` MCP tool renames and regroups sessions, so
-an agent can organise the fleet for you.
+The overlay orders sessions by pinned first, then attention state, then most recently attached, so
+the session you want is nearly always near the top. The grouped view (`g`) keeps that order but
+clusters sessions under dim repository headers, with pinned sessions leading in their own cluster; a
+git worktree clusters with its main repository, and a directory outside any repository stands alone.
+The `atc_session_update` MCP tool renames and pins sessions, so an agent can organise the fleet for
+you.
 
 Revive (`P`) and headless eject (`H`) resume the session from its saved transcript, so both need one
 to exist: a session killed before its first exchange has nothing on disk yet, and the overlay says
@@ -74,8 +81,8 @@ status bar only on the home and overlay screens.
 Spawned sessions get a `--settings` file injecting `Notification`, `Stop`, `UserPromptSubmit`, and
 `SessionEnd` hooks that report to a unix socket (`$XDG_RUNTIME_DIR/atc.sock`). Your global Claude
 settings are untouched; sessions you start outside atc are unaffected. States: red `●` needs you,
-cyan `◐` running, green `✓` turn done, gray `✗` exited. The overlay sorts needs-you first; the
-status bar turns red and names the most urgent session.
+cyan `◐` running, green `✓` turn done, gray `✗` exited. The status bar turns red and names the most
+urgent session.
 
 ## Config
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/atc",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Terminal control tower for Claude Code sessions",
   "homepage": "https://github.com/zgeoff/atc#readme",
   "bugs": "https://github.com/zgeoff/atc/issues",

package/src/daemon-connection.ts

@@ -15,7 +15,6 @@ interface SpawnParams {
   readonly rows: number;
   readonly resume: boolean | string;
   readonly namedBy: 'user' | 'auto';
-  readonly group?: string;
 }
 
 export interface DaemonContext {
@@ -25,7 +24,7 @@ export interface DaemonContext {
   readonly collectFleet: () => FleetEntry[];
   readonly spawnSession: (p: SpawnParams) => SessionDescriptor;
   readonly killSession: (id: string) => boolean;
-  readonly updateSession: (id: string, name?: string, group?: string) => boolean;
+  readonly updateSession: (id: string, name?: string, pinned?: boolean) => boolean;
   readonly quitDaemon: () => void;
   readonly ackSession: (id: string) => boolean;
   readonly buildResumeCommand: (id: string) => string | null;
@@ -225,9 +224,9 @@ export class DaemonConnection {
       case 'session.update': {
         const sessionID = typeof req.p?.['session'] === 'string' ? req.p['session'] : '';
         const name = typeof req.p?.['name'] === 'string' ? req.p['name'] : undefined;
-        const group = typeof req.p?.['group'] === 'string' ? req.p['group'] : undefined;
+        const pinned = typeof req.p?.['pinned'] === 'boolean' ? req.p['pinned'] : undefined;
 
-        if (this.ctx.updateSession(sessionID, name, group)) {
+        if (this.ctx.updateSession(sessionID, name, pinned)) {
           this.sendOk(req.id, {});
         } else {
           this.sendErr(req.id, 'no_such_session', `no session '${sessionID}'`);
@@ -370,8 +369,6 @@ export class DaemonConnection {
       resume = rawResume;
     }
 
-    const group = typeof req.p?.['group'] === 'string' ? req.p['group'] : '';
-
     const session = this.ctx.spawnSession({
       cwd,
       name: name === '' ? basename(cwd) : name,
@@ -380,7 +377,6 @@ export class DaemonConnection {
       rows: typeof req.p?.['rows'] === 'number' ? req.p['rows'] : 24,
       resume,
       namedBy: name === '' ? 'auto' : 'user',
-      ...(group === '' ? {} : { group }),
     });
 
     this.sendOk(req.id, { session });

package/src/daemon.ts

@@ -418,7 +418,8 @@ export function startDaemon(opts: DaemonOptions): DaemonHandle {
         kind: s.kind,
         alive: s.pty !== null || (s.kind === 'jsonl' && s.state !== 'exited'),
         ...(s.claudeId === undefined ? {} : { claudeId: s.claudeId }),
-        ...(s.group === undefined ? {} : { group: s.group }),
+        pinned: s.pinned,
+        lastAttachedAt: s.lastAttachedAt,
       }),
       renamed: () => ({
         v: PROTOCOL_V,
@@ -457,7 +458,7 @@ export function startDaemon(opts: DaemonOptions): DaemonHandle {
     collectSpawnDirs: () => store.collectSpawnDirs(),
     collectFleet: () => store.loadFleet(),
     spawnSession: (p) => {
-      const s = mgr.spawn(p.cwd, p.name, p.prompt, p.cols, p.rows, p.resume, p.namedBy, p.group);
+      const s = mgr.spawn(p.cwd, p.name, p.prompt, p.cols, p.rows, p.resume, p.namedBy);
 
       ptyDims.set(s.id, { cols: p.cols, rows: p.rows });
       screens.set(s.id, new ScreenModel(p.cols, p.rows));
@@ -465,7 +466,7 @@ export function startDaemon(opts: DaemonOptions): DaemonHandle {
 
       return getDescriptor(mgr, s.id);
     },
-    updateSession: (id, name, group) => mgr.updateSession(id, name, group),
+    updateSession: (id, name, pinned) => mgr.updateSession(id, name, pinned),
     quitDaemon: () => {
       // The ok response for the quit request must flush before the sockets
       // close under it.

package/src/index.ts

@@ -17,7 +17,6 @@ type Mode =
   | 'help'
   | 'picker-dir'
   | 'picker-name'
-  | 'picker-group'
   | 'picker-prompt'
   | 'picker-eject';
 
@@ -25,7 +24,9 @@ interface MirrorSession {
   id: string;
   name: string;
   cwd: string;
-  group?: string;
+  pinned: boolean;
+  lastAttachedAt: number;
+  repoRoot: string;
   state: SessionState;
   unread: boolean;
   lastMsg: string;
@@ -56,7 +57,6 @@ let pickerInput = '';
 let pickerSelected = 0;
 let spawnDir = '';
 let spawnName = '';
-let spawnGroup = '';
 let spawnResume = false;
 const stdout = process.stdout;
 
@@ -202,8 +202,11 @@ function applyHelpKey(buf: Buffer) {
 // fzf-style overlay search: null when inactive, the pattern while active.
 let overlayFilter: string | null = null;
 
+// Flat list by default; g toggles clustering under repository headers.
+let overlayGrouped = false;
+
 function pickOverlaySessions(): MirrorSession[] {
-  const sorted = sortGroupedSessionViews(fleet);
+  const sorted = overlayGrouped ? sortGroupedSessionViews(fleet) : sortSessionViews(fleet);
 
   if (overlayFilter === null || overlayFilter === '') {
     return sorted;
@@ -211,9 +214,7 @@ function pickOverlaySessions(): MirrorSession[] {
 
   const f = overlayFilter;
 
-  return sorted.filter(
-    (s) => findFuzzyScore(`${s.name} ${s.group ?? ''} ${formatDir(s.cwd)}`, f) !== null,
-  );
+  return sorted.filter((s) => findFuzzyScore(`${s.name} ${formatDir(s.cwd)}`, f) !== null);
 }
 
 function renderOverlay() {
@@ -227,6 +228,7 @@ function renderOverlay() {
     confirmKill,
     filter: overlayFilter,
     stale: daemonStale,
+    grouped: overlayGrouped,
   });
 
   scheduleStatus();
@@ -237,7 +239,7 @@ function openOverlay() {
   confirmKill = false;
   overlayFilter = null;
 
-  const focusedIndex = sortGroupedSessionViews(fleet).findIndex((s) => s.id === focusedID);
+  const focusedIndex = pickOverlaySessions().findIndex((s) => s.id === focusedID);
 
   overlaySelected = Math.max(0, focusedIndex);
 
@@ -270,18 +272,6 @@ function renderPicker() {
       placeholder: basename(spawnDir),
       hint: `session name for ${formatDir(spawnDir)} · ⏎ accept · esc back`,
     });
-  } else if (mode === 'picker-group') {
-    const groups = [...new Set(fleet.map((s) => s.group).filter((g) => g !== undefined))];
-    const known = groups.length === 0 ? '' : ` · existing: ${groups.slice(0, 4).join(', ')}`;
-
-    drawPicker({
-      title: `${verb}: group`,
-      items: [],
-      selected: -1,
-      input: pickerInput,
-      placeholder: 'optional — ⏎ to skip',
-      hint: `group for the overlay hierarchy${known} · ⏎ accept · esc back`,
-    });
   } else if (mode === 'picker-eject') {
     drawPicker({
       title: 'eject: headless instruction',
@@ -307,7 +297,6 @@ function renderPicker() {
 
 async function openDirPicker(resume = false) {
   spawnResume = resume;
-  spawnGroup = '';
 
   let recent: string[] = [];
 
@@ -355,7 +344,6 @@ async function spawnFromPicker(prompt: string) {
       cols: cols(),
       rows: ptyRows(),
       ...(spawnResume ? { resume: true } : {}),
-      ...(spawnGroup === '' ? {} : { group: spawnGroup }),
     });
 
     const spawned = toMirrorSession(ok['session']);
@@ -411,7 +399,10 @@ function toMirrorSession(value: unknown): MirrorSession | null {
     id: value['id'],
     name: value['name'],
     cwd: value['cwd'],
-    ...(typeof value['group'] === 'string' ? { group: value['group'] } : {}),
+    pinned: value['pinned'] === true,
+    lastAttachedAt:
+      typeof value['lastAttachedAt'] === 'number' ? value['lastAttachedAt'] : value['createdAt'],
+    repoRoot: typeof value['repoRoot'] === 'string' ? value['repoRoot'] : value['cwd'],
     state,
     unread: value['unread'],
     lastMsg: value['lastMsg'],
@@ -429,6 +420,9 @@ function upsertMirror(d: Readonly<MirrorSession>) {
     fleet.push({ ...d });
   } else {
     existing.name = d.name;
+    existing.pinned = d.pinned;
+    existing.lastAttachedAt = d.lastAttachedAt;
+    existing.repoRoot = d.repoRoot;
     existing.state = d.state;
     existing.unread = d.unread;
     existing.lastMsg = d.lastMsg;
@@ -497,12 +491,12 @@ function applyDaemonEvent(e: EventMsg) {
           s.kind = e['kind'];
         }
 
-        if (typeof e['group'] === 'string') {
-          if (e['group'] === '') {
-            delete s.group;
-          } else {
-            s.group = e['group'];
-          }
+        if (typeof e['pinned'] === 'boolean') {
+          s.pinned = e['pinned'];
+        }
+
+        if (typeof e['lastAttachedAt'] === 'number') {
+          s.lastAttachedAt = e['lastAttachedAt'];
         }
 
         if (typeof e['unread'] === 'boolean') {
@@ -746,6 +740,26 @@ function applyOverlayKey(buf: Buffer) {
     return;
   }
 
+  if (ch === 'g') {
+    overlayGrouped = !overlayGrouped;
+
+    stdout.write(ansi.clear);
+
+    renderOverlay();
+
+    return;
+  }
+
+  if (ch === 'p' && sel !== undefined) {
+    // Flipped locally too so the repaint is immediate; the daemon's state
+    // event confirms it.
+    sel.pinned = !sel.pinned;
+    void sendQuiet('session.update', { session: sel.id, pinned: sel.pinned });
+    renderOverlay();
+
+    return;
+  }
+
   if (ch === '?') {
     openHelp();
 
@@ -1088,30 +1102,6 @@ process.stdin.on('data', (buf: Buffer) => {
         () => {
           spawnName = pickerInput.trim();
           pickerInput = '';
-          mode = 'picker-group';
-
-          stdout.write(ansi.clear);
-
-          renderPicker();
-        },
-        () => {
-          pickerInput = '';
-          mode = 'picker-dir';
-
-          stdout.write(ansi.clear);
-
-          renderPicker();
-        },
-      );
-
-      return;
-    }
-    case 'picker-group': {
-      applyTextKey(
-        buf,
-        () => {
-          spawnGroup = pickerInput.trim();
-          pickerInput = '';
 
           // Adopt skips the prompt step: claude --resume opens its own
           // session picker inside the new PTY.
@@ -1129,7 +1119,7 @@ process.stdin.on('data', (buf: Buffer) => {
         },
         () => {
           pickerInput = '';
-          mode = 'picker-name';
+          mode = 'picker-dir';
 
           stdout.write(ansi.clear);
 
@@ -1147,7 +1137,7 @@ process.stdin.on('data', (buf: Buffer) => {
         },
         () => {
           pickerInput = '';
-          mode = 'picker-group';
+          mode = 'picker-name';
 
           stdout.write(ansi.clear);
 

package/src/mcp-server.ts

@@ -72,13 +72,13 @@ const TOOLS: readonly MCPTool[] = [
   {
     name: 'atc_session_update',
     description:
-      'Rename and/or regroup a session. Renames stick against auto-summaries; an empty group clears the grouping. Use this to organise the fleet: name sessions after their task and group related work.',
+      'Rename and/or pin a session. Renames stick against auto-summaries; pinned sessions lead every list. Use this to organise the fleet: name sessions after their task.',
     inputSchema: {
       type: 'object',
       properties: {
         session: { type: 'string', description: 'The atc session id' },
         name: { type: 'string', description: 'New display name; omit to keep' },
-        group: { type: 'string', description: 'New group; empty string clears, omit to keep' },
+        pinned: { type: 'boolean', description: 'Pin or unpin; omit to keep' },
       },
       required: ['session'],
       additionalProperties: false,
@@ -258,7 +258,7 @@ async function runTool(
       await client.sendRequest('session.update', {
         session: args['session'],
         ...(typeof args['name'] === 'string' ? { name: args['name'] } : {}),
-        ...(typeof args['group'] === 'string' ? { group: args['group'] } : {}),
+        ...(typeof args['pinned'] === 'boolean' ? { pinned: args['pinned'] } : {}),
       });
 
       return 'updated';

package/src/pick-tab-target.ts

@@ -4,6 +4,8 @@ import { sortSessionViews } from './sessions';
 interface TabCandidate {
   readonly id: string;
   readonly state: SessionState;
+  readonly pinned: boolean;
+  readonly lastAttachedAt: number;
   readonly createdAt: number;
   readonly alive: boolean;
   readonly kind: 'pty' | 'jsonl';

package/src/resolve-repo-root.ts

@@ -0,0 +1,51 @@
+import { readFileSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+/**
+ * The repository a directory belongs to, for clustering sessions in the
+ * overlay. Walks toward the filesystem root looking for a `.git` entry: a
+ * directory marks the repository root itself, and a linked worktree's `.git`
+ * file points back at the main repository, so worktrees cluster with it. A
+ * directory outside any repository resolves to itself.
+ */
+export function resolveRepoRoot(cwd: string): string {
+  let dir = cwd;
+
+  while (true) {
+    const marker = join(dir, '.git');
+    const stat = statSync(marker, { throwIfNoEntry: false });
+
+    if (stat !== undefined && stat.isDirectory()) {
+      return dir;
+    }
+
+    if (stat !== undefined && stat.isFile()) {
+      return findMainRoot(marker) ?? dir;
+    }
+
+    const parent = dirname(dir);
+
+    if (parent === dir) {
+      return cwd;
+    }
+
+    dir = parent;
+  }
+}
+
+// A linked worktree's `.git` file reads `gitdir: <main>/.git/worktrees/<name>`.
+function findMainRoot(gitFile: string): string | null {
+  try {
+    const gitdir = /^gitdir:\s*(?<dir>.+)$/mu
+      .exec(readFileSync(gitFile, 'utf8'))
+      ?.groups?.['dir']?.trim();
+
+    if (gitdir === undefined) {
+      return null;
+    }
+
+    return /^(?<root>.+)\/\.git\/worktrees\/[^/]+$/u.exec(gitdir)?.groups?.['root'] ?? null;
+  } catch {
+    return null;
+  }
+}

package/src/sessions.ts

@@ -7,6 +7,7 @@ import { collectCleanEnv } from './collect-clean-env';
 import { socketPath, stateDir, statusFile } from './config';
 import type { HookEvent } from './hooks';
 import { isRecord } from './report';
+import { resolveRepoRoot } from './resolve-repo-root';
 
 export type SessionState = 'running' | 'needs_you' | 'done' | 'exited';
 
@@ -23,7 +24,9 @@ export interface SessionDescriptor {
   readonly lastMsg: string;
   readonly lastDetail?: string;
   readonly claudeId?: string;
-  readonly group?: string;
+  readonly pinned: boolean;
+  readonly lastAttachedAt: number;
+  readonly repoRoot: string;
   readonly namedBy: 'user' | 'auto' | 'agent';
   readonly createdAt: number;
   readonly kind: 'pty' | 'jsonl';
@@ -42,7 +45,15 @@ export interface Session {
   lastDetail?: string;
   claudeId?: string;
   transcriptSource?: string;
-  group?: string;
+  pinned: boolean;
+
+  // when the operator last attached, so lists can lead with the sessions
+  // they were just working in; starts at creation time.
+  lastAttachedAt: number;
+
+  // the repository this session's directory belongs to (the directory
+  // itself outside any repository), for clustering in the overlay.
+  repoRoot: string;
 
   // who last named this session: the agent's own rename beats everything, a
   // user-typed spawn name beats auto-summaries.
@@ -56,7 +67,8 @@ export interface FleetEntry {
   readonly name: string;
   readonly cwd: string;
   readonly claudeId: string;
-  readonly group?: string;
+  readonly pinned?: boolean;
+  readonly lastAttachedAt?: number;
 }
 
 const fleetFile = join(stateDir, 'fleet.json');
@@ -155,7 +167,9 @@ export class SessionManager {
       unread: false,
       lastMsg: 'waiting to restore',
       claudeId: entry.claudeId,
-      ...(entry.group === undefined ? {} : { group: entry.group }),
+      pinned: entry.pinned ?? false,
+      lastAttachedAt: entry.lastAttachedAt ?? Date.now(),
+      repoRoot: resolveRepoRoot(entry.cwd),
       namedBy: 'auto',
       createdAt: Date.now(),
     };
@@ -215,13 +229,12 @@ export class SessionManager {
     return s;
   }
 
-  // Reports a headless run's lifecycle into the session state machine.
   /**
-   * Renames and/or regroups a session on a caller's behalf. A rename lands
-   * at user strength, so auto-summaries stop overwriting it while an
-   * in-session rename still wins. An empty group clears the grouping.
+   * Renames and/or pins a session on a caller's behalf. A rename lands at
+   * user strength, so auto-summaries stop overwriting it while an
+   * in-session rename still wins. Pinned sessions lead every list.
    */
-  updateSession(id: string, name?: string, group?: string): boolean {
+  updateSession(id: string, name?: string, pinned?: boolean): boolean {
     const s = this.sessions.find((x) => x.id === id);
 
     if (s === undefined) {
@@ -235,12 +248,8 @@ export class SessionManager {
       this.onEvent('renamed', s);
     }
 
-    if (group !== undefined) {
-      if (group === '') {
-        delete s.group;
-      } else {
-        s.group = group;
-      }
+    if (pinned !== undefined && pinned !== s.pinned) {
+      s.pinned = pinned;
 
       this.onEvent('state', s);
     }
@@ -305,7 +314,6 @@ export class SessionManager {
     rows: number,
     resume: boolean | string = false,
     namedBy: 'user' | 'auto' = 'auto',
-    group?: string,
   ): Session {
     const id = `s${++counter}-${Date.now().toString(36)}`;
     const plan = this.adapter.planSpawn({ prompt, resume });
@@ -334,7 +342,9 @@ export class SessionManager {
       unread: false,
       lastMsg: initialMsg,
       ...(typeof resume === 'string' ? { claudeId: resume } : {}),
-      ...(group === undefined ? {} : { group }),
+      pinned: false,
+      lastAttachedAt: Date.now(),
+      repoRoot: resolveRepoRoot(cwd),
       namedBy,
       createdAt: Date.now(),
     };
@@ -376,7 +386,9 @@ export class SessionManager {
       lastMsg: s.lastMsg,
       ...(s.lastDetail === undefined ? {} : { lastDetail: s.lastDetail }),
       ...(s.claudeId === undefined ? {} : { claudeId: s.claudeId }),
-      ...(s.group === undefined ? {} : { group: s.group }),
+      pinned: s.pinned,
+      lastAttachedAt: s.lastAttachedAt,
+      repoRoot: s.repoRoot,
       namedBy: s.namedBy,
       createdAt: s.createdAt,
       kind: s.kind,
@@ -508,6 +520,9 @@ export class SessionManager {
     }
 
     s.unread = false;
+    s.lastAttachedAt = Date.now();
+
+    this.writeFleet();
 
     // Attaching answers the attention request: a still-pending prompt
     // re-flags it via the next notification.
@@ -597,7 +612,8 @@ export class SessionManager {
           name: s.name,
           cwd: s.cwd,
           claudeId: s.claudeId,
-          ...(s.group === undefined ? {} : { group: s.group }),
+          ...(s.pinned ? { pinned: true } : {}),
+          lastAttachedAt: s.lastAttachedAt,
         });
       }
     }
@@ -626,10 +642,17 @@ export function countSessionStates(
   return c;
 }
 
-// Overlay order: who needs you first, then finished turns, then busy, then dead.
-export function sortSessionViews<
-  T extends { readonly state: SessionState; readonly createdAt: number },
->(list: readonly T[]): T[] {
+interface SortableSessionView {
+  readonly state: SessionState;
+  readonly pinned: boolean;
+  readonly lastAttachedAt: number;
+  readonly createdAt: number;
+}
+
+// Overlay order: pinned sessions first in most-recently-attached order, then
+// everyone else by urgency — who needs you, finished turns, busy, dead —
+// with most-recently-attached breaking ties inside each state.
+export function sortSessionViews<T extends SortableSessionView>(list: readonly T[]): T[] {
   const rank: Record<SessionState, number> = {
     needs_you: 0,
     done: 1,
@@ -637,24 +660,31 @@ export function sortSessionViews<
     exited: 3,
   };
 
-  return [...list].toSorted((a, b) => rank[a.state] - rank[b.state] || a.createdAt - b.createdAt);
+  return [...list].toSorted((a, b) => {
+    if (a.pinned !== b.pinned) {
+      return a.pinned ? -1 : 1;
+    }
+
+    const recency = b.lastAttachedAt - a.lastAttachedAt || b.createdAt - a.createdAt;
+
+    return a.pinned ? recency : rank[a.state] - rank[b.state] || recency;
+  });
 }
 
-// Overlay display order: the urgency sort with each group's sessions pulled
-// together at the position of its most urgent member, so the renderer's
-// adjacency-based headers appear once per group and urgent groups still lead.
+// Never a filesystem path, so a repository can't collide with it.
+export const PINNED_GROUP_KEY = ' pinned';
+
+// Overlay display order for the grouped view: the flat sort with each
+// repository's sessions pulled together at the position of its best-ranked
+// member, so the renderer's adjacency-based headers appear once per group.
+// Pinned sessions form their own leading group.
 export function sortGroupedSessionViews<
-  T extends {
-    readonly state: SessionState;
-    readonly createdAt: number;
-    readonly group?: string;
-    readonly cwd: string;
-  },
+  T extends SortableSessionView & { readonly repoRoot: string },
 >(list: readonly T[]): T[] {
   const buckets = new Map<string, T[]>();
 
   for (const s of sortSessionViews(list)) {
-    const key = s.group ?? s.cwd;
+    const key = s.pinned ? PINNED_GROUP_KEY : s.repoRoot;
     const bucket = buckets.get(key);
 
     if (bucket === undefined) {

package/src/state-store.ts

@@ -24,7 +24,8 @@ export class StateStore {
         claude_id TEXT PRIMARY KEY,
         name TEXT NOT NULL,
         cwd TEXT NOT NULL,
-        grp TEXT
+        pinned INTEGER NOT NULL DEFAULT 0,
+        last_attached INTEGER
       );
       CREATE TABLE IF NOT EXISTS events (
         id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -40,15 +41,21 @@ export class StateStore {
       );
     `);
 
-    // Stores created before groups existed lack the column; the create
-    // above only applies to fresh databases.
-    const fleetColumns = this.db
-      .query<{ name: string }, []>('PRAGMA table_info(fleet)')
-      .all()
-      .map((c) => c.name);
+    // Stores created before pinning and attach recency existed lack the
+    // columns; the create above only applies to fresh databases.
+    const fleetColumns = new Set(
+      this.db
+        .query<{ name: string }, []>('PRAGMA table_info(fleet)')
+        .all()
+        .map((c) => c.name),
+    );
+
+    if (!fleetColumns.has('pinned')) {
+      this.db.run('ALTER TABLE fleet ADD COLUMN pinned INTEGER NOT NULL DEFAULT 0');
+    }
 
-    if (!fleetColumns.includes('grp')) {
-      this.db.run('ALTER TABLE fleet ADD COLUMN grp TEXT');
+    if (!fleetColumns.has('last_attached')) {
+      this.db.run('ALTER TABLE fleet ADD COLUMN last_attached INTEGER');
     }
 
     if (legacyFleetPath !== undefined) {
@@ -58,20 +65,28 @@ export class StateStore {
 
   loadFleet(): FleetEntry[] {
     const rows = this.db
-      .query<{ claude_id: string; name: string; cwd: string; grp: string | null }, []>(
-        'SELECT claude_id, name, cwd, grp FROM fleet',
-      )
+      .query<
+        {
+          claude_id: string;
+          name: string;
+          cwd: string;
+          pinned: number;
+          last_attached: number | null;
+        },
+        []
+      >('SELECT claude_id, name, cwd, pinned, last_attached FROM fleet')
       .all();
 
     const entries: FleetEntry[] = [];
 
     for (const row of rows) {
-      const entry: FleetEntry =
-        row.grp === null
-          ? { claudeId: row.claude_id, name: row.name, cwd: row.cwd }
-          : { claudeId: row.claude_id, name: row.name, cwd: row.cwd, group: row.grp };
-
-      entries.push(entry);
+      entries.push({
+        claudeId: row.claude_id,
+        name: row.name,
+        cwd: row.cwd,
+        ...(row.pinned === 0 ? {} : { pinned: true }),
+        ...(row.last_attached === null ? {} : { lastAttachedAt: row.last_attached }),
+      });
     }
 
     return entries;
@@ -94,11 +109,13 @@ export class StateStore {
       this.db.run('DELETE FROM fleet');
 
       const insert = this.db.query(
-        'INSERT OR REPLACE INTO fleet (claude_id, name, cwd, grp) VALUES (?1, ?2, ?3, ?4)',
+        'INSERT OR REPLACE INTO fleet (claude_id, name, cwd, pinned, last_attached) VALUES (?1, ?2, ?3, ?4, ?5)',
       );
 
       for (const entry of all) {
-        insert.run(entry.claudeId, entry.name, entry.cwd, entry.group ?? null);
+        const pinned = entry.pinned === true ? 1 : 0;
+
+        insert.run(entry.claudeId, entry.name, entry.cwd, pinned, entry.lastAttachedAt ?? null);
       }
     });
 

package/src/ui.ts

@@ -1,5 +1,6 @@
 import { formatDir } from './dirs';
 import { RESET_INPUT_MODES } from './reset-input-modes';
+import { PINNED_GROUP_KEY } from './sessions';
 import type { SessionState } from './sessions';
 
 // The slice of a session the drawing layer needs; satisfied by both the
@@ -160,7 +161,8 @@ export interface OverlaySessionView extends SessionView {
   readonly alive: boolean;
   readonly kind: 'pty' | 'jsonl';
   readonly resumable: boolean;
-  readonly group?: string;
+  readonly pinned: boolean;
+  readonly repoRoot: string;
 }
 
 export interface OverlayView {
@@ -169,6 +171,7 @@ export interface OverlayView {
   confirmKill: boolean;
   filter: string | null;
   stale: boolean;
+  grouped: boolean;
 }
 
 export function drawOverlay(view: OverlayView) {
@@ -181,32 +184,32 @@ export function drawOverlay(view: OverlayView) {
     rowsList.push(dimRow(width, empty));
   }
 
-  // Sessions cluster under dim headers when more than one group exists: an
-  // explicit group wins, sessions without one fall back to their spawn
-  // directory. The rows keep the sorted order, so urgent groups lead.
-  const grouped = new Set(view.sessions.map((s) => s.group ?? s.cwd)).size > 1;
+  // The grouped view clusters sessions under dim repository headers, with
+  // pinned sessions leading in their own cluster; the flat view shows a
+  // directory column instead. The rows keep the sorted order either way.
   let lastKey: string | null = null;
 
   for (const [i, s] of view.sessions.entries()) {
-    const key = s.group ?? s.cwd;
+    const key = s.pinned ? PINNED_GROUP_KEY : s.repoRoot;
 
-    if (grouped && key !== lastKey) {
+    if (view.grouped && key !== lastKey) {
       lastKey = key;
 
-      rowsList.push(dimRow(width, `▸ ${s.group ?? formatDir(s.cwd)}`));
+      rowsList.push(dimRow(width, `▸ ${s.pinned ? 'pinned' : formatDir(s.repoRoot)}`));
     }
 
     const sel = i === view.selected;
     const name = truncate(s.name, 16).padEnd(16);
     const state = STATE_LABEL[s.state].padEnd(9);
-    const dir = grouped ? '' : ` ${truncate(formatDir(s.cwd), 18).padEnd(18)}`;
-    const msgWidth = Math.max(4, width - 4 - 2 - 17 - 10 - (grouped ? 0 : 19));
+    const dir = view.grouped ? '' : ` ${truncate(formatDir(s.cwd), 18).padEnd(18)}`;
+    const msgWidth = Math.max(4, width - 4 - 3 - 17 - 10 - (view.grouped ? 0 : 19));
     const msg = truncate(s.lastMsg, msgWidth).padEnd(msgWidth);
     const unread = s.unread ? `${ESC}[1;33m!${ESC}[0m` : ' ';
+    const pin = s.pinned ? `${ESC}[93m⋆${ESC}[0m` : ' ';
     const body = `${name} ${state}${dir} ${msg}`;
     const styledBody = sel ? `${ESC}[7m${body}${ESC}[0m` : body;
 
-    rowsList.push(boxRow(width, `${GLYPH[s.state]}${unread}${styledBody}`, 2 + body.length));
+    rowsList.push(boxRow(width, `${GLYPH[s.state]}${unread}${pin}${styledBody}`, 3 + body.length));
   }
 
   rowsList.push(boxDivider(width));
@@ -239,7 +242,7 @@ export function drawOverlay(view: OverlayView) {
   drawBox(rowsList);
 }
 
-const GLOBAL_HINT = 'n new · ? keys';
+const GLOBAL_HINT = 'g groups · n new · ? keys';
 
 // Only the actions valid for the selected row appear; the full reference
 // lives behind ?.
@@ -268,6 +271,10 @@ function buildOverlayHint(s: OverlaySessionView | undefined): string {
     actions.push('K forget');
   }
 
+  const pinAction = s.pinned ? 'p unpin' : 'p pin';
+
+  actions.push(pinAction);
+
   return `${actions.join(' · ')} ▏ ${GLOBAL_HINT}`;
 }
 
@@ -283,6 +290,8 @@ export function drawHelp() {
     'y  yank the resume command to the clipboard',
     'Y  yank the resume command, then kill here',
     'K  kill (K again on a dead session forgets it)',
+    'p  pin or unpin — pinned sessions stay on top',
+    'g  toggle grouping by repository',
     'n  new session',
     'r  adopt an external session',
     '/  filter · ↑↓/jk move · q quit',