@lamemind/loom-deck 0.11.0 → 0.13.0

package/README.md

@@ -62,6 +62,7 @@ Assegnazioni correnti:
 | modale | `E` | edit priorità/stato della task selezionata (salva + commit) |
 | modale | `S` | sort chain |
 | modale | `F` | filtri |
+| immediata | `f` | **forka** la sessione selezionata (solo col focus sul pane Sessions) |
 | immediata | `t` | terminale @project-root (surface standard launch) |
 | immediata | `c` | sessione Claude **nuda**: nessuna task, nessun prompt iniziale |
 | immediata | `w` | salva la vista corrente su disco |
@@ -77,7 +78,30 @@ sono configurate ma non raggiungibili (e la legenda lo dice).
 
 `t` e `c` sono gemelle: entrambe aprono una surface del cappello nella stessa
 finestra Ptyxis, senza passare da un modale. `c` (minuscola, azione) e `C`
-(maiuscola, modale create-task) restano distinte per la regola sopra.
+(maiuscola, modale create-task) restano distinte per la regola sopra — così come
+`f` (fork) e `F` (filtri).
+
+### `f` — forkare una conversazione
+
+Il fork rama la sessione selezionata: `claude --resume <origine> --fork-session`
+apre un **sessionId nuovo** con il transcript copiato, lasciando l'origine
+intatta. Serve quando vuoi ripartire da un certo stato senza perdere il ramo
+originale — e siccome i due id sono distinti, non esistono mai due processi che
+scrivono lo stesso file (il vincolo *single-writer* dello store di Claude Code).
+
+Il nuovo id lo genera il deck e lo pinna con `--session-id`, per due ragioni:
+
+- il ramo **eredita la task** dell'origine (senza id noto in anticipo il fork
+  di una sessione scoped comparirebbe come spot);
+- il **lineage** finisce nel sidecar `.claude/loom/session-tasks.jsonl` come
+  campo `forkOf`. Serve perché il transcript del fork **non nomina** la sessione
+  d'origine da nessuna parte: è una copia verbatim (stessi uuid dei messaggi) e
+  `parentUuid` incatena i messaggi dentro un transcript, non le sessioni fra
+  loro. Senza quel record un ramo sarebbe una riga gemella dell'originale, di
+  cui eredita anche il titolo.
+
+Un ramo si riconosce dal marker `⑂` nella lista e dalla riga `⑂ da <id>` nel
+pannello di dettaglio; la sua tab Ptyxis titola `<label> · <task> · fork`.
 
 > **Nota di migrazione (0.6.0)**: `c` → **`C`** per creare una task, e le voci
 > `codium`/`idea` non hanno più una lettera dedicata (erano `C`/`I` hardcoded):

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { render, Box, Text, useApp, useInput, useStdout } from 'ink';
-import { useState, useEffect, useMemo } from 'react';
+import { useState, useEffect, useMemo, useRef } from 'react';
 import { spawn } from 'node:child_process';
 import { statSync } from 'node:fs';
 import { randomUUID } from 'node:crypto';
@@ -9,7 +9,8 @@ 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';
+import { appendPin, appendSessionRecord, appendTaskBinding, loadSessionIndex, } from './task-index.js';
+import { assembleSessionList, firstSelectableId, moveSelection, rowIndexOf, selectedSession, } from './session-list.js';
 import { launchLegend, loadIdentity, loadLaunch } from './config.js';
 import { layoutBudget, normalizeEmoji, windowRange, wrapLines, } from './viewport.js';
 import { applyView, cycleSort, describeSort, priName, progName, toggleHidden, PRI_ENTRIES, PROG_ENTRIES, } from './view.js';
@@ -63,6 +64,27 @@ function spawnDeckResume(taskId, cwd, sessionId) {
     child.unref();
     return child;
 }
+// T28 — FORK: `deck-run <task|--no-task> --resume <origine> --fork --session-id
+// <nuovo>`. Variante del resume, non una terza forma: cambia solo che CC apre un
+// id nuovo (`--fork-session`) invece di riprendere a scrivere sull'origine —
+// due writer sullo stesso JSONL non esistono mai, che è l'intero punto del fork.
+// Il nuovo id lo genera il DECK e lo pinna, come in spawnDeck: è l'unico modo di
+// conoscerlo prima che la sessione esista, e senza conoscerlo non si possono
+// scrivere né il binding task né il record di lineage (il transcript del fork
+// non nomina da nessuna parte la sessione d'origine).
+function spawnDeckFork(taskId, cwd, originId, newId) {
+    const args = [
+        ...(taskId ? [taskId] : ['--no-task']),
+        '--resume',
+        originId,
+        '--fork',
+        '--session-id',
+        newId,
+    ];
+    const child = spawn(DECK_RUN, args, { cwd, detached: true, stdio: 'ignore' });
+    child.unref();
+    return child;
+}
 // T42 — sessione Claude NUDA: nessuna task, nessun prompt iniziale, nessun
 // sessionId pinnato (quindi nessuna entry nel sidecar session-tasks.jsonl: senza
 // task non c'è nulla da legare). Funzione separata e non un parametro opzionale
@@ -240,33 +262,48 @@ function useSessions(projectRoot) {
     const [state, setState] = useState({
         sessions: [],
         bindings: new Map(),
+        forkOf: new Map(),
+        pinned: new Map(),
     });
+    // T50 — pin/unpin scrive il sidecar e vuole feedback IMMEDIATO, non al
+    // prossimo tick del poll (1.5s): la reload è esposta via ref così il toggle la
+    // richiama senza risottoscrivere l'intervallo.
+    const reloadRef = useRef(() => { });
     useEffect(() => {
         let lastSig = '';
         const reload = () => {
             let sessions;
-            let bindings;
+            let index;
             try {
                 sessions = discoverProjectSessions(projectRoot);
-                bindings = loadTaskBindings(projectRoot);
+                index = loadSessionIndex(projectRoot);
             }
             catch {
                 sessions = [];
-                bindings = new Map();
+                index = { bindings: new Map(), forkOf: new Map(), pinned: new Map() };
             }
+            const { bindings, forkOf, pinned } = index;
+            // La signature copre anche fork e pin: un record di lineage o un toggle di
+            // pin appena scritto cambia la lista renderizzata, quindi deve forzare il
+            // re-render come farebbe un binding nuovo.
             const sig = sessions.map((s) => `${s.sessionId}:${s.ts}`).join('|') +
                 '#' +
-                [...bindings.entries()].map(([k, v]) => `${k}=${v}`).sort().join(',');
+                [...bindings.entries()].map(([k, v]) => `${k}=${v}`).sort().join(',') +
+                '#' +
+                [...forkOf.entries()].map(([k, v]) => `${k}<${v}`).sort().join(',') +
+                '#' +
+                [...pinned.entries()].map(([k, v]) => `${k}@${v}`).sort().join(',');
             if (sig === lastSig)
                 return;
             lastSig = sig;
-            setState({ sessions, bindings });
+            setState({ sessions, bindings, forkOf, pinned });
         };
+        reloadRef.current = reload;
         reload();
         const id = setInterval(reload, POLL_MS);
         return () => clearInterval(id);
     }, [projectRoot]);
-    return state;
+    return { ...state, reload: () => reloadRef.current() };
 }
 // 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,
@@ -302,6 +339,13 @@ const forceEmojiWidth = normalizeEmoji;
 // larghi 1 e restano intatti.
 const CARET = normalizeEmoji('▶ ');
 const CARET_OFF = '  ';
+// T50 — glifo warning della riga pin-stale: BMP largo 2 senza VS16 → va timbrato
+// (come CARET), altrimenti la riga slitta di una colonna.
+const WARN = normalizeEmoji('⚠');
+// T50 — separatore leggero fra blocco pinnate e contestuali. `─` (box-drawing) è
+// largo 1 sia per string-width sia per il terminale → nessun timbro. Corto +
+// wrap="truncate-end" così non va mai a capo nel pane al 50%.
+const SESSION_SEP = '─'.repeat(16);
 // Normalizza il marker Done per il display. `✔` (U+2714) è text-presentation-
 // default: string-width — quindi Ink, sia per il layout sia per il troncamento —
 // lo misura 2 (rispetta il VS16 di `✔️`), ma VTE/Ptyxis lo disegna largo 1
@@ -346,14 +390,17 @@ 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 { sessions, bindings, forkOf, pinned, 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. `null` = la
     // riga meta "spot", sempre in testa alla lista.
     const [selId, setSelId] = useState(null);
-    const [selSession, setSelSession] = useState(0);
+    // 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);
     const [note, setNote] = useState('');
     // Modali: catturano i tasti e corto-circuitano la navigazione normale.
     // T30 create · T39 sort/filter.
@@ -396,12 +443,18 @@ function Deck({ cwd, tasksPath, tasksDir }) {
     }
     // 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) => {
+    // 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(() => 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;
+    }), [sessions, bindings, selectedTaskId]);
+    // T50 — lista a due gruppi: pinnate (sempre, in cima) + separatore +
+    // contestuali. Dedup, cap solo sulle contestuali, righe stale per le pinnate
+    // orfane. Core PURO in session-list.ts (testabile senza Ink).
+    const assembled = useMemo(() => assembleSessionList(childSessions, sessions, pinned, MAX_SESSIONS), [childSessions, sessions, pinned]);
+    const sessionRows = assembled.rows;
+    const selSessionObj = selectedSession(sessionRows, selSessionId);
     // 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.
@@ -410,13 +463,15 @@ function Deck({ cwd, tasksPath, tasksDir }) {
             setSelId(viewTasks[0]?.id ?? null);
         }
     }, [viewTasks, selId]);
-    // Cambio padre → riparti dalla prima sessione figlia.
-    useEffect(() => {
-        setSelSession(0);
-    }, [selId]);
+    // 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(() => {
-        setSelSession((s) => Math.min(s, Math.max(0, visibleSessions.length - 1)));
-    }, [visibleSessions.length]);
+        if (rowIndexOf(sessionRows, selSessionId) < 0) {
+            setSelSessionId(firstSelectableId(sessionRows));
+        }
+    }, [sessionRows, selSessionId]);
     // 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
@@ -640,13 +695,13 @@ function Deck({ cwd, tasksPath, tasksDir }) {
             if (focus === 'tasks')
                 moveTaskSel(-1);
             else
-                setSelSession((i) => Math.max(0, i - 1));
+                setSelSessionId((id) => moveSelection(sessionRows, id, -1));
         }
         else if (key.downArrow) {
             if (focus === 'tasks')
                 moveTaskSel(1);
             else
-                setSelSession((i) => Math.min(visibleSessions.length - 1, i + 1));
+                setSelSessionId((id) => moveSelection(sessionRows, id, 1));
         }
         else if (key.return) {
             if (focus === 'tasks') {
@@ -669,9 +724,9 @@ function Deck({ cwd, tasksPath, tasksDir }) {
             else {
                 // T49 — ⏎ su una sessione = resume in nuova tab. Il binding si rilegge
                 // dal sidecar (non dal padre selezionato): vale anche per le spot.
-                const s = visibleSessions[selSession];
+                const s = selSessionObj;
                 if (!s) {
-                    setNote('nessuna sessione da riprendere');
+                    setNote(selSessionId ? 'pin stale: transcript non più presente' : 'nessuna sessione da riprendere');
                 }
                 else {
                     const bound = bindings.get(s.sessionId) ?? null;
@@ -702,6 +757,56 @@ function Deck({ cwd, tasksPath, tasksDir }) {
             setNote('');
             setMode('filter');
         }
+        else if (input === 'f') {
+            // T28 — fork della sessione selezionata. Minuscola come `t`/`c` (T39):
+            // azione immediata, nessun modale — la `F` maiuscola resta ai filtri.
+            // Vive solo sul pane sessioni: il fork ha per oggetto una conversazione,
+            // e senza focus lì non ce n'è una selezionata su cui agire.
+            if (focus !== 'sessions') {
+                setNote('f → fork: seleziona una sessione (←→ per il pane)');
+            }
+            else {
+                const s = selSessionObj;
+                if (!s) {
+                    setNote(selSessionId ? 'f → pin stale: niente da forkare' : 'f → nessuna sessione da forkare');
+                }
+                else {
+                    // L'id del ramo nasce qui, prima dello spawn: pinnandolo posso
+                    // scrivere subito binding e lineage. Il binding task si eredita
+                    // dall'origine (un ramo appartiene alla stessa task), il lineage
+                    // registra la provenienza che il transcript non porta.
+                    const newId = randomUUID();
+                    const bound = bindings.get(s.sessionId) ?? null;
+                    appendSessionRecord(cwd, {
+                        sessionId: newId,
+                        ...(bound ? { taskId: bound } : {}),
+                        forkOf: s.sessionId,
+                    });
+                    const child = spawnDeckFork(bound, cwd, s.sessionId, newId);
+                    child.on('error', () => setNote(`⚠ fork fallito (${DECK_RUN})`));
+                    setNote(`⑂ fork ${s.sessionId.slice(0, 8)} → ${newId.slice(0, 8)}${bound ? ` (${bound})` : ' (spot)'}`);
+                }
+            }
+        }
+        else if (input === 'p') {
+            // T50 — pin/unpin della conversazione selezionata. Minuscola = azione
+            // immediata (convenzione T39), gemella di `f`: opera sulla riga
+            // selezionata del pane sessioni, quindi vive solo lì. Vale anche su una
+            // pinnata STALE (l'unico modo di spinnarla). Scrive il sidecar e ricarica
+            // subito, senza attendere il tick del poll.
+            if (focus !== 'sessions') {
+                setNote('p → pin: seleziona una sessione (←→ per il pane)');
+            }
+            else if (!selSessionId) {
+                setNote('p → nessuna sessione da pinnare');
+            }
+            else {
+                const isPinned = pinned.has(selSessionId);
+                appendPin(cwd, selSessionId, !isPinned);
+                reloadSessions();
+                setNote(`${isPinned ? 'unpin' : '📌 pin'} ${selSessionId.slice(0, 8)}`);
+            }
+        }
         else if (input === 't') {
             const title = identity ? `🖥️ ${identity.owner} ${identity.name} [term]` : null;
             const child = spawnTerminal(cwd, title);
@@ -742,11 +847,12 @@ function Deck({ cwd, tasksPath, tasksDir }) {
             exit();
         }
     });
-    const selSessionObj = visibleSessions[selSession] ?? null;
-    const selSessionId = selSessionObj?.sessionId;
     const parentLabel = isSpot ? 'spot' : selectedTaskId ?? '—';
     const canSpawn = focus === 'tasks' && !isSpot;
     const canResume = focus === 'sessions' && selSessionObj !== null;
+    // T50 — il pin agisce su qualunque riga selezionata (anche stale, per
+    // spinnarla); basta il focus sul pane e una selezione.
+    const canPin = focus === 'sessions' && selSessionId !== null;
     // Larghezza dal medesimo hook che dà l'altezza: dopo un resize la legenda si
     // ricalcola con lo stesso re-render che ridimensiona i pane.
     const legend = launchLegend(launch, columns);
@@ -774,20 +880,21 @@ function Deck({ cwd, tasksPath, tasksDir }) {
         sessionHasFirstPreview: canResume && Boolean(selSessionObj?.customTitle),
         sessionHasLastPreview: canResume && Boolean(selSessionObj?.lastReply),
     });
-    // Finestre di rendering. Le liste "logiche" (viewTasks, visibleSessions)
+    // Finestre di rendering. Le liste "logiche" (viewTasks, sessionRows)
     // restano intere: navigazione, selezione e spawn continuano a ragionare su
     // quelle, la finestra è solo ciò che finisce a schermo.
     const taskWin = windowRange(viewTasks.length, selIndex - 1, budget.taskRows);
     const windowTasks = viewTasks.slice(taskWin.start, taskWin.end);
-    const sessionWin = windowRange(visibleSessions.length, selSession, budget.sessionRows);
-    const windowSessions = visibleSessions.slice(sessionWin.start, sessionWin.end);
+    const selRowIndex = rowIndexOf(sessionRows, selSessionId);
+    const sessionWin = windowRange(sessionRows.length, selRowIndex, budget.sessionRows);
+    const windowRows = sessionRows.slice(sessionWin.start, sessionWin.end);
     // Sotto la soglia minima il layout a box non entra a nessun costo: si scende
     // a una riga sola. Perdere il deck per un terminale basso è meglio che
     // sporcare la cronologia del terminale a ogni poll.
     if (budget.compact) {
         return (_jsxs(Text, { wrap: "truncate-end", children: [_jsx(Text, { bold: true, color: "cyan", children: "loom-deck" }), _jsxs(Text, { dimColor: true, children: [' ', "\u00B7 ", viewTasks.length, " task \u00B7 sel ", selectedTaskId ?? 'spot', " \u00B7 terminale ", rows, "\u00D7", columns, ": troppo basso, allarga"] })] }));
     }
-    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, wrap: "truncate-end", children: ["nuova task \u00B7 ", _jsx(Text, { color: "yellow", children: "\u23CE" }), " crea \u00B7 ", _jsx(Text, { color: "yellow", children: "esc" }), " annulla"] })) : mode === 'sort' ? (_jsxs(Text, { dimColor: true, wrap: "truncate-end", children: ["sort \u00B7 ", _jsx(Text, { color: "yellow", children: "p" }), " pri ", _jsx(Text, { color: "yellow", children: "s" }), " stato", ' ', _jsx(Text, { color: "yellow", children: "i" }), " id (asc\u2192desc\u2192off) \u00B7 ", _jsx(Text, { color: "yellow", children: "\u23CE" }), " ok \u00B7", ' ', _jsx(Text, { color: "yellow", children: "esc" }), " annulla"] })) : mode === 'filter' ? (_jsxs(Text, { dimColor: true, wrap: "truncate-end", children: ["filtri \u00B7 ", _jsx(Text, { color: "yellow", children: "\u2191\u2193\u2190\u2192" }), " naviga \u00B7 ", _jsx(Text, { color: "yellow", children: "spazio" }), ' ', "mostra/nascondi \u00B7 ", _jsx(Text, { color: "yellow", children: "\u23CE" }), " ok \u00B7 ", _jsx(Text, { color: "yellow", children: "esc" }), " annulla"] })) : mode === 'edit' ? (_jsxs(Text, { dimColor: true, wrap: "truncate-end", children: ["edit \u00B7 ", _jsx(Text, { color: "yellow", children: "\u2191\u2193" }), " campo \u00B7 ", _jsx(Text, { color: "yellow", children: "\u2190\u2192" }), " valore \u00B7", ' ', _jsx(Text, { color: "yellow", children: "\u23CE" }), " salva+commit \u00B7 ", _jsx(Text, { color: "yellow", children: "esc" }), " annulla"] })) : (_jsxs(Text, { dimColor: true, wrap: "truncate-end", children: ["\u2191\u2193 naviga \u00B7 \u2190\u2192 pane \u00B7 \u23CE ", canSpawn ? 'spawn' : canResume ? 'resume' : '—', " \u00B7 C nuova \u00B7 E edit \u00B7 S sort \u00B7 F filtri \u00B7 w salva \u00B7 t term \u00B7 c claude \u00B7 q esci \u00B7 focus:", ' ', _jsx(Text, { color: "cyan", children: focus })] })), mode === 'normal' && launch.length > 0 ? (_jsxs(Text, { dimColor: true, wrap: "truncate-end", children: ["launch ", legend.shown, legend.overflow > 0 ? (_jsxs(Text, { color: "yellow", children: [" \u00B7 +", legend.overflow, " fuori riga"] })) : null, legend.unreachable > 0 ? (_jsxs(Text, { color: "yellow", children: [" \u00B7 ", legend.unreachable, " oltre la 9\u00AA (non raggiungibili)"] })) : null] })) : null, 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, mode === 'sort' ? _jsx(SortModal, { sort: view.sort }) : null, mode === 'filter' ? _jsx(FilterModal, { view: view, cursor: filterCursor }) : null, mode === 'edit' && edit && selTask ? (_jsx(EditModal, { id: selTask.id, draft: edit, row: editRow })) : null, _jsxs(Box, { flexDirection: "row", marginTop: 1, children: [_jsx(TasksPane, { tasks: windowTasks, filtered: viewTasks.length, total: tasks.length, hidden: hiddenTasks, view: view, selected: selIndex, spotCount: spotCount, childCount: childCount, focused: focus === 'tasks', loadError: loadError, detail: detail, windowStart: taskWin.start, above: taskWin.start, below: viewTasks.length - taskWin.end, detailLines: budget.detailLines, columns: columns }), _jsx(SessionsPane, { parentLabel: parentLabel, isSpot: isSpot, sessions: windowSessions, total: childSessions.length, hidden: hiddenSessions, selectedId: selSessionId, focused: focus === 'sessions', above: sessionWin.start, below: visibleSessions.length - sessionWin.end, detail: budget.sessionDetail ? selSessionObj : null, firstLines: budget.sessionFirstLines, lastLines: budget.sessionLastLines, columns: columns })] }), note ? _jsx(Text, { color: "green", wrap: "truncate-end", children: normalizeEmoji(note) }) : null] }));
+    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, wrap: "truncate-end", children: ["nuova task \u00B7 ", _jsx(Text, { color: "yellow", children: "\u23CE" }), " crea \u00B7 ", _jsx(Text, { color: "yellow", children: "esc" }), " annulla"] })) : mode === 'sort' ? (_jsxs(Text, { dimColor: true, wrap: "truncate-end", children: ["sort \u00B7 ", _jsx(Text, { color: "yellow", children: "p" }), " pri ", _jsx(Text, { color: "yellow", children: "s" }), " stato", ' ', _jsx(Text, { color: "yellow", children: "i" }), " id (asc\u2192desc\u2192off) \u00B7 ", _jsx(Text, { color: "yellow", children: "\u23CE" }), " ok \u00B7", ' ', _jsx(Text, { color: "yellow", children: "esc" }), " annulla"] })) : mode === 'filter' ? (_jsxs(Text, { dimColor: true, wrap: "truncate-end", children: ["filtri \u00B7 ", _jsx(Text, { color: "yellow", children: "\u2191\u2193\u2190\u2192" }), " naviga \u00B7 ", _jsx(Text, { color: "yellow", children: "spazio" }), ' ', "mostra/nascondi \u00B7 ", _jsx(Text, { color: "yellow", children: "\u23CE" }), " ok \u00B7 ", _jsx(Text, { color: "yellow", children: "esc" }), " annulla"] })) : mode === 'edit' ? (_jsxs(Text, { dimColor: true, wrap: "truncate-end", children: ["edit \u00B7 ", _jsx(Text, { color: "yellow", children: "\u2191\u2193" }), " campo \u00B7 ", _jsx(Text, { color: "yellow", children: "\u2190\u2192" }), " valore \u00B7", ' ', _jsx(Text, { color: "yellow", children: "\u23CE" }), " salva+commit \u00B7 ", _jsx(Text, { color: "yellow", children: "esc" }), " annulla"] })) : (_jsxs(Text, { dimColor: true, wrap: "truncate-end", children: ["\u2191\u2193 naviga \u00B7 \u2190\u2192 pane \u00B7 \u23CE ", canSpawn ? 'spawn' : canResume ? 'resume' : '—', canResume ? ' · f fork' : '', canPin ? ' · p pin' : '', " \u00B7 C nuova \u00B7 E edit \u00B7 S sort \u00B7 F filtri \u00B7 w salva \u00B7 t term \u00B7 c claude \u00B7 q esci \u00B7 focus:", ' ', _jsx(Text, { color: "cyan", children: focus })] })), mode === 'normal' && launch.length > 0 ? (_jsxs(Text, { dimColor: true, wrap: "truncate-end", children: ["launch ", legend.shown, legend.overflow > 0 ? (_jsxs(Text, { color: "yellow", children: [" \u00B7 +", legend.overflow, " fuori riga"] })) : null, legend.unreachable > 0 ? (_jsxs(Text, { color: "yellow", children: [" \u00B7 ", legend.unreachable, " oltre la 9\u00AA (non raggiungibili)"] })) : null] })) : null, 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, mode === 'sort' ? _jsx(SortModal, { sort: view.sort }) : null, mode === 'filter' ? _jsx(FilterModal, { view: view, cursor: filterCursor }) : null, mode === 'edit' && edit && selTask ? (_jsx(EditModal, { id: selTask.id, draft: edit, row: editRow })) : null, _jsxs(Box, { flexDirection: "row", marginTop: 1, children: [_jsx(TasksPane, { tasks: windowTasks, filtered: viewTasks.length, total: tasks.length, hidden: hiddenTasks, view: view, selected: selIndex, spotCount: spotCount, childCount: childCount, focused: focus === 'tasks', loadError: loadError, detail: detail, windowStart: taskWin.start, above: taskWin.start, below: viewTasks.length - taskWin.end, detailLines: budget.detailLines, columns: columns }), _jsx(SessionsPane, { parentLabel: parentLabel, isSpot: isSpot, rows: windowRows, total: assembled.pinnedCount + assembled.contextTotal, pinnedCount: assembled.pinnedCount, hidden: assembled.contextHidden, selectedId: selSessionId ?? undefined, focused: focus === 'sessions', above: sessionWin.start, below: sessionRows.length - sessionWin.end, detail: budget.sessionDetail ? selSessionObj : null, firstLines: budget.sessionFirstLines, lastLines: budget.sessionLastLines, columns: columns, forkOf: forkOf })] }), note ? _jsx(Text, { color: "green", wrap: "truncate-end", children: normalizeEmoji(note) }) : null] }));
 }
 const SORT_UI = { pri: 'pri', prog: 'stato', id: 'id' };
 // Modali resi IN FLUSSO (come l'input box di create), non in overlay assoluto:
@@ -832,11 +939,27 @@ function TasksPane({ tasks, filtered, total, hidden, view, selected, spotCount,
                 return (_jsxs(Text, { inverse: sel && focused, bold: sel && !focused, dimColor: !sel && isDone(task.prog), wrap: "truncate-end", children: [sel ? CARET : CARET_OFF, task.id, "  ", forceEmojiWidth(task.pri), "  ", displayProg(task.prog), "  ", task.desc, n > 0 ? ` (${n})` : ''] }, task.id));
             })), detail && detailLines > 0 ? (_jsx(DetailPane, { detail: detail, maxLines: detailLines, columns: columns })) : null] }));
 }
-function SessionsPane({ parentLabel, isSpot, sessions, total, hidden, selectedId, focused, above, below, detail, firstLines, lastLines, columns, }) {
-    return (_jsxs(Box, { flexDirection: "column", width: "50%", borderStyle: "single", borderColor: focused ? 'cyan' : 'gray', paddingX: 1, children: [_jsxs(Text, { bold: true, color: focused ? 'cyan' : undefined, wrap: "truncate-end", children: ["Sessions \u00B7 ", parentLabel, " (", total, ")", hidden > 0 ? _jsxs(Text, { dimColor: true, children: [" \u00B7 +", hidden, " pi\u00F9 vecchie"] }) : null, above > 0 ? _jsxs(Text, { dimColor: true, children: [" \u00B7 \u2191", above] }) : null, below > 0 ? _jsxs(Text, { dimColor: true, children: [" \u00B7 \u2193", below] }) : 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 ? CARET : CARET_OFF, 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));
-            })), detail ? (_jsx(SessionDetailPane, { s: detail, firstLines: firstLines, lastLines: lastLines, columns: columns })) : null] }));
+function SessionsPane({ parentLabel, isSpot, rows, total, pinnedCount, hidden, selectedId, focused, above, below, detail, firstLines, lastLines, columns, forkOf, }) {
+    return (_jsxs(Box, { flexDirection: "column", width: "50%", borderStyle: "single", borderColor: focused ? 'cyan' : 'gray', paddingX: 1, children: [_jsxs(Text, { bold: true, color: focused ? 'cyan' : undefined, wrap: "truncate-end", children: ["Sessions \u00B7 ", parentLabel, " (", total, ")", pinnedCount > 0 ? _jsxs(Text, { color: "yellow", children: [" \u00B7 \uD83D\uDCCC", pinnedCount] }) : null, hidden > 0 ? _jsxs(Text, { dimColor: true, children: [" \u00B7 +", hidden, " pi\u00F9 vecchie"] }) : null, above > 0 ? _jsxs(Text, { dimColor: true, children: [" \u00B7 \u2191", above] }) : null, below > 0 ? _jsxs(Text, { dimColor: true, children: [" \u00B7 \u2193", below] }) : null] }), total === 0 ? (_jsx(Text, { color: "yellow", wrap: "truncate-end", children: isSpot ? 'nessuna sessione libera' : 'nessuna sessione legata a questa task' })) : (rows.map((row, i) => {
+                // T50 — separatore leggero fra pinnate e contestuali: riga dim, non un
+                // box pesante (coerente con lo styling delle Done dimmate).
+                if (row.kind === 'separator') {
+                    return (_jsx(Text, { dimColor: true, wrap: "truncate-end", children: SESSION_SEP }, `sep${i}`));
+                }
+                const sel = row.sessionId === selectedId;
+                // T50 — pin stale: transcript sparito, nessuna Session da mostrare.
+                // Riga navigabile e spinnabile (`p`), marcata, mai un crash.
+                if (row.kind === 'pinned' && row.stale) {
+                    return (_jsxs(Text, { inverse: sel && focused, bold: sel && !focused, dimColor: true, wrap: "truncate-end", children: [sel ? CARET : CARET_OFF, _jsx(Text, { color: "yellow", children: WARN }), " pin stale", ' ', _jsx(Text, { dimColor: true, children: row.sessionId.slice(0, 8) })] }, row.sessionId));
+                }
+                const s = row.session; // non-stale → session presente
+                const isPinnedRow = row.kind === 'pinned';
+                // T28 — un ramo eredita il titolo dell'origine: senza marcatore le due
+                // righe sarebbero identiche a occhio. `⑂` sta PRIMA del titolo, dove
+                // la troncatura non arriva mai.
+                const forked = forkOf.has(s.sessionId);
+                return (_jsxs(Text, { inverse: sel && focused, bold: sel && !focused, wrap: "truncate-end", children: [sel ? CARET : CARET_OFF, isPinnedRow ? (_jsx(Text, { color: "yellow", children: "\uD83D\uDCCC" })) : isSpot ? (_jsx(Text, { dimColor: true, children: "\u25CB" })) : (_jsx(Text, { color: "green", children: "\uD83D\uDD17" })), ' ', forked ? _jsx(Text, { color: "magenta", children: "\u2442 " }) : null, truncate(s.title, forked ? 42 : 44), ' ', _jsxs(Text, { dimColor: true, children: ["\u00B7 ", s.gitBranch || '-', " \u00B7 ", relTime(s.ts)] })] }, s.sessionId));
+            })), detail ? (_jsx(SessionDetailPane, { s: detail, firstLines: firstLines, lastLines: lastLines, columns: columns, origin: forkOf.get(detail.sessionId) ?? null })) : null] }));
 }
 // T49 — detail pane della sessione selezionata (hover), gemello del DetailPane
 // task. Tutti i campi vengono dal parse già cached dell'adapter (mtime-keyed):
@@ -846,11 +969,11 @@ function SessionsPane({ parentLabel, isSpot, sessions, total, hidden, selectedId
 // — senza, il titolo È già il primo prompt e la riga lo duplicherebbe (D4
 // preflight). Le righe rese non superano mai il riservato dal budget
 // (`firstLines`/`lastLines`); renderne meno è sicuro (frame più corto).
-function SessionDetailPane({ s, firstLines, lastLines, columns, }) {
+function SessionDetailPane({ s, firstLines, lastLines, columns, origin, }) {
     const width = detailTextWidth(columns);
     const first = s.customTitle && firstLines > 0 ? wrapLines(s.firstPrompt, width, firstLines) : [];
     const last = s.lastReply && lastLines > 0 ? wrapLines(s.lastReply, width, lastLines) : [];
-    return (_jsxs(Box, { flexDirection: "column", marginTop: 1, borderStyle: "single", borderColor: "gray", paddingX: 1, children: [_jsx(Text, { bold: true, wrap: "truncate-end", children: s.title }), _jsxs(Text, { dimColor: true, wrap: "truncate-end", children: [fmtSize(s.sizeBytes), " \u00B7 ", s.turns, " turni \u00B7 ", fmtDateTime(s.ts)] }), first.map((line, i) => (_jsxs(Text, { dimColor: true, wrap: "truncate-end", children: [i === 0 ? '» ' : '  ', line] }, `f${i}`))), last.map((line, i) => (_jsxs(Text, { dimColor: true, wrap: "truncate-end", children: [i === 0 ? '« ' : '  ', line] }, `l${i}`)))] }));
+    return (_jsxs(Box, { flexDirection: "column", marginTop: 1, borderStyle: "single", borderColor: "gray", paddingX: 1, children: [_jsx(Text, { bold: true, wrap: "truncate-end", children: s.title }), _jsxs(Text, { dimColor: true, wrap: "truncate-end", children: [fmtSize(s.sizeBytes), " \u00B7 ", s.turns, " turni \u00B7 ", fmtDateTime(s.ts), origin ? ` · ⑂ da ${origin.slice(0, 8)}` : ''] }), first.map((line, i) => (_jsxs(Text, { dimColor: true, wrap: "truncate-end", children: [i === 0 ? '» ' : '  ', line] }, `f${i}`))), last.map((line, i) => (_jsxs(Text, { dimColor: true, wrap: "truncate-end", children: [i === 0 ? '« ' : '  ', line] }, `l${i}`)))] }));
 }
 /**
  * Righe non-wrappabili del dettaglio (titolo + meta + commit) e loro conteggio.

package/dist/session-list.js

@@ -0,0 +1,80 @@
+// T50 — Assemblaggio della lista sessioni a DUE gruppi: pinnate (sempre in
+// lista, in cima) + separatore + contestuali (figlie del parent selezionato).
+// Modulo PURO: nessun import da ink/react, nessun I/O → testabile senza terminale
+// (il pacchetto non ha infrastruttura TUI di test, solo unit sui core puri).
+//
+// Invarianti (decisioni congelate al preflight):
+//  - D2: dentro il blocco pinnate l'ordine è di PIN stabile (ultima pinnata in
+//    cima), dato dal rango del sidecar `session-tasks.jsonl` — non `ts desc`.
+//  - Dedup: una sessione sia pinnata sia contestuale compare SOLO fra le pinnate.
+//  - Cap: `maxContext` limita SOLO le contestuali; le pinnate sono esenti. Il
+//    conteggio delle troncate (`contextHidden`) resta esposto (non-silenzioso).
+//  - D3: una pinnata il cui transcript non esiste più è una riga STALE (session
+//    null), navigabile e spinnabile — non sparisce in silenzio.
+//  - Trap T39: la selezione è KEYED SU sessionId, non su indice posizionale. La
+//    lista è una vista trasformata (due gruppi + separatore): un indice grezzo
+//    identificherebbe la riga sbagliata dopo un pin/cambio-contesto.
+export function assembleSessionList(childSessions, allSessions, pinned, maxContext) {
+    // Le pinnate si risolvono contro TUTTE le sessioni del progetto, non solo le
+    // figlie del parent: una pinnata può appartenere a un'altra task. Assente
+    // dallo store → stale.
+    const byId = new Map(allSessions.map((s) => [s.sessionId, s]));
+    const pinnedIds = [...pinned.entries()]
+        .sort((a, b) => b[1] - a[1]) // rango desc → ultima pinnata in cima (D2)
+        .map(([id]) => id);
+    const pinnedRows = pinnedIds.map((id) => {
+        const session = byId.get(id) ?? null;
+        return { kind: 'pinned', sessionId: id, session, stale: session === null };
+    });
+    const pinnedSet = new Set(pinnedIds);
+    const dedupedContext = childSessions.filter((s) => !pinnedSet.has(s.sessionId));
+    const shownContext = dedupedContext.slice(0, Math.max(0, maxContext));
+    const contextRows = shownContext.map((s) => ({
+        kind: 'context',
+        sessionId: s.sessionId,
+        session: s,
+    }));
+    const rows = [...pinnedRows];
+    // Separatore SOLO fra due gruppi entrambi non vuoti: senza pinnate o senza
+    // contestuali non c'è confine da segnare.
+    if (pinnedRows.length > 0 && contextRows.length > 0)
+        rows.push({ kind: 'separator' });
+    rows.push(...contextRows);
+    return {
+        rows,
+        pinnedCount: pinnedRows.length,
+        contextTotal: dedupedContext.length,
+        contextHidden: dedupedContext.length - shownContext.length,
+    };
+}
+function isSelectable(r) {
+    return r.kind !== 'separator';
+}
+/** Primo id selezionabile (salta il separatore); null = lista senza righe. */
+export function firstSelectableId(rows) {
+    return rows.find(isSelectable)?.sessionId ?? null;
+}
+/** Indice della riga con quel sessionId nell'ARRAY COMPLETO (per il windowing);
+ *  -1 se assente o id null. Il separatore non ha id → mai matchato. */
+export function rowIndexOf(rows, sessionId) {
+    if (sessionId === null)
+        return -1;
+    return rows.findIndex((r) => isSelectable(r) && r.sessionId === sessionId);
+}
+/** Sposta la selezione di `delta` fra le sole righe selezionabili (attraversa il
+ *  separatore senza fermarcisi). Id perso → prima riga; lista vuota → null. */
+export function moveSelection(rows, currentId, delta) {
+    const selectable = rows.filter(isSelectable);
+    if (selectable.length === 0)
+        return null;
+    const cur = selectable.findIndex((r) => r.sessionId === currentId);
+    if (cur < 0)
+        return selectable[0].sessionId;
+    const next = Math.max(0, Math.min(selectable.length - 1, cur + delta));
+    return selectable[next].sessionId;
+}
+/** Session della riga selezionata; null se stale o nessuna selezione. */
+export function selectedSession(rows, sessionId) {
+    const r = rows.find((row) => isSelectable(row) && row.sessionId === sessionId);
+    return r && isSelectable(r) ? r.session : null;
+}

package/dist/task-index.js

@@ -1,46 +1,60 @@
 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) {
+export function appendSessionRecord(projectRoot, rec) {
     const path = taskIndexPath(projectRoot);
     mkdirSync(dirname(path), { recursive: true });
-    const record = { sessionId, taskId, ts: new Date().toISOString() };
-    appendFileSync(path, JSON.stringify(record) + '\n');
+    appendFileSync(path, JSON.stringify({ ...rec, ts: new Date().toISOString() }) + '\n');
+}
+export function appendTaskBinding(projectRoot, sessionId, taskId) {
+    appendSessionRecord(projectRoot, { sessionId, taskId });
+}
+/** T50 — pin/unpin (toggle): append immediato, il reader risolve last-wins. */
+export function appendPin(projectRoot, sessionId, pinned) {
+    appendSessionRecord(projectRoot, { sessionId, pinned });
 }
-// sessionId → taskId, last-wins (un re-pin dello stesso sessionId sovrascrive).
-export function loadTaskBindings(projectRoot) {
+// Una sola lettura del JSONL per entrambe le mappe: il deck poll-a l'indice a
+// ogni tick, leggere il file due volte raddoppierebbe l'I/O per nulla.
+// Last-wins per campo (un re-pin dello stesso sessionId sovrascrive), e i due
+// campi sono indipendenti — un record di solo `forkOf` non cancella un binding
+// task scritto prima per lo stesso sessionId.
+export function loadSessionIndex(projectRoot) {
     const bindings = new Map();
+    const forkOf = new Map();
+    const pinned = new Map();
     let content;
     try {
         content = readFileSync(taskIndexPath(projectRoot), 'utf8');
     }
     catch {
-        return bindings;
+        return { bindings, forkOf, pinned };
     }
+    let order = 0; // posizione crescente dei record pinned → rango di pin (D2)
     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') {
+            if (typeof d.sessionId !== 'string')
+                continue;
+            if (typeof d.taskId === 'string')
                 bindings.set(d.sessionId, d.taskId);
+            if (typeof d.forkOf === 'string')
+                forkOf.set(d.sessionId, d.forkOf);
+            // last-wins per campo: un `pinned:false` finale rimuove il pin, un
+            // `pinned:true` (ri)assegna il rango con la posizione corrente nel file.
+            if (typeof d.pinned === 'boolean') {
+                if (d.pinned)
+                    pinned.set(d.sessionId, order++);
+                else
+                    pinned.delete(d.sessionId);
             }
         }
         catch {
             // riga corrotta → skip
         }
     }
-    return bindings;
+    return { bindings, forkOf, pinned };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lamemind/loom-deck",
-  "version": "0.11.0",
+  "version": "0.13.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": {

package/scripts/deck-run

@@ -10,6 +10,10 @@
 # Con --no-task la sessione è NUDA: niente LOOM_TASK, niente prompt iniziale,
 # niente --session-id. Serve al lavoro spot che non appartiene a nessuna task.
 #
+# Con --resume <sid> riprende una conversazione esistente; aggiungendo --fork la
+# riprende RAMANDOLA (`--fork-session`): id nuovo, transcript copiato, l'origine
+# resta intatta e scrivibile.
+#
 # 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
@@ -32,6 +36,7 @@ TASK=""
 SESSION_ID=""
 RESUME_ID=""
 NO_TASK=0
+FORK=0
 # Positional <TaskID> + flag opzionale --session-id <uuid> (T27): il deck genera
 # l'UUID e lo pinna così il binding sidecar sessionId↔taskId è deterministico.
 # --no-task (T42): modalità NUDA, senza TaskID — nessuna LOOM_TASK, nessun prompt
@@ -43,6 +48,13 @@ NO_TASK=0
 # <sid>` (spot: resume nudo). Su resume niente prompt iniziale (si continua la
 # conversazione, non se ne inietta una nuova) e niente --session-id (l'id ce
 # l'ha già la sessione ripresa).
+# --fork (T28): MODIFICATORE di --resume, speculare al `--fork-session` del CLI
+# (che è definito allo stesso modo: "when resuming, create a new session ID").
+# Non è una terza forma di spawn ma una variante della ripresa → richiede
+# --resume, e senza di esso è un errore d'uso, non un fork "dell'ultima".
+# Sotto --fork il --session-id torna AMMESSO (anzi: è il punto) — la mutua
+# esclusione con --resume esiste perché una ripresa nuda riscrive il transcript
+# dell'id ripreso, mentre il fork ne apre uno NUOVO, che possiamo quindi pinnare.
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --session-id)
@@ -53,6 +65,8 @@ while [[ $# -gt 0 ]]; do
       RESUME_ID="${2:-}"; shift 2 ;;
     --resume=*)
       RESUME_ID="${1#*=}"; shift ;;
+    --fork)
+      FORK=1; shift ;;
     --no-task)
       NO_TASK=1; shift ;;
     *)
@@ -64,7 +78,9 @@ done
 USAGE="uso: deck-run <TaskID> [--session-id <uuid>]   (es. deck-run T18)
      | deck-run --no-task                          (sessione nuda, senza task)
      | deck-run <TaskID> --resume <uuid>           (riprende sessione scoped)
-     | deck-run --no-task --resume <uuid>          (riprende sessione spot)"
+     | deck-run --no-task --resume <uuid>          (riprende sessione spot)
+     | deck-run <TaskID> --resume <uuid> --fork [--session-id <nuovo-uuid>]
+                                                   (forka: ramo con id NUOVO)"
 
 if [[ $NO_TASK -eq 1 && -n "$TASK" ]]; then
   echo "--no-task e <TaskID> sono mutuamente esclusivi" >&2
@@ -75,8 +91,14 @@ if [[ $NO_TASK -eq 0 && -z "$TASK" ]]; then
   echo "$USAGE" >&2
   exit 2
 fi
-if [[ -n "$RESUME_ID" && -n "$SESSION_ID" ]]; then
+if [[ $FORK -eq 1 && -z "$RESUME_ID" ]]; then
+  echo "--fork richiede --resume <uuid>: si forka una conversazione esistente, non il nulla" >&2
+  echo "$USAGE" >&2
+  exit 2
+fi
+if [[ -n "$RESUME_ID" && -n "$SESSION_ID" && $FORK -eq 0 ]]; then
   echo "--resume e --session-id sono mutuamente esclusivi (la sessione ripresa ha già il suo id)" >&2
+  echo "usa --fork se vuoi un ramo con id nuovo" >&2
   echo "$USAGE" >&2
   exit 2
 fi
@@ -125,6 +147,11 @@ if [[ -n "$_cfg" ]]; then
     if [[ $NO_TASK -eq 1 ]]; then TITLE="${_label}"; else TITLE="${_label} · ${TASK}"; fi
   fi
 fi
+# Suffisso fork (T28): un ramo eredita task e label dell'origine, quindi senza
+# marcatore le due tab risulterebbero omonime nella stessa window. Suffisso e
+# non prefisso perché il match compass è `.includes(label)` e la label deve
+# restare intatta in testa — stesso schema di `· <task>` e `· deck`.
+[[ $FORK -eq 1 ]] && TITLE="${TITLE} · fork"
 
 # ── permissionMode (T45) ─────────────────────────────────────────────────────
 # Precedenza: env LOOM_DECK_PERMISSION_MODE > campo del file config > 'manual'.
@@ -155,6 +182,13 @@ SID_FLAG=""
 RES_FLAG=""
 [[ -n "$RESUME_ID" ]] && RES_FLAG="--resume ${RESUME_ID} "
 
+# --fork-session per la tab (T28): CC apre un id NUOVO invece di riscrivere
+# quello ripreso → mai due writer sullo stesso JSONL. Terzo gemello del pattern
+# flag-opzionale, per la stessa ragione degli altri due: la variante non deve
+# duplicare IN_TAB_CMD.
+FORK_FLAG=""
+[[ $FORK -eq 1 ]] && FORK_FLAG="--fork-session "
+
 # 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
@@ -177,13 +211,18 @@ fi
 # iniezione LOOM_TASK, prompt iniziale, --session-id pinnato. Resta claude nudo,
 # titolato e con il permission mode del progetto.
 # Su resume (T49) il prompt iniziale salta anche nel ramo task: riprendere una
-# conversazione significa continuarla, non iniettarle un nuovo messaggio.
+# conversazione significa continuarla, non iniettarle un nuovo messaggio. Il
+# fork (T28) ricade nello stesso ramo — è una ripresa, con id nuovo.
 PROMPT_ARG="'${PROMPT}'"
 [[ -n "$RESUME_ID" ]] && PROMPT_ARG=""
+# Il SID_FLAG entra anche nel ramo --no-task, che altrimenti lo scarta insieme
+# agli altri elementi task-bound: nel fork di una sessione SPOT il sessionId
+# pinnato non serve a legare una task (non c'è) ma a rendere noto in anticipo
+# l'id del ramo, senza il quale il lineage non sarebbe registrabile.
 if [[ $NO_TASK -eq 1 ]]; then
-  _default_intab="claude --name '${TITLE}' ${MODE_FLAG}${RES_FLAG}"
+  _default_intab="claude --name '${TITLE}' ${MODE_FLAG}${SID_FLAG}${RES_FLAG}${FORK_FLAG}"
 else
-  _default_intab="LOOM_TASK=${TASK} claude --name '${TITLE}' ${MODE_FLAG}${SID_FLAG}${RES_FLAG}${PROMPT_ARG}"
+  _default_intab="LOOM_TASK=${TASK} claude --name '${TITLE}' ${MODE_FLAG}${SID_FLAG}${RES_FLAG}${FORK_FLAG}${PROMPT_ARG}"
 fi
 IN_TAB_CMD="${LOOM_DECK_INTAB_CMD:-$_default_intab}"