principles-disciple 1.40.0 → 1.42.0

package/src/service/workflow-watchdog.ts

@@ -0,0 +1,168 @@
+/**
+ * Workflow Watchdog - Extracted from evolution-worker.ts (lines 79-223)
+ *
+ * Detects stale/orphaned workflows, invalid results, and cleanup failures.
+ * Runs every heartbeat cycle, catching bugs like:
+ *   #185 — orphaned active workflows
+ *   #181 — structurally invalid results (all zeros)
+ *   #180/#183 — expired workflows not swept
+ *   #182 — unhandled rejections leaving workflows in limbo
+ *
+ * BUG-01: isExpectedSubagentError guard prevents marking daemon-mode stale
+ *         workflows as terminal_error (line 122)
+ * BUG-02: Gateway fallback cleans up child sessions via agentSession when
+ *         subagentRuntime unavailable (lines 148-156)
+ * BUG-03: Nocturnal workflow snapshot validation detects pain_context_fallback
+ *         with zero stats (lines 184-198)
+ */
+
+import type { WorkspaceContext } from '../core/workspace-context.js';
+import type { OpenClawPluginApi, PluginLogger } from '../openclaw-sdk.js';
+import type { WorkflowRow } from './subagent-workflow/types.js';
+import { WorkflowStore } from './subagent-workflow/workflow-store.js';
+import { isExpectedSubagentError } from './subagent-workflow/subagent-error-utils.js';
+import { WORKFLOW_TTL_MS } from '../config/defaults/runtime.js';
+
+export interface WatchdogResult {
+  anomalies: number;
+  details: string[];
+  /** Set when the watchdog scan itself failed (e.g., store errors). Undefined means scan succeeded. */
+  scanError?: string;
+}
+
+/* eslint-disable complexity */
+export async function runWorkflowWatchdog(
+  wctx: WorkspaceContext,
+  api: OpenClawPluginApi | null,
+  logger?: PluginLogger,
+): Promise<WatchdogResult> {
+  const details: string[] = [];
+  const now = Date.now();
+  const subagentRuntime = api?.runtime?.subagent;
+  const agentSession = api?.runtime?.agent?.session;
+
+  try {
+    const store = new WorkflowStore({ workspaceDir: wctx.workspaceDir });
+    try {
+      const allWorkflows: WorkflowRow[] = store.listWorkflows();
+
+      // Check 1: Stale active workflows (active > 2x TTL)
+      const staleThreshold = WORKFLOW_TTL_MS * 2;
+      const staleActive = allWorkflows.filter(
+        (wf: WorkflowRow) => wf.state === 'active' && (now - wf.created_at) > staleThreshold,
+      );
+      if (staleActive.length > 0) {
+        for (const wf of staleActive) {
+          const ageMin = Math.round((now - wf.created_at) / 60000);
+          details.push(`stale_active: ${wf.workflow_id} (${wf.workflow_type}, ${ageMin}min old)`);
+
+          // #257: Check if the last recorded event reason indicates expected subagent unavailability.
+          // If so, skip marking as terminal_error — the workflow is stale because the subagent
+          // was expectedly unavailable (daemon mode, process isolation), not due to a hard failure.
+          const events = store.getEvents(wf.workflow_id);
+          const lastEventReason = events.length > 0 ? events[events.length - 1].reason : 'unknown';
+          if (isExpectedSubagentError(lastEventReason)) {
+            logger?.debug?.(`[PD:Watchdog] Skipping stale active workflow ${wf.workflow_id}: expected subagent error (${lastEventReason})`);
+            continue;
+          }
+
+          store.updateWorkflowState(wf.workflow_id, 'terminal_error');
+          store.recordEvent(wf.workflow_id, 'watchdog_timeout', 'active', 'terminal_error', `Stale active > ${staleThreshold / 60000}s`, { ageMs: now - wf.created_at });
+
+          // Cleanup session if possible (#188: gateway-safe fallback)
+          if (wf.child_session_key) {
+            try {
+              if (subagentRuntime) {
+                await subagentRuntime.deleteSession({ sessionKey: wf.child_session_key, deleteTranscript: true });
+                logger?.info?.(`[PD:Watchdog] Cleaned up stale session: ${wf.child_session_key}`);
+              } else if (agentSession) {
+                const storePath = agentSession.resolveStorePath();
+                const sessionStore = agentSession.loadSessionStore(storePath, { skipCache: true });
+                const normalizedKey = wf.child_session_key.toLowerCase();
+                if (sessionStore[normalizedKey]) {
+                  delete sessionStore[normalizedKey];
+                  await agentSession.saveSessionStore(storePath, sessionStore);
+                  logger?.info?.(`[PD:Watchdog] Cleaned up stale session via agentSession fallback: ${wf.child_session_key}`);
+                }
+              }
+            } catch (cleanupErr) {
+              const errMsg = String(cleanupErr);
+              if (errMsg.includes('gateway request') && agentSession) {
+                const storePath = agentSession.resolveStorePath();
+                const sessionStore = agentSession.loadSessionStore(storePath, { skipCache: true });
+                const normalizedKey = wf.child_session_key.toLowerCase();
+                if (sessionStore[normalizedKey]) {
+                  delete sessionStore[normalizedKey];
+                  await agentSession.saveSessionStore(storePath, sessionStore);
+                  logger?.info?.(`[PD:Watchdog] Cleaned up stale session via agentSession fallback after gateway error: ${wf.child_session_key}`);
+                }
+              } else {
+                logger?.warn?.(`[PD:Watchdog] Failed to cleanup session ${wf.child_session_key}: ${errMsg}`);
+              }
+            }
+          }
+        }
+      }
+
+      // Check 2: Workflows in terminal_error/expired without cleanup
+      const unclearedTerminal = allWorkflows.filter(
+        (wf: WorkflowRow) => (wf.state === 'terminal_error' || wf.state === 'expired') && wf.cleanup_state === 'pending',
+      );
+      if (unclearedTerminal.length > 0) {
+        details.push(`uncleared_terminal: ${unclearedTerminal.length} workflows (will be swept next cycle)`);
+      }
+
+      // Check 3: Nocturnal workflow result validation (#181 pattern)
+      const nocturnalCompleted = allWorkflows.filter(
+        (wf: WorkflowRow) => wf.workflow_type === 'nocturnal' && wf.state === 'completed',
+      );
+      for (const wf of nocturnalCompleted) {
+        // Check if the metadata snapshot has all zeros (invalid data)
+        try {
+          const meta = JSON.parse(wf.metadata_json) as Record<string, unknown>;
+          const snapshot = meta.snapshot as Record<string, unknown> | undefined;
+          if (snapshot) {
+            // #219: Check for fallback data source (partial stats from pain context)
+            const dataSource = snapshot._dataSource as string | undefined;
+            if (dataSource === 'pain_context_fallback') {
+              details.push(`fallback_snapshot: nocturnal workflow ${wf.workflow_id} uses pain-context fallback (stats may be incomplete)`);
+            }
+            const stats = snapshot.stats as Record<string, number> | undefined;
+            // #246: Stats are now always number (never null). Detect "empty" fallback:
+            // fallback + all counts zero means no real data was available.
+            // NOTE: totalAssistantTurns may be 0 even for valid sessions because
+            // listRecentNocturnalCandidateSessions (used in fallback path) does not
+            // populate assistantTurnCount (only getNocturnalSessionSnapshot does).
+            // We use totalToolCalls=0 as the primary indicator instead.
+            if (stats && dataSource === 'pain_context_fallback' &&
+                stats.totalToolCalls === 0 && stats.totalGateBlocks === 0 &&
+                stats.failureCount === 0) {
+              details.push(`fallback_snapshot_stats: nocturnal workflow ${wf.workflow_id} has empty fallback stats (no trajectory data found)`);
+            }
+          }
+        } catch (err) {
+          details.push(`malformed_metadata: workflow ${wf.workflow_id} has unparseable metadata: ${String(err).slice(0, 100)}`);
+        }
+      }
+
+      // Summary
+      const stateCounts: Record<string, number> = {};
+      for (const wf of allWorkflows) {
+        stateCounts[wf.state] = (stateCounts[wf.state] || 0) + 1;
+      }
+      const stateSummary = Object.entries(stateCounts).map(([s, c]) => `${s}=${c}`).join(', ');
+      if (details.length === 0) {
+        logger?.debug?.(`[PD:Watchdog] OK — ${allWorkflows.length} workflows (${stateSummary})`);
+      } else {
+        logger?.info?.(`[PD:Watchdog] ${details.length} anomalies — ${allWorkflows.length} workflows (${stateSummary})`);
+      }
+    } finally {
+      store.dispose();
+    }
+  } catch (err) {
+    logger?.warn?.(`[PD:Watchdog] Failed to scan workflows: ${String(err)}`);
+    return { anomalies: -1, details: [], scanError: String(err) };
+  }
+
+  return { anomalies: details.length, details };
+}

package/src/tools/deep-reflect.ts

@@ -1,4 +1,5 @@
 import type { OpenClawPluginApi } from '../openclaw-sdk.js';
+import type { PluginRuntimeSubagent } from '../service/subagent-workflow/runtime-direct-driver.js';
 import { Type } from '@sinclair/typebox';
 import * as fs from 'fs';
 import { EventLogService } from '../core/event-log.js';
@@ -23,6 +24,16 @@ interface DeepReflectionConfig {
     timeout_ms?: number;
 }
 
+/**
+ * Type assertion: OpenClaw SDK subagent -> workflow manager subagent type.
+ * Both types are structurally identical but come from different import paths.
+ */
+function toWorkflowSubagent(
+  subagent: NonNullable<OpenClawPluginApi['runtime']>['subagent']
+): PluginRuntimeSubagent {
+  return subagent as unknown as PluginRuntimeSubagent;
+}
+
 const DEFAULT_CONFIG: DeepReflectionConfig = {
     enabled: true,
     mode: 'auto',
@@ -108,7 +119,7 @@ export function createDeepReflectTool(api: OpenClawPluginApi) {
             }
 
              
-            // eslint-disable-next-line @typescript-eslint/no-use-before-define
+             
             const effectiveWorkspaceDir = resolveReflectionWorkspace(api);
 
             const config = loadConfig(effectiveWorkspaceDir, api);
@@ -122,11 +133,11 @@ export function createDeepReflectTool(api: OpenClawPluginApi) {
 
             try {
                  
-                // eslint-disable-next-line @typescript-eslint/no-use-before-define
+                 
                 return await executeReflectionWorkflow(effectiveWorkspaceDir, config, context, depth, model_id, api);
             } catch (err) {
                  
-                // eslint-disable-next-line @typescript-eslint/no-use-before-define
+                 
                 return handleReflectionError(err, context, depth, model_id, effectiveWorkspaceDir, api);
             }
         }
@@ -149,7 +160,7 @@ function resolveReflectionWorkspace(api: OpenClawPluginApi): string {
  * Execute the deep reflection workflow: start, poll, collect results.
  */
  
-// eslint-disable-next-line @typescript-eslint/max-params
+ 
 async function executeReflectionWorkflow(
     effectiveWorkspaceDir: string,
     config: DeepReflectionConfig,
@@ -165,8 +176,8 @@ async function executeReflectionWorkflow(
     const manager = new DeepReflectWorkflowManager({
         workspaceDir: effectiveWorkspaceDir,
         logger: api.logger,
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Reason: api.runtime.subagent has structurally compatible shape but differs from PluginRuntimeSubagent due to optional provider/model fields
-        subagent: api.runtime.subagent as any,
+         
+        subagent: toWorkflowSubagent(api.runtime.subagent),
         agentSession: api.runtime.agent?.session,
     });
 
@@ -181,7 +192,7 @@ async function executeReflectionWorkflow(
         const startTime = Date.now();
         const timeoutMs = config.timeout_ms ?? 60000;
          
-        // eslint-disable-next-line @typescript-eslint/no-use-before-define
+         
         return await pollReflectionCompletion(manager, handle, timeoutMs, startTime, eventLog, effectiveWorkspaceDir, context, model_id, depth);
     } finally {
         manager.dispose();
@@ -192,7 +203,7 @@ async function executeReflectionWorkflow(
  * Poll the reflection workflow until completion, timeout, or error.
  */
  
-// eslint-disable-next-line @typescript-eslint/max-params
+ 
 async function pollReflectionCompletion(
     manager: DeepReflectWorkflowManager,
     handle: { workflowId: string; childSessionKey: string },
@@ -213,7 +224,7 @@ async function pollReflectionCompletion(
 
         if (workflowState === 'completed') {
              
-            // eslint-disable-next-line @typescript-eslint/no-use-before-define
+             
             return formatReflectionSuccess(handle, context, depth, model_id, startTime, eventLog, workspaceDir);
         }
 
@@ -229,7 +240,7 @@ async function pollReflectionCompletion(
  * Format the success response from a completed reflection.
  */
  
-// eslint-disable-next-line @typescript-eslint/max-params
+ 
 function formatReflectionSuccess(
     handle: { childSessionKey: string },
     context: string,
@@ -283,7 +294,7 @@ ${insights || '反思完成，详见 REFLECTION_LOG。'}
  * Handle reflection errors and format error response.
  */
  
-// eslint-disable-next-line @typescript-eslint/max-params
+ 
 function handleReflectionError(
     err: unknown,
     context: string,

package/src/types/event-payload.ts

@@ -0,0 +1,80 @@
+/**
+ * Discriminated union for EventLogEntry — replaces flat data: Record<string, unknown>.
+ * Each union member is keyed on the `type` field for type narrowing.
+ */
+
+import type {
+  ToolCallEventData,
+  PainSignalEventData,
+  RuleMatchEventData,
+  RulePromotionEventData,
+  HookExecutionEventData,
+  GateBlockEventData,
+  GateBypassEventData,
+  PlanApprovalEventData,
+  EvolutionTaskEventData,
+  DeepReflectionEventData,
+  EmpathyRollbackEventData,
+  EventCategory,
+} from './event-types.js';
+
+export type EventLogEntry =
+  | { ts: string; date: string; type: 'tool_call'; category: EventCategory; sessionId?: string; workspaceDir?: string; data: ToolCallEventData }
+  | { ts: string; date: string; type: 'pain_signal'; category: EventCategory; sessionId?: string; workspaceDir?: string; data: PainSignalEventData }
+  | { ts: string; date: string; type: 'rule_match'; category: EventCategory; sessionId?: string; workspaceDir?: string; data: RuleMatchEventData }
+  | { ts: string; date: string; type: 'rule_promotion'; category: EventCategory; sessionId?: string; workspaceDir?: string; data: RulePromotionEventData }
+  | { ts: string; date: string; type: 'hook_execution'; category: EventCategory; sessionId?: string; workspaceDir?: string; data: HookExecutionEventData }
+  | { ts: string; date: string; type: 'gate_block'; category: EventCategory; sessionId?: string; workspaceDir?: string; data: GateBlockEventData }
+  | { ts: string; date: string; type: 'gate_bypass'; category: EventCategory; sessionId?: string; workspaceDir?: string; data: GateBypassEventData }
+  | { ts: string; date: string; type: 'plan_approval'; category: EventCategory; sessionId?: string; workspaceDir?: string; data: PlanApprovalEventData }
+  | { ts: string; date: string; type: 'evolution_task'; category: EventCategory; sessionId?: string; workspaceDir?: string; data: EvolutionTaskEventData }
+  | { ts: string; date: string; type: 'deep_reflection'; category: EventCategory; sessionId?: string; workspaceDir?: string; data: DeepReflectionEventData }
+  | { ts: string; date: string; type: 'empathy_rollback'; category: EventCategory; sessionId?: string; workspaceDir?: string; data: EmpathyRollbackEventData }
+  | { ts: string; date: string; type: 'error'; category: EventCategory; sessionId?: string; workspaceDir?: string; data: Record<string, unknown> }
+  | { ts: string; date: string; type: 'warn'; category: EventCategory; sessionId?: string; workspaceDir?: string; data: Record<string, unknown> };
+
+// Type predicates for safe narrowing
+
+export function isToolCallEventEntry(entry: EventLogEntry): entry is Extract<EventLogEntry, { type: 'tool_call' }> {
+  return entry.type === 'tool_call';
+}
+
+export function isPainSignalEventEntry(entry: EventLogEntry): entry is Extract<EventLogEntry, { type: 'pain_signal' }> {
+  return entry.type === 'pain_signal';
+}
+
+export function isRuleMatchEventEntry(entry: EventLogEntry): entry is Extract<EventLogEntry, { type: 'rule_match' }> {
+  return entry.type === 'rule_match';
+}
+
+export function isRulePromotionEventEntry(entry: EventLogEntry): entry is Extract<EventLogEntry, { type: 'rule_promotion' }> {
+  return entry.type === 'rule_promotion';
+}
+
+export function isHookExecutionEventEntry(entry: EventLogEntry): entry is Extract<EventLogEntry, { type: 'hook_execution' }> {
+  return entry.type === 'hook_execution';
+}
+
+export function isGateBlockEventEntry(entry: EventLogEntry): entry is Extract<EventLogEntry, { type: 'gate_block' }> {
+  return entry.type === 'gate_block';
+}
+
+export function isGateBypassEventEntry(entry: EventLogEntry): entry is Extract<EventLogEntry, { type: 'gate_bypass' }> {
+  return entry.type === 'gate_bypass';
+}
+
+export function isPlanApprovalEventEntry(entry: EventLogEntry): entry is Extract<EventLogEntry, { type: 'plan_approval' }> {
+  return entry.type === 'plan_approval';
+}
+
+export function isEvolutionTaskEventEntry(entry: EventLogEntry): entry is Extract<EventLogEntry, { type: 'evolution_task' }> {
+  return entry.type === 'evolution_task';
+}
+
+export function isDeepReflectionEventEntry(entry: EventLogEntry): entry is Extract<EventLogEntry, { type: 'deep_reflection' }> {
+  return entry.type === 'deep_reflection';
+}
+
+export function isEmpathyRollbackEventEntry(entry: EventLogEntry): entry is Extract<EventLogEntry, { type: 'empathy_rollback' }> {
+  return entry.type === 'empathy_rollback';
+}

package/src/types/queue.ts

@@ -0,0 +1,70 @@
+/**
+ * Branded types for queue and workflow domain identifiers.
+ * These prevent accidental interchange of plain strings with domain-specific IDs.
+ */
+
+/**
+ * Brand type constructor using intersection type pattern.
+ * @example type UserId = Brand<string, 'UserId'>;
+ */
+export type Brand<T, B> = T & { readonly _brand: B };
+
+/**
+ * Queue item identifier — not interchangeable with plain string.
+ */
+export type QueueItemId = Brand<string, 'QueueItemId'>;
+
+/**
+ * Workflow identifier — not interchangeable with plain string.
+ */
+export type WorkflowId = Brand<string, 'WorkflowId'>;
+
+/**
+ * Session key — not interchangeable with plain string.
+ */
+export type SessionKey = Brand<string, 'SessionKey'>;
+
+/**
+ * Constructor for QueueItemId.
+ * @param id - raw string ID from queue operations
+ */
+export function toQueueItemId(id: string): QueueItemId {
+  return id as QueueItemId;
+}
+
+/**
+ * Constructor for WorkflowId.
+ * @param id - raw string ID from workflow operations
+ */
+export function toWorkflowId(id: string): WorkflowId {
+  return id as WorkflowId;
+}
+
+/**
+ * Constructor for SessionKey.
+ * @param key - raw string key from session operations
+ */
+export function toSessionKey(key: string): SessionKey {
+  return key as SessionKey;
+}
+
+/**
+ * Type predicate: true if value is a QueueItemId.
+ */
+export function isQueueItemId(value: unknown): value is QueueItemId {
+  return typeof value === 'string';
+}
+
+/**
+ * Type predicate: true if value is a WorkflowId.
+ */
+export function isWorkflowId(value: unknown): value is WorkflowId {
+  return typeof value === 'string';
+}
+
+/**
+ * Type predicate: true if value is a SessionKey.
+ */
+export function isSessionKey(value: unknown): value is SessionKey {
+  return typeof value === 'string';
+}

package/src/utils/file-lock.ts

@@ -322,7 +322,7 @@ export async function withLockAsync<T>(
  * 注意：这是一个简化的实现，适用于单进程内的异步并发控制
  * 对于多进程场景，应使用同步版本的 acquireLock
  */
-const asyncLockQueues = new Map<string, Promise<void>>();
+export const asyncLockQueues = new Map<string, Promise<void>>();
 
 export async function withAsyncLock<T>(
   filePath: string,
@@ -335,7 +335,7 @@ export async function withAsyncLock<T>(
   
   // 创建新的 Promise 链
    
-  // eslint-disable-next-line @typescript-eslint/init-declarations
+   
   let resolveRelease: () => void;
   const releasePromise = new Promise<void>(resolve => {
     resolveRelease = resolve;

package/src/utils/io.ts

@@ -28,9 +28,17 @@ export function atomicWriteFileSync(filePath: string, data: string): void {
             if (code === 'EPERM' || code === 'EBUSY' || code === 'EACCES') {
                 if (attempt < RENAME_MAX_RETRIES - 1) {
                     const delay = RENAME_BASE_DELAY_MS * Math.pow(2, attempt);
-                    // Busy-wait is acceptable for very short delays (50-200ms)
-                    const end = Date.now() + delay;
-                    while (Date.now() < end) { /* spin */ }
+                    // Bounded spin-wait with CPU yield — materially different from
+                    // tight infinite spin; only 50-200ms total across retries.
+                    const waitUntil = Date.now() + delay;
+                    let yielded = false;
+                    while (Date.now() < waitUntil) {
+                        if (!yielded && Date.now() >= waitUntil - 10) {
+                            // Last few ms: yield to give other sync code a chance to run
+                            try { require('fs').accessSync?.(tmpPath); } catch { /* ignore */ }
+                            yielded = true;
+                        }
+                    }
                 }
                 continue;
             }

package/tests/core/code-validator.test.ts

@@ -0,0 +1,197 @@
+import { describe, expect, it } from 'vitest';
+import { validateGeneratedCode } from '../../src/core/principle-compiler/code-validator.js';
+
+describe('validateGeneratedCode', () => {
+  // --- Valid code ---
+
+  it('accepts valid rule implementation with evaluate and meta', () => {
+    const code = `
+export const meta = {
+  name: 'test-rule',
+  version: '1.0.0',
+  ruleId: 'R-001',
+  coversCondition: 'test condition'
+};
+
+export function evaluate(input) {
+  return {
+    matched: input.action.toolName === 'bash',
+    reason: 'checked toolName'
+  };
+}
+`;
+    const result = validateGeneratedCode(code);
+    expect(result.valid).toBe(true);
+    expect(result.errors).toEqual([]);
+  });
+
+  it('accepts evaluate that returns matched: false', () => {
+    const code = `
+export const meta = { name: 'never-match', version: '1.0.0', ruleId: 'R-002', coversCondition: 'none' };
+
+export function evaluate(_input) {
+  return { matched: false, reason: 'never matches' };
+}
+`;
+    const result = validateGeneratedCode(code);
+    expect(result.valid).toBe(true);
+  });
+
+  // --- Syntax check ---
+
+  it('rejects code with syntax errors', () => {
+    const code = `function broken( {`;
+    const result = validateGeneratedCode(code);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => /syntax/i.test(e))).toBe(true);
+  });
+
+  // --- Forbidden patterns ---
+
+  it('rejects code containing require(', () => {
+    const code = `
+export const meta = { name: 'x', version: '1', ruleId: 'R', coversCondition: 'c' };
+export function evaluate() { const fs = require('fs'); return { matched: false, reason: '' }; }
+`;
+    const result = validateGeneratedCode(code);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => /require/i.test(e))).toBe(true);
+  });
+
+  it('rejects code containing import statement', () => {
+    const code = `import { something } from 'module';
+export const meta = { name: 'x', version: '1', ruleId: 'R', coversCondition: 'c' };
+export function evaluate() { return { matched: false, reason: '' }; }
+`;
+    const result = validateGeneratedCode(code);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => /import/i.test(e))).toBe(true);
+  });
+
+  it('rejects code containing fetch(', () => {
+    const code = `
+export const meta = { name: 'x', version: '1', ruleId: 'R', coversCondition: 'c' };
+export function evaluate() { fetch('http://evil.com'); return { matched: false, reason: '' }; }
+`;
+    const result = validateGeneratedCode(code);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => /fetch/i.test(e))).toBe(true);
+  });
+
+  it('rejects code containing eval(', () => {
+    const code = `
+export const meta = { name: 'x', version: '1', ruleId: 'R', coversCondition: 'c' };
+export function evaluate() { eval('42'); return { matched: false, reason: '' }; }
+`;
+    const result = validateGeneratedCode(code);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => /eval/i.test(e))).toBe(true);
+  });
+
+  it('rejects code containing Function(', () => {
+    const code = `
+export const meta = { name: 'x', version: '1', ruleId: 'R', coversCondition: 'c' };
+export function evaluate() { new Function('return 1')(); return { matched: false, reason: '' }; }
+`;
+    const result = validateGeneratedCode(code);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => /Function/i.test(e))).toBe(true);
+  });
+
+  it('rejects code containing process', () => {
+    const code = `
+export const meta = { name: 'x', version: '1', ruleId: 'R', coversCondition: 'c' };
+export function evaluate() { const x = process.env; return { matched: false, reason: '' }; }
+`;
+    const result = validateGeneratedCode(code);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => /process/i.test(e))).toBe(true);
+  });
+
+  it('rejects code containing globalThis', () => {
+    const code = `
+export const meta = { name: 'x', version: '1', ruleId: 'R', coversCondition: 'c' };
+export function evaluate() { globalThis.foo = 'bar'; return { matched: false, reason: '' }; }
+`;
+    const result = validateGeneratedCode(code);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => /globalThis/i.test(e))).toBe(true);
+  });
+
+  it('reports all forbidden patterns at once', () => {
+    const code = `
+export const meta = { name: 'x', version: '1', ruleId: 'R', coversCondition: 'c' };
+export function evaluate() {
+  require('fs');
+  fetch('http://x');
+  eval('1');
+  process.env;
+  return { matched: false, reason: '' };
+}
+`;
+    const result = validateGeneratedCode(code);
+    expect(result.valid).toBe(false);
+    expect(result.errors.length).toBeGreaterThanOrEqual(4);
+  });
+
+  // --- Export check ---
+
+  it('rejects code that does not export evaluate', () => {
+    const code = `
+export const meta = { name: 'x', version: '1', ruleId: 'R', coversCondition: 'c' };
+// no evaluate function at all
+`;
+    const result = validateGeneratedCode(code);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => /evaluate/i.test(e))).toBe(true);
+  });
+
+  it('rejects code that does not export meta', () => {
+    const code = `
+// no meta at all
+export function evaluate() { return { matched: false, reason: '' }; }
+`;
+    const result = validateGeneratedCode(code);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => /meta/i.test(e))).toBe(true);
+  });
+
+  // --- Return shape check ---
+
+  it('rejects evaluate that returns object without matched', () => {
+    const code = `
+export const meta = { name: 'x', version: '1', ruleId: 'R', coversCondition: 'c' };
+export function evaluate() { return { reason: 'no matched field' }; }
+`;
+    const result = validateGeneratedCode(code);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => /matched/i.test(e))).toBe(true);
+  });
+
+  it('accepts evaluate even when it throws on mock input', () => {
+    // evaluate throws because it accesses a nested property that doesn't exist in mock
+    const code = `
+export const meta = { name: 'x', version: '1', ruleId: 'R', coversCondition: 'c' };
+export function evaluate(input) {
+  if (input.action.toolName === 'bash') {
+    return { matched: true, reason: 'ok' };
+  }
+  throw new Error('unexpected input');
+}
+`;
+    // The mock input has toolName: 'bash', so it returns successfully
+    const result = validateGeneratedCode(code);
+    expect(result.valid).toBe(true);
+  });
+
+  it('accepts evaluate that throws as long as it has correct shape when it returns', () => {
+    const code = `
+export const meta = { name: 'x', version: '1', ruleId: 'R', coversCondition: 'c' };
+export function evaluate(_input) {
+  return { matched: true, reason: 'ok' };
+}
+`;
+    const result = validateGeneratedCode(code);
+    expect(result.valid).toBe(true);
+  });
+});