@soleri/core 9.14.4 → 9.15.0

package/dist/vault/default-canonical-tags.js

@@ -0,0 +1,65 @@
+/**
+ * Default canonical tag taxonomy for Soleri agents.
+ *
+ * These tags represent the most common knowledge domains. When a vault is
+ * configured with tagConstraintMode 'suggest' or 'enforce', incoming tags
+ * are mapped to the nearest entry in this list via edit-distance matching.
+ *
+ * To use these defaults in your agent runtime config:
+ *   import { DEFAULT_CANONICAL_TAGS } from '@soleri/core';
+ *   // ...
+ *   canonicalTags: DEFAULT_CANONICAL_TAGS,
+ *   tagConstraintMode: 'suggest',
+ */
+export const DEFAULT_CANONICAL_TAGS = [
+    'architecture',
+    'typescript',
+    'react',
+    'testing',
+    'workflow',
+    'design-tokens',
+    'accessibility',
+    'performance',
+    'security',
+    'planning',
+    'soleri',
+    'vault',
+    'mcp',
+    'claude-code',
+    'ai',
+    'learning',
+    'gamification',
+    'education',
+    'adhd',
+    'routing',
+    'orchestration',
+    'skills',
+    'automation',
+    'git',
+    'database',
+    'api',
+    'authentication',
+    'subagent',
+    'design-system',
+    'component',
+    'frontend',
+    'backend',
+    'tooling',
+    'monorepo',
+    'refactoring',
+    'debugging',
+    'deployment',
+    'configuration',
+    'documentation',
+    'pattern',
+    'anti-pattern',
+    'principle',
+    'decision',
+    'migration',
+    'plugin',
+    'hook',
+    'schema',
+    'pipeline',
+    'ingestion',
+];
+//# sourceMappingURL=default-canonical-tags.js.map

package/dist/vault/default-canonical-tags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-canonical-tags.js","sourceRoot":"","sources":["../../src/vault/default-canonical-tags.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAa;IAC9C,cAAc;IACd,YAAY;IACZ,OAAO;IACP,SAAS;IACT,UAAU;IACV,eAAe;IACf,eAAe;IACf,aAAa;IACb,UAAU;IACV,UAAU;IACV,QAAQ;IACR,OAAO;IACP,KAAK;IACL,aAAa;IACb,IAAI;IACJ,UAAU;IACV,cAAc;IACd,WAAW;IACX,MAAM;IACN,SAAS;IACT,eAAe;IACf,QAAQ;IACR,YAAY;IACZ,KAAK;IACL,UAAU;IACV,KAAK;IACL,gBAAgB;IAChB,UAAU;IACV,eAAe;IACf,WAAW;IACX,UAAU;IACV,SAAS;IACT,SAAS;IACT,UAAU;IACV,aAAa;IACb,WAAW;IACX,YAAY;IACZ,eAAe;IACf,eAAe;IACf,SAAS;IACT,cAAc;IACd,WAAW;IACX,UAAU;IACV,WAAW;IACX,QAAQ;IACR,MAAM;IACN,QAAQ;IACR,UAAU;IACV,WAAW;CACZ,CAAC"}

package/dist/vault/tag-normalizer.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Tag Normalizer — canonical tag taxonomy enforcement.
+ *
+ * Maps raw tags to nearest canonical via Levenshtein edit-distance.
+ * Strips noise words (version strings, single generic words).
+ * Respects metadata tag prefixes (e.g. 'source:').
+ *
+ * Three modes:
+ *   - 'enforce': must match within edit-distance 3, else drop (return null)
+ *   - 'suggest': map to nearest canonical within edit-distance 2 (passthrough if no match)
+ *   - 'off':     no normalization — return tag as-is
+ */
+/**
+ * Compute Levenshtein edit distance between two strings.
+ * O(m*n) time, O(n) space using two-row DP.
+ */
+export declare function computeEditDistance(a: string, b: string): number;
+/**
+ * Returns true if the tag starts with any of the given prefixes.
+ * Metadata tags (e.g. 'source:article') are exempt from canonical normalization.
+ */
+export declare function isMetadataTag(tag: string, prefixes: string[]): boolean;
+/**
+ * Normalize a single tag against a canonical list.
+ *
+ * @param tag       - Raw tag to normalize
+ * @param canonical - Canonical tag list to map against
+ * @param mode      - Constraint mode: 'enforce' | 'suggest' | 'off'
+ * @returns Normalized tag string, or null if the tag should be dropped.
+ */
+export declare function normalizeTag(tag: string, canonical: string[], mode: 'enforce' | 'suggest' | 'off'): string | null;
+/**
+ * Normalize a batch of tags against a canonical list.
+ * Filters out nulls (dropped tags). Deduplicates the result.
+ *
+ * @param tags              - Raw tags
+ * @param canonical         - Canonical tag list
+ * @param mode              - Constraint mode
+ * @param metadataPrefixes  - Tags with these prefixes bypass normalization
+ */
+export declare function normalizeTags(tags: string[], canonical: string[], mode: 'enforce' | 'suggest' | 'off', metadataPrefixes?: string[]): string[];
+//# sourceMappingURL=tag-normalizer.d.ts.map

package/dist/vault/tag-normalizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag-normalizer.d.ts","sourceRoot":"","sources":["../../src/vault/tag-normalizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAqCH;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAsBhE;AAID;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAEtE;AAID;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,EAAE,EACnB,IAAI,EAAE,SAAS,GAAG,SAAS,GAAG,KAAK,GAClC,MAAM,GAAG,IAAI,CA6Cf;AAID;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EAAE,EACd,SAAS,EAAE,MAAM,EAAE,EACnB,IAAI,EAAE,SAAS,GAAG,SAAS,GAAG,KAAK,EACnC,gBAAgB,GAAE,MAAM,EAAgB,GACvC,MAAM,EAAE,CAwBV"}

package/dist/vault/tag-normalizer.js

@@ -0,0 +1,157 @@
+/**
+ * Tag Normalizer — canonical tag taxonomy enforcement.
+ *
+ * Maps raw tags to nearest canonical via Levenshtein edit-distance.
+ * Strips noise words (version strings, single generic words).
+ * Respects metadata tag prefixes (e.g. 'source:').
+ *
+ * Three modes:
+ *   - 'enforce': must match within edit-distance 3, else drop (return null)
+ *   - 'suggest': map to nearest canonical within edit-distance 2 (passthrough if no match)
+ *   - 'off':     no normalization — return tag as-is
+ */
+// ─── Noise filter ────────────────────────────────────────────────────────────
+/**
+ * Version-string pattern: v1.2, v10, v1.2.3, etc.
+ */
+const VERSION_PATTERN = /^v\d+(\.\d+)*/i;
+/**
+ * Generic single words that add no signal.
+ */
+const NOISE_WORDS = new Set([
+    'one',
+    'via',
+    'new',
+    'full',
+    'actual',
+    'raw',
+    'the',
+    'and',
+    'for',
+    'with',
+    'this',
+    'that',
+    'from',
+    'into',
+]);
+function isNoisy(tag) {
+    if (VERSION_PATTERN.test(tag))
+        return true;
+    if (NOISE_WORDS.has(tag.toLowerCase()))
+        return true;
+    return false;
+}
+// ─── Levenshtein edit distance ───────────────────────────────────────────────
+/**
+ * Compute Levenshtein edit distance between two strings.
+ * O(m*n) time, O(n) space using two-row DP.
+ */
+export function computeEditDistance(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    let curr = Array.from({ length: b.length + 1 });
+    for (let i = 1; i <= a.length; i++) {
+        curr[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            curr[j] = Math.min(curr[j - 1] + 1, // insertion
+            prev[j] + 1, // deletion
+            prev[j - 1] + cost);
+        }
+        [prev, curr] = [curr, prev];
+    }
+    return prev[b.length];
+}
+// ─── Metadata tag check ──────────────────────────────────────────────────────
+/**
+ * Returns true if the tag starts with any of the given prefixes.
+ * Metadata tags (e.g. 'source:article') are exempt from canonical normalization.
+ */
+export function isMetadataTag(tag, prefixes) {
+    return prefixes.some((prefix) => tag.startsWith(prefix));
+}
+// ─── Single tag normalization ────────────────────────────────────────────────
+/**
+ * Normalize a single tag against a canonical list.
+ *
+ * @param tag       - Raw tag to normalize
+ * @param canonical - Canonical tag list to map against
+ * @param mode      - Constraint mode: 'enforce' | 'suggest' | 'off'
+ * @returns Normalized tag string, or null if the tag should be dropped.
+ */
+export function normalizeTag(tag, canonical, mode) {
+    if (mode === 'off')
+        return tag;
+    const lower = tag.toLowerCase().trim();
+    // Always drop noise words
+    if (isNoisy(lower))
+        return null;
+    // Derive lowercase canonical for matching; preserve original casing for return
+    const canonicalLower = canonical.map((x) => x.toLowerCase());
+    // Exact match in canonical list — return canonical form (original casing)
+    const exactIdx = canonicalLower.indexOf(lower);
+    if (exactIdx !== -1)
+        return canonical[exactIdx];
+    if (canonical.length === 0) {
+        // No canonical list configured — pass through in suggest, drop in enforce
+        return mode === 'enforce' ? null : lower;
+    }
+    // Find nearest canonical by edit distance
+    let bestMatch = null;
+    let bestDist = Infinity;
+    for (let i = 0; i < canonicalLower.length; i++) {
+        const dist = computeEditDistance(lower, canonicalLower[i]);
+        if (dist < bestDist) {
+            bestDist = dist;
+            bestMatch = canonical[i];
+        }
+    }
+    const threshold = mode === 'enforce' ? 3 : 2;
+    if (bestDist <= threshold && bestMatch !== null) {
+        return bestMatch;
+    }
+    // No close match found
+    if (mode === 'enforce') {
+        return null; // drop the tag
+    }
+    // 'suggest' mode — keep original tag unchanged (passthrough)
+    return lower;
+}
+// ─── Batch tag normalization ─────────────────────────────────────────────────
+/**
+ * Normalize a batch of tags against a canonical list.
+ * Filters out nulls (dropped tags). Deduplicates the result.
+ *
+ * @param tags              - Raw tags
+ * @param canonical         - Canonical tag list
+ * @param mode              - Constraint mode
+ * @param metadataPrefixes  - Tags with these prefixes bypass normalization
+ */
+export function normalizeTags(tags, canonical, mode, metadataPrefixes = ['source:']) {
+    if (mode === 'off')
+        return tags;
+    const seen = new Set();
+    const result = [];
+    for (const tag of tags) {
+        // Metadata tags bypass canonical normalization but are still kept
+        if (isMetadataTag(tag, metadataPrefixes)) {
+            if (!seen.has(tag)) {
+                seen.add(tag);
+                result.push(tag);
+            }
+            continue;
+        }
+        const normalized = normalizeTag(tag, canonical, mode);
+        if (normalized !== null && !seen.has(normalized)) {
+            seen.add(normalized);
+            result.push(normalized);
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=tag-normalizer.js.map

package/dist/vault/tag-normalizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag-normalizer.js","sourceRoot":"","sources":["../../src/vault/tag-normalizer.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soleri/core",
-  "version": "9.14.4",
+  "version": "9.15.0",
   "description": "Shared engine for Soleri agents — vault, brain, planner, LLM utilities, and facade infrastructure.",
   "keywords": [
     "agent",
@@ -39,6 +39,10 @@
     "./personas": {
       "types": "./dist/persona/defaults.d.ts",
       "import": "./dist/persona/defaults.js"
+    },
+    "./skills/validate-skills": {
+      "types": "./dist/skills/validate-skills.d.ts",
+      "import": "./dist/skills/validate-skills.js"
     }
   },
   "publishConfig": {

package/src/__tests__/embeddings.test.ts

@@ -388,7 +388,7 @@ describe('EmbeddingPipeline', () => {
 
     expect(result.embedded).toBe(2);
     expect(result.failed).toBe(0);
-    expect(result.tokensUsed).toBeGreaterThan(0);
+    expect(result.tokensUsed).toBe(10); // mock provider returns texts.length * 5 = 2 * 5
 
     // Both entries should now have vectors
     expect(getVector(persistence, 'e1')).toBeTruthy();
@@ -405,7 +405,7 @@ describe('EmbeddingPipeline', () => {
       onProgress: (completed, total) => progress.push([completed, total]),
     });
 
-    expect(progress.length).toBeGreaterThan(0);
+    expect(progress.length).toBe(1); // default batchSize=100 processes both entries in one batch, firing onProgress once
     // Last progress call should have completed == total
     const last = progress[progress.length - 1];
     expect(last[0]).toBe(last[1]);
@@ -513,7 +513,7 @@ describe('Brain hybrid search compatibility', () => {
 
     // Should not throw — returns results from FTS only
     expect(Array.isArray(results)).toBe(true);
-    expect(results.length).toBeGreaterThan(0);
+    expect(results.length).toBe(1); // single seeded entry matches FTS query 'backward compatibility'
   });
 
   it('Brain.setEmbeddingProvider can set and clear provider', () => {

package/src/brain/brain.ts

@@ -3,6 +3,7 @@ import type { SearchResult } from '../vault/vault.js';
 import type { VaultManager } from '../vault/vault-manager.js';
 import type { IntelligenceEntry } from '../intelligence/types.js';
 import { computeContentHash } from '../vault/content-hash.js';
+import { normalizeTags as normalizeTagsCanonical } from '../vault/tag-normalizer.js';
 import {
   tokenize,
   calculateTf,
@@ -76,12 +77,20 @@ const DUPLICATE_BLOCK_THRESHOLD = 0.8;
 const DUPLICATE_WARN_THRESHOLD = 0.6;
 const RECENCY_HALF_LIFE_DAYS = 365;
 
+/** Canonical tag taxonomy config, injected from AgentRuntimeConfig. */
+export interface CanonicalTagConfig {
+  canonicalTags: string[];
+  tagConstraintMode: 'enforce' | 'suggest' | 'off';
+  metadataTagPrefixes: string[];
+}
+
 export class Brain {
   private vault: Vault;
   private vaultManager: VaultManager | undefined;
   private embeddingProvider: EmbeddingProvider | undefined;
   private vocabulary: Map<string, number> = new Map();
   private weights: ScoringWeights = { ...DEFAULT_WEIGHTS };
+  private canonicalTagConfig: CanonicalTagConfig | undefined;
 
   constructor(vault: Vault, vaultManager?: VaultManager, embeddingProvider?: EmbeddingProvider) {
     this.vault = vault;
@@ -91,6 +100,11 @@ export class Brain {
     this.recomputeWeights();
   }
 
+  /** Configure canonical tag taxonomy. Called by createAgentRuntime when config provides canonicalTags. */
+  setCanonicalTagConfig(cfg: CanonicalTagConfig): void {
+    this.canonicalTagConfig = cfg;
+  }
+
   /** Set or replace the embedding provider at runtime. */
   setEmbeddingProvider(provider: EmbeddingProvider | undefined): void {
     this.embeddingProvider = provider;
@@ -260,7 +274,17 @@ export class Brain {
     },
   ): CaptureResult {
     const autoTags = this.generateTags(entry.title, entry.description, entry.context);
-    const mergedTags = Array.from(new Set([...(entry.tags ?? []), ...autoTags]));
+    let mergedTags = Array.from(new Set([...(entry.tags ?? []), ...autoTags]));
+
+    // Apply canonical tag normalization if configured
+    if (this.canonicalTagConfig && this.canonicalTagConfig.tagConstraintMode !== 'off') {
+      mergedTags = normalizeTagsCanonical(
+        mergedTags,
+        this.canonicalTagConfig.canonicalTags,
+        this.canonicalTagConfig.tagConstraintMode,
+        this.canonicalTagConfig.metadataTagPrefixes,
+      );
+    }
 
     const duplicate = this.detectDuplicate(entry.title, entry.domain);
 

package/src/brain/intelligence.ts

@@ -1129,6 +1129,30 @@ export class BrainIntelligence {
   // ─── Intelligence Pipeline ────────────────────────────────────────
 
   buildIntelligence(): BuildIntelligenceResult {
+    // Step 0: GC — close orphaned sessions with no execution signal older than 24h
+    const TTL_MS = 24 * 60 * 60 * 1000;
+    const cutoff = new Date(Date.now() - TTL_MS).toISOString();
+    const activeSessions = this.listSessions({ active: true, limit: 1000 });
+    let gcClosed = 0;
+    for (const s of activeSessions) {
+      const isOld = s.startedAt < cutoff;
+      const hasNoSignal =
+        s.toolsUsed.length === 0 && s.filesModified.length === 0 && s.planOutcome === null;
+      if (isOld && hasNoSignal) {
+        try {
+          this.lifecycle({
+            action: 'end',
+            sessionId: s.id,
+            planOutcome: 'abandoned',
+            context: 'auto-gc: no execution signal after TTL',
+          });
+          gcClosed++;
+        } catch {
+          // GC must never break the intelligence pipeline
+        }
+      }
+    }
+
     // Step 1: Compute and persist strengths
     const strengths = this.computeStrengths();
 
@@ -1154,6 +1178,7 @@ export class BrainIntelligence {
       strengthsComputed: strengths.length,
       globalPatterns,
       domainProfiles,
+      gcClosed,
     };
   }
 

package/src/brain/types.ts

@@ -198,6 +198,7 @@ export interface BuildIntelligenceResult {
   strengthsComputed: number;
   globalPatterns: number;
   domainProfiles: number;
+  gcClosed: number;
 }
 
 export interface BrainIntelligenceStats {

package/src/chat/chat-session.ts

@@ -16,6 +16,7 @@ const DEFAULT_TTL_MS = 7_200_000; // 2 hours
 const DEFAULT_COMPACTION_THRESHOLD = 100;
 const DEFAULT_COMPACTION_KEEP = 40;
 const REAPER_INTERVAL_MS = 60_000; // 1 minute
+const SESSION_SUBDIR = 'sessions';
 
 export class ChatSessionManager {
   private sessions = new Map<string, ChatSession>();
@@ -31,6 +32,7 @@ export class ChatSessionManager {
     };
 
     mkdirSync(this.config.storageDir, { recursive: true });
+    mkdirSync(this.sessionDir(), { recursive: true });
   }
 
   // ─── Lifecycle ──────────────────────────────────────────────────
@@ -78,7 +80,8 @@ export class ChatSessionManager {
    */
   has(sessionId: string): boolean {
     if (this.sessions.has(sessionId)) return true;
-    return existsSync(this.sessionPath(sessionId));
+    if (existsSync(this.sessionPath(sessionId))) return true;
+    return this.loadSessionFile(this.legacySessionPath(sessionId)) !== undefined;
   }
 
   // ─── Message Management ─────────────────────────────────────────
@@ -159,15 +162,11 @@ export class ChatSessionManager {
    */
   listAll(): string[] {
     const memoryIds = new Set(this.sessions.keys());
-    try {
-      const files = readdirSync(this.config.storageDir);
-      for (const f of files) {
-        if (f.endsWith('.json')) {
-          memoryIds.add(f.replace('.json', ''));
-        }
-      }
-    } catch {
-      // Directory may not exist yet
+    for (const id of this.readPersistedSessionIds(this.sessionDir())) {
+      memoryIds.add(id);
+    }
+    for (const id of this.readPersistedSessionIds(this.config.storageDir)) {
+      memoryIds.add(id);
     }
     return [...memoryIds];
   }
@@ -246,38 +245,97 @@ export class ChatSessionManager {
     session.messages = session.messages.slice(-keep);
   }
 
+  private sessionDir(): string {
+    return join(this.config.storageDir, SESSION_SUBDIR);
+  }
+
   private sessionPath(sessionId: string): string {
     // Sanitize ID for filesystem safety
+    const safe = sessionId.replace(/[^a-zA-Z0-9_-]/g, '_');
+    return join(this.sessionDir(), `${safe}.json`);
+  }
+
+  private legacySessionPath(sessionId: string): string {
     const safe = sessionId.replace(/[^a-zA-Z0-9_-]/g, '_');
     return join(this.config.storageDir, `${safe}.json`);
   }
 
   private persistToDisk(session: ChatSession): void {
     try {
+      mkdirSync(this.sessionDir(), { recursive: true });
       writeFileSync(this.sessionPath(session.id), JSON.stringify(session), 'utf-8');
+
+      // Clean up valid legacy session files after migrating to the namespaced path.
+      const legacyPath = this.legacySessionPath(session.id);
+      if (this.loadSessionFile(legacyPath)) {
+        this.removeFile(legacyPath);
+      }
     } catch {
       // Disk write failure is non-critical — session lives in memory
     }
   }
 
   private loadFromDisk(sessionId: string): ChatSession | undefined {
-    const path = this.sessionPath(sessionId);
+    const current = this.loadSessionFile(this.sessionPath(sessionId));
+    if (current) return current;
+
+    const legacyPath = this.legacySessionPath(sessionId);
+    const legacy = this.loadSessionFile(legacyPath);
+    if (legacy) {
+      this.persistToDisk(legacy);
+      return legacy;
+    }
+
+    return undefined;
+  }
+
+  private removeFromDisk(sessionId: string): void {
+    this.removeFile(this.sessionPath(sessionId));
+    const legacyPath = this.legacySessionPath(sessionId);
+    if (this.loadSessionFile(legacyPath)) {
+      this.removeFile(legacyPath);
+    }
+  }
+
+  private removeFile(path: string): void {
+    try {
+      rmSync(path, { force: true });
+    } catch {
+      // Removal failure is non-critical
+    }
+  }
+
+  private loadSessionFile(path: string): ChatSession | undefined {
     if (!existsSync(path)) return undefined;
 
     try {
-      const data = readFileSync(path, 'utf-8');
-      return JSON.parse(data) as ChatSession;
+      const data = JSON.parse(readFileSync(path, 'utf-8'));
+      return this.isChatSession(data) ? data : undefined;
     } catch {
       return undefined;
     }
   }
 
-  private removeFromDisk(sessionId: string): void {
-    const path = this.sessionPath(sessionId);
+  private readPersistedSessionIds(dir: string): string[] {
     try {
-      rmSync(path, { force: true });
+      return readdirSync(dir).flatMap((file) => {
+        if (!file.endsWith('.json')) return [];
+        const session = this.loadSessionFile(join(dir, file));
+        return session ? [session.id] : [];
+      });
     } catch {
-      // Removal failure is non-critical
+      return [];
     }
   }
+
+  private isChatSession(value: unknown): value is ChatSession {
+    if (!value || typeof value !== 'object') return false;
+    const session = value as Partial<ChatSession>;
+    return (
+      typeof session.id === 'string' &&
+      Array.isArray(session.messages) &&
+      typeof session.createdAt === 'number' &&
+      typeof session.lastActiveAt === 'number'
+    );
+  }
 }

package/src/chat/chat-transport.test.ts

@@ -4,7 +4,7 @@
  */
 
 import { describe, test, expect, beforeEach, afterEach } from 'vitest';
-import { mkdtempSync, rmSync } from 'node:fs';
+import { mkdtempSync, rmSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 import { ChatSessionManager } from './chat-session.js';
@@ -136,6 +136,19 @@ describe('ChatSessionManager', () => {
       expect(all).toContain('chat-2');
     });
 
+    test('listAll ignores non-session JSON files in the storage root', () => {
+      manager.getOrCreate('chat-1');
+      writeFileSync(
+        join(dir, 'plans.json'),
+        JSON.stringify({ version: '1.0', plans: [] }),
+        'utf-8',
+      );
+
+      const all = manager.listAll();
+      expect(all).toContain('chat-1');
+      expect(all).not.toContain('plans');
+    });
+
     test('setMeta updates metadata', () => {
       manager.getOrCreate('chat-1');
       manager.setMeta('chat-1', { mood: 'happy' });
@@ -162,6 +175,23 @@ describe('ChatSessionManager', () => {
       manager2.close();
     });
 
+    test('session files are namespaced away from plans.json collisions', () => {
+      writeFileSync(
+        join(dir, 'plans.json'),
+        JSON.stringify({ version: '1.0', plans: [{ id: 'plan-1' }] }),
+        'utf-8',
+      );
+
+      const session = manager.getOrCreate('plans');
+
+      expect(session.messages).toEqual([]);
+      expect(JSON.parse(readFileSync(join(dir, 'plans.json'), 'utf-8'))).toEqual({
+        version: '1.0',
+        plans: [{ id: 'plan-1' }],
+      });
+      expect(existsSync(join(dir, 'sessions', 'plans.json'))).toBe(true);
+    });
+
     test('delete removes from disk', () => {
       manager.getOrCreate('chat-1');
       manager.delete('chat-1');