@cleocode/core 2026.3.58 → 2026.3.60

package/dist/agents/health-monitor.js

@@ -0,0 +1,217 @@
+/**
+ * Agent Health Monitoring -- Heartbeat and crash detection for live agent instances.
+ *
+ * Provides the public-facing health API specified by T039:
+ *   - `recordHeartbeat`    — update last_heartbeat for a live agent
+ *   - `checkAgentHealth`   — check health of a specific agent by ID
+ *   - `detectStaleAgents`  — find agents whose heartbeat is older than threshold
+ *   - `detectCrashedAgents` — find active agents with no heartbeat for >3 min
+ *
+ * These functions delegate to the lower-level `registry.ts` primitives
+ * (`heartbeat`, `checkAgentHealth`, `listAgentInstances`) and add the
+ * named, task-spec-aligned surface required for T039.
+ *
+ * @module agents/health-monitor
+ * @task T039
+ * @epic T038
+ */
+import { heartbeat, listAgentInstances, markCrashed } from './registry.js';
+// ============================================================================
+// Constants
+// ============================================================================
+/** Default heartbeat interval (30 seconds) per BRAIN spec. */
+export const HEARTBEAT_INTERVAL_MS = 30_000;
+/** Default staleness threshold: 3 minutes without a heartbeat. */
+export const STALE_THRESHOLD_MS = 3 * 60_000;
+/** Statuses considered "alive" for health-check purposes. */
+const ALIVE_STATUSES = ['starting', 'active', 'idle'];
+// ============================================================================
+// recordHeartbeat
+// ============================================================================
+/**
+ * Record a heartbeat for an agent instance.
+ *
+ * Updates `last_heartbeat` to the current time and returns the agent's
+ * current {@link AgentInstanceStatus}. Returns `null` if the agent does not
+ * exist or is already in a terminal state (`stopped` / `crashed`).
+ *
+ * This is the primary mechanism by which long-running agents signal liveness.
+ * Call this every {@link HEARTBEAT_INTERVAL_MS} (30 s) from the agent loop.
+ *
+ * @param agentId - The agent instance ID (e.g. `agt_20260322120000_a1b2c3`)
+ * @param cwd - Working directory used to resolve the tasks.db path (optional)
+ * @returns The agent's current status, or `null` if not found / terminal
+ *
+ * @remarks
+ * Terminal agents (`stopped`, `crashed`) will NOT have their heartbeat
+ * updated — the existing status is returned as-is so callers can detect
+ * external shutdown signals.
+ *
+ * @example
+ * ```ts
+ * // Inside the agent's main loop:
+ * const heartbeatTimer = setInterval(async () => {
+ *   const status = await recordHeartbeat(agentId);
+ *   if (status === 'stopped' || status === null) {
+ *     // Orchestrator shut us down — exit cleanly
+ *     clearInterval(heartbeatTimer);
+ *     process.exit(0);
+ *   }
+ * }, HEARTBEAT_INTERVAL_MS);
+ * ```
+ */
+export async function recordHeartbeat(agentId, cwd) {
+    return heartbeat(agentId, cwd);
+}
+// ============================================================================
+// checkAgentHealth
+// ============================================================================
+/**
+ * Check the health of a specific agent instance by ID.
+ *
+ * Queries the agent's current record and returns a structured
+ * {@link AgentHealthStatus} describing staleness, heartbeat age, and
+ * whether the agent is considered healthy relative to `thresholdMs`.
+ *
+ * Returns `null` if the agent ID is not found in the database.
+ *
+ * @param agentId - The agent instance ID to check
+ * @param thresholdMs - Staleness threshold in milliseconds (default: 3 minutes)
+ * @param cwd - Working directory used to resolve the tasks.db path (optional)
+ * @returns {@link AgentHealthStatus} or `null` if the agent does not exist
+ *
+ * @remarks
+ * Returns null if the agent is not found. A non-null result includes
+ * staleness status based on the threshold comparison.
+ *
+ * @example
+ * ```ts
+ * const health = await checkAgentHealth('agt_20260322120000_a1b2c3');
+ * if (health && health.stale) {
+ *   console.log(`Agent stale for ${health.heartbeatAgeMs}ms — presumed crashed`);
+ * }
+ * ```
+ */
+export async function checkAgentHealth(agentId, thresholdMs = STALE_THRESHOLD_MS, cwd) {
+    const all = await listAgentInstances(undefined, cwd);
+    const agent = all.find((a) => a.id === agentId);
+    if (!agent)
+        return null;
+    return buildHealthStatus(agent, thresholdMs);
+}
+// ============================================================================
+// detectStaleAgents
+// ============================================================================
+/**
+ * Find all non-terminal agents whose last heartbeat is older than `thresholdMs`.
+ *
+ * "Stale" means an agent with status `starting`, `active`, or `idle` has
+ * not sent a heartbeat within the threshold window. This is a precursor to
+ * crash detection — a stale agent may still recover if it is under heavy load.
+ *
+ * Agents with status `stopped` or `crashed` are excluded — they are already
+ * in a terminal state and do not participate in the heartbeat protocol.
+ *
+ * @param thresholdMs - Staleness threshold in ms (default: 3 minutes / 180 000 ms)
+ * @param cwd - Working directory used to resolve the tasks.db path (optional)
+ * @returns Array of {@link AgentHealthStatus} for each stale agent, sorted by
+ *   heartbeat age descending (most-stale first)
+ *
+ * @remarks
+ * The default threshold matches the crash-detection window specified in T039:
+ * "timeout detection after 3 minutes".
+ *
+ * @example
+ * ```ts
+ * const stale = await detectStaleAgents();
+ * for (const s of stale) {
+ *   console.log(`${s.agentId} has been stale for ${s.heartbeatAgeMs / 1000}s`);
+ * }
+ * ```
+ */
+export async function detectStaleAgents(thresholdMs = STALE_THRESHOLD_MS, cwd) {
+    const agents = await listAgentInstances({ status: ALIVE_STATUSES }, cwd);
+    return agents
+        .map((a) => buildHealthStatus(a, thresholdMs))
+        .filter((s) => s.stale)
+        .sort((a, b) => b.heartbeatAgeMs - a.heartbeatAgeMs);
+}
+// ============================================================================
+// detectCrashedAgents
+// ============================================================================
+/**
+ * Find agents with status `active` whose heartbeat has been silent for
+ * longer than `thresholdMs`, and mark them as `crashed` in the database.
+ *
+ * An agent is considered crashed when it:
+ * 1. Has status `active` (not `idle`, `starting`, `stopped`, or `crashed`)
+ * 2. Has not sent a heartbeat for longer than `thresholdMs`
+ *
+ * Each detected agent is immediately marked `crashed` via {@link markCrashed},
+ * incrementing its error count and writing a reason to `agent_error_log`.
+ *
+ * @param thresholdMs - Crash threshold in ms (default: 3 minutes / 180 000 ms)
+ * @param cwd - Working directory used to resolve the tasks.db path (optional)
+ * @returns Array of agent instance rows for each agent that was just marked
+ *   `crashed`, sorted by last heartbeat ascending (oldest first).
+ *
+ * @remarks
+ * This function is WRITE-side: it mutates the database. Callers should run
+ * it on a schedule (e.g. every 60 s) from an orchestrator or health watchdog.
+ * For a read-only view, use {@link detectStaleAgents} instead.
+ *
+ * @example
+ * ```ts
+ * // Inside an orchestrator health watchdog:
+ * const crashed = await detectCrashedAgents();
+ * if (crashed.length > 0) {
+ *   logger.warn({ crashed: crashed.map(a => a.id) }, 'Agents marked crashed');
+ * }
+ * ```
+ */
+export async function detectCrashedAgents(thresholdMs = STALE_THRESHOLD_MS, cwd) {
+    // Only consider agents that are explicitly 'active' — idle/starting agents
+    // may not yet have established a regular heartbeat interval.
+    const activeAgents = await listAgentInstances({ status: 'active' }, cwd);
+    const cutoff = new Date(Date.now() - thresholdMs).toISOString();
+    const crashed = [];
+    for (const agent of activeAgents) {
+        if (agent.lastHeartbeat < cutoff) {
+            const updated = await markCrashed(agent.id, `Heartbeat timeout — no heartbeat for >${Math.round(thresholdMs / 1000)}s`, cwd);
+            if (updated) {
+                crashed.push(updated);
+            }
+        }
+    }
+    // Sort oldest-heartbeat first (most severely stale)
+    crashed.sort((a, b) => {
+        const aHb = a.lastHeartbeat ?? '';
+        const bHb = b.lastHeartbeat ?? '';
+        return aHb < bHb ? -1 : aHb > bHb ? 1 : 0;
+    });
+    return crashed;
+}
+// ============================================================================
+// Internal helpers
+// ============================================================================
+/**
+ * Build an {@link AgentHealthStatus} from a raw agent row.
+ */
+function buildHealthStatus(agent, thresholdMs) {
+    const lastHeartbeatMs = new Date(agent.lastHeartbeat).getTime();
+    const heartbeatAgeMs = Date.now() - lastHeartbeatMs;
+    const stale = ALIVE_STATUSES.includes(agent.status)
+        ? heartbeatAgeMs > thresholdMs
+        : false;
+    const healthy = !stale && ALIVE_STATUSES.includes(agent.status);
+    return {
+        agentId: agent.id,
+        status: agent.status,
+        lastHeartbeat: agent.lastHeartbeat,
+        heartbeatAgeMs,
+        healthy,
+        stale,
+        thresholdMs,
+    };
+}
+//# sourceMappingURL=health-monitor.js.map

package/dist/agents/health-monitor.js.map

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

package/dist/agents/index.d.ts

@@ -10,9 +10,11 @@
  *
  * @module agents
  */
+export { type AgentCapacity, type AgentPerformanceMetrics, getAgentCapacity, getAgentSpecializations, getAgentsByCapacity, MAX_TASKS_PER_AGENT, recordAgentPerformance, updateAgentSpecializations, } from './agent-registry.js';
 export { AGENT_INSTANCE_STATUSES, AGENT_TYPES, type AgentErrorLogRow, type AgentErrorType, type AgentInstanceRow, type AgentInstanceStatus, type AgentType, agentErrorLog, agentInstances, type NewAgentErrorLogRow, type NewAgentInstanceRow, } from './agent-schema.js';
 export { type CapacitySummary, findLeastLoadedAgent, getAvailableCapacity, getCapacitySummary, isOverloaded, updateCapacity, } from './capacity.js';
 export { type AgentExecutionEvent, type AgentExecutionOutcome, type AgentPerformanceSummary, getAgentPerformanceHistory, getSelfHealingSuggestions, type HealingSuggestion, processAgentLifecycleEvent, recordAgentExecution, recordFailurePattern, storeHealingStrategy, } from './execution-learning.js';
-export { type AgentHealthReport, checkAgentHealth, classifyError, deregisterAgent, generateAgentId, getAgentErrorHistory, getAgentInstance, getHealthReport, heartbeat, incrementTasksCompleted, type ListAgentFilters, listAgentInstances, markCrashed, type RegisterAgentOptions, registerAgent, type UpdateStatusOptions, updateAgentStatus, } from './registry.js';
+export { type AgentHealthStatus, checkAgentHealth, detectCrashedAgents, detectStaleAgents, HEARTBEAT_INTERVAL_MS, recordHeartbeat, STALE_THRESHOLD_MS, } from './health-monitor.js';
+export { type AgentHealthReport, checkAgentHealth as findStaleAgentRows, classifyError, deregisterAgent, generateAgentId, getAgentErrorHistory, getAgentInstance, getHealthReport, heartbeat, incrementTasksCompleted, type ListAgentFilters, listAgentInstances, markCrashed, type RegisterAgentOptions, registerAgent, type UpdateStatusOptions, updateAgentStatus, } from './registry.js';
 export { type AgentRecoveryResult, calculateDelay, createRetryPolicy, DEFAULT_RETRY_POLICY, type RetryPolicy, type RetryResult, recoverCrashedAgents, shouldRetry, withRetry, } from './retry.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/agents/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agents/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EACL,uBAAuB,EACvB,WAAW,EACX,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,SAAS,EACd,aAAa,EACb,cAAc,EACd,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,GACzB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,KAAK,eAAe,EACpB,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,YAAY,EACZ,cAAc,GACf,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,uBAAuB,EAC5B,0BAA0B,EAC1B,yBAAyB,EACzB,KAAK,iBAAiB,EACtB,0BAA0B,EAC1B,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,KAAK,iBAAiB,EACtB,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,eAAe,EACf,oBAAoB,EACpB,gBAAgB,EAChB,eAAe,EACf,SAAS,EACT,uBAAuB,EACvB,KAAK,gBAAgB,EACrB,kBAAkB,EAClB,WAAW,EACX,KAAK,oBAAoB,EACzB,aAAa,EACb,KAAK,mBAAmB,EACxB,iBAAiB,GAClB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,KAAK,mBAAmB,EACxB,cAAc,EACd,iBAAiB,EACjB,oBAAoB,EACpB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,oBAAoB,EACpB,WAAW,EACX,SAAS,GACV,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agents/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,uBAAuB,EAC5B,gBAAgB,EAChB,uBAAuB,EACvB,mBAAmB,EACnB,mBAAmB,EACnB,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,uBAAuB,EACvB,WAAW,EACX,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,SAAS,EACd,aAAa,EACb,cAAc,EACd,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,GACzB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,KAAK,eAAe,EACpB,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,YAAY,EACZ,cAAc,GACf,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,uBAAuB,EAC5B,0BAA0B,EAC1B,yBAAyB,EACzB,KAAK,iBAAiB,EACtB,0BAA0B,EAC1B,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,KAAK,iBAAiB,EACtB,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,EACf,kBAAkB,GACnB,MAAM,qBAAqB,CAAC;AAI7B,OAAO,EACL,KAAK,iBAAiB,EACtB,gBAAgB,IAAI,kBAAkB,EACtC,aAAa,EACb,eAAe,EACf,eAAe,EACf,oBAAoB,EACpB,gBAAgB,EAChB,eAAe,EACf,SAAS,EACT,uBAAuB,EACvB,KAAK,gBAAgB,EACrB,kBAAkB,EAClB,WAAW,EACX,KAAK,oBAAoB,EACzB,aAAa,EACb,KAAK,mBAAmB,EACxB,iBAAiB,GAClB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,KAAK,mBAAmB,EACxB,cAAc,EACd,iBAAiB,EACjB,oBAAoB,EACpB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,oBAAoB,EACpB,WAAW,EACX,SAAS,GACV,MAAM,YAAY,CAAC"}

package/dist/agents/index.js

@@ -10,12 +10,20 @@
  *
  * @module agents
  */
+// Load-balancing registry: task-count capacity, specializations, performance recording
+export { getAgentCapacity, getAgentSpecializations, getAgentsByCapacity, MAX_TASKS_PER_AGENT, recordAgentPerformance, updateAgentSpecializations, } from './agent-registry.js';
 // Schema & types
 export { AGENT_INSTANCE_STATUSES, AGENT_TYPES, agentErrorLog, agentInstances, } from './agent-schema.js';
 // Capacity tracking
 export { findLeastLoadedAgent, getAvailableCapacity, getCapacitySummary, isOverloaded, updateCapacity, } from './capacity.js';
+// Execution learning, failure pattern tracking, and self-healing
+export { getAgentPerformanceHistory, getSelfHealingSuggestions, processAgentLifecycleEvent, recordAgentExecution, recordFailurePattern, storeHealingStrategy, } from './execution-learning.js';
+// Health monitoring (T039)
+export { checkAgentHealth, detectCrashedAgents, detectStaleAgents, HEARTBEAT_INTERVAL_MS, recordHeartbeat, STALE_THRESHOLD_MS, } from './health-monitor.js';
 // Registry (CRUD, heartbeat, health, errors)
-export { checkAgentHealth, classifyError, deregisterAgent, generateAgentId, getAgentErrorHistory, getAgentInstance, getHealthReport, heartbeat, incrementTasksCompleted, listAgentInstances, markCrashed, registerAgent, updateAgentStatus, } from './registry.js';
+// Note: registry.checkAgentHealth (thresholdMs, cwd) -> AgentInstanceRow[] is exported
+// as findStaleAgentRows to avoid conflict with health-monitor.checkAgentHealth (T039).
+export { checkAgentHealth as findStaleAgentRows, classifyError, deregisterAgent, generateAgentId, getAgentErrorHistory, getAgentInstance, getHealthReport, heartbeat, incrementTasksCompleted, listAgentInstances, markCrashed, registerAgent, updateAgentStatus, } from './registry.js';
 // Retry & self-healing
 export { calculateDelay, createRetryPolicy, DEFAULT_RETRY_POLICY, recoverCrashedAgents, shouldRetry, withRetry, } from './retry.js';
 //# sourceMappingURL=index.js.map

package/dist/agents/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agents/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,iBAAiB;AACjB,OAAO,EACL,uBAAuB,EACvB,WAAW,EAMX,aAAa,EACb,cAAc,GAGf,MAAM,mBAAmB,CAAC;AAC3B,oBAAoB;AACpB,OAAO,EAEL,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,YAAY,EACZ,cAAc,GACf,MAAM,eAAe,CAAC;AACvB,6CAA6C;AAC7C,OAAO,EAEL,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,eAAe,EACf,oBAAoB,EACpB,gBAAgB,EAChB,eAAe,EACf,SAAS,EACT,uBAAuB,EAEvB,kBAAkB,EAClB,WAAW,EAEX,aAAa,EAEb,iBAAiB,GAClB,MAAM,eAAe,CAAC;AACvB,uBAAuB;AACvB,OAAO,EAEL,cAAc,EACd,iBAAiB,EACjB,oBAAoB,EAGpB,oBAAoB,EACpB,WAAW,EACX,SAAS,GACV,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agents/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,uFAAuF;AACvF,OAAO,EAGL,gBAAgB,EAChB,uBAAuB,EACvB,mBAAmB,EACnB,mBAAmB,EACnB,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,qBAAqB,CAAC;AAC7B,iBAAiB;AACjB,OAAO,EACL,uBAAuB,EACvB,WAAW,EAMX,aAAa,EACb,cAAc,GAGf,MAAM,mBAAmB,CAAC;AAC3B,oBAAoB;AACpB,OAAO,EAEL,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,YAAY,EACZ,cAAc,GACf,MAAM,eAAe,CAAC;AACvB,iEAAiE;AACjE,OAAO,EAIL,0BAA0B,EAC1B,yBAAyB,EAEzB,0BAA0B,EAC1B,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,yBAAyB,CAAC;AACjC,2BAA2B;AAC3B,OAAO,EAEL,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,EACf,kBAAkB,GACnB,MAAM,qBAAqB,CAAC;AAC7B,6CAA6C;AAC7C,uFAAuF;AACvF,uFAAuF;AACvF,OAAO,EAEL,gBAAgB,IAAI,kBAAkB,EACtC,aAAa,EACb,eAAe,EACf,eAAe,EACf,oBAAoB,EACpB,gBAAgB,EAChB,eAAe,EACf,SAAS,EACT,uBAAuB,EAEvB,kBAAkB,EAClB,WAAW,EAEX,aAAa,EAEb,iBAAiB,GAClB,MAAM,eAAe,CAAC;AACvB,uBAAuB;AACvB,OAAO,EAEL,cAAc,EACd,iBAAiB,EACjB,oBAAoB,EAGpB,oBAAoB,EACpB,WAAW,EACX,SAAS,GACV,MAAM,YAAY,CAAC"}

package/dist/agents/retry.d.ts

@@ -26,18 +26,54 @@ export interface RetryPolicy {
 export declare const DEFAULT_RETRY_POLICY: Readonly<RetryPolicy>;
 /**
  * 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 declare 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 declare 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 declare function shouldRetry(error: unknown, attempt: number, policy: RetryPolicy): boolean;
 /** Result of a retried operation. */
@@ -51,13 +87,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 declare function withRetry<T>(fn: () => Promise<T>, policy?: Partial<RetryPolicy>): Promise<RetryResult<T>>;
 /** Result of a recovery attempt for a single agent. */
@@ -75,9 +118,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 declare function recoverCrashedAgents(thresholdMs?: number, cwd?: string): Promise<AgentRecoveryResult[]>;
 //# sourceMappingURL=retry.d.ts.map

package/dist/agents/retry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/agents/retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAaH,wCAAwC;AACxC,MAAM,WAAW,WAAW;IAC1B,oDAAoD;IACpD,UAAU,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,WAAW,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,UAAU,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,6DAA6D;IAC7D,MAAM,EAAE,OAAO,CAAC;IAChB,yEAAyE;IACzE,cAAc,EAAE,OAAO,CAAC;CACzB;AAED,6DAA6D;AAC7D,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,WAAW,CAOrD,CAAC;AAEH;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,WAAW,CAE/E;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,MAAM,CAU3E;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAUzF;AAMD,qCAAqC;AACrC,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,CAAC,CAAC;IACV,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC5B,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAyCzB;AAMD,uDAAuD;AACvD,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,WAAW,GAAG,WAAW,GAAG,SAAS,CAAC;IAC9C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,oBAAoB,CACxC,WAAW,GAAE,MAAe,EAC5B,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAyDhC"}
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/agents/retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAaH,wCAAwC;AACxC,MAAM,WAAW,WAAW;IAC1B,oDAAoD;IACpD,UAAU,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,WAAW,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,UAAU,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,6DAA6D;IAC7D,MAAM,EAAE,OAAO,CAAC;IAChB,yEAAyE;IACzE,cAAc,EAAE,OAAO,CAAC;CACzB;AAED,6DAA6D;AAC7D,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,WAAW,CAOrD,CAAC;AAEH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,WAAW,CAE/E;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,MAAM,CAU3E;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAUzF;AAMD,qCAAqC;AACrC,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,CAAC,CAAC;IACV,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC5B,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAyCzB;AAMD,uDAAuD;AACvD,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,WAAW,GAAG,WAAW,GAAG,SAAS,CAAC;IAC9C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,oBAAoB,CACxC,WAAW,GAAE,MAAe,EAC5B,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAyDhC"}

package/dist/agents/retry.js

@@ -19,6 +19,17 @@ export const DEFAULT_RETRY_POLICY = 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) {
     return { ...DEFAULT_RETRY_POLICY, ...overrides };
@@ -26,8 +37,19 @@ export function createRetryPolicy(overrides) {
 /**
  * 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, policy) {
     const exponentialDelay = policy.baseDelayMs * policy.backoffMultiplier ** attempt;
@@ -42,6 +64,20 @@ export function calculateDelay(attempt, policy) {
 /**
  * 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, attempt, policy) {
     if (attempt >= policy.maxRetries)
@@ -57,13 +93,20 @@ export function shouldRetry(error, attempt, policy) {
 /**
  * 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(fn, policy) {
     const effectivePolicy = createRetryPolicy(policy);
@@ -112,9 +155,19 @@ export async function withRetry(fn, policy) {
  * 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 = 30_000, cwd) {
     const results = [];

package/dist/agents/retry.js.map

@@ -1 +1 @@
-{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/agents/retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,eAAe,CAAC;AAsBvB,6DAA6D;AAC7D,MAAM,CAAC,MAAM,oBAAoB,GAA0B,MAAM,CAAC,MAAM,CAAC;IACvE,UAAU,EAAE,CAAC;IACb,WAAW,EAAE,KAAK;IAClB,UAAU,EAAE,MAAM;IAClB,iBAAiB,EAAE,CAAC;IACpB,MAAM,EAAE,IAAI;IACZ,cAAc,EAAE,IAAI;CACrB,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,SAAgC;IAChE,OAAO,EAAE,GAAG,oBAAoB,EAAE,GAAG,SAAS,EAAE,CAAC;AACnD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe,EAAE,MAAmB;IACjE,MAAM,gBAAgB,GAAG,MAAM,CAAC,WAAW,GAAG,MAAM,CAAC,iBAAiB,IAAI,OAAO,CAAC;IAClF,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,gBAAgB,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;IAEnE,IAAI,CAAC,MAAM,CAAC,MAAM;QAAE,OAAO,YAAY,CAAC;IAExC,mBAAmB;IACnB,MAAM,WAAW,GAAG,YAAY,GAAG,IAAI,CAAC;IACxC,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,WAAW,CAAC;IAChD,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,GAAG,WAAW,CAAC,CAAC;AAChD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc,EAAE,OAAe,EAAE,MAAmB;IAC9E,IAAI,OAAO,IAAI,MAAM,CAAC,UAAU;QAAE,OAAO,KAAK,CAAC;IAE/C,MAAM,cAAc,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAE5C,IAAI,cAAc,KAAK,WAAW;QAAE,OAAO,KAAK,CAAC;IACjD,IAAI,cAAc,KAAK,WAAW;QAAE,OAAO,IAAI,CAAC;IAEhD,yDAAyD;IACzD,OAAO,MAAM,CAAC,cAAc,CAAC;AAC/B,CAAC;AAeD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,EAAoB,EACpB,MAA6B;IAE7B,MAAM,eAAe,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAClD,IAAI,SAA4B,CAAC;IACjC,IAAI,YAAY,GAAG,CAAC,CAAC;IAErB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,eAAe,CAAC,UAAU,EAAE,OAAO,EAAE,EAAE,CAAC;QACvE,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,EAAE,EAAE,CAAC;YACzB,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,KAAK;gBACL,QAAQ,EAAE,OAAO,GAAG,CAAC;gBACrB,YAAY;aACb,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,SAAS,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;YAEhE,IAAI,CAAC,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,eAAe,CAAC,EAAE,CAAC;gBAChD,OAAO;oBACL,OAAO,EAAE,KAAK;oBACd,KAAK,EAAE,SAAS;oBAChB,QAAQ,EAAE,OAAO,GAAG,CAAC;oBACrB,YAAY;iBACb,CAAC;YACJ,CAAC;YAED,gDAAgD;YAChD,IAAI,OAAO,GAAG,eAAe,CAAC,UAAU,EAAE,CAAC;gBACzC,MAAM,KAAK,GAAG,cAAc,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;gBACvD,YAAY,IAAI,KAAK,CAAC;gBACtB,MAAM,KAAK,CAAC,KAAK,CAAC,CAAC;YACrB,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO;QACL,OAAO,EAAE,KAAK;QACd,KAAK,EAAE,SAAS,IAAI,IAAI,KAAK,CAAC,+BAA+B,CAAC;QAC9D,QAAQ,EAAE,eAAe,CAAC,UAAU,GAAG,CAAC;QACxC,YAAY;KACb,CAAC;AACJ,CAAC;AAcD;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,cAAsB,MAAM,EAC5B,GAAY;IAEZ,MAAM,OAAO,GAA0B,EAAE,CAAC;IAE1C,oDAAoD;IACpD,MAAM,WAAW,GAAG,MAAM,gBAAgB,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;IAC7D,KAAK,MAAM,KAAK,IAAI,WAAW,EAAE,CAAC;QAChC,MAAM,iBAAiB,CACrB,KAAK,CAAC,EAAE,EACR,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,kDAAkD,EAAE,EAChF,GAAG,CACJ,CAAC;IACJ,CAAC;IAED,qCAAqC;IACrC,MAAM,aAAa,GAAG,MAAM,kBAAkB,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,GAAG,CAAC,CAAC;IAE3E,KAAK,MAAM,KAAK,IAAI,aAAa,EAAE,CAAC;QAClC,mDAAmD;QACnD,MAAM,EAAE,oBAAoB,EAAE,GAAG,MAAM,MAAM,CAAC,eAAe,CAAC,CAAC;QAC/D,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC,KAAK,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;QACzD,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAEvE,6BAA6B;QAC7B,IAAI,KAAK,CAAC,UAAU,IAAI,CAAC,EAAE,CAAC;YAC1B,MAAM,iBAAiB,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,GAAG,CAAC,CAAC;YAC9D,OAAO,CAAC,IAAI,CAAC;gBACX,OAAO,EAAE,KAAK,CAAC,EAAE;gBACjB,SAAS,EAAE,KAAK;gBAChB,MAAM,EAAE,WAAW;gBACnB,MAAM,EAAE,gBAAgB,KAAK,CAAC,UAAU,yBAAyB;aAClE,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,sCAAsC;QACtC,IAAI,SAAS,EAAE,SAAS,KAAK,WAAW,EAAE,CAAC;YACzC,MAAM,iBAAiB,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,GAAG,CAAC,CAAC;YAC9D,OAAO,CAAC,IAAI,CAAC;gBACX,OAAO,EAAE,KAAK,CAAC,EAAE;gBACjB,SAAS,EAAE,KAAK;gBAChB,MAAM,EAAE,WAAW;gBACnB,MAAM,EAAE,oBAAoB,SAAS,CAAC,OAAO,EAAE;aAChD,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,qEAAqE;QACrE,MAAM,iBAAiB,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,EAAE,GAAG,CAAC,CAAC;QAC/D,OAAO,CAAC,IAAI,CAAC;YACX,OAAO,EAAE,KAAK,CAAC,EAAE;YACjB,SAAS,EAAE,IAAI;YACf,MAAM,EAAE,WAAW;YACnB,MAAM,EAAE,2CAA2C;SACpD,CAAC,CAAC;IACL,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,+EAA+E;AAC/E,YAAY;AACZ,+EAA+E;AAE/E;;;GAGG;AACH,SAAS,KAAK,CAAC,EAAU;IACvB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC"}
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/agents/retry.ts"],"names":[],"mappings":"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"}

package/dist/backfill/index.d.ts

@@ -8,6 +8,7 @@
  *   backfillTasks(root, {})                  -- apply changes
  *   backfillTasks(root, { rollback: true })  -- revert backfill
  *
+ * @packageDocumentation
  * @epic T056
  * @task T066
  */
@@ -44,13 +45,39 @@ 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 declare function generateAcFromDescription(title: string, description: string): string[];
 /**
  * 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 declare function backfillTasks(projectRoot: string, options?: BackfillOptions): Promise<BackfillResult>;
 //# sourceMappingURL=index.d.ts.map

package/dist/backfill/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/backfill/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAUH,mCAAmC;AACnC,MAAM,WAAW,eAAe;IAC9B,yEAAyE;IACzE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,mEAAmE;AACnE,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,SAAS,EAAE,OAAO,CAAC;IACnB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,kDAAkD;AAClD,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,OAAO,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,OAAO,EAAE,kBAAkB,EAAE,CAAC;CAC/B;AAMD;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CA4DtF;AAoBD;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,cAAc,CAAC,CAiIzB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/backfill/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAUH,mCAAmC;AACnC,MAAM,WAAW,eAAe;IAC9B,yEAAyE;IACzE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,mEAAmE;AACnE,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,SAAS,EAAE,OAAO,CAAC;IACnB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,kDAAkD;AAClD,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,OAAO,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,OAAO,EAAE,kBAAkB,EAAE,CAAC;CAC/B;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CA4DtF;AAoBD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,aAAa,CACjC,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,cAAc,CAAC,CAiIzB"}