ostacky 0.5.9 → 0.5.10

package/README.md

@@ -218,33 +218,33 @@ Tras instalar, el proyecto queda así:
 
 ```json
 {
-    "version": "0.5.9",
+    "version": "0.5.10",
     "lockedAt": "2025-01-01T00:00:00.000Z",
     "repo": "JaimeHoracio/Ostacky",
-    "tag": "v0.5.9",
+    "tag": "v0.5.10",
     "agents": {
         "ostacky": {
-            "version": "0.5.9",
+            "version": "0.5.10",
             "installedAt": "2025-01-01T00:00:00.000Z",
             "sha256": "abc123..."
         }
     },
     "commands": {
         "install-stack": {
-            "version": "0.5.9",
+            "version": "0.5.10",
             "installedAt": "2025-01-01T00:00:00.000Z",
             "sha256": "def456..."
         },
         "opsx-sync": {
-            "version": "0.5.9",
+            "version": "0.5.10",
             "installedAt": "2025-01-01T00:00:00.000Z",
             "sha256": "ghi789..."
         }
     },
     "skills": {
-        "thinking": { "version": "0.5.9", ... },
-        "execution-mode-evaluation": { "version": "0.5.9", ... },
-        "openspec-propose": { "version": "0.5.9", ... }
+        "thinking": { "version": "0.5.10", ... },
+        "execution-mode-evaluation": { "version": "0.5.10", ... },
+        "openspec-propose": { "version": "0.5.10", ... }
     }
 }
 ```
@@ -274,7 +274,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.5.9`), nunca `main` — instalaciones reproducibles
+- Las URLs de descarga usan **tags de GitHub** (ej. `v0.5.10`), 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

package/assets/agents/ostacky.md

@@ -160,6 +160,24 @@ La opción por defecto va primera. **La primera respuesta del usuario es vincula
 
 **Cierre obligatorio:** DESPUÉS de `implementation_complete`, llamá `sync_complete` en el MISMO turno. Si te olvidás, el controller queda en SYNC y el próximo request falla.
 
+## Manejo de errores de tools MCP
+
+**Si una tool MCP no responde o devuelve error, la jerarquía de recursos es:**
+
+1. **CodeGraph** (primera opción siempre) → explora símbolos, callers, impacto, flujos
+2. **Engram** (si CodeGraph no está disponible) → `engram_mem_context` y `engram_mem_search` para recuperar contexto de sesiones previas, decisiones, bugs. Engram sabe lo que se hizo antes — no caigas a Grep si Engram está vivo.
+3. **Read + Glob** (último recurso) → solo cuando **ninguno** de los dos anteriores funciona
+
+**Por tool:**
+
+1. **CodeGraph**: Si `codegraph_explore` falla o no responde → si Engram está funcionando, usá `engram_mem_context` + `engram_mem_search` para recuperar contexto. Como último recurso, `Read` archivos directamente. **NUNCA uses Grep para explorar si Engram está disponible.**
+2. **Controller**: Si el ostacky-controller no está disponible → operá sin validación de estado. Todas las transiciones se manejan en lenguaje natural. No ejecutes subagentes sin autorización explícita.
+3. **Engram**: Si `engram_mem_*` falla → continuá sin memoria persistente. No bloquees el flujo por falta de memoria.
+4. **Timeout en tool call**: Si una tool no responde después de un intento, **no reintentes**. Reportá el error al usuario y seguí con lo que tenés. No te quedes en loop.
+5. **Tool no encontrada**: Si llamás una tool y recibís "tool not found" o "unavailable tool" → esa tool no está registrada. Reportalo. Si Engram está disponible, usalo para contexto. Si no, `Read` + `Glob`. Grep es el ABSOLUTO último recurso.
+
+**Regla de oro: ninguna tool failure debe congelar el agente.** Siempre tené un plan B antes de llamar a cualquier tool. Engram > Read > Grep.
+
 ## Guardrails
 
 ### Decisiones y estado

package/assets/commands/install-stack.md

@@ -5,7 +5,7 @@ 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.5.9, `npx ostacky install` ya instala automáticamente el stack completo (CodeGraph, OpenSpec, Engram, Context7, 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.5.10, `npx ostacky install` ya instala automáticamente el stack completo (CodeGraph, OpenSpec, Engram, Context7, 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.
 

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

@@ -3,15 +3,63 @@
 import { McpServer } from '@modelcontextprotocol/server';
 import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
 import * as z from 'zod/v4';
-import { readFileSync, writeFileSync, renameSync, mkdirSync } from 'node:fs';
-import { dirname } from 'node:path';
+import { readFileSync, writeFileSync, renameSync, mkdirSync, readdirSync, unlinkSync } from 'node:fs';
+import { dirname, basename } from 'node:path';
+
+const MAX_TASKS = 50;
+const MAX_SNAPSHOT_JSON_LENGTH = 100 * 1024; // 100KB per snapshot serialized
+const MAX_STATE_FILE_SIZE = 1024 * 1024; // 1MB hard cap for the entire state file
+
+/**
+ * Safe JSON.stringify that won't throw on circular references.
+ */
+function safeJsonStringify(obj, pretty = false) {
+    const seen = new WeakSet();
+    try {
+        return JSON.stringify(
+            obj,
+            (key, value) => {
+                if (typeof value === 'object' && value !== null) {
+                    if (seen.has(value)) return '[Circular]';
+                    seen.add(value);
+                }
+                return value;
+            },
+            pretty ? 2 : undefined
+        );
+    } catch (e) {
+        return `[Unstringifiable: ${e.message}]`;
+    }
+}
 
 function log(event, data) {
     const ts = new Date().toISOString();
-    const payload = data ? ` ${JSON.stringify(data)}` : '';
+    const payload = data ? ` ${safeJsonStringify(data)}` : '';
     console.error(`[${ts}] ${event}${payload}`);
 }
 
+/**
+ * Cleans up stale .tmp.* files from a previous crash.
+ */
+function cleanupTmpFiles(statePath) {
+    if (!statePath) return;
+    const dir = dirname(statePath);
+    const name = basename(statePath);
+    try {
+        for (const entry of readdirSync(dir)) {
+            if (entry.startsWith(name + '.tmp.')) {
+                try {
+                    unlinkSync(dir + '/' + entry);
+                } catch {
+                    /* best-effort */
+                }
+            }
+        }
+    } catch {
+        /* directory may not exist yet */
+    }
+}
+
 const STATES = Object.freeze({
     INTERPRETATION_PENDING: 'INTERPRETATION_PENDING',
     CLARIFICATION_PENDING: 'CLARIFICATION_PENDING',
@@ -66,11 +114,32 @@ class OstackyController {
             this.#loaded = true;
             return;
         }
+        // Try primary state file
         try {
             const raw = readFileSync(this.#statePath, 'utf8');
+            if (raw.length > MAX_STATE_FILE_SIZE) throw new Error(`State file too large: ${raw.length} bytes`);
             this.#state = { ...DEFAULT_STATE, ...JSON.parse(raw) };
+            this.#loaded = true;
+            return;
+        } catch (err) {
+            log('warn:load_primary_failed', { error: err.message });
+        }
+        // Fallback: try .backup
+        const backupPath = this.#statePath + '.backup';
+        try {
+            const raw = readFileSync(backupPath, 'utf8');
+            if (raw.length > MAX_STATE_FILE_SIZE) throw new Error(`Backup too large: ${raw.length} bytes`);
+            this.#state = { ...DEFAULT_STATE, ...JSON.parse(raw), error: 'State restored from backup' };
+            log('warn:state_restored_from_backup');
+            this.#loaded = true;
+            return;
         } catch {
-            this.#state = { ...DEFAULT_STATE };
+            // No backup either — set error state instead of silent reset
+            this.#state = {
+                ...DEFAULT_STATE,
+                error: `State file corrupt: ${err.message}. No backup available. State reset to default.`,
+            };
+            log('warn:state_reset', { error: err.message });
         }
         this.#loaded = true;
     }
@@ -79,15 +148,57 @@ class OstackyController {
         if (!this.#statePath) return;
         const dir = dirname(this.#statePath);
         mkdirSync(dir, { recursive: true });
+        const serialized = safeJsonStringify(this.#state, true);
+        // Hard cap — if state exceeds 1MB, trim snapshots and retry
+        if (serialized.length > MAX_STATE_FILE_SIZE) {
+            log('warn:state_oversized', { size: serialized.length });
+            this.#state.snapshots = { codegraph: null, execution: null };
+            const trimmed = safeJsonStringify(this.#state, true);
+            if (trimmed.length > MAX_STATE_FILE_SIZE) {
+                log('error:state_too_large_even_after_trim');
+                return; // Don't persist — better to keep old state than write garbage
+            }
+            const tmp = this.#statePath + '.tmp.' + process.pid;
+            writeFileSync(tmp, trimmed, 'utf8');
+            renameSync(tmp, this.#statePath);
+            return;
+        }
         const tmp = this.#statePath + '.tmp.' + process.pid;
-        writeFileSync(tmp, JSON.stringify(this.#state, null, 2), 'utf8');
+        writeFileSync(tmp, serialized, 'utf8');
         renameSync(tmp, this.#statePath);
+        // Best-effort backup
+        try {
+            const backupPath = this.#statePath + '.backup';
+            writeFileSync(backupPath, serialized, 'utf8');
+        } catch {
+            /* backup is best-effort */
+        }
+    }
+
+    /**
+     * Trims old completed tasks when we exceed MAX_TASKS.
+     * Keeps the most recent MAX_TASKS entries.
+     */
+    #trimTasks() {
+        if (!this.#state.tasks) return;
+        const entries = Object.entries(this.#state.tasks);
+        if (entries.length <= MAX_TASKS) return;
+        // Sort by completedAt (desc), keep newest MAX_TASKS
+        entries.sort((a, b) => {
+            const da = a[1].completedAt || '';
+            const db = b[1].completedAt || '';
+            return db.localeCompare(da);
+        });
+        const trimmed = Object.fromEntries(entries.slice(0, MAX_TASKS));
+        this.#state.tasks = trimmed;
+        log('warn:tasks_trimmed', { before: entries.length, after: MAX_TASKS });
     }
 
     #transition(to, changes = {}) {
         this.#state.revision++;
         this.#state.state = to;
         Object.assign(this.#state, changes);
+        this.#trimTasks();
         this.#persist();
     }
 
@@ -206,7 +317,7 @@ class OstackyController {
         const to = this.#isAllowedTransition(this.#state.state, 'record_discovery');
         if (!to) return { error: `Cannot record discovery from state ${this.#state.state}` };
         if (!['0', '0+1', '1+'].includes(level)) return { error: `Invalid level: ${level}` };
-        this.#transition('ROUTE_DECISION_PENDING', {
+        this.#transition(to, {
             routeDecisionId: routeDecisionId || 'route-' + Date.now(),
             routeChoice: null,
             snapshots: { ...this.#state.snapshots, codegraph: snapshot || this.#state.snapshots.codegraph },
@@ -401,6 +512,7 @@ class OstackyController {
             if (!this.#state.fileFingerprints) this.#state.fileFingerprints = {};
             this.#state.fileFingerprints[filePath] = fileHash;
         }
+        this.#trimTasks();
         this.#persist();
         return {
             taskId,
@@ -409,14 +521,42 @@ class OstackyController {
                 .length,
         };
     }
+
+    /**
+     * Public flush — force-persists current state to disk.
+     * Used by graceful shutdown (private fields not accessible from outside).
+     */
+    flush() {
+        this.#persist();
+    }
 }
 
 const statePath = process.env.OSTACKY_STATE_PATH || '.opencode/ostacky-state.json';
 const controller = new OstackyController({ statePath });
 
+/**
+ * Wraps an async tool handler to ALWAYS return a response (even on error).
+ * Without this, an unhandled exception in any tool handler leaves the LLM
+ * waiting forever — the root cause of agent freezes.
+ */
+function safeHandler(fn) {
+    return async (params) => {
+        try {
+            const result = await fn(params);
+            return { content: [{ type: 'text', text: safeJsonStringify(result) }] };
+        } catch (error) {
+            log('tool:error', { name: fn.name || 'anonymous', error: error.message });
+            return {
+                content: [{ type: 'text', text: safeJsonStringify({ error: error.message }) }],
+                isError: true,
+            };
+        }
+    };
+}
+
 const server = new McpServer({
     name: 'ostacky-controller',
-    version: '0.5.9',
+    version: '0.5.10',
 });
 
 server.registerTool(
@@ -428,11 +568,10 @@ server.registerTool(
             changeId: z.string().optional().describe('Optional change ID for OpenSpec tracking'),
         }),
     },
-    async ({ requestId, changeId }) => {
+    safeHandler(async ({ requestId, changeId }) => {
         log('tool:start_request');
-        const result = await controller.startRequest({ requestId, changeId });
-        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
-    }
+        return await controller.startRequest({ requestId, changeId });
+    })
 );
 
 server.registerTool(
@@ -443,11 +582,10 @@ server.registerTool(
             question: z.string().optional().describe('The clarification question'),
         }),
     },
-    async ({ question }) => {
+    safeHandler(async ({ question }) => {
         log('tool:request_clarification');
-        const result = await controller.requestClarification({ question });
-        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
-    }
+        return await controller.requestClarification({ question });
+    })
 );
 
 server.registerTool(
@@ -456,11 +594,10 @@ server.registerTool(
         description: 'Record that clarification was answered. Transitions to DISCOVERY.',
         inputSchema: z.object({}),
     },
-    async () => {
+    safeHandler(async () => {
         log('tool:record_clarification');
-        const result = await controller.recordClarification();
-        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
-    }
+        return await controller.recordClarification();
+    })
 );
 
 server.registerTool(
@@ -473,11 +610,10 @@ server.registerTool(
             snapshot: z.any().optional().describe('Optional CodeGraph snapshot'),
         }),
     },
-    async ({ level, routeDecisionId, snapshot }) => {
+    safeHandler(async ({ level, routeDecisionId, snapshot }) => {
         log('tool:record_discovery', { level });
-        const result = await controller.recordDiscovery({ level, routeDecisionId, snapshot });
-        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
-    }
+        return await controller.recordDiscovery({ level, routeDecisionId, snapshot });
+    })
 );
 
 server.registerTool(
@@ -489,11 +625,10 @@ server.registerTool(
             choice: z.enum(['SPEC', 'DIRECT']).describe('Route choice'),
         }),
     },
-    async ({ decisionId, choice }) => {
+    safeHandler(async ({ decisionId, choice }) => {
         log('tool:consume_route_decision', { choice });
-        const result = await controller.consumeRouteDecision({ decisionId, choice });
-        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
-    }
+        return await controller.consumeRouteDecision({ decisionId, choice });
+    })
 );
 
 server.registerTool(
@@ -502,11 +637,10 @@ server.registerTool(
         description: 'Mark specification phase as complete. Transitions to EXECUTION_ANALYSIS.',
         inputSchema: z.object({}),
     },
-    async () => {
+    safeHandler(async () => {
         log('tool:spec_complete');
-        const result = await controller.specComplete();
-        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
-    }
+        return await controller.specComplete();
+    })
 );
 
 server.registerTool(
@@ -518,11 +652,10 @@ server.registerTool(
             snapshot: z.any().optional().describe('Execution analysis snapshot'),
         }),
     },
-    async ({ executionDecisionId, snapshot }) => {
+    safeHandler(async ({ executionDecisionId, snapshot }) => {
         log('tool:record_execution_analysis');
-        const result = await controller.recordExecutionAnalysis({ executionDecisionId, snapshot });
-        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
-    }
+        return await controller.recordExecutionAnalysis({ executionDecisionId, snapshot });
+    })
 );
 
 server.registerTool(
@@ -534,11 +667,10 @@ server.registerTool(
             mode: z.enum(['INLINE', 'SUBAGENT_DRIVEN']).describe('Execution mode'),
         }),
     },
-    async ({ decisionId, mode }) => {
+    safeHandler(async ({ decisionId, mode }) => {
         log('tool:consume_execution_decision', { mode });
-        const result = await controller.consumeExecutionDecision({ decisionId, mode });
-        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
-    }
+        return await controller.consumeExecutionDecision({ decisionId, mode });
+    })
 );
 
 server.registerTool(
@@ -547,11 +679,10 @@ server.registerTool(
         description: 'Mark implementation as complete. Transitions to SYNC.',
         inputSchema: z.object({}),
     },
-    async () => {
+    safeHandler(async () => {
         log('tool:implementation_complete');
-        const result = await controller.implementationComplete();
-        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
-    }
+        return await controller.implementationComplete();
+    })
 );
 
 server.registerTool(
@@ -560,11 +691,10 @@ server.registerTool(
         description: 'Mark sync as complete. Transitions to DONE.',
         inputSchema: z.object({}),
     },
-    async () => {
+    safeHandler(async () => {
         log('tool:sync_complete');
-        const result = await controller.syncComplete();
-        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
-    }
+        return await controller.syncComplete();
+    })
 );
 
 server.registerTool(
@@ -575,11 +705,10 @@ server.registerTool(
             reason: z.string().optional().describe('Reason for blocking'),
         }),
     },
-    async ({ reason }) => {
+    safeHandler(async ({ reason }) => {
         log('tool:block');
-        const result = await controller.block({ reason });
-        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
-    }
+        return await controller.block({ reason });
+    })
 );
 
 server.registerTool(
@@ -590,11 +719,10 @@ server.registerTool(
             reason: z.string().optional().describe('Reason for replanning'),
         }),
     },
-    async ({ reason }) => {
+    safeHandler(async ({ reason }) => {
         log('tool:replan');
-        const result = await controller.replan({ reason });
-        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
-    }
+        return await controller.replan({ reason });
+    })
 );
 
 server.registerTool(
@@ -603,10 +731,9 @@ server.registerTool(
         description: 'Get the current controller state (reads persistent store).',
         inputSchema: z.object({}),
     },
-    async () => {
-        const result = await controller.getState();
-        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
-    }
+    safeHandler(async () => {
+        return await controller.getState();
+    })
 );
 
 server.registerTool(
@@ -615,10 +742,9 @@ server.registerTool(
         description: 'Get current task states.',
         inputSchema: z.object({}),
     },
-    async () => {
-        const result = await controller.getTasks();
-        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
-    }
+    safeHandler(async () => {
+        return await controller.getTasks();
+    })
 );
 
 server.registerTool(
@@ -633,12 +759,13 @@ server.registerTool(
             newString: z.string().describe('The replacement string.'),
             content: z
                 .string()
-                .optional()
-                .describe('The current file content. REQUIRED — read the file first with Read tool.'),
+                .describe(
+                    'REQUIRED — The current file content. Read the file first with Read tool, then pass the full content here.'
+                ),
             taskId: z.string().optional().describe('Optional task ID for tracking.'),
         }),
     },
-    async ({ oldString, newString, content, taskId }) => {
+    safeHandler(async ({ oldString, newString, content, taskId }) => {
         log('tool:validate_edit', {
             taskId,
             oldLen: oldString?.length,
@@ -647,20 +774,12 @@ server.registerTool(
         });
         if (typeof content !== 'string' || typeof oldString !== 'string' || typeof newString !== 'string') {
             return {
-                content: [
-                    {
-                        type: 'text',
-                        text: JSON.stringify({
-                            outcome: 'CONFLICT',
-                            reason: 'Missing required fields: content, oldString, and newString are all required. Read the file first, then pass content to validate_edit.',
-                        }),
-                    },
-                ],
+                outcome: 'CONFLICT',
+                reason: 'Missing required fields: content, oldString, and newString are all required. Read the file first, then pass content to validate_edit.',
             };
         }
-        const result = await controller.validateEdit({ oldString, newString, content, taskId });
-        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
-    }
+        return await controller.validateEdit({ oldString, newString, content, taskId });
+    })
 );
 
 server.registerTool(
@@ -675,16 +794,46 @@ server.registerTool(
             fileHash: z.string().optional().describe('Optional SHA-256 hash of the file after modification.'),
         }),
     },
-    async ({ taskId, filePath, fileHash }) => {
+    safeHandler(async ({ taskId, filePath, fileHash }) => {
         log('tool:complete_task', { taskId, filePath });
-        const result = await controller.completeTask({ taskId, filePath, fileHash });
-        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
-    }
+        return await controller.completeTask({ taskId, filePath, fileHash });
+    })
 );
 
+/**
+ * Graceful shutdown: clean up tmp files and flush state.
+ */
+function setupGracefulShutdown(ctrl) {
+    const shutdown = (signal) => {
+        log('shutdown', { signal });
+        // Final persist attempt (flush via public method, sync inside)
+        try {
+            if (ctrl) ctrl.flush();
+        } catch {
+            /* best-effort */
+        }
+        // Clean up own tmp files
+        try {
+            cleanupTmpFiles(statePath);
+        } catch {
+            /* best-effort */
+        }
+        process.exit(signal === 'SIGINT' ? 130 : 0);
+    };
+    process.on('SIGTERM', () => shutdown('SIGTERM'));
+    process.on('SIGINT', () => shutdown('SIGINT'));
+    // Prevent unhandled rejections from silently killing the server
+    process.on('unhandledRejection', (reason) => {
+        log('unhandled_rejection', { reason: String(reason) });
+    });
+}
+
 async function main() {
     log('Starting ostacky-controller MCP...');
     log('State path:', { path: statePath });
+    // Clean up stale tmp files from previous runs
+    cleanupTmpFiles(statePath);
+    setupGracefulShutdown(controller);
     const transport = new StdioServerTransport();
     await server.connect(transport);
     log('ostacky-controller connected and ready');

package/assets/mcp/ostacky-controller/package.json

@@ -1,6 +1,6 @@
 {
     "name": "ostacky-controller",
-    "version": "0.5.9",
+    "version": "0.5.10",
     "private": true,
     "type": "module",
     "dependencies": {

package/assets/tests/agent-contract.test.js

@@ -205,14 +205,15 @@ describe('Controller contract — index.js', () => {
             'validate_edit not registered as MCP tool');
     });
 
-    it('validate_edit schema has content as optional (not required)', () => {
+    it('validate_edit schema has content as required (z.string())', () => {
         // Find the validate_edit schema section
         const validateSection = controllerContent.substring(
             controllerContent.indexOf("'validate_edit'"),
             controllerContent.indexOf("'complete_task'")
         );
-        assert.ok(validateSection.includes('content: z.string().optional()'),
-            'validate_edit content param should be z.string().optional() — agent may omit it');
+        assert.ok(validateSection.includes('content: z.string()') &&
+                  !validateSection.includes('content: z.string().optional()'),
+            'validate_edit content param should be z.string() required — prevents silent state corruption');
     });
 
     it('validate_edit handler validates content type', () => {