@zgeoff/atc 0.1.6 → 0.1.8

package/README.md

@@ -43,7 +43,7 @@ fine nested inside zellij/tmux (give the pane locked mode so Ctrl-Space reaches
 | `R`             | home           | restore last fleet after a daemon death — respawns every session via `claude --resume <id>`    |
 | `j`/`k`/`↑`/`↓` | overlay/picker | move                                                                                           |
 | `Enter`         | overlay        | attach (auto-acks)                                                                             |
-| `Tab`           | overlay        | attach the most urgent needs-you session                                                       |
+| `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                                                             |
 | `H`             | overlay        | eject to headless: the terminal dies, a headless Agent SDK run resumes the same session        |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/atc",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "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/index.ts

@@ -1,7 +1,9 @@
 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';
 import type { EventMsg } from './protocol';
 import { isRecord } from './report';
 import { countSessionStates, sortGroupedSessionViews, sortSessionViews } from './sessions';
@@ -39,6 +41,12 @@ let confirmKill = false;
 
 // The client's mirror of the daemon's fleet, kept fresh by events.
 let fleet: MirrorSession[] = [];
+
+// When each session last flipped to done, so the Tab jump can prefer the
+// most recently finished turn. Sessions already done before this client
+// connected have no entry and rank last.
+const doneAt = new Map<string, number>();
+
 let focusedID: string | null = null;
 let fleetCount = 0;
 
@@ -186,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();
   }
 }
@@ -233,7 +241,7 @@ function openOverlay() {
 
   overlaySelected = Math.max(0, focusedIndex);
 
-  stdout.write(ansi.clear);
+  stdout.write(ansi.resetInputModes + ansi.clear);
 
   renderOverlay();
 }
@@ -368,7 +376,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);
@@ -471,6 +479,10 @@ function applyDaemonEvent(e: EventMsg) {
       if (s !== undefined) {
         const next = SESSION_STATES.find((x) => x === e['state']);
 
+        if (next === 'done' && s.state !== 'done') {
+          doneAt.set(s.id, Date.now());
+        }
+
         if (next !== undefined) {
           s.state = next;
         }
@@ -524,6 +536,10 @@ function applyDaemonEvent(e: EventMsg) {
     case 'session.removed': {
       fleet = fleet.filter((x) => x.id !== e['s']);
 
+      if (typeof e['s'] === 'string') {
+        doneAt.delete(e['s']);
+      }
+
       if (focusedID === e['s']) {
         focusedID = null;
       }
@@ -557,6 +573,7 @@ function copyToClipboard(text: string) {
 // ---- input ----
 
 const leader = loadConfig().leader;
+const leaderChords = buildLeaderChords(leader.code);
 
 const KEY = {
   tab: 0x09,
@@ -575,6 +592,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;
@@ -612,7 +635,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;
   }
 
@@ -670,7 +693,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;
@@ -695,10 +718,10 @@ function applyOverlayKey(buf: Buffer) {
   const ch = buf.toString();
 
   if (buf[0] === KEY.tab) {
-    const needy = sortSessionViews(fleet).find((s) => s.state === 'needs_you' && s.alive);
+    const target = pickTabTarget(fleet, (id) => doneAt.get(id));
 
-    if (needy !== undefined) {
-      void attach(needy.id);
+    if (target !== undefined) {
+      void attach(target.id);
     }
 
     return;
@@ -828,7 +851,7 @@ function applyTextKey(buf: Buffer, onSubmit: () => void, onCancel: () => void) {
     return;
   }
 
-  if (buf[0] === leader.code) {
+  if (isLeaderKey(buf)) {
     toBase();
 
     return;
@@ -970,7 +993,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;
@@ -986,7 +1009,7 @@ process.stdin.on('data', (buf: Buffer) => {
       return;
     }
     case 'home': {
-      if (buf[0] === leader.code) {
+      if (isLeaderKey(buf)) {
         openOverlay();
 
         return;
@@ -1173,7 +1196,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/pick-tab-target.ts

@@ -0,0 +1,31 @@
+import type { SessionState } from './sessions';
+import { sortSessionViews } from './sessions';
+
+interface TabCandidate {
+  readonly id: string;
+  readonly state: SessionState;
+  readonly createdAt: number;
+  readonly alive: boolean;
+  readonly kind: 'pty' | 'jsonl';
+}
+
+/**
+ * The Tab jump target: the most urgent alive needs-you session, else the
+ * alive terminal session whose turn finished most recently. Headless
+ * sessions never qualify for the fallback — they have no terminal to
+ * attach — and sessions with no recorded finish time rank last.
+ */
+export function pickTabTarget<T extends TabCandidate>(
+  list: readonly T[],
+  findDoneAt: (id: string) => number | undefined,
+): T | undefined {
+  const needy = sortSessionViews(list).find((s) => s.state === 'needs_you' && s.alive);
+
+  if (needy !== undefined) {
+    return needy;
+  }
+
+  return sortSessionViews(list)
+    .filter((s) => s.state === 'done' && s.alive && s.kind === 'pty')
+    .toSorted((a, b) => (findDoneAt(b.id) ?? 0) - (findDoneAt(a.id) ?? 0))[0];
+}

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/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/ui.ts

@@ -1,4 +1,5 @@
 import { formatDir } from './dirs';
+import { RESET_INPUT_MODES } from './reset-input-modes';
 import type { SessionState } from './sessions';
 
 // The slice of a session the drawing layer needs; satisfied by both the
@@ -15,6 +16,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`,
@@ -274,7 +276,7 @@ export function drawHelp() {
 
   const lines = [
     '⏎  attach the selected session',
-    '⇥  attach the most urgent needs-you session',
+    '⇥  attach the most urgent needs-you, else latest done',
     'a  ack its notification without attaching',
     'H  eject to a headless run',
     'P  revive a dead or headless session',