principles-disciple 1.87.0 → 1.89.0

package/tests/evolution-worker-quarantine.test.ts

@@ -2,8 +2,8 @@
  * PRI-288: Quarantine EvolutionWorkerService default startup behind MVP feature flag.
  *
  * Tests prove:
- * 1. Default config (no feature-flags.yaml) → EvolutionWorkerService does NOT start.
- * 2. Explicit enable in feature-flags.yaml → EvolutionWorkerService starts.
+ * 1. Default config (no config.yaml) → EvolutionWorkerService does NOT start.
+ * 2. Explicit enable in config.yaml → EvolutionWorkerService starts.
  * 3. Disabled state has structured observability from real helper, not hand-written JSON.
  * 4. api.registerService still works regardless of flag state.
  *
@@ -60,9 +60,63 @@ function createTempWorkspace(): string {
   return dir;
 }
 
-function writeFeatureFlags(workspaceDir: string, flags: Record<string, unknown>): void {
-  const configPath = path.join(workspaceDir, '.pd', 'feature-flags.yaml');
-  const content = yaml.dump(flags, { schema: yaml.JSON_SCHEMA });
+function deepMergeFeatures(
+  defaults: Record<string, unknown>,
+  overrides: Record<string, unknown>,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = { ...defaults };
+  for (const [key, value] of Object.entries(overrides)) {
+    if (
+      value != null &&
+      typeof value === 'object' &&
+      !Array.isArray(value) &&
+      Object.hasOwn(result, key) &&
+      result[key] != null &&
+      typeof result[key] === 'object' &&
+      !Array.isArray(result[key])
+    ) {
+      result[key] = { ...(result[key] as Record<string, unknown>), ...(value as Record<string, unknown>) };
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+function writeConfigYaml(workspaceDir: string, featureOverrides: Record<string, unknown>): void {
+  const configPath = path.join(workspaceDir, '.pd', 'config.yaml');
+  const defaultFeatures: Record<string, unknown> = {
+    prompt: { category: 'core', enabled: true },
+    code_tool_hook: { category: 'core', enabled: true },
+    defer_archive: { category: 'core', enabled: true },
+    correction_observer: { category: 'quiet', enabled: false },
+    empathy_observer: { category: 'quiet', enabled: false },
+    evolution_worker: { category: 'quiet', enabled: false },
+    nocturnal: { category: 'gone', enabled: false },
+  };
+  const config = {
+    version: 1,
+    features: deepMergeFeatures(defaultFeatures, featureOverrides),
+    runtimeProfiles: {
+      'openclaw.default': { type: 'openclaw', source: 'default' },
+    },
+    internalAgents: {
+      defaultRuntime: 'openclaw.default',
+      agents: {
+        diagnostician: { enabled: true },
+        dreamer: { enabled: true },
+        scribe: { enabled: true },
+        artificer: { enabled: true },
+        philosopher: { enabled: false },
+        evaluator: { enabled: false },
+        rolloutReviewer: { enabled: false },
+        trainer: { enabled: false },
+        correctionObserver: { enabled: false },
+        empathyObserver: { enabled: false },
+      },
+    },
+  };
+  const content = yaml.dump(config, { schema: yaml.JSON_SCHEMA });
   fs.writeFileSync(configPath, content, 'utf8');
 }
 
@@ -112,32 +166,32 @@ describe('PRI-288: EvolutionWorkerService quarantine', () => {
   // ── 2. loadFeatureFlagFromWorkspace ──
 
   describe('loadFeatureFlagFromWorkspace', () => {
-    it('returns enabled=false when no feature-flags.yaml exists', () => {
+    it('returns enabled=false when no config.yaml exists', () => {
       const logger = createMockLogger();
       const result = loadFeatureFlagFromWorkspace(workspaceDir, 'evolution_worker', logger);
       expect(result.enabled).toBe(false);
       expect(result.source).toBe('defaults');
     });
 
-    it('returns enabled=false when feature-flags.yaml has no evolution_worker entry', () => {
-      writeFeatureFlags(workspaceDir, { prompt: { enabled: true } });
+    it('returns enabled=false when config.yaml has no evolution_worker entry', () => {
+      writeConfigYaml(workspaceDir, { prompt: { enabled: true } });
       const logger = createMockLogger();
       const result = loadFeatureFlagFromWorkspace(workspaceDir, 'evolution_worker', logger);
       expect(result.enabled).toBe(false);
     });
 
-    it('returns enabled=true when feature-flags.yaml explicitly enables evolution_worker', () => {
-      writeFeatureFlags(workspaceDir, {
+    it('returns enabled=true when config.yaml explicitly enables evolution_worker', () => {
+      writeConfigYaml(workspaceDir, {
         evolution_worker: { enabled: true },
       });
       const logger = createMockLogger();
       const result = loadFeatureFlagFromWorkspace(workspaceDir, 'evolution_worker', logger);
       expect(result.enabled).toBe(true);
-      expect(result.source).toBe('workspace_file');
+      expect(result.source).toBe('user_config');
     });
 
     it('returns enabled=false when YAML is malformed and warning includes error detail', () => {
-      const configPath = path.join(workspaceDir, '.pd', 'feature-flags.yaml');
+      const configPath = path.join(workspaceDir, '.pd', 'config.yaml');
       fs.writeFileSync(configPath, '  bad: [yaml: content', 'utf8');
       const logger = createMockLogger();
       const result = loadFeatureFlagFromWorkspace(workspaceDir, 'evolution_worker', logger);
@@ -152,7 +206,7 @@ describe('PRI-288: EvolutionWorkerService quarantine', () => {
 
     it('returns defaults when file is unreadable', () => {
       // Create a directory where a file should be — causes read error
-      const configPath = path.join(workspaceDir, '.pd', 'feature-flags.yaml');
+      const configPath = path.join(workspaceDir, '.pd', 'config.yaml');
       fs.mkdirSync(configPath, { recursive: true });
       const logger = createMockLogger();
       const result = loadFeatureFlagFromWorkspace(workspaceDir, 'evolution_worker', logger);
@@ -162,7 +216,7 @@ describe('PRI-288: EvolutionWorkerService quarantine', () => {
 
     it('rejects dangerous keys (__proto__) and does not enable via prototype pollution', () => {
       // Write raw YAML with __proto__ to test dangerous key rejection on raw parsed output
-      writeFeatureFlags(workspaceDir, {
+      writeConfigYaml(workspaceDir, {
         __proto__: { enabled: true },
         evolution_worker: { enabled: false },
       });
@@ -175,7 +229,7 @@ describe('PRI-288: EvolutionWorkerService quarantine', () => {
   // ── 3. shouldStartEvolutionWorker — real helper, real output ──
 
   describe('shouldStartEvolutionWorker gate helper', () => {
-    it('returns shouldStart=false by default (no feature-flags.yaml)', () => {
+    it('returns shouldStart=false by default (no config.yaml)', () => {
       const logger = createMockLogger();
       const gate = shouldStartEvolutionWorker(workspaceDir, logger);
       expect(gate.shouldStart).toBe(false);
@@ -184,13 +238,13 @@ describe('PRI-288: EvolutionWorkerService quarantine', () => {
     });
 
     it('returns shouldStart=true when explicitly enabled', () => {
-      writeFeatureFlags(workspaceDir, {
+      writeConfigYaml(workspaceDir, {
         evolution_worker: { enabled: true },
       });
       const logger = createMockLogger();
       const gate = shouldStartEvolutionWorker(workspaceDir, logger);
       expect(gate.shouldStart).toBe(true);
-      expect(gate.flagSource).toBe('workspace_file');
+      expect(gate.flagSource).toBe('user_config');
       expect(gate.disabledInfo).toBeNull();
     });
 
@@ -248,18 +302,18 @@ describe('PRI-288: EvolutionWorkerService quarantine', () => {
 
   describe('explicit enable: worker starts', () => {
     it('shouldStartEvolutionWorker returns true when enabled in config', () => {
-      writeFeatureFlags(workspaceDir, {
+      writeConfigYaml(workspaceDir, {
         evolution_worker: { enabled: true },
       });
 
       const logger = createMockLogger();
       const gate = shouldStartEvolutionWorker(workspaceDir, logger);
       expect(gate.shouldStart).toBe(true);
-      expect(gate.flagSource).toBe('workspace_file');
+      expect(gate.flagSource).toBe('user_config');
     });
 
     it('EvolutionWorkerService.start actually runs when gate is true', () => {
-      writeFeatureFlags(workspaceDir, {
+      writeConfigYaml(workspaceDir, {
         evolution_worker: { enabled: true },
       });
 
@@ -292,17 +346,18 @@ describe('PRI-288: EvolutionWorkerService quarantine', () => {
     });
 
     it('computeEffectiveFlags preserves core flags even with evolution_worker override', () => {
-      writeFeatureFlags(workspaceDir, {
+      writeConfigYaml(workspaceDir, {
         evolution_worker: { enabled: true },
       });
 
-      const configPath = path.join(workspaceDir, '.pd', 'feature-flags.yaml');
+      const configPath = path.join(workspaceDir, '.pd', 'config.yaml');
       const raw = fs.readFileSync(configPath, 'utf8');
       const parsed: unknown = yaml.load(raw, { schema: yaml.JSON_SCHEMA });
 
       // Use isRecord type guard instead of `as`
       expect(isRecord(parsed)).toBe(true);
-      const flags = computeEffectiveFlags(parsed as Record<string, unknown>, DEFAULT_FEATURE_FLAGS, configPath);
+      const features = (parsed as Record<string, unknown>).features;
+      const flags = computeEffectiveFlags(features as Record<string, unknown>, DEFAULT_FEATURE_FLAGS, configPath);
       expect(flags.flags['prompt']?.enabled).toBe(true);
       expect(flags.flags['code_tool_hook']?.enabled).toBe(true);
       expect(flags.flags['defer_archive']?.enabled).toBe(true);
@@ -310,17 +365,18 @@ describe('PRI-288: EvolutionWorkerService quarantine', () => {
     });
 
     it('core flags cannot be disabled by user override', () => {
-      writeFeatureFlags(workspaceDir, {
+      writeConfigYaml(workspaceDir, {
         prompt: { enabled: false },
         code_tool_hook: { enabled: false },
       });
 
-      const configPath = path.join(workspaceDir, '.pd', 'feature-flags.yaml');
+      const configPath = path.join(workspaceDir, '.pd', 'config.yaml');
       const raw = fs.readFileSync(configPath, 'utf8');
       const parsed: unknown = yaml.load(raw, { schema: yaml.JSON_SCHEMA });
 
       expect(isRecord(parsed)).toBe(true);
-      const flags = computeEffectiveFlags(parsed as Record<string, unknown>, DEFAULT_FEATURE_FLAGS, configPath);
+      const features = (parsed as Record<string, unknown>).features;
+      const flags = computeEffectiveFlags(features as Record<string, unknown>, DEFAULT_FEATURE_FLAGS, configPath);
       expect(flags.flags['prompt']?.enabled).toBe(true); // core cannot be disabled
       expect(flags.flags['code_tool_hook']?.enabled).toBe(true); // core cannot be disabled
       expect(flags.warnings.length).toBeGreaterThan(0); // warnings about core override attempt
@@ -331,7 +387,7 @@ describe('PRI-288: EvolutionWorkerService quarantine', () => {
 
   describe('no confirm-first gate regression', () => {
     it('no PLAN.md or confirm-first files are created in workspace', () => {
-      writeFeatureFlags(workspaceDir, {
+      writeConfigYaml(workspaceDir, {
         evolution_worker: { enabled: false },
       });
 

package/tests/evolution-worker-slimming.test.ts

@@ -28,9 +28,63 @@ function createTempWorkspace(): string {
   return dir;
 }
 
-function writeFeatureFlags(workspaceDir: string, flags: Record<string, unknown>): void {
-  const configPath = path.join(workspaceDir, '.pd', 'feature-flags.yaml');
-  const content = yaml.dump(flags, { schema: yaml.JSON_SCHEMA });
+function deepMergeFeatures(
+  defaults: Record<string, unknown>,
+  overrides: Record<string, unknown>,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = { ...defaults };
+  for (const [key, value] of Object.entries(overrides)) {
+    if (
+      value != null &&
+      typeof value === 'object' &&
+      !Array.isArray(value) &&
+      Object.hasOwn(result, key) &&
+      result[key] != null &&
+      typeof result[key] === 'object' &&
+      !Array.isArray(result[key])
+    ) {
+      result[key] = { ...(result[key] as Record<string, unknown>), ...(value as Record<string, unknown>) };
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+function writeConfigYaml(workspaceDir: string, featureOverrides: Record<string, unknown>): void {
+  const configPath = path.join(workspaceDir, '.pd', 'config.yaml');
+  const defaultFeatures: Record<string, unknown> = {
+    prompt: { category: 'core', enabled: true },
+    code_tool_hook: { category: 'core', enabled: true },
+    defer_archive: { category: 'core', enabled: true },
+    correction_observer: { category: 'quiet', enabled: false },
+    empathy_observer: { category: 'quiet', enabled: false },
+    evolution_worker: { category: 'quiet', enabled: false },
+    nocturnal: { category: 'gone', enabled: false },
+  };
+  const config = {
+    version: 1,
+    features: deepMergeFeatures(defaultFeatures, featureOverrides),
+    runtimeProfiles: {
+      'openclaw.default': { type: 'openclaw', source: 'default' },
+    },
+    internalAgents: {
+      defaultRuntime: 'openclaw.default',
+      agents: {
+        diagnostician: { enabled: true },
+        dreamer: { enabled: true },
+        scribe: { enabled: true },
+        artificer: { enabled: true },
+        philosopher: { enabled: false },
+        evaluator: { enabled: false },
+        rolloutReviewer: { enabled: false },
+        trainer: { enabled: false },
+        correctionObserver: { enabled: false },
+        empathyObserver: { enabled: false },
+      },
+    },
+  };
+  const content = yaml.dump(config, { schema: yaml.JSON_SCHEMA });
   fs.writeFileSync(configPath, content, 'utf8');
 }
 
@@ -151,6 +205,9 @@ describe('PRI-294: CorrectionObserver independence from EvolutionWorker', () =>
   });
 
   it('CorrectionObserver starts when EvolutionWorker is disabled (default)', () => {
+    writeConfigYaml(workspaceDir, {
+      correction_observer: { enabled: true },
+    });
     const logger = createMockLogger();
 
     // Verify EvolutionWorker is disabled
@@ -164,8 +221,9 @@ describe('PRI-294: CorrectionObserver independence from EvolutionWorker', () =>
   });
 
   it('CorrectionObserver starts when EvolutionWorker is explicitly enabled', () => {
-    writeFeatureFlags(workspaceDir, {
+    writeConfigYaml(workspaceDir, {
       evolution_worker: { enabled: true },
+      correction_observer: { enabled: true },
     });
     const logger = createMockLogger();
 
@@ -177,7 +235,7 @@ describe('PRI-294: CorrectionObserver independence from EvolutionWorker', () =>
   });
 
   it('CorrectionObserver can be independently disabled', () => {
-    writeFeatureFlags(workspaceDir, {
+    writeConfigYaml(workspaceDir, {
       correction_observer: { enabled: false },
     });
     const logger = createMockLogger();

package/tests/hooks/runtime-v2-prompt-activation.test.ts

@@ -494,9 +494,11 @@ describe('Runtime V2 prompt activation — additional guard tests', () => {
 
   it('malformed DB/config input fails loud with warning', async () => {
     const pdDir = path.join(tempWorkspaceDir, '.pd');
+    // PRI-305/PRI-307: Write a malformed .pd/config.yaml with dangerous keys
+    // The core validator rejects __proto__ and constructor as dangerous keys
     fs.writeFileSync(
-      path.join(pdDir, 'feature-flags.yaml'),
-      '__proto__:\n  enabled: true\nprompt:\n  enabled: true\nconstructor:\n  enabled: false\n',
+      path.join(pdDir, 'config.yaml'),
+      'version: 1\nfeatures:\n  __proto__:\n    category: core\n    enabled: true\n  prompt:\n    category: core\n    enabled: true\n  constructor:\n    category: core\n    enabled: false\nruntimeProfiles:\n  openclaw.default:\n    type: openclaw\n    source: default\ninternalAgents:\n  defaultRuntime: openclaw.default\n  agents:\n    diagnostician:\n      enabled: true\n    dreamer:\n      enabled: true\n    scribe:\n      enabled: true\n    artificer:\n      enabled: true\n    philosopher:\n      enabled: false\n    evaluator:\n      enabled: false\n    rolloutReviewer:\n      enabled: false\n    trainer:\n      enabled: false\n    correctionObserver:\n      enabled: false\n    empathyObserver:\n      enabled: false\n',
       'utf8',
     );
 
@@ -507,10 +509,14 @@ describe('Runtime V2 prompt activation — additional guard tests', () => {
     const result = await reader.readActivatedPrinciples();
 
     const warnCalls = warnSpy.mock.calls.map((c: unknown[]) => String(c[0]));
+    // PRI-305/PRI-307: Core validator rejects dangerous keys as errors.
+    // The plugin config loader logs config errors as warnings.
     const hasDangerousKeyWarning = warnCalls.some(
-      (c: string) => c.includes('dangerous key') || c.includes('__proto__') || c.includes('constructor'),
+      (c: string) => c.includes('dangerous key') || c.includes('__proto__') || c.includes('constructor') || c.includes('Config error'),
     );
     expect(hasDangerousKeyWarning).toBe(true);
+    // With malformed config, defaults are used (prompt enabled by default),
+    // but no DB data exists, so principles should be empty
     expect(result.principles).toEqual([]);
   });
 

package/tests/service/correction-observer-service.test.ts

@@ -2,6 +2,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
+import * as yaml from 'js-yaml';
 import { WorkspaceContext } from '../../src/core/workspace-context.js';
 
 const mockLearner = {
@@ -35,6 +36,89 @@ vi.mock('../../src/service/keyword-optimization-service.js', () => ({
   KeywordOptimizationService: { get: vi.fn(() => mockOptimizationService) },
 }));
 
+// PRI-307: Mock the pd-config-loader instead of @principles/core/runtime-v2
+// The service now reads .pd/config.yaml via resolveObserverConfig
+vi.mock('../../src/core/pd-config-loader.js', () => {
+  return {
+    loadPdConfigForPlugin: vi.fn(() => ({
+      ok: true,
+      effective: {
+        config: {
+          version: 1,
+          features: {
+            prompt: { category: 'core', enabled: true },
+            code_tool_hook: { category: 'core', enabled: true },
+            defer_archive: { category: 'core', enabled: true },
+            correction_observer: { category: 'quiet', enabled: true },
+            empathy_observer: { category: 'quiet', enabled: false },
+          },
+          runtimeProfiles: {
+            'openclaw.default': { type: 'openclaw', source: 'default' },
+            'pd.anthropic-sonnet': { type: 'pi-ai', provider: 'anthropic', model: 'claude-3-5-sonnet', apiKeyEnv: 'ANTHROPIC_API_KEY', timeoutMs: 30000 },
+          },
+          internalAgents: {
+            defaultRuntime: 'openclaw.default',
+            agents: {
+              diagnostician: { enabled: true },
+              dreamer: { enabled: true },
+              scribe: { enabled: true },
+              artificer: { enabled: true },
+              philosopher: { enabled: false },
+              evaluator: { enabled: false },
+              rolloutReviewer: { enabled: false },
+              trainer: { enabled: false },
+              correctionObserver: { enabled: true, runtimeProfile: 'pd.anthropic-sonnet' },
+              empathyObserver: { enabled: false },
+            },
+          },
+        },
+        warnings: [],
+      },
+      source: 'defaults',
+      configPath: '.pd/config.yaml',
+      warnings: [],
+      errors: [],
+    })),
+    loadFeatureFlagFromConfig: vi.fn(() => ({ enabled: true, source: 'defaults' })),
+    resolveObserverConfig: vi.fn((_workspaceDir: string, flagId: string, _agentName: string) => {
+      // Default: return disabled for correction_observer (no config file in test tmp dirs)
+      if (flagId === 'correction_observer') {
+        return {
+          enabled: true,
+          readiness: 'not_ready',
+          source: 'defaults',
+          reason: 'pi-ai profile configured with apiKeyEnv',
+          nextAction: 'Run pd runtime probe',
+          runtimeProfileId: 'pd.anthropic-sonnet',
+          runtimeProfileType: 'pi-ai',
+          apiKeyEnv: 'ANTHROPIC_API_KEY',
+          apiKeyPresent: !!process.env.ANTHROPIC_API_KEY,
+          provider: 'anthropic',
+          model: 'claude-3-5-sonnet',
+          timeoutMs: 30000,
+          baseUrl: null,
+        };
+      }
+      return {
+        enabled: false,
+        readiness: 'disabled',
+        source: 'defaults',
+        reason: `${flagId} is disabled`,
+        nextAction: `Set features.${flagId}.enabled=true in .pd/config.yaml`,
+        runtimeProfileId: null,
+        runtimeProfileType: null,
+        apiKeyEnv: null,
+        apiKeyPresent: false,
+        provider: null,
+        model: null,
+        timeoutMs: null,
+        baseUrl: null,
+      };
+    }),
+    getPdConfigPath: vi.fn((workspaceDir: string) => path.join(workspaceDir, '.pd', 'config.yaml')),
+  };
+});
+
 const mockDispatch = vi.fn().mockResolvedValue({
   updated: true,
   summary: 'Keyword store optimized',
@@ -45,23 +129,12 @@ const mockRegister = vi.fn();
 
 vi.mock('@principles/core/runtime-v2', () => {
   return {
-    WorkflowFunnelLoader: class {
-      getFunnel = vi.fn(() => ({
-        policy: {
-          runtimeKind: 'pi-ai',
-          provider: 'anthropic',
-          model: 'anthropic/claude-3-5-sonnet',
-          apiKeyEnv: 'ANTHROPIC_API_KEY',
-          timeoutMs: 30000,
-        }
-      }));
-    },
     PiAiRuntimeAdapter: class {},
     CorrectionObserver: class {},
     AgentScheduler: class {
       register = mockRegister;
       dispatch = mockDispatch;
-    }
+    },
   };
 });
 
@@ -330,12 +403,12 @@ describe('runCorrectionObserverCycle — Independent Execution', () => {
   });
 });
 
-describe('resolveCorrectionObserver — Configuration Resolution', () => {
+describe('resolveCorrectionObserver — Configuration Resolution (PRI-307)', () => {
   beforeEach(() => {
     vi.clearAllMocks();
   });
 
-  it('returns observer when API key env is set with mocked policy', async () => {
+  it('returns observer when API key env is set with pi-ai profile', async () => {
     const workspaceDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-corr-resolve-'));
     const stateDir = path.join(workspaceDir, '.state');
     fs.mkdirSync(stateDir, { recursive: true });
@@ -348,7 +421,7 @@ describe('resolveCorrectionObserver — Configuration Resolution', () => {
       const wctx = WorkspaceContext.fromHookContext({ workspaceDir });
       const result = resolveCorrectionObserver(wctx, logger as any);
 
-      // With mocked WorkflowFunnelLoader returning valid policy, should return observer
+      // With mocked resolveObserverConfig returning enabled + not_ready, should return observer
       expect(result).not.toBeNull();
     } finally {
       delete process.env.ANTHROPIC_API_KEY;
@@ -356,23 +429,76 @@ describe('resolveCorrectionObserver — Configuration Resolution', () => {
     }
   });
 
-  it('returns observer when workflows.yaml provides valid policy', async () => {
-    const workspaceDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-corr-policy-'));
+  it('returns null when observer is disabled in config', async () => {
+    const workspaceDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-corr-disabled-'));
     const stateDir = path.join(workspaceDir, '.state');
     fs.mkdirSync(stateDir, { recursive: true });
 
-    process.env.ANTHROPIC_API_KEY = 'test-key';
+    const logger = { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() };
+
+    // Override the mock to return disabled
+    const { resolveObserverConfig } = await import('../../src/core/pd-config-loader.js');
+    vi.mocked(resolveObserverConfig).mockReturnValueOnce({
+      enabled: false,
+      readiness: 'disabled',
+      source: 'defaults',
+      reason: 'correction_observer is disabled in .pd/config.yaml',
+      nextAction: 'Set features.correction_observer.enabled=true in .pd/config.yaml to enable',
+      runtimeProfileId: null,
+      runtimeProfileType: null,
+      apiKeyEnv: null,
+      apiKeyPresent: false,
+      provider: null,
+      model: null,
+      timeoutMs: null,
+      baseUrl: null,
+    });
+
+    try {
+      const wctx = WorkspaceContext.fromHookContext({ workspaceDir });
+      const result = resolveCorrectionObserver(wctx, logger as any);
+
+      expect(result).toBeNull();
+    } finally {
+      safeRmDir(workspaceDir);
+    }
+  });
+
+  it('returns null when observer needs setup (no API key)', async () => {
+    const workspaceDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-corr-needs-setup-'));
+    const stateDir = path.join(workspaceDir, '.state');
+    fs.mkdirSync(stateDir, { recursive: true });
 
     const logger = { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() };
 
+    // Override the mock to return needs_setup
+    const { resolveObserverConfig } = await import('../../src/core/pd-config-loader.js');
+    vi.mocked(resolveObserverConfig).mockReturnValueOnce({
+      enabled: true,
+      readiness: 'needs_setup',
+      source: 'defaults',
+      reason: "Environment variable 'ANTHROPIC_API_KEY' is not set or empty",
+      nextAction: 'Set the environment variable ANTHROPIC_API_KEY with a valid API key',
+      runtimeProfileId: 'pd.anthropic-sonnet',
+      runtimeProfileType: 'pi-ai',
+      apiKeyEnv: 'ANTHROPIC_API_KEY',
+      apiKeyPresent: false,
+      provider: 'anthropic',
+      model: 'claude-3-5-sonnet',
+      timeoutMs: 30000,
+      baseUrl: null,
+    });
+
     try {
       const wctx = WorkspaceContext.fromHookContext({ workspaceDir });
       const result = resolveCorrectionObserver(wctx, logger as any);
 
-      // With mocked WorkflowFunnelLoader returning valid policy, should return observer
-      expect(result).not.toBeNull();
+      expect(result).toBeNull();
+      // Should log the needs_setup reason, not noisy "no API key" cycling
+      expect(logger.info).toHaveBeenCalledWith(
+        expect.stringContaining('ANTHROPIC_API_KEY')
+      );
     } finally {
-      delete process.env.ANTHROPIC_API_KEY;
       safeRmDir(workspaceDir);
     }
   });

package/tests/service/evolution-worker.correction-observer.test.ts

@@ -14,7 +14,7 @@ describe('Correction Observer Ownership — Feature Flag & Surface Registry Cons
     const result = computeEffectiveFlags(
       { correction_observer: { enabled: false } },
       DEFAULT_FEATURE_FLAGS,
-      '.pd/feature-flags.yaml',
+      '.pd/config.yaml',
     );
     expect(result.flags['correction_observer'].enabled).toBe(false);
     expect(result.warnings).not.toContain(expect.stringContaining('core flag cannot be disabled'));