@lamemind/loom-deck 0.67.0 → 0.68.0

package/dist/spawn-catalog.js

@@ -0,0 +1,338 @@
+// Il CATALOGO delle azioni di spawn: per ogni cosa che il deck sa aprire, un id
+// stabile e la terna titolo/modello/prompt con la sorgente di ciascun valore.
+//
+// Prima di questo modulo un'azione di spawn non era un'entità: era un tasto che
+// chiamava una funzione, e ogni funzione decideva da sé — nel proprio punto di
+// chiamata — quale modello e quale prompt passare. Il modello veniva da quattro
+// sorgenti diverse (il catalogo `prompt-catalog` per kind, il transcript per
+// resume e fork, un selettore vivo per la nuda, un letterale in `actions.ts` per
+// drain e srotolamento) e non esisteva nessun posto in cui leggerne l'elenco.
+// Senza quell'elenco non c'è nessuna tabella da mostrare, e nessuna riga che un
+// override di progetto possa indirizzare.
+//
+// DATO PURO: nessuna lettura di file, nessun React, nessun import di
+// `spawn.ts`. La dipendenza va in un verso solo (coding-standards: nessun modulo
+// estratto importa il file da cui è stato estratto) — `spawn.ts`, `actions.ts`,
+// `sheet.ts`, `glyphs.ts` e `prompt-catalog.ts` importano da qui.
+//
+// Chi COMPONE i default con gli override di progetto è `spawn-config.ts`: lì
+// vivono la lettura del file, la validazione al confine e la risoluzione della
+// terna. Qui ci sono solo i default del deck.
+/**
+ * `recap` → la sotto-skill giusta, quando chi spawna SA se la task è un cappello.
+ *
+ * `recap` resta il kind onesto per chi non lo sa: punta al dispatcher, che
+ * risolve la task e classifica da sé. È il caso degli acceleratori della lista,
+ * dove il deck ha in mano solo `tasks.md` — e lì il `Size` non c'è. Il DETAIL
+ * invece il task file l'ha già letto, quindi può saltare il giro e pagare un
+ * turno di modello in meno.
+ *
+ * Non è una classificazione duplicata: il criterio (`Size: Epic`) resta uno solo
+ * e sta in `taskIsEpic`, che legge lo stesso campo che leggerebbe il dispatcher.
+ * Quello che si evita è il RITARDO, non il giudizio.
+ *
+ * T161 — la stessa funzione è anche il ponte dal detail al catalogo: gli id
+ * delle sette azioni su task SONO i sette kind, quindi specializzare un kind
+ * significa già scegliere la riga di catalogo (e l'override che la indirizza).
+ *
+ * Ogni kind diverso da `recap` passa intatto: la specializzazione è un caso, non
+ * una trasformazione da applicare a tutti.
+ */
+export function specializeRecap(kind, epic) {
+    if (kind !== 'recap')
+        return kind;
+    return epic ? 'recap-epic' : 'recap-task';
+}
+// L'ordine È il giro di `tab` nel detail, non una preferenza di lettura:
+// cambiarlo sposta le voci sotto le dita di chi le ha imparate. Fino a T111 era
+// anche il binding delle cifre `1`-`4`, passate poi al campo nota.
+export const MODELS = ['fable', 'opus', 'sonnet', 'haiku'];
+/** Il valore è uno dei quattro alias? Guardia del confine: la usano il parser
+ *  del catalogo dati e quello del blocco `spawn` del file di progetto, che
+ *  leggono entrambi testo scritto a mano. */
+export function isModelKind(v) {
+    return typeof v === 'string' && MODELS.includes(v);
+}
+// Default del selettore e FALLBACK ultimo di ogni risoluzione. Duplicato del
+// default di deck-run e non letto da lì: il deck deve poter MOSTRARE la
+// selezione iniziale prima di spawnare alcunché, e un valore che si conosce solo
+// a spawn avvenuto non è mostrabile.
+//
+// T161 — non è più il default di nessuna azione in particolare: ogni riga del
+// catalogo porta il proprio (o lo prende dal catalogo dati), e qui si cade solo
+// quando nessuna delle due sorgenti ha una voce.
+export const MODEL_DEFAULT = 'fable';
+// T152 — `recap-status-project` non è una chiave di `prompt-catalog` (le chiavi
+// lì sono i valori di `--prompt-kind`, e lo spawn headless non ne passa mai
+// uno): il suo default vive nella riga `project-status` di questo catalogo.
+// Resta `opus` mentre i tre recap stanno su fable, ed è l'unico recap che gira
+// in headless (`-p`), senza nessuno che ne legga l'esito mentre si forma e possa
+// rilanciarlo — il testo prodotto è il deliverable, e viene riletto da disco
+// anche giorni dopo.
+export const PROJECT_STATUS_MODEL = 'opus';
+// T66 — le azioni del detail. Non sono un catalogo a parte: ognuna nomina una
+// riga di questo catalogo, per kind, e tutte passano dallo stesso `spawnForTask`
+// dei CTRL della lista — una superficie in più, zero percorsi di spawn in più.
+//
+// L'etichetta è distinta dal kind dove il kind è il nome del MECCANISMO e
+// l'etichetta quello dell'INTENZIONE: `none` è "aprire la task a mani nude",
+// `recap` è "vedere a che punto sta".
+export const DETAIL_ACTIONS = [
+    { kind: 'none', label: 'open' },
+    { kind: 'preflight', label: 'preflight' },
+    { kind: 'run', label: 'run' },
+    { kind: 'recap', label: 'status' },
+    { kind: 'checkpoint', label: 'checkpoint' },
+];
+// T117 — selezione DIRETTA di un'azione con la sua iniziale (`o p r s c`),
+// accanto allo scorrimento `←→`. Derivate dalle label e non cablate: una voce
+// aggiunta al catalogo porta con sé la propria lettera, invece di lasciare
+// indietro una seconda lista.
+// Il vincolo che la derivazione impone al catalogo: le iniziali devono restare
+// DISTINTE fra loro. Due label con la stessa lettera renderebbero la seconda
+// irraggiungibile, e in silenzio — chi aggiunge una voce lo controlla qui.
+export const ACTION_HOTKEYS = Object.fromEntries(DETAIL_ACTIONS.map((a, i) => [a.label[0], i]));
+export const SPAWN_FIELDS = ['title', 'model', 'prompt'];
+/**
+ * Il prompt cablato della sessione che srotola l'hard-wrap di un path.
+ *
+ * Le tre cose che dice sono le tre che rendono l'operazione reversibile e
+ * verificabile — backup fuori dal repo, rapporto, commit solo se il diff è
+ * chiaramente innocuo. Era cablato in `wrap-scan.ts` e da T161 è il DEFAULT di
+ * una riga del catalogo: resta la stessa frase, ma ora è sovrascrivibile dal
+ * progetto invece che dal solo sorgente.
+ *
+ * Nessun apice singolo, come i template di `prompt-catalog`: il testo finisce
+ * dentro `'…'` nel comando passato a `bash -lc`, e `deck-run` lo quota, ma un
+ * apice qui sarebbe comunque una scrittura da rileggere due volte.
+ */
+const UNWRAP_PROMPT = 'lancia md-wrap modo apply su {path} e backup in cartella tmp dedicata. ' +
+    'verifica risultato e fai rapporto. se le modifiche sono tutte chiaramente safe, ' +
+    'puoi committare direttamente';
+/**
+ * Le UNDICI azioni configurabili, nell'ordine in cui la pagina le elenca.
+ *
+ * Il perimetro è quello di D1: entra una riga se ha almeno una cella editabile.
+ * Ne restano fuori resume e fork — lì il modello non è una preferenza ma
+ * un'EREDITÀ, letta dal transcript della conversazione d'origine, e un override
+ * sarebbe una cella che mente — insieme a `create-task` e `clean-tasks`, che non
+ * passano `--model` e girano sul default del CLI (dargliene una sarebbe un
+ * cambio di comportamento fatto per riempire una riga), al terminale e alle voci
+ * `launch`, che non sono sessioni Claude e non hanno né modello né prompt.
+ *
+ * T156 — le emoji dei titoli sono ASTRALI (code point ≥ U+10000) per necessità,
+ * non per gusto: `sanitize` (`src/width.ts`) sostituisce con `·` ogni glifo su
+ * cui le due contabilità di larghezza divergono, e le emoji del BMP a
+ * presentazione testo divergono sempre. Le stesse sei stanno nella whitelist di
+ * `_sane_note` in `deck-run` e nel suo gemello `src/sane-note.ts`: un'emoji
+ * cambiata qui e non là sparisce fra la tabella e la tab, senza errore.
+ */
+export const SPAWN_ACTIONS = [
+    {
+        id: 'none',
+        label: 'apri la task',
+        surface: 'detail o · ⏎⏎',
+        kind: 'none',
+        // D2 di T150 — nessun prefisso: `open` è "nessuna azione", e inventargliene
+        // uno contraddirebbe l'intenzione di chi la sceglie.
+        title: '{slug}',
+        model: null,
+        prompt: '',
+        holes: ['TASK', 'slug'],
+        fixed: {},
+    },
+    {
+        id: 'recap',
+        label: 'stato · dispatcher',
+        surface: 'lista ^K',
+        kind: 'recap',
+        // P3 di T150 — le tre varianti di recap condividono il prefisso: la
+        // specializzazione sceglie quale skill parte, non cosa si sta chiedendo.
+        title: '📊 {slug}',
+        model: null,
+        prompt: null,
+        holes: ['TASK', 'slug'],
+        fixed: {},
+    },
+    {
+        id: 'recap-task',
+        label: 'stato task',
+        surface: 'detail s',
+        kind: 'recap-task',
+        title: '📊 {slug}',
+        model: null,
+        prompt: null,
+        holes: ['TASK', 'slug'],
+        fixed: {},
+    },
+    {
+        id: 'recap-epic',
+        label: 'stato epica',
+        surface: 'detail s · cappello',
+        kind: 'recap-epic',
+        title: '📊 {slug}',
+        model: null,
+        prompt: null,
+        holes: ['TASK', 'slug'],
+        fixed: {},
+    },
+    {
+        id: 'preflight',
+        label: 'preflight',
+        surface: 'detail p · lista ^P',
+        kind: 'preflight',
+        title: '📐 {slug}',
+        model: null,
+        prompt: null,
+        holes: ['TASK', 'slug'],
+        fixed: {},
+    },
+    {
+        id: 'run',
+        label: 'run',
+        surface: 'detail r · lista ^R',
+        kind: 'run',
+        title: '🚀 {slug}',
+        model: null,
+        prompt: null,
+        holes: ['TASK', 'slug'],
+        fixed: {},
+    },
+    {
+        id: 'checkpoint',
+        label: 'checkpoint',
+        surface: 'detail c',
+        kind: 'checkpoint',
+        title: '🏁 {slug}',
+        model: null,
+        prompt: null,
+        holes: ['TASK', 'slug'],
+        fixed: {},
+    },
+    {
+        // T42/T154 — la sessione a mani nude. Configurabile sul solo modello (P12):
+        // non pinna un `sessionId` e non scrive nel sidecar, quindi un titolo
+        // comparirebbe nella tab e non in lista — la divergenza che `bareArgs`
+        // esiste per non avere — e un prompt la renderebbe non nuda.
+        id: 'bare',
+        label: 'sessione nuda',
+        surface: 'tasto c',
+        kind: null,
+        title: null,
+        model: MODEL_DEFAULT,
+        prompt: '',
+        holes: [],
+        fixed: {
+            title: 'nessun sessionId pinnato',
+            prompt: 'la renderebbe non nuda',
+        },
+    },
+    {
+        // T134 — il drain di un file inbox. Il prompt lo compone `inboxPrompt`
+        // (`src/inbox.ts`), che è l'unico posto in cui vive la mappa natura →
+        // skill: un template unico non saprebbe esprimerla, e spezzare la riga in
+        // una per natura contraddirebbe il perimetro di D1.
+        id: 'drain',
+        label: 'drain di un file inbox',
+        surface: 'pane inbox ⏎⏎',
+        kind: null,
+        title: '🧹 {file}',
+        model: MODEL_DEFAULT,
+        prompt: null,
+        holes: ['file'],
+        fixed: { prompt: 'natura del file' },
+    },
+    {
+        // T134 — lo srotolamento dell'hard-wrap. `sonnet` e non il default: è una
+        // passata meccanica con un verificatore deterministico dietro (`md-wrap
+        // --apply` confronta le due versioni normalizzate e rimette indietro il
+        // file se differiscono), quindi il giudizio chiesto al modello è leggere un
+        // diff e decidere se committarlo — non progettare niente.
+        id: 'unwrap',
+        label: 'srotolamento hard-wrap',
+        surface: 'lista ^W ⏎',
+        kind: null,
+        title: '📏 {path}',
+        model: 'sonnet',
+        prompt: UNWRAP_PROMPT,
+        holes: ['path'],
+        fixed: {},
+    },
+    {
+        // T121 — il recap di progetto, headless (`claude -p`): nessuna tab, quindi
+        // nessun titolo da configurare.
+        id: 'project-status',
+        label: 'project status',
+        surface: 'tasto ^G',
+        kind: null,
+        title: null,
+        model: PROJECT_STATUS_MODEL,
+        prompt: '/loom-works:recap-status-project',
+        holes: [],
+        fixed: { title: 'headless: nessuna tab' },
+    },
+];
+/**
+ * Valori d'esempio dei buchi, per l'ANTEPRIMA dell'area di compilazione.
+ *
+ * La cella della tabella mostra il template grezzo (`🚀 {slug}`), l'area mostra
+ * come verrebbe reso: senza l'esempio un template si scrive alla cieca, e
+ * l'effetto si scopre alla prima conversazione aperta.
+ *
+ * Sono valori FINTI e dichiarati tali dalla pagina, non la task selezionata: la
+ * pagina non ha una selezione — si apre da qualunque punto del deck — e legare
+ * l'anteprima a ciò che capita di avere sotto il caret la renderebbe diversa a
+ * ogni apertura, per la stessa configurazione.
+ */
+export const EXAMPLE_HOLES = {
+    TASK: 'T42',
+    slug: 'esempio di task',
+    file: 'T42-nozioni',
+    path: 'runtime reference',
+};
+/**
+ * I valori sono quelli che i FORNITORI dei buchi producono davvero, non testo
+ * grezzo: lo slug arriva dal nome del task file coi trattini già sciolti in
+ * spazi, il basename dell'inbox senza `.md`, il path già reso in parole. Un
+ * esempio con dentro un `/` o un `.` mostrerebbe l'effetto della riduzione — le
+ * parole saldate — su un caso che allo spawn non si presenta mai, e chi lo
+ * legge correggerebbe un titolo che non è rotto.
+ */
+const BY_ID = new Map(SPAWN_ACTIONS.map((a) => [a.id, a]));
+/** L'azione di un id, o `undefined` per un id che il catalogo non conosce — il
+ *  caso di un override scritto a mano per un'azione che non esiste più. */
+export function spawnAction(id) {
+    return BY_ID.get(id);
+}
+/** L'id è nel catalogo? Guardia del parser degli override. */
+export function isSpawnActionId(id) {
+    return typeof id === 'string' && BY_ID.has(id);
+}
+/** Le celle editabili di una riga: il complemento di `fixed`, derivato e mai
+ *  scritto a mano. */
+export function editableFields(action) {
+    return SPAWN_FIELDS.filter((f) => !(f in action.fixed));
+}
+/** Il segnaposto di una cella editabile ma a vuoto. Il vuoto è un valore
+ *  legittimo e distinto dall'assenza (P15): un titolo svuotato significa
+ *  «nessuna nota», un prompt svuotato «nessun prompt». */
+const EMPTY_LABEL = {
+    title: '(nessun titolo)',
+    model: '(nessun modello)',
+    prompt: '(nessun prompt)',
+};
+export function spawnCell(action, field, 
+/** Il valore risolto: `null` quando la cella non ne ha uno. */
+value, 
+/** Il valore viene da un override di progetto. */
+overridden) {
+    const reason = action.fixed[field];
+    if (reason !== undefined) {
+        return { text: `(${reason})`, editable: false, origin: 'fisso', placeholder: true };
+    }
+    const origin = overridden ? 'override' : 'default';
+    if (value === null || value === '') {
+        return { text: EMPTY_LABEL[field], editable: true, origin, placeholder: true };
+    }
+    return { text: value, editable: true, origin, placeholder: false };
+}

package/dist/spawn-config.js

@@ -0,0 +1,280 @@
+// T161 — gli OVERRIDE di progetto delle azioni di spawn: lettura, validazione,
+// risoluzione della terna, scrittura.
+//
+// ── La sede (P19 preflight) ─────────────────────────────────────────────────
+// Blocco `spawn` dentro `.claude/loom-works.json`, il file di progetto che il
+// deck già apre in tre loader (`launch`, `archivableDays`, `identity`) e che
+// `deck-run` legge con `jq`. Nessun file nuovo: sotto `.claude/` ci sono già tre
+// file di loom, e le impostazioni di spawn sono decisioni di progetto che devono
+// viaggiare col repo — cioè committate, esattamente come `permissionMode` e
+// `order`, e a differenza della vista (`.claude/loom/deck-view.json`, che è
+// gitignored perché è una preferenza di questa macchina).
+//
+// Il costo della scelta, dichiarato: da qui in poi il deck SCRIVE in
+// `loom-works.json`, cosa che prima non faceva mai. Il saver è un
+// read-modify-write che conserva ogni altra chiave nel suo ordine e tocca il
+// solo blocco `spawn`, e RIFIUTA di scrivere se il file non si parsa — quel file
+// regge identità, label e registry di compass, e rigenerarlo da zero al posto di
+// uno rotto significherebbe perderli.
+//
+// Lo schema del plugin (`templates/loom-works.schema.json`) dichiara
+// `additionalProperties: false` e il blocco `spawn` non vi compare ancora: non è
+// un errore a runtime, perché `cfg_validate` in `lib-config.sh` è jq scritto a
+// mano sui soli campi noti e un campo sconosciuto passa. Lo schema è reference
+// per chi scrive il file a mano, e la voce `"spawn": { "type": "object" }` lo
+// raggiunge al prossimo publish del plugin (Prod Validation della task).
+//
+// ── Il formato ──────────────────────────────────────────────────────────────
+//   "spawn": { "<id azione>": { "title"?: string, "model"?: alias, "prompt"?: string } }
+//
+// SOLO override: una chiave assente significa «il default del deck», e il blocco
+// sparisce dal file quando non resta nessun override. Vuoto ≠ assente (P15): un
+// `"title": ""` è un override legittimo che dice «nessuna nota».
+//
+// ── Chi legge cosa ──────────────────────────────────────────────────────────
+// Il blocco lo legge il SOLO deck, che risolve la terna e la passa a `deck-run`
+// sempre esplicita nell'argv (`--title-note`, `--model`, `--prompt`). `deck-run`
+// non lo legge e non deve: `jq` è dipendenza OPZIONALE di quello script, e
+// dargli un blocco JSON da consultare la renderebbe obbligatoria su un percorso
+// che oggi degrada senza. La cascata env → catalogo → `fable` di `deck-run`
+// resta intatta per chi lo invoca a mano.
+import { readFileSync, writeFileSync } from 'node:fs';
+import { configFilePath } from './config.js';
+import { modelFor } from './prompt-catalog.js';
+import { interpolate, saneNote, saneTemplate } from './sane-note.js';
+import { MODEL_DEFAULT, SPAWN_ACTIONS, SPAWN_FIELDS, editableFields, isModelKind, spawnAction, } from './spawn-catalog.js';
+/** La chiave del blocco nel file di progetto. Costante e non letterale sparso:
+ *  la nominano il parser, il saver e il messaggio d'avviso. */
+export const SPAWN_BLOCK = 'spawn';
+/**
+ * Validazione per VOCE, non per file (P7).
+ *
+ * La voce sbagliata cade con una nota che la nomina, il resto vive. Rifiutare
+ * l'intero blocco alla prima chiave sporca significherebbe che un refuso su una
+ * riga spegne in silenzio gli override di tutte le altre; e conservare per
+ * sempre le voci ignote significherebbe riscriverle a ogni salvataggio, cioè
+ * tenere in vita nel file una configurazione che nessuno legge più. È lo stesso
+ * regime di `sanitizeSort` (`view-store.ts`) e di `parseLaunch`.
+ *
+ * Cosa cade e cosa no:
+ *  - id fuori catalogo → l'intera voce, con nota (un'azione che non esiste più);
+ *  - modello fuori dai quattro alias → il solo campo, con nota (arriverebbe al
+ *    CLI e produrrebbe una tab con un comando che fallisce all'avvio);
+ *  - campo su una cella FISSA → il solo campo, con nota (il valore non avrebbe
+ *    nessuna strada per arrivare allo spawn);
+ *  - titolo → ridotto, mai scartato: quello che si legge nella pagina è quello
+ *    che comparirà nella tab, anche quando il file è stato scritto a mano;
+ *  - prompt → qualunque testo, che viaggia come argv singolo.
+ */
+export function parseSpawnOverrides(raw) {
+    const entries = new Map();
+    const warnings = [];
+    if (!raw || typeof raw !== 'object')
+        return { entries, warnings };
+    const block = raw[SPAWN_BLOCK];
+    if (block === undefined)
+        return { entries, warnings };
+    if (!block || typeof block !== 'object' || Array.isArray(block)) {
+        warnings.push(`blocco ${SPAWN_BLOCK} ignorato: non è un oggetto`);
+        return { entries, warnings };
+    }
+    for (const [id, value] of Object.entries(block)) {
+        const action = spawnAction(id);
+        if (!action) {
+            warnings.push(`${SPAWN_BLOCK}.${id}: azione fuori catalogo, voce scartata`);
+            continue;
+        }
+        if (!value || typeof value !== 'object' || Array.isArray(value)) {
+            warnings.push(`${SPAWN_BLOCK}.${id}: non è un oggetto, voce scartata`);
+            continue;
+        }
+        const src = value;
+        const editable = new Set(editableFields(action));
+        const out = {};
+        for (const field of SPAWN_FIELDS) {
+            const v = src[field];
+            if (v === undefined)
+                continue;
+            if (!editable.has(field)) {
+                warnings.push(`${SPAWN_BLOCK}.${id}.${field}: ${action.fixed[field]}, campo scartato`);
+                continue;
+            }
+            if (field === 'model') {
+                if (!isModelKind(v)) {
+                    warnings.push(`${SPAWN_BLOCK}.${id}.model: '${String(v)}' non è un modello, campo scartato`);
+                    continue;
+                }
+                out.model = v;
+                continue;
+            }
+            if (typeof v !== 'string') {
+                warnings.push(`${SPAWN_BLOCK}.${id}.${field}: non è un testo, campo scartato`);
+                continue;
+            }
+            if (field === 'title')
+                out.title = saneTemplate(v);
+            else
+                out.prompt = v;
+        }
+        // Una voce rimasta senza nessun campo valido non entra: nella pagina
+        // marcherebbe la riga come «toccata» senza che niente sia stato cambiato.
+        if (Object.keys(out).length > 0)
+            entries.set(action.id, out);
+    }
+    return { entries, warnings };
+}
+/** File assente → nessun override e NESSUN avviso: è lo stato normale di un
+ *  progetto che non ha mai aperto la pagina, come per `loadLaunch` e
+ *  `loadArchivableDays`. Illeggibile o non-JSON → default con avviso: lì c'è un
+ *  file, e sta dicendo qualcosa che non si riesce a leggere. */
+export function loadSpawnOverrides(projectRoot) {
+    let text;
+    try {
+        text = readFileSync(configFilePath(projectRoot), 'utf8');
+    }
+    catch {
+        return { entries: new Map(), warnings: [] };
+    }
+    try {
+        return parseSpawnOverrides(JSON.parse(text));
+    }
+    catch {
+        return {
+            entries: new Map(),
+            warnings: [`${configFilePath(projectRoot)} non si parsa: override di spawn ignorati`],
+        };
+    }
+}
+/**
+ * Default del deck ← override di progetto, più l'interpolazione dei buchi.
+ *
+ * La precedenza è a due soli livelli, per tutta la task: i valori cablati nel
+ * sorgente sono i default, l'unico livello di override è il progetto. Nessuna
+ * configurazione d'utente — né sotto `~/.claude/`, né sotto `~/.config/`.
+ *
+ * Dentro il livello «default» ci sono però due sorgenti, e l'ordine conta: il
+ * modello e il prompt cablati nella riga di catalogo vincono su quelli del
+ * catalogo dati, che si consulta solo per le azioni che hanno un `kind`. È
+ * l'ordine giusto perché un'azione senza `kind` non ha una riga in
+ * `prompt-catalog` per costruzione, e una che ce l'ha non porta valori propri.
+ */
+export function resolveSpawn(action, overrides, catalog, holes = {}) {
+    const raw = rawSpawn(action, overrides, catalog);
+    let prompt = raw.prompt;
+    if (prompt)
+        prompt = interpolate(prompt, holes) ?? '';
+    // La riduzione si applica DOPO l'interpolazione, perché i buchi portano dentro
+    // testo che l'alfabeto non ammette: uno slug col punto, un path con le barre.
+    // Quello che esce di qui è la stessa stringa che `deck-run` comporrà.
+    const filled = raw.title === null ? null : interpolate(raw.title, holes);
+    const title = filled === null ? null : saneNote(filled) || null;
+    return { title, model: raw.model, prompt, overridden: raw.overridden };
+}
+/** La terna di un'azione per ID di catalogo. Due chiamanti — l'attuatore, che la
+ *  espone a tutte le sedi di spawn, e il valore iniziale del selettore della
+ *  sessione nuda, che si risolve prima che l'attuatore esista — e una sola
+ *  implementazione. */
+export function resolveSpawnId(id, overrides, catalog, holes = {}) {
+    return resolveSpawn(spawnAction(id), overrides, catalog, holes);
+}
+/**
+ * Gli stessi tre valori PRIMA dell'interpolazione: i template coi buchi ancora
+ * dentro.
+ *
+ * È la forma che la pagina mostra e fa modificare (P9 preflight): nella cella si
+ * legge `🚀 {slug}`, non il titolo di una task particolare — un valore già reso
+ * si modificherebbe a partire da un esempio, e ogni modifica cancellerebbe il
+ * buco senza che nulla lo dica. L'esempio reso sta accanto, nell'area di
+ * compilazione, dove serve a vedere l'effetto senza essere il campo.
+ *
+ * Serve anche al confronto col DEFAULT: chi conferma una modifica scrive la
+ * cella solo se differisce dal grezzo che uscirebbe senza override, ed è così
+ * che un valore riportato a mano al default smette di essere un override invece
+ * di restare nel file come una riga che non cambia niente.
+ */
+export function rawSpawn(action, overrides, catalog) {
+    const ov = overrides.get(action.id) ?? {};
+    const overridden = new Set(Object.keys(ov));
+    const model = ov.model ??
+        action.model ??
+        (action.kind ? modelFor(catalog, action.kind) : undefined) ??
+        MODEL_DEFAULT;
+    let prompt;
+    if (ov.prompt !== undefined)
+        prompt = ov.prompt;
+    else if (action.prompt !== null)
+        prompt = action.prompt;
+    // Catalogo dati assente o voce mancante → nessun prompt, non un testo
+    // inventato qui: un default scritto nel deck sarebbe la copia del catalogo che
+    // il file dati esiste per non avere.
+    else if (action.kind)
+        prompt = catalog.get(action.kind)?.template ?? '';
+    else
+        prompt = null;
+    return { title: ov.title ?? action.title, model, prompt, overridden };
+}
+/**
+ * Il blocco `spawn` come lo si scrive nel file: le sole voci non vuote, coi soli
+ * campi presenti, ordinate come il catalogo.
+ *
+ * L'ordine è quello di `SPAWN_ACTIONS` e non quello di inserimento nella mappa:
+ * il file è committato e lo si legge in diff, dove una riga che si sposta da
+ * sola a ogni salvataggio è rumore su cui poi si fa merge.
+ *
+ * `undefined` quando non resta nessun override: il chiamante toglie la chiave
+ * invece di scrivere `"spawn": {}`, che sarebbe una configurazione vuota da
+ * spiegare a chi la legge.
+ */
+export function serializeSpawnBlock(entries) {
+    const out = {};
+    // L'ordine viene da `SPAWN_ACTIONS`, non da una seconda lista di id scritta
+    // qui: una copia dell'elenco diverge alla prima riga aggiunta al catalogo, e
+    // la voce nuova finirebbe fuori dal file senza che niente lo segnali.
+    for (const action of SPAWN_ACTIONS) {
+        const ov = entries.get(action.id);
+        if (!ov)
+            continue;
+        const clean = {};
+        if (ov.title !== undefined)
+            clean.title = ov.title;
+        if (ov.model !== undefined)
+            clean.model = ov.model;
+        if (ov.prompt !== undefined)
+            clean.prompt = ov.prompt;
+        if (Object.keys(clean).length > 0)
+            out[action.id] = clean;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+/**
+ * Scrive il blocco `spawn` nel file di progetto, conservando tutto il resto.
+ *
+ * Read-modify-write su un file che NON è nostro: `loom-works.json` regge
+ * identità, label, surface, registry di compass e `permissionMode`, e il deck
+ * finora non ci aveva mai scritto. Da qui le due cautele:
+ *  - se il file non si parsa la funzione LANCIA invece di rigenerarlo: un
+ *    `loom-works.json` rotto va riparato a mano, non sostituito con uno che ha
+ *    perso l'identità del progetto;
+ *  - ogni altra chiave sopravvive nel suo ordine (`JSON.parse` conserva l'ordine
+ *    di inserimento delle chiavi stringa, `JSON.stringify` lo riscrive uguale),
+ *    così il diff del commit mostra il solo blocco toccato.
+ *
+ * File ASSENTE: anche qui si lancia. Un progetto senza `loom-works.json` non è
+ * registrato, e creargliene uno col solo blocco `spawn` produrrebbe un file che
+ * fallisce ogni validazione a valle.
+ */
+export function saveSpawnOverrides(projectRoot, entries) {
+    const path = configFilePath(projectRoot);
+    const raw = readFileSync(path, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`${path}: non è un oggetto JSON`);
+    }
+    const doc = parsed;
+    const block = serializeSpawnBlock(entries);
+    if (block)
+        doc[SPAWN_BLOCK] = block;
+    else
+        delete doc[SPAWN_BLOCK];
+    writeFileSync(path, JSON.stringify(doc, null, 2) + '\n', 'utf8');
+}