@zgeoff/atc 0.1.8 → 0.1.10

package/src/sessions.ts

@@ -2,11 +2,13 @@ import { readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { spawn } from 'bun-pty';
 import type { IPty } from 'bun-pty';
-import type { AgentAdapter } from './agent-adapter';
+import { toAgentKind } from './agent-adapter';
+import type { AdapterEvent, AgentAdapter, AgentKind } from './agent-adapter';
 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';
 
@@ -22,11 +24,14 @@ export interface SessionDescriptor {
   readonly unread: boolean;
   readonly lastMsg: string;
   readonly lastDetail?: string;
-  readonly claudeId?: string;
-  readonly group?: string;
+  readonly agentSessionID?: string;
+  readonly agent: AgentKind;
+  readonly pinned: boolean;
+  readonly lastAttachedAt: number;
+  readonly repoRoot: string;
   readonly namedBy: 'user' | 'auto' | 'agent';
   readonly createdAt: number;
-  readonly kind: 'pty' | 'jsonl';
+  readonly kind: 'pty' | 'headless';
   readonly alive: boolean;
 }
 
@@ -34,15 +39,24 @@ export interface Session {
   id: string;
   name: string;
   cwd: string;
-  kind: 'pty' | 'jsonl';
+  kind: 'pty' | 'headless';
   pty: IPty | null;
   state: SessionState;
   unread: boolean;
   lastMsg: string;
   lastDetail?: string;
-  claudeId?: string;
+  agentSessionID?: string;
+  agent: AgentKind;
   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.
@@ -55,8 +69,10 @@ let counter = 0;
 export interface FleetEntry {
   readonly name: string;
   readonly cwd: string;
-  readonly claudeId: string;
-  readonly group?: string;
+  readonly agentSessionID: string;
+  readonly agent: AgentKind;
+  readonly pinned?: boolean;
+  readonly lastAttachedAt?: number;
 }
 
 const fleetFile = join(stateDir, 'fleet.json');
@@ -75,6 +91,29 @@ const jsonFleetStore: FleetStore = {
   },
 };
 
+export function parseFleetEntry(raw: unknown): FleetEntry | undefined {
+  if (!isRecord(raw) || typeof raw['name'] !== 'string' || typeof raw['cwd'] !== 'string') {
+    return undefined;
+  }
+
+  // Fleet files written before the id key was agent-neutral carry it under
+  // its Claude-era name.
+  const agentSessionID = raw['agentSessionID'] ?? raw['claudeId'];
+
+  if (typeof agentSessionID !== 'string') {
+    return undefined;
+  }
+
+  return {
+    name: raw['name'],
+    cwd: raw['cwd'],
+    agentSessionID,
+    agent: toAgentKind(raw['agent']),
+    ...(raw['pinned'] === true ? { pinned: true } : {}),
+    ...(typeof raw['lastAttachedAt'] === 'number' ? { lastAttachedAt: raw['lastAttachedAt'] } : {}),
+  };
+}
+
 function loadFleet(): FleetEntry[] {
   try {
     const parsed: unknown = JSON.parse(readFileSync(fleetFile, 'utf8'));
@@ -83,13 +122,17 @@ function loadFleet(): FleetEntry[] {
       return [];
     }
 
-    return parsed.filter(
-      (entry): entry is FleetEntry =>
-        isRecord(entry) &&
-        typeof entry['name'] === 'string' &&
-        typeof entry['cwd'] === 'string' &&
-        typeof entry['claudeId'] === 'string',
-    );
+    const entries: FleetEntry[] = [];
+
+    for (const entry of parsed) {
+      const parsedEntry = parseFleetEntry(entry);
+
+      if (parsedEntry !== undefined) {
+        entries.push(parsedEntry);
+      }
+    }
+
+    return entries;
   } catch {
     return [];
   }
@@ -106,31 +149,51 @@ export class SessionManager {
 
   onEvent: (kind: SessionEventKind, s: Session) => void = () => {};
 
-  private readonly adapter: AgentAdapter;
+  private readonly fallback: AgentAdapter;
+
+  private readonly adapters: Partial<Readonly<Record<AgentKind, AgentAdapter>>>;
 
   private readonly store: FleetStore;
 
   private readonly statusPath: string;
 
-  constructor(adapter: AgentAdapter, store: FleetStore = jsonFleetStore, statusPath = statusFile) {
-    this.adapter = adapter;
+  constructor(
+    fallback: AgentAdapter,
+    store: FleetStore = jsonFleetStore,
+    statusPath: string | undefined = statusFile,
+    adapters: Partial<Readonly<Record<AgentKind, AgentAdapter>>> = {},
+  ) {
+    this.fallback = fallback;
+    this.adapters = adapters;
     this.store = store;
-    this.statusPath = statusPath;
+    this.statusPath = statusPath ?? statusFile;
+  }
+
+  /**
+   * Adapter for this kind, or null when none is registered. Never returns a
+   * different kind than the one asked for.
+   */
+  findAdapter(kind: AgentKind): AgentAdapter | null {
+    if (kind === 'claude') {
+      return this.adapters.claude ?? this.fallback;
+    }
+
+    return this.adapters[kind] ?? null;
   }
 
   // Hands a live terminal session off to a headless run: the terminal dies,
-  // the record lives on as a jsonl session and keeps its screen history.
+  // the record lives on as a headless session and keeps its screen history.
   yankHeadless(id: string): Session | null {
     const s = this.sessions.find((x) => x.id === id);
 
-    if (!s || s.pty === null || s.claudeId === undefined) {
+    if (!s || s.pty === null || s.agentSessionID === undefined) {
       return null;
     }
 
     const pty = s.pty;
 
     s.pty = null;
-    s.kind = 'jsonl';
+    s.kind = 'headless';
     s.state = 'running';
     s.lastMsg = 'ejected to headless';
 
@@ -149,13 +212,16 @@ export class SessionManager {
       id: `s${++counter}-${Date.now().toString(36)}`,
       name: entry.name,
       cwd: entry.cwd,
-      kind: 'jsonl',
+      kind: 'headless',
       pty: null,
       state: 'running',
       unread: false,
       lastMsg: 'waiting to restore',
-      claudeId: entry.claudeId,
-      ...(entry.group === undefined ? {} : { group: entry.group }),
+      agentSessionID: entry.agentSessionID,
+      agent: entry.agent,
+      pinned: entry.pinned ?? false,
+      lastAttachedAt: entry.lastAttachedAt ?? Date.now(),
+      repoRoot: resolveRepoRoot(entry.cwd),
       namedBy: 'auto',
       createdAt: Date.now(),
     };
@@ -172,11 +238,17 @@ export class SessionManager {
   adoptTerminal(id: string, cols: number, rows: number): Session | null {
     const s = this.sessions.find((x) => x.id === id);
 
-    if (!s || s.pty !== null || s.claudeId === undefined) {
+    if (!s || s.pty !== null || s.agentSessionID === undefined) {
       return null;
     }
 
-    const plan = this.adapter.planSpawn({ prompt: '', resume: s.claudeId });
+    const adapter = this.findAdapter(s.agent);
+
+    if (adapter === null) {
+      return null;
+    }
+
+    const plan = adapter.planSpawn({ prompt: '', resume: s.agentSessionID });
 
     const pty = spawn(plan.bin, plan.args, {
       name: 'xterm-256color',
@@ -215,13 +287,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 +306,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);
     }
@@ -255,7 +322,7 @@ export class SessionManager {
   updateSurfaceState(id: string, state: SessionState, msg: string) {
     const s = this.sessions.find((x) => x.id === id);
 
-    if (!s || s.kind !== 'jsonl') {
+    if (!s || s.kind !== 'headless') {
       return;
     }
 
@@ -305,10 +372,16 @@ export class SessionManager {
     rows: number,
     resume: boolean | string = false,
     namedBy: 'user' | 'auto' = 'auto',
-    group?: string,
+    agent: AgentKind = 'claude',
   ): Session {
+    const adapter = this.findAdapter(agent);
+
+    if (adapter === null) {
+      throw new Error(`no adapter for agent '${agent}'`);
+    }
+
     const id = `s${++counter}-${Date.now().toString(36)}`;
-    const plan = this.adapter.planSpawn({ prompt, resume });
+    const plan = adapter.planSpawn({ prompt, resume });
 
     const pty = spawn(plan.bin, plan.args, {
       name: 'xterm-256color',
@@ -333,8 +406,11 @@ export class SessionManager {
       state: 'running',
       unread: false,
       lastMsg: initialMsg,
-      ...(typeof resume === 'string' ? { claudeId: resume } : {}),
-      ...(group === undefined ? {} : { group }),
+      ...(typeof resume === 'string' ? { agentSessionID: resume } : {}),
+      agent,
+      pinned: false,
+      lastAttachedAt: Date.now(),
+      repoRoot: resolveRepoRoot(cwd),
       namedBy,
       createdAt: Date.now(),
     };
@@ -375,30 +451,46 @@ export class SessionManager {
       unread: s.unread,
       lastMsg: s.lastMsg,
       ...(s.lastDetail === undefined ? {} : { lastDetail: s.lastDetail }),
-      ...(s.claudeId === undefined ? {} : { claudeId: s.claudeId }),
-      ...(s.group === undefined ? {} : { group: s.group }),
+      ...(s.agentSessionID === undefined ? {} : { agentSessionID: s.agentSessionID }),
+      agent: s.agent,
+      pinned: s.pinned,
+      lastAttachedAt: s.lastAttachedAt,
+      repoRoot: s.repoRoot,
       namedBy: s.namedBy,
       createdAt: s.createdAt,
       kind: s.kind,
-      alive: s.pty !== null || (s.kind === 'jsonl' && s.state !== 'exited'),
+      alive: s.pty !== null || (s.kind === 'headless' && s.state !== 'exited'),
     }));
   }
 
-  applyHook(e: HookEvent) {
+  // Returns the normalized event kind so the caller can key lifecycle
+  // bookkeeping on it, or null when no session or adapter matches.
+  applyHook(e: HookEvent): AdapterEvent['kind'] | null {
     const s = this.sessions.find((x) => x.id === e.atcId);
 
+    if (!s) {
+      return null;
+    }
+
+    const adapter = this.findAdapter(s.agent);
+
+    if (adapter === null) {
+      return null;
+    }
+
+    const ev = adapter.normalizeHook(e);
+
     // Reporters belong to the terminal process; once a session is headless,
     // late reports from the dying terminal must not clobber its state.
-    if (!s || s.kind === 'jsonl') {
-      return;
+    if (s.kind === 'headless') {
+      return ev.kind;
     }
 
-    const ev = this.adapter.normalizeHook(e);
     const focused = this.focusedId === s.id;
     let dirty = false;
 
-    if (ev.agentSessionID !== undefined && s.claudeId !== ev.agentSessionID) {
-      s.claudeId = ev.agentSessionID;
+    if (ev.agentSessionID !== undefined && s.agentSessionID !== ev.agentSessionID) {
+      s.agentSessionID = ev.agentSessionID;
 
       this.writeFleet();
 
@@ -409,8 +501,11 @@ export class SessionManager {
       s.lastDetail = ev.detail;
     }
 
+    if (ev.transcriptSource !== undefined) {
+      s.transcriptSource = ev.transcriptSource;
+    }
+
     if (ev.nameSource !== undefined) {
-      s.transcriptSource = ev.nameSource;
       void this.refreshName(s, ev.nameSource);
     }
 
@@ -469,10 +564,18 @@ export class SessionManager {
       this.onEvent('state', s);
       this.emitChange();
     }
+
+    return ev.kind;
   }
 
   private async refreshName(s: Session, source: string) {
-    const update = await this.adapter.loadName(source, s.namedBy);
+    const adapter = this.findAdapter(s.agent);
+
+    if (adapter === null) {
+      return;
+    }
+
+    const update = await adapter.loadName(source, s.namedBy);
 
     if (update === null || update.name === '' || update.name === s.name) {
       return;
@@ -497,7 +600,7 @@ export class SessionManager {
       return null;
     }
 
-    return this.adapter.buildResumeCommand(s.cwd, s.claudeId);
+    return this.findAdapter(s.agent)?.buildResumeCommand(s.cwd, s.agentSessionID) ?? null;
   }
 
   attach(id: string) {
@@ -508,6 +611,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.
@@ -590,14 +696,16 @@ export class SessionManager {
     const fleet: FleetEntry[] = [];
 
     for (const s of this.sessions) {
-      const live = s.pty !== null || (s.kind === 'jsonl' && s.state !== 'exited');
+      const live = s.pty !== null || (s.kind === 'headless' && s.state !== 'exited');
 
-      if (live && s.claudeId !== undefined) {
+      if (live && s.agentSessionID !== undefined) {
         fleet.push({
           name: s.name,
           cwd: s.cwd,
-          claudeId: s.claudeId,
-          ...(s.group === undefined ? {} : { group: s.group }),
+          agentSessionID: s.agentSessionID,
+          agent: s.agent,
+          ...(s.pinned ? { pinned: true } : {}),
+          lastAttachedAt: s.lastAttachedAt,
         });
       }
     }
@@ -626,10 +734,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 +752,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

@@ -1,7 +1,9 @@
 import { Database } from 'bun:sqlite';
 import { existsSync, readFileSync } from 'node:fs';
+import { toAgentKind } from './agent-adapter';
+import type { AgentKind } from './agent-adapter';
 import type { HookEvent } from './hooks';
-import { isRecord } from './report';
+import { parseFleetEntry } from './sessions';
 import type { FleetEntry } from './sessions';
 
 /**
@@ -21,10 +23,12 @@ export class StateStore {
 
     this.db.run(`
       CREATE TABLE IF NOT EXISTS fleet (
-        claude_id TEXT PRIMARY KEY,
+        agent_session_id TEXT PRIMARY KEY,
         name TEXT NOT NULL,
         cwd TEXT NOT NULL,
-        grp TEXT
+        pinned INTEGER NOT NULL DEFAULT 0,
+        last_attached INTEGER,
+        agent TEXT NOT NULL DEFAULT 'claude'
       );
       CREATE TABLE IF NOT EXISTS events (
         id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -38,17 +42,37 @@ export class StateStore {
         cwd TEXT PRIMARY KEY,
         last_spawn INTEGER NOT NULL
       );
+      CREATE TABLE IF NOT EXISTS prefs (
+        key TEXT PRIMARY KEY,
+        value TEXT NOT NULL
+      );
     `);
 
-    // 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, attach recency, or agent kind 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),
+    );
+
+    // Stores created before the id column was agent-neutral carry it under
+    // its Claude-era name.
+    if (fleetColumns.has('claude_id')) {
+      this.db.run('ALTER TABLE fleet RENAME COLUMN claude_id TO agent_session_id');
+    }
+
+    if (!fleetColumns.has('pinned')) {
+      this.db.run('ALTER TABLE fleet ADD COLUMN pinned INTEGER NOT NULL DEFAULT 0');
+    }
+
+    if (!fleetColumns.has('last_attached')) {
+      this.db.run('ALTER TABLE fleet ADD COLUMN last_attached INTEGER');
+    }
 
-    if (!fleetColumns.includes('grp')) {
-      this.db.run('ALTER TABLE fleet ADD COLUMN grp TEXT');
+    if (!fleetColumns.has('agent')) {
+      this.db.run("ALTER TABLE fleet ADD COLUMN agent TEXT NOT NULL DEFAULT 'claude'");
     }
 
     if (legacyFleetPath !== undefined) {
@@ -58,20 +82,30 @@ 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<
+        {
+          agent_session_id: string;
+          name: string;
+          cwd: string;
+          pinned: number;
+          last_attached: number | null;
+          agent: string | null;
+        },
+        []
+      >('SELECT agent_session_id, name, cwd, pinned, last_attached, agent 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({
+        agentSessionID: row.agent_session_id,
+        name: row.name,
+        cwd: row.cwd,
+        agent: toAgentKind(row.agent),
+        ...(row.pinned === 0 ? {} : { pinned: true }),
+        ...(row.last_attached === null ? {} : { lastAttachedAt: row.last_attached }),
+      });
     }
 
     return entries;
@@ -94,11 +128,20 @@ 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 (agent_session_id, name, cwd, pinned, last_attached, agent) VALUES (?1, ?2, ?3, ?4, ?5, ?6)',
       );
 
       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.agentSessionID,
+          entry.name,
+          entry.cwd,
+          pinned,
+          entry.lastAttachedAt ?? null,
+          entry.agent,
+        );
       }
     });
 
@@ -107,7 +150,7 @@ export class StateStore {
 
   recordEvent(e: HookEvent): void {
     const rawMessage = e.payload['message'];
-    const rawSessionID = e.payload['session_id'];
+    const rawSessionID = e.payload['session_id'] ?? e.payload['sessionId'];
     const message = typeof rawMessage === 'string' ? rawMessage : null;
     const sessionID = typeof rawSessionID === 'string' ? rawSessionID : null;
 
@@ -134,6 +177,22 @@ export class StateStore {
     return rows.map((row) => row.cwd);
   }
 
+  loadLastUsedAgent(): AgentKind {
+    const row = this.db
+      .query<{ value: string }, []>("SELECT value FROM prefs WHERE key = 'last_used_agent'")
+      .get();
+
+    return toAgentKind(row?.value);
+  }
+
+  writeLastUsedAgent(agent: AgentKind): void {
+    this.db
+      .query(
+        'INSERT INTO prefs (key, value) VALUES (?1, ?2) ON CONFLICT(key) DO UPDATE SET value = ?2',
+      )
+      .run('last_used_agent', agent);
+  }
+
   stop(): void {
     this.db.close();
   }
@@ -152,13 +211,15 @@ export class StateStore {
         return;
       }
 
-      const entries = parsed.filter(
-        (entry): entry is FleetEntry =>
-          isRecord(entry) &&
-          typeof entry['name'] === 'string' &&
-          typeof entry['cwd'] === 'string' &&
-          typeof entry['claudeId'] === 'string',
-      );
+      const entries: FleetEntry[] = [];
+
+      for (const entry of parsed) {
+        const parsedEntry = parseFleetEntry(entry);
+
+        if (parsedEntry !== undefined) {
+          entries.push(parsedEntry);
+        }
+      }
 
       this.writeFleet(entries);
     } catch {}