ostacky 0.5.9 → 0.6.0

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

@@ -3,15 +3,128 @@
 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;
+const MAX_STATE_FILE_SIZE = 1024 * 1024;
+const WATCHDOG_TIMEOUT_MS = 30_000;
+const WATCHDOG_CHECK_INTERVAL_MS = 10_000;
+let lastToolActivity = Date.now();
+
+const TRANSITIONS = {
+    INTERPRETATION_PENDING: [
+        { via: 'request_clarification', to: 'CLARIFICATION_PENDING' },
+        { via: 'proceed_to_discovery', to: 'DISCOVERY' },
+        { via: 'record_discovery', to: 'ROUTE_DECISION_PENDING' },
+        { via: 'block', to: 'BLOCKED' },
+    ],
+    CLARIFICATION_PENDING: [
+        { via: 'record_clarification', to: 'DISCOVERY' },
+        { via: 'block', to: 'BLOCKED' },
+        { via: 'abandon', to: 'BLOCKED' },
+    ],
+    DISCOVERY: [
+        { via: 'record_discovery', to: 'LEVEL_RESOLVED' },
+        { via: 'block', to: 'BLOCKED' },
+        { via: 'abandon', to: 'BLOCKED' },
+    ],
+    LEVEL_RESOLVED: [
+        { via: 'proceed_to_route', to: 'ROUTE_DECISION_PENDING' },
+        { via: 'block', to: 'BLOCKED' },
+    ],
+    ROUTE_DECISION_PENDING: [
+        { via: 'consume_route_decision', to: 'SPECIFICATION', choice: 'SPEC' },
+        { via: 'consume_route_decision', to: 'EXECUTION_ANALYSIS', choice: 'DIRECT' },
+        { via: 'block', to: 'BLOCKED' },
+        { via: 'abandon', to: 'BLOCKED' },
+    ],
+    SPECIFICATION: [
+        { via: 'spec_complete', to: 'EXECUTION_ANALYSIS' },
+        { via: 'block', to: 'BLOCKED' },
+        { via: 'abandon', to: 'BLOCKED' },
+    ],
+    EXECUTION_ANALYSIS: [
+        { via: 'analysis_complete', to: 'EXECUTION_DECISION_PENDING' },
+        { via: 'block', to: 'BLOCKED' },
+        { via: 'abandon', to: 'BLOCKED' },
+    ],
+    EXECUTION_DECISION_PENDING: [
+        { via: 'consume_execution_decision', to: 'EXECUTING_INLINE', mode: 'INLINE' },
+        { via: 'consume_execution_decision', to: 'EXECUTING_SUBAGENTS', mode: 'SUBAGENT_DRIVEN' },
+        { via: 'block', to: 'BLOCKED' },
+        { via: 'abandon', to: 'BLOCKED' },
+    ],
+    EXECUTING_INLINE: [
+        { via: 'implementation_complete', to: 'SYNC' },
+        { via: 'block', to: 'BLOCKED' },
+    ],
+    EXECUTING_SUBAGENTS: [
+        { via: 'implementation_complete', to: 'SYNC' },
+        { via: 'block', to: 'BLOCKED' },
+    ],
+    BLOCKED: [
+        { via: 'replan', to: 'INTERPRETATION_PENDING' },
+        { via: 'abandon', to: 'DONE' },
+    ],
+    SYNC: [
+        { via: 'sync_complete', to: 'DONE' },
+        { via: 'block', to: 'BLOCKED' },
+    ],
+    DONE: [],
+};
+
+/**
+ * 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',
@@ -59,6 +172,19 @@ class OstackyController {
         }
     }
 
+    /**
+     * Validates that a parsed state object has the required fields and valid values.
+     * Returns null if valid, or an error message if invalid.
+     */
+    #validateState(parsed) {
+        if (typeof parsed !== 'object' || parsed === null) return 'State is not an object';
+        if (typeof parsed.state !== 'string') return 'Missing or invalid "state" field';
+        if (!STATES[parsed.state]) return `Unknown state: "${parsed.state}"`;
+        if (typeof parsed.revision !== 'number') return 'Missing or invalid "revision" field';
+        if (parsed.revision < 0) return `Invalid revision: ${parsed.revision}`;
+        return null; // valid
+    }
+
     #load() {
         if (this.#loaded) return;
         if (!this.#statePath) {
@@ -66,11 +192,38 @@ class OstackyController {
             this.#loaded = true;
             return;
         }
+        // Try primary state file
         try {
             const raw = readFileSync(this.#statePath, 'utf8');
-            this.#state = { ...DEFAULT_STATE, ...JSON.parse(raw) };
-        } catch {
-            this.#state = { ...DEFAULT_STATE };
+            if (raw.length > MAX_STATE_FILE_SIZE) throw new Error(`State file too large: ${raw.length} bytes`);
+            const parsed = JSON.parse(raw);
+            const validationError = this.#validateState(parsed);
+            if (validationError) throw new Error(`State validation failed: ${validationError}`);
+            this.#state = { ...DEFAULT_STATE, ...parsed };
+            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`);
+            const parsed = JSON.parse(raw);
+            const validationError = this.#validateState(parsed);
+            if (validationError) throw new Error(`Backup validation failed: ${validationError}`);
+            this.#state = { ...DEFAULT_STATE, ...parsed, error: 'State restored from backup' };
+            log('warn:state_restored_from_backup');
+            this.#loaded = true;
+            return;
+        } catch (backupErr) {
+            // No backup either — set error state instead of silent reset
+            this.#state = {
+                ...DEFAULT_STATE,
+                error: `State file corrupt: ${backupErr.message}. No backup available. State reset to default.`,
+            };
+            log('warn:state_reset', { error: backupErr.message });
         }
         this.#loaded = true;
     }
@@ -79,9 +232,46 @@ class OstackyController {
         if (!this.#statePath) return;
         const dir = dirname(this.#statePath);
         mkdirSync(dir, { recursive: true });
+        let serialized = safeJsonStringify(this.#state, true);
+        if (serialized.length > MAX_STATE_FILE_SIZE) {
+            log('warn:state_oversized', { size: serialized.length });
+            const trimmed = { ...this.#state, snapshots: { codegraph: null, execution: null } };
+            serialized = safeJsonStringify(trimmed, true);
+            if (serialized.length > MAX_STATE_FILE_SIZE) {
+                log('error:state_too_large_even_after_trim');
+                return;
+            }
+            this.#state.snapshots = { codegraph: null, execution: null };
+        }
         const tmp = this.#statePath + '.tmp.' + process.pid;
-        writeFileSync(tmp, JSON.stringify(this.#state, null, 2), 'utf8');
+        writeFileSync(tmp, serialized, 'utf8');
         renameSync(tmp, this.#statePath);
+        try {
+            const backupTmp = this.#statePath + '.backup.tmp.' + process.pid;
+            writeFileSync(backupTmp, serialized, 'utf8');
+            renameSync(backupTmp, this.#statePath + '.backup');
+        } 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 = {}) {
@@ -92,66 +282,7 @@ class OstackyController {
     }
 
     #isAllowedTransition(from, via, choiceOrMode) {
-        const table = {
-            INTERPRETATION_PENDING: [
-                { to: 'CLARIFICATION_PENDING', via: 'request_clarification' },
-                { to: 'DISCOVERY', via: 'proceed_to_discovery' },
-                { to: 'ROUTE_DECISION_PENDING', via: 'record_discovery' },
-                { to: 'BLOCKED', via: 'block' },
-            ],
-            CLARIFICATION_PENDING: [
-                { to: 'DISCOVERY', via: 'record_clarification' },
-                { to: 'BLOCKED', via: 'block' },
-                { to: 'BLOCKED', via: 'abandon' },
-            ],
-            DISCOVERY: [
-                { to: 'LEVEL_RESOLVED', via: 'record_discovery' },
-                { to: 'BLOCKED', via: 'block' },
-                { to: 'BLOCKED', via: 'abandon' },
-            ],
-            LEVEL_RESOLVED: [
-                { to: 'ROUTE_DECISION_PENDING', via: 'route_decision_pending' },
-                { to: 'BLOCKED', via: 'block' },
-            ],
-            ROUTE_DECISION_PENDING: [
-                { to: 'SPECIFICATION', via: 'consume_route_decision', choice: 'SPEC' },
-                { to: 'EXECUTION_ANALYSIS', via: 'consume_route_decision', choice: 'DIRECT' },
-                { to: 'BLOCKED', via: 'block' },
-            ],
-            SPECIFICATION: [
-                { to: 'EXECUTION_ANALYSIS', via: 'spec_complete' },
-                { to: 'BLOCKED', via: 'block' },
-                { to: 'BLOCKED', via: 'abandon' },
-            ],
-            EXECUTION_ANALYSIS: [
-                { to: 'EXECUTION_DECISION_PENDING', via: 'analysis_complete' },
-                { to: 'BLOCKED', via: 'block' },
-                { to: 'BLOCKED', via: 'abandon' },
-            ],
-            EXECUTION_DECISION_PENDING: [
-                { to: 'EXECUTING_INLINE', via: 'consume_execution_decision', mode: 'INLINE' },
-                { to: 'EXECUTING_SUBAGENTS', via: 'consume_execution_decision', mode: 'SUBAGENT_DRIVEN' },
-                { to: 'BLOCKED', via: 'block' },
-            ],
-            EXECUTING_INLINE: [
-                { to: 'SYNC', via: 'implementation_complete' },
-                { to: 'BLOCKED', via: 'block' },
-            ],
-            EXECUTING_SUBAGENTS: [
-                { to: 'SYNC', via: 'implementation_complete' },
-                { to: 'BLOCKED', via: 'block' },
-            ],
-            BLOCKED: [
-                { to: 'INTERPRETATION_PENDING', via: 'replan' },
-                { to: 'DONE', via: 'abandon' },
-            ],
-            SYNC: [
-                { to: 'DONE', via: 'sync_complete' },
-                { to: 'BLOCKED', via: 'block' },
-            ],
-            DONE: [],
-        };
-        const transitions = table[from] || [];
+        const transitions = TRANSITIONS[from] || [];
         for (const t of transitions) {
             if (t.via !== via) continue;
             if (t.choice !== undefined && t.choice !== choiceOrMode) continue;
@@ -163,11 +294,7 @@ class OstackyController {
 
     async startRequest({ requestId, changeId } = {}) {
         this.#load();
-        if (
-            this.#state.state !== 'INTERPRETATION_PENDING' &&
-            this.#state.state !== 'BLOCKED' &&
-            this.#state.state !== 'DONE'
-        ) {
+        if (this.#state.state === 'INTERPRETATION_PENDING' && !requestId) {
             return { state: this.#state.state, revision: this.#state.revision, requestId: this.#state.requestId };
         }
         this.#transition('INTERPRETATION_PENDING', {
@@ -205,8 +332,10 @@ class OstackyController {
         this.#load();
         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', {
+        if (snapshot && safeJsonStringify(snapshot).length > MAX_SNAPSHOT_JSON_LENGTH) {
+            return { error: `Snapshot exceeds maximum size of ${MAX_SNAPSHOT_JSON_LENGTH} bytes` };
+        }
+        this.#transition(to, {
             routeDecisionId: routeDecisionId || 'route-' + Date.now(),
             routeChoice: null,
             snapshots: { ...this.#state.snapshots, codegraph: snapshot || this.#state.snapshots.codegraph },
@@ -221,17 +350,28 @@ class OstackyController {
         };
     }
 
+    async proceedToRoute() {
+        this.#load();
+        const to = this.#isAllowedTransition(this.#state.state, 'proceed_to_route');
+        if (!to) return { error: `Cannot proceed to route from state ${this.#state.state}` };
+        this.#transition(to);
+        return { state: this.#state.state, revision: this.#state.revision };
+    }
+
+    async abandon({ reason } = {}) {
+        this.#load();
+        const to = this.#isAllowedTransition(this.#state.state, 'abandon');
+        if (!to) return { error: `Cannot abandon from state ${this.#state.state}` };
+        this.#transition(to, { error: reason || 'Abandoned' });
+        return { state: this.#state.state, revision: this.#state.revision };
+    }
+
     async consumeRouteDecision({ decisionId, choice } = {}) {
         this.#load();
         if (this.#state.state !== 'ROUTE_DECISION_PENDING') {
-            if (this.#state.routeDecisionId === decisionId && this.#state.routeChoice) {
-                return { error: `Route decision ${decisionId} already consumed as ${this.#state.routeChoice}` };
-            }
             return { error: `Cannot consume route decision from state ${this.#state.state}` };
         }
         if (this.#state.routeDecisionId !== decisionId) return { error: `Decision ID mismatch` };
-        if (choice !== 'SPEC' && choice !== 'DIRECT') return { error: `Invalid choice: ${choice}` };
-        if (this.#state.routeChoice) return { error: `Decision already consumed as ${this.#state.routeChoice}` };
         const to = this.#isAllowedTransition(this.#state.state, 'consume_route_decision', choice);
         if (!to) return { error: `Route ${choice} not allowed from ${this.#state.state}` };
         this.#transition(to, { routeChoice: choice });
@@ -250,7 +390,10 @@ class OstackyController {
         this.#load();
         const to = this.#isAllowedTransition(this.#state.state, 'analysis_complete');
         if (!to) return { error: `Cannot record execution analysis from state ${this.#state.state}` };
-        this.#transition('EXECUTION_DECISION_PENDING', {
+        if (snapshot && safeJsonStringify(snapshot).length > MAX_SNAPSHOT_JSON_LENGTH) {
+            return { error: `Snapshot exceeds maximum size of ${MAX_SNAPSHOT_JSON_LENGTH} bytes` };
+        }
+        this.#transition(to, {
             executionDecisionId: executionDecisionId || 'exec-' + Date.now(),
             executionMode: null,
             snapshots: { ...this.#state.snapshots, execution: snapshot || null },
@@ -265,14 +408,9 @@ class OstackyController {
     async consumeExecutionDecision({ decisionId, mode } = {}) {
         this.#load();
         if (this.#state.state !== 'EXECUTION_DECISION_PENDING') {
-            if (this.#state.executionDecisionId === decisionId && this.#state.executionMode) {
-                return { error: `Execution decision ${decisionId} already consumed as ${this.#state.executionMode}` };
-            }
             return { error: `Cannot consume execution decision from state ${this.#state.state}` };
         }
         if (this.#state.executionDecisionId !== decisionId) return { error: `Decision ID mismatch` };
-        if (mode !== 'INLINE' && mode !== 'SUBAGENT_DRIVEN') return { error: `Invalid mode: ${mode}` };
-        if (this.#state.executionMode) return { error: `Decision already consumed as ${this.#state.executionMode}` };
         const to = this.#isAllowedTransition(this.#state.state, 'consume_execution_decision', mode);
         if (!to) return { error: `Mode ${mode} not allowed from ${this.#state.state}` };
         this.#transition(to, { executionMode: mode });
@@ -322,7 +460,7 @@ class OstackyController {
 
     async getState() {
         this.#load();
-        return { ...this.#state };
+        return structuredClone(this.#state);
     }
 
     async getTasks() {
@@ -330,6 +468,14 @@ class OstackyController {
         return { ...this.#state.tasks };
     }
 
+    async getAvailableTransitions() {
+        this.#load();
+        return {
+            currentState: this.#state.state,
+            transitions: TRANSITIONS[this.#state.state] || [],
+        };
+    }
+
     /**
      * Validates an edit against the current file content.
      * Returns one of: EDITABLE, ALREADY_APPLIED, CONFLICT.
@@ -401,6 +547,7 @@ class OstackyController {
             if (!this.#state.fileFingerprints) this.#state.fileFingerprints = {};
             this.#state.fileFingerprints[filePath] = fileHash;
         }
+        this.#trimTasks();
         this.#persist();
         return {
             taskId,
@@ -409,30 +556,62 @@ 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) => {
+        lastToolActivity = Date.now();
+        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,
+                stack: error.stack,
+            });
+            return {
+                content: [{ type: 'text', text: safeJsonStringify({ error: error.message }) }],
+                isError: true,
+            };
+        }
+    };
+}
+
 const server = new McpServer({
     name: 'ostacky-controller',
-    version: '0.5.9',
+    version: '0.6.0',
 });
 
 server.registerTool(
     'start_request',
     {
-        description: 'Start or resume a new request in the state machine. Call this first.',
+        description: 'Start or reset a new request. Can be called from ANY state — resets state machine. Call this first.',
         inputSchema: z.object({
             requestId: z.string().optional().describe('Unique request ID'),
             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 +622,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,28 +634,26 @@ 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(
     'record_discovery',
     {
-        description: 'Record discovery complete with level classification. Transitions to ROUTE_DECISION_PENDING.',
+        description: 'Record discovery complete with level classification. From INTERPRETATION_PENDING goes to ROUTE_DECISION_PENDING. From DISCOVERY goes to LEVEL_RESOLVED.',
         inputSchema: z.object({
             level: z.enum(['0', '0+1', '1+']).describe('Impact level'),
             routeDecisionId: z.string().optional().describe('Unique route decision ID'),
             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 +665,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 +677,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 +692,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 +707,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 +719,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 +731,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 +745,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 +759,54 @@ 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(
+    'proceed_to_route',
+    {
+        description: 'Proceed from LEVEL_RESOLVED to ROUTE_DECISION_PENDING after discovery is confirmed.',
+        inputSchema: z.object({}),
+    },
+    safeHandler(async () => {
+        log('tool:proceed_to_route');
+        return await controller.proceedToRoute();
+    })
+);
+
+server.registerTool(
+    'abandon',
+    {
+        description: 'Abandon the current request. Transitions to BLOCKED from most states, or to DONE from BLOCKED.',
+        inputSchema: z.object({
+            reason: z.string().optional().describe('Reason for abandoning'),
+        }),
+    },
+    safeHandler(async ({ reason }) => {
+        log('tool:abandon');
+        return await controller.abandon({ reason });
+    })
+);
+
+server.registerTool(
+    'ping',
+    {
+        description: 'Health check — returns pong if controller is alive. Use this to verify controller availability before making other calls.',
+        inputSchema: z.object({}),
+    },
+    safeHandler(async () => {
+        return {
+            pong: true,
+            state: await controller.getState().then(s => ({
+                state: s.state,
+                revision: s.revision,
+                requestId: s.requestId,
+            })),
+        };
+    })
 );
 
 server.registerTool(
@@ -603,10 +815,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 +826,50 @@ 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(
+    'get_available_transitions',
+    {
+        description: 'Get valid transitions from current state. Useful for debugging state machine issues.',
+        inputSchema: z.object({}),
+    },
+    safeHandler(async () => {
+        return await controller.getAvailableTransitions();
+    })
+);
+
+server.registerTool(
+    'check_pending_state',
+    {
+        description:
+            'Check if agent is in a pending state waiting for user input. ' +
+            'MUST be called before ANY tool call when controller is available. ' +
+            'Returns ALLOW or BLOCKED with reason. ' +
+            'EXCEPTION: controller tools (consume_route_decision, consume_execution_decision, ' +
+            'record_clarification, abandon) are ALWAYS allowed — they unlock the state.',
+        inputSchema: z.object({}),
+    },
+    safeHandler(async () => {
+        const state = await controller.getState();
+        const pendingStates = [
+            'CLARIFICATION_PENDING',
+            'ROUTE_DECISION_PENDING',
+            'EXECUTION_DECISION_PENDING',
+        ];
+        if (pendingStates.includes(state.state)) {
+            return {
+                status: 'BLOCKED',
+                state: state.state,
+                revision: state.revision,
+                reason: `Cannot execute tools while in ${state.state}. Wait for user response first.`,
+            };
+        }
+        return { status: 'ALLOW', state: state.state, revision: state.revision };
+    })
 );
 
 server.registerTool(
@@ -633,12 +884,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 +899,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 +919,63 @@ 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'));
+    process.on('SIGHUP', () => shutdown('SIGHUP'));
+    process.on('SIGPIPE', () => shutdown('SIGPIPE'));
+    // Prevent unhandled rejections from silently killing the server
+    process.on('unhandledRejection', (reason) => {
+        log('unhandled_rejection', { reason: String(reason) });
+    });
+}
+
+/**
+ * Watchdog that forces process restart if controller stops responding.
+ * This prevents the agent from hanging when the MCP server is stuck.
+ */
+function setupWatchdog() {
+    setInterval(() => {
+        const idleMs = Date.now() - lastToolActivity;
+        if (idleMs > WATCHDOG_TIMEOUT_MS) {
+            log('watchdog:timeout', { idleMs, threshold: WATCHDOG_TIMEOUT_MS });
+            process.exit(1);
+        }
+    }, WATCHDOG_CHECK_INTERVAL_MS);
+}
+
 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);
+    setupWatchdog();
     const transport = new StdioServerTransport();
     await server.connect(transport);
     log('ostacky-controller connected and ready');