talos-code 0.0.1 → 0.1.0

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

@@ -0,0 +1,220 @@
+/**
+ * session-store.mjs — FASE L (30/8), piano `elegant-spinning-dongarra.md`.
+ * Owner: "ricerca web competitor" sulla domanda "un riavvio del
+ * processo perde una sessione in corso, è mai successo per davvero?".
+ *
+ * ⛔⛔⛔ La ricerca ha RIDEFINITO la fase, non solo risposto alla domanda.
+ * Verificato alla fonte (non presunto): `session-registry.mjs` dichiara
+ * fin dalla sua prima riga "solo in memoria, deliberato... non ancora
+ * aperto" — un riavvio del server perde OGNI sessione, non solo quelle
+ * in corso, e non è mai stato diversamente (`.sessions/` su disco che
+ * un piano precedente citava non esiste in questo file — verificato
+ * con una ricerca diretta, zero riscontri).
+ *
+ * Cosa fa davvero lo stato dell'arte in questo spazio: transcript JSONL
+ * append-only come fonte di verità per il replay
+ * ("rollout files"), un indice separato (SQLite, solo per liste
+ * veloci — non necessario alla scala di questo prodotto). ⭐⭐⭐ Onestamente
+ * ammesso altrove: "if a transport failure occurs early enough...
+ * no resumable artefacts may be written" — un ripristino a metà turno
+ * non è mai garantito, nemmeno lì. Il ripristino VERO che si offre in
+ * questi casi è
+ * "rilettura della trascrizione", non "il modello riprende da dove
+ * stava" — lo stesso confine onesto che questo modulo dichiara.
+ *
+ * ⛔ Trovato durante la ricerca, non ipotetico: riscrivere l'intero file
+ * invece di solo accodare è una classe di bug nota (perdita di dati su
+ * crash per una riscrittura non atomica della trascrizione) — la
+ * classe di errore che questo modulo evita per costruzione: MAI un
+ * `writeFile` che sostituisce il file intero, solo `appendFile`. Una
+ * riga JSONL è atomica sui filesystem POSIX: un crash a metà riga
+ * lascia al più UNA riga corrotta, mai le precedenti.
+ *
+ * ⛔ Nessun fsync esplicito dopo ogni riga (differenza dichiarata dal
+ * pattern "production-hardened" trovato in ricerca): a differenza di
+ * un ledger finanziario, questo è uno strumento locale owner-only — la
+ * finestra di perdita è quella del buffer del sistema operativo (tipicamente
+ * pochi millisecondi), non l'intera sessione. Scelta esplicita, non
+ * un taglio silenzioso.
+ */
+import { promises as fsp, mkdirSync, appendFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export class SessionStoreError extends Error {
+  constructor(message, code = 'SESSION_STORE_FAILED') {
+    super(message);
+    this.name = 'SessionStoreError';
+    this.code = code;
+  }
+}
+
+const ESTENSIONE = '.jsonl';
+
+function percorsoDi(cartellaStore, sessionId) {
+  // ⛔ sessionId è sempre un randomUUID() generato da questo stesso processo (mai testo esterno) — nessuna sanificazione di percorso richiesta, a differenza di un nome file scelto dal modello (vedi library-store.mjs).
+  return join(cartellaStore, `${sessionId}${ESTENSIONE}`);
+}
+
+/**
+ * Accoda UNA riga — mai una riscrittura del file intero (la classe di
+ * bug vista in ricerca, vedi la testa del file). `record` è già serializzabile (un evento AG-UI,
+ * o l'intestazione, o il record `messaggiFinali`) — questo modulo non
+ * sa cosa contiene, solo che va in coda.
+ */
+/*
+ * ⭐⭐⭐ 04/9 — W0-07: UNA CODA PER FILE. `fsp.appendFile` non è atomica per
+ * un record più grande di una singola scrittura di sistema: il contenuto
+ * viene spezzato, e un secondo append concorrente sullo stesso file si
+ * infila in mezzo. Il risultato è una riga JSONL illeggibile — cioè una
+ * sessione che `ripristina()` scarta per sempre, in silenzio.
+ *
+ * ⛔ Non è teoria: nello store dell'owner il file `b7b1b7d2…` (31/08) aveva
+ * 4 righe rotte, la prima spezzata a **1.572.866 byte, esattamente 1,5
+ * MiB**, e le successive iniziavano a metà percorso pur finendo con
+ * `_sequenza` coerenti. Erano `WorkspaceChanged` da 1-1,5 MB l'uno (il
+ * workspace era `C:\` intero). Quella conversazione — vera, conclusa con
+ * successo — è stata invisibile per quattro giorni; l'ho recuperata a mano
+ * il 04/09 buttando solo le righe illeggibili.
+ *
+ * ⇒ Le scritture dello STESSO file si mettono in fila. File diversi non si
+ * aspettano fra loro (la chiave della coda è il percorso), quindi una
+ * sessione lenta non rallenta le altre. Un errore su una scrittura non
+ * blocca la coda: la successiva parte comunque.
+ *
+ * ⭐ Ricerca web del 04/09 (obbligo dell'owner, fatta PRIMA di considerare
+ * chiusa questa cura): `O_APPEND` è atomico **per singola chiamata di
+ * scrittura** — due scrittori non si sovrappongono finché ogni record entra
+ * in UNA chiamata; un payload grande viene però spezzato in più chiamate, ed
+ * è lì che si intrecciano. La forma raccomandata è esattamente questa: «le
+ * scritture concorrenti sullo stesso file si mettono in coda e si
+ * serializzano con le Promise, mentre file diversi restano in parallelo».
+ * Due cose che la ricerca aggiunge e che qui NON sono risolte, registrate
+ * come debito nel ledger: (a) per un log si consiglia uno stream persistente
+ * invece di aprire e chiudere il file a ogni evento; (b) una scrittura
+ * riuscita vive nella cache del kernel finché non c'è un `fsync`, quindi un
+ * crash può perdere gli ultimi eventi — l'invariante da tenere è non
+ * trattare mai come record dei byte di coda non validati, e `ripristina()`
+ * già distingue l'ultima riga spezzata (crash a metà append) da una riga
+ * rotta in mezzo (danno vero).
+ */
+const codeDiScrittura = new Map();
+
+export async function registraRiga({ cartellaStore, sessionId, record, durable = false }, deps = {}) {
+  const mkdirFn = deps.mkdirFn ?? fsp.mkdir;
+  const appendFileFn = deps.appendFileFn ?? fsp.appendFile;
+  const percorso = percorsoDi(cartellaStore, sessionId);
+  // ⛔ Serializzato SUBITO, non dentro la coda: `record` potrebbe cambiare mentre questa scrittura aspetta il suo turno.
+  const riga = `${JSON.stringify(record)}\n`;
+  const precedente = codeDiScrittura.get(percorso) ?? Promise.resolve();
+  const corrente = precedente.catch(() => {}).then(async () => {
+    await mkdirFn(cartellaStore, { recursive: true });
+    await appendFileFn(percorso, riga, durable ? { encoding: 'utf8', flush: true } : 'utf8');
+  });
+  codeDiScrittura.set(percorso, corrente);
+  // La mappa non deve crescere per sempre: chi è l'ultimo della fila la ripulisce.
+  corrente.catch(() => {}).finally(() => {
+    if (codeDiScrittura.get(percorso) === corrente) codeDiScrittura.delete(percorso);
+  });
+  return corrente;
+}
+
+/**
+ * ⭐⭐⭐ FASE L, trovato dalla verifica DAL VIVO (30/8) — non ipotizzato: un
+ * server VERO, una sessione VERA, uccisa (`child.kill()`, TerminateProcess
+ * su Windows — un crash vero, nessun handler di spegnimento gira) **6 ms**
+ * dopo aver ricevuto il sessionId dal client. `ripristina()` sul riavvio:
+ * "114/115" — la sessione appena creata non c'era proprio, perché la SUA
+ * riga di intestazione (`registraRiga`, fire-and-forget) non aveva ancora
+ * toccato il disco quando il processo è morto. Non un dato corrotto: la
+ * sessione non è mai esistita per `ripristina()`, un buco onesto ma
+ * evitabile — un crash nella manciata di millisecondi dopo la creazione
+ * perde l'intera sessione, in silenzio.
+ *
+ * ⛔ La cura NON è rendere `avvia()`/`avviaLibero()` asincrone (~110
+ * call-site di test, l'intero contratto sincrono di `session-registry.mjs`
+ * — sproporzionato per una finestra di pochi millisecondi, stessa strada
+ * già scartata per lo stesso motivo in FASE E). La cura è che la SOLA
+ * intestazione — una scrittura piccola, una volta per sessione, mai per
+ * ogni evento — usi l'API fs SINCRONA: `avvia()` può restare sincrona e
+ * il client non riceve MAI un sessionId la cui intestazione non sia già
+ * durevole sul disco. Gli eventi/messaggiFinali successivi restano
+ * fire-and-forget (`registraRiga` sopra, invariata) — quella finestra
+ * resta (dichiarata nel commento di testa del modulo, "pochi
+ * millisecondi... scelta esplicita"), ma non può più cancellare
+ * l'ESISTENZA stessa della sessione.
+ */
+export function registraRigaSync({ cartellaStore, sessionId, record }, deps = {}) {
+  const mkdirSyncFn = deps.mkdirSyncFn ?? mkdirSync;
+  const appendFileSyncFn = deps.appendFileSyncFn ?? appendFileSync;
+  mkdirSyncFn(cartellaStore, { recursive: true });
+  appendFileSyncFn(percorsoDi(cartellaStore, sessionId), `${JSON.stringify(record)}\n`, 'utf8');
+}
+
+/**
+ * Elenca gli id delle sessioni persistite — per la ricostruzione
+ * all'avvio del server. Cartella assente ⇒ `[]`, mai un errore (un
+ * primo avvio non ha ancora nessuna sessione salvata).
+ */
+export async function elencaSessioniPersistite({ cartellaStore }, deps = {}) {
+  const readdirFn = deps.readdirFn ?? fsp.readdir;
+  let voci;
+  try {
+    voci = await readdirFn(cartellaStore, { withFileTypes: true });
+  } catch (errore) {
+    if (errore?.code === 'ENOENT') return [];
+    throw new SessionStoreError(`Impossibile leggere ${cartellaStore}: ${errore.message}`, 'SESSION_STORE_READ_FAILED');
+  }
+  return voci
+    .filter((v) => v.isFile() && v.name.endsWith(ESTENSIONE))
+    .map((v) => v.name.slice(0, -ESTENSIONE.length));
+}
+
+/**
+ * ⭐⭐⭐ 30/8, QA visiva (Task 14) — trovato dal vivo: nessun modo di
+ * eliminare una sessione, né qui né lato client. 144+ sessioni
+ * accumulate in un solo giro di QA senza possibilità di pulizia.
+ * Rimuove il file persistito — `ENOENT` è un esito onesto (già
+ * cancellato, o mai persistito perché senza `cartellaStore`), non un
+ * errore: stesso principio di `leggiRegistro` sopra.
+ */
+export async function eliminaSessionePersistita({ cartellaStore, sessionId }, deps = {}) {
+  const unlinkFn = deps.unlinkFn ?? fsp.unlink;
+  try {
+    await unlinkFn(percorsoDi(cartellaStore, sessionId));
+  } catch (errore) {
+    if (errore?.code === 'ENOENT') return;
+    throw new SessionStoreError(`Impossibile eliminare la sessione ${sessionId}: ${errore.message}`, 'SESSION_STORE_DELETE_FAILED');
+  }
+}
+
+/**
+ * Legge un registro per intero — una riga JSON per riga del file.
+ * ⭐⭐⭐ L'ULTIMA riga, se non è JSON valido, viene SCARTATA in silenzio
+ * (mai un errore che perde l'intero file): è esattamente il caso di
+ * un crash a metà scrittura, l'unica corruzione che l'append-only
+ * ammette per costruzione — "una riga rotta non invalida le
+ * precedenti", verificato in ricerca, non presunto. Una riga NON
+ * ultima malformata è invece un errore dichiarato: quello indica un
+ * file danneggiato in un altro modo, non un crash a metà append.
+ */
+export async function leggiRegistro({ cartellaStore, sessionId }, deps = {}) {
+  const readFileFn = deps.readFileFn ?? fsp.readFile;
+  let testo;
+  try {
+    testo = await readFileFn(percorsoDi(cartellaStore, sessionId), 'utf8');
+  } catch (errore) {
+    if (errore?.code === 'ENOENT') return null;
+    throw new SessionStoreError(`Impossibile leggere la sessione ${sessionId}: ${errore.message}`, 'SESSION_STORE_READ_FAILED');
+  }
+  const righe = testo.split('\n').filter((r) => r.trim() !== '');
+  const record = [];
+  for (let i = 0; i < righe.length; i++) {
+    try {
+      record.push(JSON.parse(righe[i]));
+    } catch {
+      if (i === righe.length - 1) break; // ultima riga, possibile crash a metà scrittura: scartata, non fatale
+      throw new SessionStoreError(`La sessione ${sessionId} ha una riga corrotta (non l'ultima): il file non è un crash a metà append, è danneggiato altrove.`, 'SESSION_STORE_CORRUPT');
+    }
+  }
+  return record;
+}

package/vendor/harness-ui/src/sessione-pronta.mjs

@@ -0,0 +1,73 @@
+/**
+ * sessione-pronta.mjs — «questa sessione può partire con QUESTO modello?» (CLI-REQ-05, punto 1).
+ *
+ * Estratta da `server.mjs` il 17/09/2026 perché lì dentro era una chiusura che nessuna prova poteva
+ * chiamare: i revisori l'avevano misurata ricopiandone i byte. Una regola che decide se un giro parte
+ * merita un nome e delle prove sue.
+ *
+ * ⛔⛔⛔ 17/09/2026, difetto trovato dalla corsia della CLI DOPO la fusione (`ba420a95`) e riprodotto qui
+ *   con lo store VERO prima di toccare una riga (`scratchpad/sonda-panchina.mjs`): una chiave messa in
+ *   PANCHINA (rifiutata dal fornitore, o in attesa dopo un 429) rispondeva ancora «pronto».
+ *     hasKey('deepseek') → true     (conta OGNI chiave del pool, panchina compresa)
+ *     getKey('deepseek') → null     (passa da `scegliChiave`, che salta chi è in panchina)
+ *   Il ramo OpenRouter usava già `getKey`, tutti gli altri `hasKey`: la sessione partiva, e il giro moriva
+ *   subito dopo senza una chiave utilizzabile. L'owner l'ha incontrato nella CLI lo stesso giorno.
+ * ⇒ «Pronto» vuol dire UNA CHIAVE UTILIZZABILE ADESSO, per ogni fornitore. E quando le chiavi ci sono ma
+ *   stanno tutte in panchina, il rifiuto lo DICE — con la causa in parole umane e fino a quando — invece
+ *   di «Manca la chiave», che manderebbe la persona a incollare una chiave che ha già.
+ *
+ * ⛔ SINCRONA per contratto: `avviaESegui` nel registro non è `async` e non lo diventa (un solo tick fa
+ *   cadere 148 prove, misurato il 10/09). Lo store risponde in memoria.
+ */
+import { REGISTRO_FORNITORI } from './provider-registry.mjs';
+import { separaFonteModello } from './model-destination.mjs';
+
+/** La causa della panchina, detta a una persona. Mai la classe tecnica a schermo. */
+const CAUSA_UMANA = Object.freeze({
+  credenziale: 'il fornitore l\'ha rifiutata',
+  credito: 'il credito è esaurito',
+  traffico: 'il fornitore ha chiesto di aspettare per troppo traffico',
+});
+
+function fraseDellaPanchina(etichetta, pool, adesso) {
+  const ferme = pool.filter((v) => Number.isFinite(v?.inPanchinaFino) && v.inPanchinaFino > adesso);
+  if (ferme.length === 0) return null;
+  // La prima a tornare disponibile è quella che interessa: è quando si può riprovare.
+  const prima = ferme.reduce((a, b) => (a.inPanchinaFino <= b.inPanchinaFino ? a : b));
+  const causa = CAUSA_UMANA[prima.causa] ?? 'il fornitore non l\'ha accettata';
+  const minuti = Math.max(1, Math.ceil((prima.inPanchinaFino - adesso) / 60_000));
+  const quando = minuti >= 120 ? `fra circa ${Math.round(minuti / 60)} ore` : `fra circa ${minuti} min`;
+  const quante = ferme.length === 1 ? `La chiave di ${etichetta} è in pausa` : `Le ${ferme.length} chiavi di ${etichetta} sono in pausa`;
+  return `${quante}: ${causa}. Si riprova da sola ${quando}; per non aspettare, collega un'altra chiave da Fornitori e accessi.`;
+}
+
+/**
+ * @param {{providerStore: {getKey: Function, elencaPool?: Function}, chiaveApi?: string|null, adessoFn?: () => number}} deps
+ * @returns {(modello: unknown) => {pronto: boolean, fornitore?: string, codice?: string, messaggio?: string}}
+ */
+export function creaProntoFn({ providerStore, chiaveApi = null, adessoFn = Date.now }) {
+  return function prontoFn(modello) {
+    /* ⛔ D2 (17/09): con un modello vuoto rispondeva «pronto» e la sessione partiva. Un modello che non si sa
+       leggere NON è pronto, e lo dice. */
+    if (typeof modello !== 'string' || modello.trim() === '') {
+      return { pronto: false, codice: 'CONFIG_INVALID', messaggio: 'Scegli un modello prima di avviare la sessione.' };
+    }
+    let fonte;
+    try { ({ fonte } = separaFonteModello(modello)); }
+    catch { return { pronto: false, codice: 'CONFIG_INVALID', messaggio: 'Questo modello non è riconosciuto: scegline uno dall\'elenco.' }; }
+    const record = REGISTRO_FORNITORI[fonte];
+    /* ⛔ `codice` e `messaggio` solo quando c'è qualcosa da dire: un «pronto» non porta un codice d'errore. */
+    if (!record || record.chiaveObbligatoria !== true) return { pronto: true, fornitore: record?.etichetta ?? fonte };
+    // UNA regola per tutti: una chiave utilizzabile ADESSO. La chiave d'ambiente di avvio vale solo per OpenRouter, com'era.
+    const utilizzabile = providerStore.getKey(fonte) ?? (fonte === 'openrouter' ? chiaveApi : null);
+    if (utilizzabile) return { pronto: true, fornitore: record.etichetta };
+    const pool = typeof providerStore.elencaPool === 'function' ? (providerStore.elencaPool(fonte) ?? []) : [];
+    const panchina = fraseDellaPanchina(record.etichetta, pool, adessoFn());
+    return {
+      pronto: false,
+      fornitore: record.etichetta,
+      codice: 'CONFIG_INVALID',
+      messaggio: panchina ?? `Manca la chiave di ${record.etichetta}: collegala da Fornitori e accessi.`,
+    };
+  };
+}

package/vendor/harness-ui/src/setup-stato.mjs

@@ -0,0 +1,31 @@
+/**
+ * ⭐⭐⭐ 04/9 — R-02, intro al primo avvio (Fascia R, owner: «abbia un intro
+ * stile mobile»). Lo stato che dice al browser QUALI passi del primo avvio
+ * sono già fatti — letto dalla realtà, come sul telefono
+ * (`mobile/src/lib/onboarding/setupProgress.ts`: «a step is done when the
+ * thing it asks for EXISTS», non da un cursore salvato che può invecchiare).
+ *
+ * ⛔ Nessun segreto passa di qui: della chiave si dice solo per QUALI provider
+ * esiste (`conChiave`), mai il valore. È la stessa disciplina di
+ * `providerStore.listPublic()`, e il test lo prova con `JSON.stringify`.
+ *
+ * `TALOS_INTRO=0` è il rollback dichiarato nel ledger: l'intro non si apre,
+ * e il lanciatore torna al comportamento di R-01 (schermata Doctor se manca
+ * la chiave).
+ */
+export function statoPrimoAvvio({ providerStore = null, localeConfigurato = false, introDisattivato = false, cartelleProgetto = 0 } = {}) {
+  let conChiave = [];
+  if (providerStore && typeof providerStore.listPublic === 'function') {
+    try {
+      conChiave = providerStore.listPublic().filter((riga) => riga.keyConfigured === true).map((riga) => riga.id);
+    } catch {
+      conChiave = []; // un portachiavi rotto non è una chiave: si dichiara «non pronto», mai un'ipotesi
+    }
+  }
+  const locale = localeConfigurato === true;
+  return Object.freeze({
+    introDisattivato: introDisattivato === true,
+    provider: Object.freeze({ pronto: conChiave.length > 0 || locale, conChiave: Object.freeze(conChiave), localeConfigurato: locale }),
+    cartelleProgetto: Number.isInteger(cartelleProgetto) && cartelleProgetto >= 0 ? cartelleProgetto : 0,
+  });
+}

package/vendor/harness-ui/src/sezioni-istruzioni.mjs

@@ -0,0 +1,204 @@
+// BC-48 A · lettore di sezioni Markdown e selezione deterministica, senza chiamate al modello.
+// Riferimenti: CommonMark 0.31.2; node:path del runtime verificato v24.18.0.
+import { posix, win32 } from 'node:path';
+
+export const SOGLIA_RIGHE_INDICE = 60;
+const byte = testo => Buffer.byteLength(testo, 'utf8');
+const slash = testo => String(testo).replace(/\\/g, '/');
+
+/** Conserva righe e terminatori originali: le coordinate appartengono al disco. */
+function scandisci(contenuto) {
+  const righe = String(contenuto).match(/[^\n]*\n|[^\n]+$/g) ?? [];
+  const commenti = [];
+  let recinto = null;
+  let commento = null;
+  const lette = righe.map((originale, indice) => {
+    const riga = originale.replace(/\r?\n$/, '');
+    const citazione = riga.match(/^(?: {0,3}>[ \t]?)+/)?.[0] ?? '';
+    const interna = riga.slice(citazione.length);
+    if (recinto?.citato && !citazione) recinto = null;
+    if (!commento && recinto) {
+      const chiusura = interna.match(/^ {0,3}(`{3,}|~{3,})[ \t]*$/);
+      if (chiusura && chiusura[1][0] === recinto.delimitatore[0] && chiusura[1].length >= recinto.delimitatore.length) recinto = null;
+      return { originale, pulita: originale, codice: true };
+    }
+    if (!commento) {
+      const apertura = interna.replace(/^ {0,3}(?:[-+*]|\d+[.)])[ \t]+/, '').match(/^ {0,3}(`{3,}|~{3,})(.*)$/);
+      if (apertura && !(apertura[1][0] === '`' && apertura[2].includes('`'))) {
+        recinto = { delimitatore: apertura[1], citato: Boolean(citazione) };
+        return { originale, pulita: originale, codice: true };
+      }
+      if (/^( {4}|\t)/.test(interna)) return { originale, pulita: originale, codice: true };
+    }
+    let pulita = '';
+    for (let i = 0; i < originale.length;) {
+      if (commento) {
+        if (originale.startsWith('-->', i)) {
+          commenti.push(commento); commento = null; i += 3;
+        } else {
+          commento.testo += originale[i];
+          if (originale[i] === '\n' || originale[i] === '\r') pulita += originale[i];
+          i++;
+        }
+      } else if (originale.startsWith('<!--', i)) {
+        commento = { da: indice + 1, testo: '' }; i += 4;
+      } else if (originale[i] === '`') {
+        const delimitatore = originale.slice(i).match(/^`+/)[0];
+        const fine = originale.indexOf(delimitatore, i + delimitatore.length);
+        const dopo = fine < 0 ? i + delimitatore.length : fine + delimitatore.length;
+        pulita += originale.slice(i, dopo); i = dopo;
+      } else { pulita += originale[i]; i++; }
+    }
+    return { originale, pulita, codice: false };
+  });
+  return { righe: lette, commenti };
+}
+
+export function rimuoviCommentiHtml(contenuto) {
+  return scandisci(contenuto).righe.map(r => r.pulita).join('');
+}
+
+function primaFrase(testo) {
+  const righe = testo.split(/\r?\n/).slice(1);
+  const paragrafo = [];
+  for (const riga of righe) {
+    if (!riga.trim()) { if (paragrafo.length) break; else continue; }
+    if (paragrafo.length && /^\s*(?:[-*+] |\d+[.)] |#|```|~~~)/.test(riga)) break;
+    paragrafo.push(riga.trim().replace(/^(?:[-*+] |\d+[.)] )/, ''));
+  }
+  const frase = paragrafo.join(' ').replace(/\s+/g, ' ').trim();
+  return frase.match(/^.*?[.!?](?=\s|$)/)?.[0] ?? frase;
+}
+
+export function analizzaSezioniIstruzioni(contenuto) {
+  const { righe, commenti } = scandisci(contenuto);
+  const inizi = righe.flatMap((r, i) => {
+    const titolo = !r.codice && r.pulita.match(/^ {0,3}##[ \t]+(.+?)[ \t]*(?:\r?\n)?$/);
+    return titolo ? [{ titolo: titolo[1].replace(/[ \t]+#+[ \t]*$/, '').trim(), da: i + 1 }] : [];
+  });
+  const sezioni = inizi.map((inizio, i) => {
+    const a = (inizi[i + 1]?.da ?? righe.length + 1) - 1;
+    const parte = righe.slice(inizio.da - 1, a);
+    const testo = parte.map(r => r.pulita).join('');
+    const metadati = commenti.filter(c => c.da > inizio.da && c.da <= a);
+    // Una lista separata da virgole; i gruppi {a,b} non vengono divisi.
+    const paths = metadati.flatMap(c => {
+      const m = c.testo.trim().match(/^talos:\s*paths:\s*([^\r\n]+)$/);
+      if (!m) return [];
+      return m[1].split(/,(?![^{}]*\})/).map(p => p.trim()).filter(Boolean);
+    });
+    return { ...inizio, a, byte: byte(parte.map(r => r.originale).join('')), testo, primaFrase: primaFrase(testo), paths,
+      sempre: (i === 0 && /^Non-Negotiable(?:\s|$)/i.test(inizio.titolo)) || metadati.some(c => /^talos:\s*sempre$/.test(c.testo.trim())) };
+  });
+  return { righe: righe.length, testo: righe.map(r => r.pulita).join(''),
+    premessa: righe.slice(0, (inizi[0]?.da ?? righe.length + 1) - 1).map(r => r.pulita).join(''), sezioni };
+}
+
+export function rendiFileIstruzioni(file, { sogliaRighe = SOGLIA_RIGHE_INDICE } = {}) {
+  const analisi = analizzaSezioniIstruzioni(file.contenuto);
+  const indicizzato = analisi.sezioni.length > 0 && (!slash(file.etichetta).includes('/') || analisi.righe > sogliaRighe);
+  if (!indicizzato) return { ...analisi, indicizzato, sezioniSempre: [], testo: analisi.testo };
+  const sempre = analisi.sezioni.filter(s => s.sempre);
+  const indice = analisi.sezioni.filter(s => !s.sempre).map(s => `## ${s.titolo} · righe ${s.da}-${s.a} · ${s.byte} byte · ${s.primaFrase}`).join('\n');
+  const lettura = file.lettura ?? file.etichetta;
+  const guida = `Prima di lavorare su un'area, leggi la sua sezione con \`leggi\` su \`${lettura}\` alle righe indicate (righe del file su disco). Le sezioni con un percorso si aprono da sole quando tocchi quei file, se la gestione del contesto è attiva.\n`;
+  return { ...analisi, indicizzato, sezioniSempre: sempre.map(({ titolo, da, a, byte }) => ({ etichetta: file.etichetta, titolo, da, a, byte })),
+    testo: analisi.premessa + sempre.map(s => s.testo).join('') + guida + indice + (indice ? '\n' : '') };
+}
+
+function percorsoNelProgetto(percorso, cartella, radice) {
+  if (typeof percorso !== 'string' || !percorso.trim() || /[\r\n\0]/.test(percorso)) return null;
+  const api = /^[A-Za-z]:\/|^\/{2}/.test(slash(radice)) ? win32 : posix;
+  const pieno = api.resolve(cartella, slash(percorso));
+  const rel = slash(api.relative(radice, pieno));
+  if (rel === '..' || rel.startsWith('../') || api.isAbsolute(rel)) return null;
+  return rel || '.';
+}
+
+function percorsiToccati(messages, cartella, radice) {
+  const chiamate = new Map();
+  const pendenti = new Set();
+  const percorsi = new Set();
+  for (const messaggio of messages) {
+    if (messaggio?.role === 'assistant') for (const c of messaggio.tool_calls ?? []) {
+      if (typeof c?.id !== 'string') continue;
+      chiamate.set(c.id, c); pendenti.add(c.id);
+    }
+    if (messaggio?.role !== 'tool' || !pendenti.has(messaggio.tool_call_id)) continue;
+    pendenti.delete(messaggio.tool_call_id);
+    const chiamata = chiamate.get(messaggio.tool_call_id);
+    const nome = chiamata?.function?.name;
+    // ⭐ PO-12 (13/09/2026) — `file_edit` tocca un file per `percorso` esattamente come `scrivi`: senza questo nome le istruzioni di progetto della cartella toccata non si accendono su una MODIFICA, cioe' proprio sull'attrezzo con cui il modello lavora su codice che gia' esiste.
+    if (!['leggi', 'scrivi', 'file_edit', 'cerca', 'elenca'].includes(nome)) continue;
+    let argomenti;
+    try { argomenti = JSON.parse(chiamata.function.arguments); } catch { continue; }
+    if (!argomenti || typeof argomenti !== 'object' || Array.isArray(argomenti)) continue;
+    const candidati = [];
+    if (nome !== 'cerca') {
+      const percorso = ['percorso', 'path', 'file_path', 'filePath', 'file', 'filename'].map(k => argomenti[k]).find(v => typeof v === 'string' && v.trim());
+      if (percorso) candidati.push(percorso);
+      else if (nome === 'elenca') candidati.push('.');
+    }
+    // Questi due attrezzi restituiscono percorsi, uno per riga. Le code sono avvisi,
+    // non risultati: non leggere mai percorsi dal contenuto di leggi o di una shell.
+    if (['cerca', 'elenca'].includes(nome) && typeof messaggio.content === 'string') {
+      for (const riga of messaggio.content.split(/\r?\n/)) {
+        if (/^(?:⚠|…|no file matches\.|give at least|".*not a readable folder)/.test(riga)) break;
+        if (riga.trim()) candidati.push(riga);
+      }
+    }
+    for (const candidato of candidati) {
+      const percorso = percorsoNelProgetto(candidato, cartella, radice);
+      if (percorso !== null) percorsi.add(percorso);
+    }
+  }
+  return { percorsi: [...percorsi], pendenti: pendenti.size };
+}
+
+function combacia(percorso, glob) {
+  const modello = slash(glob).replace(/^\.\//, '');
+  // Pattern confinati, espansione limitata: non permettere esplosioni di brace.
+  if (modello.length > 1024 || modello.startsWith('/') || /(^|\/)\.\.(\/|$)|^[A-Za-z]:/.test(modello) || (modello.match(/\{/g)?.length ?? 0) > 1) return false;
+  try { return posix.matchesGlob(percorso, modello); } catch { return false; }
+}
+
+/** Accoda agli originali. Stato locale più marcatori nello storico: nessun registro globale. */
+export function creaIniettoreSezioni({ file = [], cartella, radice, tetto = 24_000 } = {}) {
+  const catalogo = file.flatMap(f => {
+    const resa = rendiFileIstruzioni(f);
+    const occorrenze = new Map();
+    return resa.indicizzato ? resa.sezioni.map(s => {
+      const occorrenza = (occorrenze.get(s.titolo) ?? 0) + 1;
+      occorrenze.set(s.titolo, occorrenza);
+      return { ...s, occorrenza, etichetta: f.etichetta, lettura: f.lettura ?? f.etichetta };
+    }).filter(s => !s.sempre && s.paths.length) : [];
+  });
+  const viste = new Set();
+  return messages => {
+    if (!Array.isArray(messages) || !catalogo.length) return;
+    const { percorsi, pendenti } = percorsiToccati(messages, cartella, radice);
+    if (pendenti) return; // Preserva l'abbinamento anche nei batch di tool.
+    const aggiunte = [];
+    for (const sezione of catalogo) {
+      const marca = `Sezione di \`${sezione.etichetta}\` che vale per questa cartella: ${sezione.titolo} (${sezione.occorrenza}).\n`;
+      if (viste.has(marca)) continue;
+      if (messages.some(m => m?.role === 'user' && typeof m.content === 'string' && m.content.startsWith(marca))) { viste.add(marca); continue; }
+      if (!sezione.paths.some(glob => percorsi.some(p => combacia(p, glob)))) continue;
+      const intera = marca + `Righe ${sezione.da}-${sezione.a} del file su disco.\n` + sezione.testo;
+      const avviso = marca + `⚠ Tetto delle istruzioni (${tetto} byte): sezione omessa intera. Leggila con \`leggi\` su \`${sezione.lettura}\`, righe ${sezione.da}-${sezione.a}.`;
+      aggiunte.push({ marca, content: intera, avviso });
+    }
+    let totale = aggiunte.reduce((n, a) => n + byte(a.content), 0);
+    for (let i = aggiunte.length - 1; totale > tetto && i >= 0; i--) {
+      const a = aggiunte[i];
+      if (byte(a.avviso) >= byte(a.content)) continue;
+      totale += byte(a.avviso) - byte(a.content);
+      a.content = a.avviso;
+    }
+    if (totale > tetto) throw new RangeError('Il tetto delle istruzioni è insufficiente anche per gli avvisi delle sezioni.');
+    for (const { marca, content } of aggiunte) {
+      messages.push({ role: 'user', content });
+      viste.add(marca);
+    }
+  };
+}

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

@@ -0,0 +1,120 @@
+/**
+ * skill-registry.mjs — FASE F del piano `elegant-spinning-dongarra.md`
+ * (29/8): cartelle di istruzioni caricate on-demand, dichiarate per
+ * workspace. Stesso posto (`hook-registry.mjs`/`mcp-registry.mjs`
+ * letti come precedenti diretti) — `.harness-ui-skills/<nome>/SKILL.md`
+ * DENTRO il workspace, mai fuori: una skill è una proprietà del
+ * progetto, come `AGENTS.md` o `.harness-ui-hooks.json`.
+ *
+ * ⛔⛔ Nessun trust/hash gate, a differenza di hook (eseguono un
+ * comando) e server MCP (connettono un processo) — decisione
+ * deliberata: una skill è TESTO INERTE, la stessa categoria di rischio
+ * di `task.consegna` o di qualunque altro contenuto già nel system
+ * prompt, mai gated in questo progetto. Un cancello qui sarebbe un
+ * bluff di sicurezza, non una protezione vera — vedi la doc nel piano
+ * madre, FASE F, per il ragionamento completo.
+ *
+ * Formato verificato EMPIRICAMENTE il 29/8 leggendo quattro `SKILL.md`
+ * reali (`~/.claude/plugins/cache/.../SKILL.md`), non da una spec
+ * assunta: frontmatter YAML fra due righe `---`, tutte le istanze
+ * osservate a chiave singola per riga (`name: ...`, `description: ...`
+ * mai spezzato su più righe) — questo modulo parsa quella forma, non
+ * lo YAML generale (blocchi multi-riga, liste, nesting). Un file che
+ * usa una di quelle forme più ricche è un errore dichiarato
+ * (`SkillRegistryError`), mai un parsing silenziosamente sbagliato.
+ */
+import { promises as fsp } from 'node:fs';
+import { join } from 'node:path';
+
+export class SkillRegistryError extends Error {
+  constructor(message, code = 'SKILL_INVALID') {
+    super(message);
+    this.name = 'SkillRegistryError';
+    this.code = code;
+  }
+}
+
+const NOME_CARTELLA_SKILLS = '.harness-ui-skills';
+const NOME_FILE_SKILL = 'SKILL.md';
+
+/**
+ * Parsa il frontmatter minimo (`chiave: valore`, una riga per coppia,
+ * fra due delimitatori `---`) di un SKILL.md. Torna
+ * `{campi, corpo}` — `campi` è un oggetto piatto stringa→stringa,
+ * `corpo` è tutto ciò che segue il secondo `---` (il markdown vero).
+ */
+function analizzaSkillMd(testo, skillId) {
+  const righe = testo.split('\n');
+  if (righe[0]?.trim() !== '---') {
+    throw new SkillRegistryError(`${skillId}/SKILL.md deve iniziare con un frontmatter "---"`, 'SKILL_MALFORMED');
+  }
+  const fineFrontmatter = righe.findIndex((r, i) => i > 0 && r.trim() === '---');
+  if (fineFrontmatter === -1) {
+    throw new SkillRegistryError(`${skillId}/SKILL.md ha un frontmatter mai chiuso (manca il secondo "---")`, 'SKILL_MALFORMED');
+  }
+  const campi = {};
+  for (const riga of righe.slice(1, fineFrontmatter)) {
+    if (riga.trim() === '') continue;
+    const indice = riga.indexOf(':');
+    if (indice === -1) {
+      throw new SkillRegistryError(`${skillId}/SKILL.md ha una riga di frontmatter non valida (attesa "chiave: valore"): "${riga}"`, 'SKILL_MALFORMED');
+    }
+    const chiave = riga.slice(0, indice).trim();
+    const valore = riga.slice(indice + 1).trim();
+    campi[chiave] = valore;
+  }
+  /*
+   * ⛔ `/^[\r\n]+/`, non `/^\n+/`: un file con terminatori CRLF (comune
+   * su Windows — stesso difetto già visto altrove in questo progetto,
+   * `scrivere-un-file-da-python-lo-converte-in-crlf.md` in memoria)
+   * lascerebbe un `\r` isolato davanti al corpo altrimenti — verificato
+   * dal vivo il 29/8 leggendo un vero SKILL.md con CRLF, non presunto.
+   */
+  const corpo = righe.slice(fineFrontmatter + 1).join('\n').replace(/^[\r\n]+/, '');
+  return { campi, corpo };
+}
+
+/**
+ * Legge `<cartella>/.harness-ui-skills/*\/SKILL.md`. Un progetto senza
+ * skill dichiarate è uno stato valido — mai un errore, torna
+ * `{skills: []}`. Una singola skill malformata FERMA l'intero
+ * caricamento con un errore dichiarato (mai una skill fantasma
+ * ignorata in silenzio, stesso principio di caricaHooks/caricaServerMcp)
+ * — l'owner che ha sbagliato a scrivere un file deve saperlo.
+ */
+export async function caricaSkill({ cartella }, deps = {}) {
+  const readdirFn = deps.readdirFn ?? fsp.readdir;
+  const readFileFn = deps.readFileFn ?? fsp.readFile;
+  const cartellaSkills = join(cartella, NOME_CARTELLA_SKILLS);
+  let voci;
+  try {
+    voci = await readdirFn(cartellaSkills, { withFileTypes: true });
+  } catch (errore) {
+    if (errore?.code === 'ENOENT') return { skills: [] };
+    throw new SkillRegistryError(`Impossibile leggere ${NOME_CARTELLA_SKILLS}: ${errore.message}`, 'SKILL_READ_FAILED');
+  }
+  const skills = [];
+  for (const voce of voci) {
+    if (!voce.isDirectory()) continue; // un file sciolto dentro .harness-ui-skills/ non è una skill
+    const skillId = voce.name;
+    const percorso = join(cartellaSkills, skillId, NOME_FILE_SKILL);
+    let testo;
+    try {
+      testo = await readFileFn(percorso, 'utf8');
+    } catch (errore) {
+      if (errore?.code === 'ENOENT') continue; // una sottocartella senza SKILL.md non è una skill, non è un errore
+      throw new SkillRegistryError(`Impossibile leggere ${skillId}/${NOME_FILE_SKILL}: ${errore.message}`, 'SKILL_READ_FAILED');
+    }
+    const { campi, corpo } = analizzaSkillMd(testo, skillId);
+    if (typeof campi.name !== 'string' || campi.name.length === 0) {
+      throw new SkillRegistryError(`${skillId}/SKILL.md manca di "name" nel frontmatter`, 'SKILL_MALFORMED');
+    }
+    if (typeof campi.description !== 'string' || campi.description.length === 0) {
+      throw new SkillRegistryError(`${skillId}/SKILL.md manca di "description" nel frontmatter`, 'SKILL_MALFORMED');
+    }
+    skills.push({ id: skillId, name: campi.name, description: campi.description, corpo });
+  }
+  // ⭐ ordine deterministico — mai dipendere dall'ordine che il filesystem restituisce (varia per OS).
+  skills.sort((a, b) => a.id.localeCompare(b.id));
+  return { skills };
+}