ninja-terminals 2.2.5 → 2.2.6

package/CLAUDE.md

@@ -38,6 +38,17 @@ These status lines are CRITICAL — the orchestrator parses them to know your st
 - If a build breaks, fix it yourself — don't wait for the orchestrator
 - If you hit a permissions wall, report BLOCKED with specifics
 
+### Stuck Terminal Recovery
+If you notice your terminal is stuck (no response to input, commands hang), or if you see another terminal is stuck:
+1. **Report it**: `STATUS: ERROR:STUCK — terminal unresponsive after [what happened]`
+2. **The orchestrator will**: Refresh the page or restart the terminal
+3. **After restart**: You will lose context. Wait for re-orientation from the orchestrator.
+
+Common causes of stuck terminals:
+- Permission errors (chmod, file access)
+- Tool failures that leave PTY in bad state
+- Context window overflow
+
 ### Completeness
 - Don't report DONE for partial work. If you were asked to "build and test", both must be done.
 - Include evidence with DONE: test output, screenshot path, API response, URL, file path

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ninja-terminals",
-  "version": "2.2.5",
+  "version": "2.2.6",
   "description": "MCP server for multi-terminal Claude Code orchestration with DAG task management, parallel execution, and self-improvement",
   "main": "server.js",
   "bin": {

package/prompts/orchestrator-lite.md

@@ -110,8 +110,22 @@ When done: STATUS: DONE — [template name and test result]
 | `done` | Read output. Verify the claim. Assign next task. |
 | `blocked` | Read what it needs. Provide it, or reassign. |
 | `error` | Read the error. Send fix instructions or restart. |
+| `stuck` | Terminal is unresponsive. **Refresh the page** or `POST /api/terminals/:id/restart`. |
 | `compacting` | Wait, then re-orient fully with context summary. |
 
+### Stuck Terminal Recovery
+Terminals can get stuck after tool errors (permission denied, failed commands, etc.). Signs of a stuck terminal:
+- No output for 2+ minutes while status shows "working"
+- Input commands have no effect
+- Status shows `stuck`
+
+**Recovery steps:**
+1. **First try**: Refresh the Ninja Terminals page (Cmd+R / Ctrl+R)
+2. **If that fails**: `POST /api/terminals/:id/restart` to restart just that terminal
+3. **Last resort**: Kill and respawn: `DELETE /api/terminals/:id` then `POST /api/terminals/spawn`
+
+After recovery, re-dispatch the task with full context — the terminal lost its memory.
+
 ### Context Preservation
 - Terminals WILL compact during long tasks and lose memory
 - You MUST re-orient them: what they were doing, what's completed, what's next, critical context

package/server.js

@@ -219,14 +219,41 @@ function spawnTerminal(label, scope = [], cwd = null, tier = 'pro') {
 
 // ── Status Detection Loop (2s) ──────────────────────────────
 
+// Track last output time for stuck detection
+const lastOutputTime = new Map();
+const STUCK_THRESHOLD_MS = 120000; // 2 minutes with no output = stuck
+
 setInterval(() => {
-  for (const [, terminal] of terminals) {
+  for (const [id, terminal] of terminals) {
     if (terminal.status === 'exited') continue;
     const prev = terminal.status;
     const recentLines = terminal.lineBuffer.last(50);
     const newStatus = detectStatus(recentLines);
 
-    if (newStatus !== prev) {
+    // Track output activity for stuck detection
+    const currentOutput = terminal.lineBuffer.last(5).join('');
+    const lastOutput = lastOutputTime.get(id);
+    if (!lastOutput || lastOutput.output !== currentOutput) {
+      lastOutputTime.set(id, { output: currentOutput, time: Date.now() });
+    }
+
+    // Check for stuck terminal (no output for 2+ minutes while "working")
+    const lastActivity = lastOutputTime.get(id);
+    if (lastActivity && terminal.status === 'working') {
+      const stuckTime = Date.now() - lastActivity.time;
+      if (stuckTime > STUCK_THRESHOLD_MS) {
+        terminal.status = 'stuck';
+        sse.broadcast('terminal_stuck', {
+          terminal: terminal.label,
+          id: terminal.id,
+          stuckFor: Math.round(stuckTime / 1000),
+          suggestion: 'Refresh page or POST /api/terminals/:id/restart',
+        });
+        console.log(`Terminal ${id} (${terminal.label}) appears stuck - no output for ${Math.round(stuckTime / 1000)}s`);
+      }
+    }
+
+    if (newStatus !== prev && newStatus !== 'stuck') {
       terminal.status = newStatus;
       sse.broadcast('status_change', {
         terminal: terminal.label,