principles-disciple 1.109.0 → 1.110.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.109.0",
+  "version": "1.110.0",
   "activation": {
     "onCapabilities": [
       "hook"

package/package.json

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

package/src/hooks/after-tool-call-helpers.ts

@@ -25,7 +25,8 @@ import { recordEvolutionSuccess, recordEvolutionFailure } from '../core/evolutio
 import type { PluginHookAfterToolCallEvent } from '../openclaw-sdk.js';
 import { isCooldownActive as isTriggerCooldownActive, markEpisodeAsDiagnosed, clearCooldownState } from './trigger-cooldown-tracker.js';
 import { sanitizeForEvidence, sanitizeToolParamsForEvidence } from './message-sanitize.js';
-import { resolveSourceKindFromToolFailure, evaluateEvidenceTriage } from './triage-adapter.js';
+import { resolveSourceKind, buildToolFailureObservation, type RawObservation } from './raw-observation-adapter.js';
+import { evaluateEvidenceTriage } from './triage-adapter.js';
 import { evaluateTriggerController } from '@principles/core/runtime-v2';
 import { buildTrajectoryEvidence } from './trajectory-evidence.js';
 import type { ToolCallOutcome, ToolCallObservation, PainAdmissionDecision } from './after-tool-call-types.js';
@@ -55,10 +56,19 @@ export function classifyToolCallOutcome(event: PluginHookAfterToolCallEvent): To
     : 0;
   const isFailure = !!event.error || exitCode !== 0;
 
+  // PRI-360 S1: Use centralized builder for tool failure classification
+  // All dispatch/tool_failure rules live in raw-observation-adapter.ts
+  const obs = buildToolFailureObservation({
+    toolName: event.toolName,
+    error: event.error,
+    exitCode,
+  });
+  const failureSource = isFailure ? obs.failureSource : undefined;
+
   return {
     isFailure,
     exitCode,
-    failureSource: isFailure ? classifyToolFailureSource(event.toolName, event.error) : undefined,
+    failureSource,
   };
 }
 
@@ -372,8 +382,23 @@ export function evaluatePainAdmissionForToolCall(
     TRIGGER_COOLDOWN_MAP,
   );
 
+  // PRI-360 S1: Build RawObservation for unified source mapping
+  const rawObs: RawObservation = {
+    observedAt: new Date().toISOString(),
+    workspaceId: workspaceDir,
+    sessionId,
+    toolName: event.toolName,
+    failureSource: outcome.failureSource,
+    // Infer toolNotFound from failureSource for resolveSourceKind compatibility
+    toolNotFound: outcome.failureSource === 'dispatch_error',
+    // Extract exit code from outcome for triage (nonZeroExit)
+    nonZeroExit: outcome.exitCode !== 0,
+  };
+
+  // PRI-360 S1: Use unified resolveSourceKind instead of resolveSourceKindFromToolFailure
+  const sourceKind = resolveSourceKind(rawObs);
+
   // PEAT-B1: Evidence triage (with consecutiveErrors and isRisky for upgrade logic)
-  const sourceKind = resolveSourceKindFromToolFailure(event.toolName, failureSource);
   const triage = evaluateEvidenceTriage(sourceKind, observation.painScore, {
     consecutiveErrors: (latestFailureState ?? sessionState)?.consecutiveErrors,
     isRisky: observation.isRisk,
@@ -554,20 +579,8 @@ export function resetTriggerCooldownForTest(): void {
 
 // ── Source Classification ────────────────────────────────────────────────────
 
-/**
- * Classify tool failure source.
- *
- * Pure function — no I/O, no side effects.
- * Determines whether a tool failure is a dispatch error (tool not found)
- * or a regular tool execution failure.
- */
-export function classifyToolFailureSource(toolName: string | undefined, error: unknown): 'dispatch_error' | 'tool_failure' {
-  if (!toolName || toolName.trim() === '') return 'dispatch_error';
-  const msg = String(error ?? '');
-  if (/\btool\s+(?:\S+\s+)?not\s+found\b/i.test(msg)) return 'dispatch_error';
-  if (/\bunknown\s+tool\b/i.test(msg)) return 'dispatch_error';
-  return 'tool_failure';
-}
+// classifyToolFailureSource logic is now in resolveSourceKind (PRI-360 S1)
+// This function is removed to avoid duplication.
 
 /**
  * Extract error type classification from error value.

package/src/hooks/llm.ts

@@ -12,7 +12,8 @@ import { atomicWriteFileSync } from '../utils/io.js';
 import { emitPainDetectedEvent, buildTrajectoryEvidence } from './pain.js';
 import { evaluatePainDiagnosticGate } from '../core/pain-diagnostic-gate.js';
 import { loadFeatureFlagFromConfig } from '../core/pd-config-loader.js';
-import { resolveSourceKindFromLlmDetection, evaluateEvidenceTriage } from './triage-adapter.js';
+import { resolveSourceKind, type RawObservation } from './raw-observation-adapter.js';
+import { evaluateEvidenceTriage } from './triage-adapter.js';
 
 export interface EmpathySignal {
     detected: boolean;
@@ -255,7 +256,15 @@ export function handleLlmOutput(
         let triageAdmitted = true;
         const llmTriageFlag = loadFeatureFlagFromConfig(ctx.workspaceDir!, 'painEvidenceAdmission');
         if (llmTriageFlag.enabled) {
-            const sourceKind = resolveSourceKindFromLlmDetection(source, isGfiTriggered);
+            // PRI-360 S1: Build RawObservation for unified source mapping
+            const rawObs: RawObservation = {
+                observedAt: new Date().toISOString(),
+                workspaceId: ctx.workspaceDir,
+                sessionId: ctx.sessionId,
+                detectionSource: source,
+                isGfiTriggered,
+            };
+            const sourceKind = resolveSourceKind(rawObs);
             const triage = evaluateEvidenceTriage(sourceKind, painScore);
             if (triage.decision !== 'admit') {
                 triageAdmitted = false;

package/src/hooks/pain.ts

@@ -128,9 +128,10 @@ function createPainId(sessionId: string): string {
   return `pain_${Date.now()}_${computeHash(sessionId).slice(0, 8)}`;
 }
 
-// ── Source Classification (re-exported from helpers) ────────────────────────
+// ── Source Classification ────────────────────────────────────────────────────
 
-export { classifyToolFailureSource } from './after-tool-call-helpers.js';
+// PRI-360 S1: classifyToolFailureSource is removed; source mapping is now unified
+// through resolveSourceKind in raw-observation-adapter.ts
 
 // ── Main Hook ───────────────────────────────────────────────────────────────
 

package/src/hooks/raw-observation-adapter.ts

@@ -26,6 +26,9 @@
 import type { SourceKind } from '@principles/core/runtime-v2';
 import type { RawObservation } from './raw-observation-types.js';
 
+// Re-export RawObservation for plugin consumers
+export type { RawObservation } from './raw-observation-types.js';
+
 /**
  * Resolve SourceKind from a unified RawObservation.
  *
@@ -135,97 +138,78 @@ export function resolveSourceKind(observation: RawObservation): SourceKind {
   return 'unknown';
 }
 
-/**
- * Resolve SourceKind from tool failure context (legacy wrapper).
- *
- * This is a thin wrapper around resolveSourceKind for compatibility.
- * It constructs a RawObservation from the old function signature.
- *
- * @deprecated Use resolveSourceKind directly with RawObservation.
- */
-export function resolveSourceKindFromToolFailure(
-  toolName: string | undefined,
-  failureSource: 'tool_failure' | 'dispatch_error',
-  provenance?: 'openclaw_context_bound' | 'owner_reported_no_host_trace' | 'automatic_hook',
-): SourceKind {
-  const observation: RawObservation = {
-    observedAt: new Date().toISOString(),
-    toolName,
-    failureSource,
-    provenance,
-  };
-  return resolveSourceKind(observation);
-}
+// ── Builder Functions ──────────────────────────────────────────────────────
+//
+// PRI-360 S1: These builders construct RawObservation from specific contexts,
+// centralizing source classification rules in the adapter layer.
+// Hooks should NOT hold source classification logic — use these builders.
 
 /**
- * Resolve SourceKind from LLM detection context (legacy wrapper).
- *
- * This is a thin wrapper around resolveSourceKind for compatibility.
+ * Classify error message as dispatch_error vs tool_failure.
  *
- * @deprecated Use resolveSourceKind directly with RawObservation.
+ * This centralizes the regex-based classification that was previously
+ * scattered in classifyToolFailureSource and after-tool-call-helpers.
+ * Now hooks call this builder + resolveSourceKind instead of holding rules.
  */
-export function resolveSourceKindFromLlmDetection(
-  detectionSource: string,
-  isGfiTriggered: boolean,
-): SourceKind {
-  const observation: RawObservation = {
-    observedAt: new Date().toISOString(),
-    detectionSource,
-    isGfiTriggered,
-  };
-  return resolveSourceKind(observation);
+function classifyErrorForDispatch(error: unknown): 'dispatch_error' | 'tool_failure' {
+  if (!error) return 'tool_failure';
+  const msg = String(error);
+  if (/\btool\s+(?:\S+\s+)?not\s+found\b/i.test(msg) || /\bunknown\s+tool\b/i.test(msg)) {
+    return 'dispatch_error';
+  }
+  return 'tool_failure';
 }
 
 /**
- * Resolve SourceKind from gate block context (legacy wrapper).
+ * Build a RawObservation for a tool failure context.
  *
- * @deprecated Use resolveSourceKind directly with RawObservation.
+ * This replaces classifyToolFailureSource and the inline classification
+ * in after-tool-call-helpers. All tool error → dispatch/tool_failure
+ * classification is centralized here.
  */
-export function resolveSourceKindFromGateBlock(): SourceKind {
-  const observation: RawObservation = {
-    observedAt: new Date().toISOString(),
-    isGateBlock: true,
-  };
-  return resolveSourceKind(observation);
-}
+export function buildToolFailureObservation(options: {
+  toolName: string | undefined;
+  error: unknown;
+  exitCode?: number;
+  provenance?: RawObservation['provenance'];
+}): RawObservation {
+  const { toolName, error, provenance } = options;
+  const nonZeroExit = typeof options.exitCode === 'number' && options.exitCode !== 0;
+
+  // Classify dispatch vs tool_failure centrally
+  let failureSource: 'dispatch_error' | 'tool_failure' | undefined;
+
+  if (!toolName || toolName.trim() === '') {
+    // Empty/whitespace tool name → dispatch error
+    failureSource = 'dispatch_error';
+  } else {
+    failureSource = classifyErrorForDispatch(error);
+  }
 
-/**
- * Resolve SourceKind from manual command context (legacy wrapper).
- *
- * @deprecated Use resolveSourceKind directly with RawObservation.
- */
-export function resolveSourceKindFromCommand(): SourceKind {
-  const observation: RawObservation = {
-    observedAt: new Date().toISOString(),
-    isManualEntry: true,
-  };
-  return resolveSourceKind(observation);
-}
+  // If neither error nor non-zero exit, this is not a failure context
+  if (!error && !nonZeroExit) {
+    failureSource = undefined;
+  }
 
-/**
- * Resolve SourceKind from provider context (legacy wrapper).
- *
- * @deprecated Use resolveSourceKind directly with RawObservation.
- */
-export function resolveSourceKindFromProvider(
-  isRateLimit: boolean,
-): SourceKind {
-  const observation: RawObservation = {
+  return {
     observedAt: new Date().toISOString(),
-    isRateLimit,
+    toolName,
+    failureSource,
+    nonZeroExit,
+    provenance,
   };
-  return resolveSourceKind(observation);
 }
 
 /**
- * Resolve SourceKind from subagent context (legacy wrapper).
- *
- * @deprecated Use resolveSourceKind directly with RawObservation.
+ * Build a RawObservation for an LLM detection context.
  */
-export function resolveSourceKindFromSubagent(): SourceKind {
-  const observation: RawObservation = {
+export function buildLlmDetectionObservation(options: {
+  detectionSource: string;
+  isGfiTriggered: boolean;
+}): RawObservation {
+  return {
     observedAt: new Date().toISOString(),
-    isSubagentError: true,
+    detectionSource: options.detectionSource,
+    isGfiTriggered: options.isGfiTriggered,
   };
-  return resolveSourceKind(observation);
 }

package/src/hooks/triage-adapter.ts

@@ -32,50 +32,11 @@ import {
  *
  * This is the unified entry point for source-kind classification.
  * It replaces the scattered resolveSourceKindFrom* functions.
- */
-export { resolveSourceKind } from './raw-observation-adapter.js';
-
-/**
- * Map after_tool_call hook context to SourceKind.
- *
- * @deprecated Use resolveSourceKind directly with RawObservation.
- */
-export { resolveSourceKindFromToolFailure } from './raw-observation-adapter.js';
-
-/**
- * Map empathy/semantic detection context to SourceKind.
- *
- * @deprecated Use resolveSourceKind directly with RawObservation.
- */
-export { resolveSourceKindFromLlmDetection } from './raw-observation-adapter.js';
-
-/**
- * Map gate-block context to SourceKind.
- *
- * @deprecated Use resolveSourceKind directly with RawObservation.
- */
-export { resolveSourceKindFromGateBlock } from './raw-observation-adapter.js';
-
-/**
- * Map /pd-pain command to SourceKind.
- *
- * @deprecated Use resolveSourceKind directly with RawObservation.
- */
-export { resolveSourceKindFromCommand } from './raw-observation-adapter.js';
-
-/**
- * Map provider/rate-limit failure to SourceKind.
- *
- * @deprecated Use resolveSourceKind directly with RawObservation.
- */
-export { resolveSourceKindFromProvider } from './raw-observation-adapter.js';
-
-/**
- * Map subagent error to SourceKind.
  *
- * @deprecated Use resolveSourceKind directly with RawObservation.
+ * PRI-360 S1: All source-kind resolution now goes through this single entry point.
  */
-export { resolveSourceKindFromSubagent } from './raw-observation-adapter.js';
+export { resolveSourceKind, buildToolFailureObservation, buildLlmDetectionObservation, type RawObservation } from './raw-observation-adapter.js';
+// All callers should use resolveSourceKind with RawObservation.
 
 // ── Triage Evaluation ───────────────────────────────────────────────────────
 

package/tests/hooks/pain.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { handleAfterToolCall, classifyToolFailureSource } from '../../src/hooks/pain.js';
+import { handleAfterToolCall } from '../../src/hooks/pain.js';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
@@ -8,6 +8,7 @@ import { WorkspaceContext } from '../../src/core/workspace-context.js';
 import { EventLogService } from '../../src/core/event-log.js';
 import { setInjectedProbationIds, clearSession } from '../../src/core/session-tracker.js';
 import { resetTriggerCooldownForTest } from '../../src/hooks/after-tool-call-helpers.js';
+import { buildToolFailureObservation, resolveSourceKind } from '../../src/hooks/raw-observation-adapter.js';
 import { loadFeatureFlagFromConfig } from '../../src/core/pd-config-loader.js';
 
 vi.mock('fs');
@@ -31,74 +32,91 @@ const mockEmitSync = vi.fn();
 const mockRecordProbationFeedback = vi.fn();
 const mockUpdatePrincipleValueMetrics = vi.fn();
 
-describe('classifyToolFailureSource', () => {
+// PRI-360 S1: classifyToolFailureSource tests migrated to resolveSourceKind + buildToolFailureObservation
+// See triage-adapter.test.ts for the unified RawObservation path tests
+
+describe('buildToolFailureObservation + resolveSourceKind (replaces classifyToolFailureSource)', () => {
   it('empty toolName -> dispatch_error', () => {
-    expect(classifyToolFailureSource(undefined, 'tool not found')).toBe('dispatch_error');
-    expect(classifyToolFailureSource('', 'tool not found')).toBe('dispatch_error');
+    const obs = buildToolFailureObservation({ toolName: undefined, error: 'tool not found', exitCode: 1 });
+    expect(resolveSourceKind(obs)).toBe('dispatch_error');
+    const obs2 = buildToolFailureObservation({ toolName: '', error: 'tool not found', exitCode: 1 });
+    expect(resolveSourceKind(obs2)).toBe('dispatch_error');
   });
 
   it('"Tool not found" (case insensitive) -> dispatch_error', () => {
-    expect(classifyToolFailureSource('read', 'error: tool not found')).toBe('dispatch_error');
-    expect(classifyToolFailureSource('read', 'Tool Not Found')).toBe('dispatch_error');
-    // "tool <name> not found" also matches (e.g. "tool read_file not found")
-    expect(classifyToolFailureSource('read', 'Tool read_file not found')).toBe('dispatch_error');
+    const cases = [
+      'error: tool not found',
+      'Tool Not Found',
+      'Tool read_file not found',
+    ];
+    for (const err of cases) {
+      const obs = buildToolFailureObservation({ toolName: 'read', error: err, exitCode: 1 });
+      expect(resolveSourceKind(obs)).toBe('dispatch_error');
+    }
   });
 
   it('"Unknown tool" (case insensitive) -> dispatch_error', () => {
-    expect(classifyToolFailureSource('read', 'error: unknown tool')).toBe('dispatch_error');
-    expect(classifyToolFailureSource('read', 'Unknown Tool')).toBe('dispatch_error');
-    expect(classifyToolFailureSource('read', 'failed: unknown tool read_file')).toBe('dispatch_error');
+    const cases = ['error: unknown tool', 'Unknown Tool', 'failed: unknown tool read_file'];
+    for (const err of cases) {
+      const obs = buildToolFailureObservation({ toolName: 'read', error: err, exitCode: 1 });
+      expect(resolveSourceKind(obs)).toBe('dispatch_error');
+    }
   });
 
   it('Warning-style messages containing "tool not found" -> dispatch_error', () => {
-    // After dropping "error:" prefix, Warning messages with "tool not found" match the dispatch pattern
-    expect(classifyToolFailureSource('read', 'Warning: tool not found was suppressed')).toBe('dispatch_error');
-    expect(classifyToolFailureSource('read', 'Warning: tool not found - already handled')).toBe('dispatch_error');
+    const cases = ['Warning: tool not found was suppressed', 'Warning: tool not found - already handled'];
+    for (const err of cases) {
+      const obs = buildToolFailureObservation({ toolName: 'read', error: err, exitCode: 1 });
+      expect(resolveSourceKind(obs)).toBe('dispatch_error');
+    }
   });
 
   it('real execution errors (ENOENT, EACCES) -> tool_failure', () => {
-    expect(classifyToolFailureSource('read', 'ENOENT: no such file or directory')).toBe('tool_failure');
-    expect(classifyToolFailureSource('write', 'EACCES: permission denied')).toBe('tool_failure');
-    expect(classifyToolFailureSource('edit', 'Error: EIO: I/O error')).toBe('tool_failure');
+    const cases = [
+      { toolName: 'read' as const, error: 'ENOENT: no such file or directory' },
+      { toolName: 'write' as const, error: 'EACCES: permission denied' },
+      { toolName: 'edit' as const, error: 'Error: EIO: I/O error' },
+    ];
+    for (const { toolName, error } of cases) {
+      const obs = buildToolFailureObservation({ toolName, error, exitCode: 1 });
+      expect(resolveSourceKind(obs)).toBe('tool_failure');
+    }
   });
 
-  it('edge cases: null/undefined/empty error', () => {
-    expect(classifyToolFailureSource('read', null)).toBe('tool_failure');
-    expect(classifyToolFailureSource('read', undefined)).toBe('tool_failure');
-    expect(classifyToolFailureSource('read', '')).toBe('tool_failure');
-    expect(classifyToolFailureSource('read', 123)).toBe('tool_failure');
+  it('edge cases: null/undefined/empty error -> tool_failure', () => {
+    // With valid toolName and non-zero exit, no error message → tool_failure
+    const obs = buildToolFailureObservation({ toolName: 'read', error: undefined, exitCode: 1 });
+    expect(resolveSourceKind(obs)).toBe('tool_failure');
   });
 
   it('word-boundary: "report_tool_not_found" does NOT match dispatch pattern', () => {
-    expect(classifyToolFailureSource('read', 'report_tool_not_found')).toBe('tool_failure');
+    const obs = buildToolFailureObservation({ toolName: 'read', error: 'report_tool_not_found', exitCode: 1 });
+    expect(resolveSourceKind(obs)).toBe('tool_failure');
   });
 
   it('word-boundary: "atoolnotfound" (no spaces) does NOT match dispatch pattern', () => {
-    expect(classifyToolFailureSource('read', 'atoolnotfound')).toBe('tool_failure');
+    const obs = buildToolFailureObservation({ toolName: 'read', error: 'atoolnotfound', exitCode: 1 });
+    expect(resolveSourceKind(obs)).toBe('tool_failure');
   });
 
   it('word-boundary: "unknown_tool" (underscore, no space) does NOT match dispatch pattern', () => {
-    expect(classifyToolFailureSource('read', 'unknown_tool')).toBe('tool_failure');
+    const obs = buildToolFailureObservation({ toolName: 'read', error: 'unknown_tool', exitCode: 1 });
+    expect(resolveSourceKind(obs)).toBe('tool_failure');
   });
 
   it('whitespace-only toolName -> dispatch_error', () => {
-    expect(classifyToolFailureSource('   ', 'tool not found')).toBe('dispatch_error');
-  });
-
-  it('numeric error value -> tool_failure', () => {
-    expect(classifyToolFailureSource('read', 42)).toBe('tool_failure');
-  });
-
-  it('object error value -> tool_failure', () => {
-    expect(classifyToolFailureSource('read', { code: 'ENOENT' })).toBe('tool_failure');
+    const obs = buildToolFailureObservation({ toolName: '   ', error: 'tool not found', exitCode: 1 });
+    expect(resolveSourceKind(obs)).toBe('dispatch_error');
   });
 
   it('"tool <name> not found" with multi-word tool name -> dispatch_error', () => {
-    expect(classifyToolFailureSource('read', 'tool my_custom_tool not found')).toBe('dispatch_error');
+    const obs = buildToolFailureObservation({ toolName: 'read', error: 'tool my_custom_tool not found', exitCode: 1 });
+    expect(resolveSourceKind(obs)).toBe('dispatch_error');
   });
 
   it('partial match "not found" without "tool" prefix -> tool_failure', () => {
-    expect(classifyToolFailureSource('read', 'file not found')).toBe('tool_failure');
+    const obs = buildToolFailureObservation({ toolName: 'read', error: 'file not found', exitCode: 1 });
+    expect(resolveSourceKind(obs)).toBe('tool_failure');
   });
 });
 

package/tests/hooks/triage-adapter.test.ts

@@ -1,8 +1,11 @@
 /**
- * Triage Adapter Tests — PEAT-B1
+ * Triage Adapter Tests — PEAT-B1 / PRI-360 S1
  *
- * Tests the plugin-side adapter that maps hook context to SourceKind
- * and calls the pure triage policy from principles-core.
+ * Tests the unified RawObservation → SourceKind resolution path
+ * and the evidence triage policy.
+ *
+ * All legacy resolveSourceKindFrom* wrappers have been removed.
+ * Every test uses resolveSourceKind(RawObservation) directly.
  *
  * ERR checklist:
  * - ERR-001: Source kind resolved from runtime values, not `as` casts.
@@ -12,98 +15,166 @@
 
 import { describe, it, expect } from 'vitest';
 import {
-  resolveSourceKindFromToolFailure,
-  resolveSourceKindFromLlmDetection,
-  resolveSourceKindFromGateBlock,
-  resolveSourceKindFromCommand,
-  resolveSourceKindFromProvider,
-  resolveSourceKindFromSubagent,
+  resolveSourceKind,
+  buildToolFailureObservation,
+  buildLlmDetectionObservation,
+  type RawObservation,
   evaluateEvidenceTriage,
   isHighConfidenceUnsafeAction,
 } from '../../src/hooks/triage-adapter.js';
 
-// ── resolveSourceKindFromToolFailure ────────────────────────────────────────
+// ── resolveSourceKind: Tool Failure Path ─────────────────────────────────────
 
-describe('resolveSourceKindFromToolFailure', () => {
+describe('resolveSourceKind: tool failure path', () => {
   it('maps pain tool to agent_on_owner_request with openclaw_context_bound', () => {
-    expect(resolveSourceKindFromToolFailure('pain', 'tool_failure', 'openclaw_context_bound')).toBe('agent_on_owner_request');
+    const obs: RawObservation = { observedAt: 't', toolName: 'pain', failureSource: 'tool_failure', provenance: 'openclaw_context_bound' };
+    expect(resolveSourceKind(obs)).toBe('agent_on_owner_request');
   });
 
   it('maps pain tool to owner_reported without openclaw_context_bound', () => {
-    expect(resolveSourceKindFromToolFailure('pain', 'tool_failure')).toBe('owner_reported');
-    expect(resolveSourceKindFromToolFailure('pain', 'tool_failure', 'automatic_hook')).toBe('owner_reported');
+    expect(resolveSourceKind({ observedAt: 't', toolName: 'pain', failureSource: 'tool_failure' })).toBe('owner_reported');
+    expect(resolveSourceKind({ observedAt: 't', toolName: 'pain', failureSource: 'tool_failure', provenance: 'automatic_hook' })).toBe('owner_reported');
   });
 
   it('maps skill:pain to agent_on_owner_request with openclaw_context_bound', () => {
-    expect(resolveSourceKindFromToolFailure('skill:pain', 'tool_failure', 'openclaw_context_bound')).toBe('agent_on_owner_request');
+    expect(resolveSourceKind({ observedAt: 't', toolName: 'skill:pain', failureSource: 'tool_failure', provenance: 'openclaw_context_bound' })).toBe('agent_on_owner_request');
   });
 
   it('maps dispatch_error to dispatch_error', () => {
-    expect(resolveSourceKindFromToolFailure('read', 'dispatch_error')).toBe('dispatch_error');
+    expect(resolveSourceKind({ observedAt: 't', toolName: 'read', failureSource: 'dispatch_error' })).toBe('dispatch_error');
   });
 
   it('maps regular tool failure to tool_failure', () => {
-    expect(resolveSourceKindFromToolFailure('write', 'tool_failure')).toBe('tool_failure');
-    expect(resolveSourceKindFromToolFailure('exec', 'tool_failure')).toBe('tool_failure');
+    expect(resolveSourceKind({ observedAt: 't', toolName: 'write', failureSource: 'tool_failure' })).toBe('tool_failure');
+    expect(resolveSourceKind({ observedAt: 't', toolName: 'exec', failureSource: 'tool_failure' })).toBe('tool_failure');
   });
 
-  it('maps undefined tool name with tool_failure to tool_failure', () => {
-    expect(resolveSourceKindFromToolFailure(undefined, 'tool_failure')).toBe('tool_failure');
+  it('maps undefined tool name with tool_failure to dispatch_error via toolNotFound', () => {
+    expect(resolveSourceKind({ observedAt: 't', toolName: undefined, failureSource: 'tool_failure' })).toBe('tool_failure');
   });
 });
 
-// ── resolveSourceKindFromLlmDetection ───────────────────────────────────────
+// ── resolveSourceKind: LLM Detection Path ────────────────────────────────────
 
-describe('resolveSourceKindFromLlmDetection', () => {
+describe('resolveSourceKind: LLM detection path', () => {
   it('maps gfi triggered to gfi_threshold', () => {
-    expect(resolveSourceKindFromLlmDetection('llm_some_rule', true)).toBe('gfi_threshold');
+    expect(resolveSourceKind({ observedAt: 't', detectionSource: 'llm_some_rule', isGfiTriggered: true })).toBe('gfi_threshold');
   });
 
   it('maps llm_paralysis to llm_paralysis', () => {
-    expect(resolveSourceKindFromLlmDetection('llm_paralysis', false)).toBe('llm_paralysis');
+    expect(resolveSourceKind({ observedAt: 't', detectionSource: 'llm_paralysis', isGfiTriggered: false })).toBe('llm_paralysis');
   });
 
   it('maps llm_* detection rules to semantic', () => {
-    expect(resolveSourceKindFromLlmDetection('llm_repetition', false)).toBe('semantic');
-    expect(resolveSourceKindFromLlmDetection('llm_loop', false)).toBe('semantic');
+    expect(resolveSourceKind({ observedAt: 't', detectionSource: 'llm_repetition', isGfiTriggered: false })).toBe('semantic');
+    expect(resolveSourceKind({ observedAt: 't', detectionSource: 'llm_loop', isGfiTriggered: false })).toBe('semantic');
   });
 
   it('maps user_empathy to empathy_inferred', () => {
-    expect(resolveSourceKindFromLlmDetection('user_empathy', false)).toBe('empathy_inferred');
+    expect(resolveSourceKind({ observedAt: 't', detectionSource: 'user_empathy', isGfiTriggered: false })).toBe('empathy_inferred');
   });
 
   it('maps unknown source to unknown', () => {
-    expect(resolveSourceKindFromLlmDetection('something_else', false)).toBe('unknown');
+    expect(resolveSourceKind({ observedAt: 't', detectionSource: 'something_else', isGfiTriggered: false })).toBe('unknown');
   });
 });
 
-// ── Other resolve functions ─────────────────────────────────────────────────
+// ── resolveSourceKind: Other Context Paths ───────────────────────────────────
 
-describe('resolveSourceKindFromGateBlock', () => {
+describe('resolveSourceKind: gate block path', () => {
   it('returns rulehost_block', () => {
-    expect(resolveSourceKindFromGateBlock()).toBe('rulehost_block');
+    expect(resolveSourceKind({ observedAt: 't', isGateBlock: true })).toBe('rulehost_block');
   });
 });
 
-describe('resolveSourceKindFromCommand', () => {
+describe('resolveSourceKind: manual command path', () => {
   it('returns owner_reported', () => {
-    expect(resolveSourceKindFromCommand()).toBe('owner_reported');
+    expect(resolveSourceKind({ observedAt: 't', isManualEntry: true })).toBe('owner_reported');
   });
 });
 
-describe('resolveSourceKindFromProvider', () => {
+describe('resolveSourceKind: provider path', () => {
   it('returns provider_failure for non-rate-limit', () => {
-    expect(resolveSourceKindFromProvider(false)).toBe('provider_failure');
+    expect(resolveSourceKind({ observedAt: 't', isRateLimit: false })).toBe('provider_failure');
   });
 
   it('returns rate_limit for rate-limit', () => {
-    expect(resolveSourceKindFromProvider(true)).toBe('rate_limit');
+    expect(resolveSourceKind({ observedAt: 't', isRateLimit: true })).toBe('rate_limit');
   });
 });
 
-describe('resolveSourceKindFromSubagent', () => {
+describe('resolveSourceKind: subagent path', () => {
   it('returns subagent_error', () => {
-    expect(resolveSourceKindFromSubagent()).toBe('subagent_error');
+    expect(resolveSourceKind({ observedAt: 't', isSubagentError: true })).toBe('subagent_error');
+  });
+});
+
+// ── buildToolFailureObservation ──────────────────────────────────────────────
+
+describe('buildToolFailureObservation', () => {
+  it('classifies empty tool name as dispatch_error', () => {
+    const obs = buildToolFailureObservation({ toolName: undefined, error: 'tool not found', exitCode: 1 });
+    expect(obs.failureSource).toBe('dispatch_error');
+    expect(resolveSourceKind(obs)).toBe('dispatch_error');
+  });
+
+  it('classifies "tool not found" error as dispatch_error', () => {
+    const obs = buildToolFailureObservation({ toolName: 'read', error: 'tool read_file not found', exitCode: 1 });
+    expect(obs.failureSource).toBe('dispatch_error');
+    expect(resolveSourceKind(obs)).toBe('dispatch_error');
+  });
+
+  it('classifies "Unknown tool" error as dispatch_error', () => {
+    const obs = buildToolFailureObservation({ toolName: 'read', error: 'Unknown Tool', exitCode: 1 });
+    expect(obs.failureSource).toBe('dispatch_error');
+  });
+
+  it('classifies real errors (ENOENT) as tool_failure', () => {
+    const obs = buildToolFailureObservation({ toolName: 'read', error: 'ENOENT: no such file', exitCode: 1 });
+    expect(obs.failureSource).toBe('tool_failure');
+    expect(resolveSourceKind(obs)).toBe('tool_failure');
+  });
+
+  it('classifies no error + no exit as non-failure (undefined failureSource)', () => {
+    const obs = buildToolFailureObservation({ toolName: 'read', error: undefined, exitCode: 0 });
+    expect(obs.failureSource).toBeUndefined();
+  });
+
+  it('classifies whitespace-only tool name as dispatch_error', () => {
+    const obs = buildToolFailureObservation({ toolName: '   ', error: 'tool not found', exitCode: 1 });
+    expect(obs.failureSource).toBe('dispatch_error');
+  });
+
+  it('word-boundary: "report_tool_not_found" does NOT match dispatch pattern', () => {
+    const obs = buildToolFailureObservation({ toolName: 'read', error: 'report_tool_not_found', exitCode: 1 });
+    expect(obs.failureSource).toBe('tool_failure');
+  });
+
+  it('word-boundary: "atoolnotfound" does NOT match dispatch pattern', () => {
+    const obs = buildToolFailureObservation({ toolName: 'read', error: 'atoolnotfound', exitCode: 1 });
+    expect(obs.failureSource).toBe('tool_failure');
+  });
+
+  it('preserves provenance', () => {
+    const obs = buildToolFailureObservation({ toolName: 'pain', error: 'fail', exitCode: 1, provenance: 'openclaw_context_bound' });
+    expect(obs.provenance).toBe('openclaw_context_bound');
+    expect(resolveSourceKind(obs)).toBe('agent_on_owner_request');
+  });
+});
+
+// ── buildLlmDetectionObservation ─────────────────────────────────────────────
+
+describe('buildLlmDetectionObservation', () => {
+  it('builds observation for GFI-triggered detection', () => {
+    const obs = buildLlmDetectionObservation({ detectionSource: 'llm_some_rule', isGfiTriggered: true });
+    expect(obs.detectionSource).toBe('llm_some_rule');
+    expect(obs.isGfiTriggered).toBe(true);
+    expect(resolveSourceKind(obs)).toBe('gfi_threshold');
+  });
+
+  it('builds observation for llm_paralysis', () => {
+    const obs = buildLlmDetectionObservation({ detectionSource: 'llm_paralysis', isGfiTriggered: false });
+    expect(resolveSourceKind(obs)).toBe('llm_paralysis');
   });
 });