principles-disciple 1.7.5 → 1.7.8

package/dist/service/evolution-worker.js

@@ -11,7 +11,61 @@ import { initPersistence, flushAllSessions } from '../core/session-tracker.js';
 import { acquireLockAsync, releaseLock } from '../utils/file-lock.js';
 import { getEvolutionLogger } from '../core/evolution-logger.js';
 import { DIAGNOSTICIAN_PROTOCOL_SUMMARY } from '../constants/diagnostician.js';
+import { LockUnavailableError } from '../config/index.js';
+import { checkWorkspaceIdle, checkCooldown } from './nocturnal-runtime.js';
+import { executeNocturnalReflectionAsync } from './nocturnal-service.js';
+import { OpenClawTrinityRuntimeAdapter } from '../core/nocturnal-trinity.js';
 let intervalId = null;
+let timeoutId = null;
+/**
+ * Default values for new V2 fields when migrating legacy items.
+ */
+const DEFAULT_TASK_KIND = 'pain_diagnosis';
+const DEFAULT_PRIORITY = 'medium';
+const DEFAULT_MAX_RETRIES = 3;
+/**
+ * Migrate a legacy queue item to V2 schema.
+ * Old items without taskKind are assumed to be pain_diagnosis for backward compatibility.
+ */
+function migrateToV2(item) {
+    return {
+        id: item.id,
+        taskKind: item.taskKind || DEFAULT_TASK_KIND,
+        priority: item.priority || DEFAULT_PRIORITY,
+        source: item.source,
+        traceId: item.traceId,
+        task: item.task,
+        score: item.score,
+        reason: item.reason,
+        timestamp: item.timestamp,
+        enqueued_at: item.enqueued_at,
+        started_at: item.started_at,
+        completed_at: item.completed_at,
+        assigned_session_key: item.assigned_session_key,
+        trigger_text_preview: item.trigger_text_preview,
+        status: item.status || 'pending',
+        resolution: item.resolution,
+        session_id: item.session_id,
+        agent_id: item.agent_id,
+        retryCount: item.retryCount || 0,
+        maxRetries: item.maxRetries || DEFAULT_MAX_RETRIES,
+        lastError: item.lastError,
+        resultRef: item.resultRef,
+    };
+}
+/**
+ * Check if an item is a legacy (pre-V2) queue item.
+ */
+function isLegacyQueueItem(item) {
+    return item && typeof item === 'object' && !('taskKind' in item);
+}
+/**
+ * Migrate entire queue to V2 schema if needed.
+ * Returns a new array with all items migrated to V2 format.
+ */
+function migrateQueueToV2(queue) {
+    return queue.map(item => isLegacyQueueItem(item) ? migrateToV2(item) : item);
+}
 const PAIN_QUEUE_DEDUP_WINDOW_MS = 30 * 60 * 1000;
 // P0 fix: File lock constants and helper for queue operations (prevents TOCTOU race)
 export const EVOLUTION_QUEUE_LOCK_SUFFIX = '.lock';
@@ -84,8 +138,8 @@ async function requireQueueLock(resourcePath, logger, scope, lockSuffix = EVOLUT
     try {
         return await acquireQueueLock(resourcePath, logger, lockSuffix);
     }
-    catch {
-        throw new Error(`[PD:EvolutionWorker] ${scope}: queue lock unavailable for ${resourcePath}`);
+    catch (err) {
+        throw new LockUnavailableError(resourcePath, scope, { cause: err });
     }
 }
 export function extractEvolutionTaskId(task) {
@@ -128,6 +182,97 @@ export function hasEquivalentPromotedRule(dictionary, phrase) {
         return false;
     });
 }
+/**
+ * Read recent pain context from PAIN_FLAG file.
+ * Returns structured pain metadata for attaching to sleep_reflection tasks.
+ * Returns null if no pain flag exists.
+ */
+function readRecentPainContext(wctx) {
+    const painFlagPath = wctx.resolve('PAIN_FLAG');
+    if (!fs.existsSync(painFlagPath)) {
+        return { mostRecent: null, recentPainCount: 0, recentMaxPainScore: 0 };
+    }
+    try {
+        const rawPain = fs.readFileSync(painFlagPath, 'utf8');
+        const lines = rawPain.split('\n');
+        let score = 0;
+        let source = '';
+        let reason = '';
+        let timestamp = '';
+        for (const line of lines) {
+            if (line.startsWith('score:'))
+                score = parseInt(line.split(':', 2)[1].trim(), 10) || 0;
+            if (line.startsWith('source:'))
+                source = line.split(':', 2)[1].trim();
+            if (line.startsWith('reason:'))
+                reason = line.slice('reason:'.length).trim();
+            if (line.startsWith('timestamp:'))
+                timestamp = line.slice('timestamp:'.length).trim();
+        }
+        if (score > 0) {
+            return {
+                mostRecent: { score, source, reason, timestamp },
+                recentPainCount: 1,
+                recentMaxPainScore: score,
+            };
+        }
+    }
+    catch {
+        // Best effort — non-fatal
+    }
+    return { mostRecent: null, recentPainCount: 0, recentMaxPainScore: 0 };
+}
+/**
+ * Enqueue a sleep_reflection task if one is not already pending.
+ * Phase 2.4: Called when workspace is idle to trigger nocturnal reflection.
+ */
+async function enqueueSleepReflectionTask(wctx, logger) {
+    const queuePath = wctx.resolve('EVOLUTION_QUEUE');
+    const releaseLock = await requireQueueLock(queuePath, logger, 'enqueueSleepReflection', EVOLUTION_QUEUE_LOCK_SUFFIX);
+    try {
+        let rawQueue = [];
+        try {
+            rawQueue = JSON.parse(fs.readFileSync(queuePath, 'utf8'));
+        }
+        catch {
+            // Queue doesn't exist yet - create empty array
+            rawQueue = [];
+        }
+        const queue = migrateQueueToV2(rawQueue);
+        // Check if a sleep_reflection task is already pending
+        const hasPendingSleepReflection = queue.some(t => t.taskKind === 'sleep_reflection' && (t.status === 'pending' || t.status === 'in_progress'));
+        if (hasPendingSleepReflection) {
+            logger?.debug?.('[PD:EvolutionWorker] sleep_reflection task already pending/in-progress, skipping');
+            return;
+        }
+        const now = Date.now();
+        const taskId = createEvolutionTaskId('nocturnal', 50, 'idle workspace', 'Sleep-mode reflection', now);
+        const nowIso = new Date(now).toISOString();
+        // Attach recent pain context if available
+        const recentPainContext = readRecentPainContext(wctx);
+        queue.push({
+            id: taskId,
+            taskKind: 'sleep_reflection',
+            priority: 'medium',
+            score: 50,
+            source: 'nocturnal',
+            reason: 'Sleep-mode reflection triggered by idle workspace',
+            trigger_text_preview: 'Idle workspace detected',
+            timestamp: nowIso,
+            enqueued_at: nowIso,
+            status: 'pending',
+            traceId: taskId,
+            retryCount: 0,
+            maxRetries: 1, // sleep_reflection doesn't retry
+            recentPainContext,
+        });
+        fs.writeFileSync(queuePath, JSON.stringify(queue, null, 2), 'utf8');
+        logger?.info?.(`[PD:EvolutionWorker] Enqueued sleep_reflection task ${taskId}`);
+    }
+    finally {
+        releaseLock();
+    }
+}
 async function checkPainFlag(wctx, logger) {
     try {
         const painFlagPath = wctx.resolve('PAIN_FLAG');
@@ -188,8 +333,11 @@ async function checkPainFlag(wctx, logger) {
             const taskId = createEvolutionTaskId(source, score, preview, reason, now);
             const nowIso = new Date(now).toISOString();
             const effectiveTraceId = traceId || taskId;
+            // V2: New queue items include all V2 fields with pain_diagnosis defaults
             queue.push({
                 id: taskId,
+                taskKind: 'pain_diagnosis', // V2: All pain-flag triggered tasks are pain_diagnosis
+                priority: score >= 70 ? 'high' : score >= 40 ? 'medium' : 'low', // V2: Priority based on score
                 score,
                 source,
                 reason,
@@ -200,6 +348,8 @@ async function checkPainFlag(wctx, logger) {
                 session_id: sessionId || undefined,
                 agent_id: agentId || undefined,
                 traceId: effectiveTraceId,
+                retryCount: 0, // V2: No retries yet
+                maxRetries: 3, // V2: Default max retries
             });
             fs.writeFileSync(queuePath, JSON.stringify(queue, null, 2), 'utf8');
             fs.appendFileSync(painFlagPath, `\nstatus: queued\ntask_id: ${taskId}\n`, 'utf8');
@@ -232,16 +382,17 @@ async function checkPainFlag(wctx, logger) {
             logger.warn(`[PD:EvolutionWorker] Error processing pain flag: ${String(err)}`);
     }
 }
-async function processEvolutionQueue(wctx, logger, eventLog) {
+async function processEvolutionQueue(wctx, logger, eventLog, api) {
     const queuePath = wctx.resolve('EVOLUTION_QUEUE');
     if (!fs.existsSync(queuePath))
         return;
     const releaseLock = await requireQueueLock(queuePath, logger, 'processEvolutionQueue');
     const evoLogger = getEvolutionLogger(wctx.workspaceDir, wctx.trajectory);
+    let lockReleased = false;
     try {
-        let queue = [];
+        let rawQueue = [];
         try {
-            queue = JSON.parse(fs.readFileSync(queuePath, 'utf8'));
+            rawQueue = JSON.parse(fs.readFileSync(queuePath, 'utf8'));
         }
         catch (e) {
             // Backup corrupted file instead of silently discarding
@@ -260,11 +411,36 @@ async function processEvolutionQueue(wctx, logger, eventLog) {
             }
             return;
         }
-        let queueChanged = false;
+        // V2: Migrate queue to current schema if needed
+        const queue = migrateQueueToV2(rawQueue);
+        let queueChanged = rawQueue.some(isLegacyQueueItem);
         const config = wctx.config;
         const timeout = config.get('intervals.task_timeout_ms') || (60 * 60 * 1000); // Default 1 hour
-        // Check in_progress tasks for completion
-        for (const task of queue.filter(t => t.status === 'in_progress')) {
+        // V2: Recover stuck in_progress sleep_reflection tasks.
+        // If the worker crashes or the result write-back fails after Phase 1 claimed
+        // the task, it stays in_progress indefinitely. Detect via timeout and mark
+        // as failed so a fresh task can be enqueued on the next idle cycle.
+        for (const task of queue.filter(t => t.status === 'in_progress' && t.taskKind === 'sleep_reflection')) {
+            const startedAt = new Date(task.started_at || task.timestamp);
+            const age = Date.now() - startedAt.getTime();
+            if (age > timeout) {
+                task.status = 'failed';
+                task.completed_at = new Date().toISOString();
+                task.resolution = 'failed_max_retries';
+                task.lastError = `sleep_reflection timed out after ${Math.round(timeout / 60000)} minutes`;
+                task.retryCount = (task.retryCount ?? 0) + 1;
+                queueChanged = true;
+                logger?.warn?.(`[PD:EvolutionWorker] sleep_reflection task ${task.id} timed out after ${Math.round(age / 60000)} minutes, marking as failed`);
+                evoLogger.logCompleted({
+                    traceId: task.traceId || task.id,
+                    taskId: task.id,
+                    resolution: 'manual',
+                    durationMs: age,
+                });
+            }
+        }
+        // Check in_progress tasks for completion (only pain_diagnosis gets HEARTBEAT treatment)
+        for (const task of queue.filter(t => t.status === 'in_progress' && t.taskKind === 'pain_diagnosis')) {
             const startedAt = new Date(task.started_at || task.timestamp);
             // Condition 1: Check for marker file (created by diagnostician on completion)
             const completeMarker = path.join(wctx.stateDir, `.evolution_complete_${task.id}`);
@@ -336,9 +512,21 @@ async function processEvolutionQueue(wctx, logger, eventLog) {
                 queueChanged = true;
             }
         }
-        const pendingTasks = queue.filter(t => t.status === 'pending');
+        // V2: Process pain_diagnosis tasks FIRST (quick, inside lock),
+        // then sleep_reflection tasks (slow, lock released during execution).
+        // This order ensures pain tasks are never starved by long-running
+        // nocturnal reflection — sleep_reflection can safely return early
+        // because pain_diagnosis has already been handled.
+        const pendingTasks = queue.filter(t => t.status === 'pending' && t.taskKind === 'pain_diagnosis');
         if (pendingTasks.length > 0) {
-            const highestScoreTask = pendingTasks.sort((a, b) => b.score - a.score)[0];
+            // V2: Also sort by priority within same score
+            const priorityWeight = { high: 3, medium: 2, low: 1 };
+            const highestScoreTask = pendingTasks.sort((a, b) => {
+                const scoreDiff = b.score - a.score;
+                if (scoreDiff !== 0)
+                    return scoreDiff;
+                return (priorityWeight[b.priority] || 2) - (priorityWeight[a.priority] || 2);
+            })[0];
             const nowIso = new Date().toISOString();
             const taskDescription = `Diagnose systemic pain [ID: ${highestScoreTask.id}]. Source: ${highestScoreTask.source}. Reason: ${highestScoreTask.reason}. ` +
                 `Trigger text: "${highestScoreTask.trigger_text_preview || 'N/A'}"`;
@@ -408,6 +596,107 @@ async function processEvolutionQueue(wctx, logger, eventLog) {
                 SystemLogger.log(wctx.workspaceDir, 'HEARTBEAT_WRITE_FAILED', `Task ${highestScoreTask.id} HEARTBEAT write failed: ${String(heartbeatErr)}`);
             }
         }
+        // Phase 2.4: Process sleep_reflection tasks AFTER pain_diagnosis.
+        // Claim tasks inside the lock, execute reflection outside the lock,
+        // then re-acquire the lock to write results. This prevents the long-running
+        // nocturnal reflection from blocking all other queue consumers.
+        // Safe to return early here because pain_diagnosis was already handled above.
+        const sleepReflectionTasks = queue.filter(t => t.status === 'pending' && t.taskKind === 'sleep_reflection');
+        if (sleepReflectionTasks.length > 0) {
+            // --- Phase 1: Claim tasks (inside lock) ---
+            for (const sleepTask of sleepReflectionTasks) {
+                sleepTask.status = 'in_progress';
+                sleepTask.started_at = new Date().toISOString();
+            }
+            queueChanged = true;
+            // Write claimed state (includes any pain changes from above) and release lock
+            if (queueChanged) {
+                fs.writeFileSync(queuePath, JSON.stringify(queue, null, 2), 'utf8');
+            }
+            releaseLock();
+            for (const sleepTask of sleepReflectionTasks) {
+                try {
+                    logger?.info?.(`[PD:EvolutionWorker] Processing sleep_reflection task ${sleepTask.id}`);
+                    // Build runtime adapter for real Trinity execution if api is available
+                    const runtimeAdapter = api ? new OpenClawTrinityRuntimeAdapter(api) : undefined;
+                    // Call the nocturnal reflection service
+                    const result = await executeNocturnalReflectionAsync(wctx.workspaceDir, wctx.stateDir, {
+                        runtimeAdapter,
+                    });
+                    if (result.success && result.artifact) {
+                        sleepTask.status = 'completed';
+                        sleepTask.completed_at = new Date().toISOString();
+                        sleepTask.resolution = 'marker_detected';
+                        sleepTask.resultRef = result.diagnostics.persistedPath;
+                        logger?.info?.(`[PD:EvolutionWorker] sleep_reflection task ${sleepTask.id} completed successfully`);
+                    }
+                    else {
+                        // Record failure with skip reason
+                        const skipReason = result.skipReason || (result.noTargetSelected ? 'no_target' : 'validation_failed');
+                        sleepTask.status = 'failed';
+                        sleepTask.completed_at = new Date().toISOString();
+                        sleepTask.resolution = 'failed_max_retries';
+                        sleepTask.lastError = `Nocturnal reflection failed: ${result.validationFailures.join('; ') || skipReason}`;
+                        sleepTask.retryCount = (sleepTask.retryCount ?? 0) + 1;
+                        logger?.warn?.(`[PD:EvolutionWorker] sleep_reflection task ${sleepTask.id} failed: ${sleepTask.lastError}`);
+                    }
+                }
+                catch (taskErr) {
+                    sleepTask.status = 'failed';
+                    sleepTask.completed_at = new Date().toISOString();
+                    sleepTask.resolution = 'failed_max_retries';
+                    sleepTask.lastError = String(taskErr);
+                    sleepTask.retryCount = (sleepTask.retryCount ?? 0) + 1;
+                    logger?.error?.(`[PD:EvolutionWorker] sleep_reflection task ${sleepTask.id} threw: ${taskErr}`);
+                }
+            }
+            // --- Phase 3: Write results back (re-acquire lock) ---
+            try {
+                const resultLock = await requireQueueLock(queuePath, logger, 'sleepReflectionResult');
+                try {
+                    // Re-read queue to merge with any changes made while lock was released
+                    let freshQueue = [];
+                    try {
+                        freshQueue = JSON.parse(fs.readFileSync(queuePath, 'utf8'));
+                    }
+                    catch { /* empty queue if corrupted */ }
+                    // Merge: update tasks by ID
+                    for (const sleepTask of sleepReflectionTasks) {
+                        const idx = freshQueue.findIndex((t) => t.id === sleepTask.id);
+                        if (idx >= 0) {
+                            freshQueue[idx] = sleepTask;
+                        }
+                    }
+                    fs.writeFileSync(queuePath, JSON.stringify(freshQueue, null, 2), 'utf8');
+                    // Log completions to EvolutionLogger
+                    for (const sleepTask of sleepReflectionTasks) {
+                        if (sleepTask.status === 'completed' || sleepTask.status === 'failed') {
+                            evoLogger.logCompleted({
+                                traceId: sleepTask.traceId || sleepTask.id,
+                                taskId: sleepTask.id,
+                                resolution: sleepTask.status === 'completed'
+                                    ? (sleepTask.resolution === 'marker_detected' ? 'marker_detected' : 'manual')
+                                    : 'manual',
+                                durationMs: sleepTask.started_at
+                                    ? Date.now() - new Date(sleepTask.started_at).getTime()
+                                    : undefined,
+                            });
+                        }
+                    }
+                }
+                finally {
+                    resultLock();
+                }
+            }
+            catch (resultLockErr) {
+                // If we can't re-acquire lock, results are in memory but not persisted.
+                // Tasks will appear stuck as in_progress and will be retried on next cycle.
+                logger?.warn?.(`[PD:EvolutionWorker] Failed to write sleep_reflection results back: ${String(resultLockErr)}`);
+            }
+            // Safe to return — pain_diagnosis was already processed above.
+            lockReleased = true;
+            return;
+        }
         if (queueChanged) {
             fs.writeFileSync(queuePath, JSON.stringify(queue, null, 2), 'utf8');
         }
@@ -417,7 +706,9 @@ async function processEvolutionQueue(wctx, logger, eventLog) {
             logger.warn(`[PD:EvolutionWorker] Error processing evolution queue: ${String(err)}`);
     }
     finally {
-        releaseLock();
+        if (!lockReleased) {
+            releaseLock();
+        }
     }
 }
 async function processDetectionQueue(wctx, api, eventLog) {
@@ -577,14 +868,16 @@ export async function registerEvolutionTaskSession(workspaceResolve, taskId, ses
         return false;
     const releaseLock = await requireQueueLock(queuePath, logger, 'registerEvolutionTaskSession');
     try {
-        let queue;
+        let rawQueue;
         try {
-            queue = JSON.parse(fs.readFileSync(queuePath, 'utf8'));
+            rawQueue = JSON.parse(fs.readFileSync(queuePath, 'utf8'));
         }
         catch (parseErr) {
             logger?.warn?.(`[PD:EvolutionWorker] Failed to parse EVOLUTION_QUEUE for session registration: ${queuePath} - ${parseErr instanceof Error ? parseErr.message : String(parseErr)}`);
             return false;
         }
+        // V2: Migrate queue to current schema
+        const queue = migrateQueueToV2(rawQueue);
         const task = queue.find((item) => item.id === taskId && item.status === 'in_progress');
         if (!task) {
             logger?.warn?.(`[PD:EvolutionWorker] Could not find in-progress evolution task ${taskId} for session assignment`);
@@ -625,8 +918,25 @@ export const EvolutionWorkerService = {
         const interval = config.get('intervals.worker_poll_ms') || (15 * 60 * 1000);
         intervalId = setInterval(() => {
             void (async () => {
+                // V2: Nocturnal idle check — logs workspace idle state on each cycle.
+                // This makes nocturnal-runtime a visible part of the worker lifecycle.
+                // Phase 2.4: Enqueue sleep_reflection when workspace is idle and not in cooldown.
+                const idleResult = checkWorkspaceIdle(wctx.workspaceDir, {});
+                if (idleResult.isIdle) {
+                    logger?.debug?.(`[PD:EvolutionWorker] Workspace idle (${idleResult.idleForMs}ms since last activity)`);
+                    // Phase 2.4: Enqueue sleep_reflection task if not in global cooldown
+                    const cooldown = checkCooldown(wctx.stateDir);
+                    if (!cooldown.globalCooldownActive && !cooldown.quotaExhausted) {
+                        enqueueSleepReflectionTask(wctx, logger).catch((err) => {
+                            logger?.error?.(`[PD:EvolutionWorker] Failed to enqueue sleep_reflection task: ${String(err)}`);
+                        });
+                    }
+                }
+                else {
+                    logger?.debug?.(`[PD:EvolutionWorker] Workspace active (last activity ${idleResult.idleForMs}ms ago)`);
+                }
                 await checkPainFlag(wctx, logger);
-                await processEvolutionQueue(wctx, logger, eventLog);
+                await processEvolutionQueue(wctx, logger, eventLog, api ?? undefined);
                 if (api) {
                     await processDetectionQueue(wctx, api, eventLog);
                 }
@@ -638,10 +948,10 @@ export const EvolutionWorkerService = {
                     logger.error(`[PD:EvolutionWorker] Error in worker interval: ${String(err)}`);
             });
         }, interval);
-        setTimeout(() => {
+        timeoutId = setTimeout(() => {
             void (async () => {
                 await checkPainFlag(wctx, logger);
-                await processEvolutionQueue(wctx, logger, eventLog);
+                await processEvolutionQueue(wctx, logger, eventLog, api ?? undefined);
                 if (api) {
                     await processDetectionQueue(wctx, api, eventLog);
                 }
@@ -657,6 +967,8 @@ export const EvolutionWorkerService = {
             ctx.logger.info('[PD:EvolutionWorker] Stopping background service...');
         if (intervalId)
             clearInterval(intervalId);
+        if (timeoutId)
+            clearTimeout(timeoutId);
         flushAllSessions();
     }
 };

package/dist/service/nocturnal-runtime.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Nocturnal Runtime Service — Idle Detection Source of Truth
+ * ===========================================================
+ *
+ * This module is the authoritative source for workspace idle state used by the
+ * nocturnal reflection pipeline. It must NOT use `.last_active.json` as the primary
+ * source of truth.
+ *
+ * SOURCE OF TRUTH HIERARCHY (ordered by priority):
+ *  1. SessionState.lastActivityAt  — via listSessions(workspaceDir)
+ *  2. trajectory timestamps        — secondary guardrail only, NOT primary
+ *  3. nocturnal-runtime.json       — cooldown/quota bookkeeping (ephemeral state)
+ *
+ * DESIGN CONSTRAINTS:
+ * - No `.last_active.json` as primary idle source
+ * - trajectory timestamps are a guardrail, not the primary source
+ * - cooldown/quota state is persisted in nocturnal-runtime.json
+ * - abandoned sessions (>2h inactive) must not block nocturnal flow
+ */
+/** File name for nocturnal runtime bookkeeping */
+export declare const NOCTURNAL_RUNTIME_FILE = "nocturnal-runtime.json";
+/** Default idle threshold: workspace is considered idle if no activity for this duration (ms) */
+export declare const DEFAULT_IDLE_THRESHOLD_MS: number;
+/** Default cooldown between nocturnal runs (ms) */
+export declare const DEFAULT_GLOBAL_COOLDOWN_MS: number;
+/** Default per-principle cooldown (ms) */
+export declare const DEFAULT_PRINCIPLE_COOLDOWN_MS: number;
+/** Default maximum nocturnal runs per quota window */
+export declare const DEFAULT_MAX_RUNS_PER_WINDOW = 3;
+/** Default quota window size (ms) */
+export declare const DEFAULT_QUOTA_WINDOW_MS: number;
+/** Abandoned session threshold: sessions inactive for longer than this are ignored (ms) */
+export declare const DEFAULT_ABANDONED_THRESHOLD_MS: number;
+/**
+ * Persisted state for nocturnal runtime bookkeeping.
+ * Stored in {stateDir}/nocturnal-runtime.json
+ */
+export interface NocturnalRuntimeState {
+    /** Last time a nocturnal run was started (ISO string) */
+    lastRunAt?: string;
+    /** Last time a nocturnal run completed successfully */
+    lastSuccessfulRunAt?: string;
+    /** Cooldown end time for global cooldown (ISO string) */
+    globalCooldownUntil?: string;
+    /**
+     * Per-principle cooldown map.
+     * Key: principleId, Value: ISO string of cooldown end time
+     */
+    principleCooldowns: Record<string, string>;
+    /**
+     * Sliding window of recent run timestamps.
+     * Used for quota enforcement.
+     */
+    recentRunTimestamps: string[];
+    /** Metadata about last run (for debugging) */
+    lastRunMeta?: {
+        targetPrincipleId?: string;
+        sampleCount?: number;
+        status: 'success' | 'failed' | 'skipped';
+        reason?: string;
+    };
+}
+/** Result of an idle check */
+export interface IdleCheckResult {
+    /** Whether the workspace is currently idle */
+    isIdle: boolean;
+    /** Most recent activity timestamp across all sessions (epoch ms) */
+    mostRecentActivityAt: number;
+    /** How long since the last activity (ms) */
+    idleForMs: number;
+    /** Number of active (non-abandoned) sessions found */
+    activeSessionCount: number;
+    /** List of abandoned session IDs (inactive > abandoned threshold) */
+    abandonedSessionIds: string[];
+    /** Whether trajectory guardrail also confirms idle */
+    trajectoryGuardrailConfirmsIdle: boolean;
+    /** Reason for the idle determination */
+    reason: string;
+}
+/** Result of a cooldown check */
+export interface CooldownCheckResult {
+    /** Whether the global cooldown is currently active */
+    globalCooldownActive: boolean;
+    /** When the global cooldown ends (ISO string), null if not in cooldown */
+    globalCooldownUntil: string | null;
+    /** Remaining ms until global cooldown expires */
+    globalCooldownRemainingMs: number;
+    /** Whether the principle-specific cooldown is active */
+    principleCooldownActive: boolean;
+    /** When the principle cooldown ends (ISO string), null if not in cooldown */
+    principleCooldownUntil: string | null;
+    /** Remaining ms until principle cooldown expires */
+    principleCooldownRemainingMs: number;
+    /** Whether the quota has been exhausted */
+    quotaExhausted: boolean;
+    /** Number of runs remaining in current window */
+    runsRemaining: number;
+}
+/**
+ * Check if the workspace is currently idle based on session activity.
+ *
+ * IDLE DETERMINATION LOGIC:
+ * - Collect all sessions for the workspace via listSessions()
+ * - Filter out abandoned sessions (inactive > abandonedThresholdMs)
+ * - Workspace is idle if: no active sessions OR all active sessions have lastActivityAt older than idleThresholdMs
+ * - Abandoned sessions do NOT contribute to idle determination
+ *
+ * @param workspaceDir - Workspace directory to check
+ * @param options.idleThresholdMs - Consider idle if no activity for this duration (default: 30 min)
+ * @param options.abandonedThresholdMs - Consider session abandoned if inactive for this duration (default: 2 hr)
+ * @param trajectoryLastActivityAt - Optional trajectory timestamp as secondary guardrail
+ * @returns IdleCheckResult with full diagnostic information
+ */
+export declare function checkWorkspaceIdle(workspaceDir: string, options?: {
+    idleThresholdMs?: number;
+    abandonedThresholdMs?: number;
+}, trajectoryLastActivityAt?: number): IdleCheckResult;
+/**
+ * Check if the workspace is currently in a cooldown period.
+ *
+ * @param stateDir - State directory
+ * @param principleId - Optional principle ID to check per-principle cooldown
+ * @param options - Cooldown configuration options
+ * @returns CooldownCheckResult
+ */
+export declare function checkCooldown(stateDir: string, principleId?: string, options?: {
+    globalCooldownMs?: number;
+    principleCooldownMs?: number;
+    maxRunsPerWindow?: number;
+    quotaWindowMs?: number;
+}): CooldownCheckResult;
+/**
+ * Record that a nocturnal run has started.
+ * Updates global cooldown and quota tracking.
+ *
+ * @param stateDir - State directory
+ * @param principleId - Target principle ID for this run
+ */
+export declare function recordRunStart(stateDir: string, principleId: string): Promise<void>;
+/**
+ * Record the outcome of a nocturnal run.
+ *
+ * @param stateDir - State directory
+ * @param outcome - 'success', 'failed', or 'skipped'
+ * @param details - Optional details about the run
+ */
+export declare function recordRunEnd(stateDir: string, outcome: 'success' | 'failed' | 'skipped', details?: {
+    sampleCount?: number;
+    reason?: string;
+}): Promise<void>;
+/**
+ * Clear all cooldowns (for testing or admin reset).
+ *
+ * @param stateDir - State directory
+ */
+export declare function clearAllCooldowns(stateDir: string): Promise<void>;
+/**
+ * Get the current runtime state (for debugging/inspection).
+ *
+ * @param stateDir - State directory
+ * @returns The current NocturnalRuntimeState
+ */
+export declare function getRuntimeState(stateDir: string): Promise<NocturnalRuntimeState>;
+export interface PreflightCheckResult {
+    canRun: boolean;
+    idle: IdleCheckResult;
+    cooldown: CooldownCheckResult;
+    /**
+     * Human-readable reasons why run is blocked (if canRun is false)
+     */
+    blockers: string[];
+}
+/**
+ * Combined pre-flight check for whether a nocturnal run should proceed.
+ * Integrates idle + cooldown + quota checks.
+ *
+ * @param workspaceDir - Workspace directory
+ * @param stateDir - State directory
+ * @param principleId - Target principle ID
+ * @param trajectoryLastActivityAt - Optional trajectory timestamp as secondary guardrail
+ * @param idleCheckOverride - Optional override for idle check result (for testing)
+ */
+export declare function checkPreflight(workspaceDir: string, stateDir: string, principleId?: string, trajectoryLastActivityAt?: number, idleCheckOverride?: IdleCheckResult): PreflightCheckResult;