pi-jev-guard 0.3.2 → 0.4.0

package/README.md

@@ -121,11 +121,19 @@ Verdetto **incerto** (`review`): il gate tenta prima una riparazione privata
 `policy.onUncertain` e `policy.onUnavailable` (`"hold"` default, oppure `"pass"`).
 Con `"pass"` il testo viene pubblicato con una nota di trasparenza sul verdetto.
 
-Se un'altra estensione ri-registra lo stesso provider (caso reale: `pi-accounts`
-al cambio account), l'overlay viene ricostruito sopra il provider live prima di
-ogni turno; in più il gate toglie il suffisso `__jev` da qualunque payload,
-registrando `jev-gate-bypass` e avvisando in TUI, perché quel turno non è
-passato dalla verifica.
+Se un'altra estensione gestisce lo stesso provider (caso reale: `pi-accounts`
+con overlay auth su `openai-codex`), il gate NON ri-registra nulla: applica
+una patch in-place sull'oggetto provider live (stessa identità, stessa config
+del proprietario). Così i controlli di ownership altrui non vedono mai una
+"configuration changed" e non armano abort dei turni (`This operation was
+aborted` istantaneo). Quando il proprietario sostituisce l'oggetto, il nuovo
+viene patchato ex-novo agli hook (`input`, `before_agent_start`, `turn_start`,
+`model_select`, `message_end`); `/jev off` ripristina i metodi originali senza
+`unregister`. I twin restano visibili nel registry per le letture altrui
+(`jev-overlay-reassert` solo quando un oggetto nuovo viene patchato).
+In più, rete di sicurezza: se un id `__jev` sfugge comunque nel payload, il
+gate toglie il suffisso registrando `jev-gate-bypass` e avvisando in TUI,
+perché quel turno non è passato dalla verifica.
 Le conferme per comandi di rete sospetti attendono invece una decisione esplicita;
 la normale sequenza tool → risposta successiva continua senza un nuovo prompt.
 

package/extensions/index.ts

@@ -1,7 +1,6 @@
 import type { ExtensionAPI, ExtensionContext, ModelRegistry } from "@earendil-works/pi-coding-agent";
 import type { Model, Provider } from "@earendil-works/pi-ai";
 import type { Api } from "@earendil-works/pi-ai";
-import { builtinProviders } from "@earendil-works/pi-ai/providers/all";
 import { registerJevCommand, type UpstreamResult } from "../src/commands.ts";
 import { registerJevAskTool } from "../src/ask.ts";
 import {
@@ -19,15 +18,14 @@ import { createReviewer, createTypedAsk } from "../src/factory.ts";
 import { createMetrics } from "../src/metrics.ts";
 import { registerJevTool } from "../src/tools.ts";
 import {
-  STATIC_DEEPSEEK_FLASH,
-  buildOverlaidProvider,
+  isPatched,
   isTwinId,
-  mergeModelsById,
+  patchProvider,
   twinIdFor,
+  unpatchProvider,
   untwinId,
 } from "../src/automatic/overlay.ts";
 import type { GateVerdictReport } from "../src/automatic/guardian.ts";
-import { readStoreModels } from "../src/store-models.ts";
 import { DEFAULT_GATE_RULES, elideWithMarker } from "../src/reviewer.ts";
 import {
   TOOL_POLICY_REVISION,
@@ -113,16 +111,13 @@ export default function (pi: ExtensionAPI) {
   let lastGroundingErrorAt = 0;
   const metrics = createMetrics();
 
-  // Twin attivi, uno o più per provider. Nessun overlay finché la config non
-  // li attiva (automatic) o l'utente non usa /jev upstream (opt-in).
+  // Twin attivi, uno o più per provider. Patch in-place sull'oggetto live:
+  // nessuna (ri-)registrazione, quindi nessun conflitto di ownership con
+  // altre estensioni (es. pi-accounts) e nessuna entry spuria nel registry.
   interface OverlayState {
-    /** Provider live catturato prima dell'override (auth inclusa). */
-    upstream: Provider;
     twinIds: string[];
-    /** Il nostro overlay registrato, per accorgersi se viene scalzato. */
-    provider: Provider;
-    /** Ripiego dopo un tentativo di ri-registrazione non riuscito. */
-    reassertFailed?: boolean;
+    /** Oggetto live patchato (per unpatch mirato senza registry). */
+    live?: Provider;
   }
   const overlays = new Map<string, OverlayState>();
 
@@ -194,12 +189,16 @@ export default function (pi: ExtensionAPI) {
     return getConfig();
   }
 
-  /** Provider upstream vero: il nostro upstream catturato, o il live dal registry. */
+  /** Provider live corrente dal registry (sempre fresco, mai snapshot). */
   function liveUpstreamProvider(
     registry: ModelRegistry,
     providerId: string,
   ): Provider | undefined {
-    return overlays.get(providerId)?.upstream ?? registry.getProvider(providerId);
+    try {
+      return registry.getProvider(providerId);
+    } catch {
+      return undefined;
+    }
   }
 
   function snapshotUpstream(
@@ -220,61 +219,50 @@ export default function (pi: ExtensionAPI) {
     return { provider, model: model as Model<Api> };
   }
 
-  /** Registra (o aggiorna) l'overlay di un provider con i suoi twin. */
-  function registerOverlay(
-    providerId: string,
-    upstream: Provider,
-    twinIds: string[],
-  ): void {
-    const overlay = buildOverlaidProvider({
-      upstream,
+  /** Applica (o aggiorna) la patch gate sull'oggetto provider live. */
+  function patchLiveProvider(live: Provider, twinIds: string[]): string[] {
+    return patchProvider(live, {
       twinModelIds: twinIds,
       getConfig,
       getReview: getGateReview,
       onVerdict: recordGateVerdict,
       createPostCheck: createGroundingCheck,
     });
-    pi.registerProvider(overlay);
-    overlays.set(providerId, {
-      upstream,
-      twinIds: [...twinIds],
-      provider: overlay,
-    });
   }
 
   /**
-   * Un'altra estensione (es. pi-accounts) può ri-registrare lo stesso provider
-   * id, sostituendo il nostro overlay con un provider che conserva i modelli
-   * (twin compresi) ma non il gate: l'id `__jev` finirebbe all'API.
-   * Qui riapplichiamo l'overlay sopra il provider live, preservandone auth e
-   * config. Se la ri-registrazione non regge, si smette di ritentare.
+   * Assicura la patch su tutti i twin attivi contro il provider live
+   * corrente. Se un'altra estensione (es. pi-accounts) ha sostituito
+   * l'oggetto, il nuovo viene patchato ex-novo; se l'oggetto è lo stesso
+   * ma non patchato, viene patchato. Non chiama mai register/unregister:
+   * la config del proprietario resta intatta e i suoi controlli di
+   * ownership non vedono alcuna "configuration changed".
+   * Ritorna i provider (ri-)patchati in questa chiamata.
    */
-  function reassertOverlays(registry: ModelRegistry): string[] {
-    const fixed: string[] = [];
+  function ensurePatches(registry: ModelRegistry): string[] {
+    // Re-patch sempre (idempotente ed economico): dopo un /reload la factory
+    // è nuova ma gli oggetti restano patchati con le closure vecchie, e la
+    // lista twin potrebbe essere cambiata. Si segnalano solo i provider che
+    // non erano patchati, per non spammare entry diagnostiche a ogni hook.
+    const patched: string[] = [];
     for (const [providerId, state] of [...overlays]) {
-      if (state.reassertFailed) continue;
       let live: Provider | undefined;
       try {
         live = registry.getProvider(providerId);
       } catch {
         continue;
       }
-      if (!live || live === state.provider) continue;
+      if (!live) continue;
+      const was = isPatched(live);
       try {
-        registerOverlay(providerId, live, state.twinIds);
-        const applied = overlays.get(providerId);
-        if (applied && registry.getProvider(providerId) === applied.provider) {
-          fixed.push(providerId);
-        } else if (applied) {
-          // Il registry restituisce un altro oggetto: non insistere.
-          applied.reassertFailed = true;
-        }
+        patchLiveProvider(live, state.twinIds);
+        state.live = live;
+        if (!was) patched.push(providerId);
       } catch {
-        const current = overlays.get(providerId);
-        if (current) current.reassertFailed = true;
+        // Riprova al prossimo hook; mai bloccare il flusso.
       }
     }
-    return fixed;
+    return patched;
   }
 
   /**
@@ -294,11 +282,13 @@ export default function (pi: ExtensionAPI) {
     }
 
     try {
-      // Provider non più gemellati: unregister → builtin ripristinato.
+      // Provider non più gemellati: ripristina i metodi originali (l'oggetto
+      // resta del proprietario: nessuna unregister che spiazzi gli altri).
       for (const providerId of [...overlays.keys()]) {
         if (!byProvider.has(providerId)) {
           try {
-            pi.unregisterProvider(providerId);
+            const live = registry.getProvider(providerId);
+            if (live) unpatchProvider(live);
           } catch {
             // ignora
           }
@@ -307,15 +297,23 @@ export default function (pi: ExtensionAPI) {
       }
 
       for (const [providerId, twinIds] of byProvider) {
-        // Cattura il live PRIMA dell'override (dopo, getProvider dà l'overlay).
-        const existing = overlays.get(providerId)?.upstream;
-        const live = existing ?? registry.getProvider(providerId);
+        // Sempre il live corrente: con la patch non esistono chain di
+        // upstream stale da preservare.
+        const live = liveUpstreamProvider(registry, providerId);
         if (!live) return { ok: false, error: `Provider non trovato: ${providerId}` };
         for (const model of twinIds) {
           const has = live.getModels().some((m) => m.id === model && !isTwinId(m.id));
           if (!has) return { ok: false, error: `Modello non trovato: ${providerId}/${model}` };
         }
-        registerOverlay(providerId, live, twinIds);
+        try {
+          patchLiveProvider(live, twinIds);
+        } catch (error) {
+          return {
+            ok: false,
+            error: error instanceof Error ? error.message : String(error),
+          };
+        }
+        overlays.set(providerId, { twinIds: [...twinIds], live });
       }
 
       config = withTwinRefs(config, refs);
@@ -383,21 +381,20 @@ export default function (pi: ExtensionAPI) {
     };
   }
 
-  /** Rimuove tutti gli overlay (i builtin tornano da soli). */
+  /** Rimuove tutte le patch (i metodi originali tornano da soli). */
   function removeGuarded(): { ok: boolean; error?: string; removed?: number } {
     if (overlays.size === 0) return { ok: false, error: "nessun guarded attivo" };
     const removed = overlays.size;
-    for (const providerId of [...overlays.keys()]) {
+    // Nessuna unregister: gli oggetti restano del proprietario, si
+    // ripristinano solo i metodi sugli oggetti che abbiamo patchato.
+    for (const state of [...overlays.values()]) {
       try {
-        pi.unregisterProvider(providerId);
-      } catch (error) {
-        return {
-          ok: false,
-          error: error instanceof Error ? error.message : String(error),
-        };
+        if (state.live) unpatchProvider(state.live);
+      } catch {
+        // ignora
       }
-      overlays.delete(providerId);
     }
+    overlays.clear();
     return { ok: true, removed };
   }
 
@@ -482,60 +479,29 @@ export default function (pi: ExtensionAPI) {
     getLastGate: () => lastGate,
   });
 
-  // Seed all'avvio: pi ripristina il modello di sessione PRIMA di
-  // session_start, quindi un twin persistito non esisterebbe ancora e
-  // cadrebbe su "Could not restore model ...__jev". Pre-registriamo un
-  // overlay per tutti i twin salvati, anche in on-demand: il mode della
-  // sessione non è disponibile prima di session_start. Un alias non attiva il gate.
-  const bootAuto = process.env.JEV_AUTO_UPSTREAM?.trim();
-  const autoOff = bootAuto === "0" || bootAuto?.toLowerCase() === "off";
-  let seedRefs: TwinRef[] = [];
-  if (bootAuto && !autoOff) {
-    const parsed = parseUpstreamRef([bootAuto]);
-    if (!("error" in parsed)) seedRefs = [parsed];
-  } else if (!bootAuto) {
-    seedRefs = twinRefs(config);
-  }
-  if (seedRefs.length > 0) {
-    // Raggruppa per provider: un overlay per provider con tutti i suoi twin.
-    const byProvider = new Map<string, string[]>();
-    for (const ref of seedRefs) {
-      const list = byProvider.get(ref.provider) ?? [];
-      if (!list.includes(ref.model)) list.push(ref.model);
-      byProvider.set(ref.provider, list);
-    }
-    for (const [providerId, twinIds] of byProvider) {
-      try {
-        // providers/all è mappato dagli alias di pi; il subpath del singolo
-        // provider non lo è e fallirebbe a load (solo installazioni npm).
-        const base = builtinProviders().find((p) => p.id === providerId);
-        if (!base) throw new Error(`provider ${providerId} not in builtins`);
-        // Il catalogo builtin può non avere i modelli salvati: provider
-        // dinamici (es. openai-codex) li tengono nel models-store, altri
-        // (deepseek-flash su versioni vecchie) in una definizione statica.
-        const extra = [
-          ...(providerId === "deepseek" ? [STATIC_DEEPSEEK_FLASH] : []),
-          ...readStoreModels(providerId),
-        ];
-        const seedUpstream: Provider = {
-          ...base,
-          getModels: () => mergeModelsById(base.getModels(), extra),
-        };
-        const known = new Set(seedUpstream.getModels().map((m) => m.id));
-        const usable = twinIds.filter((model) => known.has(model));
-        if (usable.length === 0) continue;
-        registerOverlay(providerId, seedUpstream, usable);
-      } catch {
-        // Provider non gemellabile all'avvio: session_start riproverà dal registry.
-      }
-    }
-  }
+  // NOTA: nessun seed di boot con oggetti fake. La patch lavora SOLO
+  // sull'oggetto live del registry: registrare un oggetto nostro
+  // cancellerebbe la config del proprietario (es. pi-accounts vedrebbe
+  // "configuration changed" e abortirebbe i turni). I twin salvati vengono
+  // patchati a session_start (ogni modalità) e il twin automatic viene
+  // riselezionato lì; un twin persistito non ripristinabile cade sul modello
+  // di default e startSession lo riseleziona.
 
   async function startSession(ctx: ExtensionContext): Promise<void> {
     restoreMode(ctx);
     // Nuova sessione = nuova evidenza: il ledger non attraversa le sessioni.
     evidenceLedger = [];
     evidenceSeq = 0;
+    // Patch dei twin salvati in OGNI modalità (nessun setModel qui): senza,
+    // un twin persistito non esisterebbe nel catalogo. Silenzioso: la
+    // diagnostica resta agli hook di turno.
+    try {
+      if (twinRefs(config).length > 0) {
+        applyTwins(twinRefs(config), ctx.modelRegistry, false);
+      }
+    } catch {
+      // session_start non deve mai fallire per il seed.
+    }
     const auto = process.env.JEV_AUTO_UPSTREAM?.trim();
     if (auto && auto !== "0" && auto.toLowerCase() !== "off") {
       try {
@@ -599,6 +565,63 @@ export default function (pi: ExtensionAPI) {
   });
   pi.on("session_tree", async (_event, ctx) => { await startSession(ctx); });
 
+  /**
+   * Assicura gli overlay PRIMA di qualsiasi before_agent_start (evento input).
+   * Un'altra estensione (pi-accounts) legge il registry nel suo
+   * before_agent_start per decidere i modelli disponibili dell'account e,
+   * se il twin non c'è, arma l'abort del turno ("This operation was
+   * aborted" istantaneo su turn_start). Il seed precoce rende i twin
+   * visibili a quella lettura, indipendentemente dall'ordine di load.
+   * Silenzioso: nessuna entry diagnostica qui (l'input arriva a ogni
+   * prompt); la diagnostica resta nel reassert di before_agent_start.
+   * Vale in ogni modalità: anche in on-demand il twin passthrough ha
+   * bisogno dell'overlay registrato (altrimenti l'id __jev finisce all'API).
+   */
+  function ensureOverlays(registry: ModelRegistry): void {
+    try {
+      const refs = twinRefs(config);
+      if (refs.length === 0) return;
+      // Ricuci le patch su oggetti sostituiti dal proprietario.
+      ensurePatches(registry);
+      // Patch ex-novo i provider gemellati senza stato (seed precoce).
+      const byProvider = new Map<string, string[]>();
+      for (const ref of refs) {
+        if (overlays.get(ref.provider)?.twinIds.includes(ref.model)) continue;
+        const list = byProvider.get(ref.provider) ?? [];
+        if (!list.includes(ref.model)) list.push(ref.model);
+        byProvider.set(ref.provider, list);
+      }
+      for (const [providerId, twinIds] of byProvider) {
+        let live: Provider | undefined;
+        try {
+          live = registry.getProvider(providerId);
+        } catch {
+          continue;
+        }
+        if (!live || isPatched(live)) {
+          if (live) overlays.set(providerId, { twinIds: [...twinIds], live });
+          continue;
+        }
+        const models = live.getModels();
+        if (!twinIds.every((id) => models.some((m) => m.id === id && !isTwinId(m.id)))) {
+          continue;
+        }
+        try {
+          patchLiveProvider(live, twinIds);
+          overlays.set(providerId, { twinIds: [...twinIds], live });
+        } catch {
+          // Riprova al prossimo hook; mai bloccare l'input.
+        }
+      }
+    } catch {
+      // Mai bloccare l'input per il seed.
+    }
+  }
+
+  pi.on("input", async (_event, ctx) => {
+    ensureOverlays(ctx.modelRegistry);
+  });
+
   // Prima di ogni turno: se un'altra estensione ci ha scalzati dal provider,
   // rimettiamo l'overlay (altrimenti l'id __jev arriverebbe all'API).
   function noteReassert(fixed: string[]): void {
@@ -610,9 +633,19 @@ export default function (pi: ExtensionAPI) {
     }
   }
 
+  // Ultima rete prima della generation: dopo eventuali replace altrui nel
+  // before_agent_start, ripatcha in silenzio (mai register/unregister).
+  pi.on("turn_start", async (_event, ctx) => {
+    try {
+      ensurePatches(ctx.modelRegistry);
+    } catch {
+      // Mai bloccare il turno.
+    }
+  });
+
   pi.on("before_agent_start", async (_event, ctx) => {
     try {
-      noteReassert(reassertOverlays(ctx.modelRegistry));
+      noteReassert(ensurePatches(ctx.modelRegistry));
     } catch {
       // mai bloccare il turno
     }
@@ -666,8 +699,8 @@ export default function (pi: ExtensionAPI) {
   // su un modello non guarded (revert immediato al twin).
   pi.on("model_select", async (event, ctx) => {
     try {
-      // Una selezione account/provider può aver rimpiazzato il nostro overlay.
-      noteReassert(reassertOverlays(ctx.modelRegistry));
+      // Una selezione account/provider può aver sostituito l'oggetto: ripatcha.
+      noteReassert(ensurePatches(ctx.modelRegistry));
       if (sessionMode !== "automatic" || !config.automatic.requireGuardedModel) return;
       if (overlays.size === 0) return;
       if (isGuardedModel(event.model.provider, event.model.id)) return;
@@ -1060,9 +1093,9 @@ export default function (pi: ExtensionAPI) {
   pi.on("message_end", async (event, ctx) => {
     try {
       if (ctx.hasUI) ctx.ui.setStatus("jev", undefined);
-      // Dopo la richiesta: se qualcuno ci ha scalzati, rimetti l'overlay
+      // Dopo la richiesta: se qualcuno ha sostituito l'oggetto, ripatcha
       // per il turno successivo (il payload resta già normalizzato).
-      noteReassert(reassertOverlays(ctx.modelRegistry));
+      noteReassert(ensurePatches(ctx.modelRegistry));
       if (sessionMode !== "automatic") return;
       if (event.message.role !== "assistant") return;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-jev-guard",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "type": "module",
   "description": "Jev validation guard for pi: on-demand tool + automatic provider gate. Dual backend: TypeSafe direct + OpenRouter.",
   "keywords": [

package/src/automatic/overlay.ts

@@ -128,54 +128,129 @@ function stripTwins(models: readonly Model<Api>[]): Model<Api>[] {
 }
 
 /**
- * Costruisce l'overlay. Non registra nulla: la registrazione spetta al
- * chiamante (pi.registerProvider), così può fallire senza toccare nulla.
+ * Patch in-place del gate gemellato sullo STESSO oggetto provider.
+ *
+ * Nessuna (ri-)registrazione nel registry: l'identità dell'oggetto e la sua
+ * config restano quelle pubblicate dal proprietario (builtin o altre
+ * estensioni come pi-accounts), quindi i loro controlli di ownership e i
+ * loro snapshot non vedono mai una "configuration changed" e non armano
+ * abort. Rieseguibile: se l'oggetto è già patchato riparte dai metodi
+ * originali con la nuova lista twin. Ritorna gli id gemello pubblicati.
  */
-export function buildOverlaidProvider(deps: OverlayDeps): Provider {
-  const upstream = deps.upstream;
-  // Mappa twin-id -> modello originale (ricostruita a ogni refresh).
-  let twinToOriginal = new Map<string, Model<Api>>();
-  let currentModels: Model<Api>[] = [];
+export interface PatchDeps {
+  /** Id modelli (originali) da gemellare. */
+  twinModelIds: string[];
+  getConfig: () => JevConfig;
+  getReview: () => ReviewFn;
+  /** Riceve l'esito finale di ogni turno sul twin (per `/jev last`). */
+  onVerdict?: (report: GateVerdictReport) => void;
+  /**
+   * Factory del controllo post-safety, una per richiesta: il budget repair
+   * vive nella closure restituita, non nel loop del guardian.
+   */
+  createPostCheck?: () => PostPublishCheckFn | undefined;
+}
+
+/** Metodi originali prima della patch (per ripristino su unpatch). */
+interface PatchedOriginals {
+  getModels: Provider["getModels"];
+  stream: Provider["stream"] | undefined;
+  streamSimple: Provider["streamSimple"];
+  refreshModels?: Provider["refreshModels"];
+  filterModels?: Provider["filterModels"];
+}
+
+interface PatchRecord {
+  /** Originali veri (mai i nostri wrapper): evolve con le adozioni. */
+  orig: PatchedOriginals;
+  /** I nostri wrapper, per distinguerli dalle riassegnazioni altrui. */
+  wrapGetModels: Provider["getModels"];
+}
+
+const patchedOriginals = new WeakMap<object, PatchRecord>();
+
+/** True se l'oggetto provider è attualmente patchato da noi. */
+export function isPatched(provider: Provider): boolean {
+  return patchedOriginals.has(provider);
+}
 
-  function rebuildTwins(rawOriginals: readonly Model<Api>[]): Model<Api>[] {
-    twinToOriginal = new Map();
-    const chosen = new Set(deps.twinModelIds);
-    // Dedup per id: sorgenti miste (builtin + store + statica) possono
-    // ripetere lo stesso modello e produrrebbero twin duplicati.
-    const originals = mergeModelsById(stripTwins(rawOriginals), []);
+export function patchProvider(provider: Provider, deps: PatchDeps): string[] {
+  const previous = patchedOriginals.get(provider);
+  const rawStream: unknown = previous
+    ? previous.orig.stream
+    : (provider as { stream?: unknown }).stream;
+  const base: PatchedOriginals = previous?.orig ?? {
+    // Raw, mai bind: invocati con this=provider al momento della chiamata.
+    getModels: provider.getModels,
+    stream: typeof rawStream === "function"
+      ? (rawStream as NonNullable<Provider["stream"]>)
+      : undefined,
+    streamSimple: provider.streamSimple,
+    ...(provider.refreshModels
+      ? { refreshModels: provider.refreshModels }
+      : {}),
+    ...(provider.filterModels
+      ? { filterModels: provider.filterModels }
+      : {}),
+  };
+  const twinIds = [...deps.twinModelIds];
+  const providerId = provider.id;
+
+  // Risoluzione pigra: legge SEMPRE i modelli correnti (nessuna snapshot
+  // che diventa stale dopo refresh altrui o cataloghi dinamici). Se il
+  // proprietario riassegna getModels dopo la patch, la nuova fn viene
+  // adottata come base (i nostri wrapper si riconoscono e non si adottano).
+  function currentBase(): PatchedOriginals {
+    const rec = patchedOriginals.get(provider);
+    const orig = rec?.orig ?? base;
+    const cur = provider.getModels as Provider["getModels"];
+    if (rec && cur !== rec.wrapGetModels && cur !== orig.getModels) {
+      orig.getModels = cur;
+    }
+    return orig;
+  }
+
+  function currentOriginals(): Model<Api>[] {
+    return mergeModelsById(stripTwins(currentBase().getModels.call(provider)), []);
+  }
+
+  function resolveTwin(modelId: string): Model<Api> | undefined {
+    if (!isTwinId(modelId)) return undefined;
+    const wanted = untwinId(modelId);
+    if (!twinIds.includes(wanted)) return undefined;
+    return currentOriginals().find((m) => m.id === wanted);
+  }
+
+  function twinEntries(): Model<Api>[] {
+    const originals = currentOriginals();
+    const chosen = new Set(twinIds);
     const twins: Model<Api>[] = [];
+    const seen = new Set<string>();
     for (const original of originals) {
-      if (chosen.has(original.id)) {
-        const twin = twinModelFor(original, upstream.id);
-        if (twinToOriginal.has(twin.id)) continue;
-        twinToOriginal.set(twin.id, original);
-        twins.push(twin);
-      }
+      if (!chosen.has(original.id)) continue;
+      const twin = twinModelFor(original, providerId);
+      if (seen.has(twin.id)) continue;
+      seen.add(twin.id);
+      twins.push(twin);
     }
-    currentModels = [...originals.map((m) => ({ ...m })), ...twins];
-    return currentModels;
+    return twins;
   }
 
-  rebuildTwins(upstream.getModels());
-
   function upstreamCall(
     model: Model<Api>,
     context: Context,
     options?: SimpleStreamOptions,
   ): AssistantMessageEventStream {
-    // Public aliases are not model changes. Preserve reasoning signatures,
-    // response phases and tool ids when replaying the transcript upstream.
+    // Gli alias pubblici non sono cambi di modello: normalizza la cronologia
+    // preservando firme reasoning e tool id nel transcript upstream.
     const originalContext: Context = {
       ...context,
       messages: context.messages.map((message) =>
-        message.role === "assistant" && message.provider === upstream.id && isTwinId(message.model)
+        message.role === "assistant" && message.provider === providerId && isTwinId(message.model)
           ? { ...message, model: untwinId(message.model) }
           : message),
     };
-    if (deps.upstreamStreams) {
-      return deps.upstreamStreams.streamSimple(model, originalContext, options);
-    }
-    return upstream.streamSimple(model, originalContext, options);
+    return base.streamSimple.call(provider, model, originalContext, options);
   }
 
   function guardedStreamSimple(
@@ -183,9 +258,9 @@ export function buildOverlaidProvider(deps: OverlayDeps): Provider {
     context: Context,
     options?: SimpleStreamOptions,
   ): AssistantMessageEventStream {
-    const twinOf = twinToOriginal.get(model.id);
-    // A stale/unknown alias must never leak to the upstream API, even if a
-    // dynamic refresh removed its original from the catalogue.
+    const twinOf = resolveTwin(model.id);
+    // Un alias stale/sconosciuto non deve mai arrivare all'API upstream,
+    // anche se un refresh ha rimosso l'originale dal catalogo.
     if (!twinOf) {
       if (!isTwinId(model.id)) return upstreamCall(model, context, options);
       const stream = createAssistantMessageEventStream();
@@ -221,31 +296,29 @@ export function buildOverlaidProvider(deps: OverlayDeps): Provider {
     });
   }
 
-  const overlay: Provider = {
-    id: upstream.id,
-    name: upstream.name,
-    baseUrl: upstream.baseUrl,
-    headers: upstream.headers,
-    // STESSO oggetto auth: stesso slot credenziale, stesso login/OAuth.
-    auth: upstream.auth,
-    getModels: () => currentModels,
-    stream: (model, context, options) =>
+  const wrapGetModels: Provider["getModels"] = () => [
+    ...currentOriginals().map((m) => ({ ...m })),
+    ...twinEntries(),
+  ];
+  provider.getModels = wrapGetModels;
+  if (base.stream) {
+    provider.stream = ((model: any, context: any, options: any) =>
       guardedStreamSimple(
         model as Model<Api>,
         context,
         options as SimpleStreamOptions | undefined,
-      ),
-    streamSimple: (model, context, options) =>
-      guardedStreamSimple(model as Model<Api>, context, options),
-  };
+      )) as Provider["stream"];
+  }
+  provider.streamSimple = ((model: any, context: any, options: any) =>
+    guardedStreamSimple(model as Model<Api>, context, options)) as Provider["streamSimple"];
 
-  // Forward refresh con re-gemellamento. Il persist va depurato dai twin:
-  // lo store è letto anche dal builtin a overlay assente, che li
-  // scambierebbe per modelli normali (senza gate!).
-  if (upstream.refreshModels) {
-    const upstreamRefresh = upstream.refreshModels.bind(upstream);
-    overlay.refreshModels = async (ctx: RefreshModelsContext): Promise<void> => {
-      await upstreamRefresh({
+  // Forward refresh con persist depurato dai twin: lo store è letto anche
+  // dal builtin a overlay assente, che li scambierebbe per modelli normali
+  // (senza gate!). La risoluzione pigra non ha snapshot da ricostruire.
+  if (base.refreshModels) {
+    const upstreamRefresh = base.refreshModels;
+    provider.refreshModels = (async (ctx: RefreshModelsContext): Promise<void> => {
+      await upstreamRefresh.call(provider, {
         ...ctx,
         publish: (publication) =>
           ctx.publish({
@@ -260,41 +333,60 @@ export function buildOverlaidProvider(deps: OverlayDeps): Provider {
                   },
             update: publication.update
               ? () => {
-                  // Applica prima l'update upstream (popola il suo oggetto),
-                  // poi ricostruisci originali + twin da quelli freschi.
                   publication.update?.();
-                  rebuildTwins(upstream.getModels());
                 }
               : undefined,
           }),
       });
-    };
+    }) as Provider["refreshModels"];
   }
 
   // Forward filtro credenziali: si applica agli originali, i twin seguono
   // il destino dell'originale corrispondente.
-  if (upstream.filterModels) {
-    const upstreamFilter = upstream.filterModels.bind(upstream);
-    overlay.filterModels = (
+  if (base.filterModels) {
+    const upstreamFilter = base.filterModels;
+    provider.filterModels = ((
       models: readonly Model<Api>[],
       credential: Credential | undefined,
     ): readonly Model<Api>[] => {
       const originals = models.filter((m) => !isTwinId(m.id));
       const kept = new Set(
-        upstreamFilter(originals as ModelT<Api>[], credential).map((m) => m.id),
+        upstreamFilter.call(provider, originals as ModelT<Api>[], credential).map((m) => m.id),
       );
       return models.filter((m) =>
         isTwinId(m.id) ? kept.has(untwinId(m.id)) : kept.has(m.id),
       );
-    };
+    }) as Provider["filterModels"];
   }
 
-  if (upstream.fetchDeferred) {
-    overlay.fetchDeferred = upstream.fetchDeferred.bind(upstream);
-  }
-  if (upstream.cancelDeferred) {
-    overlay.cancelDeferred = upstream.cancelDeferred.bind(upstream);
+  if (previous) {
+    // Re-patch: i wrapper si ricreano, gli originali veri restano.
+    // Aggiorna il riferimento al wrapper corrente o l'adozione
+    // scambierebbe il nuovo wrapper per una fn altrui.
+    previous.wrapGetModels = wrapGetModels;
+    patchedOriginals.set(provider, previous);
+  } else {
+    patchedOriginals.set(provider, { orig: base, wrapGetModels });
   }
+  return twinEntries().map((t) => t.id);
+}
 
-  return overlay;
+/**
+ * Ripristina i metodi originali. Ritorna false se l'oggetto non era patchato
+ * (es. già sostituito dal proprietario: niente da ripristinare).
+ */
+export function unpatchProvider(provider: Provider): boolean {
+  const rec = patchedOriginals.get(provider);
+  const originals = rec?.orig;
+  if (!originals) return false;
+  provider.getModels = originals.getModels;
+  if (originals.stream) provider.stream = originals.stream;
+  else delete (provider as { stream?: unknown }).stream;
+  provider.streamSimple = originals.streamSimple;
+  if (originals.refreshModels) provider.refreshModels = originals.refreshModels;
+  else delete (provider as { refreshModels?: unknown }).refreshModels;
+  if (originals.filterModels) provider.filterModels = originals.filterModels;
+  else delete (provider as { filterModels?: unknown }).filterModels;
+  patchedOriginals.delete(provider);
+  return true;
 }