talos-code 0.0.1 → 0.1.0

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

@@ -0,0 +1,312 @@
+/**
+ * pty-terminal.mjs — Terminale REALE, ledger in
+ * `.claude/LEDGER-TERMINALE-REALE.md`. Owner, 28/8: *"deve essere un
+ * terminale vero e proprio bash [...] che non ha limiti [...] usabile
+ * dall'utente con le sue dita umane"* — non il log a righe dei comandi
+ * dell'agente (quello resta, invariato, nel tool-call della chat).
+ *
+ * Ricerca fatta prima di scrivere: su Windows (dove non esiste
+ * un primitivo PTY POSIX nativo), lo stato dell'arte monta Git Bash dentro
+ * una PTY vera — la stessa strategia adottata da altri strumenti dello
+ * stesso tipo.
+ * Verificato empiricamente su QUESTA macchina (non presunto): `node-pty`
+ * include il prebuild `win32-x64` DENTRO il pacchetto npm (zero
+ * compilazione), Git Bash è installato
+ * (`C:\Program Files\Git\bin\bash.exe`, lo stesso binario che questa
+ * sessione usa per il proprio tool Bash), e una sonda reale
+ * (`pty.spawn` + un comando scritto come keystroke) ha prodotto un
+ * prompt MINGW64 vero con sequenze ANSI vere.
+ *
+ * ⛔ Questo modulo NON impone timeout, non tronca l'output, non ha una
+ * allowlist di comandi — a differenza di `eseguiComandoSandboxato`
+ * (l'attrezzo `shell` dato in mano a un MODELLO): qui la shell è in
+ * mano al proprietario della macchina, "non ha limiti" per richiesta
+ * esplicita.
+ */
+import { spawn as spawnPty } from 'node-pty';
+import { existsSync } from 'node:fs';
+
+import { ambienteSenzaVariabiliDelServer } from './ambiente-solo-server.mjs';
+
+/** ⛔ Solo win32: `existsFn` iniettabile per i test, mai una vera ricerca su disco lì. */
+const PERCORSI_GIT_BASH_WINDOWS = [
+  'C:\\Program Files\\Git\\bin\\bash.exe',
+  'C:\\Program Files (x86)\\Git\\bin\\bash.exe',
+];
+
+/**
+ * Tetto del backlog **PER SCHEDA** — un replay alla riconnessione, non uno
+ * storico infinito.
+ *
+ * ⛔⛔ W1-01 (05/9): verificato che il tetto è per voce del registro e non
+ * globale (`voce.byteBacklog` vive dentro la singola voce), perché con più
+ * schede per sessione un tetto globale farebbe sparire il backlog di una
+ * scheda quando ne parla un'altra. Il numero è **200.000 byte per scheda**:
+ * dichiarato, non infinito. Stessa disciplina di VS Code, che limita lo
+ * scrollback ripristinato di una sessione persistente con
+ * `terminal.integrated.persistentSessionScrollback` (default **100 righe**,
+ * code.visualstudio.com/docs/terminal/advanced, letto il 05/09/2026) invece di
+ * rigiocare tutto. ⛔ E il backlog DEVE stare qui: `node-pty` non tiene
+ * scrollback proprio — lo scrollback vive in xterm, lato client, e un F5 lo
+ * azzera (ricerca 05/09/2026).
+ */
+export const BACKLOG_MASSIMO_BYTE = 200_000;
+
+/*
+ * ⛔ 14/09 (F04 della review, riprodotto): il tetto NON si rispettava con un solo pezzo — il vecchio ciclo si fermava a
+ *   `backlog.length > 1`, quindi un `cat` di un file grosso lasciava in memoria un elemento da megabyte PER SCHEDA, e
+ *   il numero dichiarato qui sopra («200.000 byte per scheda, dichiarato, non infinito») era falso proprio nel caso che
+ *   conta. Adesso l'ultimo pezzo si TAGLIA, e si tiene la CODA: è quella che la scheda deve rivedere al rientro.
+ * ⛔ Il taglio è sui byte UTF-8, mai sui caratteri: si entra da destra e si scavalcano i byte di continuazione
+ *   (`10xxxxxx`), perché una sequenza multi-byte spezzata arriverebbe a xterm come `�` — cioè il backlog
+ *   consegnerebbe caratteri che la shell non ha mai scritto.
+ */
+function limitaBacklog(voce) {
+  while (voce.byteBacklog > BACKLOG_MASSIMO_BYTE && voce.backlog.length > 1) {
+    voce.byteBacklog -= Buffer.byteLength(voce.backlog.shift(), 'utf8');
+  }
+  if (voce.byteBacklog <= BACKLOG_MASSIMO_BYTE || voce.backlog.length === 0) return;
+  const ultimo = Buffer.from(voce.backlog[0], 'utf8');
+  let taglio = ultimo.length - BACKLOG_MASSIMO_BYTE;
+  while (taglio < ultimo.length && (ultimo[taglio] & 0xc0) === 0x80) taglio += 1;
+  const coda = ultimo.subarray(taglio).toString('utf8');
+  voce.backlog[0] = coda;
+  voce.byteBacklog = Buffer.byteLength(coda, 'utf8');
+}
+
+/** Una PTY disconnessa da più di così viene chiusa dal reaper — pulizia di schede mai più tornate, non un limite sulla shell viva. */
+export const MINUTI_PRIMA_DI_CHIUDERE_PTY_ORFANA = 10;
+
+/*
+ * ⛔⛔⛔ CLI-REQ-04 (17/09/2026) — L'AMBIENTE DELLA SHELL DELLA PERSONA.
+ *
+ * Fino a oggi `apri` passava `env: process.env`, cioè l'ambiente INTERO del server. Dentro ci
+ * sono il token di loopback a 64 esadecimali che protegge TUTTA la nostra API locale e la chiave
+ * privata che firma le ricevute (`desktop/runtime.mjs:47-60`, `src/config.mjs:601` e `:625-627`).
+ * Un `npm install` con i suoi script di installazione, o un attrezzo scaricato, lanciato dalla
+ * persona in questa scheda poteva leggerli e usarli.
+ *
+ * ⛔ Ricerca prima di scrivere, 17/09/2026: la documentazione di `node:child_process`
+ * (nodejs.org/api/child_process.html) dichiara `env` con default `process.env`, cioè l'eredità
+ * INTERA è il comportamento predefinito e va disfatta a mano; lo stato dell'arte sui segreti in
+ * Node (nodejs-security.com/blog/do-not-use-secrets-in-environment-variables-and-here-is-how-to
+ * -do-it-better) chiama l'eredità automatica una violazione del minimo privilegio.
+ *
+ * ⛔ L'elenco e la funzione NON vivono più qui: stanno in `ambiente-solo-server.mjs`, perché dal
+ * secondo giro il browser di sistema (`browser-vivo.mjs`) ha lo stesso bisogno e due copie
+ * divergerebbero al primo segreto nuovo. Lì stanno anche il perché dell'elenco CHIUSO e la
+ * misura che mostra che D-10E NON copre già questi nomi.
+ *
+ * ⛔ L'ELENCO DEI PUNTI CHE AVVIANO PROCESSI CON L'AMBIENTE INTERO — cioè chi altri ha questo
+ * stesso difetto, quanto è coperto e quanto no — sta in
+ * `.claude/ELENCO-SPAWN-AMBIENTE-2026-09-17.md`, misurato il 17/09/2026. Chi tocca questa riga
+ * lo rilegga: una cura su una sola strada non chiude la classe.
+ */
+export { VARIABILI_DEL_SERVER_DICHIARATE_INNOCUE, VARIABILI_SOLO_DEL_SERVER } from './ambiente-solo-server.mjs';
+
+/** Il nome con cui questo modulo ha sempre esposto la funzione: una sola implementazione, due nomi. */
+export const ambienteDelTerminale = ambienteSenzaVariabiliDelServer;
+
+/**
+ * Sceglie la shell reale da lanciare. Su Windows: Git Bash se esiste
+ * — altrimenti `cmd.exe`, ma
+ * DICHIARATO (`enforcement:'cmd-fallback'`), mai un fallback silenzioso
+ * spacciato per bash (stesso principio "onestà sull'enforcement" già
+ * in uso per l'attrezzo `shell` dell'agente). Su POSIX: `$SHELL` o
+ * `/bin/bash`.
+ */
+export function sceltaShell(deps = {}) {
+  const platform = deps.platform ?? process.platform;
+  const existsFn = deps.existsFn ?? existsSync;
+  const env = deps.env ?? process.env;
+  if (platform === 'win32') {
+    const percorsi = deps.percorsiGitBash ?? PERCORSI_GIT_BASH_WINDOWS;
+    const gitBash = percorsi.find((percorso) => existsFn(percorso));
+    if (gitBash) return { comando: gitBash, argomenti: ['--login', '-i'], enforcement: 'git-bash' };
+    return { comando: 'cmd.exe', argomenti: [], enforcement: 'cmd-fallback' };
+  }
+  return { comando: env.SHELL || '/bin/bash', argomenti: ['-l'], enforcement: 'posix-shell' };
+}
+
+/**
+ * Codifica/decodifica del framing binario sulla WebSocket — un byte di
+ * comando in testa, mai lo stream incapsulato in JSON (corromperebbe le
+ * sequenze ANSI/di controllo — guardia raccolta in ricerca:
+ * xtermjs.org/docs/guides/flowcontrol). `0` = dati grezzi (tastiera
+ * umana → PTY, o PTY → schermo). `1` = controllo JSON (resize, o
+ * l'evento di uscita della shell).
+ */
+export const TIPO_FRAME_DATI = 0;
+export const TIPO_FRAME_CONTROLLO = 1;
+
+export function codificaFrame(tipo, payload) {
+  const corpo = typeof payload === 'string' ? Buffer.from(payload, 'utf8') : payload;
+  return Buffer.concat([Buffer.from([tipo]), corpo]);
+}
+
+/** AL CONTRARIO — un frame vuoto o con un tipo ignoto torna `null`, mai un crash. */
+export function decodificaFrame(dati) {
+  const buf = Buffer.isBuffer(dati) ? dati : Buffer.from(dati);
+  if (buf.length === 0) return null;
+  const tipo = buf[0];
+  if (tipo !== TIPO_FRAME_DATI && tipo !== TIPO_FRAME_CONTROLLO) return null;
+  return { tipo, payload: buf.subarray(1) };
+}
+
+/**
+ * Registro delle PTY vive, per id. Una riconnessione sullo STESSO id
+ * riaggancia la PTY viva invece di aprirne una seconda (un F5 non perde la
+ * shell) — stesso principio del `Last-Event-ID` già in uso per SSE, qui
+ * applicato a una PTY invece che a un run dell'agente.
+ *
+ * ⛔⛔ W1-01 (05/9) — l'id NON è più il `sessionId`: è il **`terminalId`**, e
+ * una sessione può averne più d'uno. Chi decide quali id esistono, a quale
+ * sessione appartengono e in quale cartella si aprono è
+ * `terminal-registry.mjs`; questo file non autorizza niente, tiene solo in
+ * vita le PTY. ⇒ Ogni id ha la sua voce, quindi la sua PTY, il suo backlog e
+ * i suoi ascoltatori: due schede della stessa sessione **non condividono
+ * I/O**, ed è il criterio della riga (provato in `pty-terminal.test.mjs`).
+ */
+export function creaRegistroTerminali(deps = {}) {
+  const spawnPtyFn = deps.spawnPtyFn ?? spawnPty;
+  const sceltaShellFn = deps.sceltaShellFn ?? sceltaShell;
+  const ambienteFn = deps.ambienteFn ?? ambienteDelTerminale; // ⛔ CLI-REQ-04: iniettabile per i test.
+  const clock = deps.clock ?? (() => Date.now());
+  /** @type {Map<string, any>} */
+  const terminali = new Map();
+
+  function apri({ id, cartella, cols = 80, rows = 24 }) {
+    const esistente = terminali.get(id);
+    if (esistente && !esistente.chiusa) {
+      esistente.ultimaDisconnessioneMs = null;
+      return esistente;
+    }
+    const scelta = sceltaShellFn();
+    const handle = spawnPtyFn(scelta.comando, scelta.argomenti, {
+      name: 'xterm-256color',
+      cols,
+      rows,
+      cwd: cartella,
+      env: ambienteFn(), // ⛔ CLI-REQ-04 (17/09/2026): mai `process.env` intero — vedi VARIABILI_SOLO_DEL_SERVER.
+    });
+    const voce = {
+      id,
+      handle,
+      enforcement: scelta.enforcement,
+      comando: scelta.comando, // 06/9 B1: il nome della shell arriva alla scheda
+      backlog: [],
+      byteBacklog: 0,
+      ultimaDisconnessioneMs: null,
+      chiusa: false,
+      ascoltatori: new Set(),
+    };
+    handle.onData((dati) => {
+      voce.backlog.push(dati);
+      voce.byteBacklog += Buffer.byteLength(dati, 'utf8');
+      limitaBacklog(voce);
+      for (const ascolta of voce.ascoltatori) ascolta({ tipo: 'dati', dati });
+    });
+    handle.onExit(({ exitCode, signal }) => {
+      voce.chiusa = true;
+      for (const ascolta of voce.ascoltatori) ascolta({ tipo: 'uscita', exitCode, signal });
+    });
+    terminali.set(id, voce);
+    return voce;
+  }
+
+  function scrivi(id, dati) {
+    terminali.get(id)?.handle.write(dati);
+  }
+
+  function ridimensiona(id, cols, rows) {
+    const voce = terminali.get(id);
+    if (voce && !voce.chiusa && cols > 0 && rows > 0) voce.handle.resize(cols, rows);
+  }
+
+  /*
+   * ⛔ 14/09 (F05 della review, riprodotto): una scheda che si stacca NON rende orfana una PTY che un'ALTRA finestra sta
+   *   ancora guardando. Prima il timbro si metteva comunque, e dieci minuti dopo il reaper uccideva un terminale vivo
+   *   sotto gli occhi di chi lo stava usando — difetto che il lavoro a due finestre di oggi rende tutt'altro che teorico.
+   *   Il timbro lo mette solo l'ULTIMO che se ne va; se resta qualcuno, si azzera.
+   */
+  function segnaDisconnesso(id) {
+    const voce = terminali.get(id);
+    if (voce) voce.ultimaDisconnessioneMs = voce.ascoltatori.size === 0 ? clock() : null;
+  }
+
+  /** Chiusura esplicita (mai implicita): l'owner chiude la scheda del terminale dalla UI. */
+  function chiudiForzato(id) {
+    const voce = terminali.get(id);
+    if (!voce) return;
+    try { voce.handle.kill(); } catch { /* già morta, nulla da fare */ }
+    terminali.delete(id);
+  }
+
+  /**
+   * Chiude solo le PTY orfane da più di `MINUTI_PRIMA_DI_CHIUDERE_PTY_ORFANA`
+   * — mai quelle ancora attaccate a un client (`ultimaDisconnessioneMs`
+   * nullo finché una WS resta aperta), mai per un tetto di tempo sulla
+   * shell VIVA.
+   */
+  function reap() {
+    const ora = clock();
+    for (const [id, voce] of terminali) {
+      // ⛔ 14/09 (F05): «orfana» vuol dire che NESSUNO la guarda — il timbro da solo non basta, perché un'altra finestra
+      //   può essersi riagganciata nel frattempo. Due condizioni, non una.
+      const orfanaScaduta = voce.ascoltatori.size === 0
+        && voce.ultimaDisconnessioneMs !== null
+        && ora - voce.ultimaDisconnessioneMs > MINUTI_PRIMA_DI_CHIUDERE_PTY_ORFANA * 60_000;
+      if (voce.chiusa || orfanaScaduta) {
+        try { voce.handle.kill(); } catch { /* già morta */ }
+        terminali.delete(id);
+      }
+    }
+  }
+
+  /**
+   * ⭐ W1-01 (05/9) — lo stato di UNA PTY, senza esporre la voce mutabile del
+   * registro fuori da qui (stesso principio di `cartellaDi` in
+   * `session-registry.mjs`). Serve all'elenco delle schede per dire «shell
+   * viva» / «shell già uscita»: `null` significa «nessuna PTY per questo id»,
+   * che è un terzo fatto e non si confonde con `{viva:false}`.
+   */
+  function stato(id) {
+    const voce = terminali.get(id);
+    if (!voce) return null;
+    return { viva: !voce.chiusa, enforcement: voce.enforcement, byteBacklog: voce.byteBacklog };
+  }
+
+  /**
+   * ⭐⭐⭐ Come `apri`, ma DICE se ha ripreso una PTY viva o ne ha aperta una
+   * nuova.
+   *
+   * ⛔ Serve perché da fuori le due cose sono indistinguibili: il ponte
+   * rigioca il backlog in entrambi i casi, e una PTY appena creata ha backlog
+   * vuoto — che è anche l'aspetto di una shell viva che non ha ancora
+   * stampato niente. Dedurlo dall'assenza di backlog è un indovinello, non una
+   * misura, e l'interfaccia finiva per dire «riconnesso» senza poter sapere se
+   * la shell della persona fosse sopravvissuta. Lo stato dell'arte separa
+   * l'identità della CONNESSIONE da quella della SESSIONE e fa dichiarare al
+   * server se ha davvero ripreso (un pattern noto come "connection state
+   * recovery", ricerca del 05/09/2026: websocket.org/guides/reconnection/).
+   *
+   * ⛔ La risposta viene dallo STESSO controllo che fa `apri` («la voce esiste
+   * e non è chiusa»), letto un attimo prima: non è una seconda verità che può
+   * divergere dalla prima. Fra la lettura e la chiamata non c'è `await`.
+   *
+   * @returns {{voce:object, ripresa:boolean}} `ripresa:false` significa shell
+   *   NUOVA — la prima volta in assoluto, oppure dopo che il reaper ha chiuso
+   *   quella di prima.
+   */
+  function apriDichiarando({ id, cartella, cols, rows }) {
+    const esistente = terminali.get(id);
+    const ripresa = Boolean(esistente && !esistente.chiusa);
+    return { voce: apri({ id, cartella, cols, rows }), ripresa };
+  }
+
+  return {
+    apri, apriDichiarando, scrivi, ridimensiona, segnaDisconnesso, chiudiForzato, reap, stato,
+    /** ⛔ Solo per i test — mai usato dal codice di produzione. */
+    _terminali: terminali,
+  };
+}

package/vendor/harness-ui/src/public-problem.mjs

@@ -0,0 +1,109 @@
+import { createHash } from 'node:crypto';
+
+const diagnostics = new Map();
+const MESSAGES = Object.freeze({
+  CONFIG_INVALID: { title: 'Configurazione non pronta', explanation: 'Manca una parte della configurazione necessaria per completare questa operazione.', action: 'Apri Doctor e segui i controlli indicati, poi riprova.' },
+  TASK_CATALOG_UNAVAILABLE: { title: 'Elenco attività non disponibile', explanation: 'Il servizio che fornisce le attività non è ancora collegato.', action: 'Controlla Doctor o configura il servizio delle attività, poi riprova.' },
+  RUNTIME_NOT_AVAILABLE: { title: 'Servizio locale non disponibile', explanation: 'Non è stato possibile trovare un servizio locale pronto.', action: 'Apri Doctor per vedere cosa manca oppure scegli un servizio online.' },
+  RUNTIME_UNREACHABLE: { title: 'Servizio locale non raggiungibile', explanation: 'Il servizio locale non ha risposto.', action: 'Controlla che sia avviato in Doctor e riprova.' },
+  PATH_NOT_ALLOWED: { title: 'Percorso non consentito', explanation: 'Il percorso scelto è fuori dall’area autorizzata.', action: 'Scegli una cartella dentro il progetto aperto.' },
+  PROCESS_POLICY_REJECTED: { title: 'Operazione bloccata per sicurezza', explanation: 'Il comando richiesto non rientra nelle autorizzazioni correnti.', action: 'Controlla il permesso della sessione e riprova solo se riconosci il comando.' },
+  /*
+   * ⛔ 07/9, O-49 — senza una voce qui la busta portava la copia di INTERNAL_ERROR:
+   * «Si è verificato un problema imprevisto» e «Apri Doctor». Falso due volte: non è
+   * imprevisto, ed è l’unica cosa che Doctor non può spiegare. La scheda del permesso
+   * è semplicemente vecchia — si ricarica la sessione e si guarda cosa chiede adesso.
+   */
+  APPROVAL_NOT_PENDING: { title: 'Richiesta di permesso scaduta', explanation: 'La sessione è andata avanti: quella domanda non aspetta più una risposta.', action: 'Ricarica la sessione e rispondi alla richiesta che vedi adesso, se ce n’è una.' },
+  /*
+   * ⛔⛔ 07/9, owner bloccato: «la sessione e ancora bloccata, non riesco a inviare messaggi e
+   * spunta errore toast». `SESSION_NOT_READY` NON era in questa mappa, quindi cadeva su
+   * INTERNAL_ERROR e a schermo arrivava «Si e verificato un problema imprevisto» — mentre il
+   * registro aveva gia scritto la frase giusta e AZIONABILE: «Questa sessione e stata interrotta
+   * da un riavvio del server e non puo essere ripresa: avvia una sessione nuova».
+   * ⇒ Il codice piu utile della mappa e quello che dice COSA FARE. Qui la spiegazione generica
+   *   resta come rete, ma il motivo VERO del registro passa in `explanation` (vedi `problemFor`):
+   *   una porta chiusa senza indicazione di dove sia quella aperta e il modo migliore per bloccare
+   *   una persona su una schermata.
+   */
+  SESSION_NOT_READY: { title: 'Sessione non pronta', explanation: 'Questa sessione non puo accettare l’azione richiesta nello stato in cui si trova.', action: 'Se e stata interrotta da un riavvio, avvia una sessione nuova: la conversazione resta leggibile qui.' },
+  /*
+   * ⛔⛔ 12/09, L5 — LA STESSA VORAGINE DI O-49, e per questo sono qui il giorno stesso in cui
+   * nascono i codici. Senza una voce in questa mappa una risposta cade sulla copia di
+   * INTERNAL_ERROR, e a schermo una ricerca cancellata dieci secondi fa diventa «Si è verificato
+   * un problema imprevisto · Apri Doctor, copia il riferimento»: falso due volte — non è
+   * imprevisto, ed è l'unica cosa che Doctor non può spiegare. Misurato interrogando la rotta
+   * vera prima di scrivere queste righe, non dedotto.
+   * ⛔ Nessuna di queste è un guasto: sono tre no diversi, e ognuna dice COSA FARE.
+   */
+  RESEARCH_NOT_FOUND: { title: 'Ricerca non trovata', explanation: 'Questa ricerca approfondita non è più nel progetto: può essere stata eliminata.', action: 'Torna all’elenco delle ricerche: mostra quelle che ci sono adesso.' },
+  RESEARCH_CONFLICT: { title: 'Azione non possibile adesso', explanation: 'Questa ricerca non è nello stato che l’azione richiede — per esempio è già ferma, o è già finita.', action: 'Riapri la scheda della ricerca: dice come sta in questo momento.' },
+  RESEARCH_RECHECK_UNAVAILABLE: { title: 'Controllo delle fonti non possibile', explanation: 'Per ricontrollare le fonti serve un rapporto con i passaggi citati, e questa ricerca non ne ha.', action: 'Le ricerche nuove lo portano: questa si può rifare, oppure lasciarla com’è.' },
+  RESEARCH_INVALID: { title: 'Richiesta non valida', explanation: 'L’identificativo della ricerca non ha una forma ammessa.', action: 'Apri la ricerca dall’elenco invece di comporre l’indirizzo a mano.' },
+  INTERNAL_ERROR: { title: 'Operazione non riuscita', explanation: 'Si è verificato un problema imprevisto durante l’operazione.', action: 'Apri Doctor, copia il riferimento e riprova.' },
+});
+
+function safeCode(error) {
+  return typeof error?.code === 'string' && /^[A-Z0-9_]+$/u.test(error.code) ? error.code : 'INTERNAL_ERROR';
+}
+
+function referenceFor(code, requestId, operation) {
+  return `doctor-${createHash('sha256').update(`${code}|${requestId || ''}|${operation || ''}`).digest('hex').slice(0, 12)}`;
+}
+
+function safeDiagnosticDetail(error) {
+  if (typeof error?.message !== 'string') return '';
+  return error.message
+    .replace(/\b(?:sk|pk)-[A-Za-z0-9_-]+\b/giu, '[redacted]')
+    .replace(/\bsecret\b/giu, '[redacted]')
+    .replace(/\bTALOS_[A-Z0-9_]+\b/gu, '[setting]')
+    .replace(/\b[A-Za-z]:\\[^\r\n;]+/gu, '[path]')
+    .replace(/\/(?:Users|home|tmp|var|data)\/[^\r\n; ]+/giu, '[path]')
+    .replace(/\s+/gu, ' ')
+    .trim()
+    .slice(0, 240);
+}
+
+/*
+ * ⛔⛔ 07/9 — I codici il cui `message` e GIA scritto per una persona, e non per un log.
+ * Il registro, per una sessione che non puo ripartire, dice: «Questa sessione e stata interrotta da
+ * un riavvio del server e non puo essere ripresa: avvia una sessione nuova» — una frase che dice
+ * cosa e successo E cosa fare. Quella frase veniva BUTTATA e sostituita con «Si e verificato un
+ * problema imprevisto», e l'owner e rimasto bloccato su una schermata senza sapere dove fosse
+ * l'uscita.
+ * ⛔ La sostituzione generica esiste per una ragione buona — un messaggio d'errore grezzo puo
+ *   portare percorsi, id, dettagli interni — e resta il comportamento predefinito. Qui si dichiara
+ *   la sola eccezione: i codici dove chi ha scritto il messaggio lo ha scritto PER lo schermo.
+ *   Aggiungerne uno vuol dire prendersi la responsabilita che quel testo sia leggibile e privo di
+ *   dettagli interni: si guarda ogni `erroreAvvio` di quel codice prima di metterlo qui.
+ */
+const MESSAGGIO_GIA_PER_LA_PERSONA = new Set(['SESSION_NOT_READY']);
+
+/** Un testo del registro e pubblicabile solo se e corto e non porta percorsi o identificatori. */
+function messaggioPubblicabile(testo) {
+  const t = String(testo || '').trim();
+  if (t.length < 12 || t.length > 240) return '';
+  if (/[\/]{1}[\w.-]+[\/]|[0-9a-f]{8}-[0-9a-f]{4}/i.test(t)) return ''; // percorsi o id: restano nel log
+  return t;
+}
+
+export function toPublicProblem(error, { requestId = '', operation = '' } = {}) {
+  const code = safeCode(error);
+  const copy = MESSAGES[code] ?? MESSAGES.INTERNAL_ERROR;
+  const doctorReference = referenceFor(code, requestId, operation);
+  diagnostics.set(doctorReference, Object.freeze({ code, operation: String(operation || 'operation'), requestId: String(requestId || ''), detail: safeDiagnosticDetail(error) }));
+  const vero = MESSAGGIO_GIA_PER_LA_PERSONA.has(code) ? messaggioPubblicabile(error?.message) : '';
+  return { title: copy.title, explanation: vero || copy.explanation, action: copy.action, doctorReference };
+}
+
+export function logDiagnosticProblem(error, { requestId = '', operation = '', logger = console } = {}) {
+  const publicProblem = toPublicProblem(error, { requestId, operation });
+  const code = safeCode(error);
+  try { logger?.warn?.(`[${publicProblem.doctorReference}] ${operation || 'operation'} (${code})`); } catch { /* un logger guasto non cambia l’esito dell’operazione */ }
+  return publicProblem.doctorReference;
+}
+
+export function getDiagnosticProblem(reference) {
+  const detail = diagnostics.get(reference);
+  return detail ? { ...detail } : null;
+}

package/vendor/harness-ui/src/research/card.mjs

@@ -0,0 +1,235 @@
+import { talosResearchIsResting, talosResearchIsTerminal, talosResearchProgressOf } from './run.mjs'
+
+/*
+ * PORTO FEDELE di AVM/mobile/src/lib/research/researchCard.ts (211 righe, 11/09/2026).
+ *
+ * ⛔ `run.mjs` è il porto di `researchRun.ts` e lo cura un'altra sessione, in
+ * parallelo: qui se ne importa solo il nome concordato.
+ *
+ * Che aspetto ha una ricerca da fuori, prima di aprirla.
+ *
+ * La stazione era un modulo con sotto un elenco di righe espandibili, e le
+ * righe dicevano `3/3 · done`. Quella è la vista della macchina. Questa è
+ * quella del lettore: che cosa ho chiesto, quando, com'è finita e — quando è
+ * finita — **quanto regge**.
+ *
+ * L'ultima parte è tutto l'argomento. La ricerca sui concorrenti (2026-08-03)
+ * ha trovato che tutti e cinque i prodotti guidano col volume — «56 siti»,
+ * «hundreds of sources» — e nessuno dice se le affermazioni hanno retto. La sua
+ * conclusione è che la vittoria non sono più citazioni, è un resoconto migliore
+ * della relazione fra affermazione e prova. Quindi una scheda qui guida col
+ * bilancio e mai col conteggio delle fonti.
+ *
+ * Pura apposta: una scheda è un riassunto, e un riassunto che ha bisogno di un
+ * database è un riassunto che non si può provare.
+ */
+
+/**
+ * @import { TalosResearchRun, TalosResearchStatus } from './run.mjs'
+ */
+
+/**
+ * I secchi che il filtro offre. Una corsa sta in esattamente uno.
+ * @typedef {'running' | 'paused' | 'unfinished' | 'cancelled' | 'done' | 'failed'} TalosResearchBucket
+ */
+
+/**
+ * @typedef {object} TalosResearchStanding
+ * @property {number} total
+ * @property {number} supported
+ * @property {number} partial
+ * @property {number} unsupported
+ * @property {number} unchecked
+ * @property {number} [contested] ⛔ CONTESA-01 — le affermazioni su cui le fonti
+ *   non concordano. Opzionale, e non per pigrizia: i rapporti scritti prima del
+ *   2026-08-20 non hanno questo conto, e leggerlo come zero su un rapporto
+ *   vecchio direbbe «nessun disaccordo» dove la verità è «non guardato». Chi lo
+ *   mostra usa `?? 0` sapendo cosa sta facendo.
+ */
+
+/**
+ * @typedef {object} TalosResearchCard
+ * @property {string} id
+ * @property {string} question Quello che l'elenco MOSTRA: l'etichetta scelta, o la domanda quando non ce n'è.
+ * @property {string} originalQuestion La domanda come è stata posta, tenuta accanto all'etichetta perché la provenienza sopravviva a una rinomina.
+ * @property {boolean} renamed Vero quando qualcuno ha dato un nome suo a questa ricerca.
+ * @property {string} startedAt
+ * @property {string} updatedAt
+ * @property {TalosResearchBucket} bucket
+ * @property {TalosResearchStatus} status La parola del giornale, che il secchio apposta sfuma.
+ * @property {number} done
+ * @property {number} total
+ * @property {number} failedSteps Rami falliti, così una scheda può ammettere un risultato parziale invece di nasconderlo.
+ * @property {TalosResearchStanding | null} standing Presente solo una volta letto il rapporto; l'elenco non lo aspetta.
+ */
+
+/**
+ * In quale secchio sta una corsa.
+ *
+ * `running` lo decide il registro VIVO, non il giornale: una corsa che il
+ * giornale chiama incompiuta può essere in volo proprio adesso, e chiamarla
+ * interrotta mentre lavora è esattamente la bugia che questo rifacimento è
+ * nato per togliere. Il giornale risponde a «che cosa è stato scritto», mai a
+ * «che cosa sta succedendo».
+ *
+ * @param {TalosResearchRun} run
+ * @param {boolean} isRunning
+ * @returns {TalosResearchBucket}
+ */
+export function talosResearchBucketOf(run, isRunning) {
+    if (isRunning) return 'running'
+    if (run.status === 'failed') return 'failed'
+    if (run.status === 'done') return 'done'
+    // Annullata è una DECISIONE, come la pausa, e per la stessa ragione non sta
+    // con le corse che il telefono ha ucciso. Peggio che disordinato: quelle
+    // sono archiviate come «interrotte», il che promette che si possano
+    // riprendere — e una ricerca annullata è l'unica cosa qui che non riparte mai.
+    if (run.status === 'cancelled') return 'cancelled'
+    // In pausa ha un secchio SUO, ed è il punto stesso della pausa: la persona
+    // ha fermato apposta e conta di tornarci. Archiviarla accanto alle corse che
+    // il telefono ha ucciso le direbbe che la sua decisione è stata un incidente.
+    // `pause_requested` sta qui anche lui — è una pausa che non ha finito di
+    // atterrare, non una situazione diversa per chi legge.
+    if (talosResearchIsResting(run.status)) return 'paused'
+    // Tutto il resto — planning, collecting, synthesising, verifying — è lavoro
+    // che si è fermato senza finire. Un secchio solo, perché dal lato del
+    // lettore sono la stessa situazione: deve qualcosa e non sta succedendo niente.
+    return 'unfinished'
+}
+
+/**
+ * @param {TalosResearchRun} run
+ * @param {{ isRunning: boolean, standing?: TalosResearchStanding | null }} options
+ * @returns {TalosResearchCard}
+ */
+export function talosResearchCardOf(run, options) {
+    const progress = talosResearchProgressOf(run)
+    return {
+        id: run.id,
+        question: run.title ?? run.question,
+        originalQuestion: run.question,
+        renamed: run.title !== null,
+        startedAt: run.startedAt,
+        updatedAt: run.updatedAt,
+        bucket: talosResearchBucketOf(run, options.isRunning),
+        status: run.status,
+        done: progress.done,
+        total: progress.total,
+        failedSteps: run.steps.filter((step) => step.state === 'failed').length,
+        standing: options.standing ?? null,
+    }
+}
+
+/**
+ * Quanto regge un rapporto finito, come un numero solo fra 0 e 1.
+ *
+ * Il sostegno parziale conta metà. Non è una furbizia: un'affermazione che la
+ * fonte sostiene in parte sta davvero in mezzo, e arrotondarla a «sostenuta» è
+ * il modo in cui un rapporto finisce per sembrare più solido di quanto sia —
+ * che è il guasto che tutta la verifica esiste per impedire. Il non verificato
+ * conta zero per la stessa ragione: «non siamo riusciti a controllare» non è
+ * una promozione.
+ *
+ * ⛔ Una CONTESA vale zero, come una smentita, e la ragione è la stessa che
+ * regge tutta questa funzione: se le fonti si contraddicono, quell'affermazione
+ * non è una prova. Contarla anche solo per metà rifarebbe esattamente il
+ * difetto che la verifica esiste per impedire — un rapporto che sembra più
+ * solido di quanto sia.
+ *
+ * @param {TalosResearchStanding | null} standing
+ * @returns {number | null}
+ */
+export function talosResearchSolidity(standing) {
+    if (!standing || standing.total === 0) return null
+    return (standing.supported + (standing.partial * 0.5)) / standing.total
+}
+
+/**
+ * Se un rapporto finito merita un secondo sguardo.
+ *
+ * Qualsiasi cosa non sostenuta, o una solidità sotto due terzi. La soglia è un
+ * giudizio, ed è scritta qui invece che sparsa in un modello di pagina, così la
+ * si può contestare in un posto solo.
+ *
+ * @param {TalosResearchCard} card
+ * @returns {boolean}
+ */
+export function talosResearchNeedsAttention(card) {
+    if (card.failedSteps > 0) return true
+    if (!card.standing) return false
+    if (card.standing.unsupported > 0) return true
+    // ⛔ Anche UNA contesa merita un secondo sguardo: vuol dire che su quel
+    // punto il mondo non concorda, ed è precisamente il caso in cui una
+    // persona vuole leggere le fonti invece di fidarsi del riassunto.
+    if ((card.standing.contested ?? 0) > 0) return true
+    const solidity = talosResearchSolidity(card.standing)
+    return solidity !== null && solidity < 2 / 3
+}
+
+/**
+ * Il file del rapporto che la sintesi ha scritto, quando ce n'è uno da leggere.
+ *
+ * Vive qui invece che in ogni schermata: l'elenco, la pagina del rapporto, la
+ * pagina dell'affermazione e quella della fonte ne hanno tutte bisogno, e
+ * quattro copie dello stesso `find` è il modo in cui cominciano a non essere
+ * più d'accordo su che cosa conti come finito.
+ *
+ * @param {TalosResearchRun} run
+ * @returns {string | null}
+ */
+export function talosResearchReportRefOf(run) {
+    const synthesis = run.steps.find((step) => step.kind === 'synthesise' && step.state === 'done')
+    return synthesis?.resultRef ?? null
+}
+
+/**
+ * Il filtro, applicato. `all` è un secchio che la UI offre e che i dati non hanno mai.
+ *
+ * @param {readonly TalosResearchCard[]} cards
+ * @param {TalosResearchBucket | 'all'} bucket
+ * @param {string} query
+ * @returns {readonly TalosResearchCard[]}
+ */
+export function talosResearchFilterCards(cards, bucket, query) {
+    const needle = query.trim().toLowerCase()
+    return cards.filter((card) => {
+        if (bucket !== 'all' && card.bucket !== bucket) return false
+        if (needle.length === 0) return true
+        return card.question.toLowerCase().includes(needle)
+    })
+}
+
+/**
+ * Che cosa si può fare a questa ricerca, adesso.
+ *
+ * Un elenco invece di un insieme di voci disabilitate: quali azioni esistono è
+ * un fatto sulla cosa, e un menu di opzioni morte fa lavorare il lettore per
+ * capire perché siano morte. Una ricerca viva offre Pausa e Annulla; una in
+ * pausa offre Riprendi; una annullata nessuna delle due, perché il motore si
+ * rifiuta di guidare una corsa finita e far finta di sì sarebbe un pulsante che
+ * mente.
+ *
+ * Elimina manca mentre gira, e non è schizzinosità: togliere il giornale da
+ * sotto all'unico scrittore distruggerebbe l'unica prova che un passo già
+ * mandato a un fornitore era stato pagato. Prima si ferma.
+ *
+ * @typedef {'open' | 'rename' | 'pause' | 'resume' | 'cancel' | 'delete'} TalosResearchAction
+ */
+
+/**
+ * @param {TalosResearchCard} card
+ * @returns {readonly TalosResearchAction[]}
+ */
+export function talosResearchActionsFor(card) {
+    /** @type {TalosResearchAction[]} */
+    const actions = ['open', 'rename']
+    if (card.bucket === 'running') {
+        actions.push('pause', 'cancel')
+        // Niente elimina: vedi sopra.
+        return actions
+    }
+    // In riposo o solo interrotta — entrambe devono ancora lavoro ed entrambe riprendono.
+    if (!talosResearchIsTerminal(card.status)) actions.push('resume', 'cancel')
+    actions.push('delete')
+    return actions
+}