brain-dev 0.1.1 → 0.2.0

package/bin/lib/stuck.cjs

@@ -0,0 +1,269 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { readLog, tailLog } = require('./logger.cjs');
+const { writeBridge, readBridge } = require('./bridge.cjs');
+
+/**
+ * Detect progress by checking multiple signals.
+ * @param {string} brainDir
+ * @param {number} phaseNumber
+ * @returns {{ lastActivity: string|null, idleSeconds: number, signals: object, isIdle: boolean }}
+ */
+function detectProgress(brainDir, phaseNumber) {
+  const now = Date.now();
+  let lastActivity = null;
+  const signals = { events: null, files: null, commits: null };
+
+  // Signal 1: Last JSONL event timestamp
+  const lastEventTs = getLastEventTimestamp(brainDir, phaseNumber);
+  if (lastEventTs) {
+    signals.events = lastEventTs;
+    if (!lastActivity || new Date(lastEventTs) > new Date(lastActivity)) {
+      lastActivity = lastEventTs;
+    }
+  }
+
+  // Signal 2: Phase directory file modification times
+  const phaseDir = findPhaseDir(brainDir, phaseNumber);
+  if (phaseDir) {
+    try {
+      const files = fs.readdirSync(phaseDir);
+      for (const f of files) {
+        const stat = fs.statSync(path.join(phaseDir, f));
+        const mtime = stat.mtime.toISOString();
+        if (!signals.files || new Date(mtime) > new Date(signals.files)) {
+          signals.files = mtime;
+        }
+        if (!lastActivity || new Date(mtime) > new Date(lastActivity)) {
+          lastActivity = mtime;
+        }
+      }
+    } catch { /* phase dir may not exist */ }
+  }
+
+  const idleSeconds = lastActivity ? Math.round((now - new Date(lastActivity).getTime()) / 1000) : Infinity;
+  const isIdle = idleSeconds > 300; // default 5 minutes
+
+  return { lastActivity, idleSeconds, signals, isIdle };
+}
+
+/**
+ * Check timeout tiers based on elapsed time and configuration.
+ * @param {string} brainDir
+ * @param {object} state - brain.json state
+ * @returns {{ tier: 'none'|'soft'|'idle'|'hard', elapsedMinutes: number, idleMinutes: number, message: string|null }}
+ */
+function checkTimeouts(brainDir, state) {
+  const timeoutConfig = state.timeout || { soft: 20, idle: 5, hard: 45, enabled: true };
+
+  if (!timeoutConfig.enabled) {
+    return { tier: 'none', elapsedMinutes: 0, idleMinutes: 0, message: null };
+  }
+
+  const startedAt = state.phase?.execution_started_at;
+  if (!startedAt) {
+    return { tier: 'none', elapsedMinutes: 0, idleMinutes: 0, message: null };
+  }
+
+  const elapsedMs = Date.now() - new Date(startedAt).getTime();
+  const elapsedMinutes = Math.round(elapsedMs / 60000);
+
+  // Check progress for idle detection
+  const progress = detectProgress(brainDir, state.phase?.current || 1);
+  const idleMinutes = Math.round(progress.idleSeconds / 60);
+
+  // Hard timeout takes precedence
+  if (elapsedMinutes >= timeoutConfig.hard) {
+    return {
+      tier: 'hard',
+      elapsedMinutes,
+      idleMinutes,
+      message: `TIME LIMIT REACHED (${elapsedMinutes}m). Execute recovery protocol: commit all WIP, write SUMMARY with status "partial", output ## EXECUTION PARTIAL`
+    };
+  }
+
+  // Idle timeout
+  if (idleMinutes >= timeoutConfig.idle) {
+    return {
+      tier: 'idle',
+      elapsedMinutes,
+      idleMinutes,
+      message: `No progress detected for ${idleMinutes}m. Agent may be stuck. Check output or extend timeout: brain-dev config set timeout.idle ${timeoutConfig.idle * 2}`
+    };
+  }
+
+  // Soft timeout
+  if (elapsedMinutes >= timeoutConfig.soft) {
+    return {
+      tier: 'soft',
+      elapsedMinutes,
+      idleMinutes,
+      message: `Agent running for ${elapsedMinutes}m (soft timeout: ${timeoutConfig.soft}m). Consider wrapping up current task.`
+    };
+  }
+
+  return { tier: 'none', elapsedMinutes, idleMinutes, message: null };
+}
+
+/**
+ * Check for execution non-convergence.
+ * Detects: same plan attempted 3+ times, repeated spawns without spot-check pass.
+ * @param {string} brainDir
+ * @param {number} phaseNumber
+ * @returns {{ converging: boolean, reason: string|null, repeatCount: number }}
+ */
+function checkExecutionConvergence(brainDir, phaseNumber) {
+  const events = readLog(brainDir, phaseNumber);
+
+  // Count spawn events per plan
+  const spawnsByPlan = {};
+  const passedPlans = new Set();
+
+  for (const event of events) {
+    if (event.type === 'spawn' && event.agent === 'executor' && event.plan) {
+      spawnsByPlan[event.plan] = (spawnsByPlan[event.plan] || 0) + 1;
+    }
+    if (event.type === 'spot-check' && event.passed && event.plan) {
+      passedPlans.add(event.plan);
+    }
+  }
+
+  // Check for repeated attempts on the same plan that haven't passed
+  for (const [plan, count] of Object.entries(spawnsByPlan)) {
+    if (count >= 3 && !passedPlans.has(plan)) {
+      return {
+        converging: false,
+        reason: `Plan ${plan} attempted ${count} times without passing spot-check`,
+        repeatCount: count
+      };
+    }
+  }
+
+  return { converging: true, reason: null, repeatCount: 0 };
+}
+
+/**
+ * Capture diagnostic information when stuck is detected.
+ * Writes to .brain/debug/stuck-{phase}-{timestamp}.md
+ * @param {string} brainDir
+ * @param {number} phaseNumber
+ * @param {object} stuckInfo - { tier, elapsedMinutes, idleMinutes, message }
+ * @returns {string} Path to diagnostic file
+ */
+function captureDiagnostics(brainDir, phaseNumber, stuckInfo) {
+  const debugDir = path.join(brainDir, 'debug');
+  try { fs.mkdirSync(debugDir, { recursive: true }); } catch {}
+
+  const timestamp = new Date().toISOString().replace(/:/g, '-').slice(0, 19);
+  const filename = `stuck-${String(phaseNumber).padStart(2, '0')}-${timestamp}.md`;
+  const filePath = path.join(debugDir, filename);
+
+  const events = tailLog(brainDir, phaseNumber, null);
+  const convergence = checkExecutionConvergence(brainDir, phaseNumber);
+
+  const content = `---
+phase: ${phaseNumber}
+triggered_at: ${new Date().toISOString()}
+elapsed_minutes: ${stuckInfo.elapsedMinutes}
+idle_minutes: ${stuckInfo.idleMinutes}
+timeout_tier: ${stuckInfo.tier}
+---
+
+# Stuck Diagnostic
+
+## Timeout Info
+- Tier: ${stuckInfo.tier}
+- Elapsed: ${stuckInfo.elapsedMinutes} minutes
+- Idle: ${stuckInfo.idleMinutes} minutes
+- Message: ${stuckInfo.message || 'none'}
+
+## Convergence
+- Converging: ${convergence.converging}
+${convergence.reason ? `- Issue: ${convergence.reason}` : ''}
+
+## Last ${events.length} Events
+${events.map(e => `- ${e.timestamp || '?'} [${e.type || '?'}] ${JSON.stringify(e)}`).join('\n')}
+
+## Recommendation
+${stuckInfo.tier === 'hard' ? 'Agent should commit partial work and output EXECUTION PARTIAL.' : ''}
+${stuckInfo.tier === 'idle' ? 'Check if agent is waiting for user input or stuck on an error.' : ''}
+${!convergence.converging ? `Non-convergent: ${convergence.reason}. Consider manual intervention.` : ''}
+`;
+
+  fs.writeFileSync(filePath, content);
+  return filePath;
+}
+
+/**
+ * Build wrap-up instructions for injection via PostToolUse hook.
+ * @param {number} phase
+ * @param {string|null} plan
+ * @returns {string}
+ */
+function buildWrapUpInstructions(phase, plan) {
+  const planId = plan ? `P${phase}-${plan}` : `P${phase}`;
+  return `[brain] TIME LIMIT REACHED. Execute the following recovery protocol:
+1. Stop current task implementation
+2. Commit all work in progress with message "wip(${planId}): partial - stuck timeout"
+3. Write SUMMARY.md with status "partial" and list completed vs remaining tasks
+4. Output ## EXECUTION PARTIAL with the same structure as EXECUTION FAILED`;
+}
+
+/**
+ * Get the timestamp of the most recent JSONL event.
+ * @param {string} brainDir
+ * @param {number} phaseNumber
+ * @returns {string|null} ISO timestamp or null
+ */
+function getLastEventTimestamp(brainDir, phaseNumber) {
+  const events = readLog(brainDir, phaseNumber);
+  if (events.length === 0) return null;
+  const last = events[events.length - 1];
+  return last.timestamp || null;
+}
+
+/**
+ * Find the phase directory for a given phase number.
+ * @param {string} brainDir
+ * @param {number} phaseNumber
+ * @returns {string|null}
+ */
+function findPhaseDir(brainDir, phaseNumber) {
+  const phasesDir = path.join(brainDir, 'phases');
+  if (!fs.existsSync(phasesDir)) return null;
+  const padded = String(phaseNumber).padStart(2, '0');
+  const dirs = fs.readdirSync(phasesDir).filter(d => d.startsWith(padded + '-'));
+  return dirs.length > 0 ? path.join(phasesDir, dirs[0]) : null;
+}
+
+/**
+ * Update the stuck bridge file with current stuck detection state.
+ * Called from hook-dispatcher during StatusLine.
+ * @param {string} brainDir
+ * @param {object} state
+ */
+function updateStuckBridge(brainDir, state) {
+  const timeoutResult = checkTimeouts(brainDir, state);
+  writeBridge(brainDir, 'stuck', {
+    phase_started_at: state.phase?.execution_started_at || null,
+    last_activity_at: detectProgress(brainDir, state.phase?.current || 1).lastActivity,
+    elapsed_minutes: timeoutResult.elapsedMinutes,
+    idle_minutes: timeoutResult.idleMinutes,
+    timeout_tier: timeoutResult.tier,
+    message: timeoutResult.message,
+    wrap_up: timeoutResult.tier === 'hard'
+  });
+}
+
+module.exports = {
+  detectProgress,
+  checkTimeouts,
+  checkExecutionConvergence,
+  captureDiagnostics,
+  buildWrapUpInstructions,
+  getLastEventTimestamp,
+  findPhaseDir,
+  updateStuckBridge
+};

package/bin/lib/tokens.cjs

@@ -0,0 +1,32 @@
+'use strict';
+
+const fs = require('node:fs');
+
+const CHARS_PER_TOKEN = 4;
+
+/**
+ * Estimate token count from text content.
+ * Uses chars/4 heuristic (~15-20% accuracy for English + code).
+ * @param {string} text
+ * @returns {number}
+ */
+function estimateTokens(text) {
+  if (!text) return 0;
+  return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+
+/**
+ * Estimate token count from a file on disk.
+ * @param {string} filePath - Absolute path to file
+ * @returns {number} Estimated tokens, 0 if file missing
+ */
+function estimateFileTokens(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    return estimateTokens(content);
+  } catch {
+    return 0;
+  }
+}
+
+module.exports = { estimateTokens, estimateFileTokens, CHARS_PER_TOKEN };

package/commands/brain/auto.md

@@ -0,0 +1,31 @@
+---
+name: brain:auto
+description: Run autonomous phase execution (discuss -> plan -> execute -> verify -> complete loop)
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Grep
+  - Glob
+  - Agent
+  - AskUserQuestion
+---
+<objective>
+Execute multiple phases automatically without human intervention.
+Chains: discuss -> plan -> execute -> verify -> complete -> next phase.
+</objective>
+
+<context>
+Auto mode generates a runbook of steps. Follow each step's instructions sequentially.
+Each step tells you which agent to spawn and what prompt to use.
+</context>
+
+<process>
+1. Run: `npx brain-dev execute --auto` (or `--dry-run` to preview)
+2. Follow the generated runbook instructions step by step
+3. Each step outputs the exact `npx brain-dev` command to run next
+4. On error: retry once, then run `npx brain-dev execute --auto --stop`
+5. Check progress: `npx brain-dev progress --cost`
+6. When done or stopped: `npx brain-dev execute --auto --stop` to release the lock
+</process>

package/commands/brain/dashboard.md

@@ -0,0 +1,18 @@
+---
+name: brain:dashboard
+description: Live monitoring dashboard showing phase progress, costs, and stuck detection
+allowed-tools:
+  - Read
+  - Bash
+---
+<objective>
+Display a live dashboard with phase progress, cost tracking, stuck detection, and recent events.
+Default mode shows a terminal (TUI) dashboard. Use --browser for web view.
+</objective>
+
+<process>
+1. Run: `npx brain-dev dashboard`
+2. Review the dashboard output
+3. Use `npx brain-dev dashboard --browser` for the web dashboard
+4. Use `npx brain-dev dashboard --stop` to stop a running web server
+</process>

package/commands/brain/recover.md

@@ -0,0 +1,19 @@
+---
+name: brain:recover
+description: Detect and recover from crashes or interrupted sessions
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+---
+<objective>
+Check for interrupted sessions and recover safely.
+Default mode shows what happened. Use --fix to auto-resume or --rollback to revert.
+</objective>
+
+<process>
+1. Run: `npx brain-dev recover`
+2. Review the recovery briefing
+3. Choose action: `npx brain-dev recover --fix` or `npx brain-dev recover --rollback` or `npx brain-dev recover --dismiss`
+</process>

package/commands/brain/update.md

@@ -0,0 +1,22 @@
+---
+name: brain:update
+description: Update brain tool files while preserving project state
+allowed-tools:
+  - Read
+  - Bash
+---
+<objective>
+Update brain's hooks, agents, and commands to the latest version without losing project state (brain.json, phases, roadmap, etc.).
+</objective>
+
+<process>
+1. Run: `npx brain-dev@latest update`
+2. Brain will:
+   - Backup brain.json to brain.json.pre-update
+   - Update hook scripts (.brain/hooks/)
+   - Update agent definitions (.claude/agents/)
+   - Update command files (.claude/commands/brain/)
+   - Migrate brain.json schema (add new fields, preserve existing)
+   - Regenerate STATE.md
+3. All project data is preserved: phases, plans, roadmap, research, quick tasks.
+</process>

package/hooks/bootstrap.sh

@@ -13,6 +13,20 @@ if [ ! -f "$BRAIN_DIR/brain.json" ]; then
   exit 0
 fi
 
+# Crash recovery check
+RECOVERY=$(npx brain-dev recover --json 2>/dev/null)
+if [ $? -eq 0 ] && echo "$RECOVERY" | node -e "
+  try {
+    let d=''; process.stdin.on('data',c=>d+=c); process.stdin.on('end',()=>{
+      const r=JSON.parse(d);
+      if(r.action==='recovery-detected') { console.log('[brain] WARNING: Previous session ended unexpectedly. Run /brain:recover to check state.'); process.exit(0); }
+      process.exit(1);
+    });
+  } catch { process.exit(1); }
+" 2>/dev/null; then
+  true  # Warning was printed by the inline script
+fi
+
 # Get status and format for context injection
 # Use npx to ensure brain-dev is found regardless of install method
 STATUS=$(npx brain-dev status --json 2>/dev/null)
@@ -34,7 +48,7 @@ try {
     'Phase: ' + (data.phase && data.phase.current || 0) + ' (' + (data.phase && data.phase.status || 'initialized') + ')',
     'Next: ' + (data.nextAction || '/brain:new-project'),
     '',
-    'Commands: /brain:new-project, /brain:discuss, /brain:plan, /brain:execute, /brain:verify, /brain:complete, /brain:quick, /brain:progress, /brain:pause, /brain:resume, /brain:help, /brain:health, /brain:storm, /brain:adr, /brain:phase, /brain:config, /brain:map',
+    'Commands: /brain:new-project, /brain:discuss, /brain:plan, /brain:execute, /brain:verify, /brain:complete, /brain:quick, /brain:progress, /brain:pause, /brain:resume, /brain:help, /brain:health, /brain:update, /brain:storm, /brain:adr, /brain:phase, /brain:config, /brain:map, /brain:recover, /brain:dashboard, /brain:auto (or execute --auto)',
     '',
     'Instructions for Claude:',
     '- When user types /brain:<command>, run: npx brain-dev <command> [args]',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brain-dev",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "AI-powered development workflow orchestrator",
   "author": "halilcosdu",
   "license": "MIT",