principles-disciple 1.72.0 → 1.74.0

package/src/core/shadow-observation-registry.ts

@@ -30,11 +30,10 @@
  *   - Observations are retained until cleanup removes expired entries
  */
 
-import * as fs from 'fs';
 import * as path from 'path';
 import * as crypto from 'crypto';
 import { withLock } from '../utils/file-lock.js';
-import { atomicWriteFileSync } from '../utils/io.js';
+import { JsonFileStore } from './file-store.js';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -170,67 +169,44 @@ export interface ShadowRegistry {
 }
 
 // ---------------------------------------------------------------------------
-// Registry Path
+// Registry Path & Store
 // ---------------------------------------------------------------------------
 
+let _store: Map<string, JsonFileStore<ShadowRegistry>> = new Map();
+
 function getRegistryPath(stateDir: string): string {
   return path.join(stateDir, SHADOW_REGISTRY_FILE);
 }
 
-/**
- * Ensure the registry directory exists.
- */
-function ensureRegistryDir(stateDir: string): void {
-  const registryPath = getRegistryPath(stateDir);
-  const dir = path.dirname(registryPath);
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
+function getStore(stateDir: string): JsonFileStore<ShadowRegistry> {
+  let store = _store.get(stateDir);
+  if (!store) {
+    const filePath = path.join(stateDir, SHADOW_REGISTRY_FILE);
+    store = new JsonFileStore<ShadowRegistry>(filePath, () => ({ observations: [], version: 1 }));
+    _store.set(stateDir, store);
   }
+  return store;
 }
 
 // ---------------------------------------------------------------------------
 // File Operations
 // ---------------------------------------------------------------------------
 
-/**
- * Read the registry from disk. Returns empty registry if missing.
- */
-function readRegistry(stateDir: string): ShadowRegistry {
-  const registryPath = getRegistryPath(stateDir);
-  if (!fs.existsSync(registryPath)) {
-    return { observations: [], version: 1 };
-  }
-  try {
-    const content = fs.readFileSync(registryPath, 'utf-8');
-    return JSON.parse(content) as ShadowRegistry;
-  } catch (err) {
-    console.warn(`[shadow-observation-registry] Registry corrupted at ${registryPath}, recovering with empty state: ${String(err)}`);
-    return { observations: [], version: 1 };
-  }
-}
-
-/**
- * Write the registry to disk atomically.
- */
-function writeRegistry(stateDir: string, registry: ShadowRegistry): void {
-  ensureRegistryDir(stateDir);
-  const registryPath = getRegistryPath(stateDir);
-  atomicWriteFileSync(registryPath, JSON.stringify(registry, null, 2));
-}
-
 /**
  * Execute a read-modify-write under an exclusive file lock.
  */
- 
 function withShadowRegistryLock<T>(
   stateDir: string,
   fn: (_registry: ShadowRegistry) => T
 ): T {
- 
-  const registryPath = getRegistryPath(stateDir);
-  return withLock(registryPath, () => {
-    const registry = readRegistry(stateDir);
-    return fn(registry);
+  const store = getStore(stateDir);
+  const filePath = getRegistryPath(stateDir);
+  // Re-create lock behavior using the store's mutate under a simple fs-based lock
+  return withLock(filePath, () => {
+    const registry = store.load();
+    const result = fn(registry);
+    store.save(registry);
+    return result;
   });
 }
 
@@ -276,7 +252,6 @@ export function recordShadowRouting(
 
   return withShadowRegistryLock(stateDir, (registry) => {
     registry.observations.push(observation);
-    writeRegistry(stateDir, registry);
     return observation;
   });
 }
@@ -326,7 +301,6 @@ export function completeShadowObservation(
       extra: {},
     };
 
-    writeRegistry(stateDir, registry);
     return observation;
   });
 }
@@ -369,7 +343,6 @@ export function completeShadowObservationByTask(
       extra: {},
     };
 
-    writeRegistry(stateDir, registry);
     return observation;
   });
 }
@@ -506,7 +479,6 @@ export function markObservationsUsedInGate(
         obs.usedInGate = true;
       }
     }
-    writeRegistry(stateDir, registry);
   });
 }
 
@@ -530,7 +502,6 @@ export function cleanupExpiredObservations(
       (o) => o.routedAt >= cutoff
     );
     removed = before - registry.observations.length;
-    writeRegistry(stateDir, registry);
   });
 
   return removed;

package/src/core/trajectory.ts

@@ -861,12 +861,13 @@ export class TrajectoryDatabase {
   listUserTurnsForSession(sessionId: string): {
     id: number;
     turnIndex: number;
+    rawExcerpt: string;
     correctionDetected: boolean;
     correctionCue: string | null;
     createdAt: string;
   }[] {
     const rows = this.db.prepare(`
-      SELECT id, turn_index, correction_detected, correction_cue, created_at
+      SELECT id, turn_index, raw_excerpt, correction_detected, correction_cue, created_at
       FROM user_turns
       WHERE session_id = ?
       ORDER BY turn_index ASC
@@ -875,6 +876,7 @@ export class TrajectoryDatabase {
     return rows.map((row) => ({
       id: Number(row.id),
       turnIndex: Number(row.turn_index),
+      rawExcerpt: String(row.raw_excerpt ?? ''),
       correctionDetected: Boolean(row.correction_detected),
       correctionCue: row.correction_cue ? String(row.correction_cue) : null,
       createdAt: String(row.created_at),

package/src/core/workflow-funnel-loader.ts

@@ -18,16 +18,34 @@ import yaml from 'js-yaml';
 
 /**
  * A single stage in a workflow funnel.
+ * Policy fields are optional — existing stages without policy fields remain valid.
  */
 export interface WorkflowStage {
-  /** Stage name within the funnel (e.g., 'dreamer_completed') */
   name: string;
-  /** Event type string (e.g., 'nocturnal_dreamer_completed') */
   eventType: string;
-  /** Event category (e.g., 'completed', 'created', 'blocked') */
   eventCategory: string;
-  /** Dot-path to stats field (e.g., 'evolution.nocturnalDreamerCompleted') */
   statsField: string;
+  timeoutMs?: number;
+  successCriteria?: string;
+  legacyDisabled?: boolean;
+  observability?: {
+    enabled?: boolean;
+    emitEvents?: string[];
+  };
+}
+
+/**
+ * Funnel-level policy that applies to all stages unless overridden per-stage.
+ */
+export interface FunnelPolicy {
+  timeoutMs?: number;
+  stageOrder?: 'strict' | 'relaxed';
+  legacyDisabled?: boolean;
+  observability?: {
+    enabled?: boolean;
+    emitEvents?: string[];
+    logLevel?: 'debug' | 'info' | 'warn' | 'error';
+  };
 }
 
 /**
@@ -36,6 +54,7 @@ export interface WorkflowStage {
 export interface WorkflowFunnel {
   workflowId: string;
   stages: WorkflowStage[];
+  policy?: FunnelPolicy;
 }
 
 /**
@@ -50,56 +69,31 @@ export interface WorkflowFunnelConfig {
 // WorkflowFunnelLoader
 // ─────────────────────────────────────────────────────────────────────────────
 
-/**
- * Loads and watches workflows.yaml, building an in-memory WORKFLOW_FUNNELS table.
- *
- * Failure semantics (per Codex review):
- * - Missing file: clears in-memory funnels, uses empty Map
- * - Malformed YAML: preserves last known-good config, logs warning
- * - Schema-invalid YAML: same as malformed YAML
- *
- * Usage:
- *   const loader = new WorkflowFunnelLoader(stateDir);
- *   const funnels = loader.getAllFunnels();  // Map<string, WorkflowStage[]>
- *   loader.watch();  // Enable hot reload
- */
 export class WorkflowFunnelLoader {
-  /** In-memory WORKFLOW_FUNNELS table: workflowId -> stages */
   private readonly funnels = new Map<string, WorkflowStage[]>();
-
+  private readonly fullFunnels = new Map<string, WorkflowFunnel>();
   private readonly configPath: string;
-
-  /** fs.watch() handle for cleanup */
   private watchHandle?: fs.FSWatcher;
-
-  /** YAML parse warnings from last load() call */
   private readonly warnings: string[] = [];
 
   constructor(stateDir: string) {
-    // D-02: workflows.yaml in .state/ directory
     this.configPath = path.join(stateDir, 'workflows.yaml');
     this.load();
   }
 
-  /**
-   * Load (or reload) workflows.yaml from disk.
-   * On parse/validation failure, preserves the last known-good config.
-   * On missing file, clears to empty.
-   */
   load(): void {
-    this.warnings.length = 0; // reset warnings on each load
+    this.warnings.length = 0;
     if (!fs.existsSync(this.configPath)) {
       this.warnings.push('workflows.yaml file not found.');
       this.funnels.clear();
+      this.fullFunnels.clear();
       return;
     }
 
     try {
       const content = fs.readFileSync(this.configPath, 'utf-8');
-      // Use safe load — no arbitrary code execution
       const config = yaml.load(content, { schema: yaml.DEFAULT_SCHEMA }) as WorkflowFunnelConfig;
 
-      // Validate top-level structure
       if (!config || typeof config.version !== 'string' || !Array.isArray(config.funnels)) {
         const msg = 'workflows.yaml validation failed: missing version or funnels array. Preserving last valid config.';
         console.warn(`[WorkflowFunnelLoader] ${msg}`);
@@ -107,11 +101,12 @@ export class WorkflowFunnelLoader {
         return;
       }
 
-      // Rebuild funnels map
       const newFunnels = new Map<string, WorkflowStage[]>();
+      const newFullFunnels = new Map<string, WorkflowFunnel>();
       for (const funnel of config.funnels) {
         if (funnel?.workflowId && typeof funnel.workflowId === 'string' && Array.isArray(funnel.stages)) {
           newFunnels.set(funnel.workflowId, funnel.stages);
+          newFullFunnels.set(funnel.workflowId, funnel);
         } else {
           const msg = 'Skipping invalid funnel entry: missing workflowId or stages.';
           console.warn(`[WorkflowFunnelLoader] ${msg}`);
@@ -119,44 +114,28 @@ export class WorkflowFunnelLoader {
         }
       }
 
-      // Atomic replace: only commit if entire parse/validation succeeded
       this.funnels.clear();
-      for (const [k, v] of newFunnels) {
-        this.funnels.set(k, v);
-      }
+      this.fullFunnels.clear();
+      for (const [k, v] of newFunnels) { this.funnels.set(k, v); }
+      for (const [k, v] of newFullFunnels) { this.fullFunnels.set(k, v); }
     } catch (err) {
-      // Best-effort: preserve last known-good config on parse error
       const msg = `Failed to parse workflows.yaml: ${String(err)}. Preserving last valid config.`;
       console.warn(`[WorkflowFunnelLoader] ${msg}`);
       this.warnings.push(msg);
     }
   }
 
-  /**
-   * Start watching workflows.yaml for changes.
-   * Calls load() automatically when the file changes.
-   * No-op if the config file does not exist.
-   */
   watch(): void {
-    // WATCHER-01: re-entry guard — prevent FSWatcher leak on double-watch
     if (this.watchHandle) return;
-    // Guard: fs.watch fails with ENOENT if the path does not exist
     if (!fs.existsSync(this.configPath)) return;
-    // Debounce: only re-read after file write settles (100ms)
     let debounceTimer: ReturnType<typeof setTimeout> | undefined;
     this.watchHandle = fs.watch(this.configPath, (eventType) => {
-      // PLAT-01: handle both 'change' and 'rename' events for Windows compatibility
       if (eventType !== 'change' && eventType !== 'rename') return;
       if (debounceTimer) clearTimeout(debounceTimer);
-      debounceTimer = setTimeout(() => {
-        this.load();
-      }, 100);
+      debounceTimer = setTimeout(() => this.load(), 100);
     });
   }
 
-  /**
-   * Stop watching and clean up the FSWatcher.
-   */
   dispose(): void {
     if (this.watchHandle) {
       this.watchHandle.close();
@@ -164,38 +143,53 @@ export class WorkflowFunnelLoader {
     }
   }
 
-  /**
-   * Get all stages for a workflow.
-   */
   getStages(workflowId: string): WorkflowStage[] {
     return this.funnels.get(workflowId) ?? [];
   }
 
-  /**
-   * Get the full WORKFLOW_FUNNELS table.
-   * Returns a deep clone — consumer mutations do not affect internal state.
-   */
+  getFunnel(workflowId: string): WorkflowFunnel | undefined {
+    const funnel = this.fullFunnels.get(workflowId);
+    if (!funnel) return undefined;
+    return this.cloneFunnel(funnel);
+  }
+
   getAllFunnels(): Map<string, WorkflowStage[]> {
     const result = new Map<string, WorkflowStage[]>();
     for (const [k, v] of this.funnels) {
-      // WATCHER-03: deep-clone arrays and stage objects
       result.set(k, v.map(stage => ({ ...stage })));
     }
     return result;
   }
 
-  /**
-   * Returns warnings from the last load() call.
-   * Callers can inspect these and propagate them to metadata.warnings.
-   */
+  getAllFunnelsWithPolicy(): Map<string, WorkflowFunnel> {
+    const result = new Map<string, WorkflowFunnel>();
+    for (const [k, v] of this.fullFunnels) {
+      result.set(k, this.cloneFunnel(v));
+    }
+    return result;
+  }
+
   getWarnings(): string[] {
     return [...this.warnings];
   }
 
-  /**
-   * Get the config file path (for testing/debugging).
-   */
   getConfigPath(): string {
     return this.configPath;
   }
+
+  private cloneFunnel(funnel: WorkflowFunnel): WorkflowFunnel {
+    return {
+      ...funnel,
+      stages: funnel.stages.map(stage => ({ ...stage })),
+      policy: funnel.policy ? {
+        ...funnel.policy,
+        observability: funnel.policy.observability ? {
+          ...funnel.policy.observability,
+          emitEvents: funnel.policy.observability.emitEvents
+            ? [...funnel.policy.observability.emitEvents]
+            : undefined,
+        } : undefined,
+      } : undefined,
+    };
+  }
 }

package/src/core/workspace-context.ts

@@ -1,6 +1,7 @@
 import type { PD_FILES } from './paths.js';
 import { resolvePdPath } from './paths.js';
 import { PathResolver } from './path-resolver.js';
+import { validateWorkspaceDir } from './workspace-dir-validation.js';
 import { ConfigService } from './config-service.js';
 import type { PainConfig } from './config.js';
 import type { EventLog } from './event-log.js';
@@ -193,6 +194,14 @@ export class WorkspaceContext {
             }
         }
 
+        const validationIssue = validateWorkspaceDir(workspaceDir);
+        if (validationIssue !== null) {
+            logWarn(
+                `[PD:WorkspaceContext] LEGACY_PATH_RESOLVER_FALLBACK: ${validationIssue}. ` +
+                'This is a legacy discovery path; explicit workspaceDir should be provided in the hook context.',
+            );
+        }
+
         const existing = this.instances.get(workspaceDir);
         if (existing) return existing;
 
@@ -210,6 +219,43 @@ export class WorkspaceContext {
         return instance;
     }
 
+    /**
+     * Creates a WorkspaceContext requiring explicit workspaceDir.
+     * For Runtime V2 entrypoints where implicit PathResolver fallback is unacceptable.
+     * @throws Error if workspaceDir is not provided in the context.
+     */
+    static fromHookContextExplicit(ctx: { workspaceDir?: string; logger?: { error?: (...args: unknown[]) => void; warn?: (...args: unknown[]) => void; info?: (...args: unknown[]) => void } }): WorkspaceContext {
+        const { logger } = ctx;
+        let { workspaceDir } = ctx;
+        if (!workspaceDir || !workspaceDir.trim()) {
+            const error = {
+                ok: false as const,
+                reason: 'workspace_dir_missing',
+                message: 'workspaceDir is required for Runtime V2 entrypoints. Provide it explicitly in the hook context.',
+                nextAction: 'Ensure the OpenClaw hook context includes workspaceDir, or use PD_WORKSPACE_DIR env var.',
+            };
+            logger?.error?.(`[PD:WorkspaceContext] ${error.message}`);
+            throw new Error(`[PD:WorkspaceContext] ${error.reason}: ${error.message}`);
+        }
+        const normalized = this.pathResolver.normalizeWorkspacePath(workspaceDir);
+        if (normalized !== workspaceDir) {
+            logger?.info?.(`[PD:WorkspaceContext] Normalized workspaceDir before validation: ${workspaceDir} -> ${normalized}`);
+            workspaceDir = normalized;
+        }
+        const validationIssue = validateWorkspaceDir(workspaceDir);
+        if (validationIssue !== null) {
+            const error = {
+                ok: false as const,
+                reason: 'workspace_dir_invalid',
+                message: `workspaceDir validation failed for Runtime V2 entrypoint: ${validationIssue}`,
+                nextAction: 'Provide a valid workspaceDir that is not the home directory, root, or empty.',
+            };
+            logger?.error?.(`[PD:WorkspaceContext] ${error.message}`);
+            throw new Error(`[PD:WorkspaceContext] ${error.reason}: ${error.message}`);
+        }
+        return this.fromHookContext({ ...ctx, workspaceDir });
+    }
+
     /**
      * Resolves a PD file path within the workspace.
      */

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

@@ -19,7 +19,7 @@ function tryResolveFromAgent(
   attempts: string[],
 ): string | undefined {
   try {
-    const resolved = api.runtime.agent.resolveAgentWorkspaceDir(api.config, agentId);
+    const resolved = api.runtime?.agent?.resolveAgentWorkspaceDir?.(api.config, agentId);
     const issue = validateWorkspaceDir(resolved);
     if (!issue) {
       return resolved;

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

@@ -1,4 +1,4 @@
-/**
+/**
  * WorkspaceDir Validation Utilities
  *
  * This module only validates candidate workspace directories and delegates
@@ -6,6 +6,7 @@
  */
 
 import * as os from 'os';
+import * as path from 'path';
 
 export interface WorkspaceResolutionContext {
   workspaceDir?: string;
@@ -17,27 +18,35 @@ export function validateWorkspaceDir(dir: string | undefined): string | null {
     return 'workspaceDir is undefined/null';
   }
 
+  if (/^[A-Za-z]:\\?$/.test(dir)) {
+    return `workspaceDir is a drive root: "${dir}"`;
+  }
+
+  const resolved = path.resolve(dir);
   const homeDir = os.homedir();
 
-  if (dir === homeDir) {
+  if (resolved === homeDir) {
     return `workspaceDir equals home directory (${homeDir}), likely missing context field`;
   }
 
-  if (dir === '/' || dir === '') {
-    return `workspaceDir is root or empty: "${dir}"`;
+  if (resolved === '/' || resolved === '') {
+    return `workspaceDir is root or empty: "${resolved}"`;
+  }
+
+  if (/^[A-Za-z]:\\?$/.test(resolved)) {
+    return `workspaceDir is a drive root: "${resolved}"`;
   }
 
   const escapedHome = homeDir.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
   const badPatterns = [
-    { pattern: new RegExp(`^${escapedHome}$`), desc: 'is home directory itself' },
-    { pattern: new RegExp(`^${escapedHome}/$`), desc: 'is home directory with trailing slash' },
+    { pattern: new RegExp(`^${escapedHome}[\\\\/]?$`), desc: 'is home directory' },
   ];
 
   for (const { pattern, desc } of badPatterns) {
-    if (pattern.test(dir)) {
-      return `workspaceDir ${desc}: "${dir}"`;
+    if (pattern.test(resolved)) {
+      return `workspaceDir ${desc}: "${resolved}"`;
     }
   }
 
   return null;
-}
+}

package/src/hooks/AGENTS.md

@@ -8,7 +8,7 @@
 |------------|------|--------------|
 | `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 |
+| `after_tool_call` | `pain.ts` | Pain detection: failure → pain score → Runtime V2 `PainSignalBridge` |
 | `before_compaction` | `lifecycle.ts` | Checkpoints state before context loss |
 | `after_compaction` | `lifecycle.ts` | State recovery |
 | `before_reset` / `session_*` | `lifecycle.ts` | Session lifecycle management |