@zgeoff/atc 0.1.7 → 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.7",
+  "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/build-leader-chords.ts

@@ -0,0 +1,27 @@
+/**
+ * Every byte sequence a terminal may deliver for the leader key. A terminal
+ * with no keyboard enhancements sends the bare control byte, one running the
+ * kitty keyboard protocol sends a CSI-u chord, and one running xterm's
+ * modifyOtherKeys sends a CSI-27 chord — a fullscreen agent can switch the
+ * terminal into either of the enhanced encodings mid-session.
+ */
+export function buildLeaderChords(code: number): readonly string[] {
+  const base = getBaseCodePoint(code);
+
+  return [String.fromCodePoint(code), `\u001B[${base};5u`, `\u001B[27;5;${base}~`];
+}
+
+// The enhanced encodings name the unshifted key, not the control byte it
+// maps to: ctrl-space carries space, ctrl-a through ctrl-z carry the
+// lowercase letter, and the punctuation controls carry their symbol.
+function getBaseCodePoint(code: number): number {
+  if (code === 0) {
+    return 32;
+  }
+
+  if (code <= 26) {
+    return code + 96;
+  }
+
+  return code + 64;
+}

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

@@ -1,5 +1,6 @@
 import { basename } from 'node:path';
 import { bootDaemonClient } from './boot-daemon';
+import { buildLeaderChords } from './build-leader-chords';
 import { loadConfig } from './config';
 import { collectDirs, findFuzzyScore, formatDir, pickMatches } from './dirs';
 import { pickTabTarget } from './pick-tab-target';
@@ -16,7 +17,6 @@ type Mode =
   | 'help'
   | 'picker-dir'
   | 'picker-name'
-  | 'picker-group'
   | 'picker-prompt'
   | 'picker-eject';
 
@@ -24,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;
@@ -55,7 +57,6 @@ let pickerInput = '';
 let pickerSelected = 0;
 let spawnDir = '';
 let spawnName = '';
-let spawnGroup = '';
 let spawnResume = false;
 const stdout = process.stdout;
 
@@ -193,7 +194,7 @@ function openHelp() {
 function applyHelpKey(buf: Buffer) {
   const ch = buf.toString();
 
-  if (buf[0] === KEY.esc || ch === '?' || ch === 'q' || buf[0] === leader.code) {
+  if (buf[0] === KEY.esc || ch === '?' || ch === 'q' || isLeaderKey(buf)) {
     openOverlay();
   }
 }
@@ -201,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;
@@ -210,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() {
@@ -226,6 +228,7 @@ function renderOverlay() {
     confirmKill,
     filter: overlayFilter,
     stale: daemonStale,
+    grouped: overlayGrouped,
   });
 
   scheduleStatus();
@@ -236,11 +239,11 @@ 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);
 
-  stdout.write(ansi.clear);
+  stdout.write(ansi.resetInputModes + ansi.clear);
 
   renderOverlay();
 }
@@ -269,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',
@@ -306,7 +297,6 @@ function renderPicker() {
 
 async function openDirPicker(resume = false) {
   spawnResume = resume;
-  spawnGroup = '';
 
   let recent: string[] = [];
 
@@ -354,7 +344,6 @@ async function spawnFromPicker(prompt: string) {
       cols: cols(),
       rows: ptyRows(),
       ...(spawnResume ? { resume: true } : {}),
-      ...(spawnGroup === '' ? {} : { group: spawnGroup }),
     });
 
     const spawned = toMirrorSession(ok['session']);
@@ -375,7 +364,7 @@ function quit(code = 0): never {
   detachFocused();
 
   client.stop();
-  stdout.write(ansi.showCursor + ansi.altScreenOff + ansi.reset);
+  stdout.write(ansi.resetInputModes + ansi.showCursor + ansi.altScreenOff + ansi.reset);
 
   try {
     process.stdin.setRawMode(false);
@@ -410,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'],
@@ -428,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;
@@ -496,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') {
@@ -572,6 +567,7 @@ function copyToClipboard(text: string) {
 // ---- input ----
 
 const leader = loadConfig().leader;
+const leaderChords = buildLeaderChords(leader.code);
 
 const KEY = {
   tab: 0x09,
@@ -590,6 +586,12 @@ function isDown(buf: Buffer): boolean {
   return buf.toString() === '\u001B[B' || buf.toString() === '\u001BOB';
 }
 
+// A fullscreen session can leave the terminal in an enhanced keyboard
+// encoding, so the leader arrives as a CSI chord instead of its bare byte.
+function isLeaderKey(buf: Buffer): boolean {
+  return leaderChords.includes(buf.toString());
+}
+
 function applyOverlayFilterKey(buf: Buffer): boolean {
   if (overlayFilter === null) {
     return false;
@@ -627,7 +629,7 @@ function applyOverlayFilterKey(buf: Buffer): boolean {
     return true;
   }
 
-  if (buf[0] === KEY.enter || isUp(buf) || isDown(buf) || buf[0] === leader.code) {
+  if (buf[0] === KEY.enter || isUp(buf) || isDown(buf) || isLeaderKey(buf)) {
     return false;
   }
 
@@ -685,7 +687,7 @@ function applyOverlayKey(buf: Buffer) {
     return;
   }
 
-  if (buf[0] === leader.code || (buf[0] === KEY.esc && buf.length === 1)) {
+  if (isLeaderKey(buf) || (buf[0] === KEY.esc && buf.length === 1)) {
     toBase();
 
     return;
@@ -738,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();
 
@@ -843,7 +865,7 @@ function applyTextKey(buf: Buffer, onSubmit: () => void, onCancel: () => void) {
     return;
   }
 
-  if (buf[0] === leader.code) {
+  if (isLeaderKey(buf)) {
     toBase();
 
     return;
@@ -985,7 +1007,7 @@ const stdinDecoder = new TextDecoder('utf-8');
 process.stdin.on('data', (buf: Buffer) => {
   switch (mode) {
     case 'attached': {
-      if (buf[0] === leader.code && buf.length === 1) {
+      if (isLeaderKey(buf)) {
         openOverlay();
 
         return;
@@ -1001,7 +1023,7 @@ process.stdin.on('data', (buf: Buffer) => {
       return;
     }
     case 'home': {
-      if (buf[0] === leader.code) {
+      if (isLeaderKey(buf)) {
         openOverlay();
 
         return;
@@ -1080,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.
@@ -1121,7 +1119,7 @@ process.stdin.on('data', (buf: Buffer) => {
         },
         () => {
           pickerInput = '';
-          mode = 'picker-name';
+          mode = 'picker-dir';
 
           stdout.write(ansi.clear);
 
@@ -1139,7 +1137,7 @@ process.stdin.on('data', (buf: Buffer) => {
         },
         () => {
           pickerInput = '';
-          mode = 'picker-group';
+          mode = 'picker-name';
 
           stdout.write(ansi.clear);
 
@@ -1188,7 +1186,7 @@ stdout.on('resize', () => {
 });
 
 process.on('uncaughtException', (err) => {
-  stdout.write(ansi.showCursor + ansi.altScreenOff + ansi.reset);
+  stdout.write(ansi.resetInputModes + ansi.showCursor + ansi.altScreenOff + ansi.reset);
 
   try {
     process.stdin.setRawMode(false);

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/reset-input-modes.ts

@@ -0,0 +1,11 @@
+/**
+ * Returns the terminal's input handling to its unenhanced defaults: pops the
+ * kitty keyboard protocol, clears modifyOtherKeys, and turns off every mode
+ * that changes key encoding or injects reports into stdin (mouse tracking,
+ * SGR mouse encoding, alternate scroll, focus events, bracketed paste, and
+ * color-scheme reports). Written when a session's screen is replaced by a
+ * chrome screen or the outer shell, so a session's input modes never leak
+ * past its own screen; a replay re-applies whatever the session had set.
+ */
+export const RESET_INPUT_MODES =
+  '\u001B[<u\u001B[>4;0m\u001B[?1000l\u001B[?1002l\u001B[?1003l\u001B[?1006l\u001B[?1007l\u001B[?1004l\u001B[?2004l\u001B[?2031l';

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/screen-model.ts

@@ -1,5 +1,10 @@
 import { SerializeAddon } from '@xterm/addon-serialize';
 import { Terminal } from '@xterm/headless';
+import { RESET_INPUT_MODES } from './reset-input-modes';
+
+// The serializer already re-emits the modes the vt engine models (mouse
+// tracking, bracketed paste, focus events); these are the ones it drops.
+const REPLAYED_DEC_MODES = new Set([1006, 1007, 2031]);
 
 /**
  * A per-session vt state machine: consumes every PTY byte continuously and
@@ -7,6 +12,13 @@ import { Terminal } from '@xterm/headless';
  * client is an instant repaint instead of a resize jiggle. Scrollback is
  * capped aggressively — the model exists for the current screen, not
  * history; transcripts on disk are the durable copy.
+ *
+ * The serializer covers buffer content and the modes the vt engine tracks,
+ * but not the input-encoding state a fullscreen agent sets: SGR mouse
+ * encoding, alternate scroll, color-scheme reports, the kitty keyboard
+ * protocol, and modifyOtherKeys. Those are tracked here and folded into the
+ * replay, which first resets every input mode so a replay painted over
+ * another session's screen never inherits its input state.
  */
 export class ScreenModel {
   private readonly term: Terminal;
@@ -15,11 +27,53 @@ export class ScreenModel {
 
   private flushed: Promise<void> = Promise.resolve();
 
+  private readonly decModes = new Map<number, boolean>();
+
+  private readonly kittyFlags: number[] = [];
+
+  private modifyOtherKeys = 0;
+
   constructor(cols: number, rows: number) {
     this.term = new Terminal({ cols, rows, allowProposedApi: true, scrollback: 300 });
     this.serializer = new SerializeAddon();
 
     this.term.loadAddon(this.serializer);
+
+    for (const final of ['h', 'l'] as const) {
+      this.term.parser.registerCsiHandler({ prefix: '?', final }, (params) => {
+        for (const p of params) {
+          if (typeof p === 'number' && REPLAYED_DEC_MODES.has(p)) {
+            this.decModes.set(p, final === 'h');
+          }
+        }
+
+        return false;
+      });
+    }
+
+    this.term.parser.registerCsiHandler({ prefix: '>', final: 'u' }, (params) => {
+      const flags = typeof params[0] === 'number' ? params[0] : 0;
+
+      this.kittyFlags.push(flags);
+
+      return false;
+    });
+
+    this.term.parser.registerCsiHandler({ prefix: '<', final: 'u' }, (params) => {
+      const count = typeof params[0] === 'number' && params[0] > 0 ? params[0] : 1;
+
+      this.kittyFlags.splice(Math.max(0, this.kittyFlags.length - count));
+
+      return false;
+    });
+
+    this.term.parser.registerCsiHandler({ prefix: '>', final: 'm' }, (params) => {
+      if (params[0] === 4) {
+        this.modifyOtherKeys = typeof params[1] === 'number' ? params[1] : 0;
+      }
+
+      return false;
+    });
   }
 
   record(data: string): void {
@@ -35,7 +89,7 @@ export class ScreenModel {
   async renderReplay(): Promise<string> {
     await this.flushed;
 
-    return this.serializer.serialize();
+    return RESET_INPUT_MODES + this.serializer.serialize() + this.renderInputModes();
   }
 
   updateDims(cols: number, rows: number): void {
@@ -45,4 +99,24 @@ export class ScreenModel {
   stop(): void {
     this.term.dispose();
   }
+
+  private renderInputModes(): string {
+    let out = '';
+
+    for (const [mode, on] of this.decModes) {
+      if (on) {
+        out += `\u001B[?${mode}h`;
+      }
+    }
+
+    for (const flags of this.kittyFlags) {
+      out += `\u001B[>${flags}u`;
+    }
+
+    if (this.modifyOtherKeys > 0) {
+      out += `\u001B[>4;${this.modifyOtherKeys}m`;
+    }
+
+    return out;
+  }
 }

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,4 +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
@@ -15,6 +17,7 @@ const ESC = '\u001B';
 
 export const ansi = {
   altScreenOn: `${ESC}[?1049h`,
+  resetInputModes: RESET_INPUT_MODES,
   altScreenOff: `${ESC}[?1049l`,
   clear: `${ESC}[2J${ESC}[H`,
   hideCursor: `${ESC}[?25l`,
@@ -158,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 {
@@ -167,6 +171,7 @@ export interface OverlayView {
   confirmKill: boolean;
   filter: string | null;
   stale: boolean;
+  grouped: boolean;
 }
 
 export function drawOverlay(view: OverlayView) {
@@ -179,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));
@@ -237,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 ?.
@@ -266,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}`;
 }
 
@@ -281,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',