create-principles-disciple 1.80.0 → 1.82.0

package/plugin/dist/core/event-log.js

@@ -2,6 +2,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { createEmptyDailyStats } from '../types/event-types.js';
 import { atomicWriteFileSync } from '../utils/io.js';
+import { redactTelemetryString } from '@principles/core/runtime-v2';
 const EVENT_LOG_RETENTION_DAYS = 7;
 export class EventLog {
     logsDir;
@@ -142,16 +143,99 @@ export class EventLog {
     recordRuntimeV2ActivationsInjected(data) {
         this.record('runtime_v2_prompt_activations_injected', 'injected', data.sessionId, data);
     }
+    /**
+     * Redact telemetry-sensitive string values in event data before persistence.
+     * Applies redactTelemetryString to known high-risk fields (filePath, command,
+     * reason, args, new_string, old_string, text, paramsSummary values) and to all
+     * string values in tool_call/rulehost_* data as a safety net.
+     *
+     * ERR-002: never throws; returns data unchanged on error.
+     * ERR-045/046: covers composite command strings, Authorization headers, env vars.
+     */
+    redactEventData(type, data) {
+        try {
+            // Known high-risk event types — telemetry that carries tool commands / paths
+            const telemetryTypes = new Set([
+                'tool_call',
+                'rulehost_evaluated',
+                'rulehost_blocked',
+                'rulehost_requireApproval',
+                'rulehost_auto_correct_proposed',
+                'rulehost_auto_correct_applied',
+                'rule_enforced',
+                'hook_execution',
+                'gate_block',
+                'gate_bypass',
+            ]);
+            if (!telemetryTypes.has(type))
+                return data;
+            const redacted = {};
+            for (const [key, value] of Object.entries(data)) {
+                if (typeof value === 'string') {
+                    redacted[key] = redactTelemetryString(value);
+                }
+                else if (Array.isArray(value)) {
+                    // Recurse into arrays (e.g. correctedFields with original/applied)
+                    redacted[key] = value.map((item) => {
+                        if (typeof item === 'string') {
+                            return redactTelemetryString(item);
+                        }
+                        if (typeof item === 'object' && item !== null) {
+                            const nested = {};
+                            for (const [nk, nv] of Object.entries(item)) {
+                                nested[nk] = typeof nv === 'string' ? redactTelemetryString(nv) : nv;
+                            }
+                            return nested;
+                        }
+                        return item;
+                    });
+                }
+                else if (typeof value === 'object' && value !== null) {
+                    // Recurse one level for nested objects (e.g. paramsSummary)
+                    const nested = {};
+                    for (const [nk, nv] of Object.entries(value)) {
+                        if (typeof nv === 'string') {
+                            nested[nk] = redactTelemetryString(nv);
+                        }
+                        else {
+                            nested[nk] = nv;
+                        }
+                    }
+                    redacted[key] = nested;
+                }
+                else {
+                    redacted[key] = value;
+                }
+            }
+            return redacted;
+        }
+        catch (e) {
+            // ERR-002: fail safe — never write raw payload on redaction failure.
+            // Return a masked payload with context so downstream knows what happened.
+            const errStr = e instanceof Error ? e.message.slice(0, 200) : String(e).slice(0, 200);
+            const masked = {
+                redactionFailure: true,
+                redactionStatus: 'failed',
+                'redaction.status': 'failed',
+                redactionReason: errStr || 'unknown error',
+                redactionDataDropped: true,
+                originalType: type,
+                originalSessionId: data.sessionId ?? null,
+            };
+            return masked;
+        }
+    }
     record(type, category, sessionId, data) {
         const now = new Date();
         const date = this.formatDate(now);
+        const redactedData = this.redactEventData(type, data);
         const entry = {
             ts: now.toISOString(),
             date,
             type,
             category,
             sessionId,
-            data: data,
+            data: redactedData,
         };
         this.eventBuffer.push(entry);
         this.updateStats(entry);

package/plugin/dist/core/pd-config-loader.d.ts

@@ -0,0 +1,96 @@
+/**
+ * PD Config Loader (Plugin I/O boundary) — PRI-307
+ *
+ * Reads `.pd/config.yaml`, validates via core, computes effective config.
+ * Replaces the old `.pd/feature-flags.yaml` and `.state/workflows.yaml` reading
+ * for plugin production paths.
+ *
+ * ADR-0016: PD owns exactly one user config file.
+ * - Missing config → defaults with nextAction
+ * - Malformed config → fail loud with errors and nextAction
+ * - No secrets in output
+ * - Observer disabled → no start / no noisy log cycling
+ * - Observer enabled + missing setup → structured needs_setup + nextAction
+ */
+import type { EffectivePdConfig } from '@principles/core/runtime-v2';
+export declare const PD_CONFIG_DIR = ".pd";
+export declare const PD_CONFIG_FILENAME = "config.yaml";
+export type ObserverReadiness = 'disabled' | 'needs_setup' | 'ready' | 'not_ready' | 'config_malformed';
+export interface ObserverConfigResult {
+    /** Whether the observer feature is enabled in config */
+    enabled: boolean;
+    /** Observer readiness state */
+    readiness: ObserverReadiness;
+    /** Config source: 'defaults' | 'user_config' | 'malformed' */
+    source: string;
+    /** Reason for current state */
+    reason: string;
+    /** What the user should do next */
+    nextAction: string;
+    /** The runtime profile ID for this observer, if configured */
+    runtimeProfileId: string | null;
+    /** The runtime profile type, if configured */
+    runtimeProfileType: string | null;
+    /** The apiKeyEnv for the runtime profile, if applicable */
+    apiKeyEnv: string | null;
+    /** Whether the apiKeyEnv is present in process.env */
+    apiKeyPresent: boolean;
+    /** Provider name from runtime profile */
+    provider: string | null;
+    /** Model name from runtime profile */
+    model: string | null;
+    /** Timeout from runtime profile */
+    timeoutMs: number | null;
+    /** Base URL from runtime profile */
+    baseUrl: string | null;
+    /** Config validation errors (only present when readiness=config_malformed) */
+    configErrors?: Array<{
+        path: string;
+        reason: string;
+        nextAction: string;
+    }>;
+}
+export interface PluginConfigLoadResult {
+    ok: boolean;
+    effective: EffectivePdConfig;
+    source: 'defaults' | 'user_config' | 'malformed';
+    configPath: string;
+    warnings: string[];
+    errors: Array<{
+        path: string;
+        reason: string;
+        nextAction: string;
+    }>;
+}
+export declare function getPdConfigPath(workspaceDir: string): string;
+/**
+ * Load and validate `.pd/config.yaml` from the workspace.
+ * Never throws on malformed input. Always provides a usable fallback.
+ */
+export declare function loadPdConfigForPlugin(workspaceDir: string): PluginConfigLoadResult;
+/**
+ * Get a single feature flag's enabled state from .pd/config.yaml.
+ * Replaces the old `loadFeatureFlagFromWorkspace` which read .pd/feature-flags.yaml.
+ */
+export declare function loadFeatureFlagFromConfig(workspaceDir: string, flagId: string, logger?: {
+    warn?: (msg: string) => void;
+    info?: (msg: string) => void;
+}): {
+    enabled: boolean;
+    source: string;
+};
+/**
+ * Resolve observer configuration from .pd/config.yaml.
+ *
+ * Returns structured state:
+ * - config_malformed: config file is invalid — no guessing, fail loud
+ * - disabled: observer feature flag is off OR agent.enabled=false → no start, no noisy logs
+ * - needs_setup: observer enabled but runtime profile missing, API key not set, or unsupported profile type
+ * - ready: observer enabled and fully configured (pi-ai with key present)
+ * - not_ready: observer enabled, API key present, but runtime availability unknown
+ */
+export declare function resolveObserverConfig(workspaceDir: string, observerFlagId: string, observerAgentName: string, _logger?: {
+    warn?: (msg: string) => void;
+    info?: (msg: string) => void;
+    debug?: (msg: string) => void;
+}): ObserverConfigResult;

package/plugin/dist/core/pd-config-loader.js

@@ -0,0 +1,307 @@
+/**
+ * PD Config Loader (Plugin I/O boundary) — PRI-307
+ *
+ * Reads `.pd/config.yaml`, validates via core, computes effective config.
+ * Replaces the old `.pd/feature-flags.yaml` and `.state/workflows.yaml` reading
+ * for plugin production paths.
+ *
+ * ADR-0016: PD owns exactly one user config file.
+ * - Missing config → defaults with nextAction
+ * - Malformed config → fail loud with errors and nextAction
+ * - No secrets in output
+ * - Observer disabled → no start / no noisy log cycling
+ * - Observer enabled + missing setup → structured needs_setup + nextAction
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import yaml from 'js-yaml';
+import { validatePdConfig, computeEffectivePdConfig, computeFeatureFlagsFromConfig, INTERNAL_AGENT_NAMES, } from '@principles/core/runtime-v2';
+// ── Constants ────────────────────────────────────────────────────────────────
+export const PD_CONFIG_DIR = '.pd';
+export const PD_CONFIG_FILENAME = 'config.yaml';
+// ── Config Path ──────────────────────────────────────────────────────────────
+export function getPdConfigPath(workspaceDir) {
+    return path.join(workspaceDir, PD_CONFIG_DIR, PD_CONFIG_FILENAME);
+}
+// ── Load PD Config ───────────────────────────────────────────────────────────
+/**
+ * Load and validate `.pd/config.yaml` from the workspace.
+ * Never throws on malformed input. Always provides a usable fallback.
+ */
+export function loadPdConfigForPlugin(workspaceDir) {
+    const configPath = getPdConfigPath(workspaceDir);
+    // 1) Config file missing → use defaults
+    if (!fs.existsSync(configPath)) {
+        const effective = computeEffectivePdConfig(null);
+        return {
+            ok: true,
+            effective,
+            source: 'defaults',
+            configPath,
+            warnings: effective.warnings,
+            errors: [],
+        };
+    }
+    // 2) Read the file
+    let raw;
+    try {
+        raw = fs.readFileSync(configPath, 'utf8');
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const effective = computeEffectivePdConfig(null);
+        return {
+            ok: false,
+            effective,
+            source: 'malformed',
+            configPath,
+            warnings: [],
+            errors: [{ path: '', reason: `Failed to read .pd/config.yaml: ${message}`, nextAction: 'Check file permissions for .pd/config.yaml' }],
+        };
+    }
+    // 3) Parse YAML — treat as unknown (ERR-001)
+    let parsed;
+    try {
+        parsed = yaml.load(raw, { schema: yaml.JSON_SCHEMA });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const effective = computeEffectivePdConfig(null);
+        return {
+            ok: false,
+            effective,
+            source: 'malformed',
+            configPath,
+            warnings: [],
+            errors: [{ path: '', reason: `YAML parse error in .pd/config.yaml: ${message}`, nextAction: 'Fix YAML syntax in .pd/config.yaml' }],
+        };
+    }
+    // 4) Validate via core (ERR-001, ERR-005: no `as` bypasses)
+    const validationResult = validatePdConfig(parsed);
+    if (!validationResult.ok) {
+        const effective = computeEffectivePdConfig(null);
+        return {
+            ok: false,
+            effective,
+            source: 'malformed',
+            configPath,
+            warnings: [],
+            errors: validationResult.errors.map(e => ({
+                path: e.path,
+                reason: e.reason,
+                nextAction: e.nextAction,
+            })),
+        };
+    }
+    // 5) Compute effective config
+    const effective = computeEffectivePdConfig(validationResult.value);
+    return {
+        ok: true,
+        effective,
+        source: 'user_config',
+        configPath,
+        warnings: effective.warnings,
+        errors: [],
+    };
+}
+// ── Feature Flag from Config ─────────────────────────────────────────────────
+/**
+ * Get a single feature flag's enabled state from .pd/config.yaml.
+ * Replaces the old `loadFeatureFlagFromWorkspace` which read .pd/feature-flags.yaml.
+ */
+export function loadFeatureFlagFromConfig(workspaceDir, flagId, logger) {
+    const result = loadPdConfigForPlugin(workspaceDir);
+    const flags = computeFeatureFlagsFromConfig(result.effective);
+    const flag = flags.flags[flagId];
+    if (!result.ok) {
+        logger?.warn?.(`[PD:Config] Config validation failed: ${result.errors.map(e => e.reason).join('; ')} — using defaults`);
+    }
+    return {
+        enabled: flag?.enabled ?? false,
+        source: result.source,
+    };
+}
+// ── Observer Config Resolution ───────────────────────────────────────────────
+/**
+ * Resolve observer configuration from .pd/config.yaml.
+ *
+ * Returns structured state:
+ * - config_malformed: config file is invalid — no guessing, fail loud
+ * - disabled: observer feature flag is off OR agent.enabled=false → no start, no noisy logs
+ * - needs_setup: observer enabled but runtime profile missing, API key not set, or unsupported profile type
+ * - ready: observer enabled and fully configured (pi-ai with key present)
+ * - not_ready: observer enabled, API key present, but runtime availability unknown
+ */
+export function resolveObserverConfig(workspaceDir, observerFlagId, observerAgentName, _logger) {
+    const result = loadPdConfigForPlugin(workspaceDir);
+    // 0) Malformed config → fail loud, do NOT swallow as "disabled"
+    if (!result.ok) {
+        return {
+            enabled: false,
+            readiness: 'config_malformed',
+            source: 'malformed',
+            reason: `Config validation failed: ${result.errors.map(e => e.reason).join('; ')}`,
+            nextAction: result.errors[0]?.nextAction ?? 'Fix .pd/config.yaml and retry',
+            runtimeProfileId: null,
+            runtimeProfileType: null,
+            apiKeyEnv: null,
+            apiKeyPresent: false,
+            provider: null,
+            model: null,
+            timeoutMs: null,
+            baseUrl: null,
+            configErrors: result.errors,
+        };
+    }
+    const config = result.effective.config;
+    // 1) Check if the observer feature flag is enabled
+    const featureFlag = config.features[observerFlagId];
+    if (!featureFlag || !featureFlag.enabled) {
+        return {
+            enabled: false,
+            readiness: 'disabled',
+            source: result.source,
+            reason: `${observerFlagId} is disabled in .pd/config.yaml`,
+            nextAction: `Set features.${observerFlagId}.enabled=true in .pd/config.yaml to enable`,
+            runtimeProfileId: null,
+            runtimeProfileType: null,
+            apiKeyEnv: null,
+            apiKeyPresent: false,
+            provider: null,
+            model: null,
+            timeoutMs: null,
+            baseUrl: null,
+        };
+    }
+    // 2) Check if the agent itself is enabled (feature flag ≠ agent.enabled)
+    const knownNames = INTERNAL_AGENT_NAMES;
+    if (!knownNames.includes(observerAgentName)) {
+        return {
+            enabled: false,
+            readiness: 'needs_setup',
+            source: result.source,
+            reason: `Unknown agent name '${observerAgentName}'`,
+            nextAction: `Use one of the known agent names: ${INTERNAL_AGENT_NAMES.join(', ')}`,
+            runtimeProfileId: null,
+            runtimeProfileType: null,
+            apiKeyEnv: null,
+            apiKeyPresent: false,
+            provider: null,
+            model: null,
+            timeoutMs: null,
+            baseUrl: null,
+        };
+    }
+    const agentKey = observerAgentName;
+    const agentConfig = config.internalAgents.agents[agentKey];
+    // Feature flag on but agent.enabled=false → disabled (not enabled)
+    if (!agentConfig || !agentConfig.enabled) {
+        return {
+            enabled: false,
+            readiness: 'disabled',
+            source: result.source,
+            reason: `${observerFlagId} feature flag is enabled but internalAgents.agents.${observerAgentName}.enabled is false`,
+            nextAction: `Set internalAgents.agents.${observerAgentName}.enabled=true in .pd/config.yaml, or disable features.${observerFlagId}`,
+            runtimeProfileId: null,
+            runtimeProfileType: null,
+            apiKeyEnv: null,
+            apiKeyPresent: false,
+            provider: null,
+            model: null,
+            timeoutMs: null,
+            baseUrl: null,
+        };
+    }
+    // 3) Find the agent's runtime profile
+    const runtimeProfileId = agentConfig.runtimeProfile ?? config.internalAgents.defaultRuntime;
+    const profile = config.runtimeProfiles[runtimeProfileId];
+    if (!profile) {
+        return {
+            enabled: true,
+            readiness: 'needs_setup',
+            source: result.source,
+            reason: `Runtime profile '${runtimeProfileId}' not found in .pd/config.yaml`,
+            nextAction: `Add runtime profile '${runtimeProfileId}' to .pd/config.yaml runtimeProfiles`,
+            runtimeProfileId,
+            runtimeProfileType: null,
+            apiKeyEnv: null,
+            apiKeyPresent: false,
+            provider: null,
+            model: null,
+            timeoutMs: null,
+            baseUrl: null,
+        };
+    }
+    // 4) For pi-ai profiles, check API key
+    if (profile.type === 'pi-ai') {
+        const apiKeyEnv = profile.apiKeyEnv ?? null;
+        const apiKeyPresent = !!apiKeyEnv && Object.prototype.hasOwnProperty.call(process.env, apiKeyEnv) && !!process.env[apiKeyEnv];
+        if (!apiKeyEnv) {
+            return {
+                enabled: true,
+                readiness: 'needs_setup',
+                source: result.source,
+                reason: `pi-ai profile '${runtimeProfileId}' missing apiKeyEnv`,
+                nextAction: `Add apiKeyEnv to runtime profile '${runtimeProfileId}' in .pd/config.yaml`,
+                runtimeProfileId,
+                runtimeProfileType: profile.type,
+                apiKeyEnv: null,
+                apiKeyPresent: false,
+                provider: profile.provider ?? null,
+                model: profile.model ?? null,
+                timeoutMs: profile.timeoutMs ?? null,
+                baseUrl: profile.baseUrl ?? null,
+            };
+        }
+        if (!apiKeyPresent) {
+            return {
+                enabled: true,
+                readiness: 'needs_setup',
+                source: result.source,
+                reason: `Environment variable '${apiKeyEnv}' is not set or empty`,
+                nextAction: `Set the environment variable '${apiKeyEnv}' with a valid API key`,
+                runtimeProfileId,
+                runtimeProfileType: profile.type,
+                apiKeyEnv,
+                apiKeyPresent: false,
+                provider: profile.provider ?? null,
+                model: profile.model ?? null,
+                timeoutMs: profile.timeoutMs ?? null,
+                baseUrl: profile.baseUrl ?? null,
+            };
+        }
+        // pi-ai with key present — runtime availability unknown without actual probe
+        return {
+            enabled: true,
+            readiness: 'not_ready',
+            source: result.source,
+            reason: `pi-ai profile configured with apiKeyEnv='${apiKeyEnv}' (key present); runtime availability unknown`,
+            nextAction: 'Run pd runtime probe to verify end-to-end connectivity',
+            runtimeProfileId,
+            runtimeProfileType: profile.type,
+            apiKeyEnv,
+            apiKeyPresent: true,
+            provider: profile.provider ?? null,
+            model: profile.model ?? null,
+            timeoutMs: profile.timeoutMs ?? null,
+            baseUrl: profile.baseUrl ?? null,
+        };
+    }
+    // 5) OpenClaw profile — CorrectionObserver does NOT support OpenClaw runtime
+    //    Mark as needs_setup with nextAction to configure a pi-ai profile
+    return {
+        enabled: true,
+        readiness: 'needs_setup',
+        source: result.source,
+        reason: `OpenClaw profile '${runtimeProfileId}' is not supported for observer runtime. Observers require a pi-ai profile with an API key.`,
+        nextAction: `Configure a pi-ai runtime profile for ${observerAgentName} in .pd/config.yaml (e.g., add a pi-ai profile with provider, model, and apiKeyEnv)`,
+        runtimeProfileId,
+        runtimeProfileType: profile.type,
+        apiKeyEnv: null,
+        apiKeyPresent: false,
+        provider: profile.provider ?? null,
+        model: profile.model ?? null,
+        timeoutMs: null,
+        baseUrl: null,
+    };
+}

package/plugin/dist/core/runtime-v2-prompt-activation-reader.d.ts

@@ -14,5 +14,9 @@ export declare class PromptActivationReader {
     constructor(workspaceDir: string, deps?: PromptActivationReaderDeps);
     readActivatedPrinciples(): Promise<PromptActivationReaderResult>;
     private queryArtifactRow;
+    /**
+     * PRI-305/PRI-307: Load feature flags from .pd/config.yaml instead of .pd/feature-flags.yaml.
+     * Uses the shared plugin config loader for consistency.
+     */
     private loadFeatureFlags;
 }

package/plugin/dist/core/runtime-v2-prompt-activation-reader.js

@@ -1,12 +1,6 @@
-import * as path from 'path';
-import * as fs from 'fs';
-import * as yaml from 'js-yaml';
-import { SqliteConnection, SqliteActivationStateStore, computeEffectiveFlags, DEFAULT_FEATURE_FLAGS, filterPromptActivations, resolvePrincipleFromArtifact } from '@principles/core/runtime-v2';
+import { SqliteConnection, SqliteActivationStateStore, computeFeatureFlagsFromConfig, filterPromptActivations, resolvePrincipleFromArtifact } from '@principles/core/runtime-v2';
+import { loadPdConfigForPlugin } from './pd-config-loader.js';
 export { RUNTIME_V2_PRINCIPLE_BUDGET } from '@principles/core/runtime-v2';
-const DANGEROUS_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
-function isRecord(value) {
-    return value !== null && typeof value === 'object' && !Array.isArray(value);
-}
 export class PromptActivationReader {
     workspaceDir;
     deps;
@@ -88,56 +82,18 @@ export class PromptActivationReader {
             throw new Error(`artifact_query_failed: artifactId=${artifactId} reason=${msg}; nextAction=check_pi_artifacts_table`);
         }
     }
+    /**
+     * PRI-305/PRI-307: Load feature flags from .pd/config.yaml instead of .pd/feature-flags.yaml.
+     * Uses the shared plugin config loader for consistency.
+     */
     loadFeatureFlags() {
-        const configPath = path.join(this.workspaceDir, '.pd', 'feature-flags.yaml');
-        if (!fs.existsSync(configPath)) {
-            return computeEffectiveFlags({}, DEFAULT_FEATURE_FLAGS, configPath);
-        }
-        let raw;
-        try {
-            raw = fs.readFileSync(configPath, 'utf8');
-        }
-        catch (e) {
-            const msg = e instanceof Error ? e.message : String(e);
-            this.deps.logger?.warn?.(`[PD:RuntimeV2] Feature flags unreadable: ${msg} — using defaults`);
-            return computeEffectiveFlags({}, DEFAULT_FEATURE_FLAGS, configPath);
-        }
-        let parsed;
-        try {
-            parsed = yaml.load(raw, { schema: yaml.JSON_SCHEMA });
-        }
-        catch {
-            this.deps.logger?.warn?.(`[PD:RuntimeV2] Feature flags YAML parse error — using defaults`);
-            return {
-                ...computeEffectiveFlags({}, DEFAULT_FEATURE_FLAGS, configPath),
-                warnings: ['feature-flags.yaml: YAML parse error, using defaults'],
-            };
-        }
-        if (!isRecord(parsed)) {
-            this.deps.logger?.warn?.(`[PD:RuntimeV2] Feature flags not a mapping — using defaults`);
-            return {
-                ...computeEffectiveFlags({}, DEFAULT_FEATURE_FLAGS, configPath),
-                warnings: ['feature-flags.yaml: expected a mapping, using defaults'],
-            };
-        }
-        const parsedRecord = Object.create(null);
-        const yamlWarnings = [];
-        for (const key of Object.keys(parsed)) {
-            if (DANGEROUS_KEYS.has(key)) {
-                yamlWarnings.push(`feature-flags.yaml: dangerous key '${key}' rejected`);
-                continue;
-            }
-            if (Object.hasOwn(parsed, key)) {
-                parsedRecord[key] = parsed[key];
-            }
-        }
-        const result = computeEffectiveFlags(parsedRecord, DEFAULT_FEATURE_FLAGS, configPath);
-        if (yamlWarnings.length > 0) {
-            result.warnings = [...yamlWarnings, ...result.warnings];
-            for (const w of yamlWarnings) {
-                this.deps.logger?.warn?.(`[PD:RuntimeV2] ${w}`);
+        const result = loadPdConfigForPlugin(this.workspaceDir);
+        const flags = computeFeatureFlagsFromConfig(result.effective);
+        if (!result.ok) {
+            for (const err of result.errors) {
+                this.deps.logger?.warn?.(`[PD:RuntimeV2] Config error at ${err.path}: ${err.reason}`);
             }
         }
-        return result;
+        return flags;
     }
 }

package/plugin/dist/core/surface-guard.d.ts

@@ -7,6 +7,16 @@ export interface SurfaceGuardResult {
     violations: string[];
     warnings: string[];
 }
+type LoggerLike = {
+    info?: (msg: string) => void;
+    debug?: (msg: string) => void;
+};
+/**
+ * Reset the per-process surface-guard skip log bookkeeping. Intended for tests
+ * that need to assert on the first-fire log without cross-test pollution.
+ * Not part of the production API surface; do not call from runtime code.
+ */
+export declare function __resetSurfaceGuardSkipLogStateForTests(): void;
 export declare function checkSurfaceGuard(): SurfaceGuardResult;
 export declare function getSurfaceIdForHook(hookEvent: string, label?: string): string;
 export declare function getSurfaceIdForService(serviceName: string): string;
@@ -15,13 +25,7 @@ export declare function isSurfaceEnabled(surfaceId: string, overrides?: Record<s
     reason?: string;
 };
 export type HookHandler<E, C, R> = (event: E, ctx: C) => R | Promise<R>;
-export declare function guardHook<E, C, R>(surfaceId: string, logger: {
-    info?: (msg: string) => void;
-    debug?: (msg: string) => void;
-} | undefined, handler: HookHandler<E, C, R>): HookHandler<E, C, R>;
-export declare function guardService<T extends OpenClawPluginService>(surfaceId: string, service: T, logger?: {
-    info?: (msg: string) => void;
-    debug?: (msg: string) => void;
-}): T | null;
+export declare function guardHook<E, C, R>(surfaceId: string, logger: LoggerLike | undefined, handler: HookHandler<E, C, R>): HookHandler<E, C, R>;
+export declare function guardService<T extends OpenClawPluginService>(surfaceId: string, service: T, logger?: LoggerLike): T | null;
 export { PLUGIN_SURFACE_REGISTRY, validateSurfaceRegistry, getSurfacesByCategory };
 export type { PluginSurfaceEntry, MvpCategory };