create-walle 0.9.14 → 0.9.15

package/README.md

@@ -20,9 +20,9 @@ A web dashboard for running and managing AI coding sessions across multiple prov
 
 An always-on AI agent that learns from your Slack, email, calendar, and coding sessions.
 
-- **Second Brain** — Automatically ingests your digital life into a searchable memory store with full-text search, knowledge extraction, and pattern detection
+- **Second Brain** — Automatically ingests your digital life and coding sessions into a searchable memory store with full-text search, knowledge extraction, and pattern detection
 - **Proactive Intelligence** — Surfaces time-sensitive items, suggests actions, and delivers morning briefings and weekly reflections without being asked
-- **Chat with Tools** — Talk to Wall-E in the browser — it can search your memories, look up people, run skills, and call external tools via MCP (Slack, Glean, etc.)
+- **Chat with Tools** — Talk to Wall-E in the browser — it can search memories, recall prior coding sessions, look up people, run skills, and call external tools via MCP
 - **20 Bundled Skills** — Morning briefing, weekly reflection, proactive alerts, Slack monitoring, email sync, calendar integration, coding agent, memory search, model training, model pricing sync, and more
 - **Multi-Model** — Works with Claude, GPT, Gemini, DeepSeek, and local models via Ollama, LM Studio, or MLX with smart routing
 - **Skill Management GUI** — Search, filter, create, edit, and monitor skills from the browser with rich cards, config forms, execution history, export/import, and pre-flight validation

package/bin/create-walle.js

@@ -17,6 +17,8 @@ const { injectMcpConfigs } = require('./mcp-inject');
 const TEMPLATE_DIR = path.join(__dirname, '..', 'template');
 const LABEL = 'com.walle.server';
 const INSTALL_PATH_FILE = path.join(process.env.HOME, '.walle', 'install-path');
+const TELEMETRY_DATA_DIR = process.env.WALL_E_DATA_DIR || path.join(process.env.HOME || '/tmp', '.walle', 'data');
+const CLI_LIFECYCLE_FILE = path.join(TELEMETRY_DATA_DIR, '.cli-lifecycle.jsonl');
 const MANAGED_PACKAGE_DIRS = ['claude-task-manager', 'wall-e'];
 const NATIVE_DEPENDENCIES = new Set([
   'better-sqlite3',
@@ -28,6 +30,24 @@ const NATIVE_DEPENDENCIES = new Set([
 // Files to preserve during update (user config, not code)
 const PRESERVE_ON_UPDATE = ['.env', 'wall-e/wall-e-config.json'];
 
+function writeCliLifecycleEvent(event, meta = {}) {
+  if (process.env.WALLE_TELEMETRY === '0' || process.env.WALLE_TELEMETRY === 'false') return;
+  try {
+    fs.mkdirSync(TELEMETRY_DATA_DIR, { recursive: true });
+    const pkg = require('../package.json');
+    const entry = {
+      event,
+      meta: {
+        command: meta.command || '',
+        package_version: pkg.version || 'unknown',
+        elapsed_ms: Number.isFinite(meta.elapsed_ms) ? meta.elapsed_ms : undefined,
+      },
+      t: Date.now(),
+    };
+    fs.appendFileSync(CLI_LIFECYCLE_FILE, JSON.stringify(entry) + '\n', { mode: 0o600 });
+  } catch {}
+}
+
 // ── CLI Router ──
 
 if (require.main === module) {
@@ -97,9 +117,11 @@ function printMcpResults(wallePort) {
       } else if (r.action === 'already_configured') {
         console.log(`     ${DIM}=  ${r.tool} -- already configured${RESET}`);
       } else if (r.action === 'updated') {
-        console.log(`     ${GREEN}~  ${r.tool}${RESET} -- updated port in ${DIM}${r.configPath}${RESET}`);
+        const label = r.kind === 'agent_instructions' ? 'updated memory routing in' : 'updated port in';
+        console.log(`     ${GREEN}~  ${r.tool}${RESET} -- ${label} ${DIM}${r.configPath}${RESET}`);
       } else {
-        console.log(`     ${GREEN}+  ${r.tool}${RESET} -- added Wall-E to ${DIM}${r.configPath}${RESET}`);
+        const label = r.kind === 'agent_instructions' ? 'added memory routing to' : 'added Wall-E to';
+        console.log(`     ${GREEN}+  ${r.tool}${RESET} -- ${label} ${DIM}${r.configPath}${RESET}`);
       }
     }
     console.log(`\n  ${DIM}Your AI coding tools can now access Wall-E's memory and knowledge.`);
@@ -140,6 +162,8 @@ function install(targetDir) {
     console.error('  Template not found. Try: npm cache clean --force && npx create-walle@latest');
     process.exit(1);
   }
+  const installStartedAt = Date.now();
+  writeCliLifecycleEvent('cli_install_started', { command: 'install' });
 
   const ownerName = detectName().replace(/[\r\n=]/g, '').trim().slice(0, 200);
   const timezone = detectTimezone();
@@ -216,12 +240,18 @@ function install(targetDir) {
     npx create-walle logs        ${DIM}View logs${RESET}
 `);
   printMcpResults(parseInt(wallePort));
+  writeCliLifecycleEvent('cli_install_completed', {
+    command: 'install',
+    elapsed_ms: Date.now() - installStartedAt,
+  });
 }
 
 function update() {
   const dir = findWalleDir();
   const port = readPort(dir);
   const pkg = require('../package.json');
+  const updateStartedAt = Date.now();
+  writeCliLifecycleEvent('cli_update_started', { command: 'update' });
 
   console.log(`${BOLD}${CYAN}  Wall-E${RESET} — Updating to v${pkg.version}...\n`);
   console.log(`  ${DIM}Directory: ${dir}${RESET}`);
@@ -274,6 +304,10 @@ function update() {
   ${DIM}Your .env and config were preserved.${RESET}
 `);
   printMcpResults(parseInt(readWallePort(dir)));
+  writeCliLifecycleEvent('cli_update_completed', {
+    command: 'update',
+    elapsed_ms: Date.now() - updateStartedAt,
+  });
 }
 
 function start() {
@@ -732,4 +766,5 @@ module.exports = {
   npmCliCandidates,
   repairNativeDependencies,
   resolveNpmRunner,
+  writeCliLifecycleEvent,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-walle",
-  "version": "0.9.14",
+  "version": "0.9.15",
   "description": "CTM + Wall-E \u2014 AI coding dashboard and personal digital twin agent. Multi-agent terminal for Claude Code, Codex, Gemini, Aider, OpenCode, and more, plus prompt editor, task queue, and an agent that learns from Slack, email & calendar.",
   "bin": {
     "create-walle": "bin/create-walle.js"

package/template/claude-task-manager/api-prompts.js

@@ -10,6 +10,12 @@ const walleClient = require('./lib/walle-client');
 const claudeDesktopSessions = require('./lib/claude-desktop-sessions');
 // AI search uses direct HTTP calls to Claude API (supports Portkey proxy)
 
+let dbMaintenanceRunner = null;
+
+function setDbMaintenanceRunner(fn) {
+  dbMaintenanceRunner = typeof fn === 'function' ? fn : null;
+}
+
 // Embed a prompt (async, fire-and-forget)
 async function _embedPrompt(promptId, title, content) {
   try {
@@ -1467,7 +1473,10 @@ async function handleRestoreBackup(req, res) {
   try {
     const data = await readBody(req);
     if (!data.name) return jsonResponse(res, 400, { error: 'Missing backup name' });
-    const result = db.restoreBackup(data.name);
+    const restore = () => db.restoreBackup(data.name);
+    const result = dbMaintenanceRunner
+      ? await dbMaintenanceRunner({ kind: 'restore-backup', backupName: data.name }, restore)
+      : restore();
     jsonResponse(res, 200, result);
   } catch (e) { jsonResponse(res, 500, { error: e.message }); }
 }
@@ -2814,4 +2823,4 @@ function safeParse(json, fallback) {
   try { return JSON.parse(json); } catch { return fallback; }
 }
 
-module.exports = { handlePromptApi, queueEngine, importPermissionsToDb, runIncrementalConversationImport, importSessionFile, setUiPrefsBroadcaster };
+module.exports = { handlePromptApi, queueEngine, importPermissionsToDb, runIncrementalConversationImport, importSessionFile, setUiPrefsBroadcaster, setDbMaintenanceRunner };

package/template/claude-task-manager/db.js

@@ -2141,7 +2141,7 @@ function listSessionConversations({ search, limit, offset, hostname, allDevices
   }
   if (search) {
     sql += ' AND (title LIKE ? OR first_message LIKE ? OR project_path LIKE ? OR messages LIKE ?)';
-    const q = `%${search}%`;
+    const q = `%${normalizeSessionSearchValue(search) || search}%`;
     params.push(q, q, q, q);
   }
   sql += ' ORDER BY imported_at DESC';
@@ -2154,6 +2154,14 @@ function getSessionConversation(sessionId) {
   return getDb().prepare('SELECT * FROM session_conversations WHERE ctm_session_id = ?').get(sessionId);
 }
 
+function normalizeSessionSearchValue(value) {
+  return String(value || '')
+    .trim()
+    .toLowerCase()
+    .replace(/(^|[\s([{])[$/]+(?=[a-z0-9_-])/g, '$1')
+    .replace(/\s+/g, ' ');
+}
+
 function updateSessionModel(sessionId, modelProvider, modelId) {
   getDb().prepare(
     'UPDATE session_conversations SET model_provider = ?, model_id = ? WHERE ctm_session_id = ?'
@@ -2215,10 +2223,25 @@ function checkpointWal(mode) {
   const m = (mode || 'PASSIVE').toUpperCase();
   if (!_VALID_CHECKPOINT_MODES.has(m)) return;
   try {
-    db.pragma(`wal_checkpoint(${m})`);
+    return db.pragma(`wal_checkpoint(${m})`);
   } catch {}
 }
 
+function checkpointWalOrThrow(mode) {
+  if (!db) throw new Error('Database not initialized');
+  const m = (mode || 'PASSIVE').toUpperCase();
+  if (!_VALID_CHECKPOINT_MODES.has(m)) throw new Error(`Invalid WAL checkpoint mode: ${mode}`);
+  const rows = db.pragma(`wal_checkpoint(${m})`);
+  const row = Array.isArray(rows) ? rows[0] : rows;
+  const busy = Number(row?.busy ?? row?.[0] ?? 0);
+  if (busy > 0) {
+    const log = row?.log ?? row?.[1] ?? 'unknown';
+    const checkpointed = row?.checkpointed ?? row?.[2] ?? 'unknown';
+    throw new Error(`WAL checkpoint ${m} could not complete: busy=${busy}, log=${log}, checkpointed=${checkpointed}`);
+  }
+  return rows;
+}
+
 // Gzip a .db file to .db.gz and remove the original.
 // Returns the actual output path (destPath if gzip succeeded, srcPath if it didn't).
 function _gzipBackup(srcPath, destPath) {
@@ -2234,41 +2257,12 @@ function _gzipBackup(srcPath, destPath) {
 }
 
 function createBackup(label) {
-  if (!db || !currentDbPath) throw new Error('Database not initialized');
-  checkpointWal('TRUNCATE');
-
-  const now = new Date();
-  const ts = now.toISOString().replace(/[:.]/g, '-').slice(0, 19);
-  const tag = label ? `-${label.replace(/[^a-zA-Z0-9_-]/g, '')}` : '';
-  const tmpPath = path.join(BACKUP_DIR, `task-manager-${ts}${tag}.db`);
-  const backupName = `task-manager-${ts}${tag}.db.gz`;
-  const backupPath = path.join(BACKUP_DIR, backupName);
-
-  // Use SQLite backup API, then gzip
-  db.backup(tmpPath).then(() => {
-    _gzipBackup(tmpPath, backupPath);
-  }).catch(() => {
-    fs.copyFileSync(currentDbPath, tmpPath);
-    _gzipBackup(tmpPath, backupPath);
-  });
-
-  // Also copy images dir as a tarball if it has content
-  const imagesBackup = path.join(BACKUP_DIR, `images-${ts}${tag}.tar.gz`);
-  try {
-
-    const imageFiles = fs.readdirSync(DEFAULT_IMAGES_DIR);
-    if (imageFiles.length > 0) {
-      require('child_process').spawnSync('tar', ['-czf', imagesBackup, '-C', path.dirname(DEFAULT_IMAGES_DIR), path.basename(DEFAULT_IMAGES_DIR)], { timeout: 30000 });
-    }
-  } catch {}
-
-  cleanOldBackups();
-  return { backupName, backupPath, timestamp: now.toISOString() };
+  return createBackupSync(label);
 }
 
 function createBackupSync(label) {
   if (!db || !currentDbPath) throw new Error('Database not initialized');
-  checkpointWal('TRUNCATE');
+  checkpointWalOrThrow('TRUNCATE');
 
   const now = new Date();
   const ts = now.toISOString().replace(/[:.]/g, '-').slice(0, 19);
@@ -2328,7 +2322,7 @@ function restoreBackup(backupName) {
   createBackupSync('pre-restore');
 
   // Close current DB
-  checkpointWal('TRUNCATE');
+  checkpointWalOrThrow('TRUNCATE');
   if (db) { db.close(); db = null; }
 
   // Decompress if needed, then copy over current DB
@@ -2874,7 +2868,7 @@ function updateStartupTaskBranch(sessionId, branch, worktreePath) {
 
 function updateStartupTaskCwd(sessionId, cwd) {
   getDb().prepare('UPDATE startup_tasks SET cwd = ?, worktree_path = ? WHERE ctm_session_id = ?')
-    .run(cwd || '', cwd && cwd.includes('.claude/worktrees/') ? cwd : null, sessionId);
+    .run(cwd || '', cwd && /\/\.(?:claude|walle)\/worktrees\//.test(cwd) ? cwd : null, sessionId);
   flushWal();
 }
 
@@ -3593,24 +3587,15 @@ function upsertSession(id, data, opts) {
   }
 
   const agentId = data.agentSessionId;
-
-  // Cross-tab claim guard: before writing agent_sessions, make sure this
-  // agent_session_id isn't already owned by a different CTM tab. This is the
-  // main defense against mass-spawn races where multiple relink paths compete.
-  if (agentId && agentId !== '__CLEAR__' && !allowReclaim) {
-    const existing = d.prepare(
-      'SELECT ctm_session_id FROM agent_sessions WHERE agent_session_id = ?'
-    ).get(agentId);
-    if (existing && existing.ctm_session_id && existing.ctm_session_id !== id) {
-      const err = new Error(
-        `agent_session_id ${agentId} is already claimed by ctm_session ${existing.ctm_session_id} (refusing cross-tab claim for ${id})`
-      );
-      err.code = 'E_CROSS_TAB_CLAIM';
-      err.existingCtmSessionId = existing.ctm_session_id;
-      err.attemptedCtmSessionId = id;
-      err.agentSessionId = agentId;
-      throw err;
-    }
+  function throwCrossTabClaim(existingCtmSessionId) {
+    const err = new Error(
+      `agent_session_id ${agentId} is already claimed by ctm_session ${existingCtmSessionId} (refusing cross-tab claim for ${id})`
+    );
+    err.code = 'E_CROSS_TAB_CLAIM';
+    err.existingCtmSessionId = existingCtmSessionId;
+    err.attemptedCtmSessionId = id;
+    err.agentSessionId = agentId;
+    throw err;
   }
   const ctmParams = {
     id,
@@ -3636,6 +3621,7 @@ function upsertSession(id, data, opts) {
     git_branch: data.gitBranch || '',
     user_msg_count: data.userMsgCount || 0,
     slug: data.slug || '',
+    allow_reclaim: allowReclaim ? 1 : 0,
   } : null;
 
   // Wrap both upserts in a transaction to keep ctm_sessions + agent_sessions atomic
@@ -3656,13 +3642,21 @@ function upsertSession(id, data, opts) {
 
     // If agent session data provided, upsert agent_sessions
     if (agentParams) {
-      d.prepare(`
+      if (!allowReclaim) {
+        const existing = d.prepare(
+          'SELECT ctm_session_id FROM agent_sessions WHERE agent_session_id = ?'
+        ).get(agentId);
+        if (existing && existing.ctm_session_id && existing.ctm_session_id !== id) {
+          throwCrossTabClaim(existing.ctm_session_id);
+        }
+      }
+      const result = d.prepare(`
         INSERT INTO agent_sessions (agent_session_id, ctm_session_id, provider, project_path, jsonl_path,
           first_message, file_size, modified_at, hostname, model, git_branch, user_msg_count, slug)
         VALUES (@agent_session_id, @ctm_session_id, @provider, @project_path, @jsonl_path,
           @first_message, @file_size, @modified_at, @hostname, @model, @git_branch, @user_msg_count, @slug)
         ON CONFLICT(agent_session_id) DO UPDATE SET
-          ctm_session_id = COALESCE(NULLIF(excluded.ctm_session_id, ''), agent_sessions.ctm_session_id),
+          ctm_session_id = excluded.ctm_session_id,
           provider = COALESCE(NULLIF(excluded.provider, ''), agent_sessions.provider),
           project_path = COALESCE(NULLIF(excluded.project_path, ''), agent_sessions.project_path),
           jsonl_path = COALESCE(NULLIF(excluded.jsonl_path, ''), agent_sessions.jsonl_path),
@@ -3675,10 +3669,20 @@ function upsertSession(id, data, opts) {
           user_msg_count = CASE WHEN excluded.user_msg_count > 0 THEN excluded.user_msg_count ELSE agent_sessions.user_msg_count END,
           slug = COALESCE(NULLIF(excluded.slug, ''), agent_sessions.slug),
           updated_at = datetime('now')
+        WHERE @allow_reclaim = 1
+           OR agent_sessions.ctm_session_id IS NULL
+           OR agent_sessions.ctm_session_id = excluded.ctm_session_id
       `).run(agentParams);
+      if (!allowReclaim && result.changes === 0) {
+        const existing = d.prepare(
+          'SELECT ctm_session_id FROM agent_sessions WHERE agent_session_id = ?'
+        ).get(agentId);
+        throwCrossTabClaim(existing?.ctm_session_id || 'unknown');
+      }
     }
   });
-  txn();
+  if (typeof txn.immediate === 'function') txn.immediate();
+  else txn();
 }
 
 function setSessionStar(id, starred) {
@@ -3757,13 +3761,17 @@ function getSessionTitleNew(id) {
 function getAllSessionsData() {
   return getDb().prepare(`
     SELECT c.*, a.agent_session_id, a.jsonl_path, a.first_message, a.file_size,
-      a.modified_at, a.hostname, a.model, a.git_branch, a.user_msg_count,
-      a.last_user_content, a.first_assistant_text, a.rename_name
+      a.modified_at, a.hostname, a.model, a.git_branch,
+      MAX(COALESCE(a.user_msg_count, 0), COALESCE(sc.user_msg_count, 0)) as user_msg_count,
+      COALESCE(NULLIF(a.last_user_content, ''), sc.last_user_content) as last_user_content,
+      COALESCE(NULLIF(a.first_assistant_text, ''), sc.first_assistant_text) as first_assistant_text,
+      COALESCE(NULLIF(a.rename_name, ''), sc.rename_name) as rename_name
     FROM ctm_sessions c
     LEFT JOIN (
       SELECT *, ROW_NUMBER() OVER (PARTITION BY ctm_session_id ORDER BY modified_at DESC, created_at DESC) as rn
       FROM agent_sessions
     ) a ON a.ctm_session_id = c.id AND a.rn = 1
+    LEFT JOIN session_conversations sc ON sc.ctm_session_id = a.agent_session_id
   `).all();
 }
 
@@ -3789,22 +3797,33 @@ function getAgentSession(agentSessionId) {
  */
 function deleteCtmSession(ctmSessionId) {
   const d = getDb();
-  // Collect JSONL paths before delete (for disk cleanup)
-  const agentRows = d.prepare('SELECT jsonl_path FROM agent_sessions WHERE ctm_session_id = ?').all(ctmSessionId);
-  const jsonlPaths = agentRows.map(r => r.jsonl_path).filter(Boolean);
-
-  // CASCADE delete: deleting from ctm_sessions cascades to agent_sessions
-  d.prepare('DELETE FROM ctm_sessions WHERE id = ?').run(ctmSessionId);
-
-  // Also clean up other child tables (these don't have FK constraints)
-  try { d.prepare('DELETE FROM startup_tasks WHERE ctm_session_id = ?').run(ctmSessionId); } catch (e) { console.error('[db] deleteSession startup_tasks cleanup:', e.message); }
-  try { d.prepare('DELETE FROM scrollback_log WHERE ctm_session_id = ?').run(ctmSessionId); } catch (e) { console.error('[db] deleteSession scrollback_log cleanup:', e.message); }
-  try { d.prepare('DELETE FROM session_conversations WHERE ctm_session_id = ?').run(ctmSessionId); } catch (e) { console.error('[db] deleteSession session_conversations cleanup:', e.message); }
-  try { d.prepare('DELETE FROM session_messages WHERE ctm_session_id = ?').run(ctmSessionId); } catch (e) { console.error('[db] deleteSession session_messages cleanup:', e.message); }
-  try { d.prepare('DELETE FROM session_analyses WHERE ctm_session_id = ?').run(ctmSessionId); } catch (e) { console.error('[db] deleteSession session_analyses cleanup:', e.message); }
-  try { d.prepare('DELETE FROM prompt_queues WHERE ctm_session_id = ?').run(ctmSessionId); } catch (e) { console.error('[db] deleteSession prompt_queues cleanup:', e.message); }
-
-  return jsonlPaths;
+  const cleanupTables = [
+    ['startup_tasks', 'ctm_session_id'],
+    ['scrollback_log', 'ctm_session_id'],
+    ['session_conversations', 'ctm_session_id'],
+    ['session_messages', 'ctm_session_id'],
+    ['session_analyses', 'ctm_session_id'],
+    ['prompt_queues', 'ctm_session_id'],
+  ];
+  const txn = d.transaction(() => {
+    // Collect JSONL paths before delete (for disk cleanup)
+    const agentRows = d.prepare('SELECT jsonl_path FROM agent_sessions WHERE ctm_session_id = ?').all(ctmSessionId);
+    const jsonlPaths = agentRows.map(r => r.jsonl_path).filter(Boolean);
+
+    // Also clean up child tables without FK constraints before the parent row is removed.
+    for (const [table, idColumn] of cleanupTables) {
+      const exists = d.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name = ?").get(table);
+      if (!exists) continue;
+      const cols = d.prepare(`PRAGMA table_info(${table})`).all().map(c => c.name);
+      const column = cols.includes(idColumn) ? idColumn : (cols.includes('session_id') ? 'session_id' : null);
+      if (column) d.prepare(`DELETE FROM ${table} WHERE ${column} = ?`).run(ctmSessionId);
+    }
+
+    // CASCADE delete: deleting from ctm_sessions cascades to agent_sessions.
+    d.prepare('DELETE FROM ctm_sessions WHERE id = ?').run(ctmSessionId);
+    return jsonlPaths;
+  });
+  return txn();
 }
 
 // Legacy compatibility: upsertSessionIndex is now a no-op (session_index dropped)
@@ -3833,7 +3852,7 @@ module.exports = {
   getSessionTitle, setSessionTitle, isSessionUserRenamed, getAllSessionTitles,
   createTemplate, listTemplates, getTemplate, deleteTemplate,
   trackPromptUsage, getPromptUsageStats,
-  checkpointWal, createBackup, createBackupSync, listBackups, restoreBackup, deleteBackup, startDailyBackup,
+  checkpointWal, checkpointWalOrThrow, createBackup, createBackupSync, listBackups, restoreBackup, deleteBackup, startDailyBackup,
   saveQueue, loadQueue, loadAllQueues, deleteQueueDb,
   listPermRules, addPermRule, removePermRule, bulkSetPermRules, getPermRulesByProject,
   listAutoApprovals, upsertAutoApproval, toggleAutoApproval, deleteAutoApproval, getEnabledAutoApprovals,

package/template/claude-task-manager/docs/session-tooltip-freshness-design.md

@@ -0,0 +1,224 @@
+# Session Tooltip Freshness Design
+
+## Problem
+
+The active-session tooltip can show an AI summary that is technically cached
+correctly but no longer represents the current task. The most visible failure is
+a running session whose tooltip headline still describes an older task while the
+latest prompt and progress have already moved on.
+
+This is worse than an empty tooltip because it gives false confidence. The
+operator uses the tooltip to decide which session needs attention, so stale
+intent text can send the user to the wrong session or hide a current blocker.
+
+## Existing Behavior
+
+Current flow:
+
+1. `stream-view.js` opens the tooltip after hover and fetches
+   `/api/sessions/:id/summary?turns=3`.
+2. `SessionStream` stores cleaned user prompts in `userPromptCache`.
+3. A new user prompt debounces AI summary generation by 2 seconds.
+4. The configured provider generates a 10-15 word summary over the cached
+   prompt list.
+5. `getSummary()` returns `summary`, `intent`, `displayPrompt`, `lastPrompt`,
+   and `progress`.
+
+Current failure modes:
+
+- Cached `intent.source = ai-summary` is treated as authoritative even when its
+  timestamp is older than the latest prompt.
+- The tooltip does not refetch or rerender while it is already open for the same
+  session.
+- The AI summary input is a flat list of recent prompts, so older work can
+  dominate the summary after a task switch.
+- The UI label `Intent` does not explain freshness or distinguish current
+  prompt evidence from slower AI synthesis.
+
+## Design Principles
+
+- Latest user intent is the primary truth. AI is a compression layer, not a
+  source of freshness.
+- Stale AI should be visible as context, never promoted as the current task.
+- Refresh should be scoped to visible UI. Do not add broad polling across every
+  session.
+- The tooltip should be copyable, stable, dense, and operational.
+- Existing API fields must stay backward compatible for Session Overview and
+  older clients.
+
+## API Contract
+
+`GET /api/sessions/:id/summary` keeps existing fields and adds:
+
+```js
+{
+  currentTask: {
+    text: string | null,
+    source: 'latest-prompt' | 'ai-summary' | 'prompt-fallback' | 'title-fallback' | 'missing',
+    freshness: 'fresh' | 'updating' | 'stale' | 'missing',
+    updatedAt: number,
+    promptTimestamp: number,
+    staleReason?: string
+  },
+  latestPrompt: {
+    text: string | null,
+    timestamp: number
+  },
+  aiSummary: {
+    text: string | null,
+    source: string | null,
+    status: 'fresh' | 'updating' | 'stale' | 'fallback' | 'unavailable',
+    updatedAt: number,
+    promptTimestamp: number,
+    promptCount: number,
+    staleReason?: string
+  }
+}
+```
+
+Compatibility mapping:
+
+- `intent` remains present.
+- `summary` remains present.
+- When AI is stale, `intent.text` should follow `currentTask.text` so existing
+  clients do not keep rendering stale AI as the primary task.
+- `aiSummary.text` retains the older AI text for secondary display.
+
+Freshness rules:
+
+- If usable AI summary exists and `aiSummary.updatedAt >= latestPrompt.timestamp`,
+  `currentTask.source = ai-summary` and `freshness = fresh`.
+- If usable AI summary exists but is older than the latest prompt,
+  `currentTask.source = latest-prompt`, `freshness = updating`, and
+  `aiSummary.status = stale` or `updating`.
+- If no AI summary exists, use the most recent content-rich prompt and mark the
+  AI summary as `unavailable` or `fallback`.
+- If a fallback summary is raw prompt text, keep current task on prompt evidence
+  and mark `aiSummary.status = fallback`.
+
+## Summary Generation
+
+Change the AI prompt from a flat prompt list to latest-prompt-weighted input.
+
+Recommended input:
+
+```text
+Latest prompt:
+<most recent cleaned prompt>
+
+Recent context:
+1. <older prompt>
+2. <older prompt>
+3. <older prompt>
+```
+
+Recommended system prompt:
+
+```text
+Summarize the user's current task. Prioritize the latest prompt. Use older
+prompts only as context. Return 8-14 words. Return only the summary, no quotes
+or prefix.
+```
+
+The cached summary should record the prompt timestamp and prompt count used to
+generate it. This makes freshness testable without depending on provider speed.
+
+## Tooltip UX
+
+Replace the main `Intent` section with `Current Task`.
+
+Fresh state:
+
+```text
+CURRENT TASK
+[AI SUMMARY] [FRESH] [now]
+Fixing Wall-E session history restore and tooltip freshness.
+```
+
+Updating state:
+
+```text
+CURRENT TASK
+[LATEST PROMPT] [UPDATING] [now]
+Does WallE coding agent have auto compact logic like OpenCode or Claude?
+
+AI SUMMARY
+[STALE] [2m ago]
+Previous: Fixing session tab drag behavior and search issues.
+```
+
+Unavailable state:
+
+```text
+CURRENT TASK
+[LATEST PROMPT] [FALLBACK] [now]
+Fix the session tooltip freshness behavior.
+```
+
+Progress remains separate and should keep using assistant-event evidence.
+
+Interaction behavior:
+
+- Opening a tooltip fetches summary immediately.
+- If the tooltip is already open for that session, new stream events rerender it.
+- While visible, perform a lightweight refresh every 10 seconds.
+- Stop the refresh timer when the tooltip is hidden.
+- Clicking inside the tooltip continues to preserve it for copy/select.
+- Activating a different session tooltip replaces the current tooltip.
+
+## Implementation Plan
+
+Phase 1: documentation
+
+- Add this design note.
+- Commit documentation by itself after TL review.
+
+Phase 2: backend freshness
+
+- Extend `SessionStream` cached summary metadata with prompt timestamp/count.
+- Add `latestPrompt`, `aiSummary`, and `currentTask` to `getSummary()`.
+- Ensure `intent` maps to `currentTask`, not stale AI.
+- Update summary generation prompt to prioritize latest prompt.
+- Add unit tests for fresh, stale, fallback, and provider-lag cases.
+
+Phase 3: tooltip UI
+
+- Render `Current Task` from `currentTask`.
+- Render stale AI only as secondary context.
+- Add freshness/status pills.
+- Add visible-tooltip refresh and stream-event rerender.
+- Add browser/render coverage for a tooltip that updates while open.
+
+Phase 4: dev validation
+
+- Start isolated CTM via `ctm-dev`.
+- Verify service health on the dev port pair.
+- Exercise stale summary behavior through a real browser.
+- Confirm no browser console errors for the tooltip flow.
+- Commit implementation after TL review.
+
+## Test Matrix
+
+Backend:
+
+- AI summary generated after latest prompt: primary task is AI summary.
+- AI summary timestamp older than latest prompt: primary task is latest prompt.
+- AI provider slow or failed: primary task remains latest prompt.
+- Fallback summary raw prompt: primary task remains prompt evidence.
+- Summary generation input puts latest prompt before recent context.
+
+Frontend:
+
+- Tooltip opens and labels `Current Task`.
+- Stale AI is demoted into `AI Summary`.
+- New user stream event updates an already-open tooltip.
+- Fresh summary event promotes AI summary.
+- Tooltip remains copyable and dismisses only on outside click or another
+  tooltip activation.
+
+Dev validation:
+
+- CTM dev server starts on a random non-primary port.
+- `/api/services/status` succeeds on the dev port.
+- Browser test uses the dev port, never `3456` or `3457`.
+- Screenshot or DOM assertions prove the freshness state.