@cleocode/core 2026.3.58 → 2026.3.60

package/src/agents/index.ts

@@ -11,6 +11,17 @@
  * @module agents
  */
 
+// Load-balancing registry: task-count capacity, specializations, performance recording
+export {
+  type AgentCapacity,
+  type AgentPerformanceMetrics,
+  getAgentCapacity,
+  getAgentSpecializations,
+  getAgentsByCapacity,
+  MAX_TASKS_PER_AGENT,
+  recordAgentPerformance,
+  updateAgentSpecializations,
+} from './agent-registry.js';
 // Schema & types
 export {
   AGENT_INSTANCE_STATUSES,
@@ -47,10 +58,22 @@ export {
   recordFailurePattern,
   storeHealingStrategy,
 } from './execution-learning.js';
+// Health monitoring (T039)
+export {
+  type AgentHealthStatus,
+  checkAgentHealth,
+  detectCrashedAgents,
+  detectStaleAgents,
+  HEARTBEAT_INTERVAL_MS,
+  recordHeartbeat,
+  STALE_THRESHOLD_MS,
+} from './health-monitor.js';
 // Registry (CRUD, heartbeat, health, errors)
+// Note: registry.checkAgentHealth (thresholdMs, cwd) -> AgentInstanceRow[] is exported
+// as findStaleAgentRows to avoid conflict with health-monitor.checkAgentHealth (T039).
 export {
   type AgentHealthReport,
-  checkAgentHealth,
+  checkAgentHealth as findStaleAgentRows,
   classifyError,
   deregisterAgent,
   generateAgentId,

package/src/agents/retry.ts

@@ -47,6 +47,17 @@ export const DEFAULT_RETRY_POLICY: Readonly<RetryPolicy> = Object.freeze({
 
 /**
  * Create a retry policy by merging overrides with the default policy.
+ *
+ * @remarks
+ * Unspecified fields fall back to {@link DEFAULT_RETRY_POLICY}.
+ *
+ * @param overrides - Partial policy to merge with defaults
+ * @returns A complete RetryPolicy
+ *
+ * @example
+ * ```ts
+ * const policy = createRetryPolicy({ maxRetries: 5 });
+ * ```
  */
 export function createRetryPolicy(overrides?: Partial<RetryPolicy>): RetryPolicy {
   return { ...DEFAULT_RETRY_POLICY, ...overrides };
@@ -55,8 +66,19 @@ export function createRetryPolicy(overrides?: Partial<RetryPolicy>): RetryPolicy
 /**
  * Calculate the delay for a given retry attempt using exponential backoff.
  *
- * Formula: min(baseDelay * multiplier^attempt, maxDelay) + jitter
+ * @remarks
+ * Formula: `min(baseDelay * multiplier^attempt, maxDelay) + jitter`.
  * Jitter adds 0-25% randomness to prevent thundering herd.
+ *
+ * @param attempt - Zero-based attempt index
+ * @param policy - Retry policy with delay configuration
+ * @returns Delay in milliseconds before the next attempt
+ *
+ * @example
+ * ```ts
+ * const delay = calculateDelay(1, createRetryPolicy());
+ * // => ~2000ms (with jitter)
+ * ```
  */
 export function calculateDelay(attempt: number, policy: RetryPolicy): number {
   const exponentialDelay = policy.baseDelayMs * policy.backoffMultiplier ** attempt;
@@ -73,6 +95,20 @@ export function calculateDelay(attempt: number, policy: RetryPolicy): number {
 /**
  * Determine whether an error should be retried based on its classification
  * and the retry policy.
+ *
+ * @remarks
+ * Permanent errors are never retried. Retriable errors are always retried
+ * (within attempt limits). Unknown errors defer to `policy.retryOnUnknown`.
+ *
+ * @param error - The caught error to classify
+ * @param attempt - Current attempt number (0-based)
+ * @param policy - Retry policy with limits and classification rules
+ * @returns True if the error should be retried
+ *
+ * @example
+ * ```ts
+ * if (shouldRetry(err, attempt, policy)) { /* retry *\/ }
+ * ```
  */
 export function shouldRetry(error: unknown, attempt: number, policy: RetryPolicy): boolean {
   if (attempt >= policy.maxRetries) return false;
@@ -102,13 +138,20 @@ export interface RetryResult<T> {
 /**
  * Wrap an async function with retry logic using configurable exponential backoff.
  *
- * The function will be retried according to the policy when retriable errors
- * occur. Permanent errors cause immediate failure. Unknown errors respect
- * the `retryOnUnknown` policy setting.
+ * @remarks
+ * Agent-specific variant that integrates with error classification from the
+ * agent registry. For a dependency-free generic retry, use `lib/retry.ts`.
  *
+ * @typeParam T - The resolved type of the async function
  * @param fn - The async function to execute with retries
  * @param policy - Retry policy (uses DEFAULT_RETRY_POLICY if not provided)
  * @returns The result of the operation with retry metadata
+ *
+ * @example
+ * ```ts
+ * const result = await withRetry(() => fetchAgentTask(agentId));
+ * if (!result.success) console.error(result.error);
+ * ```
  */
 export async function withRetry<T>(
   fn: () => Promise<T>,
@@ -176,9 +219,19 @@ export interface AgentRecoveryResult {
  * classified as 'permanent' are abandoned. Agents with retriable errors
  * are reset to 'starting' for the orchestration layer to re-assign.
  *
+ * @remarks
+ * Two-phase process: first detects stale agents via heartbeat threshold,
+ * then evaluates each crashed agent's error history for recoverability.
+ *
  * @param thresholdMs - Heartbeat threshold for crash detection (default: 30000)
  * @param cwd - Working directory
  * @returns Recovery results for each crashed agent
+ *
+ * @example
+ * ```ts
+ * const results = await recoverCrashedAgents(60_000);
+ * results.filter(r => r.recovered).forEach(r => console.log(r.agentId));
+ * ```
  */
 export async function recoverCrashedAgents(
   thresholdMs: number = 30_000,

package/src/backfill/index.ts

@@ -8,6 +8,7 @@
  *   backfillTasks(root, {})                  -- apply changes
  *   backfillTasks(root, { rollback: true })  -- revert backfill
  *
+ * @packageDocumentation
  * @epic T056
  * @task T066
  */
@@ -60,6 +61,20 @@ export interface BackfillResult {
 /**
  * Generate 3 baseline acceptance criteria from a task description.
  * Uses simple text analysis — no LLM required.
+ *
+ * @remarks
+ * Extracts action verbs from the title + description to produce contextually
+ * relevant criteria. Falls back to generic criteria when no verbs match.
+ *
+ * @param title - The task title
+ * @param description - The task description
+ * @returns Array of 3 acceptance criteria strings
+ *
+ * @example
+ * ```ts
+ * generateAcFromDescription('Fix login bug', 'Users cannot log in');
+ * // => ['The defect is resolved...', 'No breaking changes...', 'Changes verified...']
+ * ```
  */
 export function generateAcFromDescription(title: string, description: string): string[] {
   const text = `${title} ${description}`.toLowerCase();
@@ -144,8 +159,20 @@ function isBackfilledTask(task: Task): boolean {
 /**
  * Retroactively populate AC and verification metadata for tasks that lack them.
  *
+ * @remarks
+ * In dry-run mode, computes changes without writing to the database.
+ * Backfilled tasks are tagged with a note so they can be identified and
+ * optionally rolled back later.
+ *
  * @param projectRoot - Project root directory (cwd for CLEO operations)
  * @param options     - Backfill options (dryRun, rollback, taskIds)
+ * @returns Summary of changes applied (or previewed in dry-run mode)
+ *
+ * @example
+ * ```ts
+ * const result = await backfillTasks('/my/project', { dryRun: true });
+ * console.log(result.changed); // number of tasks that would be modified
+ * ```
  */
 export async function backfillTasks(
   projectRoot: string,

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/config.ts

@@ -348,7 +348,7 @@ export const STRICTNESS_PRESETS: Record<StrictnessPreset, PresetDefinition> = {
       'session.autoStart': false,
       'session.requireNotes': true,
       'session.multiSession': false,
-      'hierarchy.requireAcceptanceCriteria': true,
+      'enforcement.acceptance.mode': 'block',
       'lifecycle.mode': 'strict',
     },
   },
@@ -359,7 +359,7 @@ export const STRICTNESS_PRESETS: Record<StrictnessPreset, PresetDefinition> = {
       'session.autoStart': false,
       'session.requireNotes': false,
       'session.multiSession': true,
-      'hierarchy.requireAcceptanceCriteria': false,
+      'enforcement.acceptance.mode': 'warn',
       'lifecycle.mode': 'advisory',
     },
   },
@@ -369,7 +369,7 @@ export const STRICTNESS_PRESETS: Record<StrictnessPreset, PresetDefinition> = {
       'session.autoStart': false,
       'session.requireNotes': false,
       'session.multiSession': true,
-      'hierarchy.requireAcceptanceCriteria': false,
+      'enforcement.acceptance.mode': 'off',
       'lifecycle.mode': 'off',
     },
   },

package/src/index.ts

@@ -40,6 +40,7 @@ export * as coreHooks from './hooks/index.js';
 export * as inject from './inject/index.js';
 export * as intelligence from './intelligence/index.js';
 export * as issue from './issue/index.js';
+export * as lib from './lib/index.js';
 export * as lifecycle from './lifecycle/index.js';
 export * as coreMcp from './mcp/index.js';
 export * as memory from './memory/index.js';