@cleocode/core 2026.3.59 → 2026.3.60

package/src/agents/__tests__/agent-registry.test.ts

@@ -88,7 +88,7 @@ describe('Agent Registry (T041)', () => {
         .values({
           id: 'T-cap-001',
           title: 'Capacity test task',
-          status: 'in_progress',
+          status: 'active',
           priority: 'medium',
           createdAt: new Date().toISOString(),
         })

package/src/bootstrap.ts

@@ -41,7 +41,8 @@ export interface BootstrapOptions {
  * Bootstrap the global CLEO directory structure and install templates.
  *
  * Creates:
- *   - ~/.cleo/templates/CLEO-INJECTION.md (from bundled template or injection content)
+ *   - ~/.local/share/cleo/templates/CLEO-INJECTION.md (XDG primary)
+ *   - ~/.cleo/templates/CLEO-INJECTION.md (legacy sync)
  *   - ~/.agents/AGENTS.md with CAAMP injection block
  *
  * This is idempotent — safe to call multiple times.
@@ -60,7 +61,7 @@ export async function bootstrapGlobalCleo(options?: BootstrapOptions): Promise<B
     // Best-effort — don't fail bootstrap if cleanup fails
   }
 
-  // Step 1: Ensure global templates
+  // Step 1: Ensure global templates (XDG + legacy sync)
   await ensureGlobalTemplatesBootstrap(ctx, options?.packageRoot);
 
   // Step 2: CAAMP injection into ~/.agents/AGENTS.md
@@ -78,11 +79,30 @@ export async function bootstrapGlobalCleo(options?: BootstrapOptions): Promise<B
   // Step 6: Install provider adapters
   await installProviderAdapters(ctx, options?.packageRoot);
 
+  // Step 7: Verify injection chain health
+  await verifyBootstrapHealth(ctx);
+
   return ctx;
 }
 
 // ── Step 1: Global templates ─────────────────────────────────────────
 
+/**
+ * Write template content to a destination path, creating parent dirs as needed.
+ * Returns true if written, false if dry-run.
+ */
+async function writeTemplateTo(
+  content: string,
+  destPath: string,
+  isDryRun: boolean,
+): Promise<boolean> {
+  if (isDryRun) return false;
+  const { dirname } = await import('node:path');
+  await mkdir(dirname(destPath), { recursive: true });
+  await writeFile(destPath, content);
+  return true;
+}
+
 async function ensureGlobalTemplatesBootstrap(
   ctx: BootstrapContext,
   packageRootOverride?: string,
@@ -93,43 +113,85 @@ async function ensureGlobalTemplatesBootstrap(
     await mkdir(globalTemplatesDir, { recursive: true });
   }
 
+  // Resolve template content from bundled file or embedded fallback
+  let templateContent: string | null = null;
+
   try {
     const pkgRoot = packageRootOverride ?? getPackageRoot();
     const templatePath = join(pkgRoot, 'templates', 'CLEO-INJECTION.md');
     if (existsSync(templatePath)) {
-      const content = readFileSync(templatePath, 'utf-8');
-      const destPath = join(globalTemplatesDir, 'CLEO-INJECTION.md');
-      if (!ctx.isDryRun) {
-        await writeFile(destPath, content);
-      }
-      ctx.created.push(
-        `~/.cleo/templates/CLEO-INJECTION.md (${ctx.isDryRun ? 'would refresh' : 'refreshed'})`,
-      );
-    } else {
-      // Fallback: try using the injection content generator
-      try {
-        const { getInjectionTemplateContent } = await import('./injection.js');
-        const content = getInjectionTemplateContent();
-        if (content) {
-          const destPath = join(globalTemplatesDir, 'CLEO-INJECTION.md');
-          if (!ctx.isDryRun) {
-            await writeFile(destPath, content);
-          }
-          ctx.created.push(
-            `~/.cleo/templates/CLEO-INJECTION.md (${ctx.isDryRun ? 'would refresh' : 'refreshed'} from embedded)`,
-          );
-        }
-      } catch {
-        ctx.warnings.push('Could not refresh CLEO-INJECTION.md template');
-      }
+      templateContent = readFileSync(templatePath, 'utf-8');
     }
   } catch {
+    // Fall through to embedded fallback
+  }
+
+  if (!templateContent) {
+    try {
+      const { getInjectionTemplateContent } = await import('./injection.js');
+      templateContent = getInjectionTemplateContent() ?? null;
+    } catch {
+      ctx.warnings.push('Could not refresh CLEO-INJECTION.md template');
+      return;
+    }
+  }
+
+  if (!templateContent) {
     ctx.warnings.push('Could not refresh CLEO-INJECTION.md template');
+    return;
+  }
+
+  // Write to XDG primary path
+  const xdgDest = join(globalTemplatesDir, 'CLEO-INJECTION.md');
+  const xdgWritten = await writeTemplateTo(templateContent, xdgDest, ctx.isDryRun);
+  ctx.created.push(
+    `${getCleoTemplatesTildePath()}/CLEO-INJECTION.md (${xdgWritten ? 'refreshed' : 'would refresh'})`,
+  );
+
+  // Sync to legacy ~/.cleo/templates/ if it exists (backward compat for
+  // project AGENTS.md files that still reference the old path)
+  const home = homedir();
+  const legacyTemplatesDir = join(home, '.cleo', 'templates');
+  if (legacyTemplatesDir !== globalTemplatesDir && existsSync(join(home, '.cleo'))) {
+    const legacyDest = join(legacyTemplatesDir, 'CLEO-INJECTION.md');
+    const legacyWritten = await writeTemplateTo(templateContent, legacyDest, ctx.isDryRun);
+    if (legacyWritten) {
+      ctx.created.push('~/.cleo/templates/CLEO-INJECTION.md (legacy sync)');
+    }
   }
 }
 
 // ── Step 2: CAAMP injection into ~/.agents/AGENTS.md ─────────────────
 
+/**
+ * Sanitize a CAAMP-managed file by removing orphaned content outside
+ * CAAMP blocks. This fixes corruption from failed CAAMP consolidation
+ * (e.g. partial old block removal leaving `TION.md` fragments).
+ *
+ * Strategy: keep ONLY content inside valid CAAMP blocks + any non-CAAMP
+ * user content that doesn't look like an orphaned reference fragment.
+ */
+function sanitizeCaampFile(content: string): string {
+  // Remove any duplicate <!-- CAAMP:END --> markers
+  let cleaned = content.replace(/(<!-- CAAMP:END -->)\s*(<!-- CAAMP:END -->)/g, '$1');
+
+  // Remove orphaned content between CAAMP:END and the next CAAMP:START (or EOF)
+  // that looks like a fragment of a CLEO reference (e.g. "TION.md", "INJECTION.md")
+  cleaned = cleaned.replace(
+    /<!-- CAAMP:END -->\s*[A-Z][A-Za-z-]*\.md\s*(?:<!-- CAAMP:END -->)?/g,
+    '<!-- CAAMP:END -->',
+  );
+
+  // Remove any lines that are just orphaned .md filename fragments
+  // (leftover from partial CAAMP block removal)
+  cleaned = cleaned.replace(/^[A-Z][A-Za-z-]*\.md\s*$/gm, '');
+
+  // Collapse multiple blank lines
+  cleaned = cleaned.replace(/\n{3,}/g, '\n\n');
+
+  return cleaned.trim() + '\n';
+}
+
 async function injectAgentsHub(ctx: BootstrapContext): Promise<void> {
   const globalAgentsDir = getAgentsHome();
   const globalAgentsMd = join(globalAgentsDir, 'AGENTS.md');
@@ -143,21 +205,39 @@ async function injectAgentsHub(ctx: BootstrapContext): Promise<void> {
       await mkdir(globalAgentsDir, { recursive: true });
 
       // Strip legacy CLEO blocks (versioned markers from pre-CAAMP era)
+      // AND sanitize CAAMP corruption (orphaned fragments from bad consolidation)
       if (existsSync(globalAgentsMd)) {
         const content = await readFile(globalAgentsMd, 'utf8');
+
+        // Step A: Remove legacy <!-- CLEO:START -->...<!-- CLEO:END --> blocks
         const stripped = content.replace(
           /\n?<!-- CLEO:START[^>]*-->[\s\S]*?<!-- CLEO:END -->\n?/g,
           '',
         );
-        if (stripped !== content) {
-          await writeFile(globalAgentsMd, stripped, 'utf8');
+
+        // Step B: Sanitize CAAMP corruption (orphaned fragments, duplicate markers)
+        const sanitized = sanitizeCaampFile(stripped);
+
+        if (sanitized !== content) {
+          await writeFile(globalAgentsMd, sanitized, 'utf8');
+          ctx.created.push('~/.agents/AGENTS.md (sanitized CAAMP corruption)');
         }
       }
 
-      // CAAMP 1.8.1: inject() is idempotent AND consolidates duplicates
+      // CAAMP inject() is idempotent — writes the current XDG template reference
       const templateRef = `@${getCleoTemplatesTildePath()}/CLEO-INJECTION.md`;
       const action = await inject(globalAgentsMd, templateRef);
       ctx.created.push(`~/.agents/AGENTS.md (${action})`);
+
+      // Post-inject validation: verify the file is clean
+      const postContent = await readFile(globalAgentsMd, 'utf8');
+      const caampBlocks = postContent.match(/<!-- CAAMP:START -->/g);
+      const caampEnds = postContent.match(/<!-- CAAMP:END -->/g);
+      if (caampBlocks && caampEnds && caampBlocks.length !== caampEnds.length) {
+        ctx.warnings.push(
+          `~/.agents/AGENTS.md has mismatched CAAMP markers (${caampBlocks.length} START vs ${caampEnds.length} END)`,
+        );
+      }
     } else {
       ctx.created.push('~/.agents/AGENTS.md (would create/update CAAMP block)');
     }
@@ -330,3 +410,64 @@ async function installProviderAdapters(
     );
   }
 }
+
+// ── Step 7: Post-bootstrap health verification ───────────────────────
+
+/**
+ * Verify the injection chain is intact after bootstrap.
+ * Checks:
+ *   1. XDG template exists and has a version header
+ *   2. Legacy template (if present) matches XDG version
+ *   3. ~/.agents/AGENTS.md references the correct template path
+ *   4. No orphaned content in AGENTS.md
+ */
+async function verifyBootstrapHealth(ctx: BootstrapContext): Promise<void> {
+  if (ctx.isDryRun) return;
+
+  try {
+    const xdgTemplatePath = join(getCleoTemplatesDir(), 'CLEO-INJECTION.md');
+    const agentsMd = join(getAgentsHome(), 'AGENTS.md');
+
+    // Check 1: XDG template exists
+    if (!existsSync(xdgTemplatePath)) {
+      ctx.warnings.push('Health: XDG template missing after bootstrap');
+      return;
+    }
+
+    const xdgContent = await readFile(xdgTemplatePath, 'utf8');
+    const xdgVersion = xdgContent.match(/^Version:\s*(.+)$/m)?.[1]?.trim();
+
+    // Check 2: Legacy template version sync
+    const home = homedir();
+    const legacyTemplatePath = join(home, '.cleo', 'templates', 'CLEO-INJECTION.md');
+    if (existsSync(legacyTemplatePath)) {
+      const legacyContent = await readFile(legacyTemplatePath, 'utf8');
+      const legacyVersion = legacyContent.match(/^Version:\s*(.+)$/m)?.[1]?.trim();
+      if (legacyVersion !== xdgVersion) {
+        ctx.warnings.push(
+          `Health: Legacy template version (${legacyVersion}) != XDG version (${xdgVersion})`,
+        );
+      }
+    }
+
+    // Check 3: AGENTS.md references the correct path
+    if (existsSync(agentsMd)) {
+      const agentsContent = await readFile(agentsMd, 'utf8');
+      const expectedRef = `@${getCleoTemplatesTildePath()}/CLEO-INJECTION.md`;
+      if (!agentsContent.includes(expectedRef)) {
+        ctx.warnings.push(`Health: ~/.agents/AGENTS.md does not reference ${expectedRef}`);
+      }
+
+      // Check 4: No orphaned .md fragments outside CAAMP blocks
+      const outsideCaamp = agentsContent.replace(
+        /<!-- CAAMP:START -->[\s\S]*?<!-- CAAMP:END -->/g,
+        '',
+      );
+      if (/[A-Z][A-Za-z-]*\.md/.test(outsideCaamp)) {
+        ctx.warnings.push('Health: ~/.agents/AGENTS.md has orphaned content outside CAAMP blocks');
+      }
+    }
+  } catch {
+    // Health check is non-critical — don't fail bootstrap
+  }
+}

package/src/cleo.ts

@@ -31,6 +31,28 @@ import type {
 import { exportTasks } from './admin/export.js';
 import type { ImportParams } from './admin/import.js';
 import { importTasks } from './admin/import.js';
+// Agents
+import {
+  type AgentCapacity,
+  type AgentHealthStatus,
+  type AgentInstanceRow,
+  checkAgentHealth,
+  deregisterAgent,
+  detectCrashedAgents,
+  getAgentCapacity,
+  heartbeat,
+  isOverloaded,
+  listAgentInstances,
+  type RegisterAgentOptions,
+  registerAgent,
+} from './agents/index.js';
+// Intelligence
+import {
+  type BlastRadius,
+  calculateBlastRadius,
+  type ImpactReport,
+  predictImpact,
+} from './intelligence/index.js';
 // Lifecycle
 import {
   checkGate,
@@ -127,6 +149,8 @@ import {
 } from './sticky/index.js';
 // Store
 import { getAccessor } from './store/data-accessor.js';
+// Task Work (start/stop/current)
+import { currentTask, startTask, stopTask } from './task-work/index.js';
 // Tasks
 import { addTask } from './tasks/add.js';
 import { archiveTasks } from './tasks/archive.js';
@@ -179,10 +203,21 @@ export interface TasksAPI {
   complete(params: { taskId: string; notes?: string }): Promise<unknown>;
   delete(params: { taskId: string; force?: boolean }): Promise<unknown>;
   archive(params?: { before?: string; taskIds?: string[]; dryRun?: boolean }): Promise<unknown>;
+  /** Start working on a specific task (sets focus). */
+  start(taskId: string): Promise<unknown>;
+  /** Stop working on the current task (clears focus). */
+  stop(): Promise<{ previousTask: string | null }>;
+  /** Get the current task work state. */
+  current(): Promise<unknown>;
 }
 
 export interface SessionsAPI {
-  start(params: { name: string; scope: string; agent?: string }): Promise<unknown>;
+  start(params: {
+    name: string;
+    scope: string;
+    agent?: string;
+    startTask?: string;
+  }): Promise<unknown>;
   end(params?: { note?: string }): Promise<unknown>;
   status(): Promise<unknown>;
   resume(sessionId: string): Promise<unknown>;
@@ -324,6 +359,32 @@ export interface SyncAPI {
   removeProviderLinks(providerId: string): Promise<number>;
 }
 
+export interface AgentsAPI {
+  /** Register a new agent instance. */
+  register(options: RegisterAgentOptions): Promise<AgentInstanceRow>;
+  /** Deregister an agent instance. */
+  deregister(agentId: string): Promise<AgentInstanceRow | null>;
+  /** Get health status for a specific agent. */
+  health(agentId: string): Promise<AgentHealthStatus | null>;
+  /** Detect agents that have crashed (missed heartbeats). */
+  detectCrashed(thresholdMs?: number): Promise<AgentInstanceRow[]>;
+  /** Record a heartbeat for an agent. */
+  recordHeartbeat(agentId: string): Promise<unknown>;
+  /** Get capacity info for an agent. */
+  capacity(agentId: string): Promise<AgentCapacity | null>;
+  /** Check if system is overloaded (available capacity below threshold). */
+  isOverloaded(threshold?: number): Promise<boolean>;
+  /** List all agent instances with optional filters. */
+  list(params?: { status?: string; agentType?: string }): Promise<AgentInstanceRow[]>;
+}
+
+export interface IntelligenceAPI {
+  /** Predict impact of a change description on related tasks. */
+  predictImpact(change: string): Promise<ImpactReport>;
+  /** Calculate blast radius for a task change. */
+  blastRadius(taskId: string): Promise<BlastRadius>;
+}
+
 // ============================================================================
 // Init options
 // ============================================================================
@@ -410,6 +471,9 @@ export class Cleo {
       delete: (p) => deleteTask({ taskId: p.taskId, force: p.force }, root, store),
       archive: (p) =>
         archiveTasks({ before: p?.before, taskIds: p?.taskIds, dryRun: p?.dryRun }, root, store),
+      start: (taskId) => startTask(taskId, root, store),
+      stop: () => stopTask(root, store),
+      current: () => currentTask(root, store),
     };
   }
 
@@ -418,7 +482,12 @@ export class Cleo {
     const root = this.projectRoot;
     const store = this._store ?? undefined;
     return {
-      start: (p) => startSession({ name: p.name, scope: p.scope, agent: p.agent }, root, store),
+      start: (p) =>
+        startSession(
+          { name: p.name, scope: p.scope, agent: p.agent, startTask: p.startTask },
+          root,
+          store,
+        ),
       end: (p) => endSession({ note: p?.note }, root, store),
       status: () => sessionStatus(root, store),
       resume: (id) => resumeSession(id, root, store),
@@ -570,6 +639,38 @@ export class Cleo {
     };
   }
 
+  // === Agents ===
+  get agents(): AgentsAPI {
+    const root = this.projectRoot;
+    return {
+      register: (opts) => registerAgent(opts, root),
+      deregister: (agentId) => deregisterAgent(agentId, root),
+      health: (agentId) => checkAgentHealth(agentId, undefined, root),
+      detectCrashed: (thresholdMs) => detectCrashedAgents(thresholdMs, root),
+      recordHeartbeat: (agentId) => heartbeat(agentId, root),
+      capacity: (agentId) => getAgentCapacity(agentId, root),
+      isOverloaded: (threshold) => isOverloaded(threshold, root),
+      list: (p) =>
+        listAgentInstances(
+          {
+            status: p?.status as 'active' | 'idle' | 'crashed' | undefined,
+            agentType: p?.agentType as import('./agents/index.js').AgentType | undefined,
+          },
+          root,
+        ),
+    };
+  }
+
+  // === Intelligence ===
+  get intelligence(): IntelligenceAPI {
+    const root = this.projectRoot;
+    const store = this._store ?? undefined;
+    return {
+      predictImpact: (change) => predictImpact(change, root, store ?? undefined),
+      blastRadius: (taskId) => calculateBlastRadius(taskId, store ?? undefined, root),
+    };
+  }
+
   // === Sync (Task Reconciliation) ===
   get sync(): SyncAPI {
     const root = this.projectRoot;

package/src/scaffold.ts

@@ -14,6 +14,7 @@ import { execFile } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { existsSync, constants as fsConstants, readFileSync, statSync } from 'node:fs';
 import { access, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { homedir as getHomedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { promisify } from 'node:util';
@@ -1278,12 +1279,33 @@ export function checkGlobalTemplates(): CheckResult {
     };
   }
 
+  // Check version sync between XDG and legacy paths
+  const xdgContent = readFileSync(injectionPath, 'utf-8');
+  const xdgVersion = xdgContent.match(/^Version:\s*(.+)$/m)?.[1]?.trim();
+  const home = getHomedir();
+  const legacyPath = join(home, '.cleo', 'templates', 'CLEO-INJECTION.md');
+
+  if (existsSync(legacyPath)) {
+    const legacyContent = readFileSync(legacyPath, 'utf-8');
+    const legacyVersion = legacyContent.match(/^Version:\s*(.+)$/m)?.[1]?.trim();
+    if (legacyVersion && xdgVersion && legacyVersion !== xdgVersion) {
+      return {
+        id: 'global_templates',
+        category: 'global',
+        status: 'warning',
+        message: `Legacy template version (${legacyVersion}) out of sync with XDG (${xdgVersion})`,
+        details: { path: injectionPath, exists: true, xdgVersion, legacyVersion, legacyPath },
+        fix: 'npm install -g @cleocode/cleo (reinstall syncs both paths)',
+      };
+    }
+  }
+
   return {
     id: 'global_templates',
     category: 'global',
     status: 'passed',
-    message: 'Global injection template present',
-    details: { path: injectionPath, exists: true },
+    message: `Global injection template present (v${xdgVersion ?? 'unknown'})`,
+    details: { path: injectionPath, exists: true, version: xdgVersion },
     fix: null,
   };
 }