@cleocode/core 2026.3.59 → 2026.3.60

package/dist/hooks/registry.js

@@ -0,0 +1,176 @@
+/**
+ * Hook Registry System - Phase 2C of T5237
+ *
+ * Central registry for managing hook handlers with priority-based execution,
+ * async dispatch, and best-effort error handling. Integrates with CAAMP 1.6.0
+ * event definitions while providing CLEO's execution engine.
+ *
+ * @module @cleocode/cleo/hooks/registry
+ */
+import { getLogger } from '../logger.js';
+/**
+ * Default configuration for the hook system.
+ * All events are enabled by default.
+ */
+const DEFAULT_HOOK_CONFIG = {
+    enabled: true,
+    events: {
+        onSessionStart: true,
+        onSessionEnd: true,
+        onToolStart: true,
+        onToolComplete: true,
+        onFileChange: true,
+        onError: true,
+        onPromptSubmit: true,
+        onResponseComplete: true,
+        onWorkAvailable: true,
+        onAgentSpawn: true,
+        onAgentComplete: true,
+        onCascadeStart: true,
+        onPatrol: true,
+    },
+};
+/**
+ * Central registry for hook handlers.
+ *
+ * Manages registration, priority-based ordering, and async dispatch
+ * of hook handlers. Provides best-effort execution where errors in
+ * one handler do not block others.
+ */
+export class HookRegistry {
+    handlers = new Map();
+    config = DEFAULT_HOOK_CONFIG;
+    /**
+     * Register a hook handler for a specific event.
+     *
+     * Handlers are sorted by priority (highest first) and executed
+     * in parallel when the event is dispatched.
+     *
+     * @param registration - The hook registration containing event, handler, priority, and ID
+     * @returns A function to unregister the handler
+     *
+     * @example
+     * ```typescript
+     * const unregister = hooks.register({
+     *   id: 'my-handler',
+     *   event: 'onSessionStart',
+     *   handler: async (root, payload) => { console.log('Session started'); },
+     *   priority: 100
+     * });
+     *
+     * // Later: unregister()
+     * ```
+     */
+    register(registration) {
+        const list = this.handlers.get(registration.event) || [];
+        list.push(registration);
+        // Sort by priority (highest first)
+        list.sort((a, b) => b.priority - a.priority);
+        this.handlers.set(registration.event, list);
+        // Return unregister function
+        return () => {
+            const handlers = this.handlers.get(registration.event);
+            if (handlers) {
+                const idx = handlers.findIndex((h) => h.id === registration.id);
+                if (idx !== -1)
+                    handlers.splice(idx, 1);
+            }
+        };
+    }
+    /**
+     * Dispatch an event to all registered handlers.
+     *
+     * Executes handlers in parallel using Promise.allSettled for best-effort
+     * execution. Errors in individual handlers are logged but do not block
+     * other handlers or propagate to the caller.
+     *
+     * @param event - The CAAMP hook event to dispatch
+     * @param projectRoot - The project root directory path
+     * @param payload - The event payload (typed by event)
+     * @returns Promise that resolves when all handlers have completed
+     *
+     * @example
+     * ```typescript
+     * await hooks.dispatch('onSessionStart', '/project', {
+     *   timestamp: new Date().toISOString(),
+     *   sessionId: 'sess-123',
+     *   name: 'My Session',
+     *   scope: 'feature'
+     * });
+     * ```
+     */
+    async dispatch(event, projectRoot, payload) {
+        // Check if hooks enabled globally
+        if (!this.config.enabled)
+            return;
+        // Check if this event enabled
+        if (!this.config.events[event])
+            return;
+        const handlers = this.handlers.get(event);
+        if (!handlers || handlers.length === 0)
+            return;
+        // Execute all handlers in parallel (best-effort)
+        await Promise.allSettled(handlers.map(async (reg) => {
+            try {
+                await reg.handler(projectRoot, payload);
+            }
+            catch (error) {
+                // Hooks are best-effort - log but don't throw
+                getLogger('hooks').warn({ err: error, hookId: reg.id, event }, 'Hook handler failed');
+            }
+        }));
+    }
+    /**
+     * Check if a specific event is currently enabled.
+     *
+     * Both the global enabled flag and the per-event flag must be true.
+     *
+     * @param event - The CAAMP hook event to check
+     * @returns True if the event is enabled
+     */
+    isEnabled(event) {
+        return this.config.enabled && this.config.events[event];
+    }
+    /**
+     * Update the hook system configuration.
+     *
+     * Merges the provided config with the existing config.
+     *
+     * @param config - Partial configuration to apply
+     *
+     * @example
+     * ```typescript
+     * hooks.setConfig({ enabled: false }); // Disable all hooks
+     * hooks.setConfig({ events: { onError: false } }); // Disable specific event
+     * ```
+     */
+    setConfig(config) {
+        this.config = { ...this.config, ...config };
+    }
+    /**
+     * Get the current hook configuration.
+     *
+     * @returns A copy of the current configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * List all registered handlers for a specific event.
+     *
+     * Returns handlers in priority order (highest first).
+     *
+     * @param event - The CAAMP hook event
+     * @returns Array of hook registrations
+     */
+    listHandlers(event) {
+        return [...(this.handlers.get(event) || [])];
+    }
+}
+/**
+ * Singleton instance of the HookRegistry.
+ *
+ * Use this instance for all hook operations throughout the application.
+ */
+export const hooks = new HookRegistry();
+//# sourceMappingURL=registry.js.map

package/dist/hooks/registry.js.map

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

package/dist/hooks/types.js

@@ -0,0 +1,62 @@
+/**
+ * Universal Hooks Core Types - Phase 2B of T5237
+ *
+ * This module defines the core type system for CLEO's Universal Hooks
+ * integration with CAAMP 1.6.0. CLEO builds the hook registry and
+ * execution system while CAAMP provides the event definitions.
+ *
+ * @module @cleocode/cleo/hooks/types
+ */
+// Re-export CAAMP provider query functions for hook capability discovery
+export { getCommonHookEvents, getProvidersByHookEvent } from '@cleocode/caamp';
+/**
+ * CLEO-local coordination events used by the autonomous runtime.
+ *
+ * These are internal lifecycle signals for worker orchestration and are not
+ * surfaced through CAAMP's provider capability registry.
+ */
+export const INTERNAL_HOOK_EVENTS = [
+    'onWorkAvailable',
+    'onAgentSpawn',
+    'onAgentComplete',
+    'onCascadeStart',
+    'onPatrol',
+];
+const INTERNAL_HOOK_EVENT_SET = new Set(INTERNAL_HOOK_EVENTS);
+/**
+ * Type guard for CAAMP/provider-discoverable hook events.
+ */
+export function isProviderHookEvent(event) {
+    return !INTERNAL_HOOK_EVENT_SET.has(event);
+}
+/**
+ * Type guard for CLEO-local coordination hook events.
+ */
+export function isInternalHookEvent(event) {
+    return INTERNAL_HOOK_EVENT_SET.has(event);
+}
+/**
+ * Mapping from CLEO internal lifecycle events to CAAMP hook events
+ * This is where CLEO connects its lifecycle to CAAMP's event definitions
+ */
+export const CLEO_TO_CAAMP_HOOK_MAP = {
+    'session.start': 'onSessionStart',
+    'session.end': 'onSessionEnd',
+    'task.start': 'onToolStart',
+    'task.complete': 'onToolComplete',
+    'file.change': 'onFileChange',
+    'system.error': 'onError',
+    'prompt.submit': 'onPromptSubmit',
+    'response.complete': 'onResponseComplete',
+};
+/**
+ * Internal CLEO lifecycle events that drive autonomous coordination.
+ */
+export const CLEO_INTERNAL_HOOK_MAP = {
+    'agent.work.available': 'onWorkAvailable',
+    'agent.spawn': 'onAgentSpawn',
+    'agent.complete': 'onAgentComplete',
+    'cascade.start': 'onCascadeStart',
+    'watcher.patrol': 'onPatrol',
+};
+//# sourceMappingURL=types.js.map

package/dist/hooks/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/hooks/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,yEAAyE;AACzE,OAAO,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAO/E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,iBAAiB;IACjB,cAAc;IACd,iBAAiB;IACjB,gBAAgB;IAChB,UAAU;CACF,CAAC;AAYX,MAAM,uBAAuB,GAAG,IAAI,GAAG,CAAS,oBAAoB,CAAC,CAAC;AAEtE;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAgB;IAClD,OAAO,CAAC,uBAAuB,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AAC7C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAgB;IAClD,OAAO,uBAAuB,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AAC5C,CAAC;AAwSD;;;GAGG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,eAAe,EAAE,gBAAgB;IACjC,aAAa,EAAE,cAAc;IAC7B,YAAY,EAAE,aAAa;IAC3B,eAAe,EAAE,gBAAgB;IACjC,aAAa,EAAE,cAAc;IAC7B,cAAc,EAAE,SAAS;IACzB,eAAe,EAAE,gBAAgB;IACjC,mBAAmB,EAAE,oBAAoB;CACjC,CAAC;AAEX;;GAEG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,sBAAsB,EAAE,iBAAiB;IACzC,aAAa,EAAE,cAAc;IAC7B,gBAAgB,EAAE,iBAAiB;IACnC,eAAe,EAAE,gBAAgB;IACjC,gBAAgB,EAAE,UAAU;CACpB,CAAC"}

package/dist/hooks.js

@@ -0,0 +1,136 @@
+/**
+ * Git hook management utilities.
+ *
+ * Extracted from init.ts to enable shared use across init, upgrade, and
+ * doctor/health-check workflows.
+ *
+ * Handles installation, update, and verification of managed git hooks
+ * from the package's templates/git-hooks/ directory.
+ */
+import { existsSync } from 'node:fs';
+import { chmod, copyFile, mkdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { getPackageRoot } from './scaffold.js';
+// ── Constants ────────────────────────────────────────────────────────
+/** Git hooks managed by CLEO. */
+export const MANAGED_HOOKS = ['commit-msg', 'pre-commit', 'pre-push'];
+// ── ensureGitHooks ───────────────────────────────────────────────────
+/**
+ * Install or update managed git hooks from templates/git-hooks/ into .git/hooks/.
+ *
+ * Handles:
+ * - No .git directory (skips gracefully)
+ * - No source templates directory (skips gracefully)
+ * - Hooks already installed (skips unless force)
+ * - Sets executable permissions on installed hooks
+ */
+export async function ensureGitHooks(projectRoot, opts) {
+    const gitDir = join(projectRoot, '.git');
+    const gitHooksDir = join(gitDir, 'hooks');
+    if (!existsSync(gitDir)) {
+        return {
+            action: 'skipped',
+            path: gitHooksDir,
+            details: 'No .git/ directory found, skipping git hook installation',
+        };
+    }
+    const packageRoot = getPackageRoot();
+    const sourceDir = join(packageRoot, 'templates', 'git-hooks');
+    if (!existsSync(sourceDir)) {
+        return {
+            action: 'skipped',
+            path: sourceDir,
+            details: 'templates/git-hooks/ not found in package root, skipping git hook installation',
+        };
+    }
+    await mkdir(gitHooksDir, { recursive: true });
+    const force = opts?.force ?? false;
+    let installedCount = 0;
+    const errors = [];
+    for (const hook of MANAGED_HOOKS) {
+        const sourcePath = join(sourceDir, hook);
+        const destPath = join(gitHooksDir, hook);
+        if (!existsSync(sourcePath)) {
+            continue;
+        }
+        if (existsSync(destPath) && !force) {
+            continue;
+        }
+        try {
+            await copyFile(sourcePath, destPath);
+            await chmod(destPath, 0o755);
+            installedCount++;
+        }
+        catch (err) {
+            errors.push(`Failed to install git hook ${hook}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    if (errors.length > 0) {
+        return {
+            action: 'repaired',
+            path: gitHooksDir,
+            details: `Installed ${installedCount} hook(s) with ${errors.length} error(s): ${errors.join('; ')}`,
+        };
+    }
+    if (installedCount === 0) {
+        return {
+            action: 'skipped',
+            path: gitHooksDir,
+            details: 'All managed hooks already installed',
+        };
+    }
+    return {
+        action: 'created',
+        path: gitHooksDir,
+        details: `Installed ${installedCount} git hooks`,
+    };
+}
+// ── checkGitHooks ────────────────────────────────────────────────────
+/**
+ * Verify managed hooks are installed and current.
+ *
+ * Compares installed hooks in .git/hooks/ against source templates in the
+ * package's templates/git-hooks/ directory. Returns per-hook status including
+ * whether the hook is installed and whether its content matches the source.
+ */
+export async function checkGitHooks(projectRoot) {
+    const gitHooksDir = join(projectRoot, '.git', 'hooks');
+    const packageRoot = getPackageRoot();
+    const sourceDir = join(packageRoot, 'templates', 'git-hooks');
+    const results = [];
+    for (const hook of MANAGED_HOOKS) {
+        const sourcePath = join(sourceDir, hook);
+        const installedPath = join(gitHooksDir, hook);
+        const result = {
+            hook,
+            installed: false,
+            current: false,
+            sourcePath,
+            installedPath,
+        };
+        if (!existsSync(sourcePath)) {
+            // No source template — nothing to compare against
+            results.push(result);
+            continue;
+        }
+        if (!existsSync(installedPath)) {
+            results.push(result);
+            continue;
+        }
+        result.installed = true;
+        try {
+            const [sourceContent, installedContent] = await Promise.all([
+                readFile(sourcePath, 'utf-8'),
+                readFile(installedPath, 'utf-8'),
+            ]);
+            result.current = sourceContent === installedContent;
+        }
+        catch {
+            // If we can't read either file, mark as not current
+            result.current = false;
+        }
+        results.push(result);
+    }
+    return results;
+}
+//# sourceMappingURL=hooks.js.map

package/dist/hooks.js.map

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

package/dist/index.js

@@ -19102,6 +19102,7 @@ import { execFile as execFile3 } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { existsSync as existsSync33, constants as fsConstants3, readFileSync as readFileSync22, statSync as statSync8 } from "node:fs";
 import { access as access3, mkdir as mkdir5, readFile as readFile6, rm as rm2, writeFile as writeFile5 } from "node:fs/promises";
+import { homedir as getHomedir } from "node:os";
 import { dirname as dirname8, join as join37, resolve as resolve5 } from "node:path";
 import { fileURLToPath as fileURLToPath4 } from "node:url";
 import { promisify as promisify3 } from "node:util";
@@ -19913,12 +19914,30 @@ function checkGlobalTemplates() {
       fix: "cleo init (or restart MCP server)"
     };
   }
+  const xdgContent = readFileSync22(injectionPath, "utf-8");
+  const xdgVersion = xdgContent.match(/^Version:\s*(.+)$/m)?.[1]?.trim();
+  const home = getHomedir();
+  const legacyPath = join37(home, ".cleo", "templates", "CLEO-INJECTION.md");
+  if (existsSync33(legacyPath)) {
+    const legacyContent = readFileSync22(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
   };
 }
@@ -64457,46 +64476,68 @@ async function bootstrapGlobalCleo(options) {
   await installSkillsGlobally(ctx);
   await installAgentDefinitionGlobally(ctx);
   await installProviderAdapters(ctx, options?.packageRoot);
+  await verifyBootstrapHealth(ctx);
   return ctx;
 }
+async function writeTemplateTo(content, destPath, isDryRun) {
+  if (isDryRun) return false;
+  const { dirname: dirname20 } = await import("node:path");
+  await mkdir17(dirname20(destPath), { recursive: true });
+  await writeFile12(destPath, content);
+  return true;
+}
 async function ensureGlobalTemplatesBootstrap(ctx, packageRootOverride) {
   const globalTemplatesDir = getCleoTemplatesDir();
   if (!ctx.isDryRun) {
     await mkdir17(globalTemplatesDir, { recursive: true });
   }
+  let templateContent = null;
   try {
     const pkgRoot = packageRootOverride ?? getPackageRoot();
     const templatePath = join104(pkgRoot, "templates", "CLEO-INJECTION.md");
     if (existsSync103(templatePath)) {
-      const content = readFileSync77(templatePath, "utf-8");
-      const destPath = join104(globalTemplatesDir, "CLEO-INJECTION.md");
-      if (!ctx.isDryRun) {
-        await writeFile12(destPath, content);
-      }
-      ctx.created.push(
-        `~/.cleo/templates/CLEO-INJECTION.md (${ctx.isDryRun ? "would refresh" : "refreshed"})`
-      );
-    } else {
-      try {
-        const { getInjectionTemplateContent: getInjectionTemplateContent2 } = await Promise.resolve().then(() => (init_injection(), injection_exports));
-        const content = getInjectionTemplateContent2();
-        if (content) {
-          const destPath = join104(globalTemplatesDir, "CLEO-INJECTION.md");
-          if (!ctx.isDryRun) {
-            await writeFile12(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 = readFileSync77(templatePath, "utf-8");
     }
   } catch {
+  }
+  if (!templateContent) {
+    try {
+      const { getInjectionTemplateContent: getInjectionTemplateContent2 } = await Promise.resolve().then(() => (init_injection(), injection_exports));
+      templateContent = getInjectionTemplateContent2() ?? 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;
+  }
+  const xdgDest = join104(globalTemplatesDir, "CLEO-INJECTION.md");
+  const xdgWritten = await writeTemplateTo(templateContent, xdgDest, ctx.isDryRun);
+  ctx.created.push(
+    `${getCleoTemplatesTildePath()}/CLEO-INJECTION.md (${xdgWritten ? "refreshed" : "would refresh"})`
+  );
+  const home = homedir6();
+  const legacyTemplatesDir = join104(home, ".cleo", "templates");
+  if (legacyTemplatesDir !== globalTemplatesDir && existsSync103(join104(home, ".cleo"))) {
+    const legacyDest = join104(legacyTemplatesDir, "CLEO-INJECTION.md");
+    const legacyWritten = await writeTemplateTo(templateContent, legacyDest, ctx.isDryRun);
+    if (legacyWritten) {
+      ctx.created.push("~/.cleo/templates/CLEO-INJECTION.md (legacy sync)");
+    }
   }
 }
+function sanitizeCaampFile(content) {
+  let cleaned = content.replace(/(<!-- CAAMP:END -->)\s*(<!-- CAAMP:END -->)/g, "$1");
+  cleaned = cleaned.replace(
+    /<!-- CAAMP:END -->\s*[A-Z][A-Za-z-]*\.md\s*(?:<!-- CAAMP:END -->)?/g,
+    "<!-- CAAMP:END -->"
+  );
+  cleaned = cleaned.replace(/^[A-Z][A-Za-z-]*\.md\s*$/gm, "");
+  cleaned = cleaned.replace(/\n{3,}/g, "\n\n");
+  return cleaned.trim() + "\n";
+}
 async function injectAgentsHub(ctx) {
   const globalAgentsDir = getAgentsHome();
   const globalAgentsMd = join104(globalAgentsDir, "AGENTS.md");
@@ -64510,13 +64551,23 @@ async function injectAgentsHub(ctx) {
           /\n?<!-- CLEO:START[^>]*-->[\s\S]*?<!-- CLEO:END -->\n?/g,
           ""
         );
-        if (stripped !== content) {
-          await writeFile12(globalAgentsMd, stripped, "utf8");
+        const sanitized = sanitizeCaampFile(stripped);
+        if (sanitized !== content) {
+          await writeFile12(globalAgentsMd, sanitized, "utf8");
+          ctx.created.push("~/.agents/AGENTS.md (sanitized CAAMP corruption)");
         }
       }
       const templateRef = `@${getCleoTemplatesTildePath()}/CLEO-INJECTION.md`;
       const action = await inject2(globalAgentsMd, templateRef);
       ctx.created.push(`~/.agents/AGENTS.md (${action})`);
+      const postContent = await readFile19(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)");
     }
@@ -64650,6 +64701,45 @@ async function installProviderAdapters(ctx, packageRootOverride) {
     );
   }
 }
+async function verifyBootstrapHealth(ctx) {
+  if (ctx.isDryRun) return;
+  try {
+    const xdgTemplatePath = join104(getCleoTemplatesDir(), "CLEO-INJECTION.md");
+    const agentsMd = join104(getAgentsHome(), "AGENTS.md");
+    if (!existsSync103(xdgTemplatePath)) {
+      ctx.warnings.push("Health: XDG template missing after bootstrap");
+      return;
+    }
+    const xdgContent = await readFile19(xdgTemplatePath, "utf8");
+    const xdgVersion = xdgContent.match(/^Version:\s*(.+)$/m)?.[1]?.trim();
+    const home = homedir6();
+    const legacyTemplatePath = join104(home, ".cleo", "templates", "CLEO-INJECTION.md");
+    if (existsSync103(legacyTemplatePath)) {
+      const legacyContent = await readFile19(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})`
+        );
+      }
+    }
+    if (existsSync103(agentsMd)) {
+      const agentsContent = await readFile19(agentsMd, "utf8");
+      const expectedRef = `@${getCleoTemplatesTildePath()}/CLEO-INJECTION.md`;
+      if (!agentsContent.includes(expectedRef)) {
+        ctx.warnings.push(`Health: ~/.agents/AGENTS.md does not reference ${expectedRef}`);
+      }
+      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 {
+  }
+}
 
 // packages/core/src/cleo.ts
 import path from "node:path";
@@ -64724,7 +64814,10 @@ var Cleo = class _Cleo {
       ),
       complete: (p) => completeTask({ taskId: p.taskId, notes: p.notes }, root, store),
       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)
+      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)
     };
   }
   // === Sessions ===
@@ -64732,7 +64825,11 @@ var Cleo = class _Cleo {
     const root = this.projectRoot;
     const store = this._store ?? void 0;
     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),
@@ -64870,6 +64967,35 @@ var Cleo = class _Cleo {
       sharingStatus: () => getSharingStatus()
     };
   }
+  // === Agents ===
+  get agents() {
+    const root = this.projectRoot;
+    return {
+      register: (opts) => registerAgent(opts, root),
+      deregister: (agentId) => deregisterAgent(agentId, root),
+      health: (agentId) => checkAgentHealth2(agentId, void 0, 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,
+          agentType: p?.agentType
+        },
+        root
+      )
+    };
+  }
+  // === Intelligence ===
+  get intelligence() {
+    const root = this.projectRoot;
+    const store = this._store ?? void 0;
+    return {
+      predictImpact: (change) => predictImpact(change, root, store ?? void 0),
+      blastRadius: (taskId) => calculateBlastRadius(taskId, store ?? void 0, root)
+    };
+  }
   // === Sync (Task Reconciliation) ===
   get sync() {
     const root = this.projectRoot;