@gaia-ai/addon-gaia-ui 0.6.1

package/dist/src/Kernel/tui-kernel.js

@@ -0,0 +1,983 @@
+import { writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { agentListRows } from '../Component/agent-list/index.js';
+import { createFormLines } from '../Component/create-form/index.js';
+import { dashboardRows } from '../Component/dashboard-list/index.js';
+import { runTableRows } from '../Component/run-table/index.js';
+import { DETAIL_TABS, tabBar } from '../Component/tab-bar/index.js';
+import { tabViewLines } from '../Component/ticket-detail/index.js';
+import { ticketTableRows } from '../Component/ticket-table/index.js';
+import { topTabBar } from '../Component/top-tabs/index.js';
+import { ANSI, fitLine, styleVisibleLines } from '../lib/ansi.js';
+import { scrollTo } from '../lib/scroll.js';
+import { cycleValue, describeCriteria, hasActiveCriteria, STATE_FILTER_VALUES, TYPE_FILTER_VALUES, } from '../lib/ticket-query.js';
+import { buildCreateLaunch } from '../Service/agent.js';
+import { activeField, backspace, cycle, initialForm, moveField, moveLabelCursor, newline, serialize, shortName, toggleLabel, typeChar, } from '../Service/create-form.js';
+import { loadCreateFormOptions } from '../Service/create-form-data.js';
+import { loadFilteredTickets, loadProjectWithTickets, } from '../Service/project-data.js';
+import { loadDashboardProjects, } from '../Service/projects.js';
+import { loadProjectRuns, selectedRunTicketId } from '../Service/run-data.js';
+import { loadTicketDetail } from '../Service/ticket-data.js';
+const nowSeconds = () => Math.floor(Date.now() / 1000);
+// The three read-only screens each project a `document`/state into plain string
+// rows; a Herdr-backed create agent is layered on top as a full-terminal
+// passthrough (no node-pty / @xterm — the core renders raw ANSI to the real TTY).
+export function runTicketTui(_document, _context, services, options = {}) {
+    const output = process.stdout;
+    const input = process.stdin;
+    const agents = services?.agents ?? options?.agents ?? null;
+    const defaultProject = options?.project ?? services?.project ?? null;
+    const workingDir = options.cwd ?? process.cwd();
+    const currentUser = services?.currentUser ?? options?.currentUser;
+    const ownConductorMachineId = services?.ownConductorMachineId ?? options?.ownConductorMachineId;
+    const createPrompt = services?.createPrompt ?? options?.createPrompt;
+    // Non-TTY: emit the dashboard once so `gaia ui </dev/null` stays scriptable.
+    if (!input.isTTY || !output.isTTY) {
+        return loadDashboardProjects({ client: services.client, nowSeconds })
+            .catch(() => [])
+            .then((rows) => {
+            output.write(`${dashboardRows(rows).join('\n')}\n`);
+        });
+    }
+    let screen = 'dashboard';
+    let projects = [];
+    let selectedProject = 0;
+    let currentProjectSlug = null;
+    let currentProjectName = null;
+    let ticketRows = [];
+    let selectedTicket = 0;
+    let currentProjectId = null;
+    let criteria = { query: '', state: null, type: null };
+    let searchMode = false;
+    let searchTimer = null;
+    let detail = null;
+    let activeTab = 0;
+    let selectedComment = 0;
+    let expandedComments = new Set();
+    let offset = 0;
+    let loading = false;
+    let error = '';
+    let status = '';
+    // The current group's live agents (Ticket-Agents screen), refreshed from
+    // `agents.list(project)`; the host owns identity + layout.
+    let agentRows = [];
+    let selectedAgent = 0;
+    let runRows = [];
+    let selectedRun = 0;
+    let closing = false;
+    let createSeq = 0;
+    let lastCreateAtMs = 0;
+    // "New ticket" popup form state (null = not open).
+    let createForm = null;
+    let createFormOpts = null;
+    let formProject = '';
+    const history = [];
+    const previousRawMode = input.isRaw;
+    const viewHeight = () => Math.max(3, output.rows - 9);
+    const isCommentsTab = () => DETAIL_TABS[activeTab]?.id === 'comments';
+    // The lines rendered for the current screen plus `selRow` (the absolute row to
+    // highlight, -1 for none), `selectable` (how many selectable entries), and,
+    // for the Comments tab, `headerRows` mapping each comment to its header row.
+    const screenView = () => {
+        if (screen === 'dashboard') {
+            return {
+                lines: dashboardRows(projects),
+                selectable: projects.length,
+                selRow: projects.length ? selectedProject : -1,
+            };
+        }
+        if (screen === 'project') {
+            return {
+                lines: ticketTableRows(ticketRows, {
+                    emptyMessage: hasActiveCriteria(criteria)
+                        ? 'No tasks match the current search/filters.'
+                        : undefined,
+                }),
+                selectable: ticketRows.length,
+                selRow: ticketRows.length ? 1 + selectedTicket : -1,
+            };
+        }
+        if (screen === 'ticket-agents') {
+            return {
+                lines: agentListRows(agentRows),
+                selectable: agentRows.length,
+                selRow: agentRows.length ? 1 + selectedAgent : -1,
+            };
+        }
+        if (screen === 'project-runs') {
+            return {
+                lines: runTableRows(runRows, nowSeconds()),
+                selectable: runRows.length,
+                selRow: runRows.length ? 1 + selectedRun : -1,
+            };
+        }
+        const view = tabViewLines(detail ?? {}, activeTab, {
+            expanded: expandedComments,
+            nowSeconds: nowSeconds(),
+        });
+        const selRow = isCommentsTab() && view.selectable
+            ? (view.headerRows[Math.min(selectedComment, view.selectable - 1)] ??
+                -1)
+            : -1;
+        return {
+            lines: view.lines,
+            boldRows: view.boldRows,
+            headerRows: view.headerRows,
+            selectable: view.selectable,
+            selRow,
+        };
+    };
+    // The selected entry on the list screens (dashboard/project). The ticket
+    // screen highlights via screenView().selRow (comment header rows); its tab
+    // key-switching is handled by the `screen === 'ticket'` branch of handleKey.
+    const selectedIndex = () => screen === 'dashboard'
+        ? selectedProject
+        : screen === 'ticket-agents'
+            ? selectedAgent
+            : screen === 'project-runs'
+                ? selectedRun
+                : selectedTicket;
+    // The "New ticket" popup: a centered floating box drawn ON TOP of the current
+    // screen (a real modal overlay, not a full-screen replace) via absolute cursor
+    // positioning, so the dashboard/ticket list stays visible around it.
+    const drawPopupOverlay = () => {
+        if (!createForm || !createFormOpts)
+            return;
+        const cols = Math.max(40, output.columns);
+        const rows = Math.max(10, output.rows);
+        const body = [
+            `⚡ New ticket · ${formProject}`,
+            '',
+            ...createFormLines(createForm, createFormOpts),
+            '',
+            '↑↓ field · ←→ change · Space toggle · Ctrl+S create · Esc cancel',
+        ];
+        const innerW = Math.min(60, cols - 8);
+        const boxW = innerW + 4; // '│ ' + content + ' │'
+        const boxH = body.length + 2; // + top/bottom border
+        const startRow = Math.max(2, Math.floor((rows - boxH) / 2));
+        const startCol = Math.max(1, Math.floor((cols - boxW) / 2) + 1);
+        const at = (r) => `\x1b[${r};${startCol}H`;
+        let r = startRow;
+        output.write(`${at(r++)}${ANSI.brightCyan}${ANSI.bold}╭${'─'.repeat(boxW - 2)}╮${ANSI.reset}`);
+        for (const line of body) {
+            output.write(`${at(r++)}${ANSI.brightCyan}│${ANSI.reset} ${fitLine(line, innerW)} ${ANSI.brightCyan}│${ANSI.reset}`);
+        }
+        output.write(`${at(r++)}${ANSI.brightCyan}╰${'─'.repeat(boxW - 2)}╯${ANSI.reset}`);
+    };
+    const renderScreen = () => {
+        const width = Math.max(40, output.columns);
+        const contentWidth = Math.max(20, width - 4);
+        const height = viewHeight();
+        const { lines, boldRows, selRow } = screenView();
+        const maxOffset = Math.max(0, lines.length - height);
+        offset = Math.min(Math.max(0, offset), maxOffset);
+        const visible = styleVisibleLines({
+            lines,
+            boldRows,
+            selRow,
+            offset,
+            height,
+            contentWidth,
+        });
+        const detailAttr = (key) => {
+            const v = detail?.data?.attributes?.[key];
+            return typeof v === 'string' ? v : undefined;
+        };
+        const title = screen === 'dashboard'
+            ? 'GAIA projects'
+            : screen === 'project'
+                ? `${currentProjectName ?? currentProjectSlug} · tickets`
+                : screen === 'ticket-agents'
+                    ? 'Ticket-Agents'
+                    : screen === 'project-runs'
+                        ? `${currentProjectName ?? currentProjectSlug} · runs`
+                        : `${detailAttr('identifier') ?? ''} · ${detailAttr('title') ?? 'ticket'}`;
+        const meta = screen === 'dashboard'
+            ? `${projects.length} registered project(s)  ·  ${services?.baseUrl ?? ''}`
+            : screen === 'project'
+                ? searchMode
+                    ? `search: ${criteria.query}▌`
+                    : `${ticketRows.length} ticket(s)${hasActiveCriteria(criteria) ? `  ·  ${describeCriteria(criteria)}` : ''}  ·  n new · a agents · u runs · / search · s status · t type · c clear`
+                : screen === 'ticket-agents'
+                    ? `${agentRows.length} agent(s)  ·  Enter switch · z overview · r retry · x close · Esc back`
+                    : screen === 'project-runs'
+                        ? `${runRows.length} run(s)  ·  Enter ticket · Tab cycle · Esc back`
+                        : tabBar(activeTab);
+        const keys = screen === 'ticket'
+            ? isCommentsTab()
+                ? ' Tab tab · ↑↓ select · Enter/Space expand · Esc back · q quit '
+                : ' Tab tab · ↑↓ scroll · Esc back · q quit '
+            : screen === 'ticket-agents'
+                ? ' ↑↓ select · Enter switch · z overview · r retry · x close · Tab/t tickets · q quit '
+                : screen === 'project-runs'
+                    ? ' ↑↓ select · Enter ticket · Tab cycle · Esc back · q quit '
+                    : ' ↑↓ select · Enter open · n new · Tab/a agents · u runs · Esc back · q quit ';
+        const bar = loading
+            ? ' Loading… '
+            : error
+                ? ` Error: ${error} `
+                : status
+                    ? ` ${status} `
+                    : keys;
+        output.write('\x1b[H\x1b[2J');
+        output.write(`${ANSI.brightCyan}${ANSI.bold}╭─ ⚡ GAIA ${'─'.repeat(Math.max(1, width - 11))}╮${ANSI.reset}\n`);
+        output.write(`${ANSI.cyan}│${ANSI.reset} ${ANSI.bold}${fitLine(title, width - 4)}${ANSI.cyan} │${ANSI.reset}\n`);
+        output.write(`${ANSI.cyan}│${ANSI.reset} ${fitLine(meta, width - 4)}${ANSI.cyan} │${ANSI.reset}\n`);
+        output.write(`${ANSI.brightCyan}╰${'─'.repeat(Math.max(1, width - 2))}╯${ANSI.reset}\n`);
+        const topActive = screen === 'ticket-agents'
+            ? 'ticket-agents'
+            : screen === 'project-runs'
+                ? 'runs'
+                : 'tickets';
+        output.write(`${ANSI.bold}${fitLine(` ${topTabBar(topActive)}`, width)}${ANSI.reset}\n\n`);
+        output.write(`${visible.join('\n')}\n`);
+        output.write(`${ANSI.inverse}${fitLine(bar, width)}${ANSI.reset}`);
+    };
+    // Compose the frame: the normal screen, then (if open) the popup on top.
+    const draw = () => {
+        renderScreen();
+        if (createForm && createFormOpts)
+            drawPopupOverlay();
+    };
+    const remember = () => ({
+        screen,
+        projects,
+        selectedProject,
+        currentProjectSlug,
+        currentProjectName,
+        ticketRows,
+        selectedTicket,
+        detail,
+        offset,
+        selectedAgent,
+        runRows,
+        selectedRun,
+    });
+    const restore = (s) => {
+        screen = s.screen;
+        projects = s.projects;
+        selectedProject = s.selectedProject;
+        currentProjectSlug = s.currentProjectSlug;
+        currentProjectName = s.currentProjectName;
+        ticketRows = s.ticketRows;
+        selectedTicket = s.selectedTicket;
+        detail = s.detail;
+        offset = s.offset;
+        selectedAgent = s.selectedAgent;
+        runRows = s.runRows;
+        selectedRun = s.selectedRun;
+        error = '';
+        status = '';
+    };
+    const openDashboard = async () => {
+        loading = true;
+        error = '';
+        status = '';
+        draw();
+        try {
+            projects = await loadDashboardProjects({
+                client: services.client,
+                nowSeconds,
+            });
+            selectedProject = 0;
+            offset = 0;
+            screen = 'dashboard';
+        }
+        catch (caught) {
+            error = caught instanceof Error ? caught.message : String(caught);
+        }
+        finally {
+            loading = false;
+            draw();
+        }
+    };
+    const openSelectedProject = async () => {
+        const p = projects[selectedProject];
+        if (!p || loading)
+            return;
+        history.push(remember());
+        loading = true;
+        error = '';
+        status = '';
+        draw();
+        try {
+            const out = await loadProjectWithTickets(services.client, p.project);
+            currentProjectSlug = p.project;
+            currentProjectName = out.project.name;
+            currentProjectId = out.project.id;
+            criteria = { query: '', state: null, type: null };
+            searchMode = false;
+            ticketRows = out.tickets;
+            selectedTicket = 0;
+            offset = 0;
+            screen = 'project';
+        }
+        catch (caught) {
+            history.pop();
+            error = caught instanceof Error ? caught.message : String(caught);
+        }
+        finally {
+            loading = false;
+            draw();
+        }
+    };
+    const applyCriteria = async () => {
+        if (currentProjectId == null || loading)
+            return;
+        loading = true;
+        error = '';
+        status = '';
+        draw();
+        try {
+            ticketRows = await loadFilteredTickets(services.client, currentProjectId, criteria);
+            selectedTicket = Math.max(0, Math.min(selectedTicket, ticketRows.length - 1));
+            offset = 0;
+        }
+        catch (caught) {
+            error = caught instanceof Error ? caught.message : String(caught);
+        }
+        finally {
+            loading = false;
+            draw();
+        }
+    };
+    const scheduleSearch = () => {
+        if (searchTimer)
+            clearTimeout(searchTimer);
+        searchTimer = setTimeout(() => {
+            searchTimer = null;
+            void applyCriteria();
+        }, 200);
+    };
+    const openSelectedDetail = async () => {
+        const t = ticketRows[selectedTicket];
+        if (!t?.id || loading)
+            return;
+        history.push(remember());
+        loading = true;
+        error = '';
+        status = '';
+        draw();
+        try {
+            detail = await loadTicketDetail(services.client, t.id);
+            screen = 'ticket';
+            activeTab = 0;
+            expandedComments = new Set();
+            selectedComment = 0;
+            offset = 0;
+        }
+        catch (caught) {
+            history.pop();
+            error = caught instanceof Error ? caught.message : String(caught);
+        }
+        finally {
+            loading = false;
+            draw();
+        }
+    };
+    // Open the project-scoped run overview (GAIA-192). Canonical async-screen
+    // pattern: remember the current frame, show loading, load the runs, swap to
+    // the screen on success or pop the frame + surface the error on failure.
+    const openRunsScreen = async () => {
+        if (currentProjectId == null) {
+            status = 'open a project first to see its runs';
+            draw();
+            return;
+        }
+        if (loading)
+            return;
+        history.push(remember());
+        loading = true;
+        error = '';
+        status = '';
+        draw();
+        try {
+            runRows = await loadProjectRuns(services.client, currentProjectId);
+            selectedRun = 0;
+            offset = 0;
+            screen = 'project-runs';
+        }
+        catch (caught) {
+            history.pop();
+            error = caught instanceof Error ? caught.message : String(caught);
+        }
+        finally {
+            loading = false;
+            draw();
+        }
+    };
+    // Enter on a run row → open its ticket detail on the Runs sub-tab (AC-3). A
+    // ticket-less run is a no-op; a history frame is pushed so Esc returns here.
+    const openSelectedRunTicket = async () => {
+        const ticketId = selectedRunTicketId(runRows, selectedRun);
+        if (!ticketId || loading)
+            return;
+        history.push(remember());
+        loading = true;
+        error = '';
+        status = '';
+        draw();
+        try {
+            detail = await loadTicketDetail(services.client, ticketId);
+            screen = 'ticket';
+            activeTab = Math.max(0, DETAIL_TABS.findIndex((t) => t.id === 'runs'));
+            expandedComments = new Set();
+            selectedComment = 0;
+            offset = 0;
+        }
+        catch (caught) {
+            history.pop();
+            error = caught instanceof Error ? caught.message : String(caught);
+        }
+        finally {
+            loading = false;
+            draw();
+        }
+    };
+    return new Promise((resolve) => {
+        const handleResize = () => {
+            draw();
+        };
+        const finish = () => {
+            closing = true;
+            if (searchTimer)
+                clearTimeout(searchTimer);
+            input.off('data', onData);
+            output.off('resize', handleResize);
+            // Agents keep running in their durable herdr tabs (AC-5 restart) — quitting
+            // the TUI just tears down the renderer, never the agents.
+            input.setRawMode(previousRawMode ?? false);
+            input.pause();
+            output.write('\x1b[?25h\x1b[2J\x1b[H');
+            resolve();
+        };
+        // Launch a ticket-create agent for a project via the injected agent host
+        // (herdr owns transport + layout), then show the Ticket-Agents screen. The
+        // returned handle is appended optimistically; `list` reconciles on refresh.
+        const launchCreateFor = async (project, spec) => {
+            if (!agents) {
+                status = 'create agent unavailable — no agent host injected';
+                draw();
+                return;
+            }
+            // Multiple concurrent agents per project are allowed; only guard against a
+            // rapid accidental double-submit (debounce).
+            const nowMs = Date.now();
+            if (nowMs - lastCreateAtMs < 400) {
+                draw();
+                return;
+            }
+            lastCreateAtMs = nowMs;
+            createSeq += 1;
+            try {
+                const agent = await agents.launch(buildCreateLaunch({
+                    project,
+                    cwd: workingDir,
+                    specPath: spec?.specPath,
+                    workflow: spec?.workflow,
+                    createPrompt,
+                    label: spec?.shortName ?? `New ${spec?.workflow ?? 'ticket'}`,
+                }));
+                history.push(remember());
+                if (project === currentProjectSlug &&
+                    !agentRows.some((a) => a.id === agent.id)) {
+                    agentRows = [...agentRows, agent];
+                }
+                screen = 'ticket-agents';
+                selectedAgent = Math.max(0, agentRows.length - 1);
+                offset = 0;
+                status = `ticket agent running for ${project}`;
+                draw();
+            }
+            catch (caught) {
+                const message = caught instanceof Error ? caught.message : String(caught);
+                status = `failed to start ticket agent: ${message}`;
+                draw();
+            }
+        };
+        // `n` opens the "New ticket" popup: load the select options, then show the
+        // form. On submit the collected fields go to the create agent via a temp
+        // spec file (never on the command line — PTY-4096).
+        const openCreateAgent = async () => {
+            if (createForm)
+                return; // already open — ignore repeat presses
+            if (!agents) {
+                status = 'create agent unavailable — no agent host injected';
+                draw();
+                return;
+            }
+            formProject = currentProjectSlug ?? defaultProject ?? 'gaia';
+            status = 'loading new-ticket form…';
+            draw();
+            const options = await loadCreateFormOptions(services.client, {
+                currentUser,
+                ownConductorMachineId,
+            }).catch(() => ({
+                users: [],
+                conductors: [],
+                labels: [],
+                workflows: [],
+            }));
+            createFormOpts = options;
+            createForm = initialForm(options);
+            status = '';
+            draw();
+        };
+        const closeCreateForm = () => {
+            createForm = null;
+            createFormOpts = null;
+            draw();
+        };
+        const submitCreateForm = () => {
+            if (!createForm || !createFormOpts)
+                return;
+            const payload = serialize(createForm, createFormOpts);
+            const project = formProject;
+            let specPath;
+            try {
+                specPath = join(tmpdir(), `gaia-new-ticket-${nowSeconds()}-${++createSeq}.json`);
+                writeFileSync(specPath, JSON.stringify({ project, is_new: true, ...payload }, null, 2), 'utf8');
+            }
+            catch {
+                specPath = undefined; // fall back to a plain create agent
+            }
+            createForm = null;
+            createFormOpts = null;
+            void launchCreateFor(project, {
+                specPath,
+                workflow: payload.workflow?.id,
+                shortName: shortName(payload),
+            });
+        };
+        // Route a key into the open form. ↑↓/Tab move fields; ←→ change a select or
+        // move the label cursor; Space toggles a label; printable keys edit the
+        // description; Ctrl+S submits; Esc cancels.
+        const handleFormKey = (key) => {
+            if (!createForm || !createFormOpts)
+                return;
+            const opts = createFormOpts;
+            if (key === '\x1b') {
+                closeCreateForm();
+                return;
+            }
+            if (key === '\x13') {
+                submitCreateForm(); // Ctrl+S
+                return;
+            }
+            if (key === '\x1b[A') {
+                createForm = moveField(createForm, -1);
+                draw();
+                return;
+            }
+            if (key === '\x1b[B' || key === '\t') {
+                createForm = moveField(createForm, 1);
+                draw();
+                return;
+            }
+            const field = activeField(createForm);
+            if (field.kind === 'text') {
+                if (key === '\r' || key === '\n')
+                    createForm = newline(createForm);
+                else if (key === '\x7f')
+                    createForm = backspace(createForm);
+                else if (!key.startsWith('\x1b') && key >= ' ')
+                    createForm = typeChar(createForm, key);
+                else
+                    return;
+                draw();
+                return;
+            }
+            if (field.kind === 'select') {
+                if (key === '\x1b[C')
+                    createForm = cycle(createForm, opts, 1);
+                else if (key === '\x1b[D')
+                    createForm = cycle(createForm, opts, -1);
+                else if (key === '\r' || key === '\n')
+                    createForm = moveField(createForm, 1);
+                else
+                    return;
+                draw();
+                return;
+            }
+            if (field.kind === 'multiselect') {
+                if (key === '\x1b[C')
+                    createForm = moveLabelCursor(createForm, opts, 1);
+                else if (key === '\x1b[D')
+                    createForm = moveLabelCursor(createForm, opts, -1);
+                else if (key === ' ')
+                    createForm = toggleLabel(createForm, opts);
+                else if (key === '\r' || key === '\n')
+                    createForm = moveField(createForm, 1);
+                else
+                    return;
+                draw();
+                return;
+            }
+            // action field (submit)
+            if (key === '\r' || key === '\n')
+                submitCreateForm();
+        };
+        // Switch to an agent: the host brings it to the foreground (herdr zooms).
+        const reopenAgent = (a) => {
+            if (!agents)
+                return;
+            void agents.focus(a.id).catch(() => { });
+            status = `switched to ${a.group} agent`;
+            draw();
+        };
+        // Overview / home: the host un-zooms the group + returns focus to the caller;
+        // every agent keeps running.
+        const hideAgents = () => {
+            if (agents && currentProjectSlug) {
+                void agents.hide(currentProjectSlug).catch(() => { });
+            }
+            status = 'agents tiled — focus back on the TUI';
+            draw();
+        };
+        // Retry: drop the row locally, then launch a fresh agent for the same group.
+        const retryAgent = (a) => {
+            agentRows = agentRows.filter((r) => r.id !== a.id);
+            selectedAgent = 0;
+            void launchCreateFor(a.group);
+        };
+        // Terminate an agent for good (host `kill`); drop it from the list.
+        const terminateAgent = (a) => {
+            if (agents)
+                void agents.kill(a.id).catch(() => { });
+            agentRows = agentRows.filter((r) => r.id !== a.id);
+            selectedAgent = 0;
+            draw();
+        };
+        // Reconcile the list with the host's live agents for the current project, so
+        // it is exactly the open agents — incl. across a TUI restart. No project
+        // (dashboard) → nothing to list.
+        const refreshAgents = async () => {
+            if (!agents || !currentProjectSlug)
+                return;
+            try {
+                agentRows = await agents.list(currentProjectSlug);
+                if (selectedAgent >= agentRows.length) {
+                    selectedAgent = Math.max(0, agentRows.length - 1);
+                }
+            }
+            catch {
+                // best-effort; a lister failure leaves the current list untouched
+            }
+        };
+        const openAgentsScreen = () => {
+            if (screen !== 'ticket-agents') {
+                history.push(remember());
+                screen = 'ticket-agents';
+                selectedAgent = 0;
+                offset = 0;
+            }
+            draw();
+            // Refresh from the live panes, then redraw if still on the screen.
+            void refreshAgents().then(() => {
+                if (screen === 'ticket-agents')
+                    draw();
+            });
+        };
+        // Top-tab: switch back to the Tickets tab, restoring the drill-down screen
+        // that was active before Ticket-Agents was opened.
+        const switchToTickets = () => {
+            if (screen !== 'ticket-agents')
+                return;
+            const previous = history.pop();
+            if (previous)
+                restore(previous);
+            else {
+                screen = 'dashboard';
+                selectedProject = 0;
+                offset = 0;
+            }
+            draw();
+        };
+        const currentTopTab = () => screen === 'ticket-agents'
+            ? 'ticket-agents'
+            : screen === 'project-runs'
+                ? 'runs'
+                : 'tickets';
+        // Switch to a sibling top tab. `ticket-agents`/`runs` are overlays pushed
+        // from the Tickets base, so leaving one first pops back to that base (Esc's
+        // frame) before opening the next — the history never stacks two overlays.
+        const gotoTopTab = (target) => {
+            if (currentTopTab() === target)
+                return;
+            if (currentTopTab() !== 'tickets') {
+                const previous = history.pop();
+                if (previous)
+                    restore(previous);
+                else {
+                    screen = 'dashboard';
+                    selectedProject = 0;
+                    offset = 0;
+                }
+            }
+            if (target === 'ticket-agents')
+                openAgentsScreen();
+            else if (target === 'runs')
+                void openRunsScreen();
+            else
+                draw();
+        };
+        // Tab / Shift-Tab cycle through the three project top tabs in order.
+        const cycleTopTab = (dir) => {
+            const order = ['tickets', 'ticket-agents', 'runs'];
+            const i = order.indexOf(currentTopTab());
+            const next = order[(i + dir + order.length) % order.length];
+            if (next)
+                gotoTopTab(next);
+        };
+        const handleKey = async (buffer) => {
+            const key = buffer.toString();
+            // The New-ticket popup owns all keys while open (so `q`/letters type into
+            // the description); Esc cancels, Ctrl+S submits.
+            if (createForm) {
+                handleFormKey(key);
+                return;
+            }
+            // Search-input mode (project screen): capture all keys as text.
+            if (searchMode) {
+                if (key === '\r' || key === '\n' || key === '\x1b') {
+                    searchMode = false; // Enter/Esc: leave typing, keep query
+                    draw();
+                    return;
+                }
+                if (key === '\x7f' || key === '\b') {
+                    criteria.query = criteria.query.slice(0, -1);
+                    scheduleSearch();
+                    draw();
+                    return;
+                }
+                if (key >= ' ' && key.length === 1) {
+                    criteria.query += key;
+                    scheduleSearch();
+                    draw();
+                    return;
+                }
+                return; // swallow other control keys while typing
+            }
+            if (key === '\x03' || key === 'q') {
+                finish();
+                return;
+            }
+            if (loading)
+                return;
+            // Esc / Backspace → back.
+            if (key === '\x1b' || key === '\x7f') {
+                const previous = history.pop();
+                if (previous)
+                    restore(previous);
+                draw();
+                return;
+            }
+            // Project screen: search entry + status/type cycle + reset.
+            if (screen === 'project') {
+                if (key === '/') {
+                    searchMode = true;
+                    draw();
+                    return;
+                }
+                if (key === 's') {
+                    criteria.state = cycleValue(STATE_FILTER_VALUES, criteria.state);
+                    void applyCriteria();
+                    return;
+                }
+                if (key === 't') {
+                    criteria.type = cycleValue(TYPE_FILTER_VALUES, criteria.type);
+                    void applyCriteria();
+                    return;
+                }
+                if (key === 'c') {
+                    criteria = { query: '', state: null, type: null };
+                    void applyCriteria();
+                    return;
+                }
+            }
+            if (key === 'n') {
+                openCreateAgent();
+                return;
+            }
+            // Top-tab navigation (global): a → Ticket-Agents, t → Tickets, u → Runs.
+            if (key === 'a') {
+                openAgentsScreen();
+                return;
+            }
+            if (key === 't' && screen === 'ticket-agents') {
+                switchToTickets();
+                return;
+            }
+            if (key === 'u' && screen !== 'ticket') {
+                void openRunsScreen();
+                return;
+            }
+            // Tab / Shift-Tab cycles the top-level tabs — except on the ticket screen,
+            // where Tab switches the ticket-detail tabs (handled in its own branch).
+            if ((key === '\t' || key === '\x1b[Z') && screen !== 'ticket') {
+                cycleTopTab(key === '\x1b[Z' ? -1 : 1);
+                return;
+            }
+            if (screen === 'ticket-agents') {
+                const sel = agentRows[selectedAgent];
+                if (key === '\r' || key === '\n') {
+                    if (sel)
+                        reopenAgent(sel);
+                    return;
+                }
+                if (key === 'h' || key === 'z') {
+                    hideAgents();
+                    return;
+                }
+                if (key === 'r') {
+                    if (sel)
+                        retryAgent(sel);
+                    return;
+                }
+                if (key === 'x') {
+                    if (sel)
+                        terminateAgent(sel);
+                    return;
+                }
+                // other keys (↑↓ selection) fall through to the generic list handler
+            }
+            if (screen === 'ticket') {
+                const tabCount = DETAIL_TABS.length;
+                if (key === '\t') {
+                    activeTab = (activeTab + 1) % tabCount;
+                    offset = 0;
+                    selectedComment = 0;
+                    draw();
+                    return;
+                }
+                if (key === '\x1b[Z') {
+                    activeTab = (activeTab - 1 + tabCount) % tabCount;
+                    offset = 0;
+                    selectedComment = 0;
+                    draw();
+                    return;
+                }
+                const view = screenView();
+                const height = viewHeight();
+                const maxOffset = Math.max(0, view.lines.length - height);
+                if (isCommentsTab() && view.selectable) {
+                    if (key === '\r' || key === '\n' || key === ' ') {
+                        if (expandedComments.has(selectedComment))
+                            expandedComments.delete(selectedComment);
+                        else
+                            expandedComments.add(selectedComment);
+                        draw();
+                        return;
+                    }
+                    const moveSel = (delta) => {
+                        selectedComment = Math.max(0, Math.min(selectedComment + delta, view.selectable - 1));
+                        offset = scrollTo(view.headerRows?.[selectedComment] ?? 0, offset, height);
+                    };
+                    if (key === 'j' || key === '\x1b[B')
+                        moveSel(1);
+                    if (key === 'k' || key === '\x1b[A')
+                        moveSel(-1);
+                    if (key === 'g')
+                        moveSel(-view.selectable);
+                    if (key === 'G')
+                        moveSel(view.selectable);
+                    draw();
+                    return;
+                }
+                if (key === 'j' || key === '\x1b[B')
+                    offset += 1;
+                if (key === 'k' || key === '\x1b[A')
+                    offset -= 1;
+                if (key === '\x1b[6~')
+                    offset += height;
+                if (key === '\x1b[5~')
+                    offset -= height;
+                if (key === 'g')
+                    offset = 0;
+                if (key === 'G')
+                    offset = maxOffset;
+                offset = Math.max(0, Math.min(offset, maxOffset));
+                draw();
+                return;
+            }
+            if (key === '\r' || key === '\n') {
+                if (screen === 'dashboard')
+                    await openSelectedProject();
+                else if (screen === 'project')
+                    await openSelectedDetail();
+                else if (screen === 'project-runs')
+                    await openSelectedRunTicket();
+                return;
+            }
+            const { selectable } = screenView();
+            const height = viewHeight();
+            // Empty list screen: nothing selectable, fall back to plain scroll.
+            if (selectable === 0) {
+                const { lines } = screenView();
+                const maxOffset = Math.max(0, lines.length - height);
+                if (key === 'j' || key === '\x1b[B')
+                    offset += 1;
+                if (key === 'k' || key === '\x1b[A')
+                    offset -= 1;
+                if (key === '\x1b[6~')
+                    offset += height;
+                if (key === '\x1b[5~')
+                    offset -= height;
+                if (key === 'g')
+                    offset = 0;
+                if (key === 'G')
+                    offset = maxOffset;
+                offset = Math.max(0, Math.min(offset, maxOffset));
+                draw();
+                return;
+            }
+            // List screens: move the selection, then scroll so the highlight stays
+            // visible. Clamp against screenView().selRow — the ABSOLUTE physical row
+            // (the project ticket table prepends a header row, so it is 1 + index;
+            // the dashboard has none) — not the 0-based index (the AC-2 off-by-one).
+            const move = (delta) => {
+                const next = Math.max(0, Math.min(selectedIndex() + delta, selectable - 1));
+                if (screen === 'dashboard')
+                    selectedProject = next;
+                else if (screen === 'ticket-agents')
+                    selectedAgent = next;
+                else if (screen === 'project-runs')
+                    selectedRun = next;
+                else
+                    selectedTicket = next;
+                offset = scrollTo(screenView().selRow, offset, viewHeight());
+            };
+            if (key === 'j' || key === '\x1b[B')
+                move(1);
+            if (key === 'k' || key === '\x1b[A')
+                move(-1);
+            if (key === 'g')
+                move(-selectable);
+            if (key === 'G')
+                move(selectable);
+            draw();
+        };
+        // Stable listener reference for on/off. A sync throw inside handleKey (a
+        // draw/move failure) would otherwise surface as an unhandled rejection;
+        // catch it and show it in the status bar instead of crashing the process.
+        const onData = (buffer) => {
+            Promise.resolve()
+                .then(() => handleKey(buffer))
+                .catch((caught) => {
+                error = caught instanceof Error ? caught.message : String(caught);
+                draw();
+            });
+        };
+        input.setRawMode(true);
+        input.resume();
+        input.on('data', onData);
+        output.on('resize', handleResize);
+        output.write('\x1b[?25l');
+        // Surviving agents rehydrate lazily: opening a project's Ticket-Agents screen
+        // reconciles it from that project's live panes (AC-5 restart survival) — there
+        // is no project context at start, so nothing to reconcile here.
+        void openDashboard();
+    });
+}