talos-code 0.0.1 → 0.1.0

package/vendor/harness-ui/src/workspace-info.mjs

@@ -0,0 +1,189 @@
+/*
+ * Cosa c'è davvero dentro la cartella che stai per dare a un agente.
+ *
+ * Decisioni del 04/09 sulla modale «Nuova sessione»:
+ *  - F9  avvisa se la cartella scelta è una radice (il disco intero, la scrivania, la home);
+ *  - F10 dice QUANTI file ha, prima di partire, non dopo;
+ *  - F19 il ramo git corrente · F20 le modifiche non salvate · F21 i repo annidati.
+ * Nell'audit del 06/09 erano tutte e cinque ❌: la modale non diceva niente di tutto questo, e
+ * l'unico modo di scoprirlo era avviare una sessione e guardarla annaspare.
+ *
+ * ⛔ Contare i file di una cartella enorme è ESSO STESSO il problema: VS Code, aprendo una cartella
+ * con milioni di voci, arriva a piantarsi, e la sua stessa guida dice di avvisare invece di
+ * espandere (microsoft/vscode #237394, #75004, letti 06/09/2026). Quindi qui si conta CON UN TETTO:
+ * si smette a `TETTO_FILE` e si risponde «più di N», che è esattamente l'informazione che serve —
+ * nessuno ha bisogno del numero esatto quando il numero è «troppi».
+ * ⛔ E si saltano le cartelle che non sono lavoro (`node_modules`, `.git`, cache): contarle darebbe
+ * un numero vero e inutile, e costerebbe la parte più lenta della scansione.
+ *
+ * ⛔ I repo annidati non si scoprono da soli: VS Code li cerca esplicitamente e con un limite di
+ * profondità (microsoft/vscode #87888, #133577). Stessa scelta qui: profondità 3, che copre
+ * `mobile/`, `packages/*` e i vendor, senza camminare l'albero intero.
+ */
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join, parse, sep } from 'node:path';
+import { spawn } from 'node:child_process';
+
+export const TETTO_FILE = 20_000;
+
+/*
+ * I numeri si scrivono all'italiana con una funzione nostra, non con `toLocaleString`: la
+ * formattazione locale dipende dai dati ICU compilati in Node, e su un ambiente senza ICU completo
+ * «1234» resta «1234». Un separatore che a volte c'è e a volte no è peggio di nessun separatore.
+ */
+export function numeroItaliano(n) {
+  const v = Number(n);
+  if (!Number.isFinite(v)) return '0';
+  return String(Math.trunc(Math.abs(v))).replace(/\B(?=(\d{3})+(?!\d))/g, '.').replace(/^/, v < 0 ? '-' : '');
+}
+export const PROFONDITA_REPO_ANNIDATI = 3;
+const SALTA = new Set(['node_modules', '.git', '.hg', '.svn', 'dist', 'build', 'out', '.next', '.cache', '.venv', 'venv', '__pycache__', '.gradle', 'target', 'vendor', '.turbo', '.parcel-cache']);
+
+/**
+ * Una radice è una cartella che non si dà a un agente a cuor leggero: il disco intero, la home,
+ * la scrivania, i documenti. Non si vieta — si avvisa (F9).
+ */
+export function eUnaRadice(percorso) {
+  const grezzo = String(percorso || '');
+  if (!grezzo) return false;
+  const p = grezzo.replace(/[\/]+$/, '');
+  /*
+   * ⛔ misurato dalla prova: togliendo la barra finale «C:\» diventa «C:» e «/» diventa la stringa
+   * vuota, e nessuna delle due somigliava più a una radice. Le due forme si riconoscono PRIMA del resto.
+   */
+  if (p === '' || /^[a-z]:$/i.test(p)) return true;
+  const analisi = parse(p);
+  if (analisi.root && (p + sep) === analisi.root) return true;
+  if (p === analisi.root) return true;
+  const ultimo = p.split(/[\\/]/).pop()?.toLowerCase() || '';
+  const nomiRadice = new Set(['desktop', 'scrivania', 'documents', 'documenti', 'downloads', 'download', 'users', 'home', 'utenti']);
+  if (nomiRadice.has(ultimo)) return true;
+  // la home dell'utente: due segmenti sotto la radice, sotto Users/home
+  const pezzi = p.split(/[\\/]/).filter(Boolean);
+  if (pezzi.length === 2 && /^(users|home|utenti)$/i.test(pezzi[0])) return true;
+  if (pezzi.length === 3 && /^[a-z]:$/i.test(pezzi[0]) && /^(users|utenti)$/i.test(pezzi[1])) return true;
+  return false;
+}
+
+/** Conta i file veri fino al tetto, saltando ciò che non è lavoro. Torna `{ file, cartelle, oltre }`. */
+export async function contaFile(percorso, { tetto = TETTO_FILE, salta = SALTA } = {}) {
+  let file = 0; let cartelle = 0; let oltre = false;
+  const coda = [percorso];
+  while (coda.length > 0) {
+    const corrente = coda.shift();
+    let voci;
+    try { voci = await readdir(corrente, { withFileTypes: true }); } catch { continue; }
+    for (const voce of voci) {
+      if (voce.isDirectory()) {
+        if (salta.has(voce.name)) continue;
+        cartelle += 1;
+        coda.push(join(corrente, voce.name));
+      } else if (voce.isFile()) {
+        file += 1;
+        if (file >= tetto) { oltre = true; return { file, cartelle, oltre }; }
+      }
+    }
+  }
+  return { file, cartelle, oltre };
+}
+
+function git(argomenti, cwd) {
+  return new Promise((risolvi) => {
+    let uscita = '';
+    let processo;
+    try {
+      processo = spawn('git', argomenti, { cwd, windowsHide: true });
+    } catch { risolvi(null); return; }
+    const timer = setTimeout(() => { try { processo.kill(); } catch { /* già morto */ } risolvi(null); }, 4000);
+    processo.stdout?.on('data', (pezzo) => { uscita += String(pezzo); });
+    processo.on('error', () => { clearTimeout(timer); risolvi(null); });
+    processo.on('close', (codice) => { clearTimeout(timer); risolvi(codice === 0 ? uscita : null); });
+  });
+}
+
+/** Ramo, modifiche non salvate, repo annidati (F19-F21). Se non è un repo, torna `null` senza rumore. */
+export async function statoGit(percorso, { profondita = PROFONDITA_REPO_ANNIDATI, eseguiGit = git } = {}) {
+  const dentro = await eseguiGit(['rev-parse', '--is-inside-work-tree'], percorso);
+  if (!dentro || dentro.trim() !== 'true') return null;
+  const ramo = (await eseguiGit(['rev-parse', '--abbrev-ref', 'HEAD'], percorso) || '').trim() || null;
+  const stato = await eseguiGit(['status', '--porcelain'], percorso);
+  const nonSalvate = stato === null ? null : stato.split('\n').filter((r) => r.trim()).length;
+  const annidati = await repoAnnidati(percorso, profondita);
+  return { ramo, nonSalvate, repoAnnidati: annidati };
+}
+
+/** Le cartelle che hanno un `.git` proprio, sotto quella scelta, fino alla profondità data. */
+export async function repoAnnidati(percorso, profondita = PROFONDITA_REPO_ANNIDATI, livello = 1) {
+  if (livello > profondita) return [];
+  let voci;
+  try { voci = await readdir(percorso, { withFileTypes: true }); } catch { return []; }
+  const trovati = [];
+  for (const voce of voci) {
+    if (!voce.isDirectory() || SALTA.has(voce.name)) continue;
+    const figlio = join(percorso, voce.name);
+    let suo = false;
+    try { await stat(join(figlio, '.git')); suo = true; } catch { /* non è un repo */ }
+    if (suo) { trovati.push(figlio); continue; } // dentro un repo annidato non si scende oltre
+    trovati.push(...await repoAnnidati(figlio, profondita, livello + 1));
+  }
+  return trovati;
+}
+
+/** Le istruzioni dell'agente già presenti nella cartella: dicono che il progetto è già «abitato». */
+export async function istruzioniPresenti(percorso) {
+  const nomi = ['CLAUDE.md', 'AGENTS.md', 'TALOS.md', '.talos'];
+  const trovate = [];
+  for (const nome of nomi) {
+    try { await stat(join(percorso, nome)); trovate.push(nome); } catch { /* non c'è */ }
+  }
+  return trovate;
+}
+
+/**
+ * Il ritratto completo della cartella, quello che la modale scrive prima di avviare.
+ * Non lancia mai: una cartella illeggibile torna `leggibile: false` invece di rompere la modale.
+ */
+export async function ritrattoCartella(percorso, opzioni = {}) {
+  const p = String(percorso || '');
+  if (!p) return { percorso: p, leggibile: false };
+  let esiste = false;
+  try { const s = await stat(p); esiste = s.isDirectory(); } catch { esiste = false; }
+  if (!esiste) return { percorso: p, leggibile: false };
+  const [conteggio, gitInfo, istruzioni] = await Promise.all([
+    contaFile(p, opzioni),
+    statoGit(p, opzioni).catch(() => null),
+    istruzioniPresenti(p).catch(() => []),
+  ]);
+  return {
+    percorso: p,
+    leggibile: true,
+    radice: eUnaRadice(p),
+    file: conteggio.file,
+    cartelle: conteggio.cartelle,
+    oltreIlTetto: conteggio.oltre,
+    tetto: opzioni.tetto ?? TETTO_FILE,
+    git: gitInfo,
+    istruzioni,
+  };
+}
+
+/** La frase che la modale mostra: una riga, in italiano, coi numeri veri. */
+export function frasiRitratto(ritratto) {
+  if (!ritratto || !ritratto.leggibile) return 'Non riesco a leggere questa cartella.';
+  const pezzi = [];
+  pezzi.push(ritratto.oltreIlTetto ? `più di ${numeroItaliano(ritratto.tetto)} file` : `${numeroItaliano(ritratto.file)} file`);
+  if (ritratto.cartelle > 0) pezzi.push(`${numeroItaliano(ritratto.cartelle)} cartelle`);
+  if (ritratto.git?.ramo) pezzi.push(`ramo ${ritratto.git.ramo}`);
+  if (Number.isFinite(ritratto.git?.nonSalvate)) pezzi.push(ritratto.git.nonSalvate === 0 ? 'niente da salvare' : `${ritratto.git.nonSalvate} modifiche non salvate`);
+  if (ritratto.git?.repoAnnidati?.length) pezzi.push(`${ritratto.git.repoAnnidati.length} repo annidati`);
+  if (ritratto.istruzioni?.length) pezzi.push(`istruzioni: ${ritratto.istruzioni.join(', ')}`);
+  return pezzi.join(' · ');
+}
+
+/** L'avviso, quando serve: una frase che dice cosa succede se parti così. */
+export function avvisoRitratto(ritratto) {
+  if (!ritratto || !ritratto.leggibile) return '';
+  if (ritratto.radice) return 'Questa è una cartella radice: l’agente vedrebbe tutto quello che c’è sotto. Scegli il progetto, non il disco.';
+  if (ritratto.oltreIlTetto) return `Qui ci sono più di ${numeroItaliano(ritratto.tetto)} file: l’albero pesa a ogni giro. Se puoi, scegli una sottocartella.`;
+  return '';
+}

package/vendor/harness-ui/src/workspace-launch-store.mjs

@@ -0,0 +1,150 @@
+import {
+  accessSync,
+  constants,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { basename, dirname, isAbsolute } from 'node:path';
+
+const DEFAULT_TTL_MS = 15 * 60_000;
+const TOKEN_PATTERN = /^[a-f0-9]{64}$/;
+const INTENT_PATTERN = /^[A-Za-z0-9_-]{32}$/;
+const MAX_PATH_BYTES = 4096;
+
+export class WorkspaceLaunchError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = 'WorkspaceLaunchError';
+    this.code = code;
+  }
+}
+
+function nowMs(clock) {
+  const value = clock();
+  return value instanceof Date ? value.getTime() : Number(value);
+}
+
+function ensureCredential({ credentialFile, randomBytesFn }) {
+  let value;
+  try {
+    value = readFileSync(credentialFile, 'utf8').trim();
+  } catch (error) {
+    if (error?.code !== 'ENOENT') {
+      throw new WorkspaceLaunchError('La credenziale del launcher non è leggibile', 'WORKSPACE_LAUNCH_CONFIG_INVALID');
+    }
+    mkdirSync(dirname(credentialFile), { recursive: true });
+    const generated = randomBytesFn(32).toString('hex');
+    try {
+      writeFileSync(credentialFile, `${generated}\n`, { encoding: 'utf8', flag: 'wx', mode: 0o600 });
+      value = generated;
+    } catch (writeError) {
+      if (writeError?.code !== 'EEXIST') {
+        throw new WorkspaceLaunchError('La credenziale del launcher non può essere salvata', 'WORKSPACE_LAUNCH_CONFIG_INVALID');
+      }
+      try {
+        value = readFileSync(credentialFile, 'utf8').trim();
+      } catch {
+        throw new WorkspaceLaunchError('La credenziale del launcher non è leggibile', 'WORKSPACE_LAUNCH_CONFIG_INVALID');
+      }
+    }
+  }
+  if (!TOKEN_PATTERN.test(value)) {
+    throw new WorkspaceLaunchError('La credenziale del launcher è danneggiata', 'WORKSPACE_LAUNCH_CONFIG_INVALID');
+  }
+  return value;
+}
+
+function authenticated(expected, candidate) {
+  if (typeof candidate !== 'string' || !TOKEN_PATTERN.test(candidate)) return false;
+  const expectedBytes = Buffer.from(expected, 'hex');
+  const candidateBytes = Buffer.from(candidate, 'hex');
+  return expectedBytes.length === candidateBytes.length && timingSafeEqual(expectedBytes, candidateBytes);
+}
+
+function resolveWorkspace(percorso) {
+  if (typeof percorso !== 'string' || percorso.trim() === '' || Buffer.byteLength(percorso, 'utf8') > MAX_PATH_BYTES || !isAbsolute(percorso)) {
+    throw new WorkspaceLaunchError('Scegli una cartella valida e riprova', 'WORKSPACE_NOT_AVAILABLE');
+  }
+  let reale;
+  try {
+    reale = realpathSync(percorso);
+    if (!statSync(reale).isDirectory()) throw new Error('not-directory');
+    accessSync(reale, constants.R_OK | constants.W_OK);
+  } catch {
+    throw new WorkspaceLaunchError('La cartella non è disponibile o non consente di lavorarci', 'WORKSPACE_NOT_AVAILABLE');
+  }
+  return reale;
+}
+
+/**
+ * Intenzioni brevi e opache fra il launcher Windows e la nuova sessione.
+ * Il percorso assoluto non attraversa mai URL, localStorage o risposta HTTP.
+ */
+export function createWorkspaceLaunchStore({
+  credentialFile,
+  ttlMs = DEFAULT_TTL_MS,
+  clock = Date.now,
+  randomBytesFn = randomBytes,
+} = {}) {
+  if (typeof credentialFile !== 'string' || credentialFile.trim() === '' || !Number.isSafeInteger(ttlMs) || ttlMs < 1_000) {
+    throw new WorkspaceLaunchError('Configurazione launcher non valida', 'WORKSPACE_LAUNCH_CONFIG_INVALID');
+  }
+  const credential = ensureCredential({ credentialFile, randomBytesFn });
+  const intents = new Map();
+
+  function publicView(intent) {
+    return { id: intent.id, nome: intent.nome, scadeAlle: new Date(intent.expiresAt).toISOString() };
+  }
+
+  function cleanup() {
+    const current = nowMs(clock);
+    for (const [id, intent] of intents) {
+      if (intent.expiresAt <= current) intents.delete(id);
+    }
+  }
+
+  function get(id) {
+    cleanup();
+    if (typeof id !== 'string' || !INTENT_PATTERN.test(id) || !intents.has(id)) {
+      throw new WorkspaceLaunchError('Il collegamento non è più disponibile. Usa di nuovo “Apri cartella con TALOS”.', 'WORKSPACE_LAUNCH_NOT_AVAILABLE');
+    }
+    return intents.get(id);
+  }
+
+  return Object.freeze({
+    create({ percorso, credential: candidate } = {}) {
+      if (!authenticated(credential, candidate)) {
+        throw new WorkspaceLaunchError('Il comando locale non è autorizzato', 'WORKSPACE_LAUNCH_UNAUTHORIZED');
+      }
+      const reale = resolveWorkspace(percorso);
+      cleanup();
+      let id;
+      do { id = randomBytesFn(24).toString('base64url'); } while (intents.has(id));
+      const intent = Object.freeze({
+        id,
+        nome: basename(reale) || reale,
+        percorso: reale,
+        expiresAt: nowMs(clock) + ttlMs,
+      });
+      intents.set(id, intent);
+      return publicView(intent);
+    },
+    inspect(id) {
+      return publicView(get(id));
+    },
+    resolve(id) {
+      const intent = get(id);
+      return { ...publicView(intent), percorso: intent.percorso };
+    },
+    consume(id) {
+      cleanup();
+      if (typeof id !== 'string' || !INTENT_PATTERN.test(id)) return false;
+      return intents.delete(id);
+    },
+  });
+}
+

package/vendor/harness-ui/src/workspace-tree.mjs

@@ -0,0 +1,67 @@
+/**
+ * workspace-tree.mjs — l'albero file REALE di una sessione (piano
+ * `elegant-spinning-dongarra.md`, FASE 1, §1.3, riga "Contesto workspace").
+ *
+ * L'accesso al disco passa dall'adapter locale `workspace-disk.mjs`: nessun
+ * import da repository esterni e una sola policy di elenco, provata sul disco
+ * reale. Il contratto `{nome, cartella}` resta compatibile con il vecchio
+ * `discoNode` così i chiamanti e i test non cambiano.
+ *
+ * ⭐ UN livello alla volta, mai un dump ricorsivo intero: la UI espande le
+ * cartelle a richiesta (`percorso` sale un pezzo per volta). Stessa lezione
+ * di `talos-non-vede-i-file-del-corpus-storia` in memoria — un elenco
+ * piatto esplode in byte prima di essere utile a chi guarda.
+ *
+ * ⛔⛔ `percorso` arriva da una query string HTTP, non da un modello
+ * cooperativo dentro un tool call: `discoNode.elenca()` stesso NON sanifica
+ * `..` o percorsi assoluti (verificato leggendo dist/kernelPerIlBanco.js —
+ * usa `path.join` puro, che non contiene la risalita). Qui il controllo è
+ * ESPLICITO — stesso `isPathInside` già in path-policy.mjs, importato, non
+ * duplicato — perché un endpoint HTTP è raggiungibile da chiunque tocchi il
+ * loopback, non solo da un modello che gioca secondo le regole.
+ */
+import { realpathSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+
+import { isPathInside } from './path-policy.mjs';
+import { createWorkspaceDisk } from './workspace-disk.mjs';
+
+export class WorkspaceTreeError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'WorkspaceTreeError';
+    this.code = 'QUERY_INVALID';
+  }
+}
+
+/**
+ * @param {object} input
+ * @param {string} input.cartella — radice della sessione (già allowlisted a monte da task-catalog.preparaEsecuzione)
+ * @param {string} [input.percorso] — sottocartella relativa da elencare; '' = radice
+ * @param {object} [deps]
+ * @param {Function} [deps.discoNodeFn] — SOLO per compatibilità/test; il default è l'adapter locale
+ * @returns {Promise<Array<{nome:string, cartella:boolean}>>} cartelle prima, poi file, ciascuno alfabetico
+ */
+export async function leggiAlberoWorkspace({ cartella, percorso = '' }, { discoNodeFn } = {}) {
+  if (typeof percorso !== 'string' || percorso.includes('\0') || isAbsolute(percorso)) {
+    throw new WorkspaceTreeError('Percorso non valido');
+  }
+
+  let voci;
+  try {
+    const radiceReale = realpathSync(cartella);
+    const candidatoReale = percorso === '' ? radiceReale : realpathSync(resolve(cartella, percorso));
+    if (!isPathInside(radiceReale, candidatoReale)) {
+      throw new WorkspaceTreeError('Percorso fuori dalla cartella della sessione');
+    }
+    const disco = (discoNodeFn ?? (({ radice }) => createWorkspaceDisk({ rootDir: radice })) )({ radice: cartella });
+    voci = await disco.elenca(percorso);
+  } catch (errore) {
+    if (errore instanceof WorkspaceTreeError) throw errore;
+    throw new WorkspaceTreeError('Percorso non leggibile');
+  }
+
+  return voci
+    .map((v) => ({ nome: v.nome, cartella: Boolean(v.cartella) }))
+    .sort((a, b) => (a.cartella === b.cartella ? a.nome.localeCompare(b.nome, 'en') : a.cartella ? -1 : 1));
+}

package/vendor/harness-ui/src/workspace-watcher.mjs

@@ -0,0 +1,161 @@
+/**
+ * workspace-watcher.mjs — segnala quando i file di un workspace
+ * cambiano FUORI dall'app (Explorer, un editor, git...). Piano
+ * `elegant-spinning-dongarra.md`, owner 27/8: "se muovo i file il
+ * work tree non si aggiorna automaticamente".
+ *
+ * ⛔ Ricerca fatta PRIMA di scrivere (28/8, REGOLA ZERO): `fs.watch`
+ * nativo di Node ha difetti reali anche su Windows (più eventi per
+ * salvataggio e `filename` non sempre presente), quindi debounce e
+ * normalizzazione restano qui. Il profilo reale del 1/9 ha però
+ * invalidato l'uso di Chokidar per QUESTO percorso ricorsivo: oltre
+ * 255 mila handle e un core occupato a riposo dopo l'attivazione su un
+ * workspace grande. Node 24 usa `ReadDirectoryChangesW` per la
+ * ricorsione Windows con una registrazione nativa e supporta `ignore`,
+ * `AbortSignal` e `persistent:false`: il contratto upstream viene
+ * adottato direttamente dietro questo adapter TALOS.
+ *
+ * ⭐ Un watcher per CARTELLA, non per sessione: due sessioni sulla
+ * stessa cartella (un fork, un resume) condividono un solo watcher —
+ * conteggio dei sottoscrittori, chiuso quando l'ultimo si disiscrive.
+ * Mai duplicare un handle di sistema operativo per la stessa cartella.
+ *
+ * ⭐ `.git`/`node_modules` esclusi dal WATCH (non dalla vista
+ * dell'albero, che li mostra già se aperti a mano): sono le due
+ * cartelle a più alto churn di qualunque progetto reale — un `git
+ * status`/`npm install` rifarebbe scattare l'albero decine di volte
+ * per un cambiamento che l'utente non è mai lì a guardare.
+ *
+ * ⭐ Debounce IBRIDO (ricerca 28/8): il timer si resetta ad ogni nuovo
+ * evento (raffiche di scritture diventano UN solo segnale), ma un
+ * tetto massimo forza comunque un invio anche durante una raffica
+ * lunghissima — mai un'attesa indefinita.
+ */
+import { watch as watchReale } from 'node:fs';
+import { dirname, isAbsolute, parse, relative, resolve, sep } from 'node:path';
+
+const DEBOUNCE_MS = 400;
+const TETTO_MASSIMO_MS = 2_000;
+/*
+ * Stato interno del server: viene scritto mentre una sessione è in corso.
+ * Se il workspace scelto è la cartella Harness (o la radice del worktree),
+ * osservarlo produrrebbe un feedback continuo: l'evento aggiorna la sessione,
+ * la sessione scrive il proprio registro e il registro riattiva il watcher.
+ * Queste directory non fanno parte dell'albero del progetto dell'owner e
+ * restano leggibili tramite le loro API dedicate, quindi sono escluse dal
+ * refresh automatico allo stesso modo di `.git` e `node_modules`.
+ */
+const IGNORATI = [
+  /(^|[/\\])\.git([/\\]|$)/,
+  /(^|[/\\])node_modules([/\\]|$)/,
+  /(^|[/\\])\.(?:sessions-store|automations|generated-images|local-models|hooks-trust|mcp-trust|plugin-trust|notes-store|tasks-store|memory-store|tool-forge-store)([/\\]|$)/,
+  /(^|[/\\])\.provider-runtime\.json$/,
+];
+
+function eRadiceVolume(cartella) {
+  const assoluta = resolve(cartella);
+  const radice = parse(assoluta).root;
+  return assoluta === radice || dirname(assoluta) === assoluta;
+}
+
+const guardati = new Map(); // cartella -> { watcher, controller, sottoscrittori: Set<fn>, timerDebounce, primoEventoRaffica, percorsiInSospeso }
+
+function percorsoRelativoEvento(cartella, filename) {
+  if (filename === null || filename === undefined) return '.';
+  const grezzo = Buffer.isBuffer(filename) ? filename.toString('utf8') : String(filename);
+  if (grezzo.length === 0) return '.';
+  const assoluto = isAbsolute(grezzo) ? resolve(grezzo) : resolve(cartella, grezzo);
+  const relativo = relative(resolve(cartella), assoluto);
+  if (relativo === '' || relativo === '..' || relativo.startsWith(`..${sep}`)) return '.';
+  return relativo.split(/[/\\]+/).join('/');
+}
+
+function percorsoIgnorato(percorso) {
+  return percorso !== '.' && IGNORATI.some((rx) => rx.test(percorso));
+}
+
+export function creaGestoreWorkspaceWatcher({ watchFn = watchReale } = {}) {
+  /**
+   * Sottoscrive `onCambiamento(percorsiRelativi)` ai cambiamenti REALI
+   * (mai quelli della scansione iniziale — `ready` li separa) di
+   * `cartella`. Torna una funzione di disiscrizione — MAI un throw:
+   * un watcher che fallisce ad avviarsi (cartella inesistente,
+   * permessi) degrada a "nessun refresh automatico", non rompe la
+   * sessione che lo ha chiesto.
+   */
+  function guardaWorkspace(cartella, onCambiamento) {
+    /*
+     * Full access può indicare una radice come `C:\\`. Anche il watcher nativo
+     * ricorsivo non deve trasformare l’intero volume in una sorgente di eventi
+     * permanente prima che il modello riceva il primo messaggio. La radice resta
+     * leggibile a richiesta tramite workspace-tree, ma non ha refresh automatico:
+     * stato onesto e fail-closed, coerente con il lazy tree.
+     */
+    if (eRadiceVolume(cartella)) return () => {};
+    let voce = guardati.get(cartella);
+    if (!voce) {
+      voce = { watcher: null, controller: null, sottoscrittori: new Set(), timerDebounce: null, primoEventoRaffica: 0, percorsiInSospeso: new Set() };
+      guardati.set(cartella, voce);
+      try {
+        const controller = new AbortController();
+        const watcher = watchFn(cartella, {
+          recursive: true,
+          persistent: false,
+          encoding: 'utf8',
+          ignore: IGNORATI,
+          signal: controller.signal,
+        }, (_evento, filename) => {
+          const relativo = percorsoRelativoEvento(cartella, filename);
+          // Il filtro nativo riduce gli eventi a monte; questo secondo guard
+          // difende adapter finti, backend OS e versioni Node non omogenei.
+          if (percorsoIgnorato(relativo)) return;
+          voce.percorsiInSospeso.add(relativo);
+          const adesso = Date.now();
+          if (!voce.timerDebounce) voce.primoEventoRaffica = adesso;
+          clearTimeout(voce.timerDebounce);
+          const restaSulTetto = TETTO_MASSIMO_MS - (adesso - voce.primoEventoRaffica);
+          const attesa = Math.max(0, Math.min(DEBOUNCE_MS, restaSulTetto));
+          voce.timerDebounce = setTimeout(() => {
+            const percorsi = [...voce.percorsiInSospeso];
+            voce.percorsiInSospeso.clear();
+            voce.timerDebounce = null;
+            /*
+             * ⛔⛔⛔ 28/8, trovato dal vivo: un `for...of` senza try/catch
+             * ABORTISCE l'intero giro al primo sottoscrittore che lancia —
+             * i sottoscrittori DOPO quello (in ordine di iscrizione, quindi
+             * le sessioni create PIÙ DI RECENTE sulla stessa cartella) non
+             * venivano mai notificati. Ogni sottoscrittore è isolato dagli
+             * altri, come broadcast() già fa per i propri ascoltatori.
+             */
+            for (const s of voce.sottoscrittori) {
+              try { s(percorsi); } catch { /* un sottoscrittore rotto non deve mai bloccare gli altri */ }
+            }
+          }, attesa);
+        });
+        watcher.on?.('error', () => { /* ⛔ degrado silenzioso per costruzione — vedi doc sopra: mai un throw che romperebbe la sessione */ });
+        watcher.unref?.();
+        voce.watcher = watcher;
+        voce.controller = controller;
+      } catch { /* stesso principio: nessun refresh automatico, non un guasto */ }
+    }
+    voce.sottoscrittori.add(onCambiamento);
+    return () => {
+      voce.sottoscrittori.delete(onCambiamento);
+      if (voce.sottoscrittori.size === 0) {
+        clearTimeout(voce.timerDebounce);
+        voce.controller?.abort();
+        try { voce.watcher?.close(); } catch { /* la chiusura via signal può averlo già chiuso */ }
+        guardati.delete(cartella);
+      }
+    };
+  }
+
+  /** Solo per i test — mai chiamata da codice di produzione. */
+  function quantiWatcherAttiviPerTest() {
+    return guardati.size;
+  }
+
+  return { guardaWorkspace, quantiWatcherAttiviPerTest };
+}
+
+export const { guardaWorkspace } = creaGestoreWorkspaceWatcher();