principles-disciple 1.11.0 → 1.13.0

package/src/core/trajectory.ts

@@ -22,7 +22,6 @@ import type {
   TaskKind,
   TaskPriority,
   EvolutionTaskInput,
-  EvolutionTaskInputV2,
   EvolutionEventInput,
   EvolutionTaskRecord,
   EvolutionEventRecord,
@@ -50,7 +49,6 @@ export type {
   TaskKind,
   TaskPriority,
   EvolutionTaskInput,
-  EvolutionTaskInputV2,
   EvolutionEventInput,
   EvolutionTaskRecord,
   EvolutionEventRecord,
@@ -210,7 +208,8 @@ export class TrajectoryDatabase {
     const createdAt = input.createdAt ?? nowIso();
     // Extract filePath from paramsJson if provided and is an object with filePath
     const paramsObj = input.paramsJson as Record<string, unknown> | undefined;
-    const filePath = paramsObj && typeof paramsObj.filePath === 'string' ? paramsObj.filePath : null;
+    /* eslint-disable @typescript-eslint/no-unused-vars, no-unused-vars -- Reason: _filePath extracted for potential future use but currently unused */
+    const _filePath = paramsObj && typeof paramsObj.filePath === 'string' ? paramsObj.filePath : null;
     const rowId = this.withWrite(() => {
       const result = this.db.prepare(`
         INSERT INTO tool_calls (
@@ -272,7 +271,7 @@ export class TrajectoryDatabase {
    * Search pain_events using FTS5 full-text search (MEM-04).
    * Returns pain events matching the query, ordered by relevance.
    */
-  searchPainEvents(query: string, limit: number = 10): Array<{
+  searchPainEvents(query: string, limit = 10): {
     id: number;
     sessionId: string;
     source: string;
@@ -283,7 +282,7 @@ export class TrajectoryDatabase {
     confidence: number | null;
     text: string | null;
     createdAt: string;
-  }> {
+  }[] {
     if (!query || query.trim().length === 0) {
       return [];
     }
@@ -299,7 +298,7 @@ export class TrajectoryDatabase {
         WHERE pain_events_fts MATCH ?
         ORDER BY bm25(pain_events_fts) DESC
         LIMIT ?
-      `).all(ftsQuery, limit) as Array<{
+      `).all(ftsQuery, limit) as {
         id: number;
         session_id: string;
         source: string;
@@ -310,7 +309,7 @@ export class TrajectoryDatabase {
         confidence: number | null;
         text: string | null;
         created_at: string;
-      }>;
+      }[];
 
       return results.map(row => ({
         id: row.id,
@@ -396,7 +395,7 @@ export class TrajectoryDatabase {
   recordEvolutionTask(input: EvolutionTaskInput): void {
     const now = nowIso();
     // Cast to V2 to access new fields
-    const v2 = input as EvolutionTaskInputV2;
+    const v2 = input;
     this.withWrite(() => {
       this.db.prepare(`
         INSERT INTO evolution_tasks (
@@ -442,7 +441,7 @@ export class TrajectoryDatabase {
   updateEvolutionTask(taskId: string, updates: Partial<Omit<EvolutionTaskInput, 'taskId' | 'traceId' | 'source'>>): void {
     const now = nowIso();
     // Cast to V2 to access new fields
-    const v2Updates = updates as Partial<Omit<EvolutionTaskInputV2, 'taskId' | 'traceId' | 'source'>>;
+    const v2Updates = updates;
     this.withWrite(() => {
       const setClauses: string[] = ['updated_at = ?'];
       const values: unknown[] = [now];
@@ -553,7 +552,7 @@ export class TrajectoryDatabase {
       ${whereClause}
       ORDER BY created_at DESC
       LIMIT ? OFFSET ?
-    `).all(...values, limit, offset) as Array<Record<string, unknown>>;
+    `).all(...values, limit, offset) as Record<string, unknown>[];
 
     return rows.map((row) => ({
       id: Number(row.id),
@@ -588,7 +587,8 @@ export class TrajectoryDatabase {
     const limit = filters.limit ?? 100;
     const offset = filters.offset ?? 0;
 
-    let rows: Array<Record<string, unknown>>;
+    // eslint-disable-next-line @typescript-eslint/init-declarations -- assigned in both if/else branches
+    let rows: Record<string, unknown>[];
     if (traceId) {
       rows = this.db.prepare(`
         SELECT id, trace_id, task_id, stage, level, message, summary, metadata_json, created_at
@@ -596,14 +596,14 @@ export class TrajectoryDatabase {
         WHERE trace_id = ?
         ORDER BY created_at ASC
         LIMIT ? OFFSET ?
-      `).all(traceId, limit, offset) as Array<Record<string, unknown>>;
+      `).all(traceId, limit, offset) as Record<string, unknown>[];
     } else {
       rows = this.db.prepare(`
         SELECT id, trace_id, task_id, stage, level, message, summary, metadata_json, created_at
         FROM evolution_events
         ORDER BY created_at DESC
         LIMIT ? OFFSET ?
-      `).all(limit, offset) as Array<Record<string, unknown>>;
+      `).all(limit, offset) as Record<string, unknown>[];
     }
 
     return rows.map((row) => ({
@@ -669,7 +669,7 @@ export class TrajectoryDatabase {
   getEvolutionStats(): { total: number; pending: number; inProgress: number; completed: number; failed: number } {
     const rows = this.db.prepare(`
       SELECT status, COUNT(*) as count FROM evolution_tasks GROUP BY status
-    `).all() as Array<{ status: string; count: number }>;
+    `).all() as { status: string; count: number }[];
 
     const stats = { total: 0, pending: 0, inProgress: 0, completed: 0, failed: 0 };
     for (const row of rows) {
@@ -691,7 +691,7 @@ export class TrajectoryDatabase {
    * @param options.dateFrom - Only return sessions updated after this date
    * @param options.dateTo - Only return sessions updated before this date
    */
-  listRecentSessions(options: { limit?: number; dateFrom?: string; dateTo?: string } = {}): Array<{ sessionId: string; startedAt: string; updatedAt: string }> {
+  listRecentSessions(options: { limit?: number; dateFrom?: string; dateTo?: string } = {}): { sessionId: string; startedAt: string; updatedAt: string }[] {
     const conditions: string[] = [];
     const values: unknown[] = [];
 
@@ -713,7 +713,7 @@ export class TrajectoryDatabase {
       ${whereClause}
       ORDER BY updated_at DESC
       LIMIT ?
-    `).all(...values, limit) as Array<Record<string, unknown>>;
+    `).all(...values, limit) as Record<string, unknown>[];
 
     return rows.map((row) => ({
       sessionId: String(row.session_id),
@@ -734,7 +734,7 @@ export class TrajectoryDatabase {
       FROM assistant_turns
       WHERE session_id = ?
       ORDER BY id ASC
-    `).all(sessionId) as Array<Record<string, unknown>>;
+    `).all(sessionId) as Record<string, unknown>[];
 
     return rows.map((row) => ({
       id: Number(row.id),
@@ -755,7 +755,7 @@ export class TrajectoryDatabase {
    * Returns: Analytics data aggregated from trajectory database.
    * Not: Runtime truth or real-time queue state.
    */
-  listToolCallsForSession(sessionId: string): Array<{
+  listToolCallsForSession(sessionId: string): {
     id: number;
     toolName: string;
     outcome: string;
@@ -767,14 +767,14 @@ export class TrajectoryDatabase {
     gfiBefore: number | null;
     gfiAfter: number | null;
     createdAt: string;
-  }> {
+  }[] {
     const rows = this.db.prepare(`
       SELECT id, tool_name, outcome, params_json, duration_ms, exit_code, error_type, error_message,
              gfi_before, gfi_after, created_at
       FROM tool_calls
       WHERE session_id = ?
       ORDER BY id ASC
-    `).all(sessionId) as Array<Record<string, unknown>>;
+    `).all(sessionId) as Record<string, unknown>[];
 
     return rows.map((row) => {
       // Extract filePath from params_json if present
@@ -783,6 +783,7 @@ export class TrajectoryDatabase {
         try {
           const params = JSON.parse(row.params_json);
           if (params && typeof params.filePath === 'string') {
+            // eslint-disable-next-line @typescript-eslint/prefer-destructuring -- Reason: filePath is a reassignable outer let variable - destructuring would lose the assignment semantics
             filePath = params.filePath;
           }
         } catch {
@@ -811,7 +812,7 @@ export class TrajectoryDatabase {
    * Returns: Analytics data aggregated from trajectory database.
    * Not: Runtime truth or real-time queue state.
    */
-  listPainEventsForSession(sessionId: string): Array<{
+  listPainEventsForSession(sessionId: string): {
     id: number;
     source: string;
     score: number;
@@ -820,13 +821,13 @@ export class TrajectoryDatabase {
     origin: string | null;
     confidence: number | null;
     createdAt: string;
-  }> {
+  }[] {
     const rows = this.db.prepare(`
       SELECT id, source, score, reason, severity, origin, confidence, created_at
       FROM pain_events
       WHERE session_id = ?
       ORDER BY created_at ASC
-    `).all(sessionId) as Array<Record<string, unknown>>;
+    `).all(sessionId) as Record<string, unknown>[];
 
     return rows.map((row) => ({
       id: Number(row.id),
@@ -844,19 +845,19 @@ export class TrajectoryDatabase {
    * List user turns for a session.
    * Returns sanitized/reduced fields for nocturnal use — NO raw text.
    */
-  listUserTurnsForSession(sessionId: string): Array<{
+  listUserTurnsForSession(sessionId: string): {
     id: number;
     turnIndex: number;
     correctionDetected: boolean;
     correctionCue: string | null;
     createdAt: string;
-  }> {
+  }[] {
     const rows = this.db.prepare(`
       SELECT id, turn_index, correction_detected, correction_cue, created_at
       FROM user_turns
       WHERE session_id = ?
       ORDER BY turn_index ASC
-    `).all(sessionId) as Array<Record<string, unknown>>;
+    `).all(sessionId) as Record<string, unknown>[];
 
     return rows.map((row) => ({
       id: Number(row.id),
@@ -881,7 +882,7 @@ export class TrajectoryDatabase {
       FROM correction_samples
       WHERE review_status = ?
       ORDER BY created_at DESC
-    `).all(status) as Array<Record<string, unknown>>;
+    `).all(status) as Record<string, unknown>[];
 
     return rows.map((row) => ({
       sampleId: String(row.sample_id),
@@ -903,20 +904,20 @@ export class TrajectoryDatabase {
    * List gate blocks for a session.
    * Returns minimal fields for nocturnal use — no raw text.
    */
-  listGateBlocksForSession(sessionId: string): Array<{
+  listGateBlocksForSession(sessionId: string): {
     id: number;
     toolName: string;
     filePath: string | null;
     reason: string;
     planStatus: string | null;
     createdAt: string;
-  }> {
+  }[] {
     const rows = this.db.prepare(`
       SELECT id, tool_name, file_path, reason, plan_status, created_at
       FROM gate_blocks
       WHERE session_id = ?
       ORDER BY id ASC
-    `).all(sessionId) as Array<Record<string, unknown>>;
+    `).all(sessionId) as Record<string, unknown>[];
 
     return rows.map((row) => ({
       id: Number(row.id),
@@ -992,7 +993,7 @@ export class TrajectoryDatabase {
       JOIN user_turns ut ON ut.id = cs.user_correction_turn_id
       WHERE (? = 0 OR cs.review_status = 'approved')
       ORDER BY cs.created_at ASC
-    `).all(opts.approvedOnly ? 1 : 0) as Array<Record<string, unknown>>;
+    `).all(opts.approvedOnly ? 1 : 0) as Record<string, unknown>[];
 
     const exportPath = path.join(this.exportDir, `corrections-${Date.now()}-${opts.mode}.jsonl`);
     const lines = rows.map((row) => {
@@ -1271,7 +1272,7 @@ export class TrajectoryDatabase {
     ];
     for (const col of v2Columns) {
       const exists = this.db.prepare(`PRAGMA table_info(evolution_tasks)`).all()
-        .some((row: any) => row.name === col.name);
+        .some((row) => (row as Record<string, unknown>).name === col.name);
       if (!exists) {
         this.db.exec(`ALTER TABLE evolution_tasks ADD COLUMN ${col.name} ${col.type}`);
       }
@@ -1323,6 +1324,7 @@ export class TrajectoryDatabase {
     this.importLegacyEvolution();
   }
 
+  /* eslint-disable @typescript-eslint/no-unused-vars, no-unused-vars -- Reason: _fromVersion reserved for future migration logic */
   private migrateSchema(_fromVersion?: number): void {
     this.db.exec(`
       DROP VIEW IF EXISTS v_daily_metrics;
@@ -1509,7 +1511,7 @@ export class TrajectoryDatabase {
       WHERE session_id = ? AND outcome = 'success'
       ORDER BY id DESC
       LIMIT 3
-    `).all(sessionId) as Array<Record<string, unknown>>;
+    `).all(sessionId) as Record<string, unknown>[];
     if (successfulCalls.length === 0) return;
 
     const sampleId = `sample_${crypto.createHash('md5').update(`${sessionId}:${correctionTurn.id}:${successfulCalls[0].id}`).digest('hex').slice(0, 12)}`;
@@ -1543,6 +1545,7 @@ export class TrajectoryDatabase {
     });
   }
 
+  /* eslint-disable @typescript-eslint/max-params -- Reason: Audit record requires exportKind, mode, approvedOnly, filePath, and rowCount */
   private recordExportAudit(
     exportKind: string,
     mode: CorrectionExportMode,
@@ -1595,7 +1598,7 @@ export class TrajectoryDatabase {
       SELECT blob_ref FROM assistant_turns WHERE blob_ref IS NOT NULL
       UNION
       SELECT blob_ref FROM user_turns WHERE blob_ref IS NOT NULL
-    `).all() as Array<{ blob_ref?: string | null }>;
+    `).all() as { blob_ref?: string | null }[];
     for (const row of rows) {
       if (row.blob_ref) referenced.add(String(row.blob_ref));
     }
@@ -1607,6 +1610,7 @@ export class TrajectoryDatabase {
     for (const entry of fs.readdirSync(this.blobDir)) {
       if (referenced.has(entry)) continue;
       const fullPath = path.join(this.blobDir, entry);
+      // eslint-disable-next-line @typescript-eslint/init-declarations -- assigned in try, catch continues
       let stat: fs.Stats;
       try {
         stat = fs.statSync(fullPath);
@@ -1629,7 +1633,7 @@ export class TrajectoryDatabase {
 }
 
 export class TrajectoryRegistry {
-  private static instances = new Map<string, TrajectoryDatabase>();
+  private static readonly instances = new Map<string, TrajectoryDatabase>();
 
   static get(workspaceDir: string, opts: Omit<TrajectoryDatabaseOptions, 'workspaceDir'> = {}): TrajectoryDatabase {
     const normalized = path.resolve(workspaceDir);
@@ -1656,7 +1660,9 @@ export class TrajectoryRegistry {
     this.instances.clear();
   }
 
-  static use<T>(workspaceDir: string, fn: (db: TrajectoryDatabase) => T, opts: Omit<TrajectoryDatabaseOptions, 'workspaceDir'> = {}): T {
+  /* eslint-disable no-unused-vars -- Reason: db parameter name in callback type signature */
+  static use<T>(workspaceDir: string, fn: (_db: TrajectoryDatabase) => T, opts: Omit<TrajectoryDatabaseOptions, 'workspaceDir'> = {}): T {
+  /* eslint-enable no-unused-vars */
     const normalized = path.resolve(workspaceDir);
     const existing = this.instances.get(normalized);
     if (existing) {

package/src/core/workspace-context.ts

@@ -1,21 +1,41 @@
-import { resolvePdPath, PD_FILES } from './paths.js';
+import type { PD_FILES } from './paths.js';
+import { resolvePdPath } from './paths.js';
 import { PathResolver } from './path-resolver.js';
 import { ConfigService } from './config-service.js';
-import { PainConfig } from './config.js';
-import { EventLogService, EventLog } from './event-log.js';
+import type { PainConfig } from './config.js';
+import type { EventLog } from './event-log.js';
+import { EventLogService } from './event-log.js';
 import { DictionaryService } from './dictionary-service.js';
-import { PainDictionary } from './dictionary.js';
+import type { PainDictionary } from './dictionary.js';
 import { HygieneTracker } from './hygiene/tracker.js';
 import { EvolutionReducerImpl } from './evolution-reducer.js';
-import { TrajectoryDatabase, TrajectoryRegistry, TrajectoryDatabaseOptions } from './trajectory.js';
+import type { TrajectoryDatabase, TrajectoryDatabaseOptions } from './trajectory.js';
+import { TrajectoryRegistry } from './trajectory.js';
+import { PrincipleLifecycleService } from './principle-internalization/principle-lifecycle-service.js';
+import {
+    getPrincipleSubtree,
+    updatePrinciple,
+    updatePrincipleValueMetrics,
+    type PrincipleSubtree,
+} from './principle-tree-ledger.js';
+import type { Principle, PrincipleValueMetrics } from '../types/principle-tree-schema.js';
+import type { Principle as ActivePrinciple } from './evolution-types.js';
+
+/* eslint-disable no-unused-vars -- Reason: interface method param names intentionally unused - implementations provide actual names */
+interface PrincipleTreeLedgerAccessor {
+    getPrincipleSubtree(_principleId: string): PrincipleSubtree | undefined;
+    updatePrinciple(_principleId: string, updates: Partial<Principle>): Principle;
+    updatePrincipleValueMetrics(principleId: string, _metrics: PrincipleValueMetrics): PrincipleValueMetrics;
+}
+/* eslint-enable no-unused-vars */
 
 /**
  * WorkspaceContext - Centralized management of workspace-specific paths and services.
  * Implements a cached singleton pattern per workspace directory.
  */
 export class WorkspaceContext {
-    private static instances = new Map<string, WorkspaceContext>();
-    private static pathResolver = new PathResolver();
+    private static readonly instances = new Map<string, WorkspaceContext>();
+    private static readonly pathResolver = new PathResolver();
 
     public readonly workspaceDir: string;
     public readonly stateDir: string;
@@ -26,6 +46,8 @@ export class WorkspaceContext {
     private _hygiene?: HygieneTracker;
     private _evolutionReducer?: EvolutionReducerImpl;
     private _trajectory?: TrajectoryDatabase;
+    private _principleTreeLedger?: PrincipleTreeLedgerAccessor;
+    private _principleLifecycle?: PrincipleLifecycleService;
 
     private constructor(workspaceDir: string, stateDir: string) {
         this.workspaceDir = workspaceDir;
@@ -78,7 +100,7 @@ export class WorkspaceContext {
      */
     get evolutionReducer(): EvolutionReducerImpl {
         if (!this._evolutionReducer) {
-            this._evolutionReducer = new EvolutionReducerImpl({ workspaceDir: this.workspaceDir });
+            this._evolutionReducer = new EvolutionReducerImpl({ workspaceDir: this.workspaceDir, stateDir: this.stateDir });
         }
         return this._evolutionReducer;
     }
@@ -93,6 +115,47 @@ export class WorkspaceContext {
         return this._trajectory;
     }
 
+    /**
+     * Locked ledger access for principle tree reads and metric writes in this workspace.
+     */
+    get principleTreeLedger(): PrincipleTreeLedgerAccessor {
+        if (!this._principleTreeLedger) {
+            this._principleTreeLedger = {
+                getPrincipleSubtree: (principleId: string) => getPrincipleSubtree(this.stateDir, principleId),
+                updatePrinciple: (principleId: string, updates: Partial<Principle>) =>
+                    updatePrinciple(this.stateDir, principleId, updates),
+                updatePrincipleValueMetrics: (principleId: string, metrics: PrincipleValueMetrics) =>
+                    updatePrincipleValueMetrics(this.stateDir, principleId, metrics),
+            };
+        }
+        return this._principleTreeLedger;
+    }
+
+    /**
+     * Phase 15 lifecycle/read-model surface for metrics, assessments, and route recommendations.
+     */
+    get principleLifecycle(): PrincipleLifecycleService {
+        if (!this._principleLifecycle) {
+            this._principleLifecycle = new PrincipleLifecycleService(this.workspaceDir, this.stateDir);
+        }
+        return this._principleLifecycle;
+    }
+
+    /**
+     * Retrieve active Principle -> Rule -> Implementation subtrees without bypassing reducer authority.
+     */
+    getActivePrincipleSubtrees(): { principle: ActivePrinciple; subtree: PrincipleSubtree }[] {
+        return this.evolutionReducer
+            .getActivePrinciples()
+            .map((principle) => {
+                const subtree = this.principleTreeLedger.getPrincipleSubtree(principle.id);
+                return subtree ? { principle, subtree } : null;
+            })
+            .filter(
+                (entry): entry is { principle: ActivePrinciple; subtree: PrincipleSubtree } => entry !== null,
+            );
+    }
+
     private getTrajectoryOptions(): Omit<TrajectoryDatabaseOptions, 'workspaceDir'> {
         const inlineThreshold = Number(this.config.get('trajectory.blob_inline_threshold_bytes'));
         const busyTimeoutMs = Number(this.config.get('trajectory.busy_timeout_ms'));
@@ -110,12 +173,13 @@ export class WorkspaceContext {
      * Uses PathResolver to handle path normalization and fallback logic.
      * @throws Error if workspaceDir is missing and no fallback available.
      */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Reason: OpenClaw plugin framework hook context has dynamic shape - type not available
     static fromHookContext(ctx: any): WorkspaceContext {
-        const logger = ctx.logger;
+        const {logger} = ctx;
         const log = (msg: string) => logger?.info?.(msg);
         const logWarn = (msg: string) => logger?.warn?.(msg);
 
-        let workspaceDir = ctx.workspaceDir;
+        let {workspaceDir} = ctx;
         
         if (!workspaceDir) {
             logWarn('[PD:WorkspaceContext] workspaceDir not provided in context, using PathResolver fallback');
@@ -132,7 +196,7 @@ export class WorkspaceContext {
         const existing = this.instances.get(workspaceDir);
         if (existing) return existing;
 
-        let stateDir = ctx.stateDir;
+        let {stateDir} = ctx;
         if (!stateDir) {
             stateDir = resolvePdPath(workspaceDir, 'STATE_DIR');
             log(`[PD:WorkspaceContext] Computed stateDir: ${stateDir}`);
@@ -162,6 +226,8 @@ export class WorkspaceContext {
         this._dictionary = undefined;
         this._evolutionReducer = undefined;
         this._trajectory = undefined;
+        this._principleTreeLedger = undefined;
+        this._principleLifecycle = undefined;
     }
 
     /**

package/src/core/workspace-dir-validation.ts

@@ -0,0 +1,152 @@
+/**
+ * WorkspaceDir Validation Utilities
+ *
+ * Provides runtime validation of workspaceDir to catch OpenClaw context bugs early.
+ * When a hook receives an invalid workspaceDir, we warn immediately rather than
+ * silently writing to the wrong directory.
+ */
+
+/* eslint-disable no-unused-vars -- Reason: type definitions require param names that implementations may not use */
+
+import * as os from 'os';
+import type { PluginLogger } from '../openclaw-sdk.js';
+
+/**
+ * Check if a path looks like a home directory (not a real workspace).
+ * Returns the reason if suspicious, or null if it looks valid.
+ */
+export function validateWorkspaceDir(dir: string | undefined): string | null {
+  if (!dir) {
+    return 'workspaceDir is undefined/null';
+  }
+  
+  const homeDir = os.homedir();
+  
+  // Home directory itself is not a valid workspace
+  if (dir === homeDir) {
+    return `workspaceDir equals home directory (${homeDir}), likely missing context field`;
+  }
+  
+  // Root directory is definitely not a workspace
+  if (dir === '/' || dir === '') {
+    return `workspaceDir is root or empty: "${dir}"`;
+  }
+  
+  // Check if it looks like a resolved '.' that went wrong
+  // Common bad patterns:
+  const badPatterns = [
+    // Directly under home without a workspace subdirectory
+    { pattern: new RegExp(`^${homeDir.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}$`), desc: 'is home directory itself' },
+    { pattern: new RegExp(`^${homeDir.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}/$`), desc: 'is home directory with trailing slash' },
+  ];
+  
+  for (const { pattern, desc } of badPatterns) {
+    if (pattern.test(dir)) {
+      return `workspaceDir ${desc}: "${dir}"`;
+    }
+  }
+  
+  return null; // Looks valid
+}
+
+/**
+ * Try to resolve workspaceDir from agentId.
+ * Returns the resolved path if successful and valid, or null.
+ */
+function tryResolveFromAgentId(
+  agentId: string,
+  api: {
+    runtime: { agent: { resolveAgentWorkspaceDir: (config: unknown, agentId: string) => string } };
+    config: unknown;
+  },
+  onWarning: (msg: string) => void,
+): string | null {
+  try {
+    const resolved = api.runtime.agent.resolveAgentWorkspaceDir(api.config, agentId);
+    const issue = validateWorkspaceDir(resolved);
+    if (issue) {
+      onWarning(`agentId resolution returned invalid: "${resolved}" (${issue})`);
+      return null;
+    }
+    return resolved;
+  } catch (err) {
+    onWarning(`failed to resolve from agentId: ${String(err)}`);
+    return null;
+  }
+}
+
+/**
+ * Validate a fallback workspaceDir and warn if invalid.
+ * Returns the path regardless (it's the last resort).
+ */
+function validateFallback(path: string, onWarning: (msg: string) => void): string {
+  const issue = validateWorkspaceDir(path);
+  if (issue) {
+    onWarning(`FINAL FALLBACK "${path}" is also invalid: ${issue}. Events will be written to wrong location!`);
+  }
+  return path;
+}
+
+/**
+ * Resolve workspaceDir with validation and warning.
+ *
+ * Usage:
+ *   const workspaceDir = resolveValidWorkspaceDir(ctx, api, { source: 'after_tool_call' });
+ *
+ * Fallback chain:
+ *   1. ctx.workspaceDir (validated)
+ *   2. api.runtime.agent.resolveAgentWorkspaceDir(config, ctx.agentId)
+ *   3. api.resolvePath('.') (last resort, warns loudly)
+ */
+export function resolveValidWorkspaceDir(
+  ctx: { workspaceDir?: string; agentId?: string },
+  api: {
+    runtime: { agent: { resolveAgentWorkspaceDir: (config: unknown, agentId: string) => string } };
+    config: unknown;
+    resolvePath: (input: string) => string;
+    logger: PluginLogger;
+  },
+  options?: { source?: string; onWarning?: (msg: string) => void },
+): string {
+  const source = options?.source || 'unknown';
+  const onWarning = options?.onWarning || ((msg: string) => api.logger.warn(`[PD:workspaceDir] ${msg}`));
+
+  // 1. Try ctx.workspaceDir
+  if (ctx.workspaceDir) {
+    const issue = validateWorkspaceDir(ctx.workspaceDir);
+    if (issue) {
+      onWarning(`${source}: ctx.workspaceDir="${ctx.workspaceDir}" is invalid: ${issue}`);
+    } else {
+      return ctx.workspaceDir;
+    }
+  }
+
+  // 2. Try agentId resolution
+  if (ctx.agentId) {
+    const fromAgent = tryResolveFromAgentId(ctx.agentId, api, onWarning);
+    if (fromAgent) return fromAgent;
+  }
+
+  // 3. Final fallback
+  return validateFallback(api.resolvePath('.'), onWarning);
+}
+
+/**
+ * Log workspaceDir resolution for debugging.
+ * Call this once during plugin startup to verify hook contexts.
+ */
+export function logWorkspaceDirHealth(ctx: { workspaceDir?: string; agentId?: string }, source: string, api: {
+  runtime: { agent: { resolveAgentWorkspaceDir: (config: unknown, agentId: string) => string } };
+  config: unknown;
+  resolvePath: (input: string) => string;
+  logger: PluginLogger;
+}): void {
+  const resolved = resolveValidWorkspaceDir(ctx, api, { source });
+  const issue = validateWorkspaceDir(resolved);
+  
+  if (issue) {
+    api.logger.error(`[PD:health] ${source}: workspaceDir="${resolved}" - ${issue}`);
+  } else {
+    api.logger.info(`[PD:health] ${source}: workspaceDir="${resolved}" ✓`);
+  }
+}

package/src/hooks/AGENTS.md

@@ -0,0 +1,31 @@
+# src/hooks/ — OpenClaw Lifecycle Hooks
+
+**8 TypeScript files.** Intercepts agent behavior at key moments: prompt building, tool calls, session lifecycle.
+
+## WHERE TO LOOK
+
+| Hook Event | File | What It Does |
+|------------|------|--------------|
+| `before_prompt_build` | `prompt.ts` | Multi-layer context injection: identity, trust, evolution, principles, thinking OS |
+| `before_tool_call` | `gate.ts` | Security gate: trust stage checks, risk path blocking, bash security (Cyrillic de-obfuscation, command tokenization) |
+| `after_tool_call` | `pain.ts` | Pain detection: failure → pain score → `.pain_flag` → evolution queue |
+| `before_compaction` | `lifecycle.ts` | Checkpoints state before context loss |
+| `after_compaction` | `lifecycle.ts` | State recovery |
+| `before_reset` / `session_*` | `lifecycle.ts` | Session lifecycle management |
+| `llm_output` | `llm.ts` | Analyzes LLM responses for pain signals |
+| `subagent_*` | `subagent.ts` | Ensures sub-agents inherit mental models |
+| `before_message_write` | `message-sanitize.ts` | Strips sensitive data from messages |
+| — | `trajectory-collector.ts` | Collects tool call trajectories for SQLite analytics |
+
+## CONVENTIONS
+
+- All hooks receive `HookContext` → use `WorkspaceContext.fromHookContext(ctx)` for services
+- Gate hook is the most security-critical — handles trust stages 1-4, risk paths, bash security
+- Pain hook feeds into EvolutionReducer event sourcing
+- Prompt hook is the main injection point for agent context
+
+## ANTI-PATTERNS
+
+- ❌ Gate hook must fail-closed (invalid regex → block, not allow)
+- ❌ Never modify hook return values after they're computed
+- ❌ Pain hook must not throw — errors are logged, not propagated