principles-disciple 1.16.0 → 1.17.0

package/src/service/subagent-workflow/workflow-store.ts

@@ -232,7 +232,7 @@ export class WorkflowStore {
         `).all() as WorkflowRow[];
     }
     
-    /* eslint-disable @typescript-eslint/max-params -- Reason: Store interface requires full event context (workflowId, fromState, toState, reason, payload) */
+     
     recordEvent(
         workflowId: string,
         eventType: string,
@@ -268,7 +268,7 @@ export class WorkflowStore {
      * idempotencyKey must be unique per (workflow_id, stage). If a row with the
      * same idempotency_key already exists, this is a no-op (idempotent).
      */
-    /* eslint-disable @typescript-eslint/max-params -- Reason: Store interface requires workflowId, stage, output, and idempotencyKey */
+     
     recordStageOutput(
         workflowId: string,
         stage: 'dreamer' | 'philosopher',

package/src/tools/critique-prompt.ts

@@ -28,11 +28,10 @@ export function buildCritiquePromptV2(
 ): string {
     const { context, depth = 2, workspaceDir, api } = params;
     
-    // 1. 确定工作区目录 (优先级：显式传入 > api.config > official API > api.resolvePath)
+    // 1. 确定工作区目录 (优先级：显式传入 > api.config > official API)
     const effectiveWorkspaceDir = workspaceDir
         || (api?.config?.workspaceDir as string)
-        || resolveWorkspaceDirFromApi(api)
-        || api?.resolvePath?.('.');
+        || resolveWorkspaceDirFromApi(api);
     
     if (!effectiveWorkspaceDir) {
         throw new Error('Workspace directory is required for deep reflection.');

package/src/tools/deep-reflect.ts

@@ -4,6 +4,7 @@ import * as fs from 'fs';
 import { EventLogService } from '../core/event-log.js';
 import { resolvePdPath } from '../core/paths.js';
 import { resolveWorkspaceDirFromApi } from '../core/path-resolver.js';
+import { WorkspaceNotFoundError } from '../config/index.js';
 import {
     DeepReflectWorkflowManager,
     deepReflectWorkflowSpec,
@@ -106,11 +107,8 @@ export function createDeepReflectTool(api: OpenClawPluginApi) {
                 return { content: [{ type: 'text', text: '❌ 错误: 必须提供反思上下文 (context)。' }] };
             }
 
-            // eslint-disable-next-line @typescript-eslint/no-use-before-define -- Reason: mutual recursion between helper functions - reordering would break logical grouping
+             
             const effectiveWorkspaceDir = resolveReflectionWorkspace(api);
-            if (!effectiveWorkspaceDir) {
-                return { content: [{ type: 'text', text: '❌ 反思执行失败: Workspace directory is required for deep reflection。请检查 API 配置或网络连接。' }] };
-            }
 
             const config = loadConfig(effectiveWorkspaceDir, api);
             if (config.mode === 'disabled' || !config.enabled) {
@@ -122,10 +120,10 @@ export function createDeepReflectTool(api: OpenClawPluginApi) {
             }
 
             try {
-                // eslint-disable-next-line @typescript-eslint/no-use-before-define -- Reason: mutual recursion between helper functions - reordering would break logical grouping
+                 
                 return await executeReflectionWorkflow(effectiveWorkspaceDir, config, context, depth, model_id, api);
             } catch (err) {
-                // eslint-disable-next-line @typescript-eslint/no-use-before-define -- Reason: mutual recursion between helper functions - reordering would break logical grouping
+                 
                 return handleReflectionError(err, context, depth, model_id, effectiveWorkspaceDir, api);
             }
         }
@@ -135,16 +133,19 @@ export function createDeepReflectTool(api: OpenClawPluginApi) {
 /**
  * Resolve workspace directory for deep reflection tool.
  */
-function resolveReflectionWorkspace(api: OpenClawPluginApi): string | undefined {
-    return (api.config?.workspaceDir as string)
-        || resolveWorkspaceDirFromApi(api)
-        || api.resolvePath?.('.');
+function resolveReflectionWorkspace(api: OpenClawPluginApi): string {
+    const dir = (api.config?.workspaceDir as string)
+        || resolveWorkspaceDirFromApi(api);
+    if (!dir) {
+        throw new WorkspaceNotFoundError('deep-reflect: workspace directory could not be resolved via API or config');
+    }
+    return dir;
 }
 
 /**
  * Execute the deep reflection workflow: start, poll, collect results.
  */
-/* eslint-disable @typescript-eslint/max-params -- Reason: Function signature requires all parameters for type-safe reflection workflow */
+ 
 async function executeReflectionWorkflow(
     effectiveWorkspaceDir: string,
     config: DeepReflectionConfig,
@@ -175,7 +176,7 @@ async function executeReflectionWorkflow(
 
         const startTime = Date.now();
         const timeoutMs = config.timeout_ms ?? 60000;
-        // eslint-disable-next-line @typescript-eslint/no-use-before-define -- Reason: mutual recursion between helper functions - reordering would break logical grouping
+         
         return await pollReflectionCompletion(manager, handle, timeoutMs, startTime, eventLog, effectiveWorkspaceDir, context, model_id, depth);
     } finally {
         manager.dispose();
@@ -185,7 +186,7 @@ async function executeReflectionWorkflow(
 /**
  * Poll the reflection workflow until completion, timeout, or error.
  */
-/* eslint-disable @typescript-eslint/max-params -- Reason: Function signature requires all parameters for type-safe polling */
+ 
 async function pollReflectionCompletion(
     manager: DeepReflectWorkflowManager,
     handle: { workflowId: string; childSessionKey: string },
@@ -205,7 +206,7 @@ async function pollReflectionCompletion(
         if (!workflowState) break;
 
         if (workflowState === 'completed') {
-            // eslint-disable-next-line @typescript-eslint/no-use-before-define -- Reason: mutual recursion between helper functions - reordering would break logical grouping
+             
             return formatReflectionSuccess(handle, context, depth, model_id, startTime, eventLog, workspaceDir);
         }
 
@@ -220,7 +221,7 @@ async function pollReflectionCompletion(
 /**
  * Format the success response from a completed reflection.
  */
-/* eslint-disable @typescript-eslint/max-params -- Reason: Function signature requires all parameters for type-safe formatting */
+ 
 function formatReflectionSuccess(
     handle: { childSessionKey: string },
     context: string,
@@ -273,7 +274,7 @@ ${insights || '反思完成，详见 REFLECTION_LOG。'}
 /**
  * Handle reflection errors and format error response.
  */
-/* eslint-disable @typescript-eslint/max-params -- Reason: Function signature requires all parameters for type-safe error handling */
+ 
 function handleReflectionError(
     err: unknown,
     context: string,

package/src/tools/model-index.ts

@@ -61,7 +61,7 @@ export function loadModelIndex(
         const wctx = WorkspaceContext.fromHookContext({ workspaceDir });
         const customConfig = loadCustomConfig(wctx);
         
-        // eslint-disable-next-line @typescript-eslint/init-declarations -- assigned in both if/else branches
+         
         let modelsDir: string;
         if (customConfig?.modelsDir) {
             modelsDir = path.isAbsolute(customConfig.modelsDir) 

package/src/utils/file-lock.ts

@@ -334,7 +334,7 @@ export async function withAsyncLock<T>(
   let queue = asyncLockQueues.get(lockPath);
   
   // 创建新的 Promise 链
-  // eslint-disable-next-line @typescript-eslint/init-declarations -- assigned in Promise executor before use
+   
   let resolveRelease: () => void;
   const releasePromise = new Promise<void>(resolve => {
     resolveRelease = resolve;

package/src/utils/io.ts

@@ -16,7 +16,7 @@ export function normalizePath(filePath: string, projectDir: string): string {
     }
   }
 
-  // eslint-disable-next-line @typescript-eslint/init-declarations -- assigned in both if/else branches
+   
   let rel: string;
   if (projectIsWin) {
     const projectAbs = path.resolve(projectDir);
@@ -80,6 +80,11 @@ export function serializeKvLines(data: Record<string, any>): string {
   const keys = Object.keys(data).sort();
   for (const k of keys) {
     const v = data[k];
+    // Skip empty/undefined values — prevents writing blank lines that cause
+    // agent confusion (SKILL.md lists fields that aren't actually present on disk)
+    if (v === '' || v === undefined || v === null) {
+      continue;
+    }
     if (Array.isArray(v)) {
       lines.push(`${k}: ${v.join(',')}`);
     } else if (typeof v === 'object' && v !== null) {
@@ -105,7 +110,7 @@ export function planStatus(projectDir: string): string {
         }
       }
     }
-  /* eslint-disable @typescript-eslint/no-unused-vars, no-unused-vars -- Reason: Error is intentionally ignored for graceful degradation */
+  /* eslint-disable @typescript-eslint/no-unused-vars -- Reason: Error is intentionally ignored for graceful degradation */
   } catch (_e) {
     // Ignore read errors
   }

package/src/utils/nlp.ts

@@ -19,7 +19,7 @@ export function extractCommonPhrases(samples: string[], minOccurrence = 3): stri
 
     // Filter phrases that meet the threshold
     return Array.from(phrases.entries())
-        /* eslint-disable @typescript-eslint/no-unused-vars, no-unused-vars -- Reason: Destructuring with _placeholder for unused array element */
+         
         .filter(([_elem, count]) => count >= minOccurrence)
         .map(([phrase, _count]) => phrase);
 }

package/src/utils/plugin-logger.ts

@@ -2,12 +2,12 @@ import * as fs from 'fs';
 import * as path from 'path';
 
 export interface PluginLogger {
-    /* eslint-disable no-unused-vars -- Reason: interface method params are type signatures, implementations use actual values */
+     
     info(message: string, meta?: Record<string, unknown>): void;
     warn(message: string, meta?: Record<string, unknown>): void;
     error(message: string, meta?: Record<string, unknown>): void;
     debug(message: string, meta?: Record<string, unknown>): void;
-    /* eslint-enable no-unused-vars */
+     
 }
 
 export interface PluginLoggerConfig {

package/src/utils/retry.ts

@@ -34,7 +34,7 @@ export interface RetryOptions {
   operation?: string;
   /** Logger instance (optional, defaults to console) */
   logger?: RetryLogger;
-  /* eslint-disable no-unused-vars -- Reason: callback param names are part of type signature, unused implementations are valid */
+   
   isRetryable?: (_error: unknown) => boolean;
 }
 
@@ -424,7 +424,7 @@ export function computeDynamicTimeout(
   if (history.length < MIN_SAMPLES) {
     // Not enough data — use the spec's static timeout
     const fallback = clampTimeout(defaultTimeout);
-    // Use console.info since we don't have logger access here; this appears in journalctl
+    // eslint-disable-next-line no-console -- Monitoring output for fallback diagnostics
     console.info(`[PD:DynamicTimeout] Insufficient samples (${history.length} < ${MIN_SAMPLES}) for '${workflowType}', falling back to static timeout: ${fallback}ms`);
     return fallback;
   }
@@ -432,6 +432,7 @@ export function computeDynamicTimeout(
   const p95 = percentile(history, 95);
   const adaptive = p95 * SAFETY_MULTIPLIER;
   const result = clampTimeout(adaptive);
+  // eslint-disable-next-line no-console -- Monitoring output for adaptive timeout diagnostics
   console.info(`[PD:DynamicTimeout] Computed adaptive timeout for '${workflowType}': P95=${p95}ms (from ${history.length} samples) × ${SAFETY_MULTIPLIER} = ${result}ms`);
   return result;
 }

package/src/utils/subagent-probe.ts

@@ -1,11 +1,9 @@
 /**
  * Subagent Runtime Availability Probe
  *
- * OpenClaw has two runtime modes:
- * - Gateway mode: api.runtime.subagent methods are real async functions
- * - Embedded mode: api.runtime.subagent is a Proxy that throws synchronously
- *
- * This utility provides a reliable way to detect which mode we're in.
+ * This utility intentionally avoids inferring runtime availability from
+ * JavaScript implementation details like constructor names. The only contract
+ * we trust here is whether a callable `run` entrypoint exists.
  */
 
 import type { OpenClawPluginApi } from '../openclaw-sdk.js';
@@ -29,46 +27,35 @@ function getGlobalGatewaySubagent(): SubagentRuntime | null {
 }
 
 /**
- * Check if the subagent runtime is actually functional.
- *
- * In gateway mode, subagent.run is an AsyncFunction (constructor.name === 'AsyncFunction').
- * In embedded mode, subagent.run is a regular Function that throws synchronously.
- *
- * We use constructor check first because it's fast and has no side effects.
+ * Return a small, explicit availability assessment for the subagent runtime.
+ * This is a shape check only. Actual invocation failures are classified by the
+ * caller as runtime-unavailable vs downstream task failures.
  *
  * @param subagent - The subagent runtime object from api.runtime.subagent
- * @returns true if the runtime is functional (gateway mode), false otherwise
+ * @returns availability status and reason
  */
-export function isSubagentRuntimeAvailable(
+export function getSubagentRuntimeAvailability(
   subagent: { run?: unknown } | undefined
-): boolean {
-  if (!subagent) return false;
+): { available: boolean; reason: 'missing_runtime' | 'missing_run' | 'callable' } {
+  if (!subagent) return { available: false, reason: 'missing_runtime' };
 
   try {
     const runFn = subagent.run;
-    if (typeof runFn !== 'function') return false;
-
-    // In gateway mode, methods are AsyncFunction instances
-    // In embedded mode, methods are regular Function instances that throw
-    const isAsync = runFn.constructor?.name === 'AsyncFunction';
-    
-    if (isAsync) return true;
-
-    // Fallback: Check if it's a Proxy that might late-bind to the gateway subagent
-    // This handles the case where the plugin was loaded with allowGatewaySubagentBinding
-    // but the proxy hasn't resolved yet
-    const globalGateway = getGlobalGatewaySubagent();
-    if (globalGateway && typeof globalGateway.run === 'function') {
-      return globalGateway.run.constructor?.name === 'AsyncFunction';
+    if (typeof runFn !== 'function') {
+      return { available: false, reason: 'missing_run' };
     }
-
-    return false;
+    return { available: true, reason: 'callable' };
   } catch {
-    // Any error means unavailable
-    return false;
+    return { available: false, reason: 'missing_run' };
   }
 }
 
+export function isSubagentRuntimeAvailable(
+  subagent: { run?: unknown } | undefined
+): boolean {
+  return getSubagentRuntimeAvailability(subagent).available;
+}
+
 /**
  * Get the actual subagent runtime, preferring the global gateway subagent
  * if the passed one is not available.

package/templates/langs/en/skills/pd-pain-signal/SKILL.md

@@ -12,7 +12,7 @@ You are now the "Manual Intervention Pain" component.
 1. Write the user's feedback `$ARGUMENTS` as a **high-priority** pain signal to `.state/.pain_flag`.
 2. Inform the user that the signal has been injected, and suggest waiting for the next Hook trigger (e.g., Stop or PreCompact) or manually running `/reflection-log`.
 
-**Write Format** (must use this KV format, consistent with auto-detection channels):
+**Write Format** (must use this KV format, fields sorted alphabetically):
 
 ```
 agent_id: <current agent ID, e.g., main/builder/diagnostician>
@@ -22,16 +22,17 @@ score: 80
 session_id: <current session ID>
 source: human_intervention
 time: <ISO 8601 timestamp>
-trace_id:
-trigger_text_preview:
 ```
 
-**Field Notes**:
+**Required fields** (4):
 - `source`: Fixed as `human_intervention`
 - `score`: Default `80` for manual intervention (high priority)
+- `time`: ISO 8601 timestamp
+- `reason`: User's feedback verbatim
+
+**Optional fields** (auto-filled by system, but must be provided for manual injection):
+- `agent_id`: Current agent ID (e.g., main/builder/diagnostician)
 - `session_id`: Current session ID (from context)
-- `agent_id`: Current agent ID (from context)
 - `is_risky`: Fixed as `false`
-- `trace_id` / `trigger_text_preview`: Leave empty
 
-**⚠️ Important**: Do NOT use other formats (like writing only Source/Reason/Time lines). Downstream diagnostic systems depend on the complete KV field set.
+**Note**: `trace_id` and `trigger_text_preview` are auto-generated by the system — do NOT include them when manually injecting pain signals.

package/templates/langs/zh/skills/pd-pain-signal/SKILL.md

@@ -12,7 +12,7 @@ disable-model-invocation: true
 1. 将用户的反馈 `$ARGUMENTS` 作为一条**高优先级**的痛苦信号，写入 `.state/.pain_flag`。
 2. 告知用户信号已注入，并建议其等待下一个 Hook 触发（如 Stop 或 PreCompact）或手动运行 `/reflection-log`。
 
-**写入格式**（必须使用以下 KV 格式，与自动检测渠道保持一致）:
+**写入格式**（必须使用以下 KV 格式，字段按字母排序）:
 
 ```
 agent_id: <当前 agent ID，如 main/builder/diagnostician>
@@ -22,16 +22,17 @@ score: 80
 session_id: <当前 session ID>
 source: human_intervention
 time: <ISO 8601 时间>
-trace_id:
-trigger_text_preview:
 ```
 
-**字段说明**:
+**必填字段**（4 个）:
 - `source`: 固定为 `human_intervention`
 - `score`: 人工干预信号默认设为 `80`（高优先级）
+- `time`: ISO 8601 时间戳
+- `reason`: 用户反馈的原文
+
+**可选字段**（自动写入时由系统填充，人工注入时必须填写）:
+- `agent_id`: 当前智能体 ID（如 main/builder/diagnostician）
 - `session_id`: 当前会话 ID（从上下文中获取）
-- `agent_id`: 当前智能体 ID（从上下文中获取）
 - `is_risky`: 固定为 `false`
-- `trace_id` / `trigger_text_preview`: 留空即可
 
-**⚠️ 注意**: 不要使用其他格式（如只写 Source/Reason/Time 三行），下游诊断系统依赖完整的 KV 字段。
+**注意**: `trace_id` 和 `trigger_text_preview` 由系统自动生成，人工注入时**不需要**写这两个字段。

package/templates/pain_settings.json

@@ -27,7 +27,7 @@
   "intervals": {
     "worker_poll_ms": 900000,
     "initial_delay_ms": 5000,
-    "task_timeout_ms": 1800000
+    "task_timeout_ms": 3600000
   },
   "trust": {
     "stages": {

package/tests/build-artifacts.test.ts

@@ -8,7 +8,7 @@
  */
 
 import { describe, it, expect } from 'vitest';
-import { existsSync, readdirSync, statSync } from 'fs';
+import { existsSync, readdirSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 
@@ -35,45 +35,9 @@ describe('Build Artifacts', () => {
     }
   });
 
-  describe('Agent definitions', () => {
-    const expectedAgents = [
-      'diagnostician',
-      'explorer',
-      'auditor',
-      'planner',
-      'implementer',
-      'reviewer',
-      'reporter',
-    ];
-
-    it('should have agents directory with correct files', () => {
-      const agentsDir = join(packageRoot, 'dist/agents');
-      
-      if (!existsSync(agentsDir)) {
-        // Skip test if dist/agents doesn't exist (not a production build)
-        return;
-      }
-
-      const files = readdirSync(agentsDir)
-        .filter(f => f.endsWith('.md'))
-        .map(f => f.replace('.md', ''));
-
-      // At least 5 agents should be present
-      expect(files.length, 'Should have at least 5 agent definitions').toBeGreaterThanOrEqual(5);
-    });
-
-    for (const agent of expectedAgents) {
-      it(`should include ${agent}.md`, () => {
-        const agentPath = join(packageRoot, `dist/agents/${agent}.md`);
-        
-        if (!existsSync(join(packageRoot, 'dist/agents'))) {
-          return; // Skip if directory doesn't exist
-        }
-
-        expect(existsSync(agentPath), `${agent}.md should exist in dist/agents`).toBe(true);
-      });
-    }
-  });
+  // NOTE: agents/ directory was removed in favor of embedded prompts.
+  // All role prompts are now inlined in nocturnal-trinity.ts at build time.
+  // See: nocturnal-trinity.ts NOCTURNAL_DREAMER_PROMPT, etc.
 
   describe('Templates', () => {
     it('should have templates directory with subdirectories', () => {
@@ -91,21 +55,3 @@ describe('Build Artifacts', () => {
   });
 });
 
-describe('Agent Loader Integration', () => {
-  it('should be able to import agent-loader from dist', async () => {
-    const distPath = join(packageRoot, 'dist/core/agent-loader.js');
-    
-    if (!existsSync(distPath)) {
-      return; // Skip if dist not built
-    }
-
-    // Dynamic import from dist
-    const { listAvailableAgents } = await import(join(packageRoot, 'dist/core/agent-loader.js'));
-    
-    const agents = listAvailableAgents();
-    
-    expect(agents.length, 'listAvailableAgents should return at least 5 agents').toBeGreaterThanOrEqual(5);
-    expect(agents, 'Should include diagnostician').toContain('diagnostician');
-    expect(agents, 'Should include explorer').toContain('explorer');
-  });
-});

package/tests/commands/pd-reflect.test.ts

@@ -0,0 +1,49 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { handlePdReflect } from '../../src/commands/pd-reflect.js';
+
+describe('pd-reflect command', () => {
+  let tempDir: string;
+  let workspaceDir: string;
+  let queuePath: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-reflect-'));
+    workspaceDir = path.join(tempDir, 'workspace-a');
+    fs.mkdirSync(path.join(workspaceDir, '.state'), { recursive: true });
+    queuePath = path.join(workspaceDir, '.state', 'evolution_queue.json');
+    fs.writeFileSync(queuePath, '[]', 'utf8');
+  });
+
+  it('requires an explicit resolved workspace directory', async () => {
+    const result = await handlePdReflect.handler({} as any);
+    expect(result.isError).toBe(true);
+    expect(result.text).toContain('Cannot determine workspace directory');
+  });
+
+  it('enqueues into the provided active workspace', async () => {
+    const result = await handlePdReflect.handler({ workspaceDir } as any);
+    expect(result.isError).toBeUndefined();
+
+    const queue = JSON.parse(fs.readFileSync(queuePath, 'utf8')) as Array<Record<string, unknown>>;
+    expect(queue).toHaveLength(1);
+    expect(queue[0].taskKind).toBe('sleep_reflection');
+    expect(result.text).toContain('Nocturnal reflection task enqueued');
+  });
+
+  it('does not hardcode another workspace when context already provides one', async () => {
+    const otherWorkspace = path.join(tempDir, 'workspace-b');
+    fs.mkdirSync(path.join(otherWorkspace, '.state'), { recursive: true });
+    const otherQueuePath = path.join(otherWorkspace, '.state', 'evolution_queue.json');
+    fs.writeFileSync(otherQueuePath, '[]', 'utf8');
+
+    await handlePdReflect.handler({ workspaceDir } as any);
+
+    const activeQueue = JSON.parse(fs.readFileSync(queuePath, 'utf8')) as Array<Record<string, unknown>>;
+    const otherQueue = JSON.parse(fs.readFileSync(otherQueuePath, 'utf8')) as Array<Record<string, unknown>>;
+    expect(activeQueue).toHaveLength(1);
+    expect(otherQueue).toHaveLength(0);
+  });
+});

package/tests/core/nocturnal-snapshot-contract.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from 'vitest';
+import { validateNocturnalSnapshotIngress } from '../../src/core/nocturnal-snapshot-contract.js';
+
+describe('validateNocturnalSnapshotIngress', () => {
+  it('accepts a fully shaped runtime snapshot', () => {
+    const result = validateNocturnalSnapshotIngress({
+      sessionId: 'session-1',
+      startedAt: '2026-04-10T00:00:00.000Z',
+      updatedAt: '2026-04-10T00:01:00.000Z',
+      assistantTurns: [],
+      userTurns: [],
+      toolCalls: [],
+      painEvents: [],
+      gateBlocks: [],
+      stats: {
+        totalAssistantTurns: 1,
+        totalToolCalls: 2,
+        totalPainEvents: 0,
+        totalGateBlocks: 0,
+        failureCount: 0,
+      },
+    });
+
+    expect(result.status).toBe('valid');
+    expect(result.snapshot?.sessionId).toBe('session-1');
+  });
+
+  it('rejects reduced pseudo-snapshots that omit canonical fields', () => {
+    const result = validateNocturnalSnapshotIngress({
+      sessionId: 'session-1',
+      sessionStart: '2026-04-10T00:00:00.000Z',
+      stats: {
+        totalAssistantTurns: 1,
+        totalToolCalls: 2,
+        totalPainEvents: 0,
+        totalGateBlocks: 0,
+        failureCount: 0,
+      },
+      recentPain: [],
+    });
+
+    expect(result.status).toBe('invalid');
+    expect(result.reasons).toContain('snapshot.startedAt must be a non-empty string');
+    expect(result.reasons).toContain('snapshot.assistantTurns must be an array');
+  });
+
+  it('rejects fallback snapshots with no pain signal', () => {
+    const result = validateNocturnalSnapshotIngress({
+      sessionId: 'session-1',
+      startedAt: '2026-04-10T00:00:00.000Z',
+      updatedAt: '2026-04-10T00:00:00.000Z',
+      assistantTurns: [],
+      userTurns: [],
+      toolCalls: [],
+      painEvents: [],
+      gateBlocks: [],
+      stats: {
+        totalAssistantTurns: null,
+        totalToolCalls: null,
+        totalPainEvents: 0,
+        totalGateBlocks: null,
+        failureCount: null,
+      },
+      _dataSource: 'pain_context_fallback',
+    });
+
+    expect(result.status).toBe('invalid');
+    expect(result.reasons).toContain('fallback snapshot must contain at least one pain signal');
+  });
+});