ostacky 0.9.3 → 0.9.5

package/README.md

@@ -23,24 +23,26 @@ opencode
 
 Abre la interfaz de terminal interactiva. **Para elegir el agente Ostacky: usá `Tab` para navegar entre agentes** en el panel lateral, o escribí `/agent Ostacky` en el chat.
 
-### Web UI — para usar desde el navegador
+### Web UI — para usar desde el navegador (OpenCode v2)
 
 ```bash
-opencode web --port 4096
+opencode pair
 ```
 
-Abre OpenCode en el navegador en `http://localhost:4096`. **Para elegir el agente Ostacky: abrí el combo/selector de agentes** en la barra superior y seleccioná "Ostacky". Útil para sesiones largas, trabajo en equipo o cuando querés compartir pantalla sin compartir terminal.
+Abre el link de un solo uso (expira en 5 minutos) o escaneá el QR en el navegador para cargar la web UI con cookie de sesión (30 días). **Para elegir el agente Ostacky: abrí el combo/selector de agentes** en la barra superior y seleccioná "Ostacky". Útil para sesiones largas, trabajo en equipo o cuando querés compartir pantalla sin compartir terminal.
 
-Opciones útiles:
+> Por defecto el server corre en `http://127.0.0.1:49374` solo en localhost. Cambialo con `opencode service` (ver tabla). Docs: https://opencode.ai/v2/docs/cli/web
 
-| Comando                                         | Qué hace                                            |
-| ----------------------------------------------- | --------------------------------------------------- |
-| `opencode web`                                  | Puerto aleatorio, abre el navegador automáticamente |
-| `opencode web --port 4096`                      | Puerto fijo                                         |
-| `opencode web --hostname 0.0.0.0`               | Accesible desde la red local                        |
-| `opencode web --mdns`                           | Descubrible como `opencode.local`                   |
-| `OPENCODE_SERVER_PASSWORD=secreta opencode web` | Con autenticación HTTP Basic                        |
-| `opencode attach http://localhost:4096`         | Conectar una terminal TUI a un servidor web activo  |
+Opciones útiles (v2):
+
+| Comando                                            | Qué hace                                                        |
+| -------------------------------------------------- | --------------------------------------------------------------- |
+| `opencode pair`                                    | Muestra URL + QR para conectar web/app (links de un uso, 5 min) |
+| `opencode serve --hostname 0.0.0.0 --port 4096`    | Server dedicado en foreground (host remoto, Docker/systemd)     |
+| `opencode --server http://127.0.0.1:4096`          | Conectar un cliente TUI a un server activo                      |
+| `opencode service set hostname 0.0.0.0`            | Escuchar en red local (luego `opencode service start`)          |
+| `opencode service set port 49374`                  | Puerto fijo en vez del default del channel                      |
+| `opencode service set password "un-secreto-largo"` | Reemplaza password generado (rota todas las sesiones)           |
 
 > 💡 Si no tenés OpenCode instalado aún: `curl -fsSL https://opencode.ai/install | bash`
 
@@ -248,37 +250,37 @@ Tras instalar (`--scope local`), el proyecto queda así:
 
 ```json
 {
-    "version": "0.9.3",
+    "version": "0.9.5",
     "lockedAt": "2025-01-01T00:00:00.000Z",
     "repo": "JaimeHoracio/Ostacky",
-    "tag": "v0.9.3",
+    "tag": "v0.9.5",
     "agents": {
         "ostacky": {
-            "version": "0.9.3",
+            "version": "0.9.5",
             "installedAt": "2025-01-01T00:00:00.000Z",
             "sha256": "abc123..."
         }
     },
     "commands": {
         "install-stack": {
-            "version": "0.9.3",
+            "version": "0.9.5",
             "installedAt": "2025-01-01T00:00:00.000Z",
             "sha256": "def456..."
         },
         "opsx-sync": {
-            "version": "0.9.3",
+            "version": "0.9.5",
             "installedAt": "2025-01-01T00:00:00.000Z",
             "sha256": "ghi789..."
         }
     },
     "skills": {
-        "brainstorming": { "version": "0.9.3", ... },
-        "execution-mode-evaluation": { "version": "0.9.3", ... },
-        "openspec-propose": { "version": "0.9.3", ... }
+        "brainstorming": { "version": "0.9.5", ... },
+        "execution-mode-evaluation": { "version": "0.9.5", ... },
+        "openspec-propose": { "version": "0.9.5", ... }
     },
     "mcpServers": {
-        "ostacky-controller": { "version": "0.9.3", ... },
-        "openspec": { "version": "0.9.3", ... }
+        "ostacky-controller": { "version": "0.9.5", ... },
+        "openspec": { "version": "0.9.5", ... }
     }
 }
 ```
@@ -293,7 +295,7 @@ Al terminar la instalación, el flujo normal es:
 
 1. **Iniciar OpenCode** (si no está corriendo):
     - **TUI:** `opencode` en tu terminal → seleccioná el agente con `/agents` (o atajos **Shift+Tab** / **Ctrl+X A**)
-    - **Web:** `opencode web --port 4096` y abrí `http://localhost:4096` → abrí el selector de agentes de la interfaz y elegí `ostacky`
+    - **Web:** `opencode pair` y abrí el link impreso (ej. `http://127.0.0.1:49374/auth/...`) o escaneá el QR → abrí el selector de agentes de la interfaz y elegí `ostacky`
 2. OpenCode detecta automáticamente los archivos nuevos en `.opencode/` al iniciar, no necesita recarga manual.
 3. Para usar el agente, seleccionalo con `/agents` y escribí tu mensaje en el chat. (En OpenCode v2, `@` es solo para referenciar archivos, no agentes.)
 
@@ -310,7 +312,7 @@ Es opcional y solo necesario si algo falló durante la instalación o si querés
 ## Seguridad
 
 - `opencode.jsonc` se versiona en el repo para compartir permisos y MCP de forma reproducible.
-- Las URLs de descarga usan **tags de GitHub** (ej. `v0.9.3`), nunca `main` — instalaciones reproducibles
+- Las URLs de descarga usan **tags de GitHub** (ej. `v0.9.5`), nunca `main` — instalaciones reproducibles
 - Cada path de archivo descargado es validado para prevenir **path traversal**
 - Los archivos incluyen **checksum SHA-256** opcional; si el manifest lo define, el contenido se verifica antes de escribir
 - El cache local (`.opencode/cache/`) también valida integridad al servir archivos cacheados
@@ -367,7 +369,7 @@ CodeGraph está instalado en `.opencode/tools/codegraph/bin/codegraph` y se conf
 | `.opencode/tools/codegraph/bin/codegraph status`                                           | Muestra estado del index y archivos pendientes              |
 | `.opencode/tools/codegraph/bin/codegraph install --target opencode --location local --yes` | Configura CodeGraph para OpenCode y genera AGENTS.md        |
 
-> **Windows:** si ves `Command failed: cmd.exe /d /c call ... codegraph.cmd init -i` durante `npx ostacky install`, es un _warning_ no fatal — el binario se instaló pero el índice no se pudo crear. Reintentá con `npx ostacky install-stack --scope local` o ejecutá manualmente `.opencode\tools\codegraph\bin\codegraph.exe init -i` (o `codegraph.cmd` si no hay `.exe`) dentro del proyecto. Desde v0.9.3 el instalador usa el patrón resiliente de Engram (strip 0 + búsqueda recursiva) y loguea `projectRoot|toolsDir` para diagnosticar scope.
+> **Windows:** si ves `Command failed: cmd.exe /d /c call ... codegraph.cmd init -i` durante `npx ostacky install`, es un _warning_ no fatal — el binario se instaló pero el índice no se pudo crear. Reintentá con `npx ostacky install-stack --scope local` o ejecutá manualmente `.opencode\tools\codegraph\bin\codegraph.exe init -i` (o `codegraph.cmd` si no hay `.exe`) dentro del proyecto. Desde v0.9.5 el instalador usa el patrón resiliente de Engram (strip 0 + búsqueda recursiva) y loguea `projectRoot|toolsDir` para diagnosticar scope.
 
 ## Licencia
 

package/assets/agents/ostacky.md

@@ -1,12 +1,12 @@
 ---
 description: Orquestador principal — rutea por nivel, orquesta CodeGraph + OpenSpec + Superpowers.
 mode: primary
-version: 0.9.3
+version: 0.9.5
 ---
 
-Sos **Ostacky v0.9.3**, orquestás, no implementás. Interpretás, clasificás (0/0+1/1+), ruteás y coordinás.
+Sos **Ostacky v0.9.5**, orquestás, no implementás. Interpretás, clasificás (0/0+1/1+), ruteás y coordinás.
 
-> **Versión:** `0.9.3` (sincronizada desde `package.json` vía `scripts/sync-version.ts`). Cuando te pregunten qué versión tenés, qué versión sos, o `¿qué versión tenés?` / `version` / `¿en qué versión estás?`, respondé exactamente: **"Ostacky v0.9.3"** (o `v0.9.3` si te piden solo el número). No inventes otra versión.
+> **Versión:** `0.9.5` (sincronizada desde `package.json` vía `scripts/sync-version.ts`). Cuando te pregunten qué versión tenés, qué versión sos, o `¿qué versión tenés?` / `version` / `¿en qué versión estás?`, respondé exactamente: **"Ostacky v0.9.5"** (o `v0.9.5` si te piden solo el número). No inventes otra versión.
 
 ## Reglas innegociables
 
@@ -23,6 +23,7 @@ Sos **Ostacky v0.9.3**, orquestás, no implementás. Interpretás, clasificás (
 > **Regla de oro:** Nunca escribas instrucciones genéricas tipo `“sé cuidadoso / no introduzcas errores / no inventes”`. Son no-verificables y el LLM las ignora (instruction fatigue). Cada SHALL abajo es **verificable** (comando, evidencia o artefacto). `tasks.md` también SHALL ser verificable — no behavioral.
 
 1. **Engram contradiction check SHALL.** Antes de proponer o discutir cambios (Nivel 0+1/1+, **eximido si `isTrivial && DONE`** — ej: "cambiar título" no paga `mem_search`), SHALL `mem_search` por keywords del pedido (max 5 keywords = sustantivos del pedido + `topic_key` del change activo si lo hay); si hit `type:decision|architecture` con contradicción semántica (ej: pide Zustand y hay #571 “usar Redux por X”), SHALL mostrar diff `“Antes decidimos X el <fecha> por Z (topic_key), ahora pedís ¬X”`, llamar `request_clarification` y esperar. Si Engram `degraded`/timeout → SHALL advertir “sin memoria” y continuar (no block). Si usuario confirma override → SHALL `mem_save` mismo `topic_key` + `mem_compare supersedes` + `record_user_confirmation`.
+   1b. **Code-contradiction check SHALL.** Antes de ejecutar (Nivel 0+1/1+, **eximido si `isTrivial && DONE`**), si `codegraph_impact`/evidencia del código contradice el pedido (API pública con N callers afectada, invariante verificado roto): SHALL mostrar evidencia con cita (`símbolo, archivo:línea`), advertir el riesgo concreto, hacer UNA pregunta y esperar. Si el usuario insiste → SHALL `record_user_confirmation` + ejecutar. Nunca termina en bloqueo: el protocolo siempre cierra en acatamiento si insiste.
 2. **Solo propuestas que ayudan SHALL.** Toda propuesta SHALL incluir `por qué ayuda + tradeoff + evidencia` (CodeGraph symbol, Engram hit) o literal `“no verificado”` + best practice 2026. No sugerir por sugerir.
 3. **Pocas honestas > muchas de relleno SHALL.** Si solo hay una opción honesta, dar una. Si hay 2-3, tabla `coste|riesgo|complejidad`. No inventar para llenar.
 4. **Si no hay propuesta honesta SHALL decirlo.** Literal: `“No hay propuesta honesta que aporte vs no hacer nada en este contexto.”`
@@ -84,7 +85,7 @@ Router `brainstorming`↔`OpenSpec` por `level`/`estLines`/`fileCount`/`hasAPI`
 ### 4. Execution
 
 1. `skill(execution-mode-evaluation)` en memoria, reusa discovery.
-2. Mostrar análisis → `¿Procedo?` → `record_execution_analysis` → `consume_execution_decision`.
+2. Gate ÚNICO (sin segunda pregunta): presentar resumen único `Nivel + DIRECT/SPEC + INLINE/SUBAGENT + archivos + ~líneas` (+ comparativa tokens|tiempo si `1+` multi-archivo) → UNA sola pregunta `¿Procedo?` (el usuario puede modificar). Si hay Riesgo concreto verificable aunque sea 0+1, el resumen incluye `Riesgo concreto: … → Mitigación: …`; sin riesgo verificable no se inventa ninguno. Todo override a advertencia del agente (de memoria o técnica) SHALL pasar por `record_user_confirmation`. Si confirma → `record_execution_analysis` + `consume_execution_decision` seguidos sin volver a preguntar. `Nivel 0` y mismo-archivo → recomendación fija `INLINE/DIRECT` sin alternativa. `1+` multi-archivo → tabla `INLINE (1x contexto, más lento) vs SUBAGENT (Nx contexto, más rápido, reglas 2b/3c intactas)` + recomendación; nunca forzar `INLINE`.
 3. Por task: `Read` fresco → plugin valida edición in-process → `edit` → `verifyTask` (genérico: `codegraph:<Symbol>` con `codegraph_codegraph_explore`, `file:<path> contiene <string>` con `Read`/`Grep`, `test:<cmd>` con `shell` acotado — según `— verificar:` de `tasks.md`) → solo si `verifyTask.ok` → `complete_task`. **NUNCA marques `complete_task` a ojo**; si `verifyTask` falla, reintentá el fix. Vale para SPEC y DIRECT, INLINE y SUBAGENTS.
 
 ### 5. Sync y cierre

package/assets/commands/install-stack.md

@@ -5,13 +5,13 @@ agent: build
 
 Instala el stack tecnológico de desarrollo para OpenCode. **IMPORTANTE:** las herramientas se instalan por separado (cada una con su propio CLI/comando). `npx ostacky install` solo instala el agente y commands de Ostacky en `.opencode/`. Este comando (`/install-stack`) es la guía de referencia para la instalación manual completa paso a paso.
 
-**Nota:** A partir de v0.9.3, `npx ostacky install` ya instala automáticamente el stack completo (CodeGraph, OpenSpec, Engram, MCPs bundleados) además del agente y skills. Este comando es útil para instalación manual, verificación, o cuando algo falló y necesita reinstalarse.
+**Nota:** A partir de v0.9.5, `npx ostacky install` ya instala automáticamente el stack completo (CodeGraph, OpenSpec, Engram, MCPs bundleados) además del agente y skills. Este comando es útil para instalación manual, verificación, o cuando algo falló y necesita reinstalarse.
 
 **RESTRICCIÓN ABSOLUTA:** instalar ÚNICAMENTE para OpenCode. Está terminantemente prohibido crear o modificar archivos en `.claude/`, `.kiro/`, `.cursor/`, `.gemini/`, `.codex/`, `.antigravity/`, `.windsurf/` o cualquier otro directorio de plataformas externas.
 
 **Origen del set curado:** el set de 15 skills referenciado en `assets/agents/ostacky.md` está bundleado en `assets/skills/` dentro del paquete npm. La definición del set y su trazabilidad viven en `manifest.json` y `.opencode/ostacky-lock.json`.
 
-## Scope de instalación — local vs global (desde v0.9.3)
+## Scope de instalación — local vs global (desde v0.9.5)
 
 `npx ostacky install` soporta `--scope local|global|auto` (también `--scope=...`):
 

package/assets/mcp/ostacky-controller/bun.lock

@@ -0,0 +1,20 @@
+{
+  "lockfileVersion": 2,
+  "configVersion": 0,
+  "workspaces": {
+    "": {
+      "name": "ostacky-controller",
+      "dependencies": {
+        "@modelcontextprotocol/server": "^2.0.0",
+        "zod": "^4.0.0",
+      },
+    },
+  },
+  "packages": {
+    "@modelcontextprotocol/core": ["@modelcontextprotocol/core@2.1.0", "", { "dependencies": { "zod": "^4.2.0" } }, "sha512-YdFj5gMRHr0gYNAhTbQDgjLHiEJdIAUYxomhKseUNye7ZGlISQmUoLh2sveFFCiQ7j2YMffT1kgSND0FSfIFjQ=="],
+
+    "@modelcontextprotocol/server": ["@modelcontextprotocol/server@2.1.0", "", { "dependencies": { "@modelcontextprotocol/core": "2.1.0", "zod": "^4.2.0" } }, "sha512-FdvwZU5N03O77Suh35JqjAqq5R1ZTEPFtwu6N4BgBq28qrQtrCnpbLL5U2pwYCuE194jAw0xnlOVmIqhfoYuUQ=="],
+
+    "zod": ["zod@4.4.3", "", {}, "sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ=="],
+  }
+}

package/assets/mcp/ostacky-controller/index.js

@@ -42,6 +42,13 @@ import {
     getMaxTasks,
 } from './controller-core.js';
 
+// --- approved-but-blocked recovery (sin timers) ---
+// El PENDING que espera confirmación del usuario puede esperar indefinidamente (por diseño):
+// acá NO hay timeouts ni watchdogs de idle (ver tests/controller-source.test.ts).
+// Esto solo cuenta consumes fallidos cuando el usuario YA aprobó pero el consume no completa,
+// y al umbral habilita recovery (refresh_decision) sin ejecutar nada por sí mismo.
+const CONSUME_FAIL_THRESHOLD = 3;
+
 // --- Audit JSONL (D5) — single source: src/audit-jsonl.ts ---
 function getAuditPath(projectRoot) {
     return join(projectRoot, '.opencode', 'ostacky-audit.jsonl');
@@ -1042,6 +1049,27 @@ class OstackyController {
         return suggestions[state] || `Unexpected state: ${state}`;
     }
 
+    // --- approved-but-blocked: contador de consumes fallidos + hint de recovery ---
+    async #noteConsumeFailure(via, reason) {
+        const count = (this.#state.consumeFailedCount || 0) + 1;
+        this.#state.consumeFailedCount = count;
+        await this.#audit(
+            'WARN',
+            'consume_failed',
+            `${via}: ${reason} (attempt ${count}/${CONSUME_FAIL_THRESHOLD})${count >= CONSUME_FAIL_THRESHOLD ? ' — recovery available: call refresh_decision for fresh IDs, then retry' : ''}`
+        );
+        // Durability: el fallo y su evidencia nunca deben perderse en un restart
+        await this.#flushAudit(true);
+        return count;
+    }
+
+    #consumeRecoveryHint(count) {
+        if (count >= CONSUME_FAIL_THRESHOLD) {
+            return 'Recovery: call refresh_decision for fresh decision IDs, then retry the consume. The user approval still stands — only the IDs are repaired.';
+        }
+        return undefined;
+    }
+
     // --- 3.3: Degraded mode ---
     #enterDegradedMode(reason) {
         this.#degraded = true;
@@ -1100,6 +1128,7 @@ class OstackyController {
             fileFingerprints: {},
             expectedTasks: null,
             expectedTaskCount: null,
+            consumeFailedCount: 0,
             error: null,
         });
         await this.#audit(
@@ -1138,6 +1167,7 @@ class OstackyController {
             );
         await this.#transition(to, { error: null });
         await this.#audit('DISCOVERY', 'record_clarification');
+        await this.#flushAudit(true);
         return { state: this.#state.state, revision: this.#state.revision };
     }
 
@@ -1221,6 +1251,7 @@ class OstackyController {
             lastProposal,
         });
         await this.#audit('ROUTE_DECISION_PENDING', 'record_discovery', `level=${level}, default=${defaultChoice}`);
+        await this.#flushAudit(true);
         // 8.2: reasoning sin plan → WARN
         if (!shownToUser && !isTrivial) {
             const auditId = `aud-${Date.now()}-${this.#state.auditSeq}`;
@@ -1352,13 +1383,25 @@ class OstackyController {
                 'consume_route_decision'
             );
         }
-        if (this.#state.routeDecisionId !== decisionId)
-            return this.#makeError('Decision ID mismatch', 'consume_route_decision');
+        if (this.#state.routeDecisionId !== decisionId) {
+            const fails = await this.#noteConsumeFailure('consume_route_decision', 'Decision ID mismatch');
+            const err = this.#makeError('Decision ID mismatch', 'consume_route_decision');
+            const hint = this.#consumeRecoveryHint(fails);
+            return hint ? { ...err, recovery: hint } : err;
+        }
         const to = this.#isAllowedTransition(this.#state.state, 'consume_route_decision', choice);
-        if (!to)
-            return this.#makeError(`Route ${choice} not allowed from ${this.#state.state}`, 'consume_route_decision');
-        await this.#transition(to, { routeChoice: choice });
+        if (!to) {
+            const fails = await this.#noteConsumeFailure('consume_route_decision', `choice ${choice} not allowed`);
+            const err = this.#makeError(
+                `Route ${choice} not allowed from ${this.#state.state}`,
+                'consume_route_decision'
+            );
+            const hint = this.#consumeRecoveryHint(fails);
+            return hint ? { ...err, recovery: hint } : err;
+        }
+        await this.#transition(to, { routeChoice: choice, consumeFailedCount: 0 });
         await this.#audit(to, 'consume_route_decision', `choice=${choice}`);
+        await this.#flushAudit(true);
         return { state: this.#state.state, revision: this.#state.revision, routeChoice: choice };
     }
 
@@ -1562,6 +1605,7 @@ class OstackyController {
             lastProposal: execLastProposal,
         });
         await this.#audit('EXECUTION_DECISION_PENDING', 'record_execution_analysis');
+        await this.#flushAudit(true);
         // fix-execution-analysis-validation: degraded/early-exit defaulted snapshot → WARN
         if (_snapshotDefaulted) {
             const auditId = `aud-${Date.now()}-${this.#state.auditSeq}`;
@@ -1678,16 +1722,54 @@ class OstackyController {
                 'consume_execution_decision'
             );
         }
-        if (this.#state.executionDecisionId !== decisionId)
-            return this.#makeError('Decision ID mismatch', 'consume_execution_decision');
+        if (this.#state.executionDecisionId !== decisionId) {
+            const fails = await this.#noteConsumeFailure('consume_execution_decision', 'Decision ID mismatch');
+            const err = this.#makeError('Decision ID mismatch', 'consume_execution_decision');
+            const hint = this.#consumeRecoveryHint(fails);
+            return hint ? { ...err, recovery: hint } : err;
+        }
         const to = this.#isAllowedTransition(this.#state.state, 'consume_execution_decision', mode);
-        if (!to)
-            return this.#makeError(`Mode ${mode} not allowed from ${this.#state.state}`, 'consume_execution_decision');
-        await this.#transition(to, { executionMode: mode });
+        if (!to) {
+            const fails = await this.#noteConsumeFailure('consume_execution_decision', `mode ${mode} not allowed`);
+            const err = this.#makeError(
+                `Mode ${mode} not allowed from ${this.#state.state}`,
+                'consume_execution_decision'
+            );
+            const hint = this.#consumeRecoveryHint(fails);
+            return hint ? { ...err, recovery: hint } : err;
+        }
+        await this.#transition(to, { executionMode: mode, consumeFailedCount: 0 });
         await this.#audit(to, 'consume_execution_decision', `mode=${mode}`);
+        await this.#flushAudit(true);
         return { state: this.#state.state, revision: this.#state.revision, executionMode: mode };
     }
 
+    /**
+     * Regenera decision IDs frescos dentro del PENDING actual.
+     * Recovery para "usuario aprobó pero el consume no completa" (IDs viejos tras
+     * restart/compactación). No ejecuta nada: solo repara el tubo, la aprobación sigue valiendo.
+     */
+    async refreshDecision() {
+        this.#load();
+        const s = this.#state.state;
+        const prevFails = this.#state.consumeFailedCount || 0;
+        if (s === 'ROUTE_DECISION_PENDING') {
+            const routeDecisionId = 'route-' + Date.now();
+            await this.#transition(s, { routeDecisionId, consumeFailedCount: 0 });
+            await this.#audit(s, 'refresh_decision', `fresh routeDecisionId after ${prevFails} failed consume(s)`);
+            await this.#flushAudit(true);
+            return { state: this.#state.state, revision: this.#state.revision, routeDecisionId };
+        }
+        if (s === 'EXECUTION_DECISION_PENDING') {
+            const executionDecisionId = 'exec-' + Date.now();
+            await this.#transition(s, { executionDecisionId, consumeFailedCount: 0 });
+            await this.#audit(s, 'refresh_decision', `fresh executionDecisionId after ${prevFails} failed consume(s)`);
+            await this.#flushAudit(true);
+            return { state: this.#state.state, revision: this.#state.revision, executionDecisionId };
+        }
+        return this.#makeError(`No decision to refresh from state ${s}`, 'refresh_decision');
+    }
+
     async implementationComplete({ force } = {}) {
         this.#load();
         const to = this.#isAllowedTransition(this.#state.state, 'implementation_complete');
@@ -2300,6 +2382,47 @@ class OstackyController {
         };
     }
 
+    // --- fix-new-file-gate: ligadura validate → complete por filePath (mapa + fallback legacy) ---
+    _getValidatedFor(filePath) {
+        const lv = this.#state.lastValidated;
+        if (!lv || !filePath) return null;
+        if (lv.byFile && typeof lv.byFile === 'object' && lv.byFile[filePath]) return lv.byFile[filePath];
+        if (lv.filePath === filePath) return lv; // fallback slot legacy (single)
+        return null;
+    }
+    async _setValidatedFor(filePath, hash, mode) {
+        const prev = this.#state.lastValidated;
+        let byFile = {};
+        if (prev) {
+            if (prev.byFile && typeof prev.byFile === 'object') byFile = { ...prev.byFile };
+            else if (prev.filePath)
+                byFile[prev.filePath] = { hash: prev.hash ?? null, ts: prev.ts ?? 0, mode: prev.mode ?? 'replace' };
+        }
+        if (filePath) byFile[filePath] = { hash: hash ?? null, ts: Date.now(), mode: mode || 'replace' };
+        const keys = Object.keys(byFile);
+        if (keys.length > 50) {
+            keys.sort((a, b) => (byFile[a].ts || 0) - (byFile[b].ts || 0));
+            for (const k of keys.slice(0, keys.length - 50)) delete byFile[k];
+        }
+        this.#state.lastValidated = {
+            byFile,
+            filePath: filePath || null,
+            hash: hash ?? null,
+            ts: Date.now(),
+            mode: mode || 'replace',
+        };
+    }
+    async _clearValidatedFor(filePath) {
+        const lv = this.#state.lastValidated;
+        if (lv && lv.byFile && typeof lv.byFile === 'object') {
+            if (filePath && lv.byFile[filePath]) delete lv.byFile[filePath];
+            if (Object.keys(lv.byFile).length === 0) this.#state.lastValidated = null;
+            else this.#state.lastValidated = { byFile: lv.byFile, filePath: null, hash: null, ts: Date.now() };
+        } else {
+            this.#state.lastValidated = null;
+        }
+    }
+
     // --- O6: Validate edit with fast fingerprint + D6/D4 hard gate + 10.4 freshness ---
     async validateEdit({ oldString, newString, content, taskId, filePath } = {}) {
         this.#load();
@@ -2323,8 +2446,10 @@ class OstackyController {
                 await this.#persist();
             } catch {}
         }
-        // 10.4: validación de frescura — content debe coincidir con disco si filePath dado
-        if (filePath && typeof content === 'string') {
+        // 10.4: validación de frescura — content debe coincidir con disco si filePath dado.
+        // fix-new-file-gate: con oldString "" (intento create) no hay nada que comparar; la rama
+        // create más abajo produce el error preciso (file exists vs EDITABLE).
+        if (filePath && typeof content === 'string' && oldString !== '') {
             try {
                 const projectRoot = getProjectRoot(this.#statePath);
                 const absolutePath =
@@ -2353,12 +2478,8 @@ class OstackyController {
                         ? resolve(filePath)
                         : resolve(projectRoot, filePath);
                 const currentHash = fastFingerprint(absolutePath);
-                if (
-                    currentHash &&
-                    hashArg === currentHash &&
-                    this.#state.lastValidated?.filePath === filePath &&
-                    this.#state.lastValidated?.hash === currentHash
-                ) {
+                const _prevValidated = this._getValidatedFor(filePath);
+                if (currentHash && hashArg === currentHash && _prevValidated && _prevValidated.hash === currentHash) {
                     try {
                         content = readFileSync(absolutePath, 'utf8');
                     } catch {
@@ -2374,11 +2495,8 @@ class OstackyController {
             }
         }
         // 5.3: optimization — si fastFingerprint no cambió, no re-enviar content completo
-        if (
-            (typeof content !== 'string' || content.length === 0) &&
-            filePath &&
-            this.#state.lastValidated?.filePath === filePath
-        ) {
+        const _optValidated = filePath ? this._getValidatedFor(filePath) : null;
+        if ((typeof content !== 'string' || content.length === 0) && filePath && _optValidated) {
             try {
                 const projectRoot = getProjectRoot(this.#statePath);
                 const absolutePath =
@@ -2386,7 +2504,7 @@ class OstackyController {
                         ? resolve(filePath)
                         : resolve(projectRoot, filePath);
                 const currentHash = fastFingerprint(absolutePath);
-                if (currentHash && currentHash === this.#state.lastValidated.hash) {
+                if (currentHash && currentHash === _optValidated.hash) {
                     try {
                         const diskContent = readFileSync(absolutePath, 'utf8');
                         content = diskContent;
@@ -2394,6 +2512,29 @@ class OstackyController {
                 }
             } catch {}
         }
+        // fix-new-file-gate: modo create — oldString "" + archivo inexistente en disco
+        if (typeof oldString === 'string' && oldString === '' && typeof newString === 'string' && filePath) {
+            if (newString.length === 0) {
+                return { outcome: 'CONFLICT', reason: 'newString required for create' };
+            }
+            try {
+                const projectRoot = getProjectRoot(this.#statePath);
+                const absolutePath =
+                    filePath.startsWith('/') || /^[A-Za-z]:/.test(filePath)
+                        ? resolve(filePath)
+                        : resolve(projectRoot, filePath);
+                if (existsSync(absolutePath)) {
+                    return { outcome: 'CONFLICT', reason: 'file exists, use replace mode', filePath };
+                }
+            } catch {
+                return { outcome: 'CONFLICT', reason: 'create validation failed', filePath };
+            }
+            await this._setValidatedFor(filePath, null, 'create');
+            try {
+                await this.#persist();
+            } catch {}
+            return { outcome: 'EDITABLE', taskId, mode: 'create' };
+        }
         if (typeof content !== 'string' || typeof oldString !== 'string' || typeof newString !== 'string') {
             return { outcome: 'CONFLICT', reason: 'Missing required fields: content, oldString, newString' };
         }
@@ -2438,7 +2579,7 @@ class OstackyController {
                     : resolve(projectRoot, filePath)
                 : null;
             const hash = absolutePath ? fastFingerprint(absolutePath) : null;
-            this.#state.lastValidated = { filePath: filePath || null, hash, ts: Date.now() };
+            await this._setValidatedFor(filePath || null, hash, 'replace');
             await this.#persist();
         } catch {}
         return { outcome: 'EDITABLE', taskId };
@@ -2483,7 +2624,9 @@ class OstackyController {
                 !this.#state.fileFingerprints?.[filePath] &&
                 !Object.values(this.#state.tasks || {}).some((t) => t.filePath === filePath))
         );
-        if (!this.#state.lastValidated || (filePath && this.#state.lastValidated.filePath !== filePath)) {
+        // fix-new-file-gate: ligadura por-archivo (create o replace); se consume solo ese path
+        const _ligadura = filePath ? this._getValidatedFor(filePath) : this.#state.lastValidated;
+        if (!_ligadura) {
             if (!isNewFile) {
                 return {
                     error: 'validate required',
@@ -2498,7 +2641,7 @@ class OstackyController {
                 `complete_task without prior validate_edit for ${filePath || taskId}${isNewFile ? ' (new file, WARN not BLOCK)' : ''}`
             );
         } else {
-            this.#state.lastValidated = null;
+            await this._clearValidatedFor(filePath);
         }
 
         // --- Generico: verificar task antes de marcar completa (evita invento)
@@ -2853,7 +2996,7 @@ function safeHandler(fn, options = {}) {
 
 const server = new McpServer({
     name: 'ostacky-controller',
-    version: '0.9.3',
+    version: '0.9.5',
 });
 
 server.registerTool(
@@ -2971,6 +3114,19 @@ server.registerTool(
     })
 );
 
+server.registerTool(
+    'refresh_decision',
+    {
+        description:
+            'Regenerate fresh decision IDs within the current PENDING state (recovery when the user approved but consume keeps failing with stale IDs; executes nothing)',
+        inputSchema: z.object({}),
+    },
+    safeHandler(async () => {
+        log('tool:refresh_decision');
+        return await controller.refreshDecision();
+    })
+);
+
 server.registerTool(
     'implementation_complete',
     {
@@ -3442,7 +3598,7 @@ function setupGracefulShutdown(ctrl) {
 }
 
 async function main() {
-    log('Starting ostacky-controller MCP v0.9.3...');
+    log('Starting ostacky-controller MCP v0.9.5...');
     log('State path:', { path: statePath });
     // Clean up stale tmp/lock files from previous runs
     cleanupTmpFiles(statePath);