dave-code 1.0.4 → 1.2.0

package/bin/runtimeEvents.js

@@ -0,0 +1,104 @@
+import { EventEmitter } from 'events';
+
+export const RUNTIME_EVENT_TYPES = new Set([
+  'turn.started',
+  'turn.completed',
+  'turn.failed',
+  'turn.cancelled',
+  'model.started',
+  'model.delta',
+  'model.tool_call',
+  'model.completed',
+  'model.retry',
+  'tool.requested',
+  'tool.started',
+  'tool.progress',
+  'tool.completed',
+  'tool.failed',
+  'permission.requested',
+  'permission.resolved',
+  'context.compacted'
+  ,'context.planned'
+  ,'context.usage'
+  ,'read.plan.presented'
+  ,'read.plan.resolved'
+  ,'budget.warning'
+  ,'budget.resolved'
+  ,'usage.phase'
+  ,'scan.started'
+  ,'scan.progress'
+  ,'scan.inspect'
+  ,'scan.index.completed'
+  ,'scan.notebook.checked'
+  ,'scan.drift.completed'
+  ,'scan.completed'
+  ,'scan.degraded'
+  ,'scan.note.plan.started'
+  ,'scan.note.plan.completed'
+  ,'scan.note.plan.degraded'
+  ,'phase.changed'
+  ,'note.build.started'
+  ,'note.build.progress'
+  ,'note.build.completed'
+  ,'note.loaded'
+  ,'note.drift'
+  ,'note.update.started'
+  ,'note.update.completed'
+  ,'note.failed'
+  ,'note.synthesis.started'
+  ,'note.synthesis.completed'
+  ,'read.file.completed'
+  ,'memory.recalled'
+  ,'memory.saved'
+  ,'team.started'
+  ,'team.phase'
+  ,'team.completed'
+  ,'member.added'
+  ,'member.updated'
+  ,'task.updated'
+  ,'message.sent'
+  ,'resource.proposed'
+  ,'todos.updated'
+  ,'resource.approved'
+]);
+
+export function createRuntimeEvents({ turnId, now = Date.now } = {}) {
+  const emitter = new EventEmitter();
+  const resolvedTurnId = turnId || `turn-${now()}-${Math.random().toString(36).slice(2, 8)}`;
+  let seq = 0;
+  let closed = false;
+
+  function emit(type, data = {}) {
+    if (closed) return null;
+    if (!RUNTIME_EVENT_TYPES.has(type)) {
+      throw new Error(`Unknown runtime event type: ${type}`);
+    }
+    const event = {
+      version: 1,
+      seq: ++seq,
+      type,
+      turnId: resolvedTurnId,
+      timestamp: now(),
+      data: data && typeof data === 'object' ? data : { value: data }
+    };
+    emitter.emit('event', event);
+    return event;
+  }
+
+  function subscribe(listener) {
+    emitter.on('event', listener);
+    return () => emitter.off('event', listener);
+  }
+
+  function close() {
+    closed = true;
+    emitter.removeAllListeners();
+  }
+
+  return {
+    turnId: resolvedTurnId,
+    emit,
+    subscribe,
+    close
+  };
+}

package/bin/scanManager.js

@@ -0,0 +1,561 @@
+import crypto from 'crypto';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { streamAIResponse } from './aiClient.js';
+import { getUsableContextTokens, inferContextWindowTokens } from './configManager.js';
+import { estimateTokens } from './contextManager.js';
+import { isSensitivePath } from './toolRuntime.js';
+import {
+  detectNotebookDrift,
+  loadProjectNotebook,
+  normalizeNotebookBuildPlan
+} from './projectNotebookManager.js';
+
+const CACHE_VERSION = 1;
+const BUILTIN_IGNORES = new Set([
+  '.git', 'node_modules', '.next', '.nuxt', 'dist', 'build', 'coverage',
+  'vendor', '__pycache__', '.venv', 'venv', 'target', '.cache',
+  '.pytest_cache', '.mypy_cache', '.ruff_cache', '.tox', '.nox', 'htmlcov',
+  '.turbo', '.parcel-cache', '.vite', 'out', 'artifacts', 'cache',
+  'tmp', 'temp', 'logs'
+]);
+let cacheBaseDir = path.join(os.homedir(), '.dave-code-scans');
+
+export function setScanCacheDirForTesting(directory) {
+  cacheBaseDir = directory;
+}
+
+function canonicalRoot(root) {
+  const resolved = path.resolve(root);
+  try { return fs.realpathSync.native(resolved); } catch { return resolved; }
+}
+
+function cacheFile(root) {
+  const key = crypto.createHash('sha256').update(canonicalRoot(root).toLowerCase()).digest('hex');
+  return path.join(cacheBaseDir, `${key}.json`);
+}
+
+function atomicWrite(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+  const temp = `${filePath}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
+  fs.writeFileSync(temp, JSON.stringify(value), { encoding: 'utf8', mode: 0o600 });
+  try { fs.chmodSync(temp, 0o600); } catch {}
+  try {
+    fs.renameSync(temp, filePath);
+  } catch (error) {
+    if (process.platform !== 'win32' || !fs.existsSync(filePath)) throw error;
+    fs.unlinkSync(filePath);
+    fs.renameSync(temp, filePath);
+  } finally {
+    if (fs.existsSync(temp)) fs.unlinkSync(temp);
+  }
+}
+
+function loadCache(root) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(cacheFile(root), 'utf8'));
+    return parsed?.version === CACHE_VERSION && parsed.files ? parsed : { version: CACHE_VERSION, files: {} };
+  } catch {
+    return { version: CACHE_VERSION, files: {} };
+  }
+}
+
+function extensionKind(relPath) {
+  const ext = path.extname(relPath).toLowerCase();
+  const kinds = {
+    '.js': 'JavaScript', '.mjs': 'JavaScript', '.cjs': 'JavaScript', '.ts': 'TypeScript', '.tsx': 'TypeScript UI',
+    '.jsx': 'JavaScript UI', '.py': 'Python', '.go': 'Go', '.rs': 'Rust', '.java': 'Java', '.cs': 'C#',
+    '.cpp': 'C++', '.c': 'C', '.h': 'C/C++ header', '.json': 'JSON', '.yaml': 'YAML', '.yml': 'YAML',
+    '.toml': 'TOML', '.md': 'Documentation', '.html': 'HTML', '.css': 'Stylesheet', '.scss': 'Stylesheet',
+    '.sql': 'SQL', '.sh': 'Shell', '.ps1': 'PowerShell', '.bat': 'Batch'
+  };
+  return kinds[ext] || (ext ? `${ext.slice(1).toUpperCase()} file` : 'File');
+}
+
+function purposeHint(relPath) {
+  const normalized = relPath.replace(/\\/g, '/').toLowerCase();
+  const base = path.basename(normalized);
+  if (/^(package|composer|cargo|pyproject|requirements|go\.mod)/.test(base)) return 'Dependency and project manifest';
+  if (/^(readme|contributing|changelog|license)/.test(base)) return 'Project documentation';
+  if (/(^|\/)(test|tests|spec|__tests__)(\/|$)|\.(test|spec)\./.test(normalized)) return 'Automated tests';
+  if (/(^|\/)(config|configs|\.github)(\/|$)|config\./.test(normalized)) return 'Configuration or automation';
+  if (/(^|\/)(src|app|lib)(\/|$)/.test(normalized)) return 'Application source';
+  if (/(^|\/)(assets|public|static)(\/|$)/.test(normalized)) return 'Static asset';
+  if (/(index|main|app|server|cli)\.[^.]+$/.test(base)) return 'Likely entry point';
+  return extensionKind(relPath);
+}
+
+function gitignorePatterns(root) {
+  try {
+    return fs.readFileSync(path.join(root, '.gitignore'), 'utf8')
+      .split(/\r?\n/).map(line => line.trim()).filter(line => line && !line.startsWith('#'));
+  } catch { return []; }
+}
+
+function ignoredByPattern(relPath, patterns) {
+  const normalized = relPath.replace(/\\/g, '/');
+  let ignored = false;
+  for (const rawRule of patterns) {
+    const negated = rawRule.startsWith('!');
+    const raw = negated ? rawRule.slice(1) : rawRule;
+    const pattern = raw.replace(/^\//, '').replace(/\/$/, '');
+    if (!pattern) continue;
+    let matches;
+    if (!pattern.includes('*')) matches = normalized === pattern || normalized.startsWith(`${pattern}/`) || normalized.split('/').includes(pattern);
+    else {
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*\*/g, '.*').replace(/\*/g, '[^/]*').replace(/\?/g, '.');
+      matches = new RegExp(`(?:^|/)${escaped}(?:$|/)`).test(normalized);
+    }
+    if (matches) ignored = !negated;
+  }
+  return ignored;
+}
+
+function requestTerms(request) {
+  return [...new Set(String(request || '').toLowerCase().match(/[a-z][a-z0-9_.-]{2,}|[\u3400-\u9fff]{2,}/g) || [])].slice(0, 30);
+}
+
+function capEstimatedTokens(value, maxTokens) {
+  const text = String(value || '');
+  if (estimateTokens(text) <= maxTokens) return text;
+  let low = 0;
+  let high = text.length;
+  while (low < high) {
+    const middle = Math.ceil((low + high) / 2);
+    if (estimateTokens(text.slice(0, middle)) <= maxTokens) low = middle;
+    else high = middle - 1;
+  }
+  return `${text.slice(0, low)}\n[Token-capped]`;
+}
+
+function notebookCatalog(notebook, drift = null) {
+  if (!notebook) return null;
+  return {
+    status: notebook.status,
+    maturity: notebook.maturity || 'complete',
+    coverage: notebook.coverage,
+    headings: Object.keys(notebook.sections || {}).slice(0, 12),
+    sectionIndex: Object.fromEntries(Object.entries(notebook.sectionIndex || {}).slice(0, 12).map(([name, entry]) => [
+      name,
+      {
+        files: Array.isArray(entry?.files) ? entry.files.slice(0, 12) : [],
+        keywords: Array.isArray(entry?.keywords) ? entry.keywords.slice(0, 20) : []
+      }
+    ])),
+    shortSummary: capEstimatedTokens(notebook.shortSummary || '', 1000),
+    drift: (drift?.changes || []).slice(0, 100).map(item => ({
+      type: item.type, path: item.path, from: item.from
+    }))
+  };
+}
+
+function isOutlineCandidate(file, terms) {
+  const lower = file.path.toLowerCase();
+  return file.size <= 512 * 1024 && !file.sensitive && (
+    /(^|\/)(package\.json|readme[^/]*|[^/]*(index|main|server|cli)\.[^/]+)$/.test(lower) ||
+    terms.some(term => lower.includes(term))
+  );
+}
+
+async function outlineFile(absPath) {
+  const handle = await fs.promises.open(absPath, 'r');
+  try {
+    const buffer = Buffer.alloc(128 * 1024);
+    const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+    const sample = buffer.subarray(0, bytesRead);
+    if (sample.includes(0)) return null;
+    const text = sample.toString('utf8');
+    const lines = text.split(/\r?\n/);
+    const symbols = [];
+    const imports = [];
+    for (let index = 0; index < lines.length && symbols.length < 60; index++) {
+      const line = lines[index];
+      if (/^\s*(?:import|export\s+.*from|const\s+.*require\s*\()/i.test(line)) imports.push(`${index + 1}: ${line.trim().slice(0, 180)}`);
+      if (/^\s*(?:export\s+)?(?:async\s+)?(?:function|class|interface|type|const\s+\w+\s*=\s*(?:async\s*)?\(|def\s+|class\s+)/.test(line)) symbols.push(`${index + 1}: ${line.trim().slice(0, 180)}`);
+    }
+    return { imports: imports.slice(0, 30), symbols, sampledBytes: bytesRead };
+  } finally { await handle.close(); }
+}
+
+export async function buildScanSnapshot(workspaceRoot, request = '', { emit = () => {}, signal, includeOutlines = true } = {}) {
+  const root = canonicalRoot(workspaceRoot);
+  const previous = loadCache(root);
+  const patterns = gitignorePatterns(root);
+  const terms = requestTerms(request);
+  const files = [];
+  const excluded = [];
+  const languages = {};
+  const directories = {};
+  let totalBytes = 0;
+  let cacheHits = 0;
+  const queue = [root];
+  emit('scan.started', { root });
+  while (queue.length) {
+    if (signal?.aborted) throw new Error('Scan cancelled.');
+    const directory = queue.shift();
+    let entries;
+    try { entries = await fs.promises.readdir(directory, { withFileTypes: true }); } catch { continue; }
+    for (const entry of entries) {
+      const absolute = path.join(directory, entry.name);
+      const rel = path.relative(root, absolute).replace(/\\/g, '/');
+      if (entry.isSymbolicLink()) { excluded.push({ path: rel, reason: 'symlink' }); continue; }
+      if (entry.isDirectory()) {
+        if (BUILTIN_IGNORES.has(entry.name) || ignoredByPattern(rel, patterns)) {
+          excluded.push({ path: rel, reason: 'ignored-directory' });
+        } else queue.push(absolute);
+        continue;
+      }
+      if (!entry.isFile() || ignoredByPattern(rel, patterns)) continue;
+      let stat;
+      try { stat = await fs.promises.stat(absolute); } catch { continue; }
+      const kind = extensionKind(rel);
+      const identity = `${stat.size}:${Math.trunc(stat.mtimeMs)}`;
+      const cached = previous.files[rel]?.identity === identity ? previous.files[rel] : null;
+      if (cached) cacheHits++;
+      const file = {
+        path: rel, size: stat.size, mtimeMs: stat.mtimeMs, identity, kind,
+        purpose: cached?.purpose || purposeHint(rel), sensitive: isSensitivePath(rel),
+        outline: cached?.outline || null
+      };
+      files.push(file);
+      totalBytes += stat.size;
+      languages[kind] = (languages[kind] || 0) + 1;
+      const top = rel.includes('/') ? rel.split('/')[0] : '.';
+      directories[top] = (directories[top] || 0) + 1;
+      if (files.length % 100 === 0) emit('scan.progress', { files: files.length, bytes: totalBytes, current: rel, cacheHits });
+    }
+  }
+
+  if (includeOutlines) {
+    const candidates = files.filter(file => isOutlineCandidate(file, terms)).sort((a, b) => a.size - b.size).slice(0, 24);
+    for (const file of candidates) {
+      if (file.outline) continue;
+      try {
+        emit('scan.inspect', { path: file.path });
+        file.outline = await outlineFile(path.join(root, file.path));
+      } catch {}
+    }
+  }
+  const snapshotId = crypto.createHash('sha256')
+    .update(files.map(file => `${file.path}:${file.identity}`).join('|')).digest('hex').slice(0, 20);
+  const snapshot = {
+    version: 1, snapshotId, workspaceRoot: root, createdAt: Date.now(),
+    totalFiles: files.length, totalBytes, cacheHits, excluded, languages, directories, files
+  };
+  atomicWrite(cacheFile(root), {
+    version: CACHE_VERSION, snapshotId, updatedAt: Date.now(),
+    files: Object.fromEntries(files.map(file => [file.path, {
+      identity: file.identity, purpose: file.purpose, outline: file.outline
+    }]))
+  });
+  return snapshot;
+}
+
+export function summarizeScanSnapshot(snapshot, request = '') {
+  const terms = requestTerms(request);
+  const relevant = snapshot.files.map(file => ({
+    ...file,
+    score: terms.reduce((score, term) => score + (file.path.toLowerCase().includes(term) ? 5 : 0), 0)
+      + (/entry point|manifest|configuration/i.test(file.purpose) ? 2 : 0)
+      + (file.outline ? 1 : 0)
+  })).sort((a, b) => b.score - a.score || a.size - b.size).slice(0, 40);
+  const summary = JSON.stringify({
+    snapshotId: snapshot.snapshotId,
+    totalFiles: snapshot.totalFiles,
+    totalBytes: snapshot.totalBytes,
+    cacheHitRate: snapshot.totalFiles ? snapshot.cacheHits / snapshot.totalFiles : 0,
+    excludedDirectories: snapshot.excluded.slice(0, 40),
+    languages: snapshot.languages,
+    directories: snapshot.directories,
+    candidateFiles: relevant.map(file => ({
+      path: file.path, size: file.size, kind: file.kind, purpose: file.purpose,
+      ...(file.outline ? { outline: file.outline } : {})
+    }))
+  }, null, 2);
+  return summary.length <= 12000 ? summary : `${summary.slice(0, 12000)}\n[Scan summary truncated; complete metadata remains in the local snapshot cache.]`;
+}
+
+function normalizeReadStrategy(value, fallback = 'targeted') {
+  const strategy = String(value || '').toLowerCase();
+  if (['outline', 'inspect'].includes(strategy)) return 'outline';
+  if (['full', 'read'].includes(strategy)) return 'full';
+  if (['targeted', 'targeted-read', 'range'].includes(strategy)) return 'targeted';
+  return fallback;
+}
+
+function normalizeContextPlan(raw, snapshot, profile, request, {
+  notebookAvailable = false,
+  notebookStatus = 'missing',
+  notebookMaturity = 'baseline',
+  drift = []
+} = {}) {
+  const contextWindowTokens = inferContextWindowTokens(profile);
+  const usable = getUsableContextTokens(profile);
+  const requestedContext = Number(raw?.contextBudgetTokens ?? raw?.budgetTokens);
+  const contextBudgetTokens = Math.max(
+    4096,
+    Math.min(usable, Number.isFinite(requestedContext) ? Math.round(requestedContext) : Math.round(usable * 0.45))
+  );
+  const requestedTurn = Number(raw?.turnBudgetTokens);
+  const turnBudgetTokens = Math.max(
+    contextBudgetTokens,
+    Math.min(contextBudgetTokens * 8, Number.isFinite(requestedTurn) ? Math.round(requestedTurn) : contextBudgetTokens * 3)
+  );
+  const known = new Set(snapshot.files.map(file => file.path.toLowerCase()));
+  const rawFiles = Array.isArray(raw?.files) ? raw.files : (Array.isArray(raw?.recommendedFiles) ? raw.recommendedFiles : []);
+  let files = rawFiles
+    .map(item => typeof item === 'string' ? { path: item } : item)
+    .filter(item => item?.path && known.has(String(item.path).replace(/\\/g, '/').toLowerCase()))
+    .slice(0, 100)
+    .map(item => {
+      const file = snapshot.files.find(candidate => candidate.path.toLowerCase() === String(item.path).replace(/\\/g, '/').toLowerCase());
+      const strategy = normalizeReadStrategy(item.strategy);
+      const estimatedTokens = Math.max(50, Number(item.estimatedTokens)
+        || Math.ceil(Math.min(file?.size || 0, strategy === 'full' ? file?.size || 0 : strategy === 'targeted' ? 24000 : 4000) / 4));
+      return {
+        path: String(item.path).replace(/\\/g, '/'),
+        reason: String(item.reason || ''),
+        strategy,
+        required: item.required === true,
+        estimatedTokens
+      };
+    });
+
+  const legacyReuse = raw?.notebookReuse && typeof raw.notebookReuse === 'object' ? raw.notebookReuse : null;
+  if (!files.length && legacyReuse?.verifyFiles) {
+    files = legacyReuse.verifyFiles
+      .map(item => typeof item === 'string' ? { path: item } : item)
+      .filter(item => item?.path && known.has(String(item.path).replace(/\\/g, '/').toLowerCase()))
+      .slice(0, 40)
+      .map(item => ({
+        path: String(item.path).replace(/\\/g, '/'),
+        reason: String(item.reason || ''),
+        strategy: normalizeReadStrategy(item.strategy),
+        required: true,
+        estimatedTokens: 1000
+      }));
+  }
+
+  const rawNotebook = raw?.notebook && typeof raw.notebook === 'object' ? raw.notebook : {};
+  const defaultNotebookAction = !notebookAvailable
+    ? 'build'
+    : (drift.length || ['stale', 'failed', 'partial'].includes(notebookStatus) ? 'update' : 'reuse');
+  const requestedNotebookAction = String(rawNotebook.action || '').toLowerCase();
+  const notebookAction = ['reuse', 'build', 'update'].includes(requestedNotebookAction)
+    ? requestedNotebookAction
+    : defaultNotebookAction;
+  const notebookBudgetTokens = Math.max(
+    0,
+    Math.min(turnBudgetTokens, Math.round(Number(rawNotebook.notebookBudgetTokens ?? raw?.notebookBudgetTokens)
+      || (notebookAction === 'reuse' ? 0 : Math.min(2000, Math.round(turnBudgetTokens * 0.15)))))
+  );
+  const notebook = {
+    action: notebookAction,
+    status: notebookStatus,
+    maturity: notebookMaturity,
+    sections: Array.isArray(rawNotebook.sections)
+      ? rawNotebook.sections.map(String).slice(0, 12)
+      : (Array.isArray(legacyReuse?.trustedSections) ? legacyReuse.trustedSections.map(String).slice(0, 12) : []),
+    notebookBudgetTokens
+  };
+  const recommendedFiles = files.map(item => ({
+    path: item.path,
+    reason: item.reason,
+    strategy: item.strategy
+  }));
+  const notebookReuse = notebookAvailable ? {
+    rationale: String(legacyReuse?.rationale || 'Use the private notebook on demand and verify only task-critical source.'),
+    trustedSections: notebook.sections,
+    verifyFiles: files.map(item => ({
+      path: item.path, reason: item.reason, strategy: item.strategy
+    })),
+    stalePaths: [...new Set([
+      ...(Array.isArray(legacyReuse?.stalePaths) ? legacyReuse.stalePaths.map(String) : []),
+      ...drift.flatMap(item => [item.path, item.from].filter(Boolean))
+    ])].slice(0, 200)
+  } : null;
+  return {
+    version: 2,
+    requestFingerprint: crypto.createHash('sha256').update(String(request)).digest('hex').slice(0, 20),
+    snapshotId: snapshot.snapshotId,
+    contextWindowTokens,
+    usableTokens: usable,
+    contextBudgetTokens,
+    turnBudgetTokens,
+    budgetTokens: contextBudgetTokens,
+    reserveTokens: Math.max(0, turnBudgetTokens - contextBudgetTokens),
+    rationale: String(raw?.rationale || 'Adaptive fallback based on the model context window.'),
+    files,
+    notebook,
+    recommendedFiles,
+    notebookReuse,
+    degraded: raw?.degraded === true,
+    createdAt: Date.now()
+  };
+}
+
+export async function planHighwayNotebookBuild({
+  snapshot, request = '', emit = () => {}, signal
+}) {
+  emit('scan.note.plan.started', { files: snapshot.totalFiles, bytes: snapshot.totalBytes });
+  if (signal?.aborted) throw new Error('Scan cancelled.');
+  // This decision is intentionally local: a second planning model call costs
+  // more time and tokens than it saves on small and medium repositories.
+  const plan = normalizeNotebookBuildPlan({
+    rationale: 'Fast local plan: outline every effective file and read only entry, manifest, configuration, and request-matching files.',
+    estimatedInputTokens: 0, estimatedModelCalls: 1, defaultStrategy: 'outline', groups: [],
+    validation: { requiredCoveragePercent: 100, requireEntries: true, requireConfigs: true, requireDependencies: true }
+  }, snapshot, request);
+  emit('scan.note.plan.completed', { plan });
+  return plan;
+}
+
+export async function runAdaptiveScan({
+  workspaceRoot, request, memories = '', conversationContext = '', profile, emit = () => {}, signal,
+  modelRunner = streamAIResponse, notebookPolicy = 'metadata', notebookMode = 'auto', lang = 'cn'
+}) {
+  const existingNotebook = notebookPolicy === 'highway' ? loadProjectNotebook(workspaceRoot) : null;
+  const snapshot = await buildScanSnapshot(workspaceRoot, request, {
+    emit,
+    signal,
+    // Scan may inspect compact local outlines, but it never builds or refreshes
+    // the private notebook. That work begins only after the read plan is approved.
+    includeOutlines: true
+  });
+  emit('scan.index.completed', {
+    files: snapshot.totalFiles,
+    bytes: snapshot.totalBytes,
+    cacheHits: snapshot.cacheHits,
+    excluded: snapshot.excluded.length,
+    outlines: snapshot.files.filter(file => file.outline).length
+  });
+  emit('scan.notebook.checked', notebookPolicy === 'highway'
+    ? {
+        enabled: true,
+        found: Boolean(existingNotebook),
+        status: existingNotebook?.status || 'missing',
+        files: existingNotebook?.coverage?.completed || 0,
+        updatedAt: existingNotebook?.updatedAt || null
+      }
+    : { enabled: false, found: false, status: 'disabled', files: 0, updatedAt: null });
+  const metadataSummary = summarizeScanSnapshot(snapshot, request);
+  let drift = null;
+  if (notebookPolicy === 'highway') {
+    try {
+      drift = existingNotebook
+        ? await detectNotebookDrift(workspaceRoot, snapshot, existingNotebook)
+        : { changes: [], semantic: false, shouldUpdate: true, shouldRebuild: true };
+      emit('scan.drift.completed', {
+        enabled: true,
+        action: existingNotebook ? (drift.changes.length ? 'update-planned' : 'loaded') : 'build-planned',
+        changes: drift.changes.length,
+        semantic: drift.semantic === true,
+        notebookStatus: existingNotebook?.status || 'missing'
+      });
+    } catch (error) {
+      emit('scan.drift.completed', { enabled: true, action: 'failed', changes: 0, error: error.message });
+    }
+  } else {
+    emit('scan.drift.completed', { enabled: false, action: 'skipped', changes: 0 });
+  }
+  const catalog = notebookPolicy === 'highway' ? notebookCatalog(existingNotebook, drift) : null;
+  const summary = capEstimatedTokens(JSON.stringify({
+    source: catalog ? 'notebook-catalog-and-index' : 'workspace-index',
+    snapshotMetadata: capEstimatedTokens(metadataSummary, 3000),
+    notebook: catalog,
+    requestedNotebookMode: notebookMode
+  }, null, 2), 4000);
+  emit('scan.progress', { files: snapshot.totalFiles, bytes: snapshot.totalBytes, cacheHits: snapshot.cacheHits, planning: true });
+  const prompt = `Create a token-efficient READ plan for the repository task below. Do not solve the task, request source tools, or modify the workspace. Use the compact notebook catalog as orientation only. Plan the post-Scan cumulative token budget and the smallest set of files that formal READ should verify. Submit exactly one COMMIT_CONTEXT_PLAN tool call.
+
+The call should prefer this v2 shape:
+{"contextBudgetTokens":number,"turnBudgetTokens":number,"files":[{"path":string,"reason":string,"strategy":"outline|targeted|full","required":boolean,"estimatedTokens":number}],"notebook":{"action":"reuse|build|update","sections":[string],"notebookBudgetTokens":number},"rationale":string}
+
+REQUEST:
+${capEstimatedTokens(request, 800)}
+
+RECENT CONVERSATION SUMMARY (untrusted):
+${capEstimatedTokens(conversationContext || '(none)', 800)}
+
+RELEVANT MEMORY (untrusted):
+${capEstimatedTokens(memories || '(none)', 500)}
+
+COMPACT SCAN EVIDENCE:
+${summary}`;
+  let rawPlan = null;
+  let legacyReply = '';
+  let commitCount = 0;
+  const scanUsage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+  try {
+    for await (const event of modelRunner([{ role: 'user', content: prompt }], {
+      profile, stream: false, mode: 'scan', workspaceRoot, signal, lang,
+      maxOutputTokens: 800, usagePhase: 'scan'
+    })) {
+      if (event.type === 'model.tool_call' && event.data?.name === 'COMMIT_CONTEXT_PLAN') {
+        commitCount++;
+        rawPlan = event.data.arguments || {};
+      }
+      if (event.type === 'model.delta') legacyReply += event.data?.text || '';
+      if (event.type === 'model.completed') {
+        scanUsage.inputTokens += Number(event.data?.inputTokens) || 0;
+        scanUsage.outputTokens += Number(event.data?.outputTokens) || 0;
+        scanUsage.totalTokens = scanUsage.inputTokens + scanUsage.outputTokens;
+      }
+    }
+    if (!rawPlan && legacyReply.trim()) {
+      const match = legacyReply.trim().match(/^<<COMMIT_CONTEXT_PLAN:\s*(\{[\s\S]*\})>>$/);
+      try { rawPlan = JSON.parse(match ? match[1] : legacyReply.trim()); } catch {}
+    }
+    if (commitCount > 1) throw new Error('Scan model committed more than one context plan.');
+    if (!rawPlan) throw new Error('Scan model did not commit a context plan.');
+    const contextPlan = normalizeContextPlan(rawPlan, snapshot, profile, request, {
+      notebookAvailable: Boolean(existingNotebook?.content),
+      notebookStatus: existingNotebook?.status || 'missing',
+      notebookMaturity: existingNotebook?.maturity || 'complete',
+      drift: drift?.changes || []
+    });
+    emit('context.planned', { contextPlan, scanUsage });
+    emit('scan.completed', { snapshot, contextPlan, notebookAction: contextPlan.notebook.action, scanUsage });
+    return {
+      snapshot, contextPlan, summary, notebook: existingNotebook,
+      notebookAction: contextPlan.notebook.action, notebookDrift: drift, scanUsage
+    };
+  } catch (error) {
+    if (signal?.aborted) throw error;
+    const terms = requestTerms(request);
+    const fallbackFiles = snapshot.files
+      .filter(file => !file.sensitive && (
+        /entry point|manifest|configuration/i.test(file.purpose)
+        || terms.some(term => file.path.toLowerCase().includes(term))
+      ))
+      .slice(0, 12)
+      .map((file, index) => ({
+        path: file.path,
+        reason: index === 0 ? 'Likely task entry point.' : 'Metadata-selected task evidence.',
+        strategy: file.size > 56000 ? 'outline' : 'targeted',
+        required: index < 3,
+        estimatedTokens: Math.max(100, Math.ceil(Math.min(file.size, 24000) / 4))
+      }));
+    const contextPlan = normalizeContextPlan({
+      degraded: true,
+      rationale: `Scan planning degraded: ${error.message}`,
+      files: fallbackFiles,
+      notebook: {
+        action: !existingNotebook ? 'build' : ((drift?.changes?.length || notebookMode === 'rebuild') ? 'update' : 'reuse'),
+        sections: [],
+        notebookBudgetTokens: existingNotebook ? 0 : 1600
+      }
+    }, snapshot, profile, request, {
+      notebookAvailable: Boolean(existingNotebook?.content),
+      notebookStatus: existingNotebook?.status || 'missing',
+      notebookMaturity: existingNotebook?.maturity || 'complete',
+      drift: drift?.changes || []
+    });
+    emit('scan.degraded', { error: error.message, snapshot, contextPlan, scanUsage });
+    return {
+      snapshot, contextPlan, summary, notebook: existingNotebook,
+      notebookAction: contextPlan.notebook.action, notebookDrift: drift, scanUsage
+    };
+  }
+}