memorix 1.1.13 → 1.2.1

package/src/codegraph/lite-provider.ts

@@ -1,7 +1,8 @@
 import { createHash } from 'node:crypto';
 import { readdirSync, readFileSync, statSync, type Dirent } from 'node:fs';
 import { join, relative } from 'node:path';
-import type { CodeEdge, CodeFile, CodeSymbol } from './types.js';
+import type { CodeEdge, CodeFile, CodeStateSnapshot, CodeSymbol } from './types.js';
+import { collectCodeStateSnapshot } from './code-state.js';
 import { makeCodeEdgeId, makeCodeFileId, makeCodeSymbolId, normalizeCodePath } from './ids.js';
 import { isCodeGraphExcludedPath, normalizeCodeGraphExcludePatterns } from './exclude.js';
 import { CodeGraphStore, type CodeGraphFileDelta } from './store.js';
@@ -19,6 +20,7 @@ export interface LiteIndexResult {
   symbols: CodeSymbol[];
   edges: CodeEdge[];
   skippedOversizedFiles: number;
+  unreadableFiles: number;
 }
 
 export interface LiteRefreshResult {
@@ -30,7 +32,9 @@ export interface LiteRefreshResult {
   indexedSymbols: number;
   indexedEdges: number;
   skippedOversizedFiles: number;
+  unreadableFiles: number;
   removalScanDeferred: boolean;
+  snapshot: CodeStateSnapshot;
 }
 
 export const DEFAULT_CODEGRAPH_MAX_FILE_BYTES = 2 * 1024 * 1024;
@@ -299,13 +303,18 @@ function extractImportEdges(projectId: string, file: CodeFile, text: string, ind
   return edges;
 }
 
+interface LiteFileIndexAttempt {
+  delta?: CodeGraphFileDelta;
+  unreadable: boolean;
+}
+
 function indexFileLite(
   projectId: string,
   projectRoot: string,
   abs: string,
   indexedAt: string,
   fileStat?: ReturnType<typeof statSync>,
-): CodeGraphFileDelta | undefined {
+): LiteFileIndexAttempt {
   const rel = normalizeCodePath(relative(projectRoot, abs));
   try {
     const text = readFileSync(abs, 'utf-8');
@@ -316,17 +325,22 @@ function indexFileLite(
       path: rel,
       language: languageForPath(rel),
       contentHash: hashText(text),
-      mtimeMs: Math.round(Number(stat.mtimeMs)),
+      // Preserve filesystem precision. Rounding here made same-size edits in
+      // a short Windows timestamp window indistinguishable to refresh.
+      mtimeMs: Number(stat.mtimeMs),
       sizeBytes: Number(stat.size),
       indexedAt,
     };
     return {
-      file,
-      symbols: extractSymbols(projectId, file, text, indexedAt),
-      edges: extractImportEdges(projectId, file, text, indexedAt),
+      delta: {
+        file,
+        symbols: extractSymbols(projectId, file, text, indexedAt),
+        edges: extractImportEdges(projectId, file, text, indexedAt),
+      },
+      unreadable: false,
     };
   } catch {
-    return undefined;
+    return { unreadable: true };
   }
 }
 
@@ -340,26 +354,31 @@ export async function indexProjectLite(options: LiteIndexOptions): Promise<LiteI
   const symbols: CodeSymbol[] = [];
   const edges: CodeEdge[] = [];
   let skippedOversizedFiles = 0;
+  let unreadableFiles = 0;
 
   for (const abs of paths) {
     let stat: ReturnType<typeof statSync>;
     try {
       stat = statSync(abs);
     } catch {
+      unreadableFiles++;
       continue;
     }
     if (Number(stat.size) > maxFileBytes) {
       skippedOversizedFiles++;
       continue;
     }
-    const delta = indexFileLite(options.projectId, options.projectRoot, abs, indexedAt, stat);
-    if (!delta) continue;
-    files.push(delta.file);
-    symbols.push(...delta.symbols);
-    edges.push(...delta.edges);
+    const attempt = indexFileLite(options.projectId, options.projectRoot, abs, indexedAt, stat);
+    if (!attempt.delta) {
+      if (attempt.unreadable) unreadableFiles++;
+      continue;
+    }
+    files.push(attempt.delta.file);
+    symbols.push(...attempt.delta.symbols);
+    edges.push(...attempt.delta.edges);
   }
 
-  return { files, symbols, edges, skippedOversizedFiles };
+  return { files, symbols, edges, skippedOversizedFiles, unreadableFiles };
 }
 
 /**
@@ -382,31 +401,38 @@ export async function refreshProjectLite(
   const oversizedExistingFileIds = new Set<string>();
   let unchangedFiles = 0;
   let skippedOversizedFiles = 0;
+  let unreadableFiles = 0;
 
   for (const abs of paths) {
     const rel = normalizeCodePath(relative(options.projectRoot, abs));
+    // A discovered but temporarily unreadable path is not deletion evidence.
+    seenPaths.add(rel);
     let stat: ReturnType<typeof statSync>;
     try {
       stat = statSync(abs);
     } catch {
+      unreadableFiles++;
       continue;
     }
-    seenPaths.add(rel);
     const existing = existingByPath.get(rel);
-    const roundedMtime = Math.round(Number(stat.mtimeMs));
+    const mtimeMs = Number(stat.mtimeMs);
     const sizeBytes = Number(stat.size);
     if (sizeBytes > maxFileBytes) {
       skippedOversizedFiles++;
       if (existing) oversizedExistingFileIds.add(existing.id);
       continue;
     }
-    if (existing && existing.mtimeMs === roundedMtime && existing.sizeBytes === sizeBytes) {
+    if (existing && existing.mtimeMs === mtimeMs && existing.sizeBytes === sizeBytes) {
       unchangedFiles++;
       continue;
     }
 
-    const delta = indexFileLite(options.projectId, options.projectRoot, abs, indexedAt, stat);
-    if (!delta) continue;
+    const attempt = indexFileLite(options.projectId, options.projectRoot, abs, indexedAt, stat);
+    if (!attempt.delta) {
+      if (attempt.unreadable) unreadableFiles++;
+      continue;
+    }
+    const delta = attempt.delta;
     if (existing?.contentHash === delta.file.contentHash) {
       metadataOnly.push(delta.file);
       unchangedFiles++;
@@ -430,7 +456,24 @@ export async function refreshProjectLite(
     metadataOnly,
     removedFileIds,
   });
-
+  const completeness = {
+    scannedFiles: paths.length,
+    maxFiles,
+    changedFiles: changed.length,
+    unchangedFiles,
+    metadataOnlyFiles: metadataOnly.length,
+    removedFiles: removedFileIds.length,
+    skippedOversizedFiles,
+    unreadableFiles,
+    removalScanDeferred,
+  };
+  const snapshot = store.recordCodeStateSnapshot(await collectCodeStateSnapshot({
+    projectId: options.projectId,
+    projectRoot: options.projectRoot,
+    provider: 'lite',
+    indexedAt,
+    completeness,
+  }));
   return {
     scannedFiles: paths.length,
     changedFiles: changed.length,
@@ -440,6 +483,8 @@ export async function refreshProjectLite(
     indexedSymbols: changed.reduce((total, delta) => total + delta.symbols.length, 0),
     indexedEdges: changed.reduce((total, delta) => total + delta.edges.length, 0),
     skippedOversizedFiles,
+    unreadableFiles,
     removalScanDeferred,
+    snapshot,
   };
 }

package/src/codegraph/project-context.ts

@@ -1,6 +1,12 @@
 import type { ProjectInfo } from '../types.js';
 import { evaluateCodeRefFreshness } from './freshness.js';
-import type { CodeFile, CodeRefStatus, CodeSymbol, ObservationCodeRef } from './types.js';
+import type {
+  CodeFile,
+  CodeRefStatus,
+  CodeStateSnapshot,
+  CodeSymbol,
+  ObservationCodeRef,
+} from './types.js';
 import type { CodeGraphStore } from './store.js';
 import { isCodeGraphExcludedPath } from './exclude.js';
 
@@ -31,6 +37,7 @@ export interface ProjectContextOverview {
     refs: number;
     indexedAt?: string;
     languages: LanguageSummary[];
+    latestSnapshot?: CodeStateSnapshot;
   };
   memory: {
     total: number;
@@ -196,6 +203,7 @@ function overviewFromGraph(input: {
       refs: status.refs,
       ...(status.indexedAt ? { indexedAt: status.indexedAt } : {}),
       languages: countLanguages(input.graph.files),
+      ...(status.latestSnapshot ? { latestSnapshot: status.latestSnapshot } : {}),
     },
     memory: {
       total: input.observations.filter(obs => obs.projectId === input.project.id).length,

package/src/codegraph/store.ts

@@ -1,5 +1,15 @@
+import { randomUUID } from 'node:crypto';
 import { getDatabase } from '../store/sqlite-db.js';
-import type { CodeEdge, CodeFile, CodeGraphStatus, CodeSymbol, ObservationCodeRef } from './types.js';
+import type {
+  CodeEdge,
+  CodeFile,
+  CodeGraphStatus,
+  CodeStateScanCompleteness,
+  CodeStateSnapshot,
+  CodeStateSnapshotInput,
+  CodeSymbol,
+  ObservationCodeRef,
+} from './types.js';
 import { normalizeCodePath } from './ids.js';
 
 export interface CodeGraphFileDelta {
@@ -19,6 +29,8 @@ function rowToFile(row: any): CodeFile {
     ...(row.sizeBytes != null ? { sizeBytes: row.sizeBytes } : {}),
     indexedAt: row.indexedAt,
     ...(row.gitCommit ? { gitCommit: row.gitCommit } : {}),
+    ...(row.snapshotId ? { snapshotId: row.snapshotId } : {}),
+    ...(row.sourceEpoch != null ? { sourceEpoch: Number(row.sourceEpoch) } : {}),
   };
 }
 
@@ -37,6 +49,8 @@ function rowToSymbol(row: any): CodeSymbol {
     ...(row.contentHash ? { contentHash: row.contentHash } : {}),
     indexedAt: row.indexedAt,
     stale: !!row.stale,
+    ...(row.snapshotId ? { snapshotId: row.snapshotId } : {}),
+    ...(row.sourceEpoch != null ? { sourceEpoch: Number(row.sourceEpoch) } : {}),
   } as CodeSymbol;
 }
 
@@ -52,6 +66,8 @@ function rowToEdge(row: any): CodeEdge {
     confidence: row.confidence,
     ...(row.evidence ? { evidence: row.evidence } : {}),
     indexedAt: row.indexedAt,
+    ...(row.snapshotId ? { snapshotId: row.snapshotId } : {}),
+    ...(row.sourceEpoch != null ? { sourceEpoch: Number(row.sourceEpoch) } : {}),
   } as CodeEdge;
 }
 
@@ -68,16 +84,71 @@ function rowToRef(row: any): ObservationCodeRef {
     ...(row.reason ? { reason: row.reason } : {}),
     createdAt: row.createdAt,
     ...(row.updatedAt ? { updatedAt: row.updatedAt } : {}),
+    ...(row.snapshotId ? { snapshotId: row.snapshotId } : {}),
   } as ObservationCodeRef;
 }
 
+function parseCompleteness(raw: unknown): CodeStateScanCompleteness {
+  try {
+    const parsed = typeof raw === 'string' ? JSON.parse(raw) : raw;
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('invalid completeness');
+    return {
+      scannedFiles: Number((parsed as any).scannedFiles) || 0,
+      maxFiles: Number((parsed as any).maxFiles) || 0,
+      changedFiles: Number((parsed as any).changedFiles) || 0,
+      unchangedFiles: Number((parsed as any).unchangedFiles) || 0,
+      metadataOnlyFiles: Number((parsed as any).metadataOnlyFiles) || 0,
+      removedFiles: Number((parsed as any).removedFiles) || 0,
+      skippedOversizedFiles: Number((parsed as any).skippedOversizedFiles) || 0,
+      unreadableFiles: Number((parsed as any).unreadableFiles) || 0,
+      removalScanDeferred: Boolean((parsed as any).removalScanDeferred),
+    };
+  } catch {
+    return {
+      scannedFiles: 0,
+      maxFiles: 0,
+      changedFiles: 0,
+      unchangedFiles: 0,
+      metadataOnlyFiles: 0,
+      removedFiles: 0,
+      skippedOversizedFiles: 0,
+      unreadableFiles: 0,
+      removalScanDeferred: false,
+    };
+  }
+}
+
+function rowToSnapshot(row: any): CodeStateSnapshot {
+  return {
+    id: row.id,
+    projectId: row.projectId,
+    provider: row.provider,
+    ...(row.baseRevision ? { baseRevision: row.baseRevision } : {}),
+    worktreeFingerprint: row.worktreeFingerprint,
+    worktreeState: row.worktreeState,
+    changedPathCount: Number(row.changedPathCount),
+    indexedAt: row.indexedAt,
+    sourceEpoch: Number(row.sourceEpoch),
+    completeness: parseCompleteness(row.completenessJson),
+    ...(row.previousSnapshotId ? { previousSnapshotId: row.previousSnapshotId } : {}),
+  } as CodeStateSnapshot;
+}
+
 export class CodeGraphStore {
   private db: any = null;
+  private dataDir: string | null = null;
 
   async init(dataDir: string): Promise<void> {
+    this.dataDir = dataDir;
     this.db = getDatabase(dataDir);
   }
 
+  /** Data directory shared with the rest of the local project evidence stores. */
+  getDataDir(): string {
+    if (!this.dataDir) throw new Error('CodeGraphStore is not initialized');
+    return this.dataDir;
+  }
+
   upsertFiles(files: CodeFile[]): void {
     if (files.length === 0) return;
     const stmt = this.db.prepare(`
@@ -364,9 +435,9 @@ export class CodeGraphStore {
     if (refs.length === 0) return;
     const stmt = this.db.prepare(`
       INSERT OR REPLACE INTO observation_code_refs
-        (id, projectId, observationId, fileId, symbolId, capturedFileHash, capturedSymbolHash, status, reason, createdAt, updatedAt)
+        (id, projectId, observationId, fileId, symbolId, capturedFileHash, capturedSymbolHash, status, reason, createdAt, updatedAt, snapshotId)
       VALUES
-        (@id, @projectId, @observationId, @fileId, @symbolId, @capturedFileHash, @capturedSymbolHash, @status, @reason, @createdAt, @updatedAt)
+        (@id, @projectId, @observationId, @fileId, @symbolId, @capturedFileHash, @capturedSymbolHash, @status, @reason, @createdAt, @updatedAt, @snapshotId)
     `);
     const tx = this.db.transaction((items: ObservationCodeRef[]) => {
       for (const ref of items) {
@@ -382,6 +453,7 @@ export class CodeGraphStore {
           reason: ref.reason ?? null,
           createdAt: ref.createdAt,
           updatedAt: ref.updatedAt ?? null,
+          snapshotId: ref.snapshotId ?? this.latestSnapshot(ref.projectId)?.id ?? null,
         });
       }
     });
@@ -395,9 +467,9 @@ export class CodeGraphStore {
     `);
     const insertRef = this.db.prepare(`
       INSERT OR REPLACE INTO observation_code_refs
-        (id, projectId, observationId, fileId, symbolId, capturedFileHash, capturedSymbolHash, status, reason, createdAt, updatedAt)
+        (id, projectId, observationId, fileId, symbolId, capturedFileHash, capturedSymbolHash, status, reason, createdAt, updatedAt, snapshotId)
       VALUES
-        (@id, @projectId, @observationId, @fileId, @symbolId, @capturedFileHash, @capturedSymbolHash, @status, @reason, @createdAt, @updatedAt)
+        (@id, @projectId, @observationId, @fileId, @symbolId, @capturedFileHash, @capturedSymbolHash, @status, @reason, @createdAt, @updatedAt, @snapshotId)
     `);
     const tx = this.db.transaction(() => {
       deleteRefs.run(projectId, observationId);
@@ -414,6 +486,7 @@ export class CodeGraphStore {
           reason: ref.reason ?? null,
           createdAt: ref.createdAt,
           updatedAt: ref.updatedAt ?? null,
+          snapshotId: ref.snapshotId ?? this.latestSnapshot(ref.projectId)?.id ?? null,
         });
       }
     });
@@ -514,12 +587,87 @@ export class CodeGraphStore {
     `).all(projectId, projectId).map(rowToSymbol);
   }
 
+  latestSnapshot(projectId: string): CodeStateSnapshot | undefined {
+    const row = this.db.prepare(
+      'SELECT * FROM code_state_snapshots WHERE projectId = ? ORDER BY sourceEpoch DESC LIMIT 1',
+    ).get(projectId);
+    return row ? rowToSnapshot(row) : undefined;
+  }
+
+  listSnapshots(projectId: string, limit = 20): CodeStateSnapshot[] {
+    const safeLimit = Number.isFinite(limit) ? Math.max(1, Math.min(200, Math.floor(limit))) : 20;
+    return this.db.prepare(
+      'SELECT * FROM code_state_snapshots WHERE projectId = ? ORDER BY sourceEpoch DESC LIMIT ?',
+    ).all(projectId, safeLimit).map(rowToSnapshot);
+  }
+
+  /**
+   * Record a completed scan and mark all current structural facts with its
+   * epoch. The snapshot is written only after refresh reconciliation succeeds,
+   * so an interrupted scan cannot be advertised as complete.
+   */
+  recordCodeStateSnapshot(input: CodeStateSnapshotInput): CodeStateSnapshot {
+    const id = randomUUID();
+    let snapshot: CodeStateSnapshot | undefined;
+    const tx = this.db.transaction(() => {
+      const previous = this.db.prepare(
+        'SELECT id, sourceEpoch FROM code_state_snapshots WHERE projectId = ? ORDER BY sourceEpoch DESC LIMIT 1',
+      ).get(input.projectId);
+      const sourceEpoch = Number(previous?.sourceEpoch ?? 0) + 1;
+      const previousSnapshotId = previous?.id as string | undefined;
+      this.db.prepare(
+        'INSERT INTO code_state_snapshots (id, projectId, provider, baseRevision, worktreeFingerprint, worktreeState, changedPathCount, indexedAt, sourceEpoch, completenessJson, previousSnapshotId) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)',
+      ).run(
+        id,
+        input.projectId,
+        input.provider,
+        input.baseRevision ?? null,
+        input.worktreeFingerprint,
+        input.worktreeState,
+        input.changedPathCount,
+        input.indexedAt,
+        sourceEpoch,
+        JSON.stringify(input.completeness),
+        previousSnapshotId ?? null,
+      );
+      this.db.prepare(
+        'UPDATE code_files SET snapshotId = ?, sourceEpoch = ?, gitCommit = COALESCE(?, gitCommit) WHERE projectId = ?',
+      ).run(id, sourceEpoch, input.baseRevision ?? null, input.projectId);
+      this.db.prepare(
+        'UPDATE code_symbols SET snapshotId = ?, sourceEpoch = ? WHERE projectId = ? AND stale = 0',
+      ).run(id, sourceEpoch, input.projectId);
+      this.db.prepare(
+        'UPDATE code_edges SET snapshotId = ?, sourceEpoch = ? WHERE projectId = ?',
+      ).run(id, sourceEpoch, input.projectId);
+      this.db.prepare(
+        "UPDATE observation_code_refs SET snapshotId = ? WHERE projectId = ? AND status = 'current'",
+      ).run(id, input.projectId);
+      snapshot = {
+        ...input,
+        id,
+        sourceEpoch,
+        ...(previousSnapshotId ? { previousSnapshotId } : {}),
+      };
+    });
+    tx();
+    return snapshot!;
+  }
+
   status(projectId: string): CodeGraphStatus {
     const files = this.db.prepare(`SELECT COUNT(*) AS count FROM code_files WHERE projectId = ?`).get(projectId).count;
     const symbols = this.db.prepare(`SELECT COUNT(*) AS count FROM code_symbols WHERE projectId = ? AND stale = 0`).get(projectId).count;
     const edges = this.db.prepare(`SELECT COUNT(*) AS count FROM code_edges WHERE projectId = ?`).get(projectId).count;
     const refs = this.db.prepare(`SELECT COUNT(*) AS count FROM observation_code_refs WHERE projectId = ?`).get(projectId).count;
     const latest = this.db.prepare(`SELECT MAX(indexedAt) AS indexedAt FROM code_files WHERE projectId = ?`).get(projectId);
-    return { provider: 'lite', files, symbols, edges, refs, ...(latest?.indexedAt ? { indexedAt: latest.indexedAt } : {}) };
+    const latestSnapshot = this.latestSnapshot(projectId);
+    return {
+      provider: 'lite',
+      files,
+      symbols,
+      edges,
+      refs,
+      ...(latest?.indexedAt ? { indexedAt: latest.indexedAt } : {}),
+      ...(latestSnapshot ? { latestSnapshot } : {}),
+    };
   }
 }

package/src/codegraph/task-lens.ts

@@ -115,6 +115,7 @@ const KEYWORDS: Record<Exclude<TaskLensId, 'general'>, string[]> = {
   bugfix: [
     'bug',
     'crash',
+    'incident',
     'debug',
     'error',
     'fail',
@@ -125,6 +126,7 @@ const KEYWORDS: Record<Exclude<TaskLensId, 'general'>, string[]> = {
     'repro',
     '报错',
     '崩溃',
+    '故障',
     '失败',
     '修复',
     '问题',
@@ -157,11 +159,53 @@ function tokenize(text: string): string[] {
     .filter(token => token.length > 1 && !STOP_WORDS.has(token));
 }
 
-function containsKeyword(text: string, keyword: string): boolean {
-  if (/^[a-z0-9_-]+$/i.test(keyword)) {
-    return new RegExp(`(^|[^a-z0-9_-])${keyword.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}([^a-z0-9_-]|$)`, 'i').test(text);
+/**
+ * Match a task keyword only when the task states it as an action or intent,
+ * rather than prohibiting that action. Workflow selection shares this rule so
+ * a safety constraint cannot reintroduce an intent rejected by task routing.
+ */
+export function containsTaskKeyword(text: string, keyword: string): boolean {
+  const matcher = /^[a-z0-9_-]+$/i.test(keyword)
+    ? new RegExp(`(^|[^a-z0-9_-])${keyword.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?=[^a-z0-9_-]|$)`, 'gi')
+    : new RegExp(keyword.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'gi');
+  let match: RegExpExecArray | null;
+  while ((match = matcher.exec(text)) !== null) {
+    const keywordIndex = match.index + (match[1]?.length ?? 0);
+    if (!isNegatedTaskKeyword(text, keywordIndex)) return true;
   }
-  return text.includes(keyword);
+  return false;
+}
+
+/**
+ * Task text often carries safety constraints such as "do not publish". Those
+ * constraints must not route a debugging task into the release workflow.
+ * Keep this deliberately small and local: it only suppresses a keyword inside
+ * the same sentence when the sentence explicitly negates an action.
+ */
+function isNegatedTaskKeyword(text: string, keywordIndex: number): boolean {
+  const boundary = Math.max(
+    text.lastIndexOf('.', keywordIndex - 1),
+    text.lastIndexOf('!', keywordIndex - 1),
+    text.lastIndexOf('?', keywordIndex - 1),
+    text.lastIndexOf(';', keywordIndex - 1),
+    text.lastIndexOf('\n', keywordIndex - 1),
+    text.lastIndexOf('\u3002', keywordIndex - 1),
+    text.lastIndexOf('\uff01', keywordIndex - 1),
+    text.lastIndexOf('\uff1f', keywordIndex - 1),
+    text.lastIndexOf('\uff1b', keywordIndex - 1),
+  );
+  let prefix = text.slice(boundary + 1, keywordIndex).toLowerCase();
+  const contrast = /(?:,|\uff0c)\s*(?:but|however|instead|yet|\u4f46\u662f|\u4f46|\u800c\u662f)\s*/gi;
+  let contrastMatch: RegExpExecArray | null;
+  let contrastEnd = -1;
+  while ((contrastMatch = contrast.exec(prefix)) !== null) contrastEnd = contrast.lastIndex;
+  if (contrastEnd >= 0) prefix = prefix.slice(contrastEnd);
+  if (/\b(?:do|does|did|should|must|can|could|will|would|may|might)\s+not\b/.test(prefix)) return true;
+  if (/\b(?:don't|dont|never|without|avoid|skip)\b/.test(prefix)) return true;
+  if (/(?:^|[\s,])no\s+(?:[a-z0-9_-]+\s*){0,4}$/i.test(prefix)) return true;
+  const chineseClauseStart = Math.max(prefix.lastIndexOf(','), prefix.lastIndexOf('\uff0c'), prefix.lastIndexOf('\u3001'));
+  const chineseClause = prefix.slice(chineseClauseStart + 1);
+  return /(?:\u4e0d\u8981|\u4e0d\u5e94|\u4e0d\u53ef|\u4e0d\u80fd|\u4e0d\u4f1a|\u7981\u6b62|\u52ff|\u4e0d)\s*(?:\u7acb\u5373|\u76f4\u63a5|\u518d|\u73b0\u5728|\u64c5\u81ea|\u5148)?\s*$/.test(chineseClause);
 }
 
 export function resolveTaskLens(task?: string): TaskLens {
@@ -175,7 +219,7 @@ export function resolveTaskLens(task?: string): TaskLens {
   };
 
   for (const id of LENS_PRIORITY) {
-    const score = KEYWORDS[id].reduce((sum, keyword) => sum + (containsKeyword(normalized, keyword) ? 1 : 0), 0);
+    const score = KEYWORDS[id].reduce((sum, keyword) => sum + (containsTaskKeyword(normalized, keyword) ? 1 : 0), 0);
     const priority = LENS_PRIORITY.indexOf(id);
     if (score > best.score || (score === best.score && score > 0 && priority < best.priority)) {
       best = { id, score, priority };

package/src/codegraph/types.ts

@@ -32,6 +32,8 @@ export interface CodeFile {
   sizeBytes?: number;
   indexedAt: string;
   gitCommit?: string;
+  snapshotId?: string;
+  sourceEpoch?: number;
 }
 
 export interface CodeSymbol {
@@ -48,6 +50,8 @@ export interface CodeSymbol {
   contentHash?: string;
   indexedAt: string;
   stale?: boolean;
+  snapshotId?: string;
+  sourceEpoch?: number;
 }
 
 export interface CodeEdge {
@@ -61,6 +65,8 @@ export interface CodeEdge {
   confidence: number;
   evidence?: string;
   indexedAt: string;
+  snapshotId?: string;
+  sourceEpoch?: number;
 }
 
 export interface ObservationCodeRef {
@@ -75,6 +81,39 @@ export interface ObservationCodeRef {
   reason?: string;
   createdAt: string;
   updatedAt?: string;
+  snapshotId?: string;
+}
+
+export type CodeStateWorktreeState = 'clean' | 'dirty' | 'unavailable';
+
+export interface CodeStateScanCompleteness {
+  scannedFiles: number;
+  maxFiles: number;
+  changedFiles: number;
+  unchangedFiles: number;
+  metadataOnlyFiles: number;
+  removedFiles: number;
+  skippedOversizedFiles: number;
+  /** Source paths discovered but unavailable for stat/read during this scan. */
+  unreadableFiles?: number;
+  removalScanDeferred: boolean;
+}
+
+export interface CodeStateSnapshotInput {
+  projectId: string;
+  provider: CodeGraphProviderKind;
+  baseRevision?: string;
+  worktreeFingerprint: string;
+  worktreeState: CodeStateWorktreeState;
+  changedPathCount: number;
+  indexedAt: string;
+  completeness: CodeStateScanCompleteness;
+}
+
+export interface CodeStateSnapshot extends CodeStateSnapshotInput {
+  id: string;
+  sourceEpoch: number;
+  previousSnapshotId?: string;
 }
 
 export interface CodeGraphStatus {
@@ -84,4 +123,82 @@ export interface CodeGraphStatus {
   edges: number;
   refs: number;
   indexedAt?: string;
+  latestSnapshot?: CodeStateSnapshot;
+}
+
+/** Policy for using a separately installed, local semantic CodeGraph index. */
+export type CodeGraphExternalMode = 'auto' | 'off';
+
+/**
+ * The external provider state is deliberately more precise than a boolean.
+ * A caller can distinguish an absent optional tool from a stale or invalid
+ * result without treating either as a fatal failure for Code Memory.
+ */
+export type ExternalCodeGraphState =
+  | 'disabled'
+  | 'not-detected'
+  | 'unavailable'
+  | 'not-initialized'
+  | 'stale'
+  | 'timed-out'
+  | 'invalid'
+  | 'ready';
+
+export interface ExternalCodeGraphHealth {
+  state: ExternalCodeGraphState;
+  reason?: string;
+  indexedFiles?: number;
+  indexedNodes?: number;
+  indexedEdges?: number;
+  languages?: string[];
+}
+
+export interface CodeGraphProviderQuality {
+  /** Provider that contributed task-scoped code evidence to this response. */
+  selected: CodeGraphProviderKind;
+  /** Lite is heuristic; external outlines are only semantic after validation. */
+  selectedQuality: 'heuristic' | 'semantic';
+  mode: CodeGraphExternalMode;
+  lite: {
+    quality: 'heuristic';
+    capabilities: {
+      declarations: boolean;
+      importHints: boolean;
+      resolvedRelations: false;
+      exactLocations: false;
+    };
+    supportedLanguages: string[];
+  };
+  external: ExternalCodeGraphHealth;
+}
+
+export interface ExternalCodeGraphSymbol {
+  id: string;
+  name: string;
+  qualifiedName?: string;
+  kind: string;
+  path: string;
+  startLine?: number;
+  endLine?: number;
+  language?: string;
+}
+
+export interface ExternalCodeGraphRelation {
+  from: ExternalCodeGraphSymbol;
+  to: ExternalCodeGraphSymbol;
+  kind: string;
+  line?: number;
+}
+
+/** A bounded, non-source-code semantic outline returned for one task. */
+export interface ExternalCodeGraphOutline {
+  provider: 'external';
+  entryPoints: ExternalCodeGraphSymbol[];
+  relations: ExternalCodeGraphRelation[];
+  relatedFiles: string[];
+  stats: {
+    nodes: number;
+    edges: number;
+    files: number;
+  };
 }