@lamemind/loom-deck 0.76.0 → 0.78.0

package/dist/sane-note.js

@@ -1,35 +1,29 @@
-// T161 — il gemello TypeScript di `_sane_note`, la riduzione che `deck-run`
-// applica a ogni nota del titolo.
+// La riduzione della nota del titolo di una tab: l'unica, per il deck e per
+// `deck-run`.
 //
-// Perché serve un gemello. La nota del titolo è l'UNICO ingresso di testo libero
-// nel titolo di una tab, quindi `deck-run` non la quota: la RIDUCE a una
-// whitelist chiusa di code point, e tutto ciò che non ci rientra sparisce senza
-// errore. Finché la nota nasceva da un campo scritto al volo, la divergenza fra
-// quello che si legge nel deck e quello che compare nella tab durava il tempo di
-// uno spawn. Da quando un TEMPLATE del titolo si scrive in una pagina e si salva
-// su disco, quella divergenza diventa permanente: il file direbbe una cosa e la
-// tab ne mostrerebbe un'altra, per sempre e senza un errore da nessuna parte.
+// La nota del titolo è l'UNICO ingresso di testo libero nel titolo di una tab,
+// quindi non si quota: si RIDUCE a una whitelist chiusa di code point, e tutto
+// ciò che non ci rientra sparisce senza errore. Da quando un TEMPLATE del titolo
+// si scrive in una pagina e si salva su disco (T161), la riduzione si applica
+// anche QUI, al confine — al salvataggio e alla lettura del blocco `spawn` —
+// così quello che sta nel file è quello che la tab mostrerà.
 //
-// La riduzione si applica quindi QUI, al confine — al salvataggio e alla
-// lettura del blocco `spawn` — così quello che sta nel file è quello che la tab
-// mostrerà.
-//
-// L'ALLINEAMENTO fra i due lati non è assunto: `test/sane-note.test.ts` passa la
-// stessa batteria di input a questa funzione e a `deck-run` vero (via lo shim
-// `ptyxis` di `deck-run.test.ts`) e pretende l'uguaglianza. La whitelist non si
-// allarga — e se un giorno lo facesse, sono tre le sedi da toccare insieme
-// (`deck-run`, questo file, le emoji dei titoli in `spawn-catalog.ts`), col test
-// che fallisce se una resta indietro.
+// T176 — fino a T176 questo modulo era il gemello di `_sane_note`, la stessa
+// riduzione scritta in bash dentro `deck-run`, e un test teneva uguali i due
+// lati. Il composer della tab ora è TypeScript (`src/tab-compose.ts`) e chiama
+// questa funzione: la whitelist ha due sedi da toccare insieme, questo file e le
+// emoji dei titoli in `spawn-catalog.ts`, e `test/deck-run.test.ts` fallisce se
+// un'emoji di un titolo del catalogo non passa.
 /**
  * L'alfabeto ammesso, negato: lettere, cifre, spazio, `_`, `-`, le accentate
  * italiane e sette emoji.
  *
- * Whitelist e non blacklist, come in bash: il titolo finisce dentro apici
- * singoli in `bash -lc "claude --name '…'"`, ed enumerare i caratteri pericolosi
- * significa sbagliarne uno.
+ * Whitelist e non blacklist: il titolo finisce in una riga di shell su Linux
+ * (`bash -lc "claude --name '…'"`) e nella riga di `wt.exe` su Windows, ed
+ * enumerare i caratteri pericolosi significa sbagliarne uno.
  *
  * Le sette emoji sono nominate una per una e NON come intervallo di code point,
- * per due ragioni che valgono su entrambi i lati: un'emoji arriva nella tab solo
+ * per due ragioni: un'emoji arriva nella tab solo
  * se il deck la mostra identica in lista, cioè se `sanitize` (`src/width.ts`) la
  * lascia passare invece di renderla `·`, e quel verdetto si verifica un glifo
  * alla volta; e l'ordine di un intervallo dentro un bracket expression segue la

package/dist/spawn-catalog.js

@@ -123,9 +123,9 @@ const UNWRAP_PROMPT = 'lancia md-wrap modo apply su {path} e backup in cartella
  * 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 SETTE (T160 aggiunge `🧭`)
- * 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.
+ * stanno nella whitelist di `saneNote` (`src/sane-note.ts`), la riduzione del
+ * titolo: un'emoji cambiata qui e non là sparisce fra la tabella e la tab,
+ * senza errore.
  */
 export const SPAWN_ACTIONS = [
     {
@@ -276,7 +276,7 @@ export const SPAWN_ACTIONS = [
         // DUE buchi per lo stesso dato, e servono entrambi: `{target}` è il path
         // VERO, che la skill risolve contro la colonna `PATH` della misura, e
         // `{words}` lo stesso path reso a parole per il titolo. L'alfabeto di
-        // `_sane_note` non ha né `/` né `.`, quindi un `{target}` in un template di
+        // `saneNote` non ha né `/` né `.`, quindi un `{target}` in un template di
         // titolo uscirebbe con le parole saldate (`runtimereferencedoc-systemmd`) e
         // la tab mostrerebbe un nome diverso da quello che il deck legge dal
         // sidecar.

package/dist/spawn-config.js

@@ -4,7 +4,7 @@
 // ── 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
+// `deck-run` legge per label e permission mode. 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 è
@@ -34,9 +34,9 @@
 // ── 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`
+// non lo legge e non deve: la terna che parte è quella che il deck ha mostrato,
+// e una seconda risoluzione dall'altra parte del processo sarebbe una seconda
+// copia delle stesse regole. 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';

package/dist/spawn.js

@@ -10,10 +10,24 @@ import { dirname, join } from 'node:path';
 import { MODEL_DEFAULT, PROJECT_STATUS_MODEL } from './spawn-catalog.js';
 import { isAvailable } from './platform.js';
 import { claudeLauncher } from './claude-cmd.js';
-import { claudeEnv } from './git-bash.js';
+import { claudeEnv, gitBash } from './git-bash.js';
+import { windowsTabEnv, WT_CMD, wtNewTabArgs, wtProfile } from './windows-terminal.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.
 export const DECK_RUN = join(dirname(fileURLToPath(import.meta.url)), '..', 'scripts', 'deck-run');
+// T176 — il punto d'ingresso che lo shim `scripts/deck-run` esegue, nel build.
+// Su Windows il deck lo lancia da sé: CreateProcess non esegue uno script bash
+// senza estensione.
+export const DECK_RUN_JS = join(dirname(fileURLToPath(import.meta.url)), '..', 'dist', 'deck-run.js');
+/**
+ * Come il deck lancia `deck-run`: lo shim su Linux, il node del deck sul punto
+ * d'ingresso su Windows. Le due forme eseguono lo stesso programma — lo shim è
+ * una riga che fa `exec node dist/deck-run.js` —, e su Linux resta lo shim
+ * perché è il comando che la riga di stato mostra e che si ripete a mano.
+ */
+export function deckRunLauncher(platform = process.platform, nodePath = process.execPath) {
+    return platform === 'win32' ? { cmd: nodePath, prefix: [DECK_RUN_JS] } : { cmd: DECK_RUN, prefix: [] };
+}
 /**
  * Freno agli effetti VERSO L'ESTERNO (tab Ptyxis, sessioni Claude, git commit).
  *
@@ -78,13 +92,15 @@ export function shellCommand(cmd, args) {
 // comando in-tab (vedi `onInTabCommand`). Il figlio resta detached — la pipe
 // serve a leggere una riga, non a possedere il processo.
 function launchDeckRun(args, cwd) {
-    const child = spawnOut(DECK_RUN, args, {
+    const run = deckRunLauncher();
+    const argv = [...run.prefix, ...args];
+    const child = spawnOut(run.cmd, argv, {
         cwd,
         detached: true,
         stdio: ['ignore', 'pipe', 'ignore'],
     });
     child.unref();
-    return { child, cmd: shellCommand(DECK_RUN, args) };
+    return { child, cmd: shellCommand(run.cmd, argv) };
 }
 /** Prefisso della riga con cui `deck-run` annuncia il comando in-tab. */
 export const INTAB_MARKER = 'LOOM_DECK_INTAB ';
@@ -152,10 +168,9 @@ export function onInTabCommand(child, cb) {
 // acceleratori della lista passavano `--prompt-kind` e lasciavano risolvere il
 // testo a `deck-run`, che consultava il proprio catalogo; il detail passava già
 // il letterale. Con un override di progetto sui prompt la risoluzione deve
-// stare da una parte sola, e quella parte è il deck — che è l'unico dei due a
-// leggere `.claude/loom-works.json` per questo (`jq` è dipendenza opzionale di
-// `deck-run`). Un percorso solo, quindi, e ciò che parte è verificabile
-// sull'argv.
+// stare da una parte sola, e quella parte è il deck — l'unico dei due che legge
+// il blocco `spawn` di `.claude/loom-works.json`. Un percorso solo, quindi, e
+// ciò che parte è verificabile sull'argv.
 //
 // Due conseguenze dichiarate: `--prompt-kind` resta in `deck-run` per chi lo
 // invoca a mano, e `LOOM_DECK_ENTER_PROMPT` non ha più effetto sugli spawn dal
@@ -346,7 +361,36 @@ export function runLaunch(entry, cwd) {
 export function terminalArgs(cwd, title) {
     return title ? ['--tab', '-T', title, '-d', cwd] : ['--tab', '-d', cwd];
 }
+/**
+ * T176 — il tasto `t` su Windows (P10 preflight): una tab di Windows Terminal
+ * nella finestra attiva, col profilo del deck e il titolo bloccato, SENZA
+ * comando — la shell è il `commandline` del profilo, come `ptyxis --tab` apre
+ * quella del profilo di Ptyxis.
+ */
+export function windowsTerminalArgs(cwd, title, env = process.env) {
+    return wtNewTabArgs({ newWindow: false, profile: wtProfile(env), cwd, title });
+}
+/** Il terminale del tasto `t`, per nome: è ciò che la nota dice quando non parte. */
+export function terminalName(platform = process.platform) {
+    return platform === 'win32' ? WT_CMD : 'ptyxis';
+}
 export function spawnTerminal(cwd, title) {
+    if (process.platform === 'win32') {
+        // La tab eredita l'env del deck (T174 verdetto 5): senza i marker di
+        // sessione e senza `LOOM_TASK`, col bash di Git — come una conversazione
+        // `--no-task`, perché un `claude` lanciato da questa shell nascerebbe con
+        // l'env che riceve. `windowsHide: false`: `wt.exe` è un'app GUI, e con
+        // `true` una finestra nuova partirebbe nascosta.
+        const child = spawnOut(WT_CMD, windowsTerminalArgs(cwd, title), {
+            cwd,
+            detached: true,
+            stdio: 'ignore',
+            env: windowsTabEnv(process.env, null, gitBash()),
+            windowsHide: false,
+        });
+        child.unref();
+        return child;
+    }
     const child = spawnOut('ptyxis', terminalArgs(cwd, title), {
         cwd,
         detached: true,

package/dist/tab-args.js

@@ -0,0 +1,141 @@
+/** I kind accettati da `--prompt-kind`. Enum e non stringa libera: un kind è un
+ *  simbolo interno del deck, e uno fuori elenco è un errore del chiamante. */
+export const PROMPT_KINDS = [
+    'none',
+    'recap',
+    'recap-task',
+    'recap-epic',
+    'preflight',
+    'run',
+    'checkpoint',
+];
+export const USAGE = `uso: deck-run <TaskID> [--model <alias>] [--prompt-kind <kind>] [--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 <TaskID> --resume <uuid> --fork [--session-id <nuovo-uuid>]
+                                                   (forka: ramo con id NUOVO)
+
+  --prompt-kind  prompt iniziale della sessione bound (default: recap)
+       none        nessun prompt — sessione aperta sulla task, a mani nude
+       recap       /loom-works:recap-status <TaskID>       (dispatcher)
+       recap-task  /loom-works:recap-status-task <TaskID>  (task non cappello)
+       recap-epic  /loom-works:recap-status-epic <TaskID>  (Size: Epic)
+       preflight   /loom-works:preflight-task <TaskID>
+       run         /loom-works:run-task <TaskID>
+       checkpoint  /loom-works:checkpoint-task <TaskID>
+
+  --prompt       prompt LETTERALE, per chi lo ha già composto (o fatto
+                 modificare). Esclusivo con --prompt-kind; vuoto = nessun
+                 prompt. Ammesso anche con --no-task: un testo già scritto non
+                 ha una task da nominare, a differenza dei kind del catalogo
+
+  --model        modello della sessione: fable|opus|sonnet|haiku
+                 (default: il modello del kind in catalogo, o 'fable' fuori catalogo)
+                 valore ignoto → fallback sul default, con avviso su stderr
+
+  --title-note   nota della conversazione, appesa al titolo tab
+                 (ridotta a lettere/cifre/spazi/-/_, cap 60 char)
+
+  --new-window   apre una FINESTRA nuova invece di una tab nella finestra
+                 attiva. Per chi chiama da fuori dalla finestra del progetto`;
+/** I flag che portano un valore, nel campo della richiesta che lo riceve. */
+const VALUED = {
+    '--model': 'model',
+    '--title-note': 'titleNote',
+    '--prompt-kind': 'promptKind',
+    '--prompt': 'promptText',
+    '--session-id': 'sessionId',
+    '--resume': 'resumeId',
+};
+function usageError(...lines) {
+    return { lines: [...lines, USAGE] };
+}
+/**
+ * L'argv di `deck-run` come richiesta validata, o l'errore d'uso.
+ *
+ * Le due forme di un flag con valore (`--model x` e `--model=x`) valgono uguale;
+ * un argomento che non è un flag noto è il TaskID se il TaskID non c'è ancora,
+ * altrimenti un errore — anche `--qualcosa`, come nello script.
+ *
+ * L'ordine delle validazioni è quello dello script, perché è l'ordine in cui un
+ * chiamante riceve i messaggi quando più regole sono violate insieme.
+ */
+export function parseTabArgs(argv) {
+    const req = {
+        task: '',
+        noTask: false,
+        sessionId: '',
+        resumeId: '',
+        fork: false,
+        newWindow: false,
+        titleNote: '',
+        promptKind: '',
+        promptText: '',
+        promptGiven: false,
+        model: '',
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        const eq = arg.indexOf('=');
+        const name = eq > 0 ? arg.slice(0, eq) : arg;
+        const field = VALUED[name];
+        if (field) {
+            let value;
+            if (eq > 0)
+                value = arg.slice(eq + 1);
+            else if (i + 1 < argv.length)
+                value = argv[++i];
+            else
+                return usageError(`${name} richiede un valore`);
+            req[field] = value;
+            if (field === 'promptText')
+                req.promptGiven = true;
+            continue;
+        }
+        if (arg === '--fork')
+            req.fork = true;
+        else if (arg === '--no-task')
+            req.noTask = true;
+        else if (arg === '--new-window')
+            req.newWindow = true;
+        else if (!req.task)
+            req.task = arg;
+        else
+            return { lines: [`argomento inatteso: '${arg}'`] };
+    }
+    if (req.noTask && req.task) {
+        return usageError('--no-task e <TaskID> sono mutuamente esclusivi');
+    }
+    if (!req.noTask && !req.task)
+        return usageError();
+    if (req.fork && !req.resumeId) {
+        return usageError('--fork richiede --resume <uuid>: si forka una conversazione esistente, non il nulla');
+    }
+    // Una ripresa nuda riscrive il transcript dell'id ripreso, quindi un id
+    // pinnato non ha senso; il fork apre un transcript NUOVO, che si può pinnare.
+    if (req.resumeId && req.sessionId && !req.fork) {
+        return usageError('--resume e --session-id sono mutuamente esclusivi (la sessione ripresa ha già il suo id)', 'usa --fork se vuoi un ramo con id nuovo');
+    }
+    // Un kind fuori catalogo è un errore del CHIAMANTE (simbolo interno, non
+    // configurazione utente): uscita, non fallback silenzioso come il modello.
+    if (req.promptKind && !PROMPT_KINDS.includes(req.promptKind)) {
+        return usageError(`--prompt-kind ignoto: '${req.promptKind}' (usa ${PROMPT_KINDS.join('|')})`);
+    }
+    // Ogni prompt del catalogo nomina il TaskID: senza task produrrebbe un
+    // comando monco (`/loom-works:run-task ` con l'id vuoto). Il testo letterale
+    // invece è ammesso con `--no-task` (T134/D9): non ha una task da nominare.
+    if (req.noTask && req.promptKind) {
+        return usageError('--prompt-kind richiede una task: una sessione --no-task non ha prompt iniziale');
+    }
+    // Due modi di dire la stessa cosa: accettarli insieme obbligherebbe a
+    // stabilire quale vince.
+    if (req.promptGiven && req.promptKind) {
+        return usageError('--prompt e --prompt-kind sono mutuamente esclusivi (il testo o il simbolo, non entrambi)');
+    }
+    return req;
+}
+export function isUsageError(r) {
+    return 'lines' in r;
+}

package/dist/tab-compose.js

@@ -0,0 +1,233 @@
+// T176 — la COMPOSIZIONE di una tab di conversazione: dai quattro assi di
+// `deck-run` (`tab-args.ts`) a titolo, flag di `claude`, env di sessione e
+// comando in-tab.
+//
+// Un composer solo per Linux e Windows (D1 preflight). Cambia per piattaforma
+// solo CHI riceve il risultato: su Linux una riga per `bash -lc` dentro una tab
+// Ptyxis, su Windows l'argv di `claude` in una variabile d'ambiente letta dal
+// wrapper della tab (`windows-terminal.ts`). Titolo, modello, permission mode e
+// prompt si risolvono qui una volta, per entrambe.
+//
+// Modulo PURO: il file di progetto, il catalogo dei prompt e l'env arrivano già
+// letti. Le regole e i messaggi sono quelli dello script bash che questo modulo
+// ha sostituito, e il gate di parità su Linux (`test/deck-run.test.ts`) li
+// misura sul comando in-tab.
+import { saneNote } from './sane-note.js';
+import { MODEL_DEFAULT, MODELS } from './spawn-catalog.js';
+import { shellQuote } from './spawn.js';
+export const PERMISSION_MODES = ['acceptEdits', 'auto', 'bypassPermissions', 'manual', 'dontAsk', 'plan'];
+/** L'alfabeto della chiave di stato: il valore entra in `bash -lc "…"` e il
+ *  file di progetto è editabile a mano, quindi si scarta invece di quotare. */
+const STATE_KEY_RE = /^[A-Za-z0-9_-]+$/;
+/**
+ * Un campo del file di progetto come lo leggeva `jq -r '.campo // empty'`:
+ * `null`, `false` o assente danno vuoto, una stringa passa com'è, ogni altro
+ * valore diventa il suo JSON (`jq -r` stampa così numeri e oggetti).
+ */
+function configField(config, key) {
+    if (!config || typeof config !== 'object' || Array.isArray(config))
+        return '';
+    const v = config[key];
+    if (v === undefined || v === null || v === false)
+        return '';
+    return typeof v === 'string' ? v : JSON.stringify(v);
+}
+/**
+ * La label del progetto, `{emoji} {name}`: la chiave con cui compass riconosce
+ * la finestra cercando nel titolo della tab attiva. Vuota se il file manca o
+ * non porta entrambi i campi, e il titolo ricade su `cc`.
+ */
+export function projectLabel(config) {
+    const emoji = configField(config, 'emoji');
+    const name = configField(config, 'name');
+    return emoji && name ? `${emoji} ${name}` : '';
+}
+/**
+ * Il titolo della tab: label + `· <task>` + nota + `· fork`.
+ *
+ * La label sta in TESTA perché il match di compass è un `.includes` sulla
+ * chiave, e tutto il resto va in coda per non spezzarla. Il suffisso task
+ * distingue le tab di più task, la nota (T64) quelle di più conversazioni sulla
+ * stessa task, `· fork` (T28) un ramo dalla sua origine. La nota è l'unico testo
+ * libero del titolo: non si quota, si RIDUCE (`saneNote`) — e ridotta a vuoto
+ * non lascia nessun suffisso.
+ */
+export function tabTitle(req, label) {
+    let title;
+    if (req.noTask)
+        title = label || 'cc';
+    else
+        title = label ? `${label} · ${req.task}` : `cc ${req.task}`;
+    if (req.titleNote) {
+        const note = saneNote(req.titleNote);
+        if (note)
+            title = `${title} ${note}`;
+    }
+    if (req.fork)
+        title = `${title} · fork`;
+    return title;
+}
+/**
+ * Il permission mode: env `LOOM_DECK_PERMISSION_MODE` > campo del file > `manual`.
+ *
+ * Passato SEMPRE al CLI, anche `manual`: lo spawn resta deterministico invece
+ * di dipendere da un default che cambia fra versioni. Un valore fuori elenco
+ * non arriva al CLI — produrrebbe una tab con un comando rotto — e degrada a
+ * `manual` con un avviso.
+ */
+function permissionMode(ctx, warnings) {
+    const raw = ctx.env.LOOM_DECK_PERMISSION_MODE || configField(ctx.config, 'permissionMode');
+    if (!raw)
+        return 'manual';
+    if (PERMISSION_MODES.includes(raw))
+        return raw;
+    warnings.push(`permissionMode ignoto: '${raw}' → fallback 'manual'`);
+    return 'manual';
+}
+/**
+ * Il kind di catalogo effettivo: solo sul ramo bound senza prompt letterale.
+ * `--no-task` e `--prompt` non hanno una riga di catalogo da consultare, né per
+ * il prompt né per il modello.
+ */
+function catalogKind(req) {
+    return !req.promptGiven && !req.noTask ? req.promptKind || 'recap' : '';
+}
+/**
+ * Il modello: `--model` > env `LOOM_DECK_MODEL` > modello del kind nel catalogo
+ * > `MODEL_DEFAULT`.
+ *
+ * Il deck TUI passa SEMPRE `--model` già risolto (T161), quindi dal deck la
+ * cascata si ferma al primo gradino: i tre sotto servono a chi invoca a mano.
+ * Le voci restano ALIAS fino dentro `claude --model`: un id versionato cablato
+ * qui diventerebbe un modello inesistente al primo cambio di generazione. Un
+ * valore ignoto degrada al default con un avviso — arriverebbe al CLI, che lo
+ * rifiuterebbe all'avvio.
+ */
+function modelOf(req, ctx, warnings) {
+    let model = req.model || ctx.env.LOOM_DECK_MODEL || '';
+    const kind = catalogKind(req);
+    if (!model && kind && kind !== 'none')
+        model = ctx.catalog.get(kind)?.model ?? '';
+    if (!model)
+        return MODEL_DEFAULT;
+    if (MODELS.includes(model))
+        return model;
+    warnings.push(`modello ignoto: '${model}' → fallback '${MODEL_DEFAULT}' (usa ${MODELS.join('|')})`);
+    return MODEL_DEFAULT;
+}
+/**
+ * Il prompt iniziale, vuoto = nessun prompt.
+ *
+ * `--prompt` vince su tutto ed è usato così com'è. Una sessione nuda senza
+ * `--prompt` non ha prompt: il default `recap` del catalogo non si applica,
+ * perché ogni template interpola `{TASK}` e con la task vuota sarebbe un
+ * comando monco. Sul ramo bound il kind sceglie il template; un catalogo che
+ * non ha la voce è un'installazione mutila, e la sessione parte senza prompt
+ * dicendolo. `LOOM_DECK_ENTER_PROMPT` vince sul kind, tranne su `none`.
+ */
+function promptOf(req, ctx, warnings) {
+    if (req.promptGiven)
+        return req.promptText;
+    if (req.noTask)
+        return '';
+    const kind = catalogKind(req);
+    if (kind === 'none')
+        return '';
+    const enter = ctx.env.LOOM_DECK_ENTER_PROMPT;
+    const template = ctx.catalog.get(kind)?.template;
+    if (template === undefined) {
+        warnings.push(`catalogo prompt non leggibile ('${ctx.catalogPath}'): sessione senza prompt iniziale`);
+    }
+    const text = enter || template || '';
+    return text.replaceAll('{TASK}', req.task);
+}
+/**
+ * La chiave di stato per compass, solo su Linux: env `LOOM_DECK_STATE_PROFILE`
+ * (anche vuota = nessun annuncio) > `id` del file di progetto.
+ *
+ * Lo stato di una sessione viaggia verso compass via D-Bus keyed su
+ * `PTYXIS_PROFILE`, e compass lo associa a un progetto solo se la chiave è l'`id`
+ * di un progetto del registry. Senza la variabile forzata in-tab, Ptyxis ne
+ * esporterebbe una col valore del profilo di default, e il badge resterebbe
+ * fermo senza nessun errore. Il nome della variabile è storico: non contiene
+ * l'UUID di un profilo. Su Windows compass non esiste, e la chiave non serve.
+ */
+function stateKey(ctx, warnings) {
+    if (ctx.platform === 'win32')
+        return '';
+    const raw = ctx.env.LOOM_DECK_STATE_PROFILE !== undefined
+        ? ctx.env.LOOM_DECK_STATE_PROFILE
+        : configField(ctx.config, 'id');
+    if (raw && !STATE_KEY_RE.test(raw)) {
+        warnings.push(`profilo di stato ignorato (caratteri non ammessi): '${raw}'`);
+        return '';
+    }
+    return raw;
+}
+/** Un testo come UN argomento di una shell POSIX: sempre fra apici singoli, con
+ *  l'apice stesso chiuso, escapato e riaperto (`'\''`). Dentro gli apici nessun
+ *  altro carattere resta speciale, newline compresi. */
+export function posixQuote(text) {
+    return `'${text.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * La composizione intera.
+ *
+ * Ordine degli argomenti di `claude`: nome, permission mode e modello prima dei
+ * flag di continuità, il prompt sempre ultimo. Il modello sta accanto al
+ * permission mode perché sono la stessa cosa — la scelta di chi apre la
+ * sessione — e non una proprietà della task né della ripresa.
+ *
+ * Su una ripresa il prompt salta anche sul ramo bound: riprendere significa
+ * continuare la conversazione, non iniettarle un messaggio nuovo; il fork è una
+ * ripresa con id nuovo e ricade nello stesso ramo. Il `--session-id` vale invece
+ * anche sul ramo nudo: nel fork di una sessione spot rende noto in anticipo
+ * l'id del ramo, senza il quale il lineage non sarebbe registrabile.
+ */
+export function composeTab(req, ctx) {
+    const warnings = [];
+    const title = tabTitle(req, projectLabel(ctx.config));
+    const mode = permissionMode(ctx, warnings);
+    const model = modelOf(req, ctx, warnings);
+    const key = stateKey(ctx, warnings);
+    const prompt = promptOf(req, ctx, warnings);
+    const withPrompt = prompt !== '' && !req.resumeId;
+    const flags = ['--permission-mode', mode, '--model', model];
+    if (req.sessionId)
+        flags.push('--session-id', req.sessionId);
+    if (req.resumeId)
+        flags.push('--resume', req.resumeId);
+    if (req.fork)
+        flags.push('--fork-session');
+    const sessionEnv = {};
+    if (key)
+        sessionEnv.PTYXIS_PROFILE = key;
+    if (!req.noTask)
+        sessionEnv.LOOM_TASK = req.task;
+    // La riga in-tab nella grafia storica dello script: ogni flag seguito da uno
+    // spazio, il prompt in coda fra apici. Il gate di parità su Linux confronta
+    // questa riga byte per byte, spazio finale compreso quando il prompt manca.
+    const envPrefix = Object.entries(sessionEnv)
+        .map(([k, v]) => `${k}=${shellQuote(v)} `)
+        .join('');
+    const flagText = flags.map((f) => `${f} `).join('');
+    const inTab = `${envPrefix}claude --name ${posixQuote(title)} ${flagText}` +
+        (withPrompt ? posixQuote(prompt) : '');
+    return {
+        title,
+        claudeArgs: ['--name', title, ...flags, ...(withPrompt ? [prompt] : [])],
+        sessionEnv,
+        inTab,
+        warnings,
+    };
+}
+/**
+ * L'argv di Ptyxis: una tab nella finestra attiva (quella col focus, cioè il
+ * deck), o una finestra nuova con `--new-window` (T162) per chi chiama da fuori
+ * dalla finestra del progetto. Il comando gira dentro `bash -lc`, e le env di
+ * sessione viaggiano DENTRO il comando: `ptyxis --tab` consegna la tab
+ * all'istanza già aperta, che non eredita l'env di chi la chiede.
+ */
+export function ptyxisArgv(newWindow, workdir, title, inTab) {
+    return [newWindow ? '--new-window' : '--tab', '-d', workdir, '-T', title, '--', 'bash', '-lc', inTab];
+}