dual-brain 0.2.14 → 0.2.16

package/src/narrative.mjs

@@ -0,0 +1,169 @@
+// narrative.mjs — HEAD's running narrative: prose it writes to itself between turns.
+// Not structured data. A paragraph or two that captures where we are, what just
+// happened, what's brewing. Loaded at the top of each turn so HEAD is immediately
+// "in the song" without reconstructing from scattered JSON.
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+const STATE_DIR = join(process.cwd(), '.dualbrain');
+const NARRATIVE_FILE = join(STATE_DIR, 'narrative.md');
+const NARRATIVE_HISTORY = join(STATE_DIR, 'narrative-history.jsonl');
+
+const MAX_NARRATIVE_LENGTH = 2000;
+const MAX_HISTORY_ENTRIES = 20;
+
+/**
+ * Load the current running narrative. Returns empty string if none exists.
+ * This is meant to be injected at the top of HEAD's context each turn.
+ */
+export function load() {
+  try {
+    if (existsSync(NARRATIVE_FILE)) {
+      return readFileSync(NARRATIVE_FILE, 'utf8').trim();
+    }
+  } catch {}
+  return '';
+}
+
+/**
+ * Write a new narrative, replacing the old one.
+ * The old narrative is archived to history before overwrite.
+ *
+ * @param {string} prose - HEAD's current understanding in prose form.
+ *   Should answer: Where are we? What just happened? What's brewing?
+ *   What did the user care about? What should I not forget?
+ */
+export function write(prose) {
+  if (!prose || typeof prose !== 'string') return;
+
+  const trimmed = prose.slice(0, MAX_NARRATIVE_LENGTH).trim();
+  if (!trimmed) return;
+
+  mkdirSync(STATE_DIR, { recursive: true });
+
+  // Archive current before overwriting
+  const current = load();
+  if (current) {
+    _appendHistory(current);
+  }
+
+  writeFileSync(NARRATIVE_FILE, trimmed + '\n');
+}
+
+/**
+ * Evolve the narrative — append new observations without replacing everything.
+ * Used after dispatches return, after user says something illuminating,
+ * or after a wave completes.
+ *
+ * @param {string} addition - New prose to weave into the narrative.
+ * @param {object} opts
+ * @param {boolean} opts.replace - If true, replace entirely instead of appending.
+ */
+export function evolve(addition, { replace = false } = {}) {
+  if (!addition || typeof addition !== 'string') return;
+
+  if (replace) {
+    write(addition);
+    return;
+  }
+
+  const current = load();
+  const combined = current
+    ? current + '\n\n' + addition.trim()
+    : addition.trim();
+
+  // If too long, keep the newest portion (recency bias for immersion)
+  const final = combined.length > MAX_NARRATIVE_LENGTH
+    ? combined.slice(-MAX_NARRATIVE_LENGTH)
+    : combined;
+
+  mkdirSync(STATE_DIR, { recursive: true });
+  writeFileSync(NARRATIVE_FILE, final.trim() + '\n');
+}
+
+/**
+ * Generate a narrative excerpt suitable for a dispatch envelope.
+ * Shorter than the full narrative — just enough context for a worker
+ * to understand the "why" without the full stream of consciousness.
+ *
+ * @param {number} maxLength - Max chars for the excerpt (default 500)
+ * @returns {string}
+ */
+export function excerpt(maxLength = 500) {
+  const full = load();
+  if (!full) return '';
+  if (full.length <= maxLength) return full;
+
+  // Take the last N chars — most recent context is most relevant for workers
+  const trimmed = full.slice(-maxLength);
+  // Find the first sentence boundary to avoid mid-thought cuts
+  const firstPeriod = trimmed.indexOf('. ');
+  if (firstPeriod > 0 && firstPeriod < maxLength * 0.4) {
+    return trimmed.slice(firstPeriod + 2);
+  }
+  return trimmed;
+}
+
+/**
+ * Get recent narrative history entries (for warm memory tier).
+ * @param {number} n - Number of recent entries to retrieve
+ * @returns {Array<{ts: number, text: string}>}
+ */
+export function recentHistory(n = 5) {
+  try {
+    if (!existsSync(NARRATIVE_HISTORY)) return [];
+    const lines = readFileSync(NARRATIVE_HISTORY, 'utf8').trim().split('\n').filter(Boolean);
+    return lines.slice(-n).map(line => {
+      try { return JSON.parse(line); } catch { return null; }
+    }).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Persist the current narrative for precompact survival.
+ * Called by the precompact hook before context compression.
+ * Returns the narrative that was persisted (for confirmation).
+ */
+export function persist() {
+  const current = load();
+  if (!current) return '';
+  // Narrative is already on disk — this just ensures it's fresh
+  // and archives a snapshot with explicit "precompact" marker
+  _appendHistory(current, { reason: 'precompact' });
+  return current;
+}
+
+/**
+ * Clear the narrative (used in testing or session reset).
+ */
+export function clear() {
+  try {
+    if (existsSync(NARRATIVE_FILE)) {
+      writeFileSync(NARRATIVE_FILE, '');
+    }
+  } catch {}
+}
+
+// ── Internal ──────────────────────────────────────────────────────────────────
+
+function _appendHistory(text, meta = {}) {
+  try {
+    const entry = JSON.stringify({ ts: Date.now(), text: text.slice(0, 800), ...meta });
+    mkdirSync(STATE_DIR, { recursive: true });
+
+    // Cap history file
+    let existing = '';
+    if (existsSync(NARRATIVE_HISTORY)) {
+      existing = readFileSync(NARRATIVE_HISTORY, 'utf8');
+      const lines = existing.trim().split('\n').filter(Boolean);
+      if (lines.length >= MAX_HISTORY_ENTRIES) {
+        existing = lines.slice(-MAX_HISTORY_ENTRIES + 1).join('\n') + '\n';
+      }
+    }
+
+    writeFileSync(NARRATIVE_HISTORY, existing + entry + '\n');
+  } catch {}
+}

package/src/predictive.mjs

@@ -0,0 +1,250 @@
+/** Predictive Dispatch — Layer 3: anticipates failure modes BEFORE dispatching. */
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { join } from 'path';
+
+const DIAG_DIR = join(process.cwd(), '.dualbrain', 'diagnostic');
+const STATE_PATH = join(DIAG_DIR, 'current.json');
+const WEIGHTS_PATH = join(DIAG_DIR, 'pattern-weights.json');
+
+export function loadSessionPatterns() {
+  const empty = { frequencies: [], avgSeverity: 0, precedingTools: {}, timeTrends: [] };
+  if (!existsSync(STATE_PATH)) return empty;
+
+  let state;
+  try { state = JSON.parse(readFileSync(STATE_PATH, 'utf8')); }
+  catch { return empty; }
+
+  const noticings = state.noticings || [];
+  if (!noticings.length) return empty;
+
+  const counts = {};
+  const severityMap = { low: 1, medium: 2, high: 3 };
+  let totalSeverity = 0;
+  for (const n of noticings) {
+    counts[n.type] = (counts[n.type] || 0) + 1;
+    totalSeverity += severityMap[n.severity] || 1;
+  }
+  const frequencies = Object.entries(counts)
+    .map(([type, count]) => ({ type, count }))
+    .sort((a, b) => b.count - a.count);
+
+  const toolCalls = state.toolCalls || [];
+  const precedingTools = {};
+  for (const n of noticings) {
+    const before = toolCalls.filter(tc => tc.ts < n.ts).slice(-3).map(tc => tc.tool);
+    if (!precedingTools[n.type]) precedingTools[n.type] = [];
+    precedingTools[n.type].push(...before);
+  }
+
+  const sessionStart = state.startedAt || noticings[0]?.ts || 0;
+  const sessionEnd = state.lastActivity || noticings[noticings.length - 1]?.ts || Date.now();
+  const duration = sessionEnd - sessionStart || 1;
+  const timeTrends = noticings.map(n => ({
+    type: n.type, position: (n.ts - sessionStart) / duration,
+  }));
+
+  return { frequencies, avgSeverity: totalSeverity / noticings.length, precedingTools, timeTrends };
+}
+
+function loadWeights() {
+  if (!existsSync(WEIGHTS_PATH)) return {};
+  try { return JSON.parse(readFileSync(WEIGHTS_PATH, 'utf8')); }
+  catch { return {}; }
+}
+
+export function predictFailureModes(agentSpec, context = {}) {
+  const predictions = [];
+  const patterns = context.patterns || loadSessionPatterns();
+  const weights = loadWeights();
+  const objective = agentSpec.objective || '';
+  const scope = agentSpec.scope || {};
+  const files = scope.files || [];
+  const tier = agentSpec.tier || '';
+  const priorFailures = context.priorFailures || [];
+  const activeWaves = context.activeWaves || [];
+  const lastReadAge = context.lastReadAge || 0; // ms
+
+  const applyWeight = (mode, base) => {
+    const w = weights[mode];
+    if (!w) return base;
+    // Shift likelihood based on historical accuracy
+    return Math.min(1, Math.max(0, base + (w.accuracy - 0.5) * 0.3));
+  };
+
+  // scope-explosion
+  const multiTarget = files.length > 3 || /\band\b|multiple|several|all/i.test(objective);
+  const priorScopeCreep = patterns.frequencies.some(f => f.type === 'scope-creep' && f.count >= 2);
+  if (multiTarget || priorScopeCreep) {
+    const base = multiTarget && priorScopeCreep ? 0.8 : 0.7;
+    predictions.push({
+      mode: 'scope-explosion',
+      likelihood: applyWeight('scope-explosion', base),
+      basis: multiTarget
+        ? `Objective references ${files.length || 'multiple'} targets`
+        : 'Prior waves encountered scope creep',
+      prevention: `If scope grows beyond ${Math.max(files.length, 3)} files, STOP and report back rather than continuing.`,
+    });
+  }
+
+  // missing-context
+  const noFiles = files.length === 0;
+  const executeWithoutSearch = tier === 'execute' && !(context.priorSearchWave);
+  if (noFiles || executeWithoutSearch) {
+    const base = 0.6;
+    predictions.push({
+      mode: 'missing-context',
+      likelihood: applyWeight('missing-context', base),
+      basis: noFiles
+        ? 'No files specified in scope — agent may waste tokens searching'
+        : 'Execute tier dispatched without prior search wave',
+      prevention: `Read the current state of target files before making changes. If unsure what to modify, list candidates first.`,
+    });
+  }
+
+  // wrong-approach
+  const hasStuckLoop = patterns.frequencies.some(f => f.type === 'stuck-loop' && f.count >= 2);
+  const objectiveFailed = priorFailures.some(f =>
+    f.objective && objective.toLowerCase().includes(f.objective.toLowerCase().slice(0, 20))
+  );
+  if (hasStuckLoop || objectiveFailed) {
+    const base = objectiveFailed ? 0.8 : 0.6;
+    predictions.push({
+      mode: 'wrong-approach',
+      likelihood: applyWeight('wrong-approach', base),
+      basis: objectiveFailed
+        ? 'Prior attempt at this objective failed'
+        : 'Diagnostic shows stuck-loop pattern in session',
+      prevention: `Try a fundamentally different approach than previous attempts. If stuck after 2 tries, report back with what was tried.`,
+    });
+  }
+
+  // blocked-dependency
+  const refsOtherWave = activeWaves.some(w =>
+    objective.toLowerCase().includes(w.output?.toLowerCase()?.slice(0, 20) || '___none')
+  );
+  if (refsOtherWave) {
+    predictions.push({
+      mode: 'blocked-dependency',
+      likelihood: applyWeight('blocked-dependency', 0.5),
+      basis: 'Objective references output from an in-progress wave',
+      prevention: `If blocked by a dependency from another wave, pivot to independent work or report the blocker.`,
+    });
+  }
+
+  // stale-assumption
+  if (lastReadAge > 5 * 60 * 1000 && files.length > 0) {
+    predictions.push({
+      mode: 'stale-assumption',
+      likelihood: applyWeight('stale-assumption', 0.4),
+      basis: `Files in scope were last read ${Math.round(lastReadAge / 60000)}m ago — may have changed`,
+      prevention: `Re-read ${files.slice(0, 3).join(', ')} before assuming current state.`,
+    });
+  }
+
+  return predictions;
+}
+
+export function generatePreventions(predictions) {
+  const actionable = predictions
+    .filter(p => p.likelihood >= 0.4)
+    .sort((a, b) => b.likelihood - a.likelihood)
+    .slice(0, 5);
+
+  if (!actionable.length) return '';
+
+  const lines = actionable.map(p => `- [${p.prevention}]`);
+  return `⚠ Pre-flight awareness:\n${lines.join('\n')}`;
+}
+
+export function scoreDispatchReadiness(agentSpec, wavePlan = {}, predictions = []) {
+  const blockers = [];
+  const warnings = [];
+  let score = 1.0;
+
+  const files = agentSpec.scope?.files || [];
+  const priorSearch = wavePlan.completedSearchWave || false;
+  const hasContext = files.length > 0 || priorSearch;
+
+  // Scope researched?
+  if (!hasContext) {
+    blockers.push('No files in scope and no prior search wave — context unknown');
+    score -= 0.3;
+  }
+
+  // High-likelihood predictions
+  const highRisk = predictions.filter(p => p.likelihood >= 0.7);
+  const medRisk = predictions.filter(p => p.likelihood >= 0.4 && p.likelihood < 0.7);
+
+  for (const p of highRisk) {
+    blockers.push(`High-risk: ${p.mode} (${Math.round(p.likelihood * 100)}%) — ${p.basis}`);
+    score -= 0.25;
+  }
+  for (const p of medRisk) {
+    warnings.push(`${p.mode} (${Math.round(p.likelihood * 100)}%) — ${p.basis}`);
+    score -= 0.1;
+  }
+
+  // Unresolved blockers from prior waves
+  const unresolvedBlockers = wavePlan.unresolvedBlockers || [];
+  for (const b of unresolvedBlockers) {
+    blockers.push(`Unresolved from prior wave: ${b}`);
+    score -= 0.2;
+  }
+
+  score = Math.max(0, Math.min(1, score));
+  const ready = score >= 0.5 && blockers.length === 0;
+
+  let suggestion = '';
+  if (!ready) {
+    if (blockers.some(b => b.includes('context unknown'))) {
+      suggestion = 'Run a search/read wave first to establish context before executing.';
+    } else if (highRisk.length) {
+      suggestion = `Address high-risk predictions: ${highRisk.map(p => p.mode).join(', ')}. Add preventions to prompt or restructure scope.`;
+    } else {
+      suggestion = 'Resolve listed blockers before dispatching.';
+    }
+  }
+
+  return { ready, score, blockers, warnings, suggestion };
+}
+
+export function evolvePatterns(newDebrief, predictions) {
+  const weights = loadWeights();
+
+  for (const pred of predictions) {
+    if (!weights[pred.mode]) {
+      weights[pred.mode] = { correct: 0, incorrect: 0, accuracy: 0.5 };
+    }
+
+    const w = weights[pred.mode];
+    const occurred = debriefContainsPattern(newDebrief, pred.mode);
+
+    if (occurred && pred.likelihood >= 0.4) {
+      w.correct++;
+    } else if (!occurred && pred.likelihood >= 0.4) {
+      w.incorrect++;
+    } else if (occurred && pred.likelihood < 0.4) {
+      // Missed prediction — we should have predicted higher
+      w.incorrect++;
+    }
+
+    const total = w.correct + w.incorrect;
+    w.accuracy = total > 0 ? w.correct / total : 0.5;
+  }
+
+  mkdirSync(DIAG_DIR, { recursive: true });
+  writeFileSync(WEIGHTS_PATH, JSON.stringify(weights, null, 2));
+}
+
+function debriefContainsPattern(debrief, mode) {
+  if (!debrief) return false;
+  const modeMap = {
+    'scope-explosion': ['scope-creep', 'scope_explosion', 'expanded'],
+    'missing-context': ['missing-context', 'no_context', 'searched'],
+    'wrong-approach': ['stuck-loop', 'wrong_approach', 'retry'],
+    'blocked-dependency': ['blocked', 'dependency', 'waiting'],
+    'stale-assumption': ['stale', 'outdated', 'changed'],
+  };
+  const text = JSON.stringify([...(debrief.issues || []), ...(debrief.patterns || [])]).toLowerCase();
+  return (modeMap[mode] || [mode]).some(k => text.includes(k));
+}

package/src/provider-context.mjs

@@ -102,7 +102,7 @@ export function buildSurvivalBlock(provider, state) {
 /**
  * Generate a handoff receipt that works for both providers.
  * Accounts for Codex's lack of native resume support by writing
- * to a shared .dual-brain/handoffs/ directory that both providers can read.
+ * to a shared .dualbrain/handoffs/ directory that both providers can read.
  */
 export function generateProviderHandoff(sessionState, provider) {
   const caps = getProviderCaps(provider);
@@ -136,7 +136,7 @@ export function generateProviderHandoff(sessionState, provider) {
  * Codex gets a more verbose brief since it has no native session memory.
  */
 export function buildProviderResumeBrief(cwd, targetProvider) {
-  const dir = join(cwd || process.cwd(), '.dual-brain', 'handoffs');
+  const dir = join(cwd || process.cwd(), '.dualbrain', 'handoffs');
   if (!existsSync(dir)) return null;
 
   const files = readdirSync(dir)

package/src/receipt.mjs

@@ -111,7 +111,7 @@ export function formatFailureReceipt(receipt, failureContext) {
 
 // ─── Persistent session receipt ──────────────────────────────────────────────
 
-const RECEIPTS_DIR = '.dual-brain/receipts';
+const RECEIPTS_DIR = '.dualbrain/receipts';
 
 function receiptsDir(cwd) {
   return join(cwd, RECEIPTS_DIR);
@@ -130,7 +130,7 @@ function gitChangedFiles(cwd) {
 
 function readDecisionsRecent(cwd, limit = 5) {
   try {
-    const raw = readFileSync(join(cwd, '.dual-brain', 'decisions.jsonl'), 'utf8');
+    const raw = readFileSync(join(cwd, '.dualbrain', 'decisions.jsonl'), 'utf8');
     const lines = raw.split('\n').filter(l => l.trim());
     return lines.slice(-limit).map(l => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
   } catch {

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();
+}