@lamemind/loom-deck 0.55.0 → 0.56.0

package/dist/deck-model.js

@@ -0,0 +1,348 @@
+// Il MODELLO del deck: ciò che si sta guardando e come lo si naviga.
+//
+// Tiene insieme le fonti (task, conversazioni, archiviabili, dettaglio), lo
+// stato di navigazione (focus, selezione dei due pane, vista attiva di ognuno) e
+// le derivazioni che la schermata consuma. Non spawna, non scrive su disco, non
+// legge la tastiera: chi agisce è `actions.ts`, chi dispaccia è `input.ts`.
+//
+// T131 — la superficie di ritorno è larga (~35 campi), e va dichiarato invece
+// che nascosto. La ragione per cui va bene qui e non altrove è che questo È il
+// modello: l'insieme di ciò che la vista consuma, e un modello con trenta campi
+// resta tale che sia scritto in un `return` o sparso nel corpo di un
+// componente. Quello che non va fatto è passarlo PEZZO PER PEZZO ai
+// consumatori — gli attuatori e il dispatch ne ricevono l'oggetto intero, ed è
+// la ragione per cui i loro conti di parametri restano leggibili.
+import { useEffect, useMemo, useState } from 'react';
+import { loadArchivableDays, loadIdentity, loadLaunch } from './config.js';
+import { useArchivable, useDirtyFolders, useSessions, useTaskDetail, useTasks, } from './hooks.js';
+import { isDone } from './layout.js';
+import { TASK_EMPTY, relTime } from './glyphs.js';
+import { assembleSessionList, firstSelectableId, rowIndexOf, selectedSession, } from './session-list.js';
+import { cycleSessionView, cycleTaskView, selectSessionRows, selectTasks, sessionView, taskView, } from './pane-views.js';
+import { ALL, MAX_SESSIONS, MAX_SESSIONS_ALL, META_ROWS, ROW_ALL, ROW_SPOT, SPOT, } from './model.js';
+import { applyView, taskColumns } from './view.js';
+import { loadView } from './view-store.js';
+import { termWidth } from './width.js';
+/**
+ * Conteggio dei figli per task, più il rollup delle VIVE e le conversazioni
+ * senza binding.
+ *
+ * T124 — il rollup delle vive si deriva NELLO STESSO CICLO del conteggio, non
+ * da un secondo passaggio sul registry dei processi: quel registry conosce una
+ * conversazione PRIMA che abbia scritto il suo primo record di transcript,
+ * quindi due derivazioni indipendenti renderebbero producibile `1/0` — una viva
+ * senza totale — che non è un caso limite teorico ma la finestra normale fra lo
+ * spawn e il primo turno. Intersecando qui, **`vive ≤ totali` è garantito per
+ * costruzione**: la conversazione appena nata resta invisibile a entrambi i
+ * numeri finché non scrive, e il segnale arriva in ritardo di un turno invece
+ * che sbagliato.
+ */
+export function rollupChildren(sessions, bindings, live) {
+    const childCount = new Map();
+    const taskLive = new Map();
+    let spotCount = 0;
+    for (const s of sessions) {
+        const bound = bindings.get(s.sessionId);
+        if (!bound) {
+            spotCount++;
+            continue;
+        }
+        childCount.set(bound, (childCount.get(bound) ?? 0) + 1);
+        const entry = live.get(s.sessionId);
+        if (!entry)
+            continue;
+        const prev = taskLive.get(bound);
+        // Rollup a stato misto: vince `busy`. Fra N vive, quella che sta lavorando è
+        // la ragione per cui si guarda la riga.
+        taskLive.set(bound, {
+            count: (prev?.count ?? 0) + 1,
+            status: prev?.status === 'busy' || entry.status === 'busy' ? 'busy' : 'idle',
+        });
+    }
+    return { childCount, taskLive, spotCount };
+}
+/**
+ * T60 — larghezze delle colonne fisse della lista sessioni, misurate sulla
+ * lista INTERA e non sulla finestra visibile: derivarle dalle sole righe a
+ * schermo le farebbe cambiare a ogni scroll, cioè l'opposto di una tabella.
+ *
+ * La colonna task esiste solo nella vista "tutte" (altrove il binding è lo
+ * stesso su ogni riga e sta già nell'header del pane), e `0` la spegne.
+ */
+export function sessionColumns(rows, bindings, isAll) {
+    let task = 0;
+    let age = 2;
+    for (const r of rows) {
+        // T133 D10 — la colonna serve dove l'appartenenza NON è già scritta
+        // altrove sullo schermo, cioè nella sola vista "tutte": ogni altra lista
+        // contiene le figlie del parent selezionato, che l'header nomina.
+        if (isAll) {
+            const b = bindings.get(r.sessionId);
+            if (b)
+                task = Math.max(task, termWidth(b));
+        }
+        if (r.kind === 'session')
+            age = Math.max(age, termWidth(relTime(r.session.ts)));
+    }
+    // La cella vuota deve poter entrare nella colonna, o le righe spot
+    // perderebbero il segnaposto e con lui l'allineamento.
+    return { task: task > 0 ? Math.max(task, termWidth(TASK_EMPTY)) : 0, age };
+}
+/**
+ * Le conversazioni figlie della selezione: tutte quelle del progetto (`≡
+ * tutte`), quelle bound alla task selezionata, oppure (spot) quelle senza
+ * binding. `sessions` è già ts desc → l'ordine si eredita in tutti e tre i rami.
+ */
+export function childSessionsOf(sessions, bindings, selectedTaskId, isAll) {
+    if (isAll)
+        return sessions;
+    return sessions.filter((s) => {
+        const bound = bindings.get(s.sessionId);
+        return selectedTaskId ? bound === selectedTaskId : !bound;
+    });
+}
+export function useDeckModel({ cwd, tasksPath, tasksDir, setNote, }) {
+    const { tasks, loadError } = useTasks(tasksPath);
+    // `notes` esce dall'indice come `sessionNotes`: nel deck `note` è già la riga
+    // di STATO in fondo al frame (il feedback di un'azione). Due concetti diversi
+    // a una lettera di distanza sarebbero una trappola di lettura — e di
+    // scrittura, visto che `setNote` compare in quasi ogni ramo.
+    const { sessions, bindings, forkOf, pinned, notes: sessionNotes, live, reload: reloadSessions, } = useSessions(cwd);
+    const [focus, setFocus] = useState('tasks');
+    // T39 — selezione KEYED SU ID, non su indice. Con una vista trasformata
+    // (filtro/sort) l'indice non identifica più la stessa task: leggere l'array
+    // grezzo per posizione spawnerebbe la task sbagliata, in silenzio.
+    // T59 — e le righe meta sono sentinelle, non `null`: gli stati sono tre.
+    // D4 — si apre su `≡ tutte`: la vista più ampia in cima, poi si scende verso
+    // i sottoinsiemi. La selezione non è persistita (a differenza di `view`, T39),
+    // quindi questo atterraggio vale a ogni avvio.
+    const [sel, setSel] = useState(ALL);
+    // T50 — selezione del pane sessioni KEYED SU sessionId (non indice): la lista
+    // a due gruppi + separatore è una vista trasformata, un indice grezzo punterebbe
+    // alla riga sbagliata dopo un pin o un cambio di contesto (stesso trap T39).
+    const [selSessionId, setSelSessionId] = useState(null);
+    // T39 — vista corrente (filtri + sort). Vive nel modello e non nell'hook dei
+    // modali che la editano: è ciò che `applyView` consuma per produrre la lista,
+    // è persistita su disco e la rilegge il tasto `w`. È stato del modello che due
+    // overlay scrivono, non stato di un overlay.
+    const [view, setView] = useState(() => loadView(cwd));
+    // T100 — vista attiva di ciascun pane, navigata con `tab`. VOLATILE per
+    // decisione (D3 create): non entra in `deck-view.json`, il deck riapre sempre
+    // su `Tasks` e su `{parent}`. Il criterio è il rischio di leggere una lista
+    // parziale credendola completa — un filtro salvato lo si è scelto, una vista
+    // riaperta a freddo si legge come la lista intera.
+    const [taskViewId, setTaskViewId] = useState('tasks');
+    const [sessionViewId, setSessionViewId] = useState('context');
+    // Voci launch del progetto (T32): lette una volta, raggiunte per indice 1..9.
+    const launch = useMemo(() => loadLaunch(cwd), [cwd]);
+    // Identità (T37): titolo delle tab terminale spawnate col tasto `t`.
+    const identity = useMemo(() => loadIdentity(cwd), [cwd]);
+    // T53 — il core che ogni titolo di tab porta, quindi la colonna costante da
+    // togliere quando serve spazio. Hoistato perché lo consumano DUE schermate
+    // (lista e ricerca): calcolarlo su ogni call site è il modo in cui le due
+    // smettono di togliere la stessa cosa.
+    // T58 — il core è il solo `name`, non `<emoji> <name>` come la chiave di match
+    // di compass: qui non serve entropia (è un taglio cosmetico, non un matcher) e
+    // il nome nudo ripulisce anche i titoli storici, scritti quando la formula
+    // includeva l'owner.
+    const projectCore = identity ? identity.name : null;
+    const projectName = cwd.split('/').pop() || cwd;
+    // La vista è una trasformazione DERIVATA, applicata a valle del load: il
+    // polling di tasks.md continua a funzionare senza saperne nulla.
+    const { visible: viewTasks, hidden: hiddenTasks } = useMemo(() => applyView(tasks, view), [tasks, view]);
+    // T61 — il conteggio guarda la lista GREZZA, non `viewTasks`: le Done fuori
+    // dai filtri della vista restano archiviabili, e un contatore che cambiasse
+    // filtrando direbbe qualcosa sulla vista invece che sulla task list.
+    const doneSig = useMemo(() => tasks.filter((t) => isDone(t.prog)).map((t) => t.id).join(','), [tasks]);
+    const archivableDays = useMemo(() => loadArchivableDays(cwd), [cwd]);
+    const archivable = useArchivable(doneSig, tasksDir, cwd, archivableDays);
+    // T112 — secondo asse di stato della vista `archiviabili`: quali fra le
+    // eliminabili hanno una folder che `git rm` non svuoterebbe. Si misura solo
+    // su quelle, non su tutta la lista: fuori da quella vista `CANC` agisce su
+    // una task sola e il dato lo ricalcola al momento.
+    const archivableSig = useMemo(() => [...archivable].sort().join(','), [archivable]);
+    const dirtyFolders = useDirtyFolders(archivableSig, tasksDir, cwd);
+    // T100 — le task effettivamente a schermo: la vista principale coincide con
+    // `viewTasks` (nessun ricalcolo sul cammino di default), le altre due passano
+    // dal predicato del catalogo. I CONTATORI restano misurati sulla vista di
+    // default, o navigare cambierebbe i numeri che si sta navigando.
+    const taskCounts = {
+        filtered: viewTasks.length,
+        total: tasks.length,
+        hidden: hiddenTasks,
+        archivable: archivable.size,
+    };
+    const paneTasks = useMemo(() => taskViewId === 'tasks' ? viewTasks : selectTasks(tasks, taskViewId, { view, archivable }), [taskViewId, viewTasks, tasks, view, archivable]);
+    const isSpot = sel === SPOT;
+    const isAll = sel === ALL;
+    // T112 — quando `CANC` pota in BLOCCO invece della sola task selezionata.
+    //
+    // La SELEZIONE batte la vista, non il contrario: con una riga task sotto il
+    // caret il tasto tocca quella task e basta, in ogni vista. Il bulk vive solo
+    // sulle righe meta della vista `archiviabili`, cioè richiede di essere usciti
+    // da ogni riga task — così l'azione di massa non è mai a un tasto di distanza
+    // da quella singola, e non si preme guardando una task evidenziata credendo
+    // che il bersaglio sia lei.
+    //
+    // Derivato una volta e letto sia dal ramo di apertura sia dalla legenda: due
+    // condizioni scritte due volte direbbero due cose diverse sullo stesso tasto
+    // alla prima modifica.
+    const purgeBulk = taskViewId === 'archivable' && (isAll || isSpot);
+    // Unica fonte della selezione: si legge SEMPRE dalla vista, mai dall'array
+    // grezzo — è l'invariante che tiene allineati dettaglio mostrato e spawn.
+    const selTask = typeof sel === 'string' ? paneTasks.find((t) => t.id === sel) ?? null : null;
+    const selectedTaskId = selTask?.id ?? null;
+    const selIndex = selTask ? paneTasks.indexOf(selTask) + META_ROWS : isAll ? ROW_ALL : ROW_SPOT;
+    const detail = useTaskDetail(tasksDir, selectedTaskId ?? undefined);
+    // Il parent delle conversazioni: l'asse che sceglie il pane task, ortogonale
+    // alla vista che sceglie l'header (D2 create).
+    const parentLabel = isAll ? 'tutte' : isSpot ? 'spot' : selectedTaskId ?? '—';
+    const { childCount, taskLive, spotCount } = rollupChildren(sessions, bindings, live);
+    const taskRowData = { childCount, live: taskLive, dirty: dirtyFolders };
+    // T118 — colonne fisse della lista task, misurate su `paneTasks` (la vista
+    // attiva INTERA) e non sulla finestra visibile: gemelle di `sessionCols` e
+    // per la stessa ragione, che una larghezza derivata dallo schermo si muove a
+    // ogni scroll.
+    const taskCols = taskColumns(paneTasks, taskRowData);
+    // Memoizzato così `sessionRows` resta stabile fra render che non cambiano gli
+    // input: l'effect di validità della selezione non rigira a vuoto.
+    const childSessions = useMemo(() => childSessionsOf(sessions, bindings, selectedTaskId, isAll), [sessions, bindings, selectedTaskId, isAll]);
+    // T133 — lista unica: le figlie del parent, `ts desc`, cap su tutte. Le
+    // pinnate del progetto escono a parte (`pinnedRows`), per la sola vista `📌`.
+    // Core PURO in session-list.ts (testabile senza Ink).
+    const assembled = useMemo(() => assembleSessionList(childSessions, sessions, pinned, isAll ? MAX_SESSIONS_ALL : MAX_SESSIONS), [childSessions, sessions, pinned, isAll]);
+    // T62 — contato sulla lista INTERA (stessa ragione delle larghezze di colonna
+    // qui sotto): derivarlo dalla finestra visibile lo farebbe cambiare a ogni
+    // scroll, cioè un contatore che conta lo schermo invece della lista.
+    // T100 — «intera» ora vuol dire la lista della vista di DEFAULT (`assembled`),
+    // non quella a schermo: il contatore di una voce del catalogo non può
+    // dipendere da quale voce è selezionata, o navigare muoverebbe i numeri.
+    const liveCount = useMemo(() => assembled.rows.filter((r) => live.has(r.sessionId)).length, [assembled, live]);
+    const sessionCounts = {
+        total: assembled.contextTotal,
+        live: liveCount,
+        pinned: assembled.pinnedRows.length,
+        older: assembled.overflowRows.length,
+    };
+    // T100 — le righe a schermo sono quelle della vista attiva.
+    const sessionRows = useMemo(() => selectSessionRows(sessionViewId, { assembled, isLive: (id) => live.has(id) }), [sessionViewId, assembled, live]);
+    const selSessionObj = selectedSession(sessionRows, selSessionId);
+    const sessionCols = useMemo(() => sessionColumns(sessionRows, bindings, isAll), [sessionRows, bindings, isAll]);
+    // T39 — selezione stabile sotto trasformazione. Se la task selezionata esce
+    // dalla vista (filtro appena attivato, oppure sparita da tasks.md), si cade
+    // sulla prima visibile — fallback deterministico, mai una posizione a caso.
+    useEffect(() => {
+        if (typeof sel === 'string' && !paneTasks.some((t) => t.id === sel)) {
+            setSel(paneTasks[0]?.id ?? ALL);
+        }
+    }, [paneTasks, sel]);
+    // T50 — la selezione (id) resta valida sotto la vista a due gruppi: se l'id
+    // non è più una riga selezionabile (cambio parent, lista mutata, pin rimosso,
+    // sessione sparita) cade sulla prima riga — fallback deterministico, mai una
+    // posizione a caso. Sostituisce il reset-a-0 e il clamp index-based.
+    useEffect(() => {
+        if (rowIndexOf(sessionRows, selSessionId) < 0) {
+            setSelSessionId(firstSelectableId(sessionRows));
+        }
+    }, [sessionRows, selSessionId]);
+    /** Selezione per INDICE nella vista, riconvertita subito in sentinella o id.
+     *  T21 — la chiama anche il click su una riga del pane task. */
+    function selectTaskRow(index) {
+        if (index === ROW_ALL)
+            setSel(ALL);
+        else if (index === ROW_SPOT)
+            setSel(SPOT);
+        else
+            setSel(paneTasks[index - META_ROWS]?.id ?? SPOT);
+    }
+    // Sposta la selezione di `delta` righe nella VISTA (0 = tutte, 1 = spot,
+    // 2..N+1 = task visibili) e la riconverte subito in sentinella o id: l'indice
+    // non sopravvive a un cambio di filtro, l'id sì.
+    function moveTaskSel(delta) {
+        selectTaskRow(Math.max(0, Math.min(paneTasks.length + META_ROWS - 1, selIndex + delta)));
+    }
+    // T21 — per VISTA e non per passo: il click sull'header nomina una voce, e
+    // `tab` la raggiunge ciclando. Sulla vista già attiva non si fa niente — un
+    // click che azzerasse la selezione alla riga in alto sarebbe un effetto che
+    // la tastiera non ha mai avuto, perché `tab` non può restare ferma.
+    function selectTaskView(next) {
+        if (next === taskViewId)
+            return;
+        setTaskViewId(next);
+        setSel(ALL);
+        setNote(`vista task: ${taskView(next).label(taskCounts)}`);
+    }
+    function selectSessionView(next) {
+        if (next === sessionViewId)
+            return;
+        setSessionViewId(next);
+        setSelSessionId(null);
+        setNote(`vista sessioni: ${sessionView(next).label(sessionCounts, parentLabel)}`);
+    }
+    // T100 — `tab` naviga il catalogo viste del pane in focus. Il reset della
+    // selezione è la regola letterale «prima riga in alto», senza eccezioni: sul
+    // pane task è `ROW_ALL` (D2 preflight — le righe meta non si saltano, e il
+    // parent delle sessioni che torna a `tutte` è un effetto accettato); sul pane
+    // sessioni basta invalidare l'id, e l'effect di validità atterra sulla prima
+    // riga selezionabile della vista nuova.
+    function cycleView(delta) {
+        if (focus === 'tasks')
+            selectTaskView(cycleTaskView(taskViewId, delta));
+        else
+            selectSessionView(cycleSessionView(sessionViewId, delta));
+    }
+    return {
+        // fonti
+        tasks,
+        loadError,
+        sessions,
+        bindings,
+        forkOf,
+        pinned,
+        sessionNotes,
+        live,
+        reloadSessions,
+        detail,
+        // progetto
+        launch,
+        identity,
+        projectCore,
+        projectName,
+        // stato di navigazione
+        focus,
+        setFocus,
+        sel,
+        selSessionId,
+        setSelSessionId,
+        view,
+        setView,
+        taskViewId,
+        sessionViewId,
+        // derivazioni del pane task
+        viewTasks,
+        hiddenTasks,
+        taskCounts,
+        paneTasks,
+        isSpot,
+        isAll,
+        purgeBulk,
+        selTask,
+        selectedTaskId,
+        selIndex,
+        parentLabel,
+        taskRowData,
+        taskCols,
+        spotCount,
+        // derivazioni del pane sessioni
+        sessionRows,
+        sessionCounts,
+        selSessionObj,
+        sessionCols,
+        // mutatori di navigazione
+        selectTaskRow,
+        moveTaskSel,
+        selectTaskView,
+        selectSessionView,
+        cycleView,
+    };
+}

package/dist/frame.js

@@ -0,0 +1,178 @@
+// La GEOMETRIA di un frame del deck: cosa entra a schermo, dove, e quali righe
+// sono cliccabili.
+//
+// Modulo PURO — nessun React, nessuno stato, nessun effetto. Prende le misure
+// del terminale e le liste intere, restituisce il budget d'altezza, le finestre
+// di rendering e la mappa dell'hit-test. Ne discende che è testabile a unità,
+// che è la ragione principale per cui è uscito da `cli.tsx`: qui vivono due
+// invarianti che prima erano affidate a un commento — la legenda che non deve
+// mentire sul bersaglio di `CANC`, e le righe cliccabili che devono essere
+// esattamente quelle disegnate.
+//
+// T131 — l'ordine di calcolo è vincolante rispetto al cablaggio dell'input.
+// `frameGeometry` va invocata PRIMA di `useDeckInput`, perché l'hook del mouse
+// riceve `listGeometry` come valore e non più attraverso una closure che la
+// leggeva dichiarata seicento righe più in basso. Il costo è calcolare il
+// budget anche quando il render esce presto su una schermata sostitutiva:
+// aritmetica su array già in memoria, e `layoutBudget` accetta ogni `Mode`.
+import { headerItems, sessionHeaderParts, taskHeaderParts } from './pane-header.js';
+import { FRAME_TEXT_COL, inlineRegions, LAUNCH_ROW, PANE_TEXT_PAD, paneSpans, rowRegions, } from './mouse.js';
+import { cellWidth, launchLegend, LAUNCH_SEP } from './config.js';
+import { layoutBudget, windowRange } from './viewport.js';
+import { sanitize, termWidth } from './width.js';
+import { META_ROWS } from './model.js';
+import { rowIndexOf } from './session-list.js';
+import { VERSION } from './version.js';
+// Le due surface built-in del cappello, in testa alla riga launch. Non stanno
+// fra i tasti perché hanno la stessa natura delle voci `launch` — fire-once,
+// cwd = project root, nessuno stato — e la differenza è solo che sono
+// universali (nessun progetto le dichiara) invece che custom. Emoji del menu
+// compass: 🤖 = nuova sessione claude. Per il terminale compass usa 🖥️, che nel
+// frame Ink NON passa — `sanitize` lo sostituisce (VTE lo disegna largo 1,
+// string-width dice 2: discordante, invariante ① di width.ts) e resterebbe un
+// `·` muto. 💻 è il gemello concorde; il `sanitize` qui rende il vincolo
+// automatico invece che da ricordare.
+//
+// T21 — `key` è il tasto che la superficie rappresenta: un click su di essa
+// entra nell'handler di tastiera con quel tasto, invece di chiamare l'azione
+// per conto proprio. È ciò che tiene click e tasto per costruzione allineati.
+export const SURFACE_SEGMENTS = [
+    { key: 't', text: sanitize('t 💻') },
+    { key: 'c', text: sanitize('c 🤖') },
+];
+/**
+ * La legenda della modalità normale. Elenca SOLO i tasti che fanno qualcosa qui
+ * e ora: le voci contestuali compaiono quando il pane a fuoco le rende possibili
+ * e altrimenti spariscono, invece di annunciarsi inerti con un `—`.
+ *
+ * Fuori: la navigazione (`↑↓` `←→`), universale in qualunque TUI, e
+ * l'indicatore `focus:` — il pane a fuoco si vede già dall'evidenziazione, e
+ * ridirlo a parole costava colonne su una riga che tronca in silenzio.
+ * Nessuna voce di uscita: non esiste più un tasto che chiuda il deck.
+ */
+export function deckLegend(state) {
+    const canSpawn = state.focus === 'tasks' && state.hasTask;
+    const canResume = state.focus === 'sessions' && state.hasSession;
+    // T50 — il pin agisce su qualunque riga selezionata (anche stale, per
+    // spinnarla); basta il focus sul pane e una selezione.
+    const canPin = state.focus === 'sessions' && state.hasSessionId;
+    return sanitize([
+        ...(canSpawn ? ['⏎ detail', '^K/^P/^R spawn'] : canResume ? ['⏎ resume'] : []),
+        // T112 — la voce nomina il BERSAGLIO, che cambia di taglia senza che
+        // cambi il tasto. Legge `purgeBulk`, la stessa condizione del ramo di
+        // apertura: una legenda che annunciasse «tutte» dove il tasto ne pota una
+        // sola sarebbe peggio di nessuna legenda.
+        ...(state.focus === 'tasks' ? [state.purgeBulk ? 'CANC elimina tutte' : 'CANC elimina'] : []),
+        ...(canResume ? ['f fork'] : []),
+        // T117 · D3 — «titolo» anche qui: è lo stesso valore che il detail chiede
+        // allo spawn, e due nomi per una cosa sola li paga chi legge le due
+        // schermate. Rename di sola ETICHETTA: il dato resta `note` nel sidecar e
+        // `--title-note` in deck-run, dove rinominarlo sarebbe un breaking.
+        ...(canPin ? ['p pin', 'N titolo', 'A assegna'] : []),
+        // T121 — le due voci nominano il GESTO e non l'oggetto: «status» da solo
+        // sarebbe indistinguibile dal recap della task su `^K`, che è un'altra
+        // cosa e sta a due voci di distanza.
+        '^G genera status',
+        '^O apri status',
+        '^F cerca',
+        'C nuova',
+        'E edit',
+        'S sort',
+        'F filtri',
+        'w salva',
+    ].join(' · '));
+}
+/**
+ * T21 — la riga launch come DATO, non come stringa: gli stessi segmenti
+ * compongono il testo renderizzato e le colonne dell'hit-test. Derivare le
+ * seconde ri-splittando il primo sarebbe un conto parallelo, che diverge alla
+ * prima label che contenga il separatore.
+ *
+ * Le celle delle surface (più il ` · ` che le separa dalle voci) sono già spese
+ * sulla riga → vanno riservate, o le voci launch la sfonderebbero di quel tanto.
+ */
+export function launchRow(launch, columns) {
+    const surfaceLegend = SURFACE_SEGMENTS.map((s) => s.text).join(LAUNCH_SEP);
+    const legend = launchLegend(launch, columns, cellWidth(surfaceLegend) + cellWidth(LAUNCH_SEP));
+    const segments = [
+        ...SURFACE_SEGMENTS,
+        ...legend.taken.map((text, i) => ({ key: String(i + 1), text })),
+    ];
+    return {
+        segments,
+        regions: rowRegions(segments, LAUNCH_SEP, FRAME_TEXT_COL),
+        overflow: legend.overflow,
+        unreachable: legend.unreachable,
+    };
+}
+/**
+ * Il budget d'altezza e le finestre di rendering.
+ *
+ * Il frame deve restare sotto `rows`, sempre: oltre quella soglia Ink smette di
+ * aggiornare per differenza e pulisce lo schermo a ogni redraw, che su Ptyxis
+ * significa un frame intero versato nello scrollback per ogni tick del poll.
+ * Tutto ciò che varia in altezza (le due liste e la descrizione del dettaglio)
+ * riceve qui la propria capienza.
+ *
+ * Le liste "logiche" restano intere: navigazione, selezione e spawn continuano
+ * a ragionare su quelle, la finestra è solo ciò che finisce a schermo.
+ */
+export function frameGeometry(input) {
+    // Le surface built-in `t`/`c` la rendono sempre presente in modalità normale:
+    // non dipende da quante voci `launch` il progetto dichiara.
+    const launchLine = input.mode === 'normal';
+    const budget = layoutBudget({
+        rows: input.rows,
+        mode: input.mode,
+        launchLine,
+        noteLine: input.hasNote,
+        preview: input.previewKind,
+        detailMetaLines: input.detailMetaLines,
+        // Riservo righe di anteprima solo per i blocchi che davvero renderizzano: il
+        // primo prompt aggiunge info solo con un titolo custom (senza, titolo ===
+        // primo prompt); l'ultima risposta solo se il modello ha già risposto.
+        sessionHasFirstPreview: input.sessionHasFirstPreview,
+        sessionHasLastPreview: input.sessionHasLastPreview,
+    });
+    const taskWin = windowRange(input.paneTasks.length, input.selIndex - META_ROWS, budget.taskRows);
+    const windowTasks = input.paneTasks.slice(taskWin.start, taskWin.end);
+    const selRowIndex = rowIndexOf(input.sessionRows, input.selSessionId);
+    const sessionWin = windowRange(input.sessionRows.length, selRowIndex, budget.sessionRows);
+    const windowRows = input.sessionRows.slice(sessionWin.start, sessionWin.end);
+    // T21 — geometria delle liste per l'hit-test del click, dalla STESSA
+    // aritmetica che disegna i pane: le parti degli header escono dal modulo che
+    // `ui/panes.tsx` consuma per renderle, le righe cliccabili sono le finestre
+    // appena calcolate.
+    const spans = paneSpans(input.columns);
+    const listGeometry = budget.compact
+        ? null
+        : {
+            columns: input.columns,
+            taskHeader: inlineRegions(headerItems(taskHeaderParts(input.taskCounts, input.taskViewId, taskWin.start, input.paneTasks.length - taskWin.end, input.columns)), spans.tasks.start + PANE_TEXT_PAD),
+            sessionHeader: inlineRegions(headerItems(sessionHeaderParts(input.parentLabel, input.sessionCounts, input.sessionViewId, sessionWin.start, input.sessionRows.length - sessionWin.end, input.columns)), spans.sessions.start + PANE_TEXT_PAD),
+            // Con un errore di caricamento al posto delle task c'è la riga rossa:
+            // restano cliccabili le sole righe meta.
+            taskRows: META_ROWS + (input.hasLoadError ? 0 : windowTasks.length),
+            sessionRows: windowRows.length,
+        };
+    return {
+        budget,
+        taskWin,
+        windowTasks,
+        sessionWin,
+        windowRows,
+        listGeometry,
+        // Dimensione del terminale in CELLE (colonne×righe, mai pixel — un processo
+        // dentro un terminale vede solo la griglia di caratteri) e versione. La
+        // parte sinistra della testata riceve un budget derivato da questa stringa e
+        // non da una lunghezza fissa: la risoluzione cambia a ogni resize, quindi
+        // anche la larghezza che occupa.
+        headerRight: `${input.columns}×${input.rows} · v${VERSION}`,
+        launchLine,
+    };
+}
+/** Il budget della testata sinistra, per sottrazione dal segmento destro. */
+export function headlineWidth(columns, headerRight) {
+    return Math.max(4, columns - 4 - termWidth(headerRight) - 1);
+}
+export { LAUNCH_ROW };

package/dist/inbox.js

@@ -0,0 +1,135 @@
+// T134 — la coda inbox come dato del deck.
+//
+// La misura non la fa il deck: la fa `doc-metrics.sh --inbox`, che per ogni file
+// invoca `inbox.sh parse` e ne riporta natura e marcatori. È il contrario della
+// scelta fatta per le task archiviabili (`archivable.ts`), dove il criterio —
+// una data meno un'altra — era abbastanza piccolo da replicarlo: qui si
+// replicherebbe la grammatica intera del marker inbox, e una divergenza fra le
+// due copie non si vedrebbe finché non conta i file sbagliati.
+//
+// Lettore puro + spawn: nessun React, nessuna resa. È l'unico modo di provarlo
+// senza pseudo-terminale.
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { basename } from 'node:path';
+import { pluginScript } from './plugin-cache.js';
+const execFileAsync = promisify(execFile);
+export const INBOX_METRICS_SCRIPT = 'scripts/docs/doc-metrics.sh';
+/** Le tre nature che una skill sa consumare, più il file che non si parsa. */
+export const NATURE = ['nozioni', 'derivazione', 'sweep'];
+/**
+ * `si`/`no` è la grafia dello script. Qualunque altra cosa (colonna vuota su un
+ * file malformato) è `false`: un marcatore che non si è potuto leggere non vale
+ * come presente.
+ */
+function flag(cell) {
+    return cell === 'si';
+}
+function num(cell) {
+    const n = Number(cell);
+    return Number.isFinite(n) ? n : 0;
+}
+function natura(cell) {
+    return NATURE.includes(cell) ? cell : 'malformato';
+}
+/**
+ * Il TSV di `doc-metrics.sh --inbox --format tsv`, riga di intestazione
+ * compresa. Colonne, nell'ordine emesso dallo script:
+ *
+ *   PATH · NATURA · INDEXED · DRAINABLE · BRANCH · NOZIONI · APERTE · CHAR ·
+ *   CREATED · AGE_DAYS · CAPPELLO
+ *
+ * `AGE_DAYS` si scarta di proposito: è troncato al giorno, e la soglia della
+ * sirena è in ORE — con i giorni interi 47 e 49 ore sarebbero lo stesso numero.
+ * L'età la ricalcola `ageHours` da `CREATED`.
+ */
+export function parseInboxTsv(stdout) {
+    const out = [];
+    for (const line of stdout.split('\n')) {
+        if (!line.trim())
+            continue;
+        const c = line.split('\t');
+        if (c[0] === 'PATH' || c.length < 11)
+            continue;
+        out.push({
+            path: c[0],
+            basename: basename(c[0]),
+            natura: natura(c[1]),
+            indexed: flag(c[2]),
+            drainable: flag(c[3]),
+            branch: c[4] ?? '',
+            nozioni: num(c[5]),
+            aperte: num(c[6]),
+            chars: num(c[7]),
+            created: num(c[8]),
+            cappello: c[10] ?? '',
+        });
+    }
+    // Dal più vecchio in cima (D8): i più vecchi sono i più urgenti. Lo script
+    // emette già in quest'ordine — riordinare qui costa nulla e toglie di mezzo
+    // la dipendenza da una garanzia scritta altrove.
+    return out.sort((a, b) => a.created - b.created);
+}
+/** Ore intere trascorse da `created` (epoch in secondi). */
+export function ageHours(created, now) {
+    return Math.floor((now - created * 1000) / 3_600_000);
+}
+/**
+ * Il file promette lavoro che una skill può prendere DA SOLA, senza che nessuno
+ * lo nomini: `drainable` e nessun branch che lo congeli.
+ *
+ * Non è un criterio di ammissibilità dell'azione, ed è la distinzione che tiene
+ * in piedi D5: le tre skill dichiarano tutte che un file NOMINATO si esegue
+ * anche senza `drainable` — nominarlo è già la decisione che il token
+ * dichiarerebbe. Replicare qui quel criterio come guardia impedirebbe ciò che
+ * l'utente ha appena chiesto. Serve solo a decidere cosa entra nei contatori.
+ */
+export function isQueued(f) {
+    return f.drainable && !f.branch && f.natura !== 'malformato';
+}
+/**
+ * Un contatore per natura, sui soli file in coda. Un `malformato` non ha natura
+ * e non entra in nessuno dei tre — ma resta in lista, perché nasconderlo
+ * produrrebbe un contatore che mente al ribasso proprio quando qualcosa si è
+ * rotto.
+ */
+export function countByNatura(files) {
+    const counts = { nozioni: 0, derivazione: 0, sweep: 0 };
+    for (const f of files)
+        if (isQueued(f))
+            counts[f.natura]++;
+    return counts;
+}
+export function totalQueued(counts) {
+    return counts.nozioni + counts.derivazione + counts.sweep;
+}
+/**
+ * D10 — 48 ore. Un campionamento a 6 ore sbaglia al massimo di un ottavo, cioè
+ * entro il rumore di una soglia scelta a mano.
+ */
+export const DEFAULT_INBOX_STALE_HOURS = 48;
+/** Quanti file in coda hanno passato la soglia: è il numero accanto alla sirena. */
+export function staleCount(files, hours, now) {
+    return files.filter((f) => isQueued(f) && ageHours(f.created, now) >= hours).length;
+}
+/**
+ * Invoca la misura e ne parsa l'output.
+ *
+ * I modi di non avere il dato — plugin non installato su questa macchina,
+ * script che esce male — collassano in un solo `ok: false` (D2): chi vede
+ * l'allerta chiede a Claude di indagare, e distinguerli a schermo non
+ * cambierebbe la prima mossa. Nessuno dei due è un throw: un contatore
+ * informativo non può rompere il deck.
+ */
+export async function scanInbox(projectRoot, docsRoot) {
+    const script = pluginScript(INBOX_METRICS_SCRIPT);
+    if (!script)
+        return { files: [], ok: false };
+    try {
+        const { stdout } = await execFileAsync(script, ['--docs-root', docsRoot, '--inbox', '--format', 'tsv'], { cwd: projectRoot, maxBuffer: 4 * 1024 * 1024 });
+        return { files: parseInboxTsv(stdout), ok: true };
+    }
+    catch {
+        return { files: [], ok: false };
+    }
+}