@alucard_24/pi-codeindex 1.1.0 → 1.1.1

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 1.1.1
+
+- Porta loopback predefinita `43127`, sempre configurabile; l'override esplicito
+  `0` conserva la scelta deterministica precedente. Nessuna garanzia che una
+  porta fissa sia libera o non esclusa su ogni macchina.
+- Attivazione dell'integrazione pi persistente **per progetto**, spenta in
+  assenza di consenso. `/codeindex enable|disable` salva la scelta fuori dai
+  sorgenti; progetti e sessioni non si abilitano globalmente a vicenda.
+- Il servizio embedding resta condiviso. Disabilitare un progetto annulla
+  watcher/indicizzazione e libera le cache del client, senza arrestare il
+  modello eventualmente usato da altri progetti.
+- Gli errori `listen EACCES` suggeriscono una porta alternativa configurabile,
+  senza fallback in-process. Nessuna correzione dichiarata per il timeout
+  intermittente segnalato su Windows: la causa resta da diagnosticare.
+- Nessun caricamento automatico dell'indice o reindex a progetto spento.
+  I vecchi flag di sessione non vengono migrati in consenso per un progetto.
+- Prima di cambiare porta, arrestare il servizio con la configurazione
+  precedente e riavviare i client. Anche il nuovo default richiede questa
+  precauzione se è ancora presente un servizio della versione precedente.
+
 ## 1.1.0
 
 ### Novità

package/README.md

@@ -7,6 +7,10 @@ Una sola copia del modello fra processi pi/CLI sullo stesso endpoint;
 nessun servizio remoto o database. Indice: due file in
 `~/.cache/pi-codeindex/<sha1(repo)>/`.
 
+**Default dalla versione 1.1.1:** porta locale `43127`; integrazione pi
+spenta nei progetti mai abilitati. `/codeindex enable` salva il consenso
+**per progetto**, mentre il modello resta condiviso fra i progetti attivi.
+
 ## Requisiti
 
 - Node 22+ (testato su 26.5.1).
@@ -20,7 +24,7 @@ nessun servizio remoto o database. Indice: due file in
 ### Da npm, solo su richiesta
 
 ```bash
-pi -e npm:@alucard_24/pi-codeindex@1.0.0
+pi -e npm:@alucard_24/pi-codeindex@1.1.1
 ```
 
 Carica il pacchetto per questa invocazione, senza aggiungerlo alle impostazioni
@@ -162,13 +166,25 @@ Stop viene rifiutato se ci sono richieste attive/in coda; non interrompe altri
 client. Il servizio si riavvierà al prossimo utilizzo del modello. Nessun
 avvio al login, servizio di sistema o modifica alle impostazioni globali di pi.
 
-Il listener è solo `127.0.0.1`, con porta deterministica per la directory
-utente e autenticazione tramite token in `~/.cache/pi-codeindex/service/`
+Il listener è solo `127.0.0.1`, sulla porta predefinita **`43127`**, con
+autenticazione tramite token in `~/.cache/pi-codeindex/service/`
 (directory 0700, record 0600 su POSIX). Il binding esclusivo della porta
-impedisce due avvii simultanei. Una porta occupata da un altro programma dà
-un errore: `servicePort` consente una scelta esplicita. Usa gli stessi
-`serviceDir`/`servicePort` in tutti i client: cambiarli crea endpoint distinti
-e permette deliberatamente più modelli. Non condividere il token o la directory.
+impedisce due avvii simultanei sullo stesso endpoint. Nessuna porta è garantita
+su tutte le macchine: se occupata o esclusa dal sistema, scegli una porta
+libera con `/codeindex config set servicePort NUMERO` e riavvia pi.
+Su Windows `netsh interface ipv4 show excludedportrange protocol=tcp` mostra
+gli intervalli esclusi; non cancellare le prenotazioni del sistema.
+
+Usa gli stessi `serviceDir`/`servicePort` in tutti i client per condividere il
+modello. **Arresta il vecchio servizio inattivo prima di cambiare porta**
+(`/codeindex service stop` con la configurazione precedente), poi chiudi e
+riapri i client. Questo vale anche per il passaggio dalla porta automatica
+della 1.1.0 al nuovo default: un vecchio record può riferirsi alla porta
+precedente. Gli override già salvati non vengono sovrascritti; `servicePort: 0`
+mantiene esplicitamente la scelta deterministica precedente.
+Directory diverse e porte diverse permettono deliberatamente più modelli;
+una stessa directory non va usata contemporaneamente con porte diverse.
+Non condividere il token o la directory.
 
 Restano per-processo le cache degli indici, dei vettori e dei grafi: il servizio
 elimina le copie del **modello**, non tutta la memoria di pi. Dopo l'aggiornamento
@@ -236,7 +252,7 @@ non default silenziosi. Schema per editor: [config.schema.json](config.schema.js
 | `cpuThreads` | 0 = default ORT, oppure 1–256; non limita la GPU | `CODEINDEX_CPU_THREADS` |
 | `serviceIdleMs` | default 300000 (5 min), da 1000 a 86400000 ms | `CODEINDEX_SERVICE_IDLE_MS` |
 | `serviceDir` | directory privata condivisa, default `~/.cache/pi-codeindex/service` | `CODEINDEX_SERVICE_DIR` |
-| `servicePort` | 0 = deterministica, oppure 1024–65535; solo loopback | `CODEINDEX_SERVICE_PORT` |
+| `servicePort` | default **43127**; 1024–65535, oppure 0 per la scelta deterministica precedente; solo loopback | `CODEINDEX_SERVICE_PORT` |
 
 **Riavvia pi con un nuovo processo** dopo una modifica: non si cambia pipeline
 nel mezzo di un run. Se il servizio ha già un profilo/configurazione diversi,
@@ -287,11 +303,43 @@ node src/cli.js embed-test
   mai dal repo.
 - `eval` misura recall@3/@8 e latenza sulle query della fixture.
 
+## Attivazione per progetto
+
+Il caricamento dell'estensione non abilita automaticamente un progetto.
+Prima del consenso non vengono avviati modello, download, indicizzazione,
+watcher o caricamento automatico dell'indice. Configurazione, stato e
+`doctor` restano disponibili; `doctor --probe` richiede esplicitamente il modello.
+
+```text
+/codeindex enable    # abilita solo il progetto corrente, anche per le sessioni future
+/codeindex disable   # disabilita solo quel progetto, senza fermare il modello condiviso
+/codeindex status    # mostra radice, stato e percorso del file di attivazione
+```
+
+La scelta è salvata fuori dai sorgenti, in
+`projects/<sha256(radice canonica)>.json` accanto al file restituito da
+`/codeindex config path` (normalmente `~/.config/pi-codeindex/projects/`,
+oppure `%APPDATA%\\pi-codeindex\\projects\\` su Windows).
+Non viene aggiunto un flag globale di attivazione alla configurazione di pi
+o al profilo embedding. Symlink e differenze di maiuscole su Windows non
+creano consensi separati per lo stesso percorso canonico.
+
+Nei repository Git la scelta vale per l'intera radice Git, anche dalle
+sottocartelle. Senza Git vale per la cartella di avvio. Gli altri client dello
+stesso progetto rileggono la scelta al prompt, alle richieste di stato/reindex
+e prima di indicizzare; i progetti diversi mantengono il proprio stato.
+
+I vecchi flag nel branch della sessione non abilitano implicitamente un
+progetto: dopo l'aggiornamento usa `/codeindex enable` una volta per progetto.
+Stato corrotto o illeggibile significa spento con avviso, non consenso implicito.
+`/codeindex reindex` a progetto spento invita prima ad abilitarlo; i comandi CLI
+espliciti di indice/ricerca non cambiano il consenso dell'integrazione pi.
+
 ## Uso dentro pi
 
 ```bash
 # pacchetto npm: solo questa invocazione, nessuna configurazione globale
-pi -e npm:@alucard_24/pi-codeindex@1.0.0
+pi -e npm:@alucard_24/pi-codeindex@1.1.1
 
 # in sviluppo, dalla directory del progetto
 pi -e ./src/extension.js
@@ -314,9 +362,10 @@ Cosa aggiunge:
   durante l'indicizzazione).
 - **`/codeindex status|reindex [--force]|enable|disable|config|configure|doctor`**. `disable` spegne
   tutto: tool, outline, riga di stato, riga nel system prompt, watcher e
-  indicizzazione in corso. Lo stato è persistito nel branch della sessione;
-  una sessione nuova riparte attiva.
-- **indicizzazione automatica** all'avvio della sessione, in background,
+  indicizzazione in corso. Lo stato è persistito **per progetto**, non nel
+  branch della sessione e non globalmente. Disabilitare libera anche le cache
+  dell'indice e del grafo di quel client, senza fermare il servizio condiviso.
+- **indicizzazione automatica solo nei progetti già abilitati**, in background,
   single-flight, interrompibile, con cap 5.000 file / 200 MB.
 - **sincronizzazione**: watcher ricorsivo con debounce 800 ms, invalidazione
   diretta da `write`/`edit` e controllo dopo `bash`: sweep `git status` nei

package/config.schema.json

@@ -13,7 +13,7 @@
     "cacheDir": { "type": "string", "minLength": 1, "pattern": "\\S", "description": "Cache dei pesi. Supporta ~/; i percorsi relativi sono risolti dal cwd." },
     "cpuThreads": { "type": "integer", "minimum": 0, "maximum": 256, "default": 0, "description": "0 usa il default di ONNX Runtime; non limita la GPU." },
     "serviceDir": { "type": "string", "minLength": 1, "pattern": "\\S", "description": "Directory privata del servizio condiviso. Default ~/.cache/pi-codeindex/service; non cambiarla fra sessioni se vuoi condividere il modello." },
-    "servicePort": { "type": "integer", "anyOf": [{ "const": 0 }, { "minimum": 1024, "maximum": 65535 }], "default": 0, "description": "0 sceglie una porta loopback deterministica dalla directory del servizio. Cambiarla crea un endpoint distinto." },
+    "servicePort": { "type": "integer", "anyOf": [{ "const": 0 }, { "minimum": 1024, "maximum": 65535 }], "default": 43127, "description": "Porta TCP loopback predefinita 43127, da cambiare se occupata o esclusa dal sistema. 0 mantiene la scelta deterministica precedente. Arrestare il vecchio servizio prima di cambiare porta nella stessa directory." },
     "serviceIdleMs": { "type": "integer", "minimum": 1000, "maximum": 86400000, "default": 300000, "description": "Inattività prima di terminare il processo e liberare il modello (default 5 minuti). Status non rinnova il timer." }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alucard_24/pi-codeindex",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Indice semantico locale del codice per pi (EmbeddingGemma 2, ONNX)",
   "license": "MIT",
   "author": "Alucard24",

package/src/config.js

@@ -28,7 +28,7 @@ function expandPath(value, home = os.homedir()) {
 export function defaults(home = os.homedir()) {
   return { device: 'auto', dtype: 'auto', webgpuBackend: 'auto', fallback: 'error', offline: false,
     cacheDir: path.join(home, '.cache', 'pi-codeindex', 'text-model'), cpuThreads: 0,
-    serviceDir: path.join(home, '.cache', 'pi-codeindex', 'service'), servicePort: 0, serviceIdleMs: 300_000 };
+    serviceDir: path.join(home, '.cache', 'pi-codeindex', 'service'), servicePort: 43127, serviceIdleMs: 300_000 };
 }
 
 export function validateConfig(value, source = 'config') {

package/src/extension.js

@@ -13,6 +13,7 @@ import { indexRepo } from './indexer.js';
 import { embeddingStatus, serviceCommand, getServiceStatus, formatServiceStatus } from './embed.js';
 import { formatProfile } from './backend.js';
 import { configCommand } from './config.js';
+import { readProjectState, writeProjectState } from './project-state.js';
 import { configure } from './config-ui.js';
 import { doctor, formatDoctor, parseDoctorArgs } from './doctor.js';
 import { loadIndex } from './store.js';
@@ -27,25 +28,52 @@ const STATUS_KEY = 'codeindex';
 const DEFAULT_K = 8;
 const MAX_K = 30;
 const MAX_CAPS = { maxFiles: 5000, maxBytes: 200 * 1024 * 1024 };
-const CONFIG_ENTRY = 'codeindex-config';
 const DEBOUNCE_MS = 800;
 const MAX_SWEEP_PATHS = 200;
 
 let state = null; // { repo, mode, enabled, indexing, progress, index, error, abort, queue, watcher, rerun }
 const running = new Map(); // repo -> promise (single-flight per repo)
 
-function readEnabled(ctx) {
-  try {
-    for (const entry of ctx.sessionManager.getBranch()) {
-      if (entry.type === 'custom' && entry.customType === CONFIG_ENTRY) {
-        const data = entry.data ?? {};
-        if (typeof data.enabled === 'boolean') return data.enabled;
-      }
+function applyEnabled(ctx, enabled, { start = true } = {}) {
+  const st = state;
+  st.enabled = enabled;
+  if (enabled) {
+    if (st.abort.signal.aborted) st.abort = new AbortController();
+    st.error = null;
+    if (start) {
+      if (!st.watcher) startWatcher(ctx);
+      void runIndex(ctx);
     }
-  } catch {
-    /* nessuno stato salvato: default attivo */
+  } else {
+    stopBackground();
+    st.index = null;
+    st.graph = null;
+    invalidateSearcher(st.repo);
+  }
+  showStatus(ctx);
+}
+
+async function syncProjectState(ctx, options = {}) {
+  const st = state;
+  if (!st) return false;
+  try {
+    const saved = await readProjectState(st.repo);
+    if (state !== st) return false;
+    if (st.error === st.activationError) st.error = null;
+    st.activationError = null;
+    st.activationFile = saved.file;
+    const enabled = saved.enabled && (st.autoIndex || st.manualConsent);
+    if (enabled !== st.enabled) applyEnabled(ctx, enabled, options);
+    return enabled;
+  } catch (e) {
+    if (state !== st) return false;
+    const changed = st.activationError !== e.message;
+    applyEnabled(ctx, false, options);
+    st.activationError = e.message;
+    st.error = e.message;
+    if (changed) ctx.ui.notify(`codeindex: ${e.message}`, 'warning');
+    return false;
   }
-  return true;
 }
 
 function showStatus(ctx) {
@@ -93,18 +121,20 @@ function runIndex(ctx, { force = false } = {}) {
     return inflight;
   }
 
+  const signal = st.abort.signal;
   const p = (async () => {
-    st.indexing = true;
-    st.rerun = false;
-    st.progress = null;
-    st.error = null;
-    showStatus(ctx);
     try {
+      if (!await syncProjectState(ctx, { start: false }) || state !== st || signal.aborted) return null;
+      st.indexing = true;
+      st.rerun = false;
+      st.progress = null;
+      st.error = null;
+      showStatus(ctx);
       const r = await indexRepo({
         root: repo,
         ...MAX_CAPS,
         force,
-        signal: st.abort.signal,
+        signal,
         log: () => {}, // niente rumore su stderr dentro la TUI
         onProgress: (p) => {
           if (state !== st) return; // sessione sostituita: non toccarne lo stato
@@ -112,6 +142,7 @@ function runIndex(ctx, { force = false } = {}) {
           showStatus(ctx);
         },
       });
+      if (state !== st || !st.enabled || signal.aborted) return null;
       st.index = r.index;
       const runtime = embeddingStatus();
       const warnings = [...runtime.warnings, ...runtime.attempts.filter((a) => !a.ok).map((a) => `${a.device}: ${a.error}`)];
@@ -123,7 +154,7 @@ function runIndex(ctx, { force = false } = {}) {
       invalidateSearcher(repo);
       return r;
     } catch (e) {
-      if (st.abort.signal.aborted) return null;
+      if (signal.aborted) return null;
       st.error = e.message ?? String(e);
       if (state === st && st.enabled && !/abort/i.test(st.error)) {
         // Degradazione silenziosa: il tool resta disponibile e risponde con lo stato.
@@ -347,8 +378,10 @@ function statusReport() {
     if (state.mode === 'git') lines.push(`head        : ${i.head ?? '?'}`);
     lines.push(`aggiornato  : ${i.updatedAt}`);
   } else {
-    lines.push('indice      : assente (usa /codeindex reindex)');
+    lines.push(state.enabled ? 'indice      : assente (usa /codeindex reindex)'
+      : 'indice      : non caricato (usa /codeindex enable)');
   }
+  if (state.activationFile) lines.push(`attivazione progetto: ${state.activationFile}`);
   const runtime = embeddingStatus();
   lines.push(`profilo client: ${runtime.profile ? formatProfile(runtime.profile) : 'non ancora associato al servizio'}`);
   if (i?.device) lines.push(`profilo indice: ${formatProfile(i)}`);
@@ -396,7 +429,8 @@ export default function codeindexExtension(pi) {
       if (sub === 'status') {
         // La sessione può chiedere lo stato prima che il refresh in background
         // abbia finito: meglio aspettare che mentire ("indice assente").
-        if (!state.index) await refreshMeta();
+        await syncProjectState(ctx);
+        if (state.enabled && !state.index) await refreshMeta();
         showStatus(ctx);
         let service;
         try { service = formatServiceStatus(await getServiceStatus()); }
@@ -405,6 +439,11 @@ export default function codeindexExtension(pi) {
         return;
       }
       if (sub === 'reindex') {
+        await syncProjectState(ctx);
+        if (!state.enabled) {
+          ctx.ui.notify('codeindex: progetto disattivato; usa prima /codeindex enable', 'warning');
+          return;
+        }
         if (state.indexing) {
           ctx.ui.notify('codeindex: indicizzazione già in corso', 'warning');
           return;
@@ -414,24 +453,20 @@ export default function codeindexExtension(pi) {
         return;
       }
       if (sub === 'enable' || sub === 'disable') {
-        state.enabled = sub === 'enable';
-        if (state.enabled) {
-          // Un abort precedente resta sul vecchio controller: senza rinnovarlo
-          // ogni run futuro uscirebbe subito.
-          state.abort = new AbortController();
-          state.error = null;
-          if (!state.watcher) startWatcher(ctx);
-        } else {
-          stopBackground(); // watcher, coda, run in corso e rerun pendente
-        }
-        showStatus(ctx);
+        const st = state;
+        const enabled = sub === 'enable';
         try {
-          pi.appendEntry(CONFIG_ENTRY, { enabled: state.enabled });
-        } catch {
-          /* stato non persistito: vale per questa sessione */
+          const saved = await writeProjectState(st.repo, enabled);
+          if (state !== st) return;
+          st.activationFile = saved.file;
+          st.activationError = null;
+          st.error = null;
+          st.manualConsent = enabled;
+          applyEnabled(ctx, enabled);
+          ctx.ui.notify(`codeindex: ${enabled ? 'attivo' : 'disattivato'} per questo progetto (${st.repo})`, 'info');
+        } catch (e) {
+          ctx.ui.notify(`codeindex: attivazione progetto non salvata (${e.message})`, 'error');
         }
-        if (state.enabled) void runIndex(ctx);
-        ctx.ui.notify(`codeindex: ${state.enabled ? 'attivo' : 'disattivato'}`, 'info');
         return;
       }
       ctx.ui.notify('uso: /codeindex status|reindex [--force]|enable|disable|config [show|set CHIAVE VALORE|unset CHIAVE]|configure|service [status [--json]|stop]|doctor [--probe] [--all] [--device DEVICE] [--webgpu-backend auto|vulkan]', 'warning');
@@ -440,13 +475,19 @@ export default function codeindexExtension(pi) {
 
   // Risorse di sessione: watcher e timer non vanno creati nel factory.
   pi.on('session_start', async (_event, ctx) => {
+    stopBackground();
+    invalidateSearcher();
     const workspace = resolveWorkspace(ctx.cwd);
     const st = {
       repo: workspace.root,
       mode: workspace.mode,
       // Le cartelle protette richiedono consenso a ogni nuova sessione,
       // anche se un enable era stato salvato nel branch in un altro progetto.
-      enabled: workspace.autoIndex && readEnabled(ctx),
+      enabled: false,
+      autoIndex: workspace.autoIndex,
+      manualConsent: false,
+      activationFile: null,
+      activationError: null,
       indexing: false,
       progress: null,
       index: null,
@@ -461,11 +502,14 @@ export default function codeindexExtension(pi) {
       if (state === st && st.enabled) void runIndex(ctx);
     }, { delayMs: DEBOUNCE_MS });
     state = st;
+    await syncProjectState(ctx, { start: false });
+    if (state !== st) return;
     showStatus(ctx);
     if (!workspace.autoIndex && !st.enabled) {
       ctx.ui.notify('codeindex: indicizzazione automatica disattivata nella home o nella radice del disco; usa una cartella di progetto o /codeindex enable', 'info');
     }
-    // Non bloccare l'avvio: metadati, watcher e indice corrono in background.
+    if (!st.enabled) return;
+    // Solo i progetti abilitati caricano metadati, watcher e indice.
     void (async () => {
       await refreshMeta();
       if (state !== st) return;
@@ -485,6 +529,7 @@ export default function codeindexExtension(pi) {
   // Una riga stabile nel system prompt rende il tool scopribile; i conteggi
   // esatti restano nel footer per non invalidare la prompt cache a ogni run.
   pi.on('before_agent_start', async (event, ctx) => {
+    await syncProjectState(ctx);
     showStatus(ctx);
     if (!state?.enabled) return undefined; // spento: nessuna riga nel prompt
     // Un checkout può cambiare HEAD senza eventi utili del watcher.
@@ -501,6 +546,7 @@ export default function codeindexExtension(pi) {
 
   // Invalidazione diretta: `write`/`edit` sanno esattamente che path hanno toccato.
   pi.on('tool_result', async (event, ctx) => {
+    await syncProjectState(ctx);
     if (!state?.enabled) return undefined;
     try {
       // Anche un comando terminato con errore può aver modificato dei file.

package/src/project-state.js

@@ -0,0 +1,53 @@
+// Consenso persistente per progetto, separato dal profilo embedding globale.
+// Nessun file viene letto o scritto nel repository del progetto.
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { configPath } from './config.js';
+
+export function projectIdentity(root, platform = process.platform) {
+  const resolved = (platform === 'win32' ? path.win32 : path).resolve(root);
+  return platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+
+async function location(root, options = {}) {
+  const project = await fs.realpath(path.resolve(root));
+  const identity = projectIdentity(project);
+  const hash = createHash('sha256').update(identity).digest('hex');
+  const file = path.join(path.dirname(configPath(options.env, options.home)), 'projects', `${hash}.json`);
+  return { project, identity, file };
+}
+
+export async function readProjectState(root, options = {}) {
+  const target = await location(root, options);
+  let text;
+  try { text = await fs.readFile(target.file, 'utf8'); }
+  catch (e) {
+    if (e.code === 'ENOENT') return { ...target, enabled: false };
+    throw e;
+  }
+  let value;
+  try { value = JSON.parse(text); }
+  catch { throw new Error(`attivazione progetto non valida: ${target.file}`); }
+  if (!value || value.version !== 1 || typeof value.enabled !== 'boolean'
+      || typeof value.project !== 'string' || !path.isAbsolute(value.project)
+      || projectIdentity(value.project) !== target.identity) {
+    throw new Error(`attivazione progetto non valida: ${target.file}`);
+  }
+  return { ...target, enabled: value.enabled };
+}
+
+export async function writeProjectState(root, enabled, options = {}) {
+  if (typeof enabled !== 'boolean') throw new Error('attivazione progetto: enabled deve essere booleano');
+  const target = await location(root, options);
+  await fs.mkdir(path.dirname(target.file), { recursive: true, mode: 0o700 });
+  const tmp = `${target.file}.${randomUUID()}.tmp`;
+  try {
+    await fs.writeFile(tmp, JSON.stringify({ version: 1, project: target.project, enabled }, null, 2) + '\n',
+      { flag: 'wx', mode: 0o600 });
+    await fs.rename(tmp, target.file);
+  } finally {
+    await fs.rm(tmp, { force: true });
+  }
+  return { ...target, enabled };
+}

package/src/service-client.js

@@ -43,7 +43,11 @@ export function createEmbeddingClient({ env = process.env, settings = () => load
         child.on('error', (e) => { launchError = e; childRunning = false; });
         child.on('exit', () => { childRunning = false; });
         child.on('message', (message) => {
-          if (message?.ready === false && message.code !== 'EADDRINUSE') launchError = serviceError(message.code ?? 'START_FAILED', message.error);
+          if (message?.ready === false && message.code !== 'EADDRINUSE') {
+            const hint = message.code === 'EACCES' && /^listen\b/.test(message.error ?? '')
+              ? ' Porta locale non utilizzabile: potrebbe essere esclusa dal sistema. Scegli una porta libera con /codeindex config set servicePort NUMERO e riavvia pi. Nessun fallback in-process.' : '';
+            launchError = serviceError(message.code ?? 'START_FAILED', `${message.error}${hint}`);
+          }
         });
         child.unref(); child.channel?.unref();
       };

package/src/workspace.js

@@ -1,9 +1,16 @@
 // Radice del progetto: Git quando disponibile, altrimenti la cartella corrente.
 // Nessuna configurazione di progetto viene letta e nessun repository viene creato.
+import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { repoRoot } from './util.js';
 
+function canonicalPath(value) {
+  let result = path.resolve(value);
+  try { result = fs.realpathSync.native(result); } catch { /* directory non accessibile */ }
+  return process.platform === 'win32' ? result.toLowerCase() : result;
+}
+
 export function resolveWorkspace(cwd = process.cwd(), {
   findRepoRoot = repoRoot,
   home = os.homedir(),
@@ -13,6 +20,7 @@ export function resolveWorkspace(cwd = process.cwd(), {
   const mode = gitRoot ? 'git' : 'folder';
   // Un avvio dalla home o dalla radice del disco non deve scandire l'intera
   // macchina per errore. /codeindex enable resta un consenso esplicito.
-  const broadFolder = root === path.parse(root).root || root === path.resolve(home);
+  const canonicalRoot = canonicalPath(root);
+  const broadFolder = canonicalRoot === path.parse(canonicalRoot).root || canonicalRoot === canonicalPath(home);
   return { root, mode, autoIndex: mode === 'git' || !broadFolder };
 }