talos-code 0.0.1 → 0.1.0

package/vendor/harness-ui/src/task-catalog.mjs

@@ -0,0 +1,65 @@
+/**
+ * task-catalog.mjs — quali task sono LANCIABILI da Harness UI, e come
+ * ottenere una cartella vera per farli girare. Piano
+ * `elegant-spinning-dongarra.md`, FASE 1, §1.5 (Opzione A).
+ *
+ * ⛔⛔ ALLOWLIST STRETTA, stesso principio di `path-policy.mjs`: un id che non
+ * è testualmente uno dei task del corpus non produce MAI una cartella. Prima
+ * di questo file, Harness UI era read-only per costruzione (`http-app.mjs`
+ * rifiuta ogni metodo che non sia GET/HEAD) — questo è il PRIMO punto dove
+ * un browser può far succedere qualcosa di reale sul disco, quindi l'elenco
+ * ammesso non è "qualunque cartella passi", è SOLO ciò che è già nel corpus.
+ *
+ * Il catalogo non possiede più un corpus implicito: riceve un provider
+ * esplicito dal runtime configurato. Senza provider il risultato è
+ * `TASK_CATALOG_UNAVAILABLE`, non una fixture o un import da un checkout
+ * fratello. Questo mantiene la promessa di portabilità del desktop.
+ */
+export class TaskCatalogError extends Error {
+  constructor(message, code = 'TASK_NOT_ALLOWED') {
+    super(message);
+    this.name = 'TaskCatalogError';
+    this.code = code;
+  }
+}
+
+function providerRequired(provider) {
+  if (!provider || typeof provider.list !== 'function' || typeof provider.prepare !== 'function') {
+    throw new TaskCatalogError('Il catalogo task non è disponibile in questa installazione. Configura il runtime proprietario.', 'TASK_CATALOG_UNAVAILABLE');
+  }
+  return provider;
+}
+
+/**
+ * Un elenco LEGGERO — mai il corpo intero della consegna, che può essere
+ * lungo (i task storia, quando arriveranno, elencano casi di test interi).
+ * Chi avvia una sessione riceve la consegna vera da `preparaEsecuzione`, non
+ * da qui: questa funzione è per un menu, non per lanciare niente.
+ */
+export function listaTaskDisponibili(provider) {
+  return providerRequired(provider).list().map((task) => ({
+    id: task.id,
+    progetto: task.progetto,
+    difficolta: task.difficolta,
+    consegnaCorta: task.consegnaCorta,
+  }));
+}
+
+/**
+ * Da un id ammesso a una cartella VERA e usa-e-getta, pronta per
+ * `talosLavora`. Lancia `TaskCatalogError` su qualunque id che non sia
+ * ESATTAMENTE uno dei task del corpus — nessuna normalizzazione, nessun
+ * fallback: lo stesso stile di `assertSafeSegment` in `path-policy.mjs`.
+ *
+ * @returns {{cartella:string, comandoProva:string, task:object, pulisci:()=>void}}
+ */
+export function preparaEsecuzione(taskId, provider) {
+  if (typeof taskId !== 'string' || taskId.length === 0) {
+    throw new TaskCatalogError('Id task non valido', 'QUERY_INVALID');
+  }
+  const risultato = providerRequired(provider).prepare(taskId);
+  if (!risultato || typeof risultato !== 'object' || typeof risultato.cartella !== 'string' || !risultato.task) {
+    throw new TaskCatalogError('Il catalogo task ha restituito una sessione non valida.', 'TASK_CATALOG_INVALID');
+  }
+  return risultato;
+}

package/vendor/harness-ui/src/tasks-store.mjs

@@ -0,0 +1,220 @@
+/**
+ * tasks-store.mjs — FASE N, quinto sistema (30/8), piano
+ * `elegant-spinning-dongarra.md`. Owner: "TUTTI i 5 sistemi rimasti, uno
+ * dopo l'altro".
+ *
+ * ⛔⛔⛔ GLOBALE, non per-progetto — stesso principio di notes-store.mjs
+ * (letto alla fonte: `mobile/src/lib/tools/tasksWriteTools.ts`+
+ * `readTools.ts`, `mobile/src/persistence/chatDatabaseSchema.ts`).
+ * "Ricordami di chiamare l'idraulico" non riguarda nessun progetto di
+ * codice — un desktop che rendesse le attività per-progetto le
+ * renderebbe invisibili da qualunque altra sessione. Storage accanto a
+ * `server.mjs`, stesso pattern REALE di `.automations/`/`.notes-store/`.
+ *
+ * ⛔ `schedule_json`/`instruction`/`last_run_at` (schema mobile
+ * `talos_tasks`) NON portati: colonne presenti nello schema mobile ma
+ * NON esposte da NESSUN tool mobile oggi ("pianificare aggiungerà un
+ * campo, non un'altra entità" — mai arrivato, verificato leggendo
+ * `TalosTasksWriteSources` per intero, zero riferimento a schedule).
+ * Harness Desktop ha già un proprio sistema di scheduling (Automazioni,
+ * `automation-store.mjs`, chiuso 27/8) — quando/se un task deve
+ * ripartire da solo, quella è la casa giusta, non una seconda qui.
+ *
+ * ⛔ Stessa CONVENZIONE DI CHIAMATA di `notes-store.mjs`/`library-store.mjs`
+ * (`funzione({cartella, ...}, deps={})`), per lo stesso motivo: va
+ * agganciato negli stessi punti di contatto I/O iniettabili di
+ * `agent-service.mjs`.
+ *
+ * ⛔ Un file JSON per attività (non un unico array) — stessa classe di
+ * bug (riscrittura invece di accodamento) già evitata altrove in
+ * questo progetto (session-store.mjs).
+ */
+import { randomUUID } from 'node:crypto';
+import { promises as fsp } from 'node:fs';
+import { join } from 'node:path';
+import { idArchivioValido } from './id-archivio.mjs';
+
+const TITOLO_MASSIMO = 200;
+const DESCRIZIONE_MASSIMA = 2_000;
+const PRIORITA = Object.freeze(['low', 'normal', 'high']);
+const STATI = Object.freeze(['todo', 'doing', 'done']);
+
+/** ⭐ Stesso pattern REALE di `.automations/`/`.notes-store/`: il nome che `server.mjs` userà per il percorso di default, esportato per non duplicarlo lì. */
+export const CARTELLA_ATTIVITA = '.tasks-store';
+
+export class TaskStoreError extends Error {
+  constructor(message, code = 'TASK_INVALID') {
+    super(message);
+    this.name = 'TaskStoreError';
+    this.code = code;
+  }
+}
+
+function percorsoDi(cartella, id) {
+  // ⛔ 14/09: l'id arriva da fuori (indirizzo HTTP, attrezzo del modello) — un id fuori grammatica non nomina nessun file e
+  //   torna `null`, mai un `join` che con `..` uscirebbe dalla cartella. Vedi id-archivio.mjs.
+  if (!idArchivioValido(id)) return null;
+  return join(cartella, `${id}.json`);
+}
+
+function validaTitolo(title) {
+  if (typeof title !== 'string' || title.trim().length === 0 || title.length > TITOLO_MASSIMO) {
+    throw new TaskStoreError(`title deve avere 1-${TITOLO_MASSIMO} caratteri`, 'TASK_INVALID');
+  }
+  return title.trim();
+}
+
+/** `null`/assente sono la stessa cosa (nessun dettaglio) — una descrizione fatta di soli spazi diventa `null`, stesso principio del tool mobile. */
+function validaDescrizione(description) {
+  if (description === undefined || description === null) return null;
+  if (typeof description !== 'string' || description.length > DESCRIZIONE_MASSIMA) {
+    throw new TaskStoreError(`description deve avere al massimo ${DESCRIZIONE_MASSIMA} caratteri`, 'TASK_INVALID');
+  }
+  return description.trim() || null;
+}
+
+function validaPriorita(priority) {
+  if (!PRIORITA.includes(priority)) {
+    throw new TaskStoreError(`priority deve essere una fra ${PRIORITA.join('/')}`, 'TASK_INVALID');
+  }
+  return priority;
+}
+
+function validaStato(status) {
+  if (!STATI.includes(status)) {
+    throw new TaskStoreError(`status deve essere uno fra ${STATI.join('/')}`, 'TASK_INVALID');
+  }
+  return status;
+}
+
+/*
+ * ⛔ 11/09 — CHI ha scritto questa attività, stesso identico principio (e stesso default) di
+ *   `ORIGINI` in notes-store.mjs: due porte sole — gli attrezzi `tasks_*` del modello e le
+ *   rotte HTTP della persona — e ciò che è già sul disco viene tutto dal modello, perché fino
+ *   a oggi la persona non aveva una porta per scrivere.
+ */
+const ORIGINI = Object.freeze(['persona', 'modello']);
+
+function validaOrigine(origine) {
+  if (!ORIGINI.includes(origine)) {
+    throw new TaskStoreError(`origine deve essere una fra ${ORIGINI.join('/')}`, 'TASK_INVALID');
+  }
+  return origine;
+}
+
+/**
+ * La forma PUBBLICA di un'attività — l'unica che esce da questo prodotto.
+ * ⛔ `fatta` è CALCOLATA da `stato`, mai scritta sul disco: due campi che dicono la stessa cosa
+ *   e possono divergere sono un difetto, non una comodità. Esce dalla porta perché un pannello
+ *   ha bisogno di una casella da spuntare, ma la verità resta una sola (`stato`).
+ * ⛔ Nessuna `scadenza`: non esiste in questo magazzino e non esiste in nessun attrezzo del
+ *   modello (vedi l'intestazione di questo file sulle colonne mobile NON portate). Inventarla
+ *   qui vorrebbe dire un campo che solo la persona può scrivere e che il modello non vedrà mai
+ *   — la asimmetria che questo porto esiste per evitare.
+ */
+export function formaPubblicaAttivita(voce) {
+  return {
+    id: voce.id,
+    titolo: voce.titolo,
+    descrizione: voce.descrizione ?? null,
+    stato: voce.stato,
+    fatta: voce.stato === 'done',
+    priorita: voce.priorita,
+    creataAlle: voce.creataAlle ?? null,
+    aggiornataAlle: voce.aggiornataAlle ?? null,
+    origine: ORIGINI.includes(voce.origine) ? voce.origine : 'modello',
+  };
+}
+
+/** Più recentemente aggiornate per prime — stesso ordine di `tasks_list` mobile. Cartella assente ⇒ `[]`, mai un errore. */
+export async function elencaAttivita({ cartella }, deps = {}) {
+  const readdirFn = deps.readdirFn ?? fsp.readdir;
+  const readFileFn = deps.readFileFn ?? fsp.readFile;
+  let nomi;
+  try {
+    nomi = await readdirFn(cartella);
+  } catch {
+    return [];
+  }
+  const voci = [];
+  for (const nome of nomi) {
+    if (!nome.endsWith('.json')) continue;
+    try {
+      voci.push(JSON.parse(await readFileFn(join(cartella, nome), 'utf8')));
+    } catch { /* una voce corrotta non deve nascondere le altre */ }
+  }
+  return voci.sort((a, b) => b.aggiornataAlle.localeCompare(a.aggiornataAlle) || a.id.localeCompare(b.id));
+}
+
+/** Un id assente torna `null`, mai un'eccezione. */
+export async function leggiAttivita({ cartella, id }, deps = {}) {
+  const readFileFn = deps.readFileFn ?? fsp.readFile;
+  const percorso = percorsoDi(cartella, id);
+  if (!percorso) return null; // ⛔ 14/09: id fuori grammatica = «non c'è», mai una lettura fuori dalla cartella
+  try {
+    return JSON.parse(await readFileFn(percorso, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** @returns l'attività creata: `{id, titolo, descrizione, priorita, stato:'todo', creataAlle, aggiornataAlle}`. @throws {TaskStoreError} TASK_INVALID PRIMA di ogni I/O. */
+export async function creaAttivita({ cartella, title, description, priority = 'normal', origine = 'modello' }, deps = {}) {
+  const titolo = validaTitolo(title);
+  const descrizione = validaDescrizione(description);
+  const priorita = validaPriorita(priority);
+  const daChi = validaOrigine(origine);
+  const mkdirFn = deps.mkdirFn ?? fsp.mkdir;
+  const writeFileFn = deps.writeFileFn ?? fsp.writeFile;
+  const clockFn = deps.clockFn ?? (() => new Date());
+  const ora = clockFn().toISOString();
+  const voce = { id: randomUUID(), titolo, descrizione, priorita, stato: 'todo', origine: daChi, creataAlle: ora, aggiornataAlle: ora };
+  await mkdirFn(cartella, { recursive: true });
+  await writeFileFn(percorsoDi(cartella, voce.id), JSON.stringify(voce, null, 2), 'utf8');
+  return voce;
+}
+
+/**
+ * Solo title/description/priority — MAI lo stato (quello è
+ * `completaAttivita`, stesso confine del tool mobile: "Do NOT use this
+ * to mark something done"). Solo i campi passati cambiano.
+ * @throws {TaskStoreError} TASK_NOT_FOUND se l'id non esiste.
+ */
+export async function aggiornaAttivita({ cartella, id, title, description, priority }, deps = {}) {
+  const readFileFn = deps.readFileFn ?? fsp.readFile;
+  const mkdirFn = deps.mkdirFn ?? fsp.mkdir;
+  const writeFileFn = deps.writeFileFn ?? fsp.writeFile;
+  const clockFn = deps.clockFn ?? (() => new Date());
+  const voce = await leggiAttivita({ cartella, id }, { readFileFn });
+  if (!voce) throw new TaskStoreError(`nessuna attività con id ${id}`, 'TASK_NOT_FOUND');
+  if (title !== undefined) voce.titolo = validaTitolo(title);
+  if (description !== undefined) voce.descrizione = validaDescrizione(description);
+  if (priority !== undefined) voce.priorita = validaPriorita(priority);
+  voce.aggiornataAlle = clockFn().toISOString();
+  await mkdirFn(cartella, { recursive: true });
+  await writeFileFn(percorsoDi(cartella, id), JSON.stringify(voce, null, 2), 'utf8');
+  return voce;
+}
+
+/** Cambia SOLO lo stato — tool a parte sul mobile perché "è la cosa che si fa più spesso, e di gran lunga". @throws {TaskStoreError} TASK_NOT_FOUND se l'id non esiste. */
+export async function completaAttivita({ cartella, id, status = 'done' }, deps = {}) {
+  const readFileFn = deps.readFileFn ?? fsp.readFile;
+  const mkdirFn = deps.mkdirFn ?? fsp.mkdir;
+  const writeFileFn = deps.writeFileFn ?? fsp.writeFile;
+  const clockFn = deps.clockFn ?? (() => new Date());
+  const voce = await leggiAttivita({ cartella, id }, { readFileFn });
+  if (!voce) throw new TaskStoreError(`nessuna attività con id ${id}`, 'TASK_NOT_FOUND');
+  voce.stato = validaStato(status);
+  voce.aggiornataAlle = clockFn().toISOString();
+  await mkdirFn(cartella, { recursive: true });
+  await writeFileFn(percorsoDi(cartella, id), JSON.stringify(voce, null, 2), 'utf8');
+  return voce;
+}
+
+/** Idempotente — un id già assente non è un errore, è l'esito voluto ottenuto da qualcun altro. */
+export async function eliminaAttivita({ cartella, id }, deps = {}) {
+  const rmFn = deps.rmFn ?? fsp.rm;
+  const percorso = percorsoDi(cartella, id);
+  if (!percorso) return; // ⛔ 14/09: un id che non può nominare un file è già «assente» — no-op idempotente
+  await rmFn(percorso, { force: true });
+}

package/vendor/harness-ui/src/terminal-registry.mjs

@@ -0,0 +1,312 @@
+/**
+ * terminal-registry.mjs — W1-01 (05/09). Il registro che decide **CHI può
+ * attaccarsi a quale PTY**. Ledger: `.claude/LEDGER-W1-01-SCHEDE-TERMINALE-2026-09-05.md`.
+ *
+ * ⛔⛔⛔ Perché è un modulo A PARTE da `pty-terminal.mjs`: quello è il ciclo
+ * di vita di una PTY (spawn, backlog, reap); questo è **autorizzazione**.
+ * Fino al 04/9 le due cose erano la stessa cosa perché l'id della PTY *era*
+ * il `sessionId`, quindi non c'era niente da autorizzare. Nel momento in cui
+ * una sessione può avere PIÙ schede, il `terminalId` diventa un identificativo
+ * scelto dal client — ed è esattamente la forma di difetto che ha prodotto
+ * **CVE-2026-59224** (Open WebUI, 2026 —
+ * github.com/advisories/GHSA-j657-m4c4-24jq, letto il 05/09/2026): il proxy
+ * WebSocket del terminale costruiva l'URL a monte concatenando il `session_id`
+ * ricevuto dal client senza validarlo, e con un id vivo ci si **agganciava
+ * alla PTY di un'altra persona**. L'identità inoltrata era una pretesa
+ * «bearer», senza legame di integrità.
+ *
+ * ⇒ Il principio NON NEGOZIABILE di questo file: **il `terminalId` non decide
+ * MAI la cartella**. La cartella si risolve UNA volta, alla creazione, dalla
+ * sessione vera (`cartellaDiSessione`), e da lì resta congelata nella voce.
+ * Il client può solo NOMINARE un terminale che il server gli ha già dato.
+ * È la cura standard per IDOR/BOLA — OWASP API1:2023 Broken Object Level
+ * Authorization, oggi #1: «l'API si fida di un identificativo fornito dal
+ * client senza verificare che il chiamante possa accedere a QUELL'oggetto»
+ * (ricerca 05/09/2026).
+ *
+ * ⛔ Il difetto misurato che questo file chiude, `server.mjs:589` prima di oggi:
+ *
+ *     risolviCartella: (id) => sessionRegistry.cartellaDi(id)
+ *       ?? config.cartelleProgetto[0]?.percorso ?? process.cwd()
+ *
+ * Un id **sconosciuto** non veniva rifiutato: cadeva sul primo progetto
+ * configurato. Con l'id legato al `sessionId` il danno era contenuto; con un
+ * `terminalId` libero **qualunque stringa apriva una shell**. Qui quel `??`
+ * non esiste: `risolviPerConnessione()` torna `null`, e chi lo chiama rifiuta.
+ *
+ * ⛔ Il tetto per sessione NON è burocrazia: su Windows ogni PTY porta con sé
+ * un processo `conhost` (node-pty#471, ConPTY — letto il 05/09/2026), e
+ * `conhost` è noto per sopravvivere alla morte del processo figlio. Schede
+ * illimitate = processi di sistema illimitati.
+ */
+import { randomUUID } from 'node:crypto';
+
+/**
+ * Tetto di schede per sessione. Otto: abbastanza per il lavoro vero (build,
+ * test, log, un paio di scratch), abbastanza poco da non lasciare in giro
+ * decine di `conhost` su Windows. ⛔ Dichiarato, non indovinato a runtime.
+ */
+export const SCHEDE_MASSIME_PER_SESSIONE = 8;
+
+/*
+ * ⛔⛔ Quanto vive una scheda DIMENTICATA — 24 ore dall'ultimo aggancio.
+ *
+ * Il registro delle PTY ha gia' il suo reaper, ma chiude la SHELL, non la
+ * scheda: e' voluto, perche' un F5 dieci minuti dopo deve riaprire nella
+ * cartella giusta invece di prendere un 403. Il prezzo era che le schede non
+ * si dimenticavano MAI: su un server acceso per settimane e' crescita lenta,
+ * e non era misurata da nessuno.
+ *
+ * ⛔ Il tetto e' molto piu' lungo della grazia delle PTY, di proposito: dopo
+ * la scadenza una riconnessione riceve 403, quindi il numero non e' un
+ * dettaglio di implementazione ma una PROMESSA — «una scheda che non tocchi
+ * per un giorno non c'e' piu'». Lo stato dell'arte dice esattamente questo:
+ * la scadenza si applica lato SERVER, con una politica di durata dichiarata,
+ * e la pulizia si programma invece di affidarla al caso (una GC probabilistica
+ * puo' non passare mai). Ricerca del 05/09/2026:
+ * cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html ·
+ * modelcontextprotocol.io/seps/2567-sessionless-mcp
+ *
+ * ⛔ E una scheda tolta in SILENZIO sarebbe il difetto peggiore di quello che
+ * cura: `reap()` torna chi ha tolto e perche', e `misura()` dice quante ne
+ * esistono adesso — un problema di dimensionamento che nessuno puo' vedere
+ * non e' un problema risolto.
+ */
+export const ORE_PRIMA_DI_DIMENTICARE_UNA_SCHEDA = 24;
+
+/**
+ * Registro delle schede terminale.
+ *
+ * @param {object} deps
+ * @param {(sessionId:string)=>string|null} deps.cartellaDiSessione  L'UNICA autorità sulla cartella. `null` ⇒ la sessione non esiste ⇒ niente terminale.
+ * @param {(terminalId:string)=>void} [deps.chiudiPtyFn]  Chiude la PTY vera quando una scheda viene chiusa esplicitamente.
+ * @param {(terminalId:string)=>{viva:boolean}|null} [deps.statoPtyFn]  Per dire in elenco se la shell è ancora viva, senza esporre la voce interna del registro PTY.
+ * @param {string|null} [deps.cartellaStandaloneLegacy]  ⛔ DEBITO DICHIARATO, vedi `risolviPerConnessione`. `null` (default) = registro STRETTO: un id ignoto si rifiuta e basta.
+ */
+export function creaRegistroSchedeTerminale({
+  cartellaDiSessione,
+  chiudiPtyFn = () => {},
+  statoPtyFn = () => null,
+  cartellaStandaloneLegacy = null,
+  schedeMassimePerSessione = SCHEDE_MASSIME_PER_SESSIONE,
+  orePrimaDiDimenticare = ORE_PRIMA_DI_DIMENTICARE_UNA_SCHEDA,
+  generaId = randomUUID,
+  clock = () => new Date(),
+} = {}) {
+  /** @type {Map<string, {terminalId:string, sessionId:string|null, cartella:string, creatoAlle:string, origine:string}>} */
+  const schede = new Map();
+
+  function schedeDi(sessionId) {
+    return [...schede.values()].filter((voce) => voce.sessionId === sessionId);
+  }
+
+  function pubblica(voce) {
+    return {
+      terminalId: voce.terminalId,
+      sessionId: voce.sessionId,
+      cartella: voce.cartella,
+      creatoAlle: voce.creatoAlle,
+      origine: voce.origine,
+      /* ⛔ Tre stati, non due: `attiva:false` significa "scheda registrata, shell non ancora aperta o già uscita" — mai confuso con "scheda inesistente" (quella non compare proprio). */
+      attiva: statoPtyFn(voce.terminalId)?.viva === true,
+    };
+  }
+
+  /**
+   * Registra la PRIMA scheda di una sessione con `terminalId === sessionId`.
+   *
+   * ⭐ Compatibilità all'indietro OBBLIGATORIA: `public/harness-ui/app.js` è
+   * congelato da un contratto (`frontend/tests/contract/legacy-contract-snapshot.test.mjs`
+   * blocca byte-count e sha256) e si collega a `?id=<sessionId>`. Tenendo la
+   * prima scheda uguale al `sessionId`, il monolite continua a funzionare
+   * **senza una riga di modifica**.
+   *
+   * ⛔ Non è un fallback travestito: la cartella la dà comunque
+   * `cartellaDiSessione()`, cioè il registro delle sessioni. Se la sessione
+   * non esiste, qui non nasce niente.
+   */
+  function registraPrimaScheda(sessionId, cartella) {
+    const voce = {
+      terminalId: sessionId,
+      sessionId,
+      cartella,
+      creatoAlle: clock().toISOString(),
+      ultimoAggancioMs: clock().getTime(),
+      origine: 'prima-scheda',
+    };
+    schede.set(sessionId, voce);
+    return voce;
+  }
+
+  return {
+    /**
+     * Crea una scheda per una sessione VERA. È l'unica porta da cui nasce un
+     * `terminalId` nuovo, e l'id lo sceglie il SERVER (`randomUUID`), mai il
+     * client — un id imprevedibile è metà della cura raccomandata da OWASP
+     * per le WebSocket (il browser non applica la same-origin policy alle WS
+     * come la applica a `fetch`: serve il controllo Origin esplicito **più**
+     * un valore che non si indovina — WebSocket Security Cheat Sheet, letto
+     * il 05/09/2026).
+     */
+    crea({ sessionId } = {}) {
+      if (typeof sessionId !== 'string' || sessionId === '') {
+        return { erroreAvvio: 'Sessione non valida', code: 'QUERY_INVALID' };
+      }
+      const cartella = cartellaDiSessione(sessionId);
+      if (typeof cartella !== 'string' || cartella === '') {
+        /* ⛔ Qui viveva il `??` di server.mjs:589. Una sessione che non esiste non prende una cartella di ripiego: non prende NIENTE. */
+        return { erroreAvvio: 'Sessione non trovata', code: 'NOT_FOUND' };
+      }
+      const gia = schedeDi(sessionId);
+      if (gia.length >= schedeMassimePerSessione) {
+        return { erroreAvvio: `Massimo ${schedeMassimePerSessione} terminali per sessione`, code: 'TERMINAL_LIMIT_REACHED' };
+      }
+      if (gia.length === 0) return pubblica(registraPrimaScheda(sessionId, cartella));
+      let terminalId = generaId();
+      /* ⛔ AL CONTRARIO — un `generaId` che collide (o un test che ne inietta uno fisso) non deve MAI sovrascrivere una scheda viva di qualcun altro. */
+      while (schede.has(terminalId)) terminalId = `${terminalId}-${schede.size}`;
+      const voce = {
+        terminalId,
+        sessionId,
+        cartella,
+        creatoAlle: clock().toISOString(),
+        ultimoAggancioMs: clock().getTime(),
+        origine: 'rotta',
+      };
+      schede.set(terminalId, voce);
+      return pubblica(voce);
+    },
+
+    /** Elenco delle schede di UNA sessione — mai di tutte: una sessione non vede i terminali delle altre. */
+    elenca(sessionId) {
+      if (typeof sessionId !== 'string' || sessionId === '') return { erroreAvvio: 'Sessione non valida', code: 'QUERY_INVALID' };
+      if (cartellaDiSessione(sessionId) === null) return { erroreAvvio: 'Sessione non trovata', code: 'NOT_FOUND' };
+      return { items: schedeDi(sessionId).map(pubblica) };
+    },
+
+    /**
+     * Chiusura ESPLICITA di una scheda: chiude anche la PTY vera.
+     *
+     * ⛔⛔ La proprietà si verifica, non si presume: chiudere un terminale che
+     * appartiene a un'ALTRA sessione risponde `NOT_FOUND` — lo stesso codice di
+     * un terminale inesistente, di proposito. Distinguere «non esiste» da «non
+     * è tuo» regalerebbe a chi prova id a caso una sonda per scoprire quali
+     * esistono (OWASP API1:2023, ricerca 05/09/2026).
+     */
+    chiudi({ sessionId, terminalId } = {}) {
+      if (typeof sessionId !== 'string' || sessionId === '' || typeof terminalId !== 'string' || terminalId === '') {
+        return { erroreAvvio: 'Terminale non valido', code: 'QUERY_INVALID' };
+      }
+      const voce = schede.get(terminalId);
+      if (!voce || voce.sessionId !== sessionId) {
+        return { erroreAvvio: 'Terminale non trovato', code: 'NOT_FOUND' };
+      }
+      chiudiPtyFn(terminalId);
+      schede.delete(terminalId);
+      return { ok: true, terminalId, sessionId };
+    },
+
+    /**
+     * L'UNICA domanda che `terminal-ws.mjs` ha il diritto di fare: «questo id
+     * può attaccarsi, e a quale cartella?». Tre esiti, in quest'ordine:
+     *
+     *  1. **scheda già registrata** → la sua voce, con la cartella congelata
+     *     alla creazione (⛔ mai ri-risolta a ogni connessione: è così che si
+     *     evita che un cambio di stato altrove sposti una shell già aperta);
+     *  2. **id che è un `sessionId` VIVO** → prima scheda di quella sessione,
+     *     registrata al volo. È la porta di compatibilità del monolite
+     *     congelato, e l'autorità resta il registro delle sessioni;
+     *  3. **tutto il resto** → `null`, cioè **rifiuto**. Nessuna PTY nasce.
+     *
+     * ⛔ DEBITO DICHIARATO — `cartellaStandaloneLegacy`. Il monolite congelato
+     * ha una TERZA strada, misurata il 05/09 leggendo `public/app.js` (non
+     * presunta): `idTerminaleCorrente()` fa
+     * `if (state.realSession.id) return state.realSession.id;` e **altrimenti
+     * inventa un `crypto.randomUUID()` lato client** — un terminale
+     * "standalone" senza nessuna sessione, raggiungibile aprendo il tab
+     * Terminale prima di avviare qualsiasi cosa. Quel caso è esattamente ciò
+     * che il `??` di server.mjs teneva in piedi. Qui il default è `null`, cioè
+     * **rifiuto**; chi vuole tenere viva quella funzione del monolite deve
+     * passare una cartella ESPLICITA a costruzione — una riga sola, visibile,
+     * con un tetto suo — invece di una catena di `??` valutata a ogni
+     * connessione. ⛔ Si spegne rimettendo `null` in `server.mjs` il giorno in
+     * cui il frontend nuovo sostituisce il monolite.
+     */
+    risolviPerConnessione(id) {
+      if (typeof id !== 'string' || id === '') return null;
+      const registrata = schede.get(id);
+      if (registrata) {
+        // ⛔ «Ultimo aggancio», non «ultima creazione»: e' l'uso che tiene viva
+        // una scheda, ed e' l'unico momento in cui qualcuno la nomina davvero.
+        registrata.ultimoAggancioMs = clock().getTime();
+        return registrata;
+      }
+      const cartellaSessione = cartellaDiSessione(id);
+      if (typeof cartellaSessione === 'string' && cartellaSessione !== '') {
+        return registraPrimaScheda(id, cartellaSessione);
+      }
+      if (typeof cartellaStandaloneLegacy === 'string' && cartellaStandaloneLegacy !== '') {
+        const standalone = [...schede.values()].filter((voce) => voce.sessionId === null);
+        /* ⛔ Tetto anche qui: senza, «qualunque stringa apre una shell» resterebbe vero per la porta legacy. */
+        if (standalone.length >= schedeMassimePerSessione) return null;
+        const voce = {
+          terminalId: id,
+          sessionId: null,
+          cartella: cartellaStandaloneLegacy,
+          creatoAlle: clock().toISOString(),
+        ultimoAggancioMs: clock().getTime(),
+          origine: 'standalone-legacy',
+        };
+        schede.set(id, voce);
+        return voce;
+      }
+      return null;
+    },
+
+    /**
+     * ⭐⭐⭐ Dimentica le schede che nessuno tocca da `orePrimaDiDimenticare`.
+     *
+     * ⛔ Una scheda si toglie SOLO se la sua shell e' gia' morta: finche' una
+     * PTY e' viva la scheda serve, per lunga che sia l'attesa — buttarla
+     * lascerebbe un processo vivo senza piu' nessuno che possa raggiungerlo,
+     * che e' esattamente la perdita che questa funzione dovrebbe curare.
+     *
+     * ⛔ Torna CHI ha tolto e PERCHE': una scheda sparita in silenzio sarebbe
+     * peggio del problema, perche' la prossima riconnessione riceve 403 e
+     * nessuno saprebbe dire da dove viene.
+     */
+    dimenticaLeVecchie({ adesso = clock().getTime() } = {}) {
+      const limite = orePrimaDiDimenticare * 60 * 60 * 1000;
+      const tolte = [];
+      for (const [terminalId, voce] of [...schede]) {
+        const ferma = adesso - (voce.ultimoAggancioMs ?? 0);
+        if (ferma < limite) continue;
+        const pty = statoPtyFn(terminalId);
+        if (pty && pty.viva) continue;
+        schede.delete(terminalId);
+        tolte.push({ terminalId, sessionId: voce.sessionId, origine: voce.origine, fermaDaMs: ferma });
+      }
+      return { tolte, restano: schede.size };
+    },
+
+    /**
+     * Quante schede esistono adesso, e da quanto tace la piu' vecchia.
+     * ⛔ Serve a vedere un problema di dimensionamento PRIMA che diventi una
+     * perdita: un numero che nessuno puo' leggere non e' una garanzia.
+     */
+    misura({ adesso = clock().getTime() } = {}) {
+      let piuVecchiaMs = null;
+      let conShellViva = 0;
+      for (const [terminalId, voce] of schede) {
+        const ferma = adesso - (voce.ultimoAggancioMs ?? 0);
+        if (piuVecchiaMs === null || ferma > piuVecchiaMs) piuVecchiaMs = ferma;
+        const pty = statoPtyFn(terminalId);
+        if (pty && pty.viva) conShellViva += 1;
+      }
+      return { schede: schede.size, conShellViva, piuVecchiaFermaDaMs: piuVecchiaMs, orePrimaDiDimenticare };
+    },
+
+    /** ⛔ Solo per i test e per lo shutdown — mai per decidere un permesso. */
+    _schede: schede,
+  };
+}