principles-disciple 1.79.0 → 1.81.0

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "principles-disciple",
   "name": "Principles Disciple",
   "description": "Evolutionary programming agent framework with strategic guardrails and reflection loops.",
-  "version": "1.79.0",
+  "version": "1.81.0",
   "activation": {
     "onCapabilities": [
       "hook"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "principles-disciple",
-  "version": "1.79.0",
+  "version": "1.81.0",
   "description": "Native OpenClaw plugin for Principles Disciple",
   "type": "module",
   "main": "./dist/bundle.js",

package/src/index.ts

@@ -49,6 +49,7 @@ import { handleExportCommand } from './commands/export.js';
 import { handleSamplesCommand } from './commands/samples.js';
 import { handleWorkflowDebugCommand } from './commands/workflow-debug.js';
 import { EvolutionWorkerService } from './service/evolution-worker.js';
+import { CorrectionObserverService } from './service/correction-observer-service.js';
 import { TrajectoryService } from './service/trajectory-service.js';
 import { PDTaskService } from './core/pd-task-service.js';
 import { CentralSyncService } from './service/central-sync-service.js';
@@ -168,6 +169,30 @@ export function shouldStartEvolutionWorker(
   return { shouldStart: false, flagSource: flag.source, disabledInfo };
 }
 
+export interface CorrectionObserverGateResult {
+  shouldStart: boolean;
+  flagSource: string;
+  disabledInfo: string | null;
+}
+
+export function shouldStartCorrectionObserver(
+  workspaceDir: string,
+  logger: { info?: (msg: string) => void; warn?: (msg: string) => void },
+): CorrectionObserverGateResult {
+  const flag = loadFeatureFlagFromWorkspace(workspaceDir, 'correction_observer', logger);
+  if (flag.enabled) {
+    return { shouldStart: true, flagSource: flag.source, disabledInfo: null };
+  }
+  const disabledInfo = JSON.stringify({
+    reason: 'correction_observer_disabled',
+    nextAction: 'set correction_observer.enabled=true in .pd/feature-flags.yaml to enable',
+    featureFlag: 'correction_observer',
+    boundedContext: 'correction_observer_service',
+    flagSource: flag.source,
+  });
+  return { shouldStart: false, flagSource: flag.source, disabledInfo };
+}
+
 const plugin = {
   name: "Principles Disciple",
   description: "Evolutionary programming agent framework with strategic guardrails and reflection loops.",
@@ -246,6 +271,22 @@ const plugin = {
               api.logger.info(`[PD] EvolutionWorker NOT started for workspace: ${workspaceDir}. ${gate.disabledInfo}`);
               SystemLogger.log(workspaceDir, 'EVOLUTION_WORKER_DISABLED', gate.disabledInfo ?? '');
             }
+
+            // ── Start CorrectionObserver for THIS workspace ──
+            // MVP-Core per ADR-0014 amendment, independently owned (PRI-293).
+            const corrGate = shouldStartCorrectionObserver(workspaceDir, api.logger);
+            if (corrGate.shouldStart) {
+              CorrectionObserverService.start({
+                config: api.config,
+                workspaceDir,
+                stateDir: path.join(workspaceDir, '.state'),
+                logger: api.logger,
+              });
+              api.logger.info(`[PD] CorrectionObserver started for workspace: ${workspaceDir} (flag source: ${corrGate.flagSource})`);
+            } else {
+              api.logger.info(`[PD] CorrectionObserver NOT started for workspace: ${workspaceDir}. ${corrGate.disabledInfo}`);
+              SystemLogger.log(workspaceDir, 'CORRECTION_OBSERVER_DISABLED', corrGate.disabledInfo ?? '');
+            }
           }
 
           const result = await handleBeforePromptBuild(event, { ...ctx, api: api as Parameters<typeof handleBeforePromptBuild>[1]['api'], workspaceDir });
@@ -527,6 +568,8 @@ const plugin = {
       EvolutionWorkerService.api = api;
       const guardedEvolutionWorker = guardService('service:evolution-worker', EvolutionWorkerService, api.logger);
       if (guardedEvolutionWorker) api.registerService(guardedEvolutionWorker);
+      const guardedCorrectionObserver = guardService('service:correction-observer', CorrectionObserverService, api.logger);
+      if (guardedCorrectionObserver) api.registerService(guardedCorrectionObserver);
       const guardedTrajectory = guardService('service:trajectory', TrajectoryService, api.logger);
       if (guardedTrajectory) api.registerService(guardedTrajectory);
       const guardedPdTask = guardService('service:pd-task', PDTaskService, api.logger);

package/src/service/correction-observer-service.ts

@@ -0,0 +1,200 @@
+import type { OpenClawPluginServiceContext, PluginLogger } from '../openclaw-sdk.js';
+import { WorkspaceContext } from '../core/workspace-context.js';
+import { TrajectoryRegistry } from '../core/trajectory.js';
+import { CorrectionCueLearner } from '../core/correction-cue-learner.js';
+import {
+    WorkflowFunnelLoader,
+    PiAiRuntimeAdapter,
+    CorrectionObserver,
+    AgentScheduler,
+} from '@principles/core/runtime-v2';
+import { KeywordOptimizationService } from './keyword-optimization-service.js';
+import { SystemLogger } from '../core/system-logger.js';
+
+export interface CorrectionObserverServiceShape {
+    id: string;
+    start: (ctx: OpenClawPluginServiceContext) => void;
+    stop?: (ctx: OpenClawPluginServiceContext) => void;
+}
+
+let correctionObserverTimeoutId: ReturnType<typeof setTimeout> | null = null;
+let correctionObserverStopped = false;
+const startedWorkspaces = new Set<string>();
+
+const CORRECTION_OBSERVER_INTERVAL_MS = 15 * 60 * 1000;
+const CORRECTION_OBSERVER_INITIAL_DELAY_MS = 10_000;
+const CORRECTION_OBSERVER_MAX_RECENT_SESSIONS = 20;
+const CORRECTION_OBSERVER_MAX_PAYLOAD_SESSIONS = 5;
+
+export function resolveCorrectionObserver(wctx: WorkspaceContext, logger?: Pick<PluginLogger, 'info' | 'warn' | 'error' | 'debug'>): CorrectionObserver | null {
+    try {
+        const loader = new WorkflowFunnelLoader(wctx.stateDir);
+        const funnel = loader.getFunnel('pd-correction-observer');
+        const policy = funnel?.policy;
+        if (!policy || policy.runtimeKind !== 'pi-ai') {
+            logger?.debug?.('[PD:CorrectionObserver] workflows.yaml pd-correction-observer policy not found. Falling back to environment variables.');
+            const provider = process.env.PD_CORRECTION_PROVIDER || 'anthropic';
+            const model = process.env.PD_CORRECTION_MODEL || 'anthropic/claude-3-5-sonnet';
+            const apiKeyEnv = process.env.PD_CORRECTION_API_KEY_ENV || 'ANTHROPIC_API_KEY';
+            const baseUrl = process.env.PD_CORRECTION_BASE_URL;
+
+            if (!process.env[apiKeyEnv]) {
+                logger?.debug?.(`[PD:CorrectionObserver] API key env ${apiKeyEnv} is not set. Periodic optimization disabled.`);
+                return null;
+            }
+
+            const adapter = new PiAiRuntimeAdapter({
+                provider,
+                model,
+                apiKeyEnv,
+                baseUrl,
+                workspace: wctx.workspaceDir,
+            });
+            return new CorrectionObserver({ runtimeAdapter: adapter });
+        }
+
+        const adapter = new PiAiRuntimeAdapter({
+            provider: String(policy.provider),
+            model: String(policy.model),
+            apiKeyEnv: String(policy.apiKeyEnv),
+            maxRetries: policy.maxRetries,
+            timeoutMs: policy.timeoutMs ?? 30_000,
+            baseUrl: policy.baseUrl,
+            workspace: wctx.workspaceDir,
+        });
+        return new CorrectionObserver({ runtimeAdapter: adapter }, { timeoutMs: policy.timeoutMs });
+    } catch (err) {
+        logger?.warn?.(`[PD:CorrectionObserver] Failed to resolve CorrectionObserver: ${String(err)}`);
+        return null;
+    }
+}
+
+export async function runCorrectionObserverCycle(wctx: WorkspaceContext, logger: PluginLogger): Promise<void> {
+    try {
+        const observer = resolveCorrectionObserver(wctx, logger);
+        if (!observer) {
+            logger?.info?.('[PD:CorrectionObserver] Observer not resolved (no API key or config). Skipping cycle.');
+            return;
+        }
+
+        logger?.info?.('[PD:CorrectionObserver] Observer resolved. Initiating periodic optimization...');
+
+        const db = TrajectoryRegistry.get(wctx.workspaceDir);
+        const recentSessions = db.listRecentSessions({ limit: CORRECTION_OBSERVER_MAX_RECENT_SESSIONS });
+        const recentSessionIds = recentSessions.map(s => s.sessionId);
+
+        if (recentSessionIds.length === 0) {
+            logger?.info?.('[PD:CorrectionObserver] No recent sessions found. Skipping correction optimization.');
+            return;
+        }
+
+        const recentMessages: string[] = [];
+        for (const sId of recentSessionIds.slice(0, CORRECTION_OBSERVER_MAX_PAYLOAD_SESSIONS)) {
+            try {
+                const turns = db.listUserTurnsForSession(sId);
+                for (const t of turns) {
+                    if (t.rawExcerpt) {
+                        recentMessages.push(t.rawExcerpt);
+                    }
+                }
+            } catch (turnErr) {
+                logger?.warn?.(`[PD:CorrectionObserver] Failed to load user turns for session ${sId}: ${String(turnErr)}`);
+            }
+        }
+
+        const learner = CorrectionCueLearner.get(wctx.stateDir);
+        const keywords = learner.getStore().keywords;
+        const keywordStoreSummary = {
+            totalKeywords: keywords.length,
+            terms: keywords.map(k => ({
+                term: k.term,
+                weight: k.weight,
+                hitCount: k.hitCount ?? 0,
+                truePositiveCount: k.truePositiveCount ?? 0,
+                falsePositiveCount: k.falsePositiveCount ?? 0,
+            })),
+        };
+
+        const optimizationService = KeywordOptimizationService.get(wctx.stateDir, wctx.workspaceDir, logger);
+        const trajectoryHistory = await optimizationService.buildTrajectoryHistory(recentSessionIds);
+
+        const payload = {
+            parentSessionId: 'correction-observer-service',
+            workspaceDir: wctx.workspaceDir,
+            keywordStoreSummary,
+            recentMessages,
+            trajectoryHistory,
+        };
+
+        const scheduler = new AgentScheduler();
+        scheduler.register({
+            agentId: 'correction-observer',
+            mode: 'realtime',
+            runner: observer,
+        });
+
+        logger?.info?.(`[PD:CorrectionObserver] Dispatching with ${trajectoryHistory.length} trajectory events, ${recentMessages.length} recent messages.`);
+        const result = await scheduler.dispatch('correction-observer', payload);
+        logger?.info?.(`[PD:CorrectionObserver] Completed: updated=${result.updated}, summary="${result.summary}"`);
+
+        if (result.updated) {
+            optimizationService.applyResult(result);
+        }
+    } catch (err) {
+        const errMsg = `Correction observer cycle failed: ${String(err)}`;
+        logger?.warn?.(`[PD:CorrectionObserver] ${errMsg}`);
+        SystemLogger.log(wctx.workspaceDir, 'CORRECTION_OBSERVER_CYCLE_FAILED', errMsg);
+    }
+}
+
+export const CorrectionObserverService: CorrectionObserverServiceShape = {
+    id: 'principles-correction-observer',
+
+    start(ctx: OpenClawPluginServiceContext): void {
+        const workspaceDir = ctx?.workspaceDir;
+        const logger = ctx?.logger || console;
+
+        if (!workspaceDir) {
+            if (logger) logger.warn('[PD:CorrectionObserver] workspaceDir not found in service config. Correction observer disabled.');
+            return;
+        }
+
+        if (startedWorkspaces.has(workspaceDir)) {
+            if (logger) logger.info(`[PD:CorrectionObserver] Already started for workspace: ${workspaceDir}. Skipping duplicate start.`);
+            return;
+        }
+        startedWorkspaces.add(workspaceDir);
+
+        correctionObserverStopped = false;
+
+        const wctx = WorkspaceContext.fromHookContext({ workspaceDir, ...ctx.config });
+        if (logger) logger.info(`[PD:CorrectionObserver] Starting with workspaceDir=${wctx.workspaceDir}, stateDir=${wctx.stateDir}`);
+
+        const interval = CORRECTION_OBSERVER_INTERVAL_MS;
+
+        async function runCycle(): Promise<void> {
+            if (correctionObserverStopped) return;
+            await runCorrectionObserverCycle(wctx, logger);
+            if (correctionObserverStopped) return;
+            correctionObserverTimeoutId = setTimeout(runCycle, interval);
+            correctionObserverTimeoutId.unref();
+        }
+
+        correctionObserverTimeoutId = setTimeout(() => {
+            void runCycle().catch((err) => {
+                if (logger) logger.error(`[PD:CorrectionObserver] Startup cycle failed: ${String(err)}`);
+                if (correctionObserverStopped) return;
+                correctionObserverTimeoutId = setTimeout(runCycle, interval);
+                correctionObserverTimeoutId.unref();
+            });
+        }, CORRECTION_OBSERVER_INITIAL_DELAY_MS);
+        correctionObserverTimeoutId.unref();
+    },
+
+    stop(_ctx: OpenClawPluginServiceContext): void {
+        correctionObserverStopped = true;
+        startedWorkspaces.clear();
+        if (correctionObserverTimeoutId) clearTimeout(correctionObserverTimeoutId);
+        correctionObserverTimeoutId = null;
+    },
+};

package/src/service/evolution-worker.ts

@@ -22,14 +22,7 @@ export { loadEvolutionQueue, saveEvolutionQueue, withQueueLock, acquireQueueLock
 export { EVOLUTION_QUEUE_LOCK_SUFFIX, LOCK_MAX_RETRIES, LOCK_RETRY_DELAY_MS, LOCK_STALE_MS } from './queue-io.js';
 import { saveEvolutionQueue, requireQueueLock } from './queue-io.js';
 import { WorkflowStore } from './subagent-workflow/workflow-store.js';
-import {
-    WorkflowFunnelLoader,
-    PiAiRuntimeAdapter,
-    CorrectionObserver,
-    AgentScheduler,
-} from '@principles/core/runtime-v2';
-import { KeywordOptimizationService } from './keyword-optimization-service.js';
-import { CorrectionCueLearner } from '../core/correction-cue-learner.js';
+
 
 import { PrincipleCompiler } from '../core/principle-compiler/index.js';
 import { loadLedger, updatePrinciple } from '../core/principle-tree-ledger.js';
@@ -632,49 +625,6 @@ async function processEvolutionQueueWithResult(
     return { queue: queueResult, errors };
 }
 
-function resolveCorrectionObserver(wctx: WorkspaceContext, logger?: Pick<PluginLogger, 'info' | 'warn' | 'error' | 'debug'>): CorrectionObserver | null {
-  try {
-    const loader = new WorkflowFunnelLoader(wctx.stateDir);
-    const funnel = loader.getFunnel('pd-correction-observer');
-    const policy = funnel?.policy;
-    if (!policy || policy.runtimeKind !== 'pi-ai') {
-      logger?.debug?.('[PD:Correction] workflows.yaml pd-correction-observer policy not found. Falling back to environment variables.');
-      const provider = process.env.PD_CORRECTION_PROVIDER || 'anthropic';
-      const model = process.env.PD_CORRECTION_MODEL || 'anthropic/claude-3-5-sonnet';
-      const apiKeyEnv = process.env.PD_CORRECTION_API_KEY_ENV || 'ANTHROPIC_API_KEY';
-      const baseUrl = process.env.PD_CORRECTION_BASE_URL;
-
-      if (!process.env[apiKeyEnv]) {
-        logger?.debug?.(`[PD:Correction] Correction observer API key env ${apiKeyEnv} is not set. Periodic optimization disabled.`);
-        return null;
-      }
-
-      const adapter = new PiAiRuntimeAdapter({
-        provider,
-        model,
-        apiKeyEnv,
-        baseUrl,
-        workspace: wctx.workspaceDir,
-      });
-      return new CorrectionObserver({ runtimeAdapter: adapter });
-    }
-
-    const adapter = new PiAiRuntimeAdapter({
-      provider: String(policy.provider),
-      model: String(policy.model),
-      apiKeyEnv: String(policy.apiKeyEnv),
-      maxRetries: policy.maxRetries,
-      timeoutMs: policy.timeoutMs ?? 30_000,
-      baseUrl: policy.baseUrl,
-      workspace: wctx.workspaceDir,
-    });
-    return new CorrectionObserver({ runtimeAdapter: adapter }, { timeoutMs: policy.timeoutMs });
-  } catch (err) {
-    logger?.warn?.(`[PD:Correction] Failed to resolve CorrectionObserver: ${String(err)}`);
-    return null;
-  }
-}
-
 export const EvolutionWorkerService: ExtendedEvolutionWorkerService = {
     id: 'principles-evolution-worker',
     api: null,
@@ -759,78 +709,7 @@ export const EvolutionWorkerService: ExtendedEvolutionWorkerService = {
                     await processDetectionQueue(wctx, api, eventLog);
                 }
                 // processPromotion removed (D-06) — promotion via PAIN_CANDIDATES no longer needed
-
-                // ── Correction Observer: periodic keyword optimization (D-40-08 / H-1) ──
-                try {
-                    const observer = resolveCorrectionObserver(wctx, logger);
-                    if (observer) {
-                        logger?.info?.('[PD:EvolutionWorker] Correction Observer resolved. Initiating periodic optimization...');
-                        const db = TrajectoryRegistry.get(wctx.workspaceDir);
-                        const recentSessions = db.listRecentSessions({ limit: 20 });
-                        const recentSessionIds = recentSessions.map(s => s.sessionId);
-
-                        if (recentSessionIds.length > 0) {
-                            const recentMessages: string[] = [];
-                            for (const sId of recentSessionIds.slice(0, 5)) {
-                                try {
-                                    const turns = db.listUserTurnsForSession(sId);
-                                    for (const t of turns) {
-                                        if (t.rawExcerpt) {
-                                            recentMessages.push(t.rawExcerpt);
-                                        }
-                                    }
-                                } catch (turnErr) {
-                                    logger?.warn?.(`[PD:EvolutionWorker] Failed to load user turns for session ${sId}: ${String(turnErr)}`);
-                                }
-                            }
-
-                            const learner = CorrectionCueLearner.get(wctx.stateDir);
-                            const keywords = learner.getStore().keywords;
-                            const keywordStoreSummary = {
-                                totalKeywords: keywords.length,
-                                terms: keywords.map(k => ({
-                                    term: k.term,
-                                    weight: k.weight,
-                                    hitCount: k.hitCount ?? 0,
-                                    truePositiveCount: k.truePositiveCount ?? 0,
-                                    falsePositiveCount: k.falsePositiveCount ?? 0,
-                                })),
-                            };
-
-                            const optimizationService = KeywordOptimizationService.get(wctx.stateDir, wctx.workspaceDir, logger);
-                            const trajectoryHistory = await optimizationService.buildTrajectoryHistory(recentSessionIds);
-
-                            const payload = {
-                                parentSessionId: 'evolution-worker',
-                                workspaceDir: wctx.workspaceDir,
-                                keywordStoreSummary,
-                                recentMessages,
-                                trajectoryHistory,
-                            };
-
-                            const scheduler = new AgentScheduler();
-                            scheduler.register({
-                                agentId: 'correction-observer',
-                                mode: 'realtime',
-                                runner: observer,
-                            });
-
-                            logger?.info?.(`[PD:EvolutionWorker] Dispatching correction-observer with ${trajectoryHistory.length} trajectory events, ${recentMessages.length} recent messages.`);
-                            const result = await scheduler.dispatch('correction-observer', payload);
-                            logger?.info?.(`[PD:EvolutionWorker] Correction-observer completed: updated=${result.updated}, summary="${result.summary}"`);
-                            
-                            if (result.updated) {
-                                optimizationService.applyResult(result);
-                            }
-                        } else {
-                            logger?.info?.('[PD:EvolutionWorker] No recent sessions found. Skipping correction optimization.');
-                        }
-                    }
-                } catch (corrErr) {
-                    const corrErrMsg = `Correction observer execution failed: ${String(corrErr)}`;
-                    cycleResult.errors.push(corrErrMsg);
-                    logger?.warn?.(`[PD:EvolutionWorker] ${corrErrMsg}`);
-                }
+                // Correction Observer extracted to independent service (PRI-293) — no longer runs on EvolutionWorker heartbeat
 
                 try {
                     const subagentRuntime = api?.runtime?.subagent;

package/tests/core/surface-guard.test.ts

@@ -0,0 +1,198 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import {
+  checkSurfaceGuard,
+  isSurfaceEnabled,
+  guardHook,
+  guardService,
+  getSurfaceIdForHook,
+  getSurfaceIdForService,
+} from '../../src/core/surface-guard.js';
+import { PLUGIN_SURFACE_REGISTRY } from '@principles/core/runtime-v2';
+import type { OpenClawPluginService } from '../../src/openclaw-sdk.js';
+
+describe('surface-guard', () => {
+  describe('getSurfaceIdForHook', () => {
+    it('generates correct surface id without label', () => {
+      expect(getSurfaceIdForHook('before_tool_call')).toBe('hook:before_tool_call');
+    });
+
+    it('generates correct surface id with label', () => {
+      expect(getSurfaceIdForHook('after_tool_call', 'trajectory')).toBe('hook:after_tool_call.trajectory');
+    });
+  });
+
+  describe('getSurfaceIdForService', () => {
+    it('generates correct surface id for service', () => {
+      expect(getSurfaceIdForService('evolution-worker')).toBe('service:evolution-worker');
+    });
+  });
+
+  describe('checkSurfaceGuard', () => {
+    it('returns passed=true when registry is valid', () => {
+      const result = checkSurfaceGuard();
+      expect(result.passed).toBe(true);
+      expect(result.violations).toEqual([]);
+    });
+
+    it('includes enabled core surfaces', () => {
+      const result = checkSurfaceGuard();
+      expect(result.enabledCoreSurfaces.length).toBeGreaterThan(0);
+      for (const surfaceId of result.enabledCoreSurfaces) {
+        const entry = PLUGIN_SURFACE_REGISTRY.find(s => s.id === surfaceId);
+        expect(entry).toBeDefined();
+        expect(entry?.category).toBe('core');
+      }
+    });
+
+    it('includes disabled non-core surfaces', () => {
+      const result = checkSurfaceGuard();
+      expect(result.disabledNonCoreSurfaces.length).toBeGreaterThan(0);
+      for (const surfaceId of result.disabledNonCoreSurfaces) {
+        const entry = PLUGIN_SURFACE_REGISTRY.find(s => s.id === surfaceId);
+        expect(entry).toBeDefined();
+        expect(entry?.category).not.toBe('core');
+        expect(entry?.enabledByDefault).toBe(false);
+      }
+    });
+
+    it('returns violations when non-core surface is enabledByDefault', () => {
+      const result = checkSurfaceGuard();
+      const nonCoreEnabled = PLUGIN_SURFACE_REGISTRY.filter(
+        s => s.category !== 'core' && s.enabledByDefault,
+      );
+      if (nonCoreEnabled.length > 0) {
+        expect(result.violations.length).toBeGreaterThan(0);
+      }
+    });
+  });
+
+  describe('isSurfaceEnabled', () => {
+    it('returns enabled=true for core surface without override', () => {
+      const result = isSurfaceEnabled('hook:before_prompt_build');
+      expect(result.enabled).toBe(true);
+      expect(result.reason).toBeUndefined();
+    });
+
+    it('returns enabled=false for quiet surface without override', () => {
+      const result = isSurfaceEnabled('hook:after_tool_call.trajectory');
+      expect(result.enabled).toBe(false);
+      expect(result.reason).toBeDefined();
+    });
+
+    it('returns reason when surface not found', () => {
+      const result = isSurfaceEnabled('hook:nonexistent_hook');
+      expect(result.enabled).toBe(false);
+      expect(result.reason).toContain('not found in registry');
+    });
+
+    it('allows override for quiet surface', () => {
+      const result = isSurfaceEnabled('hook:after_tool_call.trajectory', {
+        'hook:after_tool_call.trajectory': true,
+      });
+      expect(result.enabled).toBe(true);
+    });
+
+    it('ignores non-boolean override', () => {
+      const result = isSurfaceEnabled('hook:before_prompt_build', {
+        'hook:before_prompt_build': 'yes' as unknown as boolean,
+      });
+      expect(result.enabled).toBe(true);
+    });
+
+    it('cannot disable core surface', () => {
+      const result = isSurfaceEnabled('hook:before_prompt_build', {
+        'hook:before_prompt_build': false,
+      });
+      expect(result.enabled).toBe(true);
+      expect(result.reason).toContain('core');
+    });
+
+    it('returns disabledReason for disabled surface', () => {
+      const result = isSurfaceEnabled('service:evolution-worker');
+      expect(result.enabled).toBe(false);
+      expect(result.reason).toContain('evolution_worker');
+    });
+  });
+
+  describe('guardHook', () => {
+    beforeEach(() => {
+      vi.clearAllMocks();
+    });
+
+    it('returns original handler for enabled surface', () => {
+      const mockHandler = vi.fn().mockReturnValue('result');
+      const guarded = guardHook('hook:before_prompt_build', undefined, mockHandler);
+      const result = guarded({}, {});
+      expect(mockHandler).toHaveBeenCalled();
+      expect(result).toBe('result');
+    });
+
+    it('returns no-op for disabled surface without logger', () => {
+      const mockHandler = vi.fn();
+      const guarded = guardHook('hook:after_tool_call.trajectory', undefined, mockHandler);
+      const result = guarded({}, {});
+      expect(mockHandler).not.toHaveBeenCalled();
+      expect(result).toBeUndefined();
+    });
+
+    it('logs when surface is disabled with logger', () => {
+      const mockLogger = { info: vi.fn(), debug: vi.fn() };
+      const mockHandler = vi.fn();
+      const guarded = guardHook('hook:after_tool_call.trajectory', mockLogger, mockHandler);
+      guarded({}, {});
+      expect(mockLogger.info).toHaveBeenCalled();
+      expect(mockHandler).not.toHaveBeenCalled();
+    });
+
+    it('does not log for enabled surface', () => {
+      const mockLogger = { info: vi.fn(), debug: vi.fn() };
+      const mockHandler = vi.fn();
+      const guarded = guardHook('hook:before_prompt_build', mockLogger, mockHandler);
+      guarded({}, {});
+      expect(mockLogger.info).not.toHaveBeenCalled();
+    });
+
+    it('guards unknown surface with not-found reason', () => {
+      const mockLogger = { info: vi.fn(), debug: vi.fn() };
+      const guarded = guardHook('hook:unknown_hook', mockLogger, vi.fn());
+      guarded({}, {});
+      expect(mockLogger.info).toHaveBeenCalledWith(
+        expect.stringContaining('not found in registry'),
+      );
+    });
+  });
+
+  describe('guardService', () => {
+    beforeEach(() => {
+      vi.clearAllMocks();
+    });
+
+    it('returns original service for enabled surface', () => {
+      const mockService: OpenClawPluginService = { id: 'test-service' };
+      const result = guardService('hook:before_prompt_build', mockService);
+      expect(result).toBe(mockService);
+    });
+
+    it('returns null for disabled surface without logger', () => {
+      const mockService: OpenClawPluginService = { id: 'test-service' };
+      const result = guardService('hook:after_tool_call.trajectory', mockService);
+      expect(result).toBeNull();
+    });
+
+    it('logs when surface is disabled with logger', () => {
+      const mockLogger = { info: vi.fn(), debug: vi.fn() };
+      const mockService: OpenClawPluginService = { id: 'test-service' };
+      const result = guardService('hook:after_tool_call.trajectory', mockService, mockLogger);
+      expect(result).toBeNull();
+      expect(mockLogger.info).toHaveBeenCalledWith(
+        expect.stringContaining('SKIP service'),
+      );
+    });
+
+    it('returns null for unknown surface', () => {
+      const mockService: OpenClawPluginService = { id: 'test-service' };
+      const result = guardService('service:nonexistent', mockService);
+      expect(result).toBeNull();
+    });
+  });
+});