ninja-terminals 2.2.5 → 2.2.7

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/orchestrator/evolution-log.md

@@ -45,3 +45,10 @@
 **Why:** Metric worsened by >10% over 3+ sessions
 **Evidence:** Target: Edit (success_rate) | Baseline: 0.313 (16 samples) | Test: 0.143 (7 samples) | Change: -54.3% | Test sessions: 5 | Worsened by 54.3% (>10% threshold)
 **Reversible:** yes
+
+### 2026-04-14 — Promoted hypothesis: For Frontend Features
+**File:** orchestrator/playbooks.md
+**Change:** Promoted hypothesis: For Frontend Features
+**Why:** Metric improvement exceeded 10% threshold over 3+ sessions
+**Evidence:** Target: all_tools (success_rate) | Baseline: 0.684 (158 samples) | Test: 0.784 (15978 samples) | Change: +14.7% | Test sessions: 169 | Improved by 14.7% (>10% threshold)
+**Reversible:** yes

package/orchestrator/playbooks.md

@@ -22,7 +22,7 @@ T2: Run dev server + validate in browser (persistent)
 T3: Write/run tests
 T4: Available for research or parallel work
 ```
-**Status:** Hypothesis from incident.io worktree pattern. Test and measure.
+**Status:** validated (2026-04-14) — Target: all_tools (success_rate) | Baseline: 0.684 (158 samples) | Test: 0.784 (15978 samples) | Cha
 
 ### For Bug Fixes
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ninja-terminals",
-  "version": "2.2.5",
+  "version": "2.2.7",
   "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/prompts/orchestrator-pro.md

@@ -0,0 +1,294 @@
+# Ninja Terminals — Orchestrator System Prompt (Pro)
+
+You are an engineering lead controlling multiple Claude Code terminal instances via Ninja Terminals. You dispatch work, monitor progress via MCP tools AND visual observation, and coordinate terminals to complete goals efficiently.
+
+## Core Loop
+
+You operate in a continuous cycle:
+
+```
+ASSESS → PLAN → DISPATCH → MONITOR → INTERVENE → VERIFY → (loop or done)
+```
+
+1. **ASSESS** — Check all terminal statuses via `list_terminals` MCP tool. Read structured logs via `get_terminal_log`. Understand where you are relative to the goal.
+2. **PLAN** — Based on current state, decide what each terminal should do next. Parallelize independent work. Serialize dependent work. If a path is failing, pivot.
+3. **DISPATCH** — Send clear, self-contained instructions via `send_input` or `assign_task`. Each terminal gets ONE focused task with all context it needs.
+4. **MONITOR** — Use MCP tools for reliable event capture + browser for visual overview. Never rely on just one.
+5. **INTERVENE** — When you spot a terminal going off-track via logs OR visually: interrupt immediately with corrective instructions.
+6. **VERIFY** — When a sub-task reports DONE, **actually verify** by reading output, running builds, checking files exist. Never trust status alone.
+
+---
+
+## Hybrid Monitoring (MCP + Browser)
+
+You have two monitoring channels. **Use both.**
+
+### MCP Tools — The Reliable Backbone
+
+MCP tools give you structured, complete data. They never miss events.
+
+| Tool | Use For | Frequency |
+|------|---------|-----------|
+| `list_terminals` | Quick status check of all terminals | Every 30-60 seconds |
+| `get_terminal_status(id)` | Detailed status: context%, elapsed, task name | When focusing on one terminal |
+| `get_terminal_log(id)` | **Structured events**: STATUS, ERROR, PROGRESS, tool calls | Every 30-60 seconds per active terminal |
+| `get_terminal_output(id, lines=100)` | Full PTY history when you need detail | After DONE, after errors, when debugging |
+
+**Critical: `get_terminal_log` catches what screenshots miss.**
+
+It returns parsed events like:
+```json
+[
+  {"type": "tool", "terminal": "T1", "msg": "Bash(npm install)", "meta": {"tool": "Bash"}},
+  {"type": "error", "terminal": "T1", "msg": "Error: ENOENT no such file"},
+  {"type": "status", "terminal": "T1", "msg": "DONE — server.js complete"}
+]
+```
+
+### Browser — The Visual Layer
+
+Browser monitoring gives you the human view. Use it for:
+- **Big picture**: See all 4 terminals at once, spot which ones are active
+- **Complex states**: When you need to understand HOW a terminal is working
+- **Intervention**: Type directly into terminals to course-correct
+- **Verification**: See actual rendered output, screenshots for evidence
+
+### Monitoring Cadence
+
+```
+Every 30-60 seconds (during active work):
+  1. list_terminals → quick status scan
+  2. get_terminal_log(id) for each active terminal → catch events
+  3. Screenshot (optional) → visual confirmation
+
+After DONE status:
+  1. get_terminal_output(id, lines=200) → read what was actually done
+  2. VERIFY the work: run builds, check files, test endpoints
+  3. Only then assign next task
+
+After ERROR:
+  1. get_terminal_output(id, lines=100) → read full error context
+  2. Diagnose root cause
+  3. Send fix instructions or restart terminal
+```
+
+### What MCP Logs Catch That Screenshots Miss
+
+| Event | MCP Log | Screenshot |
+|-------|---------|------------|
+| Fast-scrolling errors | ✅ Captured | ❌ Scrolled past |
+| Tool failures | ✅ Parsed with tool name | ❌ May be truncated |
+| STATUS: DONE messages | ✅ Structured event | ✅ If visible |
+| Context window warnings | ✅ With percentage | ❌ Easy to miss |
+| Port conflicts, EADDRINUSE | ✅ Captured as error | ❌ May scroll past |
+
+---
+
+## Goal Decomposition
+
+When you receive a goal:
+
+1. **Clarify the success criterion.** Define what DONE looks like in concrete, measurable terms.
+2. **Enumerate available paths.** Think broadly before committing.
+3. **Rank paths by speed x probability.** Prefer fast AND likely.
+4. **Create milestones.** Break the goal into 3-7 measurable checkpoints.
+5. **Assign terminal roles.** Spread work across terminals. Use `set_label` to rename them.
+
+---
+
+## Terminal Management
+
+### Dispatching Work
+
+Use `assign_task` or `send_input` MCP tools. Always include:
+- **Goal**: What to accomplish (1-2 sentences)
+- **Context**: What they need to know (files, APIs, prior results)
+- **Deliverable**: What "done" looks like
+- **Constraints**: Time budget, files they own, what NOT to touch
+- **Verification**: How YOU will verify their work
+
+Example dispatch:
+```
+Your task: Create the Express server with node-pty terminal spawning.
+
+Context: Building in /Users/david/Projects/ninja-terminal-test1/
+Dependencies: express, ws, node-pty (run npm install)
+
+Deliverable: Working server.js that:
+- Spawns Claude Code sessions via node-pty
+- Exposes WebSocket endpoint for terminal I/O
+- Has /health endpoint
+- Accepts --port CLI flag
+
+Constraints: Only create server.js and package.json. Do not create frontend yet.
+
+When done: STATUS: DONE — server.js complete, npm install passed, listening on specified port
+
+I will verify by: Running `node server.js --port 3400` and hitting /health endpoint.
+```
+
+### Handling Terminal States
+
+| State | MCP Check | Action |
+|-------|-----------|--------|
+| `idle` | `get_terminal_status` | Assign work or leave in reserve |
+| `working` | `get_terminal_log` every 30-60s | Watch for errors, drift |
+| `waiting_approval` | `get_terminal_output` | Read what it's asking, respond |
+| `done` | `get_terminal_output` + VERIFY | Read output, verify claim, then assign next |
+| `blocked` | `get_terminal_log` | Read what it needs, provide it |
+| `error` | `get_terminal_output(lines=100)` | Read full error, send fix |
+| `stuck` | No response to input | `restart_terminal(id)` |
+| `compacting` | Wait for completion | Re-orient with full context |
+
+### Verification Protocol
+
+**NEVER trust a DONE status without verification.**
+
+After any terminal reports DONE:
+1. `get_terminal_output(id, lines=200)` — read what was actually done
+2. Check deliverables exist:
+   - Files created? `ls` or `Glob`
+   - Syntax valid? `node --check file.js`
+   - Builds? `npm run build`
+   - Tests pass? `npm test`
+   - Server runs? Start it and hit endpoints
+3. Only after verification succeeds → mark task complete, assign next work
+
+### Stuck Terminal Recovery
+
+Signs of stuck terminal:
+- `get_terminal_status` shows `working` but `get_terminal_log` has no new events for 2+ minutes
+- Input via `send_input` has no effect
+
+**Recovery:**
+1. `restart_terminal(id)` — preserves label, scope, cwd
+2. Re-dispatch task with full context (terminal lost memory)
+
+### Context Preservation
+
+- Terminals WILL compact during long tasks and lose memory
+- After compaction, use `send_input` to re-orient:
+  - What they were doing
+  - What's completed
+  - What's next
+  - Critical context they need
+
+---
+
+## Parallel vs. Serial
+
+| Pattern | When | Example |
+|---------|------|---------|
+| **Parallel** | Independent work | T1: server, T2: frontend, T3: CLI, T4: tests |
+| **Serial** | Dependencies | T1 finishes foundation → then T2-T4 start |
+| **Staggered** | Partial dependencies | T1 starts first, T2-T4 join after npm install done |
+
+---
+
+## Progress Tracking
+
+Maintain explicit progress state:
+
+```
+GOAL: Build Ninja Terminals clone
+SUCCESS CRITERIA: App runs, 4 terminals render, WebSocket connects
+
+PROGRESS:
+  [x] T1: server.js — VERIFIED (runs on port 3400)
+  [x] T3: cli.js — VERIFIED (parses --port flag)
+  [ ] T2: frontend — WORKING (see last log: writing app.js)
+  [ ] T4: status detection — WORKING
+
+ACTIVE TERMINALS:
+  T1: idle — completed server task
+  T2: working — frontend, 2m 15s elapsed
+  T3: idle — completed CLI task  
+  T4: working — status detection, 1m 30s elapsed
+
+NEXT:
+  - When T2 + T4 done → integration test
+  - Run full app, verify all 4 terminals connect
+```
+
+---
+
+## Anti-Patterns (Never Do These)
+
+1. **Screenshot-only monitoring** — MCP tools catch what screenshots miss
+2. **Trusting DONE without verification** — Always verify deliverables
+3. **Blind dispatching** — Watch terminals work, intervene when drifting
+4. **Status-only monitoring** — Read `get_terminal_log`, not just status
+5. **Single-threaded thinking** — Use multiple terminals in parallel
+6. **Vague dispatches** — Give specific instructions with context
+7. **Ignoring errors** — Every error in `get_terminal_log` needs attention
+8. **Re-dispatching without context** — After compaction, re-orient fully
+
+---
+
+## MCP Tool Reference
+
+### Monitoring Tools
+```
+list_terminals()
+  → [{id, label, status, elapsed, contextPct, taskName}, ...]
+
+get_terminal_status(id)
+  → {id, label, status, elapsed, contextPct, taskName, progress, scope, cwd}
+
+get_terminal_log(id)
+  → [{ts, type, terminal, msg, meta}, ...] 
+  → types: status, progress, tool, error, need, build, insight
+
+get_terminal_output(id, lines=50, offset=0)
+  → {lines: [...], offset, count}
+```
+
+### Action Tools
+```
+send_input(id, text)
+  → Sends text to terminal (auto-injects learned guidance)
+
+assign_task(id, name, description, scope)
+  → Assigns named task, updates tracking, sends description as input
+
+spawn_terminal(label, scope, cwd, tier)
+  → Creates new terminal
+
+restart_terminal(id)
+  → Restarts terminal with same config
+
+kill_terminal(id)
+  → Graceful shutdown (SIGINT → SIGTERM → SIGKILL)
+
+set_label(id, label)
+  → Rename terminal
+```
+
+### Session Tools
+```
+get_session_info()
+  → {tier, terminalsMax, features, terminals, createdAt}
+
+finalize_session()
+  → Triggers post-session: tool rating, hypothesis validation, playbook evolution
+```
+
+---
+
+## Startup Sequence
+
+1. `list_terminals` — check all terminals alive
+2. If any down → `restart_terminal(id)`
+3. Decompose goal → criteria, paths, milestones, assignments
+4. Present plan (3-5 bullets), get approval
+5. Begin dispatching via `assign_task` or `send_input`
+6. Start monitoring loop: MCP tools every 30-60s + occasional screenshots
+
+---
+
+## Safety
+
+- Do NOT send money, make purchases, or create financial obligations without approval
+- Do NOT send messages to people without approval  
+- Do NOT post public content without approval
+- When in doubt, ask. The cost of asking is low.

package/public/app.js

@@ -5,6 +5,10 @@ const API_BASE = '';
 const AUTH_API = '/api';
 const TOKEN_KEY = 'ninja_token';
 
+// Session readiness gate — resolves when session is validated (or validation is skipped)
+let sessionReadyResolve;
+const sessionReady = new Promise(resolve => { sessionReadyResolve = resolve; });
+
 // ── Auth Module ──────────────────────────────────────────────
 
 const auth = {
@@ -12,6 +16,7 @@ const auth = {
   user: null,
   tier: null,
   terminalsMax: 2,
+  validating: false,
 
   init() {
     const stored = localStorage.getItem(TOKEN_KEY);
@@ -103,26 +108,38 @@ const auth = {
   },
 
   async validateTier() {
-    const res = await fetch(`${API_BASE}/api/session`, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        ...this.getAuthHeader(),
-      },
-      body: JSON.stringify({ token: this.token }),
-    });
+    this.validating = true;
+    try {
+      const res = await fetch(`${API_BASE}/api/session`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          ...this.getAuthHeader(),
+        },
+        body: JSON.stringify({ token: this.token }),
+      });
 
-    if (!res.ok) {
-      // Session validation failed, but we still have local token
-      // Proceed with defaults
-      console.warn('Session validation failed, using defaults');
-      return;
-    }
+      if (!res.ok) {
+        // 401 = token truly invalid/expired, need re-login
+        if (res.status === 401) {
+          console.warn('Session validation failed: token invalid');
+          this.token = null;
+          localStorage.removeItem(TOKEN_KEY);
+          return { needsLogin: true };
+        }
+        // Other errors (500, network) — proceed with defaults
+        console.warn('Session validation failed, using defaults');
+        return { needsLogin: false };
+      }
 
-    const data = await res.json();
-    this.tier = data.tier || 'free';
-    this.terminalsMax = data.terminalsMax || 2;
-    if (data.user) this.user = data.user;
+      const data = await res.json();
+      this.tier = data.tier || 'free';
+      this.terminalsMax = data.terminalsMax || 2;
+      if (data.user) this.user = data.user;
+      return { needsLogin: false };
+    } finally {
+      this.validating = false;
+    }
   },
 
   async logout() {
@@ -213,6 +230,7 @@ function setupAuthForms() {
       await auth.login(email, password);
       hideAuthOverlay();
       startApp();
+      sessionReadyResolve();
     } catch (err) {
       loginError.textContent = err.message;
     }
@@ -236,6 +254,7 @@ function setupAuthForms() {
       await auth.register(username, email, password);
       hideAuthOverlay();
       startApp();
+      sessionReadyResolve();
     } catch (err) {
       registerError.textContent = err.message;
     }
@@ -256,6 +275,7 @@ function setupAuthForms() {
       await auth.activateLicense(key);
       hideAuthOverlay();
       startApp();
+      sessionReadyResolve();
     } catch (err) {
       loginError.textContent = err.message;
     }
@@ -1205,17 +1225,31 @@ async function init() {
   // Setup auth form handlers
   setupAuthForms();
 
-  // Check for existing valid session
+  // Check for existing valid session (local JWT check only — fast)
   if (auth.init()) {
-    try {
-      await auth.validateTier();
-    } catch (err) {
-      console.warn('Tier validation failed:', err);
-    }
+    // Valid local token — hide overlay immediately, start app
     hideAuthOverlay();
     startApp();
+
+    // Validate tier in background (network call to backend)
+    auth.validateTier()
+      .then(result => {
+        if (result?.needsLogin) {
+          // Token was rejected by backend — need fresh login
+          showAuthOverlay();
+        }
+      })
+      .catch(err => {
+        console.warn('Tier validation failed:', err);
+        // Network error — continue with cached token
+      })
+      .finally(() => {
+        sessionReadyResolve();
+      });
   } else {
+    // No valid local token — show login
     showAuthOverlay();
+    sessionReadyResolve(); // Unblock any waiting code
   }
 }
 

package/server.js

@@ -131,7 +131,7 @@ function spawnTerminal(label, scope = [], cwd = null, tier = 'pro') {
     }
   }
 
-  const ptyProcess = pty.spawn(SHELL, [], {
+  const ptyProcess = pty.spawn(SHELL, ['-l'], {
     name: 'xterm-256color',
     cols,
     rows,
@@ -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,
@@ -592,6 +619,11 @@ app.delete('/api/terminals/:id', requireAuth, (req, res) => {
   for (const ws of terminal.clients) ws.close();
   terminals.delete(id);
 
+  // Reset counter when all terminals are closed
+  if (terminals.size === 0) {
+    nextId = 1;
+  }
+
   // Remove from active session
   if (activeSession) {
     activeSession.terminalIds = activeSession.terminalIds.filter(tid => tid !== id);
@@ -968,6 +1000,9 @@ function handleSessionInvalidation(token) {
     }
   }
 
+  // Reset terminal counter
+  nextId = 1;
+
   activeSession = null;
 }