@lamemind/loom-deck 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lamemind
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,85 @@
+# loom-deck
+
+Deck TUI (Ink) **per-progetto** della famiglia [loom](https://github.com/lamemind/loom-works).
+
+Legge il `tasks.md` del progetto e, con un tasto (poi un click), **spawna** una tab
+[Ptyxis](https://gitlab.gnome.org/chergert/ptyxis) che avvia una sessione Claude Code
+già bound alla task via `LOOM_TASK`, dritta su `/loom-works:run-task <Txx>`.
+
+```
+↑↓ scegli la task  →  ⏎  →  tab CC di fianco  →  parte già su /loom-works:run-task <Txx>
+```
+
+## Ruolo nella famiglia loom
+
+`loom-deck` è un **client** con runtime proprio (TUI Ink) che **consuma** il contratto
+definito da `loom-works-plugin` (formato `tasks.md`, variabile `LOOM_TASK`) — non lo
+ridefinisce. Divisione dei ruoli con Compass:
+
+| | scope | ruolo | domanda |
+|---|---|---|---|
+| **Compass** (GNOME) | globale, cross-desktop | radar, stato live, focus/jump | "dove sono?" |
+| **loom-deck** (TUI) | per-progetto | attuatore locale, spawna task | "cosa faccio qui?" |
+
+## Architettura di processo
+
+Il deck è **UN processo Node**: spawna ma **non contiene** le sessioni CC — le possiede
+Ptyxis. Chiudere il deck non uccide le sessioni. La tab nasce nella window *attiva*
+(quella col focus = il deck) → desktop isolation "gratis".
+
+## Stato
+
+Bootstrap + spike ① + **TUI ③** funzionante (legge `tasks.md`, `⏎` spawna). Roadmap:
+
+```
+① spike spawn-tab + LOOM_TASK   ✅ scripts/deck-run
+② gradino $LOOM_TASK nelle skill loom-works
+③ TUI Ink sopra (lista tasks.md, ↑↓/⏎ → chiama ①)   ✅ src/
+④ mouse opzionale (SGR enable+parse+hit-test)
+⑤ azioni extra (start/preflight/checkpoint/merge dal deck)
+```
+
+## Installazione
+
+```bash
+npm install -g @lamemind/loom-deck   # comando globale `loom-deck`
+# oppure senza install permanente:
+npx @lamemind/loom-deck
+```
+
+## Requisiti runtime
+
+- **Node.js ≥ 18** (dichiarato in `engines`).
+- **[Ptyxis](https://gitlab.gnome.org/chergert/ptyxis)** (terminale GNOME) — **dipendenza
+  di runtime, non risolvibile da npm**. Lo spawn di una tab (`scripts/deck-run`) invoca il
+  binario `ptyxis`: l'**install riesce anche senza**, ma al momento dello spawn il comando
+  fallisce (gestito: handler `error` → la TUI resta viva, mostra la nota). Senza una GUI
+  GNOME con Ptyxis installato, il deck naviga i task ma **non apre sessioni**.
+- **[Claude Code](https://claude.com/claude-code)** nel `PATH` — la tab spawnata avvia `claude`.
+
+## Uso (spike ①)
+
+```bash
+# dalla project dir con un tasks.md
+scripts/deck-run T18
+```
+
+Apre una tab Ptyxis nella window attiva con `LOOM_TASK=T18 claude '/loom-works:run-task T18'`.
+
+## Sviluppo (TUI Ink)
+
+```bash
+npm install
+npm run dev      # tsx src/cli.tsx — lista tasks.md reale, ↑↓ naviga · ⏎ spawn · q esci
+npm run build    # tsc → dist/
+```
+
+Il deck cerca `tasks.md` in `$PWD/${LOOM_DECK_DOCS_ROOT:-docs}/tasks.md`. Progetti
+con docs-root non-standard esportano la variabile, es. `LOOM_DECK_DOCS_ROOT=runtime`.
+
+La lista si **auto-aggiorna** quando `tasks.md` cambia sotto (poll su `mtime`, ~1.5s):
+crei/checkpoint una task da un'altra sessione → il deck la riflette senza riavvio.
+
+## Licenza
+
+MIT © 2026 lamemind

package/dist/cli.js

@@ -0,0 +1,411 @@
+#!/usr/bin/env node
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { render, Box, Text, useApp, useInput } from 'ink';
+import { useState, useEffect } from 'react';
+import { spawn } from 'node:child_process';
+import { statSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { resolveTasksPath, resolveTasksDir, loadTasks, loadTaskDetail, } from './tasks.js';
+import { discoverProjectSessions } from './sessions.js';
+import { appendTaskBinding, loadTaskBindings } from './task-index.js';
+// scripts/deck-run è un sibling della dir del bundle: src/ (dev, tsx) e dist/
+// (build, node) stanno entrambi sotto la package root → risalita di un livello.
+const DECK_RUN = join(dirname(fileURLToPath(import.meta.url)), '..', 'scripts', 'deck-run');
+const POLL_MS = 1500;
+// Cap del pane sessioni: le più recenti (ts desc), le altre restano nell'indice
+// ma fuori vista. Non-silenzioso → l'header mostra quante sono nascoste.
+const MAX_SESSIONS = 30;
+// Modello task-centrico: il Tasks pane ha, oltre alle task reali, una riga
+// meta "spot" (sentinella) che raccoglie le sessioni NON legate ad alcuna task.
+// La selezione nel Tasks pane è il "padre"; il Sessions pane mostra i suoi figli.
+const SPOT = Symbol('spot');
+function isDone(prog) {
+    return prog.includes('✔');
+}
+// Spawn detached: il deck spawna ma NON contiene la sessione (la possiede
+// ptyxis-agent). unref + stdio ignore → ritorna subito, la TUI resta viva.
+// sessionId pinnato (T27) → il binding sidecar è deterministico allo spawn.
+function spawnDeck(id, cwd, sessionId) {
+    const child = spawn(DECK_RUN, [id, '--session-id', sessionId], {
+        cwd,
+        detached: true,
+        stdio: 'ignore',
+    });
+    child.unref();
+    return child;
+}
+// Editor esterni: aprono l'IDE sulla project root. Il comando risolve attraverso
+// la shell login+interattiva dell'utente (bash -lic) → alias/funzioni in ~/.bashrc
+// (es. `codium`=alias flatpak, `idea`=funzione) risolvono come nel terminale.
+// Override via env per ambienti senza quegli alias (loom-deck è destinato a NPM).
+const EDITOR_CMD = {
+    codium: process.env.LOOM_DECK_EDITOR_CODIUM ?? 'codium',
+    idea: process.env.LOOM_DECK_EDITOR_IDEA ?? 'idea',
+};
+// Spawn detached come spawnDeck: il deck lancia ma non possiede l'IDE. La project
+// root arriva via $PWD (spawn cwd) → niente interpolazione di path, zero injection.
+function openEditor(cmd, cwd) {
+    const child = spawn('bash', ['-lic', `${cmd} "$PWD"`], {
+        cwd,
+        detached: true,
+        stdio: 'ignore',
+    });
+    child.unref();
+    return child;
+}
+// Comando claude (override per ambienti dove non è su PATH; loom-deck → NPM).
+const CLAUDE_CMD = process.env.LOOM_DECK_CLAUDE_CMD ?? 'claude';
+// T30: create-task inline. Spawna CC HEADLESS (`-p`) con `--session-id` pinnato
+// che invoca la skill create-task. Differenze da spawnDeck:
+//  - headless (`-p`), non una tab Ptyxis interattiva → il deck osserva l'esito;
+//  - `yolo` FORZATO: create-task è interattiva di default (AskUserQuestion) e in
+//    `-p` non può ricevere risposte → si impianterebbe. yolo = zero domande.
+//  - `--output-format stream-json` (richiede `--verbose`): l'ultima riga è
+//    `{type:"result", is_error}`, segnale di completamento robusto (> exit code).
+//  - detached (own process-group) → il create sopravvive alla chiusura del deck e
+//    completa commit+push da sé; stdout in pipe SOLO per leggere il result event.
+// Il prompt viaggia come singolo argv (no shell) → nessuna injection dal testo utente.
+function spawnCreateTask(text, cwd, sessionId, onResult) {
+    const child = spawn(CLAUDE_CMD, [
+        '-p',
+        '--output-format',
+        'stream-json',
+        '--verbose',
+        '--session-id',
+        sessionId,
+        `/loom-works:create-task yolo ${text}`,
+    ], { cwd, detached: true, stdio: ['ignore', 'pipe', 'pipe'] });
+    let buf = '';
+    let isError = null;
+    child.stdout?.on('data', (chunk) => {
+        buf += chunk.toString();
+        let nl;
+        while ((nl = buf.indexOf('\n')) >= 0) {
+            const line = buf.slice(0, nl).trim();
+            buf = buf.slice(nl + 1);
+            if (!line)
+                continue;
+            try {
+                const obj = JSON.parse(line);
+                if (obj.type === 'result')
+                    isError = obj.is_error ?? false;
+            }
+            catch {
+                // riga parziale / non-json → skip
+            }
+        }
+    });
+    // Drena stderr per non riempire il buffer pipe (deadlock del figlio).
+    child.stderr?.on('data', () => { });
+    child.on('error', () => onResult(false));
+    child.on('close', (code) => {
+        onResult(isError === null ? code === 0 : !isError);
+    });
+    return child;
+}
+// Carica tasks.md e lo ri-legge quando cambia sotto (poll su mtime). Poll
+// (non fs.watch) perché i writer di tasks.md — checkpoint-task/create-task —
+// riscrivono il file (probabile replace atomico), che rompe il watch sull'inode
+// originale; statSync(path) segue sempre il file corrente al path.
+function useTasks(tasksPath) {
+    const [tasks, setTasks] = useState([]);
+    const [loadError, setLoadError] = useState('');
+    useEffect(() => {
+        let lastMtime = -1;
+        const reload = () => {
+            try {
+                const mtime = statSync(tasksPath).mtimeMs;
+                if (mtime === lastMtime)
+                    return; // invariato → niente re-read
+                lastMtime = mtime;
+                setTasks(loadTasks(tasksPath));
+                setLoadError('');
+            }
+            catch {
+                lastMtime = -1; // così quando il file riappare viene ri-letto
+                setTasks([]);
+                setLoadError(`tasks.md non leggibile: ${tasksPath}`);
+            }
+        };
+        reload();
+        const id = setInterval(reload, POLL_MS);
+        return () => clearInterval(id);
+    }, [tasksPath]);
+    return { tasks, loadError };
+}
+// Poll delle sessioni del progetto + binding sidecar. discoverProjectSessions
+// ha cache mtime-keyed interna → il poll è economico; qui si evita comunque il
+// re-render inutile con una signature (sessionId:ts + binding entries): setState
+// solo quando cambia davvero qualcosa.
+function useSessions(projectRoot) {
+    const [state, setState] = useState({
+        sessions: [],
+        bindings: new Map(),
+    });
+    useEffect(() => {
+        let lastSig = '';
+        const reload = () => {
+            let sessions;
+            let bindings;
+            try {
+                sessions = discoverProjectSessions(projectRoot);
+                bindings = loadTaskBindings(projectRoot);
+            }
+            catch {
+                sessions = [];
+                bindings = new Map();
+            }
+            const sig = sessions.map((s) => `${s.sessionId}:${s.ts}`).join('|') +
+                '#' +
+                [...bindings.entries()].map(([k, v]) => `${k}=${v}`).sort().join(',');
+            if (sig === lastSig)
+                return;
+            lastSig = sig;
+            setState({ sessions, bindings });
+        };
+        reload();
+        const id = setInterval(reload, POLL_MS);
+        return () => clearInterval(id);
+    }, [projectRoot]);
+    return state;
+}
+// Legge il task file della task selezionata (Q1+B T20). On-id-change: navigare
+// con ↑↓ ricarica il dettaglio; leggere un singolo file 4-9KB è I/O triviale,
+// niente debounce serve per la tastiera. Il refresh del contenuto a file fermo
+// (es. checkpoint aggiorna Progress) è demandato al prossimo cambio selezione.
+function useTaskDetail(tasksDir, id) {
+    const [detail, setDetail] = useState(null);
+    useEffect(() => {
+        setDetail(id ? loadTaskDetail(tasksDir, id) : null);
+    }, [tasksDir, id]);
+    return detail;
+}
+// Collassa gli spazi (description multi-paragrafo → blocco unico wrappabile) e
+// tronca: il pane resta compatto e d'altezza prevedibile sotto la lista.
+function truncate(s, n) {
+    const flat = s.replace(/\s+/g, ' ').trim();
+    return flat.length > n ? flat.slice(0, n - 1).trimEnd() + '…' : flat;
+}
+// Forza la presentazione emoji (larghezza 2 non-ambigua) su un glifo BMP
+// text-default come ⚡ (U+26A1, range simboli U+2190–U+2BFF). Senza il variation
+// selector VS16 questi glifi sono larghi-ambigui: Ink li misura 1, ma string-width
+// e il terminale li disegnano 2 → la riga esce 1 colonna troppo larga, sfonda il
+// pane e va a capo (righe vuote spurie). Gli emoji astrali (🔥🔵🟡…, U+1F000+) sono
+// già width-2 non-ambigui e le sequenze con VS16 (✔️) sono >1 code point → intatti.
+const VS16 = '️';
+function forceEmojiWidth(s) {
+    const cps = [...s];
+    if (cps.length !== 1)
+        return s;
+    const cp = cps[0].codePointAt(0);
+    if (cp >= 0x2190 && cp <= 0x2bff)
+        return s + VS16;
+    return s;
+}
+// Età relativa compatta (ms epoch → "2m"/"3h"/"5d") per il preview sessioni.
+function relTime(ts) {
+    const sec = Math.max(0, Math.floor((Date.now() - ts) / 1000));
+    if (sec < 60)
+        return `${sec}s`;
+    const min = Math.floor(sec / 60);
+    if (min < 60)
+        return `${min}m`;
+    const hr = Math.floor(min / 60);
+    if (hr < 24)
+        return `${hr}h`;
+    return `${Math.floor(hr / 24)}d`;
+}
+const META_KEYS = ['Priority', 'Size', 'Estimated Time', 'Progress'];
+function Deck({ cwd, tasksPath, tasksDir }) {
+    const { exit } = useApp();
+    const { tasks, loadError } = useTasks(tasksPath);
+    const { sessions, bindings } = useSessions(cwd);
+    const [focus, setFocus] = useState('tasks');
+    // selParent ∈ [0, tasks.length]: l'indice 0 è la riga meta "spot" (prima voce),
+    // gli indici 1..tasks.length sono le task reali (task = selParent-1).
+    const [selParent, setSelParent] = useState(0);
+    const [selSession, setSelSession] = useState(0);
+    const [note, setNote] = useState('');
+    // T30: modale di creazione task inline. mode='create' → useInput cattura il
+    // testo (gating della navigazione normale) e mostra l'input box.
+    const [mode, setMode] = useState('normal');
+    const [draft, setDraft] = useState('');
+    const isSpot = selParent === 0;
+    const projectName = cwd.split('/').pop() || cwd;
+    const selectedTaskId = isSpot ? null : tasks[selParent - 1]?.id ?? null;
+    const detail = useTaskDetail(tasksDir, selectedTaskId ?? undefined);
+    // Conteggio figli per task + spot (badge nel Tasks pane).
+    const childCount = new Map();
+    let spotCount = 0;
+    for (const s of sessions) {
+        const bound = bindings.get(s.sessionId);
+        if (bound)
+            childCount.set(bound, (childCount.get(bound) ?? 0) + 1);
+        else
+            spotCount++;
+    }
+    // Figli della selezione: sessioni bound alla task selezionata, oppure (spot)
+    // le sessioni senza binding. sessions è già ts desc → l'ordine si eredita.
+    const childSessions = sessions.filter((s) => {
+        const bound = bindings.get(s.sessionId);
+        return selectedTaskId ? bound === selectedTaskId : !bound;
+    });
+    const visibleSessions = childSessions.slice(0, MAX_SESSIONS);
+    const hiddenSessions = childSessions.length - visibleSessions.length;
+    // Dopo un refresh le liste possono accorciarsi: tieni le selezioni in range
+    // (max index = tasks.length; spot è sempre l'indice 0).
+    useEffect(() => {
+        setSelParent((s) => Math.min(s, tasks.length));
+    }, [tasks.length]);
+    // Cambio padre → riparti dalla prima sessione figlia.
+    useEffect(() => {
+        setSelSession(0);
+    }, [selParent]);
+    useEffect(() => {
+        setSelSession((s) => Math.min(s, Math.max(0, visibleSessions.length - 1)));
+    }, [visibleSessions.length]);
+    // T30: submit dell'input box. Il taskId nasce DOPO create-task (lo assegna la
+    // skill scrivendo tasks.md) → non è noto allo spawn. Il sessionId invece è
+    // pinnato qui: snapshot degli id PRIMA, poi al completamento re-leggo tasks.md
+    // e il diff dà il nuovo id → appendTaskBinding lega la sessione (scoped).
+    function submitCreate() {
+        const text = draft.trim();
+        setMode('normal');
+        setDraft('');
+        if (!text) {
+            setNote('c → create annullato (vuoto)');
+            return;
+        }
+        const sid = randomUUID();
+        const beforeIds = new Set(tasks.map((t) => t.id));
+        setNote(`⏳ creando task… "${truncate(text, 40)}" (sid ${sid.slice(0, 8)})`);
+        const child = spawnCreateTask(text, cwd, sid, (ok) => {
+            if (!ok) {
+                setNote(`⚠ create-task fallito (${CLAUDE_CMD} -p)`);
+                return;
+            }
+            let newId;
+            try {
+                newId = loadTasks(tasksPath).find((t) => !beforeIds.has(t.id))?.id;
+            }
+            catch {
+                // tasks.md illeggibile → id non rilevato, sotto
+            }
+            if (newId) {
+                appendTaskBinding(cwd, sid, newId);
+                setNote(`✔ ${newId} creata · sessione scoped (sid ${sid.slice(0, 8)})`);
+            }
+            else {
+                setNote(`✔ task creata (id non rilevato) · sid ${sid.slice(0, 8)}`);
+            }
+        });
+        child.on('error', () => setNote(`⚠ create-task: '${CLAUDE_CMD}' non lanciabile`));
+    }
+    useInput((input, key) => {
+        // T30: in modalità create l'handler cattura il testo e corto-circuita la
+        // navigazione normale (incl. q/esc → quit: qui esc annulla, non esce).
+        if (mode === 'create') {
+            if (key.escape) {
+                setMode('normal');
+                setDraft('');
+                setNote('c → create annullato');
+            }
+            else if (key.return) {
+                submitCreate();
+            }
+            else if (key.backspace || key.delete) {
+                setDraft((d) => d.slice(0, -1));
+            }
+            else if (input && !key.ctrl && !key.meta) {
+                setDraft((d) => d + input);
+            }
+            return;
+        }
+        if (key.leftArrow || key.rightArrow || key.tab) {
+            setFocus((f) => (f === 'tasks' ? 'sessions' : 'tasks'));
+        }
+        else if (key.upArrow) {
+            if (focus === 'tasks')
+                setSelParent((i) => Math.max(0, i - 1));
+            else
+                setSelSession((i) => Math.max(0, i - 1));
+        }
+        else if (key.downArrow) {
+            if (focus === 'tasks')
+                setSelParent((i) => Math.min(tasks.length, i + 1));
+            else
+                setSelSession((i) => Math.min(visibleSessions.length - 1, i + 1));
+        }
+        else if (key.return) {
+            if (focus === 'tasks') {
+                if (isSpot) {
+                    setNote('spot: sessioni libere, nessuna task da spawnare');
+                }
+                else {
+                    const task = tasks[selParent - 1];
+                    if (task) {
+                        // sessionId pinnato lato deck → binding sidecar scritto PRIMA dello
+                        // spawn: la sessione risulta figlia della task appena il JSONL compare.
+                        const sid = randomUUID();
+                        appendTaskBinding(cwd, sid, task.id);
+                        const child = spawnDeck(task.id, cwd, sid);
+                        // Un errore di spawn è async: senza handler diventa uncaughtException
+                        // e ucciderebbe il deck. Lo intercetto per preservare l'invariante
+                        // "il deck resta vivo" e mostro la nota d'errore.
+                        child.on('error', () => setNote(`⚠ spawn ${task.id} fallito (${DECK_RUN})`));
+                        setNote(`⏎ spawn ${task.id} → tab CC (sid ${sid.slice(0, 8)})`);
+                    }
+                }
+            }
+            else {
+                setNote('sessioni read-only in T27 · fork/resume → T28');
+            }
+        }
+        else if (input === 'c') {
+            setNote('');
+            setMode('create');
+        }
+        else if (input === 'C') {
+            const child = openEditor(EDITOR_CMD.codium, cwd);
+            child.on('error', () => setNote(`⚠ codium: '${EDITOR_CMD.codium}' non lanciabile`));
+            setNote(`C → codium su ${projectName}`);
+        }
+        else if (input === 'I') {
+            const child = openEditor(EDITOR_CMD.idea, cwd);
+            child.on('error', () => setNote(`⚠ idea: '${EDITOR_CMD.idea}' non lanciabile`));
+            setNote(`I → idea su ${projectName}`);
+        }
+        else if (input === 'q' || key.escape) {
+            exit();
+        }
+    });
+    const selSessionId = visibleSessions[selSession]?.sessionId;
+    const parentLabel = isSpot ? 'spot' : selectedTaskId ?? '—';
+    const canSpawn = focus === 'tasks' && !isSpot;
+    return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: "cyan", paddingX: 1, children: [_jsx(Text, { bold: true, color: "cyan", children: "loom-deck" }), mode === 'create' ? (_jsxs(Text, { dimColor: true, children: ["nuova task \u00B7 ", _jsx(Text, { color: "yellow", children: "\u23CE" }), " crea \u00B7 ", _jsx(Text, { color: "yellow", children: "esc" }), " annulla"] })) : (_jsxs(Text, { dimColor: true, children: ["\u2191\u2193 naviga \u00B7 \u2190\u2192 pane \u00B7 \u23CE ", canSpawn ? 'spawn' : '—', " \u00B7 c nuova \u00B7 C codium \u00B7 I idea \u00B7 q esci \u00B7 focus: ", _jsx(Text, { color: "cyan", children: focus })] })), mode === 'create' ? (_jsxs(Box, { borderStyle: "round", borderColor: "yellow", paddingX: 1, marginTop: 1, children: [_jsx(Text, { color: "yellow", children: "c \u203A " }), _jsx(Text, { children: draft }), _jsx(Text, { inverse: true, children: " " })] })) : null, _jsxs(Box, { flexDirection: "row", marginTop: 1, children: [_jsx(TasksPane, { tasks: tasks, selected: selParent, spotCount: spotCount, childCount: childCount, focused: focus === 'tasks', loadError: loadError, detail: detail }), _jsx(SessionsPane, { parentLabel: parentLabel, isSpot: isSpot, sessions: visibleSessions, total: childSessions.length, hidden: hiddenSessions, selectedId: selSessionId, focused: focus === 'sessions' })] }), note ? _jsx(Text, { color: "green", children: note }) : null] }));
+}
+function TasksPane({ tasks, selected, spotCount, childCount, focused, loadError, detail, }) {
+    const spotSelected = selected === 0;
+    return (_jsxs(Box, { flexDirection: "column", width: "50%", marginRight: 1, borderStyle: "single", borderColor: focused ? 'cyan' : 'gray', paddingX: 1, children: [_jsxs(Text, { bold: true, color: focused ? 'cyan' : undefined, children: ["Tasks (", tasks.length, ")"] }), _jsxs(Text, { inverse: spotSelected && focused, bold: spotSelected && !focused, wrap: "truncate-end", children: [spotSelected ? '▶ ' : '  ', "\u25CB spot  sessioni libere", spotCount > 0 ? ` (${spotCount})` : ''] }), loadError ? (_jsx(Text, { color: "red", wrap: "truncate-end", children: loadError })) : (tasks.map((task, i) => {
+                const sel = i + 1 === selected; // +1: lo 0 è spot
+                const n = childCount.get(task.id) ?? 0;
+                return (_jsxs(Text, { inverse: sel && focused, bold: sel && !focused, dimColor: !sel && isDone(task.prog), wrap: "truncate-end", children: [sel ? '▶ ' : '  ', task.id, "  ", forceEmojiWidth(task.pri), "  ", forceEmojiWidth(task.prog), "  ", task.desc, n > 0 ? ` (${n})` : ''] }, task.id));
+            })), detail ? _jsx(DetailPane, { detail: detail }) : null] }));
+}
+function SessionsPane({ parentLabel, isSpot, sessions, total, hidden, selectedId, focused, }) {
+    return (_jsxs(Box, { flexDirection: "column", width: "50%", borderStyle: "single", borderColor: focused ? 'cyan' : 'gray', paddingX: 1, children: [_jsxs(Text, { bold: true, color: focused ? 'cyan' : undefined, children: ["Sessions \u00B7 ", parentLabel, " (", total, ")", hidden > 0 ? _jsxs(Text, { dimColor: true, children: [" \u00B7 +", hidden, " pi\u00F9 vecchie"] }) : null] }), total === 0 ? (_jsx(Text, { color: "yellow", wrap: "truncate-end", children: isSpot ? 'nessuna sessione libera' : 'nessuna sessione legata a questa task' })) : (sessions.map((s) => {
+                const sel = s.sessionId === selectedId;
+                return (_jsxs(Text, { inverse: sel && focused, bold: sel && !focused, wrap: "truncate-end", children: [sel ? '▶ ' : '  ', isSpot ? _jsx(Text, { dimColor: true, children: "\u25CB" }) : _jsx(Text, { color: "green", children: "\uD83D\uDD17" }), ' ', truncate(s.title, 44), ' ', _jsxs(Text, { dimColor: true, children: ["\u00B7 ", s.gitBranch || '-', " \u00B7 ", relTime(s.ts)] })] }, s.sessionId));
+            }))] }));
+}
+function DetailPane({ detail }) {
+    const meta = META_KEYS.map((k) => detail.fields[k])
+        .filter(Boolean)
+        .join('  ·  ');
+    const commit = detail.fields['Last tracked commit'];
+    return (_jsxs(Box, { flexDirection: "column", marginTop: 1, borderStyle: "single", borderColor: "gray", paddingX: 1, children: [_jsx(Text, { bold: true, children: detail.title || detail.id }), meta ? _jsx(Text, { dimColor: true, children: meta }) : null, detail.description ? _jsx(Text, { wrap: "wrap", children: truncate(detail.description, 300) }) : null, commit ? _jsxs(Text, { dimColor: true, children: ["\u21B3 ", commit] }) : null] }));
+}
+const cwd = process.cwd();
+render(_jsx(Deck, { cwd: cwd, tasksPath: resolveTasksPath(cwd), tasksDir: resolveTasksDir(cwd) }));

package/dist/sessions.js

@@ -0,0 +1,158 @@
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, join } from 'node:path';
+// CC codifica la project dir sostituendo ogni char non-alfanumerico con '-'
+// (verificato: `/home/lamemind/cc-host` → `-home-lamemind-cc-host`). È LOSSY
+// (un '-' nel path e un '/' collassano nello stesso char) → il forward è
+// deterministico ma non reversibile; per questo filtriamo comunque per cwd.
+export function projectDirName(projectRoot) {
+    return projectRoot.replace(/[^a-zA-Z0-9]/g, '-');
+}
+function claudeProjectsRoot() {
+    return join(homedir(), '.claude', 'projects');
+}
+// Collassa whitespace/newline e strippa i tag XML-ish dei wrapper comando CC
+// (`<command-name>`, `<local-command-*>`, …) per una preview leggibile.
+function cleanPreview(s) {
+    return s
+        .replace(/<[^>]+>/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+function extractUserText(message) {
+    if (!message || typeof message !== 'object')
+        return '';
+    const content = message.content;
+    if (typeof content === 'string')
+        return cleanPreview(content);
+    if (Array.isArray(content)) {
+        for (const block of content) {
+            if (block &&
+                typeof block === 'object' &&
+                block.type === 'text' &&
+                typeof block.text === 'string') {
+                const t = cleanPreview(block.text);
+                if (t)
+                    return t;
+            }
+        }
+    }
+    return '';
+}
+// Cache mtime-keyed: re-parse solo i file cambiati. Steady-state di una TUI che
+// poll-a resta economico anche con decine di sessioni multi-MB. Lo stato vive
+// dentro l'adapter così l'invariante "unico modulo che tocca lo store" regge.
+const cache = new Map();
+function parseSessionFile(path, mtime) {
+    let content;
+    try {
+        content = readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    let sessionId = basename(path).replace(/\.jsonl$/, '');
+    let cwd = '';
+    let gitBranch = '';
+    let parentUuid = null;
+    let customTitle = '';
+    let firstUserText = '';
+    for (const line of content.split('\n')) {
+        if (!line.trim())
+            continue;
+        let d;
+        try {
+            d = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (typeof d.sessionId === 'string' && d.sessionId)
+            sessionId = d.sessionId;
+        if (!cwd && typeof d.cwd === 'string' && d.cwd)
+            cwd = d.cwd;
+        if (!gitBranch && typeof d.gitBranch === 'string' && d.gitBranch)
+            gitBranch = d.gitBranch;
+        if (parentUuid === null && typeof d.parentUuid === 'string' && d.parentUuid) {
+            parentUuid = d.parentUuid;
+        }
+        if (typeof d.customTitle === 'string' && d.customTitle)
+            customTitle = d.customTitle; // last-wins
+        if (!firstUserText && d.type === 'user') {
+            const t = extractUserText(d.message);
+            if (t)
+                firstUserText = t;
+        }
+    }
+    if (!cwd)
+        return null; // nessuna riga con cwd → non è una sessione di progetto valida
+    return {
+        sessionId,
+        cwd,
+        gitBranch,
+        parentUuid,
+        title: customTitle || firstUserText || '(senza titolo)',
+        ts: mtime,
+        path,
+    };
+}
+// Discovery read-only delle sessioni del SOLO progetto corrente (D2 preflight
+// T27): legge la project dir calcolata dal forward-transform, filtra per cwd
+// (difesa contro le collisioni lossy del naming), ordina per ts desc.
+export function discoverProjectSessions(projectRoot) {
+    const dir = join(claudeProjectsRoot(), projectDirName(projectRoot));
+    let files;
+    try {
+        files = readdirSync(dir).filter((f) => f.endsWith('.jsonl'));
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    const seen = new Set();
+    for (const f of files) {
+        const path = join(dir, f);
+        seen.add(path);
+        let mtime;
+        try {
+            mtime = statSync(path).mtimeMs;
+        }
+        catch {
+            continue;
+        }
+        const cached = cache.get(path);
+        let session;
+        if (cached && cached.mtime === mtime) {
+            session = cached.session;
+        }
+        else {
+            session = parseSessionFile(path, mtime);
+            cache.set(path, { mtime, session });
+        }
+        if (session && (session.cwd === projectRoot || session.cwd.startsWith(projectRoot + '/'))) {
+            out.push(session);
+        }
+    }
+    for (const key of cache.keys())
+        if (!seen.has(key))
+            cache.delete(key);
+    out.sort((a, b) => b.ts - a.ts);
+    return out;
+}
+// Raggruppa per gitBranch (D2: group-by-branch nel progetto corrente). Ordine
+// dei gruppi = sessione più recente nel gruppo (desc); dentro il gruppo resta
+// l'ordine ts desc ereditato dall'input.
+export function groupByBranch(sessions) {
+    const map = new Map();
+    for (const s of sessions) {
+        const branch = s.gitBranch || '(no branch)';
+        const arr = map.get(branch);
+        if (arr)
+            arr.push(s);
+        else
+            map.set(branch, [s]);
+    }
+    return [...map.entries()]
+        .map(([branch, arr]) => ({ branch, sessions: arr }))
+        .sort((a, b) => b.sessions[0].ts - a.sessions[0].ts);
+}

package/dist/task-index.js

@@ -0,0 +1,46 @@
+import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+// SIDECAR sessionId ↔ taskId (T27).
+//
+// Lo store JSONL di CC NON registra LOOM_TASK/taskId: la classificazione
+// spot vs scoped non può derivare dal transcript. La verità è QUESTO indice,
+// che il deck popola allo spawn — quando pinna `--session-id <uuid>` (D1
+// preflight) il sessionId è già noto, quindi il binding è deterministico.
+//
+// Store (D3 preflight): project-local `<root>/.claude/loom/session-tasks.jsonl`,
+// JSONL append-only. Append (non read-modify-write) = concurrency-safe fra
+// spawn concorrenti; last-wins in lettura copre eventuali re-pin.
+export function taskIndexPath(projectRoot) {
+    return join(projectRoot, '.claude', 'loom', 'session-tasks.jsonl');
+}
+export function appendTaskBinding(projectRoot, sessionId, taskId) {
+    const path = taskIndexPath(projectRoot);
+    mkdirSync(dirname(path), { recursive: true });
+    const record = { sessionId, taskId, ts: new Date().toISOString() };
+    appendFileSync(path, JSON.stringify(record) + '\n');
+}
+// sessionId → taskId, last-wins (un re-pin dello stesso sessionId sovrascrive).
+export function loadTaskBindings(projectRoot) {
+    const bindings = new Map();
+    let content;
+    try {
+        content = readFileSync(taskIndexPath(projectRoot), 'utf8');
+    }
+    catch {
+        return bindings;
+    }
+    for (const line of content.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            const d = JSON.parse(line);
+            if (typeof d.sessionId === 'string' && typeof d.taskId === 'string') {
+                bindings.set(d.sessionId, d.taskId);
+            }
+        }
+        catch {
+            // riga corrotta → skip
+        }
+    }
+    return bindings;
+}

package/dist/tasks.js

@@ -0,0 +1,100 @@
+import { readFileSync, readdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+// D1 (preflight T20): default docs/tasks.md, override della docs-root via env
+// LOOM_DECK_DOCS_ROOT (es. questo progetto usa `runtime`). No auto-detect.
+export function resolveTasksPath(cwd = process.cwd()) {
+    const docsRoot = process.env.LOOM_DECK_DOCS_ROOT || 'docs';
+    return join(cwd, docsRoot, 'tasks.md');
+}
+// I task file vivono in `<docsRoot>/tasks/` — sibling di tasks.md. Derivo la
+// dir dallo stesso path per rispettare l'override LOOM_DECK_DOCS_ROOT.
+export function resolveTasksDir(cwd = process.cwd()) {
+    return join(dirname(resolveTasksPath(cwd)), 'tasks');
+}
+// Estrae le righe `| Tnn | Pri | K | Prog | Task |` della Tasks Overview.
+// Il prefisso task è `T` (contratto plugin); le doc-task `D{N}` e le righe
+// header/separatore non matchano `^T\d+$` → scartate. deck-run agisce solo
+// su task T (run-task), quindi le D non hanno azione qui.
+export function parseTasks(content) {
+    const tasks = [];
+    for (const line of content.split('\n')) {
+        const t = line.trim();
+        if (!t.startsWith('|'))
+            continue;
+        const cells = t.split('|').map((c) => c.trim());
+        // cells[0] = '' (prima del primo |), cells[last] = '' (dopo l'ultimo |)
+        const id = cells[1];
+        if (!/^T\d+$/.test(id))
+            continue;
+        // Colonne overview: | ID | Pri | K | Prog | Task | → cells[2]=Pri (icona
+        // priorità), cells[4]=Prog. K (Kind, cells[3]) non serve al deck.
+        const pri = cells[2] ?? '';
+        const prog = cells[4] ?? '';
+        // desc = colonna finale; join per resistere a eventuali `|` nella descrizione.
+        const desc = cells.slice(5, -1).join('|').trim();
+        tasks.push({ id, pri, prog, desc });
+    }
+    return tasks;
+}
+export function loadTasks(path) {
+    return parseTasks(readFileSync(path, 'utf8'));
+}
+// ID → path del task file: `<id>-<slug>.md` nella tasks dir. Il dash dopo l'ID
+// disambigua i prefissi (`T20-` non matcha `T2-…`). Se più file matchano, primo
+// in ordine. `null` se la dir non è leggibile o nessun file matcha.
+export function findTaskFile(dir, id) {
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return null;
+    }
+    const prefix = `${id}-`;
+    const match = entries
+        .filter((f) => f.startsWith(prefix) && f.endsWith('.md'))
+        .sort()[0];
+    return match ? join(dir, match) : null;
+}
+// Estrae title (H1, `Task:` prefix strippato), bullet header e blocco
+// `## Description`. First-match-wins per chiave: se un campo compare due volte
+// (es. T15 ha una riga Progress `yyyy-MM-dd` residuo template nel body) vince la
+// prima — quella dell'header. La description si ferma al successivo `## `.
+export function parseTaskDetail(id, content) {
+    let title = '';
+    const fields = {};
+    const descLines = [];
+    let inDesc = false;
+    for (const line of content.split('\n')) {
+        if (!title && line.startsWith('# ')) {
+            title = line.replace(/^#\s+/, '').replace(/^Task:\s*/, '').trim();
+            continue;
+        }
+        if (line.startsWith('## ')) {
+            inDesc = /^##\s+Description\b/.test(line);
+            continue;
+        }
+        if (inDesc) {
+            descLines.push(line);
+            continue;
+        }
+        const f = line.match(/^-\s*\*\*(.+?)\*\*:\s*(.*)$/);
+        if (f) {
+            const key = f[1].trim();
+            if (!(key in fields))
+                fields[key] = f[2].trim();
+        }
+    }
+    return { id, title, fields, description: descLines.join('\n').trim() };
+}
+export function loadTaskDetail(dir, id) {
+    const path = findTaskFile(dir, id);
+    if (!path)
+        return null;
+    try {
+        return parseTaskDetail(id, readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@lamemind/loom-deck",
+  "version": "0.5.0",
+  "description": "Deck TUI Ink per-progetto della famiglia loom: legge tasks.md e spawna sessioni Claude Code bound via LOOM_TASK",
+  "type": "module",
+  "bin": {
+    "loom-deck": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "scripts"
+  ],
+  "scripts": {
+    "dev": "tsx src/cli.tsx",
+    "build": "tsc",
+    "start": "node dist/cli.js",
+    "prepare": "tsc"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lamemind/loom-deck.git"
+  },
+  "homepage": "https://github.com/lamemind/loom-deck#readme",
+  "bugs": {
+    "url": "https://github.com/lamemind/loom-deck/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "loom",
+    "ink",
+    "tui",
+    "deck",
+    "claude-code"
+  ],
+  "author": "lamemind",
+  "license": "MIT",
+  "dependencies": {
+    "ink": "^5.1.0",
+    "react": "^18.3.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.0",
+    "@types/react": "^18.3.12",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.3"
+  }
+}

package/scripts/deck-run

@@ -0,0 +1,125 @@
+#!/usr/bin/env bash
+#
+# deck-run <TaskID> — spike ① spawn primitive (UI-agnostico) di loom-deck.
+#
+# Apre una tab Ptyxis nella window ATTIVA (quella col focus = il deck) e vi
+# avvia una sessione Claude Code già bound alla task via LOOM_TASK, dritta sul
+# prompt iniziale (default: prompt diretto "recap stato task <TaskID>" — no skill,
+# solo recap → più controllo). Riusabile identico da TUI (Ink) e da web.
+#
+# Modalità spawn (LOOM_DECK_SPAWN_MODE):
+#   inline   → ptyxis --tab -- <cmd>            (default)  comando inline, LOOM_TASK diretta, zero dconf
+#   profile  → ptyxis --tab-with-profile=<UUID>            riusa il profilo, riscrive il custom-command via dconf
+#
+# La scelta fra le due è la Decisione aperta §9 della proposta: la modalità
+# "inline" è il default perché non muta stato dconf condiviso. Vedi la nota
+# di decisione nella task folder di T18.
+#
+# Env:
+#   LOOM_DECK_SPAWN_MODE   inline|profile          (default: inline)
+#   LOOM_DECK_PROFILE_UUID UUID profilo Ptyxis     (default: cc-host)
+#   LOOM_DECK_WORKDIR      dir di lavoro della tab (default: $PWD)
+#   LOOM_DECK_ENTER_PROMPT prompt iniziale sessione, {TASK}=TaskID (default: "recap stato task <TaskID>")
+#   LOOM_DECK_INTAB_CMD    override comando in-tab (default: la sessione CC; usato per i test)
+#
+set -euo pipefail
+
+TASK=""
+SESSION_ID=""
+# Positional <TaskID> + flag opzionale --session-id <uuid> (T27): il deck genera
+# l'UUID e lo pinna così il binding sidecar sessionId↔taskId è deterministico.
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --session-id)
+      SESSION_ID="${2:-}"; shift 2 ;;
+    --session-id=*)
+      SESSION_ID="${1#*=}"; shift ;;
+    *)
+      if [[ -z "$TASK" ]]; then TASK="$1"; shift
+      else echo "argomento inatteso: '$1'" >&2; exit 2; fi ;;
+  esac
+done
+
+if [[ -z "$TASK" ]]; then
+  echo "uso: deck-run <TaskID> [--session-id <uuid>]   (es. deck-run T18)" >&2
+  exit 2
+fi
+
+MODE="${LOOM_DECK_SPAWN_MODE:-inline}"
+PROFILE_UUID="${LOOM_DECK_PROFILE_UUID:-5a36ae48df1c4d4882f43060e3e59656}"
+WORKDIR="${LOOM_DECK_WORKDIR:-$PWD}"
+
+# ── Titolo tab = label standard loom (matchabile da compass) ──────────────────
+# compass matcha le finestre con `window.title.includes(project.label)`, dove la
+# label è DERIVATA dal contratto committato .claude/loom-works.json:
+# `{emoji} {owner} {name}` → es. "🧵 LOCAL loom-works". Un titolo "cc <task>"
+# non contiene la label → finestra ORFANA (progetto appare spento anche mentre ci
+# lavori dentro). Deriviamo la label dal file e la usiamo come titolo, con
+# suffisso "· <task>" per restare distinguibili fra più tab claude (il suffisso
+# non rompe il match: è .includes, non equals — stesso pattern del "· deck").
+# Fallback su "cc <task>" se manca il file o jq (progetto non loom-registered).
+_find_project_root() {  # <start-dir> → dir con .claude/loom-works.json, o vuoto
+  local d="${1%/}"
+  while [[ -n "$d" && "$d" != "/" ]]; do
+    [[ -f "$d/.claude/loom-works.json" ]] && { printf '%s\n' "$d"; return 0; }
+    d="$(dirname "$d")"
+  done
+  [[ -f "/.claude/loom-works.json" ]] && { printf '/\n'; return 0; }
+  return 1
+}
+
+TITLE="cc ${TASK}"
+if command -v jq >/dev/null 2>&1; then
+  _proot="$(_find_project_root "$WORKDIR" || true)"
+  if [[ -n "${_proot:-}" ]]; then
+    _label="$(jq -r 'if (.emoji and .owner and .name)
+                     then "\(.emoji) \(.owner) \(.name)" else empty end' \
+              "${_proot}/.claude/loom-works.json" 2>/dev/null || true)"
+    [[ -n "${_label:-}" ]] && TITLE="${_label} · ${TASK}"
+  fi
+fi
+
+# --session-id per la tab: pinna il sessionId della sessione CC (vuoto → CC ne
+# genera uno). Lo spazio finale tiene la concatenazione pulita quando è assente.
+SID_FLAG=""
+[[ -n "$SESSION_ID" ]] && SID_FLAG="--session-id ${SESSION_ID} "
+
+# Prompt iniziale della sessione. Default: prompt DIRETTO (no skill) che chiede
+# a Claude un recap dello stato della task — l'utente rivede/steera prima di
+# lanciare (= più controllo), nessuna esecuzione automatica. Override completo via
+# LOOM_DECK_ENTER_PROMPT, con placeholder {TASK} rimpiazzato dal TaskID. Vincolo: il
+# template NON deve contenere apici singoli (viaggia dentro '...' nel comando in-tab).
+# NB: il default NON può stare nel `${VAR:-...}` perché conterrebbe `{TASK}` e la sua
+# `}` chiuderebbe in anticipo l'espansione → if/else esplicito (default interpola
+# ${TASK} diretto; il placeholder {TASK} vale solo per il valore dell'override).
+if [[ -n "${LOOM_DECK_ENTER_PROMPT:-}" ]]; then
+  PROMPT="${LOOM_DECK_ENTER_PROMPT//\{TASK\}/${TASK}}"
+else
+  PROMPT="recap stato task ${TASK}"
+fi
+
+# Comando eseguito dentro la tab: bind LOOM_TASK per la sessione, avvia CC sul PROMPT.
+# `--name '<TITLE>'` = canale AUTORITATIVO del terminal-title (Ptyxis -T è solo il
+# titolo iniziale, prima che CC parta): CC lo setta e nomina anche la sessione nel
+# picker. Override-abile via LOOM_DECK_INTAB_CMD per i test empirici (probe non-CC).
+IN_TAB_CMD="${LOOM_DECK_INTAB_CMD:-LOOM_TASK=${TASK} claude --name '${TITLE}' ${SID_FLAG}'${PROMPT}'}"
+
+case "$MODE" in
+  inline)
+    # --tab: tab nella window attiva. -- <cmd>: comando inline nella tab.
+    # LOOM_TASK viaggia dentro il comando → nessuna scrittura dconf.
+    exec ptyxis --tab -d "$WORKDIR" -T "${TITLE}" -- bash -lc "$IN_TAB_CMD"
+    ;;
+  profile)
+    # --tab-with-profile: riusa il profilo (custom-command FISSO) → per iniettare
+    # LOOM_TASK+task va riscritto il custom-command al volo via dconf (stato condiviso).
+    dpath="/org/gnome/Ptyxis/Profiles/${PROFILE_UUID}/"
+    dconf write "${dpath}use-custom-command" true
+    dconf write "${dpath}custom-command" "'bash -lc \"${IN_TAB_CMD//\"/\\\"}\"'"
+    exec ptyxis --tab-with-profile="$PROFILE_UUID" -d "$WORKDIR" -T "${TITLE}"
+    ;;
+  *)
+    echo "LOOM_DECK_SPAWN_MODE ignoto: '$MODE' (usa 'inline' o 'profile')" >&2
+    exit 2
+    ;;
+esac