dual-brain 0.2.13 → 0.2.15

package/src/session-lock.mjs

@@ -0,0 +1,154 @@
+// session-lock.mjs — Ensures one active HEAD session at a time.
+// If two shells/chats open, only one owns the cognitive state.
+// The other gets read-only access (can observe but not dispatch).
+//
+// "One ring rules them all" — no split-brain.
+
+import { existsSync, readFileSync, writeFileSync, unlinkSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+const STATE_DIR = join(process.cwd(), '.dualbrain');
+const LOCK_FILE = join(STATE_DIR, 'session.lock');
+
+const STALE_THRESHOLD_MS = 90_000; // 90 seconds without heartbeat = stale
+const HEARTBEAT_INTERVAL_MS = 30_000;
+
+let _heartbeatTimer = null;
+let _sessionId = null;
+
+/**
+ * @typedef {object} LockResult
+ * @property {boolean} acquired - Whether this session owns HEAD
+ * @property {string} sessionId - This session's ID
+ * @property {string|null} existingSession - ID of the session that already holds the lock (if not acquired)
+ * @property {string} mode - 'primary' | 'takeover' | 'readonly'
+ */
+
+/**
+ * Attempt to acquire the session lock.
+ * - If no lock exists or lock is stale: acquire as primary
+ * - If lock is fresh and held by another: return readonly
+ *
+ * @param {object} opts
+ * @param {boolean} opts.force - Force takeover even if existing session is fresh
+ * @returns {LockResult}
+ */
+export function acquire({ force = false } = {}) {
+  mkdirSync(STATE_DIR, { recursive: true });
+  _sessionId = _generateSessionId();
+
+  const existing = _readLock();
+
+  if (!existing) {
+    // No lock — claim it
+    _writeLock(_sessionId);
+    _startHeartbeat();
+    return { acquired: true, sessionId: _sessionId, existingSession: null, mode: 'primary' };
+  }
+
+  const age = Date.now() - existing.heartbeat;
+
+  if (age > STALE_THRESHOLD_MS || force) {
+    // Stale or forced takeover
+    _writeLock(_sessionId);
+    _startHeartbeat();
+    return { acquired: true, sessionId: _sessionId, existingSession: existing.sessionId, mode: 'takeover' };
+  }
+
+  // Another session is active — go readonly
+  return { acquired: false, sessionId: _sessionId, existingSession: existing.sessionId, mode: 'readonly' };
+}
+
+/**
+ * Release the session lock (called at session end).
+ */
+export function release() {
+  if (_heartbeatTimer) {
+    clearInterval(_heartbeatTimer);
+    _heartbeatTimer = null;
+  }
+
+  try {
+    const existing = _readLock();
+    if (existing && existing.sessionId === _sessionId) {
+      unlinkSync(LOCK_FILE);
+    }
+  } catch {}
+}
+
+/**
+ * Check if this session currently holds the lock.
+ * @returns {boolean}
+ */
+export function isOwner() {
+  const existing = _readLock();
+  return existing?.sessionId === _sessionId;
+}
+
+/**
+ * Get current lock status without modifying it.
+ * @returns {{active: boolean, sessionId: string|null, age: number|null}}
+ */
+export function status() {
+  const existing = _readLock();
+  if (!existing) return { active: false, sessionId: null, age: null };
+  return {
+    active: (Date.now() - existing.heartbeat) < STALE_THRESHOLD_MS,
+    sessionId: existing.sessionId,
+    age: Date.now() - existing.heartbeat,
+  };
+}
+
+/**
+ * Manually heartbeat (useful if the automatic timer isn't running).
+ */
+export function heartbeat() {
+  if (!_sessionId) return;
+  const existing = _readLock();
+  if (existing && existing.sessionId === _sessionId) {
+    _writeLock(_sessionId);
+  }
+}
+
+// ── Internal ──────────────────────────────────────────────────────────────────
+
+function _generateSessionId() {
+  return Date.now().toString(36) + '-' + Math.random().toString(36).slice(2, 8);
+}
+
+function _readLock() {
+  try {
+    if (!existsSync(LOCK_FILE)) return null;
+    return JSON.parse(readFileSync(LOCK_FILE, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function _writeLock(sessionId) {
+  const lock = {
+    sessionId,
+    heartbeat: Date.now(),
+    pid: process.pid,
+  };
+  writeFileSync(LOCK_FILE, JSON.stringify(lock));
+}
+
+function _startHeartbeat() {
+  if (_heartbeatTimer) clearInterval(_heartbeatTimer);
+  _heartbeatTimer = setInterval(() => {
+    try {
+      const existing = _readLock();
+      if (existing && existing.sessionId === _sessionId) {
+        _writeLock(_sessionId);
+      } else {
+        // Someone else took over — stop heartbeating
+        clearInterval(_heartbeatTimer);
+        _heartbeatTimer = null;
+      }
+    } catch {}
+  }, HEARTBEAT_INTERVAL_MS);
+
+  // Don't keep the process alive just for heartbeats
+  if (_heartbeatTimer.unref) _heartbeatTimer.unref();
+}

package/src/simmer.mjs

@@ -0,0 +1,241 @@
+// simmer.mjs — Ideas that aren't tasks yet. They sit, gather heat, and crystallize.
+//
+// The "song" insight: users drop ideas casually. HEAD tends to acknowledge them
+// verbally then move on. The simmer buffer catches these — every idea gets stored
+// with a heat score. Heat rises when: the idea recurs, evidence supports it,
+// adjacent work makes it more relevant, or time passes and it keeps nagging.
+// When heat crosses a threshold, the idea crystallizes into an actionable item
+// and surfaces to HEAD during deliberation.
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+const STATE_DIR = join(process.cwd(), '.dualbrain');
+const SIMMER_FILE = join(STATE_DIR, 'simmer.json');
+
+const CRYSTALLIZE_THRESHOLD = 5;
+const MAX_ITEMS = 30;
+const HEAT_DECAY_PER_HOUR = 0.3;
+
+/**
+ * @typedef {object} SimmerItem
+ * @property {string} id
+ * @property {string} idea - The raw idea in prose
+ * @property {string} origin - Where it came from (user quote, observation, debrief finding)
+ * @property {number} heat - Current heat score
+ * @property {number} createdAt
+ * @property {number} lastHeated - Last time heat was added
+ * @property {string[]} signals - Evidence trail (why heat was added)
+ * @property {boolean} crystallized - Whether it's crossed the threshold
+ * @property {string|null} crystallizedAs - What it became (task description, architecture decision, etc)
+ */
+
+/**
+ * Add a new idea to the simmer buffer.
+ * If a similar idea already exists (fuzzy match), heat it instead of duplicating.
+ *
+ * @param {string} idea - The idea in natural language
+ * @param {object} opts
+ * @param {string} opts.origin - Where this came from
+ * @param {number} opts.initialHeat - Starting heat (default 1)
+ * @returns {SimmerItem} The created or heated item
+ */
+export function add(idea, { origin = 'observation', initialHeat = 1 } = {}) {
+  const items = _load();
+
+  // Check for similar existing idea
+  const existing = _findSimilar(items, idea);
+  if (existing) {
+    return heat(existing.id, initialHeat, `Recurrence: "${idea.slice(0, 60)}"`);
+  }
+
+  const item = {
+    id: Date.now().toString(36) + Math.random().toString(36).slice(2, 5),
+    idea,
+    origin,
+    heat: initialHeat,
+    createdAt: Date.now(),
+    lastHeated: Date.now(),
+    signals: [`Created from: ${origin}`],
+    crystallized: false,
+    crystallizedAs: null,
+  };
+
+  items.push(item);
+  _save(items);
+  return item;
+}
+
+/**
+ * Add heat to an existing item. If it crosses the threshold, mark as crystallized.
+ *
+ * @param {string} id
+ * @param {number} amount - Heat to add (default 1)
+ * @param {string} signal - Why heat is being added
+ * @returns {SimmerItem|null}
+ */
+export function heat(id, amount = 1, signal = '') {
+  const items = _load();
+  const item = items.find(i => i.id === id);
+  if (!item) return null;
+
+  item.heat += amount;
+  item.lastHeated = Date.now();
+  if (signal) item.signals.push(signal);
+
+  // Cap signals array
+  if (item.signals.length > 10) {
+    item.signals = item.signals.slice(-10);
+  }
+
+  // Check crystallization
+  if (!item.crystallized && item.heat >= CRYSTALLIZE_THRESHOLD) {
+    item.crystallized = true;
+  }
+
+  _save(items);
+  return item;
+}
+
+/**
+ * Get all items that have crystallized but haven't been surfaced yet.
+ * These should be presented to HEAD during deliberation.
+ *
+ * @returns {SimmerItem[]}
+ */
+export function harvest() {
+  const items = _load();
+  return items.filter(i => i.crystallized && !i.crystallizedAs);
+}
+
+/**
+ * Mark a crystallized item as actioned — record what it became.
+ *
+ * @param {string} id
+ * @param {string} became - Description of what action was taken
+ */
+export function resolve(id, became) {
+  const items = _load();
+  const item = items.find(i => i.id === id);
+  if (!item) return;
+  item.crystallizedAs = became;
+  _save(items);
+}
+
+/**
+ * Get all active (non-resolved) simmering items, sorted by heat descending.
+ * Used by the narrative to include "what's brewing" context.
+ *
+ * @returns {SimmerItem[]}
+ */
+export function active() {
+  const items = _load();
+  _applyDecay(items);
+  return items
+    .filter(i => !i.crystallizedAs)
+    .sort((a, b) => b.heat - a.heat);
+}
+
+/**
+ * Check if an idea already exists in the buffer (for deduplication).
+ * @param {string} idea
+ * @returns {SimmerItem|null}
+ */
+export function find(idea) {
+  const items = _load();
+  return _findSimilar(items, idea);
+}
+
+/**
+ * Generate a brief for HEAD showing what's simmering.
+ * Included in the narrative context so HEAD is aware of brewing ideas.
+ *
+ * @returns {string} Prose summary of active simmer items, or empty string
+ */
+export function brief() {
+  const items = active();
+  if (items.length === 0) return '';
+
+  const crystallized = items.filter(i => i.crystallized);
+  const hot = items.filter(i => !i.crystallized && i.heat >= 3);
+  const warm = items.filter(i => !i.crystallized && i.heat >= 1.5 && i.heat < 3);
+
+  const parts = [];
+
+  if (crystallized.length > 0) {
+    parts.push(`Crystallized (ready to act): ${crystallized.map(i => i.idea.slice(0, 80)).join('; ')}`);
+  }
+  if (hot.length > 0) {
+    parts.push(`Hot (building momentum): ${hot.map(i => `${i.idea.slice(0, 60)} [heat:${i.heat.toFixed(1)}]`).join('; ')}`);
+  }
+  if (warm.length > 0 && parts.length < 2) {
+    parts.push(`Warm: ${warm.slice(0, 3).map(i => i.idea.slice(0, 50)).join('; ')}`);
+  }
+
+  return parts.join('\n');
+}
+
+/**
+ * Prune resolved and cold-dead items.
+ */
+export function prune() {
+  let items = _load();
+  _applyDecay(items);
+  // Remove: resolved items older than 1h, or items with heat <= 0
+  const cutoff = Date.now() - 60 * 60 * 1000;
+  items = items.filter(i => {
+    if (i.crystallizedAs && i.lastHeated < cutoff) return false;
+    if (i.heat <= 0) return false;
+    return true;
+  });
+  _save(items);
+}
+
+// ── Internal ──────────────────────────────────────────────────────────────────
+
+function _load() {
+  try {
+    if (existsSync(SIMMER_FILE)) {
+      return JSON.parse(readFileSync(SIMMER_FILE, 'utf8'));
+    }
+  } catch {}
+  return [];
+}
+
+function _save(items) {
+  // Cap total items
+  if (items.length > MAX_ITEMS) {
+    items.sort((a, b) => b.heat - a.heat);
+    items = items.slice(0, MAX_ITEMS);
+  }
+  mkdirSync(STATE_DIR, { recursive: true });
+  writeFileSync(SIMMER_FILE, JSON.stringify(items, null, 2));
+}
+
+function _applyDecay(items) {
+  const now = Date.now();
+  for (const item of items) {
+    if (item.crystallized) continue; // Crystallized items don't decay
+    const hoursSinceHeat = (now - item.lastHeated) / (60 * 60 * 1000);
+    if (hoursSinceHeat > 1) {
+      item.heat -= HEAT_DECAY_PER_HOUR * hoursSinceHeat;
+      if (item.heat < 0) item.heat = 0;
+    }
+  }
+}
+
+function _findSimilar(items, idea) {
+  const normalized = idea.toLowerCase().replace(/[^a-z0-9\s]/g, '');
+  const words = normalized.split(/\s+/).filter(w => w.length > 4);
+  if (words.length === 0) return null;
+
+  for (const item of items) {
+    if (item.crystallizedAs) continue; // Skip resolved
+    const itemNorm = item.idea.toLowerCase().replace(/[^a-z0-9\s]/g, '');
+    const matchCount = words.filter(w => itemNorm.includes(w)).length;
+    if (matchCount >= Math.ceil(words.length * 0.5)) {
+      return item;
+    }
+  }
+  return null;
+}

package/src/wave-planner.mjs

@@ -0,0 +1,294 @@
+// Wave Planner — Layer 2 cognitive loop
+// Takes HEAD's deliberation output and produces structured wave-based execution plans.
+
+const TIER_COST = {
+  search:  { tokens: 5000,  time: '~10s' },
+  execute: { tokens: 20000, time: '~45s' },
+  think:   { tokens: 15000, time: '~30s' },
+  review:  { tokens: 10000, time: '~20s' },
+};
+
+let waveCounter = 0;
+function nextWaveId() { return `w-${Date.now().toString(36)}-${++waveCounter}`; }
+
+/** Plan waves from HEAD's deliberation output. */
+export function planWaves(deliberation, context = {}) {
+  const { situation = {}, uncertainties = [], result = {} } = deliberation;
+  const { files = [], priorDebriefs = [], diagnosticPatterns = [] } = context;
+  const depth = result.depth || 'light';
+
+  const blockers = uncertainties.filter(u => u.confidence < 0.3);
+  const hasFragile = situation.risk === 'high' || situation.risk === 'critical';
+  const largeScope = situation.scope === 'large';
+  const priorBlockers = priorDebriefs.filter(d => d.blockers?.length);
+
+  const waves = [];
+  const contingencies = [];
+
+  // Determine wave structure based on depth
+  if (depth === 'reflexive' || depth === 'light') {
+    waves.push(makeSingleWave(result, situation, files));
+  } else if (depth === 'full') {
+    if (blockers.length) {
+      waves.push(makeReconWave(blockers, situation, files, priorBlockers));
+    }
+    waves.push(makeImplementWave(result, situation, files, largeScope, waves));
+    if (hasFragile) {
+      waves.push(makeVerifyWave(situation, files, waves));
+    }
+  } else if (depth === 'deep') {
+    // Always start with recon for deep
+    waves.push(makeReconWave(
+      blockers.length ? blockers : uncertainties,
+      situation, files, priorBlockers
+    ));
+    // Plan wave
+    waves.push({
+      id: nextWaveId(),
+      phase: 'synthesize',
+      agents: [{
+        tier: 'think',
+        objective: `Synthesize recon findings into implementation plan for: ${result.action || situation.taskShape || 'task'}`,
+        scope: files.slice(0, 10),
+      }],
+      dependsOn: [waves[0].id],
+      gateCondition: 'recon wave completed without escalation',
+      parallel: false,
+    });
+    // Implement wave
+    waves.push(makeImplementWave(result, situation, files, largeScope, waves));
+    // Verify wave
+    waves.push(makeVerifyWave(situation, files, waves));
+  }
+
+  // Force recon-first if blockers exist and first wave isn't recon
+  if (blockers.length && waves.length && waves[0].phase !== 'recon') {
+    const reconWave = makeReconWave(blockers, situation, files, priorBlockers);
+    waves.forEach(w => { if (!w.dependsOn.length) w.dependsOn.push(reconWave.id); });
+    waves.unshift(reconWave);
+  }
+
+  // Build contingencies
+  if (largeScope) {
+    contingencies.push({
+      trigger: 'if wave 1 finds scope is larger than expected',
+      response: 'add-wave',
+      details: 'Split implementation into additional parallel waves by file group',
+    });
+  }
+  if (hasFragile) {
+    contingencies.push({
+      trigger: 'if implementation wave introduces regressions',
+      response: 'retry-different',
+      details: 'Re-approach with smaller incremental changes',
+    });
+  }
+  if (blockers.length) {
+    contingencies.push({
+      trigger: 'if recon cannot resolve uncertainty',
+      response: 'escalate',
+      details: 'Ask user for clarification before proceeding',
+    });
+  }
+
+  const agentCount = waves.reduce((n, w) => n + w.agents.length, 0);
+  const dominantTier = agentCount <= 1 ? (waves[0]?.agents[0]?.tier || 'search')
+    : waves.flatMap(w => w.agents.map(a => a.tier))
+      .sort((a, b) => TIER_COST[b].tokens - TIER_COST[a].tokens)[0];
+
+  return {
+    waves,
+    rationale: buildRationale(depth, blockers, hasFragile, largeScope),
+    estimatedCost: { waves: waves.length, agents: agentCount, tier: dominantTier },
+    contingencies,
+  };
+}
+
+/** Decide if the remaining plan is still valid after a wave debrief. */
+export function shouldReplan(currentPlan, newDebrief) {
+  if (!newDebrief) return false;
+  if (newDebrief.scopeChange === 'larger' || newDebrief.scopeChange === 'different') return true;
+  if (newDebrief.pivotReason) return true;
+  if (newDebrief.confidence !== undefined && newDebrief.confidence < 0.4) return true;
+
+  // Check if blockers intersect with upcoming wave objectives
+  if (newDebrief.blockers?.length) {
+    const remaining = currentPlan.waves.filter(w => !w.completed);
+    for (const w of remaining) {
+      for (const agent of w.agents) {
+        for (const blocker of newDebrief.blockers) {
+          const bLower = (typeof blocker === 'string' ? blocker : blocker.description || '').toLowerCase();
+          if (bLower && agent.objective.toLowerCase().includes(bLower.split(' ')[0])) return true;
+        }
+      }
+    }
+  }
+  return false;
+}
+
+/** Produce a new plan incorporating what was learned. Preserves completed waves. */
+export function replan(currentPlan, waveSummary, originalDeliberation) {
+  const completed = currentPlan.waves.filter(w => w.completed);
+  const context = {
+    files: waveSummary.filesDiscovered || [],
+    priorDebriefs: [waveSummary],
+    diagnosticPatterns: waveSummary.patterns || [],
+  };
+
+  // Merge learning into deliberation
+  const updated = { ...originalDeliberation };
+  if (waveSummary.scopeChange === 'larger') {
+    updated.situation = { ...updated.situation, scope: 'large' };
+  }
+  if (waveSummary.confidence !== undefined) {
+    updated.result = { ...updated.result, confidence: waveSummary.confidence };
+  }
+  if (waveSummary.newUncertainties) {
+    updated.uncertainties = [
+      ...(updated.uncertainties || []),
+      ...waveSummary.newUncertainties,
+    ];
+  }
+
+  const newPlan = planWaves(updated, context);
+
+  // Preserve completed waves at the front
+  newPlan.waves = [...completed, ...newPlan.waves];
+  newPlan.rationale = `Replanned after wave debrief: ${waveSummary.pivotReason || waveSummary.scopeChange || 'confidence drop'}. ${newPlan.rationale}`;
+  return newPlan;
+}
+
+/** Rough cost estimate for a single wave. */
+export function estimateWaveCost(wave) {
+  let tokens = 0;
+  for (const agent of wave.agents) {
+    tokens += TIER_COST[agent.tier]?.tokens || 10000;
+  }
+  // Time: parallel agents overlap, sequential add up
+  const times = wave.agents.map(a => parseInt(TIER_COST[a.tier]?.time) || 20);
+  const seconds = wave.parallel ? Math.max(...times) : times.reduce((s, t) => s + t, 0);
+  return { tokens, time: `~${seconds}s` };
+}
+
+function makeSingleWave(result, situation, files) {
+  const tier = mapActionToTier(result.action);
+  return {
+    id: nextWaveId(),
+    phase: tier === 'search' ? 'recon' : 'implement',
+    agents: [{
+      tier,
+      objective: situation.explicitAsk || situation.raw || (typeof result.action === 'string' ? result.action : result.action?.mode) || 'execute task',
+      scope: files.slice(0, 5),
+    }],
+    dependsOn: [],
+    parallel: false,
+  };
+}
+
+function makeReconWave(uncertainties, situation, files, priorBlockers) {
+  const avoidApproaches = priorBlockers.flatMap(d =>
+    d.blockers?.map(b => typeof b === 'string' ? b : b.approach) || []
+  );
+
+  const agents = uncertainties.slice(0, 3).map(u => {
+    const spec = {
+      tier: 'search',
+      objective: `Resolve uncertainty: ${u.claim || u.description || 'unknown'}`,
+      scope: files.slice(0, 5),
+    };
+    if (u.wouldChangeIf) {
+      spec.conditionalPivot = { if: u.wouldChangeIf, then: 'report finding and stop' };
+    }
+    return spec;
+  });
+
+  // If no uncertainties provided, add a general recon agent
+  if (!agents.length) {
+    agents.push({
+      tier: 'search',
+      objective: `Explore scope and structure for: ${situation.taskShape || 'task'}`,
+      scope: files.slice(0, 5),
+    });
+  }
+
+  // Annotate agents to avoid prior failed approaches
+  if (avoidApproaches.length) {
+    for (const agent of agents) {
+      agent.objective += ` (avoid: ${avoidApproaches.join(', ')})`;
+    }
+  }
+
+  return {
+    id: nextWaveId(),
+    phase: 'recon',
+    agents,
+    dependsOn: [],
+    gateCondition: undefined,
+    parallel: agents.length > 1,
+  };
+}
+
+function makeImplementWave(result, situation, files, largeScope, existingWaves) {
+  const dependsOn = existingWaves.length ? [existingWaves[existingWaves.length - 1].id] : [];
+  const agents = [];
+
+  if (largeScope && files.length > 3) {
+    // Split into parallel agents by file group
+    const groupSize = Math.ceil(files.length / 3);
+    for (let i = 0; i < files.length; i += groupSize) {
+      agents.push({
+        tier: 'execute',
+        objective: result.action || `Implement changes in file group ${Math.floor(i / groupSize) + 1}`,
+        scope: files.slice(i, i + groupSize),
+      });
+    }
+  } else {
+    agents.push({
+      tier: 'execute',
+      objective: result.action || situation.taskShape || 'implement changes',
+      scope: files.slice(0, 10),
+    });
+  }
+
+  return {
+    id: nextWaveId(),
+    phase: 'implement',
+    agents,
+    dependsOn,
+    gateCondition: existingWaves.length ? 'prior wave completed successfully' : undefined,
+    parallel: agents.length > 1,
+  };
+}
+
+function makeVerifyWave(situation, files, existingWaves) {
+  const dependsOn = existingWaves.length ? [existingWaves[existingWaves.length - 1].id] : [];
+  return {
+    id: nextWaveId(),
+    phase: 'verify',
+    agents: [{
+      tier: 'review',
+      objective: `Verify changes are correct and safe${situation.risk === 'critical' ? ' — critical risk area' : ''}`,
+      scope: files.slice(0, 10),
+    }],
+    dependsOn,
+    gateCondition: 'implementation wave completed',
+    parallel: false,
+  };
+}
+
+function mapActionToTier(action) {
+  if (!action) return 'execute';
+  const a = (typeof action === 'string' ? action : `${action.type || ''} ${action.mode || ''}`).toLowerCase();
+  if (a.includes('search') || a.includes('find') || a.includes('look') || a.includes('explore')) return 'search';
+  if (a.includes('review') || a.includes('check') || a.includes('verify')) return 'review';
+  if (a.includes('think') || a.includes('plan') || a.includes('design') || a.includes('architect')) return 'think';
+  return 'execute';
+}
+
+function buildRationale(depth, blockers, hasFragile, largeScope) {
+  const parts = [`Depth: ${depth}.`];
+  if (blockers.length) parts.push(`${blockers.length} blocker(s) require recon first.`);
+  if (hasFragile) parts.push('High-risk area — verification wave added.');
+  if (largeScope) parts.push('Large scope — parallel agents where possible.');
+  return parts.join(' ');
+}