dual-brain 0.2.14 → 0.2.16

package/src/head.mjs

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
-import { readDiagnosticNoticings } from '../.claude/hooks/diagnostic-companion.mjs';
+import { readDiagnosticNoticings } from '../hooks/diagnostic-companion.mjs';
 
 const STATE_DIR = join(process.cwd(), '.dualbrain');
 const STATE_FILE = join(STATE_DIR, 'head-state.json');
@@ -63,9 +63,14 @@ export function assessDepth(signals) {
     score += (LEVEL_SCORES[level] || 0) * cfg.weight;
   }
 
-  if (score <= 4)  return 'reflexive';
-  if (score <= 12) return 'light';
-  if (score <= 22) return 'full';
+  // Task type floor: work requests are never reflexive
+  const taskType = signals.taskShape?.type || signals.type;
+  const isWorkRequest = ['edit', 'debug', 'review', 'research'].includes(taskType);
+  if (isWorkRequest && score < 3) score = 3;
+
+  if (score <= 2)  return 'reflexive';
+  if (score <= 8)  return 'light';
+  if (score <= 18) return 'full';
   return 'deep';
 }
 
@@ -124,7 +129,9 @@ function _inferTaskShape(message, context) {
   const lower = message.toLowerCase();
 
   // Scope: how big is this?
-  const fileCount = context.files?.length || 0;
+  const files = context.files || [];
+  const dirCount = files.filter(f => f.endsWith('/') || !f.includes('.')).length;
+  const fileCount = files.length + (dirCount * 4); // directories imply multiple files
   const scope = fileCount > 5 ? 'large' : fileCount > 2 ? 'medium' : lower.length > 500 ? 'medium' : 'small';
 
   // Risk: what could go wrong?
@@ -149,7 +156,9 @@ function _inferTaskShape(message, context) {
   if (/\b(maybe|might|could|should we|not sure|thinking about|what if|somehow)\b/i.test(message)) ambiguitySignals.push('hedging-language');
   if (/\b(or|versus|vs|either|option|alternative)\b/i.test(message)) ambiguitySignals.push('considering-alternatives');
   if (message.split('?').length > 2) ambiguitySignals.push('multiple-questions');
-  if (!context.files?.length && /\b(it|this|that|these|those)\b/i.test(message) && !context.recentFiles?.length) ambiguitySignals.push('vague-reference');
+  if (!context.files?.length && /\b(it|this|that|these|those)\b/i.test(message) && !context.recentFiles?.length && !/\?\s*$/.test(message.trim())) ambiguitySignals.push('vague-reference');
+  if (/\b(everything|all|entire|whole|every)\b/i.test(message)) ambiguitySignals.push('unbounded-scope');
+  if (/\b(better|improve|enhance|optimize|clean up)\b/i.test(message) && !context.files?.length) ambiguitySignals.push('vague-goal');
 
   const ambiguity = ambiguitySignals.length >= 2 ? 'high' : ambiguitySignals.length >= 1 ? 'medium' : 'low';
 
@@ -251,78 +260,32 @@ function _assessRelationship(message, context, taskShape) {
  * and what would change HEAD's mind.
  */
 export function assessUncertainty(situation, context = {}) {
-  const ledger = [];
-
-  // Scope certainty
-  if (situation.taskShape.scope !== 'small') {
-    ledger.push({
-      claim: 'The change is contained to the identified files',
-      confidence: situation.material.touchedFiles.length > 0 ? 0.7 : 0.3,
-      basis: situation.material.touchedFiles.length > 0
-        ? `${situation.material.touchedFiles.length} files identified`
-        : 'No files explicitly identified — scope unknown',
-      wouldChangeIf: 'Dependency analysis reveals cross-cutting concerns',
-    });
-  }
-
-  // Risk assessment certainty
-  if (situation.taskShape.risk !== 'low') {
-    ledger.push({
-      claim: `Risk level is ${situation.taskShape.risk}`,
-      confidence: situation.taskShape.riskSignals.length >= 2 ? 0.85 : 0.6,
-      basis: `Signals: ${situation.taskShape.riskSignals.join(', ') || 'none'}`,
-      wouldChangeIf: 'Closer inspection reveals the risky-looking code is actually isolated/tested',
-    });
-  }
-
-  // Goal understanding certainty
-  if (situation.inferredGoal) {
-    ledger.push({
-      claim: 'I understand what the user actually needs',
-      confidence: 0.5,
-      basis: `Explicit: "${situation.explicitAsk.slice(0, 80)}" but inferred: "${situation.inferredGoal}"`,
-      wouldChangeIf: 'User clarifies their actual goal',
-    });
-  } else if (situation.taskShape.ambiguity === 'high') {
-    ledger.push({
-      claim: 'I understand the request',
-      confidence: 0.4,
-      basis: `Ambiguity signals: ${situation.taskShape.ambiguitySignals.join(', ')}`,
-      wouldChangeIf: 'User provides more specific criteria or constraints',
-    });
-  }
-
-  // Prior failure uncertainty
-  if (situation.priorFailures >= 1) {
-    ledger.push({
-      claim: 'The same approach will work this time',
-      confidence: Math.max(0.1, 0.8 - (situation.priorFailures * 0.25)),
-      basis: `${situation.priorFailures} prior failure(s) on similar task`,
-      wouldChangeIf: 'A fundamentally different approach is tried',
-    });
-  }
-
-  // Material safety
-  if (situation.material.fragileAreas.length > 0) {
-    ledger.push({
-      claim: 'Changes won\'t break existing functionality',
-      confidence: 0.5,
-      basis: `Fragile areas: ${situation.material.fragileAreas.map(a => a.file).join(', ')}`,
-      wouldChangeIf: 'Tests exist and pass for the affected areas',
-    });
-  }
-
-  // Context freshness
-  if (context.contextAge === 'stale') {
-    ledger.push({
-      claim: 'My understanding of the codebase is current',
-      confidence: 0.3,
-      basis: 'Context may be outdated — files could have changed since last read',
-      wouldChangeIf: 'Fresh file reads confirm current state',
-    });
-  }
-
-  return ledger;
+  let score = 0.8; // default: reasonably confident
+  let blocker = null;
+  let shouldVerify = false;
+
+  // Confidence drops
+  if (situation.taskShape.ambiguity === 'high') score -= 0.3;
+  else if (situation.taskShape.ambiguity === 'medium') score -= 0.1;
+
+  if (situation.priorFailures >= 2) { score -= 0.3; blocker = 'Repeated failures suggest wrong approach'; }
+  else if (situation.priorFailures >= 1) score -= 0.15;
+
+  if (situation.material.fragileAreas.length > 0) { score -= 0.15; shouldVerify = true; }
+  if (situation.taskShape.scope === 'large') { score -= 0.1; shouldVerify = true; }
+  if (!situation.material.touchedFiles.length && situation.taskShape.type === 'edit') { score -= 0.2; blocker = blocker || 'No files identified for edit task'; }
+  if (context.contextAge === 'stale') score -= 0.2;
+  if (situation.inferredGoal) score -= 0.15;
+
+  score = Math.max(0.1, Math.min(1.0, score));
+
+  // Return same interface summarizeConfidence produces (so callers don't break)
+  return [{
+    claim: blocker || 'Task assessment',
+    confidence: score,
+    basis: `score=${score.toFixed(2)}`,
+    wouldChangeIf: blocker ? 'Different approach tried' : 'n/a',
+  }];
 }
 
 /**
@@ -399,6 +362,30 @@ export function deriveObligations(situation) {
   return active;
 }
 
+// ── Turn history query ────────────────────────────────────────────────────────
+
+export function queryRecentTurns(state, n = 3) {
+  if (!state.turns?.length) return { count: 0, lastActions: [], failureStreak: 0, sameActionCount: 0 };
+
+  const recent = state.turns.slice(-n);
+  const lastActions = recent.map(t => t.action);
+
+  // Detect same action repeated
+  const lastAction = lastActions[lastActions.length - 1];
+  const sameActionCount = lastActions.filter(a => a === lastAction).length;
+
+  // Detect failure streak (low confidence runs)
+  const failureStreak = [...recent].reverse().findIndex(t => t.confidence > 0.6);
+
+  return {
+    count: state.turns.length,
+    lastActions,
+    failureStreak: failureStreak === -1 ? recent.length : failureStreak,
+    sameActionCount,
+    avgConfidence: recent.reduce((s, t) => s + (t.confidence || 0), 0) / recent.length,
+  };
+}
+
 // ── Noticings: what HEAD observes passively ─────────────────────────────────
 
 /**
@@ -409,6 +396,25 @@ export function deriveObligations(situation) {
 export function notice(situation, state, context = {}) {
   const noticings = [];
 
+  // Self-awareness: detect stuck patterns from turn history
+  const turnHistory = queryRecentTurns(state);
+  if (turnHistory.sameActionCount >= 3) {
+    noticings.push({
+      type: 'self-awareness',
+      severity: 'high',
+      observation: `Same action "${turnHistory.lastActions[turnHistory.lastActions.length-1]}" repeated ${turnHistory.sameActionCount} times — may be stuck`,
+      shouldSurface: true,
+    });
+  }
+  if (turnHistory.failureStreak >= 2) {
+    noticings.push({
+      type: 'self-awareness',
+      severity: 'medium',
+      observation: `${turnHistory.failureStreak} turns with low confidence — consider changing approach`,
+      shouldSurface: true,
+    });
+  }
+
   // Drift: are we doing something different from what was discussed?
   if (state.declaredGoal && situation.inferredGoal && state.declaredGoal !== situation.inferredGoal) {
     noticings.push({
@@ -485,6 +491,20 @@ export function notice(situation, state, context = {}) {
   }
 
 
+  // Self-awareness: detect repeated dispatch failures
+  if (state.dispatches?.length >= 2) {
+    const recent = state.dispatches.slice(-3);
+    const failures = recent.filter(d => d.outcome === 'failure');
+    if (failures.length >= 2) {
+      noticings.push({
+        type: 'self-awareness',
+        severity: 'high',
+        observation: `${failures.length} of last ${recent.length} dispatches failed — approach may need to change`,
+        shouldSurface: true,
+      });
+    }
+  }
+
   // Diagnostic companion: feed tool-call pattern observations into deliberation
   try {
     const diagnosticNoticings = readDiagnosticNoticings();
@@ -791,6 +811,7 @@ export function freshState() {
     declaredGoal: null,
     originalScope: null,
     turns: [],
+    dispatches: [],  // { ts, type, objective, outcome, durationMs }
     contextEstimate: { messages: 0, estimatedTokens: 0 },
     lastActivity: Date.now(),
     created: Date.now(),
@@ -803,8 +824,22 @@ export function saveState(state) {
   writeFileSync(STATE_FILE, JSON.stringify(state, null, 2));
 }
 
+export function recordDispatchOutcome(state, outcome) {
+  if (!state.dispatches) state.dispatches = [];
+  state.dispatches.push({
+    ts: Date.now(),
+    type: outcome.type || 'unknown',
+    objective: (outcome.objective || '').slice(0, 100),
+    outcome: outcome.status || 'unknown', // 'success' | 'failure' | 'partial'
+    durationMs: outcome.durationMs || 0,
+  });
+  // Keep last 10 dispatches only
+  if (state.dispatches.length > 10) state.dispatches = state.dispatches.slice(-10);
+  saveState(state);
+}
+
 // ── Exports ─────────────────────────────────────────────────────────────────
 // Core pipeline: perceive, assessUncertainty, deriveObligations, notice, deliberate
-// Convenience: processTurn, assessDepth, summarizeConfidence
+// Convenience: processTurn, assessDepth, summarizeConfidence, queryRecentTurns
 // State: loadState, freshState, saveState
 // Values: HEAD_VALUES

package/src/inbox.mjs

@@ -0,0 +1,195 @@
+/**
+ * inbox.mjs — Cross-session signal system for dual-brain orchestrator
+ *
+ * Agents write messages to .dualbrain/inbox/. HEAD and the cognitive loop
+ * check the inbox at entry points. Messages have TTL and recipient types.
+ */
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+const INBOX_DIR = join(process.cwd(), '.dualbrain', 'inbox');
+const INDEX_PATH = join(INBOX_DIR, '_index.json');
+const DEFAULT_TTL = 24 * 60 * 60 * 1000; // 24h
+const MAX_ACTIVE = 50;
+const PRIORITY_ORDER = { critical: 0, high: 1, medium: 2, low: 3 };
+
+function ensureDir() {
+  if (!existsSync(INBOX_DIR)) mkdirSync(INBOX_DIR, { recursive: true });
+}
+
+function readIndex() {
+  try {
+    if (existsSync(INDEX_PATH)) return JSON.parse(readFileSync(INDEX_PATH, 'utf8'));
+  } catch { /* rebuild */ }
+  return rebuildIndex();
+}
+
+function rebuildIndex() {
+  ensureDir();
+  const entries = [];
+  for (const f of readdirSync(INBOX_DIR)) {
+    if (f === '_index.json' || !f.endsWith('.json')) continue;
+    try {
+      const msg = JSON.parse(readFileSync(join(INBOX_DIR, f), 'utf8'));
+      entries.push({ id: msg.id, to: msg.to, type: msg.type, priority: msg.priority, createdAt: msg.createdAt, expired: Date.now() > msg.createdAt + msg.ttl });
+    } catch { /* skip corrupt */ }
+  }
+  writeFileSync(INDEX_PATH, JSON.stringify(entries, null, 2));
+  return entries;
+}
+
+function writeIndex(entries) {
+  ensureDir();
+  writeFileSync(INDEX_PATH, JSON.stringify(entries, null, 2));
+}
+
+function readMessage(id) {
+  try {
+    return JSON.parse(readFileSync(join(INBOX_DIR, `${id}.json`), 'utf8'));
+  } catch { return null; }
+}
+
+function matchesRecipient(msgTo, recipient) {
+  if (msgTo === 'all' || msgTo === recipient) return true;
+  if (msgTo === 'worker:*' && recipient.startsWith('worker:')) return true;
+  return false;
+}
+
+/** Write a message to the inbox. */
+export function send(partial) {
+  if (!partial.to || !partial.type || !partial.subject || !partial.body) {
+    throw new Error('inbox.send requires: to, type, subject, body');
+  }
+  ensureDir();
+  const msg = {
+    id: randomUUID(),
+    from: partial.from || 'system',
+    to: partial.to,
+    type: partial.type,
+    priority: partial.priority || 'medium',
+    subject: partial.subject,
+    body: partial.body,
+    ttl: partial.ttl ?? DEFAULT_TTL,
+    createdAt: Date.now(),
+    readBy: partial.readBy || [],
+    relatedFiles: partial.relatedFiles || [],
+    tags: partial.tags || [],
+  };
+  // Enforce cap — purge oldest if over limit
+  const index = readIndex();
+  const active = index.filter(e => !e.expired);
+  if (active.length >= MAX_ACTIVE) {
+    const sorted = [...active].sort((a, b) => a.createdAt - b.createdAt);
+    const toRemove = sorted.slice(0, active.length - MAX_ACTIVE + 1);
+    for (const e of toRemove) {
+      try { unlinkSync(join(INBOX_DIR, `${e.id}.json`)); } catch { /* ok */ }
+    }
+    const removeIds = new Set(toRemove.map(e => e.id));
+    const trimmed = index.filter(e => !removeIds.has(e.id));
+    trimmed.push({ id: msg.id, to: msg.to, type: msg.type, priority: msg.priority, createdAt: msg.createdAt, expired: false });
+    writeIndex(trimmed);
+  } else {
+    index.push({ id: msg.id, to: msg.to, type: msg.type, priority: msg.priority, createdAt: msg.createdAt, expired: false });
+    writeIndex(index);
+  }
+  writeFileSync(join(INBOX_DIR, `${msg.id}.json`), JSON.stringify(msg, null, 2));
+  return msg;
+}
+
+/** Read messages for a recipient. */
+export function check(recipient, options = {}) {
+  const { unreadOnly = false, types, minPriority, limit } = options;
+  const index = readIndex();
+  const now = Date.now();
+  const minP = minPriority ? PRIORITY_ORDER[minPriority] ?? 3 : 3;
+  let results = [];
+  for (const entry of index) {
+    if (now > entry.createdAt + DEFAULT_TTL) continue; // rough TTL check
+    if (!matchesRecipient(entry.to, recipient)) continue;
+    if (types && !types.includes(entry.type)) continue;
+    if ((PRIORITY_ORDER[entry.priority] ?? 3) > minP) continue;
+    const msg = readMessage(entry.id);
+    if (!msg) continue;
+    if (now > msg.createdAt + msg.ttl) continue; // precise TTL
+    if (unreadOnly && msg.readBy.includes(recipient)) continue;
+    results.push(msg);
+  }
+  results.sort((a, b) => (PRIORITY_ORDER[a.priority] ?? 3) - (PRIORITY_ORDER[b.priority] ?? 3) || b.createdAt - a.createdAt);
+  if (limit) results = results.slice(0, limit);
+  return results;
+}
+
+/** Mark a message as read by a specific reader. */
+export function markRead(messageId, reader) {
+  const path = join(INBOX_DIR, `${messageId}.json`);
+  const msg = readMessage(messageId);
+  if (!msg) return;
+  if (!msg.readBy.includes(reader)) {
+    msg.readBy.push(reader);
+    writeFileSync(path, JSON.stringify(msg, null, 2));
+  }
+}
+
+/** Clean up expired and fully-read messages. */
+export function purge(options = {}) {
+  const { purgeRead = false } = options;
+  const index = readIndex();
+  const now = Date.now();
+  let expired = 0, read = 0;
+  const keep = [];
+  for (const entry of index) {
+    const msg = readMessage(entry.id);
+    if (!msg) continue;
+    if (now > msg.createdAt + msg.ttl) {
+      try { unlinkSync(join(INBOX_DIR, `${entry.id}.json`)); } catch { /* ok */ }
+      expired++;
+      continue;
+    }
+    if (purgeRead && msg.readBy.length > 0 && msg.to !== 'all') {
+      try { unlinkSync(join(INBOX_DIR, `${entry.id}.json`)); } catch { /* ok */ }
+      read++;
+      continue;
+    }
+    keep.push(entry);
+  }
+  writeIndex(keep);
+  return { expired, read };
+}
+
+/** Produce a concise text summary for prompt injection. */
+export function generateInboxBrief(recipient) {
+  const msgs = check(recipient, { unreadOnly: true, limit: 5 });
+  if (!msgs.length) return '';
+  const lines = [`\u{1F4EC} Inbox (${msgs.length} unread):`];
+  let len = lines[0].length;
+  for (const m of msgs) {
+    const line = `• [${m.priority}] ${m.from !== 'system' ? `From ${m.from}: ` : ''}${m.subject}`;
+    if (len + line.length > 480) { lines.push('• ...'); break; }
+    lines.push(line);
+    len += line.length;
+  }
+  return lines.join('\n');
+}
+
+/** Convenience: send a continuation message when session ends. */
+export function sendContinuation(context) {
+  return send({
+    from: context.from || 'head',
+    to: 'session:next',
+    type: 'continuation',
+    priority: 'high',
+    subject: context.subject || 'Session continuation state',
+    body: typeof context.body === 'string' ? context.body : JSON.stringify(context.state || context, null, 2),
+    relatedFiles: context.relatedFiles || [],
+    tags: ['continuation', ...(context.tags || [])],
+    ttl: context.ttl ?? DEFAULT_TTL * 3, // 72h for continuations
+  });
+}
+
+/** Convenience: check for the most recent unread continuation. */
+export function checkContinuation(reader = 'head') {
+  const msgs = check('session:next', { unreadOnly: true, types: ['continuation'], limit: 1 });
+  return msgs.length ? msgs[0] : null;
+}

package/src/ledger.mjs

@@ -3,7 +3,7 @@
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
 import { join } from 'path';
 
-const LEDGER_PATH = '.dual-brain/ledger.jsonl';
+const LEDGER_PATH = '.dualbrain/ledger.jsonl';
 
 function ledgerPath(cwd) {
   return join(cwd || process.cwd(), LEDGER_PATH);
@@ -19,7 +19,7 @@ function readAllEntries(cwd) {
 
 function appendEntry(entry, cwd) {
   const p = ledgerPath(cwd);
-  mkdirSync(join(cwd || process.cwd(), '.dual-brain'), { recursive: true });
+  mkdirSync(join(cwd || process.cwd(), '.dualbrain'), { recursive: true });
   writeFileSync(p, JSON.stringify(entry) + '\n', { flag: 'a' });
 }
 

package/src/living-docs.mjs

@@ -1,11 +1,11 @@
-// living-docs.mjs — Living document system for .dual-brain/.
+// living-docs.mjs — Living document system for .dualbrain/.
 // Manages project.json, vision.md, roadmap.md, state.md, actions.jsonl, decisions.jsonl, checkpoints.jsonl.
 
 import { readFileSync, writeFileSync, appendFileSync, mkdirSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { execSync } from 'node:child_process';
 
-const DIR = '.dual-brain';
+const DIR = '.dualbrain';
 
 function docsDir(cwd = process.cwd()) {
   return join(cwd, DIR);

package/src/memory-tiers.mjs

@@ -0,0 +1,193 @@
+// memory-tiers.mjs — Hot/Warm/Cold memory with active paging.
+//
+// Hot: loaded every turn (narrative + active simmer). Always in HEAD's context.
+// Warm: loaded on demand (recent debriefs, narrative history, relevant past decisions).
+// Cold: past sessions, archived patterns. Only retrieved when explicitly needed.
+//
+// The paging mechanism: HEAD doesn't decide what to load — this module does,
+// based on what the current situation seems to need.
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import * as narrative from './narrative.mjs';
+import * as simmer from './simmer.mjs';
+
+const STATE_DIR = join(process.cwd(), '.dualbrain');
+
+/**
+ * @typedef {object} MemoryContext
+ * @property {string} narrative - Current running narrative
+ * @property {string} simmerBrief - What's brewing
+ * @property {Array} warmItems - Paged-in warm memory items
+ * @property {string} combined - Single string ready to inject into HEAD's context
+ */
+
+/**
+ * Load hot memory — always returned, every turn.
+ * This is the minimum context HEAD needs to be "in the song."
+ *
+ * @returns {{narrative: string, simmerBrief: string, combined: string}}
+ */
+export function loadHot() {
+  const narr = narrative.load();
+  const simmering = simmer.brief();
+
+  const parts = [];
+  if (narr) parts.push(narr);
+  if (simmering) parts.push(`[Simmering]\n${simmering}`);
+
+  return {
+    narrative: narr,
+    simmerBrief: simmering,
+    combined: parts.join('\n\n'),
+  };
+}
+
+/**
+ * Load warm memory — contextually relevant items paged in based on signals.
+ *
+ * @param {object} signals - What the current turn is about
+ * @param {string} signals.userMessage - The user's message
+ * @param {string[]} signals.files - Files being discussed
+ * @param {string} signals.intent - Detected intent (from HEAD's perception)
+ * @returns {Array<{source: string, content: string}>}
+ */
+export function loadWarm(signals = {}) {
+  const items = [];
+
+  // Recent narrative history if we're resuming or context feels thin
+  if (_looksLikeResume(signals.userMessage) || !narrative.load()) {
+    const history = narrative.recentHistory(3);
+    if (history.length > 0) {
+      items.push({
+        source: 'narrative-history',
+        content: history.map(h => h.text).join('\n---\n'),
+      });
+    }
+  }
+
+  // Recent debriefs if we're continuing dispatch work
+  if (signals.intent === 'dispatch' || signals.intent === 'proceed') {
+    const debriefs = _loadRecentDebriefs(3);
+    if (debriefs.length > 0) {
+      items.push({
+        source: 'recent-debriefs',
+        content: debriefs.map(d => `[${d.status}] ${d.objective || d.summary || ''}`).join('\n'),
+      });
+    }
+  }
+
+  // Routing decisions if making a new routing choice
+  if (signals.intent === 'route' || signals.intent === 'dispatch') {
+    const decisions = _loadRecentDecisions(5);
+    if (decisions.length > 0) {
+      items.push({
+        source: 'routing-history',
+        content: decisions.map(d => `${d.provider}/${d.model}: ${d.reason || ''}`).join('\n'),
+      });
+    }
+  }
+
+  return items;
+}
+
+/**
+ * Load cold memory — only when explicitly requested or when signals strongly indicate need.
+ *
+ * @param {string} query - What we're looking for
+ * @returns {Array<{source: string, content: string}>}
+ */
+export function loadCold(query) {
+  const items = [];
+
+  // Search past handoffs (from continuity.mjs)
+  const handoffs = _searchHandoffs(query);
+  if (handoffs.length > 0) {
+    items.push({
+      source: 'past-sessions',
+      content: handoffs.map(h => `[${h.timestamp}] ${h.task || ''}: ${h.resumeHint || ''}`).join('\n'),
+    });
+  }
+
+  return items;
+}
+
+/**
+ * Full context assembly — combines hot + warm based on current signals.
+ * This is what gets injected into HEAD's turn context.
+ *
+ * @param {object} signals
+ * @returns {MemoryContext}
+ */
+export function assemble(signals = {}) {
+  const hot = loadHot();
+  const warm = loadWarm(signals);
+
+  const parts = [];
+  if (hot.combined) parts.push(hot.combined);
+
+  if (warm.length > 0) {
+    const warmText = warm.map(w => `[${w.source}]\n${w.content}`).join('\n\n');
+    parts.push(warmText);
+  }
+
+  return {
+    narrative: hot.narrative,
+    simmerBrief: hot.simmerBrief,
+    warmItems: warm,
+    combined: parts.join('\n\n---\n\n'),
+  };
+}
+
+// ── Internal helpers ──────────────────────────────────────────────────────────
+
+function _looksLikeResume(msg) {
+  if (!msg) return false;
+  const lower = msg.toLowerCase();
+  return /continue|where were we|pick up|resume|what's next|whats next/.test(lower);
+}
+
+function _loadRecentDebriefs(n) {
+  try {
+    const loopFile = join(STATE_DIR, 'cognitive-loop.json');
+    if (!existsSync(loopFile)) return [];
+    const loop = JSON.parse(readFileSync(loopFile, 'utf8'));
+    return (loop.debriefs || []).slice(-n);
+  } catch {
+    return [];
+  }
+}
+
+function _loadRecentDecisions(n) {
+  try {
+    const file = join(STATE_DIR, 'decisions.jsonl');
+    if (!existsSync(file)) return [];
+    const lines = readFileSync(file, 'utf8').trim().split('\n').filter(Boolean);
+    return lines.slice(-n).map(l => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+function _searchHandoffs(query) {
+  try {
+    const handoffDir = join(STATE_DIR, 'handoffs');
+    if (!existsSync(handoffDir)) return [];
+    const files = readdirSync(handoffDir).filter(f => f.endsWith('.json')).slice(-10);
+    const results = [];
+    const queryLower = query.toLowerCase();
+
+    for (const f of files) {
+      try {
+        const data = JSON.parse(readFileSync(join(handoffDir, f), 'utf8'));
+        const text = JSON.stringify(data).toLowerCase();
+        if (text.includes(queryLower)) {
+          results.push(data);
+        }
+      } catch {}
+    }
+    return results.slice(-3);
+  } catch {
+    return [];
+  }
+}