talos-code 0.0.1 → 0.1.0

package/vendor/harness-ui/src/http-lifecycle.mjs

@@ -0,0 +1,132 @@
+/** Shared lifecycle primitives for HTTP requests, SSE streams and shutdown. */
+
+/*
+ * ⛔⛔⛔ P0 · punto 7 (16/09/2026) — QUI C'ERA UNA MINA: `createRequestLifecycle`, RIMOSSA.
+ *
+ * Era una funzione che abortiva una richiesta dopo `timeoutMs = 30_000`, e **non la usava
+ * nessuno**: misurato con `grep -rn createRequestLifecycle harness-ui --include=*.mjs` — due sole
+ * occorrenze, la sua definizione e il suo test. Zero chiamanti in tre mesi.
+ *
+ * ⛔ Perché toglierla invece di lasciarla lì: era pronta per essere cablata dal primo che avesse
+ *   cercato «lifecycle» per la rotta `/events`. E cablarla avrebbe ucciso OGNI sessione SSE dopo
+ *   trenta secondi — cioè avrebbe rimesso, in un colpo solo, il tetto di durata che questo punto
+ *   sta togliendo, dalla parte del server invece che da quella del fornitore. Un attrezzo che fa
+ *   la cosa sbagliata e aspetta paziente è peggio di un attrezzo mancante: il secondo lo scrivi
+ *   guardando il problema, il primo lo adotti perché c'era già.
+ * ⭐ Ciò che serviva davvero — chiudere quando il client se ne va — `createSseSession` lo fa già,
+ *   qui sotto, senza nessun orologio: ascolta `close` sulla risposta e l'abort del segnale.
+ * ⛔ Il cancello che impedisce di rimetterla sta in `tests/timeout-generazione-p0.test.mjs`
+ *   (P0-D-13), non nella memoria di qualcuno.
+ */
+
+/**
+ * ⛔⛔ P0 · punto 7 (16/09/2026) — I TEMPI DEL SERVER, DICHIARATI INVECE CHE SUBITI.
+ *
+ * `server.mjs` faceva `createServer(app)` e `listen()` senza toccare nessuno dei quattro tempi:
+ * quelli attivi erano quelli che capitavano. Misurati su **Node v24.18.0** (script su file, non
+ * `node -e`), il 16/09/2026:
+ *     server.timeout = 0 · headersTimeout = 60000 · keepAliveTimeout = 5000 · requestTimeout = 300000
+ * Sono i default di OGGI, e cambiano fra le versioni di Node — `server.timeout` valeva 120 s fino a
+ * Node 13. Una rotta SSE che deve reggere un ragionamento lungo non può dipendere da quale Node è
+ * installato sul computer di chi apre l'app.
+ *
+ * I quattro valori, e perché:
+ *  · `timeout: 0` — nessun guardiano di inattività sul SOCKET. È il valore che rende possibile una
+ *    risposta SSE lunga: qualunque numero qui ucciderebbe la chat mentre il modello pensa. Il
+ *    canale non resta comunque muto, perché il battito scrive ogni 15 s.
+ *  · `keepAliveTimeout: 72_000` — quanto si tiene aperta una connessione INUTILIZZATA fra due
+ *    richieste. Il default di 5 s fa ricostruire il socket di continuo a un'interfaccia che
+ *    chiacchiera; 72 s sono poco meno di cinque battiti, cioè comodamente oltre il ritmo con cui
+ *    l'app parla col server.
+ *  · `headersTimeout: 75_000` — **deve restare maggiore di `keepAliveTimeout`**: se fosse minore,
+ *    Node può chiudere un socket riusato mentre la richiesta successiva è per strada, e il browser
+ *    vede un `ECONNRESET` senza colpevole. Tre secondi di margine sopra il keep-alive.
+ *  · `requestTimeout: 300_000` — tempo per ricevere la RICHIESTA completa (intestazioni + corpo),
+ *    non la risposta: non tocca lo streaming in uscita, e a zero aprirebbe uno slowloris. Resta il
+ *    valore di Node, ma scritto, così nessuno deve andare a cercarlo.
+ *
+ * ⛔ Stanno QUI e non dentro `server.mjs` perché la prova che il battito regge oltre il vecchio
+ *   muro (`P0-D-12`, e la misura lunga in `tests/aiuto/`) deve usare gli STESSI numeri del
+ *   prodotto: due copie divergerebbero, e la prova continuerebbe a essere verde su numeri che
+ *   nessuno usa più.
+ */
+export const TEMPI_SERVER_HTTP = Object.freeze({
+  timeout: 0,
+  keepAliveTimeout: 72_000,
+  headersTimeout: 75_000,
+  requestTimeout: 300_000,
+});
+
+/**
+ * Applica i tempi dichiarati sopra a un server HTTP, e li restituisce come letti DAL server —
+ * non come li abbiamo chiesti.
+ *
+ * ⛔ Il ritorno è la lettura vera (`server.timeout`, …) perché un assegnamento che non attecchisse
+ *   (una versione di Node che rifiuta un valore, un server finto) lascerebbe il chiamante convinto
+ *   di aver deciso qualcosa. «L'ho scritto» e «è così» sono due misure diverse.
+ */
+export function applicaTempiDelServer(server, tempi = TEMPI_SERVER_HTTP) {
+  if (!server) return null;
+  for (const [nome, valore] of Object.entries(tempi)) server[nome] = valore;
+  return Object.freeze(Object.fromEntries(Object.keys(tempi).map((nome) => [nome, server[nome]])));
+}
+
+export function createSseSession({ response, heartbeatMs = 15_000, signal = null, lastEventId = 0, headers = {}, setIntervalFn = setInterval, clearIntervalFn = clearInterval } = {}) {
+  let closed = false;
+  let heartbeat = null;
+  let onResponseClose;
+  let onAbort;
+  const send = (event) => {
+    if (closed || response?.writableEnded || response?.destroyed) return false;
+    if (typeof event?._sequenza === 'number' && event._sequenza <= lastEventId) return false;
+    if (typeof event?._sequenza === 'number') response.write(`id: ${event._sequenza}\n`);
+    response.write(`data: ${JSON.stringify(event)}\n\n`);
+    return true;
+  };
+  const close = () => {
+    if (closed) return;
+    closed = true;
+    if (heartbeat !== null) clearIntervalFn(heartbeat);
+    response?.removeListener?.('close', onResponseClose);
+    signal?.removeEventListener?.('abort', onAbort);
+  };
+  const start = () => {
+    if (closed) return;
+    response.writeHead(200, {
+      ...headers,
+      'Content-Type': 'text/event-stream; charset=utf-8',
+      'Cache-Control': 'no-store',
+      Connection: 'keep-alive',
+    });
+    response.socket?.setNoDelay?.(true);
+    response.write(':ok\n\n');
+    onResponseClose = close;
+    response.once?.('close', onResponseClose);
+    onAbort = close;
+    signal?.addEventListener?.('abort', onAbort, { once: true });
+    heartbeat = setIntervalFn(() => {
+      if (closed || response.writableEnded || response.destroyed) { close(); return; }
+      response.write(':battito\n\n');
+    }, heartbeatMs);
+    heartbeat?.unref?.();
+  };
+  return Object.freeze({ start, send, close, get closed() { return closed; } });
+}
+
+export async function closeRuntimeResources(reason, { resources = [], logger = null } = {}) {
+  const pending = [];
+  for (const resource of resources) {
+    try {
+      const result = typeof resource?.abort === 'function' ? resource.abort(reason)
+        : typeof resource?.stop === 'function' ? resource.stop(reason)
+          : typeof resource?.close === 'function' ? resource.close(reason)
+            : typeof resource?.destroy === 'function' ? resource.destroy(reason) : undefined;
+      if (result && typeof result.then === 'function') pending.push(Promise.resolve(result).catch((error) => {
+        try { logger?.warn?.(`[runtime-close] ${error?.code || 'cleanup-failed'}`); } catch { /* cleanup best effort */ }
+      }));
+    } catch (error) {
+      try { logger?.warn?.(`[runtime-close] ${error?.code || 'cleanup-failed'}`); } catch { /* cleanup best effort */ }
+    }
+  }
+  await Promise.all(pending);
+}

package/vendor/harness-ui/src/id-archivio.mjs

@@ -0,0 +1,27 @@
+/*
+ * ⛔⛔⛔ 14/09/2026 — L'ID DI UN ARCHIVIO (Note/Attività/Memoria) ARRIVA DA FUORI, e finiva dritto nel percorso di un file.
+ *
+ * Trovato dalla review ingegneristica del 13/09 (F01) e CONFERMATO dal vivo su un banco a porta effimera: una
+ * `DELETE /api/v1/sessions/<id>/notes/..%5C<nome>` rispondeva 200 e cancellava un file FUORI da `.notes-store/`. La causa:
+ * `http-app.mjs` fa `decodeURIComponent` dell'id e lo passa a `percorsoDi(cartella, id) = join(cartella, id + '.json')`,
+ * senza nessun controllo — e lo stesso id arriva ANCHE dagli attrezzi del modello (`agent-service.mjs`, `argomenti?.id`),
+ * quindi la porta era aperta pure a un prompt-injection, non solo a una richiesta HTTP sul loopback.
+ *
+ * La Libreria aveva già chiuso lo stesso buco il 10/09 (`library-store.mjs#idVoceLibreriaValido`), con QUESTA identica
+ * grammatica. Le tre restanti no. La difesa sta nel magazzino, in un posto solo, così vale per tutti e due i chiamanti
+ * (la persona via HTTP e il modello via attrezzo) e non c'è una seconda copia che un giorno diverge.
+ *
+ * ⛔ Un id fuori grammatica NON è un'eccezione: `percorsoDi` torna `null` e chi lo chiama si comporta come per un id
+ *   assente — «questa voce non c'è». È vero (un id con una barra o `..` dentro non può nominare nessuna voce reale),
+ *   tiene l'idempotenza delle `elimina*` (un id già assente non è un errore) e non arriva in faccia al modello come un
+ *   guasto nuovo per una chiamata che oggi si chiude con un «non trovato». È la stessa scelta della Libreria.
+ *
+ * ⛔ La grammatica è quella della Libreria, non quella (più stretta, coi nomi riservati di Windows) della patch della
+ *   review: gli id di questi archivi li genera SEMPRE `randomUUID()` (solo esadecimali e trattini), il primo carattere
+ *   dev'essere alfanumerico — quindi `..`, `a/b`, `a\b`, un id vuoto e ogni separatore o `..` sono già respinti, cioè
+ *   TUTTO ciò che fa uscire dalla cartella. Restare sulla stessa grammatica della Libreria è la regola di casa: una
+ *   difesa sola, non due che divergono.
+ */
+export function idArchivioValido(id) {
+  return typeof id === 'string' && /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(id);
+}

package/vendor/harness-ui/src/image-generator.mjs

@@ -0,0 +1,143 @@
+/**
+ * image-generator.mjs — FASE H del piano `elegant-spinning-dongarra.md`
+ * (29/8): chiama la Image API di OpenRouter (lanciata fine giugno
+ * 2026), la STESSA chiave già in `config.mjs` — zero provider nuovo,
+ * il one-up dichiarato: niente attrezzo immagine verso un provider
+ * separato dal modello di chat.
+ *
+ * Codici d'errore `TALOS_IMAGE_*` — stessa famiglia di nomi già in
+ * uso nell'omologo mobile (`mobile/src/lib/images/imageTools.ts`:
+ * `TALOS_IMAGE_NO_PROVIDER`/`TALOS_IMAGE_SOURCE_NOT_FOUND`/...), non
+ * inventata qui — un modello che ha già visto quei codici (in
+ * un'altra conversazione, o nella sua formazione) li riconosce.
+ *
+ * Due percorsi CONFERMATI (29/8, tre fonti incluso il riferimento API
+ * ufficiale, non presunti — vedi il piano madre, FASE H):
+ * - **DEDICATO** (`nativo:false`): `POST /api/v1/images`, corpo
+ *   `{model, prompt, aspect_ratio}`, risposta
+ *   `data[0].{b64_json, media_type}`. Il catalogo di questi modelli è
+ *   `GET /api/v1/images/models` — un endpoint SEPARATO da
+ *   `/api/v1/models` (verificato dal vivo il 29/8: un modello dedicato
+ *   reale, `bytedance-seed/seedream-4.5`, NON compare affatto in
+ *   `/api/v1/models` — solo i modelli NATIVI ci compaiono, con
+ *   `architecture.output_modalities` che include `"image"`).
+ * - **NATIVO** (`nativo:true`): `POST /api/v1/chat/completions`
+ *   STANDARD (lo stesso endpoint che il kernel già chiama per il
+ *   testo) con `modalities:["text","image"]` nel corpo — l'immagine
+ *   arriva in `choices[0].message.images[0].image_url.url`, una data
+ *   URL (`data:<mediaType>;base64,<dati>`), MAI in `data[].b64_json`
+ *   (quello è solo del percorso dedicato).
+ *
+ * ⛔ Quale dei due usare NON si indovina qui — è una proprietà del
+ * MODELLO scelto (`config.mjs`, `immagine.nativo`), decisa a monte:
+ * questo modulo non chiama nessun catalogo per scoprirlo (un giro di
+ * rete in più per ogni immagine, per un fatto che il chiamante può
+ * già sapere). I due cataloghi VERI esistono e sono stati verificati
+ * dal vivo il 29/8 — restano per un futuro picker owner-facing
+ * (mirror del picker `modello` già in uso), non per questa decisione
+ * a runtime.
+ *
+ * ⛔ Aspect ratio sul percorso NATIVO: non inviato in questa fetta —
+ * un campo che alcune fonti secondarie citano (`image_config.aspect_ratio`)
+ * non è confermato nel riferimento API ufficiale consultato il 29/8;
+ * mai un campo non verificato nella chiamata vera. Il prompt può
+ * comunque descrivere l'inquadratura in linguaggio naturale.
+ */
+import { talosSafeFileStem } from './document-filename.mjs';
+
+/*
+ * ⛔⛔⛔ DICHIARATO E NON CURATO — CLI-REQ-05, punto 3 del terzo giro (17/09/2026).
+ *
+ * Questi due indirizzi sono FISSI e la chiamata parte da una `fetch` nuda: in una sessione il cui
+ * fornitore NON è OpenRouter — una DeepSeek, una locale — il prompt dell'immagine va comunque a
+ * openrouter.ai. È la stessa classe del difetto curato per la compattazione e per il giudice
+ * (`session-registry.mjs`, `compatta()` e `creaChiediAlModelloGiudice`), che adesso passano dalla
+ * destinazione multi-fornitore dell'host col modello DELLA SESSIONE.
+ *
+ * ⇒ NON si cura qui, ed è una scelta dichiarata, non una dimenticanza: la generazione di immagini
+ *   è nata su OpenRouter come unico fornitore («zero provider nuovo»), e spostarla vuol dire
+ *   decidere quale fornitore genera le immagini per una sessione che non è di OpenRouter — una
+ *   decisione dell'owner, non di questa riga.
+ * ⛔ Finché resta così: chi sceglie una sessione locale perché niente esca, e poi chiede
+ *   un'immagine, manda comunque il suo prompt a openrouter.ai. Sta scritto qui perché la prossima
+ *   persona che legge questo file lo sappia senza doverlo scoprire.
+ */
+const OPENROUTER_IMAGES_URL = 'https://openrouter.ai/api/v1/images';
+const OPENROUTER_CHAT_URL = 'https://openrouter.ai/api/v1/chat/completions';
+
+/** ⭐ Le tre forme che il tool del kernel offre — stesso vocabolario di `mobile/src/lib/images/imageTools.ts` (`SHAPES`), non un terzo nuovo. */
+export const ASPECT_RATIO_PER_FORMA = Object.freeze({ square: '1:1', portrait: '9:16', landscape: '16:9' });
+
+function decodeDataUrl(dataUrl) {
+  const match = /^data:([^;]+);base64,(.+)$/s.exec(dataUrl ?? '');
+  if (!match) throw new Error('TALOS_IMAGE_BAD_RESPONSE: OpenRouter has returned an image in an unexpected format (not a base64 data URL).');
+  return { mediaType: match[1], bytes: Buffer.from(match[2], 'base64') };
+}
+
+async function leggiCorpoJson(risposta, dove) {
+  try {
+    return await risposta.json();
+  } catch {
+    throw new Error(`TALOS_IMAGE_BAD_RESPONSE: ${dove} returned a response that is not valid JSON.`);
+  }
+}
+
+async function chiamaImmaginiDedicato({ prompt, shape, modello, chiave }, fetchFn) {
+  let risposta;
+  try {
+    risposta = await fetchFn(OPENROUTER_IMAGES_URL, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${chiave}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ model: modello, prompt, aspect_ratio: ASPECT_RATIO_PER_FORMA[shape] ?? '1:1' }),
+    });
+  } catch (errore) {
+    throw new Error(`TALOS_IMAGE_UNREACHABLE: the OpenRouter Image API could not be reached (${errore instanceof Error ? errore.message : String(errore)}).`);
+  }
+  const corpo = await leggiCorpoJson(risposta, 'the OpenRouter Image API');
+  if (!risposta.ok) {
+    throw new Error(`TALOS_IMAGE_UPSTREAM_ERROR: the OpenRouter Image API responded ${risposta.status} (${corpo?.error?.message ?? 'no detail'}).`);
+  }
+  const voce = corpo?.data?.[0];
+  if (!voce?.b64_json) throw new Error('TALOS_IMAGE_BAD_RESPONSE: the OpenRouter Image API response has no image data.');
+  return { mediaType: typeof voce.media_type === 'string' && voce.media_type ? voce.media_type : 'image/png', bytes: Buffer.from(voce.b64_json, 'base64') };
+}
+
+async function chiamaImmaginiNativo({ prompt, modello, chiave }, fetchFn) {
+  let risposta;
+  try {
+    risposta = await fetchFn(OPENROUTER_CHAT_URL, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${chiave}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ model: modello, messages: [{ role: 'user', content: prompt }], modalities: ['text', 'image'] }),
+    });
+  } catch (errore) {
+    throw new Error(`TALOS_IMAGE_UNREACHABLE: OpenRouter could not be reached for native image generation (${errore instanceof Error ? errore.message : String(errore)}).`);
+  }
+  const corpo = await leggiCorpoJson(risposta, 'OpenRouter (native image generation)');
+  if (!risposta.ok) {
+    throw new Error(`TALOS_IMAGE_UPSTREAM_ERROR: OpenRouter responded ${risposta.status} for native image generation (${corpo?.error?.message ?? 'no detail'}).`);
+  }
+  const dataUrl = corpo?.choices?.[0]?.message?.images?.[0]?.image_url?.url;
+  if (!dataUrl) {
+    throw new Error('TALOS_IMAGE_NO_IMAGE: the model did not return an image — it may have answered in text only. Try a more explicit drawing prompt, or a dedicated image model.');
+  }
+  return decodeDataUrl(dataUrl);
+}
+
+/**
+ * `spec.shape` è ignorato sul percorso nativo (vedi la doc sopra sul
+ * campo non confermato) — non un bug, un limite dichiarato.
+ * @param {{prompt:string, shape?:'square'|'portrait'|'landscape', modello:string, nativo:boolean, chiave:string}} spec
+ * @param {{fetchFn?: typeof fetch}} [deps]
+ * @returns {Promise<{mediaType:string, bytes:Buffer, fileStem:string}>}
+ */
+export async function generaImmagineOpenRouter(spec, deps = {}) {
+  const fetchFn = deps.fetchFn ?? fetch;
+  const { prompt, shape, modello, nativo, chiave } = spec;
+  const { mediaType, bytes } = nativo
+    ? await chiamaImmaginiNativo({ prompt, modello, chiave }, fetchFn)
+    : await chiamaImmaginiDedicato({ prompt, shape, modello, chiave }, fetchFn);
+  // ⭐ un nome file leggibile dal prompt, mai "immagine-<uuid>" — stesso principio di talosSafeFileStem già in uso per document-generator.mjs.
+  const fileStem = talosSafeFileStem(prompt, 80, 'immagine');
+  return { mediaType, bytes, fileStem };
+}

package/vendor/harness-ui/src/istruzioni-di-progetto.mjs

@@ -0,0 +1,234 @@
+/**
+ * BC-48 A (12/09/2026): indice della radice e dei file oltre 60 righe; sezioni sempre
+ * intere, commenti HTML esterni al codice rimossi. Il compositore omette file interi
+ * con avviso. Il resoconto storico sotto e `tagliaIstruzioni` descrivono il contratto
+ * precedente; la funzione esportata resta per compatibilità, fuori dal preambolo.
+ *
+ * istruzioni-di-progetto.mjs — BLOCCO 3 del preambolo: `AGENTS.md` / `CLAUDE.md`, con un tetto
+ * di byte DICHIARATO e un troncamento che dice dove riprendere.
+ *
+ * ── IL DIFETTO CHE CHIUDE ────────────────────────────────────────────────────────────────────
+ *
+ * Misurato l'11/09/2026 (`.claude/RAPPORTO-PREAMBOLO-CONCORRENTI-2026-09-11.md` §6.3): in
+ * `harness-ui/src/` i nomi `AGENTS.md` e `CLAUDE.md` comparivano **solo** in `path-policy.mjs:35`
+ * (permessi) e dentro i commenti. ⇒ **Al modello arrivavano 17.000 token di inventario dei file e
+ * ZERO byte di istruzioni del progetto** — l'esatto contrario di tutti e quattro i concorrenti
+ * letti nel codice lo stesso giorno:
+ *   · Codex .......... `agents_md.rs`, catena dalla radice del progetto al cwd, tetto
+ *                      `AGENTS_MD_MAX_BYTES = 32 KiB`, e il commento dice *«Larger files are
+ *                      silently truncated»*;
+ *   · Claude Code .... budget `max(40.000, 5% della finestra)`, taglio per file a 200 righe /
+ *                      25.000 byte con una sezione `WARNING` che lo dichiara;
+ *   · Hermes v0.21 ... `CONTEXT_FILE_MAX_CHARS = 20_000`, head 70% / tail 20%, e il marcatore dice
+ *                      **dove riprendere** (`read_file` sul percorso vero);
+ *   · DeepSeek `dsh` . budget in byte **obbligatorio** in configurazione (65.536 di serie), e la
+ *                      politica: *«it drops whole broader files before truncating the most-specific
+ *                      file, and emits a visible `Workspace instruction budget …` notice naming the
+ *                      omitted and truncated paths»*.
+ *
+ * RICERCA WEB, letta l'11/09/2026 PRIMA di scrivere:
+ *  1. Specifica aperta AGENTS.md <https://agents.md/> — verbatim: *«Place another AGENTS.md inside
+ *     each package. Agents automatically read the nearest file in the directory tree, so the
+ *     closest one takes precedence.»* e *«used by over 60k open-source projects»*. ⛔ La specifica
+ *     **non dichiara nessun tetto di byte**: il tetto è una scelta di ogni harness, e ogni harness
+ *     che abbiamo letto ne ha uno. Chi non ce l'ha, prima o poi manda in contesto un file da 200 KB.
+ *  2. Claude Platform Docs, «Prompt caching» (letto 11/09/2026,
+ *     <https://platform.claude.com/docs/en/docs/build-with-claude/prompt-caching>) — *«Cache hits
+ *     require 100% identical prompt segments»*: il testo prodotto qui sta nel PREFISSO, quindi
+ *     dev'essere una funzione pura del contenuto dei file, senza orari, senza percorsi assoluti,
+ *     senza niente che cambi da una chiamata all'altra.
+ *
+ * ── LE QUATTRO DECISIONI ─────────────────────────────────────────────────────────────────────
+ *
+ * (1) LA CATENA, dalla radice del progetto al cwd, il più SPECIFICO per ULTIMO. È la forma di
+ *     Codex (`agents_md.rs`: *«Collect every AGENTS.md found from the project root down to the
+ *     current working directory (inclusive) and concatenate their contents in that order»*) e la
+ *     precedenza che la specifica dichiara. L'ultimo letto vince perché è l'ultimo letto: non
+ *     serve nessuna regola in più, e il testo lo dice al modello a parole.
+ *     ⛔ Non si risale MAI oltre la radice del progetto: un `AGENTS.md` nella home dell'utente
+ *     riguarda un altro lavoro, e trascinarlo dentro sarebbe rifare il difetto del `.gitignore`
+ *     che ereditava regole da fuori (curato in `gitignore-elenco.mjs`).
+ *
+ * (2) UN SOLO FILE PER CARTELLA, nell'ordine `AGENTS.md` poi `CLAUDE.md` — i candidati di serie di
+ *     `dsh` (`packages/context/agent-instructions/src/config.ts:11-15`). Prenderli entrambi
+ *     significherebbe pagare due volte lo stesso contenuto in un repo che li tiene allineati, ed è
+ *     esattamente il caso di questo repo.
+ *
+ * (3) IL TETTO SI DICHIARA, e il troncamento è ONESTO. Due livelli, come `dsh`:
+ *       · se la catena sfora, si tolgono INTERI i file più GENERICI (i più lontani dal cwd) prima
+ *         di tagliare il più specifico — quello vicino al lavoro è quello che serve;
+ *       · il file che resta e sfora si taglia head 70% / tail 20% (Hermes), e il marcatore dice
+ *         quanti caratteri mancano e **con quale attrezzo** leggere il file intero.
+ *     ⛔ Un taglio silenzioso è il difetto che questo progetto ha già pagato sulla propria
+ *     memoria: `MEMORY.md` perde righe oltre 200/25.000 senza un avviso in sessione, e nessuno
+ *     se n'era accorto per settimane. Qui il taglio è una RIGA DI TESTO, non un effetto.
+ *
+ * (4) SE NON C'È NIENTE, IL BLOCCO NON ESISTE. Nessuna intestazione vuota, nessun «(nessuna
+ *     istruzione trovata)»: zero byte. È il principio che Hermes scrive in chiaro
+ *     (`system_prompt.py:713-716`): *«Emits a single line; emits NOTHING when the environment is
+ *     clean (no token cost)»*.
+ */
+import { readFile, stat } from 'node:fs/promises';
+import { dirname, join, parse, relative, sep } from 'node:path';
+import { rendiFileIstruzioni } from './sezioni-istruzioni.mjs';
+
+/**
+ * Il tetto, in BYTE, dell'intero blocco 3. 24.000 sta fra Hermes (20.000 caratteri) e Codex
+ * (32 KiB), e sotto `dsh` (65.536). Perché non di più: a 3,5 byte/token (la taratura misurata il
+ * 09/09 su `z-ai/glm-5.3-flash`, `costo-elenco.mjs`) sono ~6.900 token, cioè già il 40% di tutto
+ * ciò che l'elenco dei file costava su `AVM/mobile` prima di questa cura (17.149 token misurati).
+ * Un tetto più alto renderebbe il preambolo nuovo non più leggero di quello vecchio nel caso
+ * peggiore, e il caso peggiore è l'unico che conta.
+ * ⛔ È un ARGOMENTO, non una legge: chi ha un progetto con istruzioni enormi lo alza sapendo cosa
+ *    paga. Ciò che non è negoziabile è che sia DICHIARATO nel testo quando morde.
+ */
+export const TETTO_BYTE_PREDEFINITO = 24_000;
+
+/** I candidati, nell'ordine in cui si guardano dentro una cartella. Vedi decisione (2). */
+export const NOMI_CANDIDATI = Object.freeze(['AGENTS.md', 'CLAUDE.md']);
+
+/** Quanti livelli si risale al massimo cercando la radice del progetto. */
+export const RISALITA_MASSIMA = 40;
+
+/** Quote del taglio per file: testa 70%, coda 20%, il 10% di mezzo è il marcatore e il margine. */
+export const QUOTA_TESTA = 0.7;
+export const QUOTA_CODA = 0.2;
+
+const normalizza = (p) => String(p).replace(/\\/g, '/');
+
+/**
+ * La radice del progetto: la prima cartella, risalendo, che ha un `.git`.
+ * ⛔ `.git` si cerca con `stat` e non si distingue DIRECTORY da FILE: in un worktree è un file, ed
+ *    è il caso di oggi su questo repo. È la stessa scelta di ripgrep (`Ignore::add_parents`, che
+ *    usa `exists()`) già documentata in `gitignore-elenco.mjs`.
+ */
+export async function trovaRadiceProgetto(cartella, { fs, risalitaMassima = RISALITA_MASSIMA } = {}) {
+  const disco = { stat, ...(fs ?? {}) };
+  let corrente = String(cartella ?? '');
+  for (let i = 0; i < risalitaMassima && corrente; i += 1) {
+    try {
+      await disco.stat(join(corrente, '.git'));
+      return corrente;
+    } catch { /* non è la radice: si sale */ }
+    const sopra = dirname(corrente);
+    if (!sopra || sopra === corrente || sopra === parse(corrente).root) break;
+    corrente = sopra;
+  }
+  return null;
+}
+
+/**
+ * Trova i file di istruzioni della catena, dalla radice del progetto al cwd.
+ * @returns {Promise<{percorso:string, etichetta:string, lettura:string, contenuto:string, byte:number}[]>}
+ *   in ordine dal più GENERICO al più SPECIFICO (l'ultimo vince).
+ */
+export async function trovaIstruzioniDiProgetto(cartella, { fs, nomi = NOMI_CANDIDATI, risalitaMassima = RISALITA_MASSIMA } = {}) {
+  const disco = { readFile, stat, ...(fs ?? {}) };
+  const cwd = String(cartella ?? '');
+  if (!cwd) return [];
+  const radice = await trovaRadiceProgetto(cwd, { fs, risalitaMassima }) ?? cwd;
+
+  /* Le cartelle da guardare: dalla radice del progetto giù fino al cwd, incluse entrambe. */
+  const tratto = relative(radice, cwd);
+  const pezzi = tratto && tratto !== '.' ? tratto.split(sep).filter(Boolean) : [];
+  const cartelle = [radice];
+  let corrente = radice;
+  for (const pezzo of pezzi) {
+    corrente = join(corrente, pezzo);
+    cartelle.push(corrente);
+  }
+
+  const trovati = [];
+  for (const dove of cartelle) {
+    for (const nome of nomi) {
+      let contenuto;
+      try {
+        contenuto = await disco.readFile(join(dove, nome), 'utf8');
+      } catch { continue; } // non c'è, o non si legge: si passa al candidato dopo
+      if (typeof contenuto !== 'string' || contenuto.trim() === '') continue;
+      /*
+       * ⛔ L'ETICHETTA È RELATIVA ALLA RADICE DEL PROGETTO, MAI ASSOLUTA. Un percorso assoluto
+       *    contiene il nome della persona e questo testo esce dalla macchina dentro un prompt —
+       *    lezione [[cancello-4-non-guardava-tutto-mobile]]. E in più: un percorso assoluto
+       *    cambia da macchina a macchina, quindi romperebbe il prefisso della cache fra due
+       *    installazioni dello stesso progetto.
+       */
+      const etichetta = normalizza(relative(radice, join(dove, nome))) || nome;
+      trovati.push({ percorso: join(dove, nome), etichetta, lettura: normalizza(relative(cwd, join(dove, nome))), contenuto, byte: Buffer.byteLength(contenuto, 'utf8') });
+      break; // decisione (2): un solo file per cartella
+    }
+  }
+  return trovati;
+}
+
+/**
+ * Taglia un contenuto al tetto dato, testa 70% / coda 20%, e DICE dove riprendere.
+ * ⛔ Si taglia sui BYTE (non sui caratteri) perché il tetto è in byte e un carattere accentato ne
+ *    vale 2: contare caratteri farebbe sforare il tetto proprio sui testi italiani, cioè i nostri.
+ *    E si ritaglia all'a-capo più vicino, per non spezzare una riga a metà parola.
+ */
+export function tagliaIstruzioni(contenuto, tetto, etichetta) {
+  const byte = Buffer.byteLength(contenuto, 'utf8');
+  if (byte <= tetto) return { testo: contenuto, tagliato: false, byteTenuti: byte, byteTotali: byte };
+
+  const buf = Buffer.from(contenuto, 'utf8');
+  const byteTesta = Math.max(0, Math.floor(tetto * QUOTA_TESTA));
+  const byteCoda = Math.max(0, Math.floor(tetto * QUOTA_CODA));
+  /* `toString` su un taglio a metà di una sequenza UTF-8 produce U+FFFD: si accetta e si ripulisce
+     all'a-capo, invece di fingere che il taglio sui byte sia sempre su un confine di carattere. */
+  let testa = buf.subarray(0, byteTesta).toString('utf8');
+  const aCapoTesta = testa.lastIndexOf('\n');
+  if (aCapoTesta > byteTesta * 0.5) testa = testa.slice(0, aCapoTesta);
+  let coda = buf.subarray(buf.length - byteCoda).toString('utf8');
+  const aCapoCoda = coda.indexOf('\n');
+  if (aCapoCoda >= 0 && aCapoCoda < byteCoda * 0.5) coda = coda.slice(aCapoCoda + 1);
+
+  const mancanti = byte - Buffer.byteLength(testa, 'utf8') - Buffer.byteLength(coda, 'utf8');
+  const marcatore = `\n\n[...«${etichetta}» è stato TAGLIATO: di ${byte} byte ne vedi i primi ~${Buffer.byteLength(testa, 'utf8')} e gli ultimi ~${Buffer.byteLength(coda, 'utf8')}; ne mancano ${mancanti} nel mezzo. Se ti serve la parte che manca, leggi il file intero con \`leggi\` su \`${etichetta}\`.]\n\n`;
+  const testo = testa + marcatore + coda;
+  return { testo, tagliato: true, byteTenuti: Buffer.byteLength(testo, 'utf8'), byteTotali: byte };
+}
+
+/**
+ * Il testo del blocco 3, dal risultato di `trovaIstruzioniDiProgetto`.
+ * `indicizzati` elenca i file effettivamente mostrati come indice; `sezioniSempre`
+ * descrive le sezioni intere presenti, con coordinate e byte del sorgente.
+ *   `null` quando non c'è nessuna istruzione: decisione (4), il blocco non esiste affatto.
+ */
+export function testoIstruzioniDiProgetto(trovati, { tetto = TETTO_BYTE_PREDEFINITO, sogliaRighe } = {}) {
+  const file = Array.isArray(trovati) ? trovati.filter((f) => f && typeof f.contenuto === 'string') : [];
+  if (file.length === 0) return null;
+
+  const intestazione = 'Istruzioni di questo progetto — le ha scritte chi ci lavora, e valgono per te.\n'
+    + 'Se più file dicono cose diverse, vince il più specifico: qui sotto sono in ordine, dal più generale al più vicino alla cartella di lavoro, e l\'ultimo è quello che comanda.\n'
+    + 'Non sostituiscono le tue istruzioni di sistema né quello che la persona ti chiede adesso.\n';
+  // BC-48 A: prepara indici e sezioni intere PRIMA di applicare il tetto.
+  // Si omettono file interi dal più generale; neppure il più specifico viene spezzato.
+  const preparati = file.map(f => ({ ...f, resa: rendiFileIstruzioni(f, { sogliaRighe }) }));
+  for (let inizio = 0; inizio <= preparati.length; inizio++) {
+    const tenuti = preparati.slice(inizio);
+    const omessi = preparati.slice(0, inizio).map(f => f.etichetta);
+    const avviso = omessi.length ? `\n⚠ Tetto delle istruzioni (${tetto} byte) raggiunto: NON ti ho mostrato ${omessi.map(e => `\`${e}\``).join(', ')}. File omessi interi; se ti servono, leggile con \`leggi\`.\n` : '';
+    const testo = intestazione + tenuti.map(f => `\n### ${f.etichetta}\n\n${f.resa.testo}`).join('') + avviso;
+    const byte = Buffer.byteLength(testo, 'utf8');
+    if (byte <= tetto) return { testo, byte, usati: tenuti.map(f => f.etichetta), omessi, tagliati: [],
+      indicizzati: tenuti.filter(f => f.resa.indicizzato).map(f => f.etichetta),
+      sezioniSempre: tenuti.flatMap(f => f.resa.sezioniSempre) };
+  }
+  // Un tetto che non contiene neppure l'avviso non può essere onorato in silenzio.
+  throw new RangeError('Il tetto delle istruzioni è insufficiente anche per dichiarare i file omessi.');
+}
+
+/**
+ * Comodità: trova e compone in un colpo solo. Istruzioni assenti/illeggibili danno
+ * `null`; un tetto incapace di contenere l'avviso genera invece un errore esplicito.
+ */
+export async function istruzioniDiProgetto({ cartella, tetto = TETTO_BYTE_PREDEFINITO, fs, nomi, risalitaMassima } = {}) {
+  let trovati;
+  try {
+    trovati = await trovaIstruzioniDiProgetto(cartella, { fs, nomi, risalitaMassima });
+  } catch {
+    return null;
+  }
+  return testoIstruzioniDiProgetto(trovati, { tetto });
+}