@cleocode/core 2026.4.51 → 2026.4.53

package/src/memory/brain-retrieval.ts

@@ -259,9 +259,18 @@ export async function searchBrainCompact(
       const returnedIds = results.map((r) => r.id);
       setImmediate(() => {
         incrementCitationCounts(projectRoot, returnedIds).catch(() => {});
-        logRetrieval(projectRoot, query, returnedIds, 'find-rrf', results.length * 50).catch(
-          () => {},
-        );
+        getCurrentSessionId(projectRoot)
+          .then((sessionId) => {
+            return logRetrieval(
+              projectRoot,
+              query,
+              returnedIds,
+              'find-rrf',
+              results.length * 50,
+              sessionId,
+            );
+          })
+          .catch(() => {});
       });
     }
 
@@ -345,7 +354,18 @@ export async function searchBrainCompact(
     const returnedIds = results.map((r) => r.id);
     setImmediate(() => {
       incrementCitationCounts(projectRoot, returnedIds).catch(() => {});
-      logRetrieval(projectRoot, query, returnedIds, 'find', results.length * 50).catch(() => {});
+      getCurrentSessionId(projectRoot)
+        .then((sessionId) => {
+          return logRetrieval(
+            projectRoot,
+            query,
+            returnedIds,
+            'find',
+            results.length * 50,
+            sessionId,
+          );
+        })
+        .catch(() => {});
     });
   }
 
@@ -604,13 +624,18 @@ export async function fetchBrainEntries(
     const fetchedIds = results.map((r) => r.id);
     setImmediate(() => {
       incrementCitationCounts(projectRoot, fetchedIds).catch(() => {});
-      logRetrieval(
-        projectRoot,
-        fetchedIds.join(','),
-        fetchedIds,
-        'fetch',
-        results.length * 500,
-      ).catch(() => {});
+      getCurrentSessionId(projectRoot)
+        .then((sessionId) => {
+          return logRetrieval(
+            projectRoot,
+            fetchedIds.join(','),
+            fetchedIds,
+            'fetch',
+            results.length * 500,
+            sessionId,
+          );
+        })
+        .catch(() => {});
     });
   }
 
@@ -1364,6 +1389,31 @@ export async function retrieveWithBudget(
   };
 }
 
+// ============================================================================
+// Session ID Retrieval (for logRetrieval)
+// ============================================================================
+
+/**
+ * Get the current session ID from the session manager.
+ *
+ * This is a best-effort operation — if no session is active or session
+ * manager is unavailable, returns null. Used by logRetrieval to group
+ * retrievals by session for STDP analysis.
+ *
+ * @param projectRoot - Project root directory
+ * @returns Current session ID or null if unavailable
+ */
+async function getCurrentSessionId(projectRoot: string): Promise<string | undefined> {
+  try {
+    const { sessionStatus } = await import('../sessions/index.js');
+    const session = await sessionStatus(projectRoot);
+    return session?.id;
+  } catch {
+    // Session manager unavailable or other error — log retrievals without session
+    return undefined;
+  }
+}
+
 // ============================================================================
 // Citation Count Increment (non-blocking helper)
 // ============================================================================
@@ -1416,6 +1466,13 @@ async function incrementCitationCounts(projectRoot: string, ids: string[]): Prom
  *
  * Creates the table on first use if it doesn't exist (self-healing).
  * Best-effort: errors are silently swallowed.
+ *
+ * @param projectRoot - Project root directory
+ * @param query - The search query or fetch IDs
+ * @param entryIds - Array of entry IDs returned in this retrieval
+ * @param source - Retrieval source ('find', 'fetch', 'hybrid', 'timeline', 'budget')
+ * @param tokensUsed - Estimated tokens consumed (optional)
+ * @param sessionId - Session ID for grouping retrievals by session (optional, soft FK to tasks.db)
  */
 async function logRetrieval(
   projectRoot: string,
@@ -1423,6 +1480,7 @@ async function logRetrieval(
   entryIds: string[],
   source: string,
   tokensUsed?: number,
+  sessionId?: string,
 ): Promise<void> {
   if (entryIds.length === 0) return;
 
@@ -1431,7 +1489,7 @@ async function logRetrieval(
   const nativeDb = getBrainNativeDb();
   if (!nativeDb) return;
 
-  // Self-healing: create table if not exists
+  // Self-healing: create table if not exists (includes session_id column)
   const createSql =
     'CREATE TABLE IF NOT EXISTS brain_retrieval_log (' +
     'id INTEGER PRIMARY KEY AUTOINCREMENT,' +
@@ -1440,6 +1498,7 @@ async function logRetrieval(
     'entry_count INTEGER NOT NULL,' +
     'source TEXT NOT NULL,' +
     'tokens_used INTEGER,' +
+    'session_id TEXT,' +
     "created_at TEXT NOT NULL DEFAULT (datetime('now'))" +
     ')';
   try {
@@ -1451,9 +1510,16 @@ async function logRetrieval(
   try {
     nativeDb
       .prepare(
-        'INSERT INTO brain_retrieval_log (query, entry_ids, entry_count, source, tokens_used) VALUES (?, ?, ?, ?, ?)',
+        'INSERT INTO brain_retrieval_log (query, entry_ids, entry_count, source, tokens_used, session_id) VALUES (?, ?, ?, ?, ?, ?)',
       )
-      .run(query, entryIds.join(','), entryIds.length, source, tokensUsed ?? null);
+      .run(
+        query,
+        entryIds.join(','),
+        entryIds.length,
+        source,
+        tokensUsed ?? null,
+        sessionId ?? null,
+      );
   } catch {
     /* best-effort */
   }

package/src/memory/brain-similarity.ts

@@ -61,7 +61,7 @@ export async function searchSimilar(
   projectRoot: string,
   limit?: number,
 ): Promise<SimilarityResult[]> {
-  if (!query || !query.trim()) return [];
+  if (!query?.trim()) return [];
   if (!isEmbeddingAvailable()) return [];
 
   const maxResults = limit ?? 10;

package/src/memory/claude-mem-migration.ts

@@ -316,7 +316,7 @@ export async function migrateClaudeMem(
 
       try {
         for (const row of batch) {
-          if (!row.learned || !row.learned.trim()) {
+          if (!row.learned?.trim()) {
             continue;
           }
 

package/src/scaffold.ts

@@ -15,6 +15,7 @@ import { randomUUID } from 'node:crypto';
 import type { Dirent } from 'node:fs';
 import { existsSync, constants as fsConstants, readFileSync, statSync } from 'node:fs';
 import { access, copyFile, mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
 import { homedir as getHomedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -1836,8 +1837,159 @@ export async function ensureCleoOsHub(): Promise<ScaffoldResult> {
   };
 }
 
+/**
+ * Resolve the source location of CLEOOS-IDENTITY.md from the cleo-os starter bundle.
+ *
+ * Search order:
+ * 1. Monorepo development: `packages/cleo-os/starter-bundle/CLEOOS-IDENTITY.md`
+ * 2. Installed package: `node_modules/@cleocode/cleo-os/starter-bundle/CLEOOS-IDENTITY.md`
+ *
+ * @returns Absolute path to the source identity file, or null if not found.
+ * @internal Used by ensureGlobalIdentity.
+ */
+function resolveIdentitySourcePath(): string | null {
+  // Prefer monorepo source (development)
+  const monorepoPath = join(
+    process.cwd(),
+    'packages',
+    'cleo-os',
+    'starter-bundle',
+    'CLEOOS-IDENTITY.md',
+  );
+  if (existsSync(monorepoPath)) return monorepoPath;
+
+  // Fall back to installed package via require resolution
+  try {
+    const require = createRequire(import.meta.url);
+    const pkgJson = require.resolve('@cleocode/cleo-os/package.json');
+    const pkgDir = pkgJson.replace(/\/package\.json$/, '');
+    const installedPath = join(pkgDir, 'starter-bundle', 'CLEOOS-IDENTITY.md');
+    if (existsSync(installedPath)) return installedPath;
+  } catch {
+    // Not installed — fall through
+  }
+
+  return null;
+}
+
+/**
+ * Ensure the Cleo Prime identity file is deployed to the global XDG path.
+ *
+ * SSoT architecture (T631): CLEOOS-IDENTITY.md lives ONCE at the global path
+ * (`~/.local/share/cleo/CLEOOS-IDENTITY.md`). Per-project override is OPTIONAL —
+ * a project may place a customized copy at `.cleo/CLEOOS-IDENTITY.md` and the
+ * loader (`cant-context.ts readIdentityFile`) reads project-first then global.
+ *
+ * Called by both `cleo init` (init.ts deployStarterBundle) and `cleo upgrade`
+ * (upgrade.ts) so existing projects self-heal on upgrade if the file is missing
+ * or out of date.
+ *
+ * Idempotent. Always overwrites if `forceRefresh` is true (used by `upgrade
+ * --refresh-identity`); otherwise only writes when missing.
+ *
+ * @param forceRefresh - Overwrite even if the file exists. Default false.
+ * @returns ScaffoldResult describing what happened.
+ */
+export async function ensureGlobalIdentity(forceRefresh = false): Promise<ScaffoldResult> {
+  const sourcePath = resolveIdentitySourcePath();
+  if (!sourcePath) {
+    return {
+      action: 'skipped',
+      path: '',
+      details: 'CLEOOS-IDENTITY.md source not found in monorepo or installed package',
+    };
+  }
+
+  const cleoHome = getCleoHome();
+  const dst = join(cleoHome, 'CLEOOS-IDENTITY.md');
+
+  try {
+    await mkdir(cleoHome, { recursive: true });
+  } catch (err) {
+    return {
+      action: 'skipped',
+      path: dst,
+      details: `Failed to create global cleo home: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+
+  if (existsSync(dst) && !forceRefresh) {
+    return { action: 'skipped', path: dst, details: 'identity already present' };
+  }
+
+  const existedBefore = existsSync(dst);
+  try {
+    const content = readFileSync(sourcePath, 'utf-8');
+    await writeFile(dst, content);
+    return {
+      action: existedBefore ? 'repaired' : 'created',
+      path: dst,
+      details: `from ${sourcePath}`,
+    };
+  } catch (err) {
+    return {
+      action: 'skipped',
+      path: dst,
+      details: `Failed to write identity: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+}
+
 // ── Global check* functions (read-only diagnostics) ──────────────────
 
+/**
+ * Check that the global CLEOOS-IDENTITY.md file is present and non-empty.
+ * Read-only diagnostic for `cleo doctor`.
+ *
+ * @returns Check result with status, path details, and self-heal command.
+ *
+ * @remarks
+ * Used by `cleo doctor` to verify the orchestrator persona is installed.
+ * Self-heal: `cleo upgrade --refresh-identity` re-deploys from source.
+ */
+export function checkGlobalIdentity(): CheckResult {
+  const cleoHome = getCleoHome();
+  const identityPath = join(cleoHome, 'CLEOOS-IDENTITY.md');
+
+  if (!existsSync(identityPath)) {
+    return {
+      id: 'global_identity',
+      category: 'global',
+      status: 'failed',
+      message: 'Global CLEOOS-IDENTITY.md not found — orchestrator persona missing',
+      details: { path: identityPath, exists: false },
+      fix: 'cleo upgrade (auto-deploys identity)',
+    };
+  }
+
+  let size = 0;
+  try {
+    size = statSync(identityPath).size;
+  } catch {
+    /* ignore */
+  }
+
+  if (size === 0) {
+    return {
+      id: 'global_identity',
+      category: 'global',
+      status: 'failed',
+      message: 'Global CLEOOS-IDENTITY.md exists but is empty',
+      details: { path: identityPath, exists: true, size: 0 },
+      fix: 'cleo upgrade --refresh-identity',
+    };
+  }
+
+  return {
+    id: 'global_identity',
+    category: 'global',
+    status: 'passed',
+    message: 'Global CLEOOS-IDENTITY.md present',
+    details: { path: identityPath, exists: true, size },
+    fix: '',
+  };
+}
+
 /**
  * Check that the global ~/.cleo/ home and its required subdirectories exist.
  * Read-only: no side effects.

package/src/sessions/briefing.ts

@@ -292,7 +292,7 @@ async function computeLastSession(
     const allSessions = await accessor.loadSessions();
 
     const session = allSessions.find((s) => s.id === sessionId);
-    if (!session || !session.endedAt) return null;
+    if (!session?.endedAt) return null;
 
     // Calculate duration if startedAt is available
     let duration = 0;

package/src/skills/dispatch.ts

@@ -382,7 +382,7 @@ export function prepareSpawnMulti(
     const isPrimary = i === 0;
 
     const skill = findSkill(skillName, cwd);
-    if (!skill || !skill.content) {
+    if (!skill?.content) {
       continue;
     }
 

package/src/skills/injection/subagent.ts

@@ -205,7 +205,7 @@ export async function orchestratorSpawnSkill(
 ): Promise<string> {
   // Find the skill
   const skill = findSkill(skillName, cwd);
-  if (!skill || !skill.content) {
+  if (!skill?.content) {
     throw new CleoError(ExitCode.NOT_FOUND, `Skill not found: ${skillName}`, {
       fix: `Check skills directory for ${skillName}/SKILL.md`,
     });

package/src/skills/orchestrator/spawn.ts

@@ -45,7 +45,7 @@ export async function buildPrompt(
 
   // Find skill template
   const skill = findSkill(templateName, cwd);
-  if (!skill || !skill.content) {
+  if (!skill?.content) {
     const { canonical } = mapSkillName(templateName);
     throw new CleoError(ExitCode.NOT_FOUND, `Skill template ${templateName} not found`, {
       fix: `Expected at skills/${canonical}/SKILL.md`,

package/src/store/brain-schema.ts

@@ -707,11 +707,15 @@ export const brainRetrievalLog = sqliteTable(
     /** Estimated tokens consumed by this retrieval. */
     tokensUsed: integer('tokens_used'),
 
+    /** Session ID (soft FK to tasks.db sessions). Enables grouping retrievals by session for STDP analysis. */
+    sessionId: text('session_id'),
+
     createdAt: text('created_at').notNull().default(sql`(datetime('now'))`),
   },
   (table) => [
     index('idx_retrieval_log_created').on(table.createdAt),
     index('idx_retrieval_log_source').on(table.source),
+    index('idx_retrieval_log_session').on(table.sessionId),
   ],
 );
 

package/src/store/json.ts

@@ -206,7 +206,7 @@ export async function readLogEntries(filePath: string): Promise<Record<string, u
       if (remainder) {
         for (const line of remainder.split('\n')) {
           const l = line.trim();
-          if (!l || !l.startsWith('{')) continue;
+          if (!l?.startsWith('{')) continue;
           try {
             entries.push(JSON.parse(l) as Record<string, unknown>);
           } catch {
@@ -219,7 +219,7 @@ export async function readLogEntries(filePath: string): Promise<Record<string, u
     // Pure JSONL (no initial JSON object)
     for (const line of trimmed.split('\n')) {
       const l = line.trim();
-      if (!l || !l.startsWith('{')) continue;
+      if (!l?.startsWith('{')) continue;
       try {
         entries.push(JSON.parse(l) as Record<string, unknown>);
       } catch {

package/src/system/archive-analytics.ts

@@ -420,7 +420,7 @@ export async function analyzeArchive(
 
   const reportType = opts.report ?? 'summary';
 
-  if (!data || !data.archivedTasks?.length) {
+  if (!data?.archivedTasks?.length) {
     return {
       report: reportType,
       filters: null,

package/src/system/health.ts

@@ -18,6 +18,7 @@ import {
   checkCleoStructure,
   checkConfig,
   checkGlobalHome,
+  checkGlobalIdentity,
   checkGlobalTemplates,
   checkLogDir,
   checkMemoryBridge,
@@ -842,6 +843,7 @@ export async function coreDoctorReport(projectRoot: string): Promise<DoctorRepor
   // 5c. Global scaffold checks: home, templates, schemas
   checks.push(mapCheckResult(checkGlobalHome()));
   checks.push(mapCheckResult(checkGlobalTemplates()));
+  checks.push(mapCheckResult(checkGlobalIdentity()));
   checks.push(mapSchemaCheckResult(checkGlobalSchemas()));
 
   // 5d. Project scaffold checks: log dir, structure, git hooks, project-info, injection

package/src/tasks/task-ops.ts

@@ -144,7 +144,7 @@ function measureDependencyDepth(
   visited.add(taskId);
 
   const task = taskMap.get(taskId);
-  if (!task || !task.depends || task.depends.length === 0) return 0;
+  if (!task?.depends || task.depends.length === 0) return 0;
 
   let maxDepth = 0;
   for (const depId of task.depends) {
@@ -921,7 +921,7 @@ export async function coreTaskUnarchive(
   }
 
   const archive = await accessor.loadArchive();
-  if (!archive || !archive.archivedTasks) {
+  if (!archive?.archivedTasks) {
     throw new Error('No archive file found');
   }
 

package/src/upgrade.ts

@@ -940,6 +940,23 @@ export async function runUpgrade(
       /* best-effort */
     }
 
+    // Ensure global CLEOOS-IDENTITY.md is present (T631 — single SSoT).
+    // Self-heals if file is missing on existing projects after upgrade.
+    try {
+      const { ensureGlobalIdentity } = await import('./scaffold.js');
+      const identityResult = await ensureGlobalIdentity();
+      actions.push({
+        action: 'global_identity',
+        status:
+          identityResult.action === 'created' || identityResult.action === 'repaired'
+            ? 'applied'
+            : 'skipped',
+        details: `${identityResult.path} (${identityResult.details ?? identityResult.action})`,
+      });
+    } catch {
+      /* best-effort — identity is already-kept-or-skipped on failure */
+    }
+
     // Install core skills
     try {
       const skillsCreated: string[] = [];

package/src/validation/verification.ts

@@ -438,9 +438,7 @@ export function allEpicChildrenVerified(epicId: string, tasks: TaskForVerificati
   const incomplete = children.filter((t) => t.status !== 'done');
   if (incomplete.length > 0) return false;
 
-  const unverified = children.filter(
-    (t) => t.status === 'done' && (!t.verification || !t.verification.passed),
-  );
+  const unverified = children.filter((t) => t.status === 'done' && !t.verification?.passed);
   return unverified.length === 0;
 }
 
@@ -451,9 +449,7 @@ export function allEpicChildrenVerified(epicId: string, tasks: TaskForVerificati
 export function allSiblingsVerified(parentId: string, tasks: TaskForVerification[]): boolean {
   const siblings = tasks.filter((t) => t.parentId === parentId);
 
-  const unverifiedDone = siblings.filter(
-    (t) => t.status === 'done' && (!t.verification || !t.verification.passed),
-  );
+  const unverifiedDone = siblings.filter((t) => t.status === 'done' && !t.verification?.passed);
 
   const incomplete = siblings.filter(
     (t) => t.status === 'pending' || t.status === 'active' || t.status === 'blocked',