principles-disciple 1.16.0 → 1.17.0

package/src/core/promotion-gate.ts

@@ -70,7 +70,7 @@ export const DEFAULT_ALLOWED_MARGIN = 0.05;
  * Allowed worker profiles for Phase 7 shadow rollout.
  * Only bounded local workers eligible. local-reader first, local-editor deferred.
  */
-// eslint-disable-next-line no-unused-vars, @typescript-eslint/no-unused-vars -- Reason: reserved for Phase 7 shadow rollout profile validation
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- Reason: reserved for Phase 7 shadow rollout profile validation
 const ALLOWED_ROLLOUT_PROFILES: readonly TrainableWorkerProfile[] = ['local-reader'];
 
 /**
@@ -233,7 +233,7 @@ function writeRegistry(stateDir: string, registry: PromotionRegistry): void {
  */
 function withPromotionRegistryLock<T>(
   stateDir: string,
-  // eslint-disable-next-line no-unused-vars -- Reason: callback parameter name is type documentation, actual value passed at call site
+   
   fn: (_registry: PromotionRegistry) => T
 ): T {
   const registryPath = getRegistryPath(stateDir);
@@ -318,7 +318,7 @@ export function evaluatePromotionGate(
 ): PromotionGateResult {
   const {
     checkpointId,
-    // eslint-disable-next-line no-unused-vars, @typescript-eslint/no-unused-vars -- Reason: reserved for Phase 7 profile-based targeting
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars -- Reason: reserved for Phase 7 profile-based targeting
     targetProfile: _targetProfile,
     baselineMetrics,
     minDelta = DEFAULT_MIN_DELTA,
@@ -388,9 +388,9 @@ export function evaluatePromotionGate(
   // PREFER real shadow evidence over eval verdict proxy
   // Shadow evidence comes from actual runtime routing decisions
   const shadowStats = computeShadowStats(stateDir, { checkpointId });
-  // eslint-disable-next-line @typescript-eslint/init-declarations -- assigned in both if/else branches
+   
   let arbiterRejectRate: number;
-  // eslint-disable-next-line @typescript-eslint/init-declarations -- assigned in both if/else branches
+   
   let arbiterRejectSource: 'shadow' | 'eval-proxy';
 
   if (shadowStats && shadowStats.isStatisticallySignificant) {
@@ -424,9 +424,9 @@ export function evaluatePromotionGate(
 
   // --- Check 6: Executability reject rate constraint ---
   // PREFER real shadow evidence: escalation rate + profile rejection rate
-  // eslint-disable-next-line @typescript-eslint/init-declarations -- assigned in both if/else branches
+   
   let executabilityRejectRate: number;
-  // eslint-disable-next-line @typescript-eslint/init-declarations -- assigned in both if/else branches
+   
   let executabilityRejectSource: 'shadow' | 'eval-proxy';
 
   if (shadowStats && shadowStats.isStatisticallySignificant) {
@@ -484,7 +484,7 @@ export function evaluatePromotionGate(
     qualityCheck.passed;
 
   // --- Suggest state based on checks ---
-  // eslint-disable-next-line @typescript-eslint/init-declarations -- assigned in all branches
+   
   let suggestedState: PromotionState | undefined;
   if (allPassed) {
     suggestedState = 'candidate_only';
@@ -585,7 +585,7 @@ export function advancePromotion(
     // - rejected → candidate_only/shadow_ready: allowed via re-evaluation
     //   (new eval data may reverse a previous rejection)
     //
-    // eslint-disable-next-line @typescript-eslint/init-declarations -- assigned in all branches
+     
     let targetState: PromotionState;
     if (!gateResult.passes) {
       targetState = 'rejected';

package/src/core/replay-engine.ts

@@ -69,9 +69,9 @@ export interface ReplayReport {
 }
 
 export interface CandidateEvaluator {
-  /* eslint-disable no-unused-vars -- Reason: interface method params are type signatures */
+   
   evaluate(sample: unknown): { passed: boolean; reason?: string; decision: string };
-  /* eslint-enable no-unused-vars */
+   
 }
 
 export class ReplayEngine {
@@ -112,7 +112,7 @@ export class ReplayEngine {
     return samples;
   }
 
-  // eslint-disable-next-line @typescript-eslint/class-methods-use-this -- Reason: Public API method that delegates to evaluator, no instance state needed
+   
   runSingleSample(sample: ReplaySample, evaluator: CandidateEvaluator): ReplayResult {
     const evaluation = evaluator.evaluate(sample);
     return {
@@ -202,12 +202,12 @@ export class ReplayEngine {
       throw new Error(`Implementation ${implementation.id} does not export evaluate().`);
     }
 
-    /* eslint-disable no-unused-vars -- Reason: type-only parameters in type cast, not used at runtime */
+     
     const evaluate = moduleExports.evaluate as (
       _input: RuleHostInput,
       _helpers: RuleHostHelpers,
     ) => RuleHostResult;
-    /* eslint-enable no-unused-vars */
+     
 
     return {
       evaluate: (sample: unknown) => {
@@ -284,7 +284,7 @@ export class ReplayEngine {
     };
   }
 
-  // eslint-disable-next-line @typescript-eslint/class-methods-use-this -- Reason: Private helper doesn't use instance state
+   
   private _selectToolCall(
     snapshot: NocturnalSessionSnapshot,
     classification: SampleClassification,
@@ -314,7 +314,7 @@ export class ReplayEngine {
     return byNewest[0] ?? null;
   }
 
-  // eslint-disable-next-line @typescript-eslint/class-methods-use-this -- Reason: Private helper doesn't use instance state
+   
   private _matchGateBlock(
     gateBlocks: NocturnalGateBlock[],
     toolCall: NocturnalToolCall,
@@ -351,7 +351,7 @@ export class ReplayEngine {
     }
   }
 
-  // eslint-disable-next-line @typescript-eslint/class-methods-use-this -- Reason: Private helper doesn't use instance state
+   
   private _estimateLineChanges(toolCall: NocturnalToolCall): number {
     if (toolCall.toolName === 'edit' || toolCall.toolName === 'write') {
       return 20;
@@ -359,7 +359,7 @@ export class ReplayEngine {
     return 0;
   }
 
-  // eslint-disable-next-line @typescript-eslint/class-methods-use-this -- Reason: Private helper doesn't use instance state
+   
   private _inferBashRisk(toolCall: NocturnalToolCall): 'safe' | 'normal' | 'dangerous' | 'unknown' {
     if (toolCall.toolName !== 'bash' && toolCall.toolName !== 'run_shell_command') {
       return 'unknown';
@@ -371,7 +371,7 @@ export class ReplayEngine {
     return toolCall.outcome === 'success' ? 'safe' : 'normal';
   }
 
-  // eslint-disable-next-line @typescript-eslint/class-methods-use-this -- Reason: Private helper doesn't use instance state
+   
   private _scoreEvaluation(
     sample: ReplaySample,
     result: RuleHostResult,
@@ -465,7 +465,7 @@ export class ReplayEngine {
     };
   }
 
-  // eslint-disable-next-line @typescript-eslint/class-methods-use-this -- Reason: Private helper doesn't use instance state
+   
   private _determineDecision(
     pain: ClassificationSummary,
     success: ClassificationSummary,
@@ -495,7 +495,7 @@ export class ReplayEngine {
     });
   }
 
-  // eslint-disable-next-line @typescript-eslint/class-methods-use-this -- Reason: Private helper doesn't use instance state
+   
   private _deriveExpectedOutcome(
     record: NocturnalDatasetRecord,
   ): ReplaySample['expectedOutcome'] {

package/src/core/risk-calculator.ts

@@ -93,7 +93,7 @@ export function getTargetFileLineCount(absoluteFilePath: string): number | null
  * @param maxLines - Optional upper bound to prevent misconfiguration
  * @returns Maximum allowed lines (at least minLines, at most maxLines if provided)
  */
-// eslint-disable-next-line @typescript-eslint/max-params -- Reason: percentage threshold calculation requires all 4 params - refactoring would break API
+ 
 export function calculatePercentageThreshold(
     targetLineCount: number,
     percentage: number,

package/src/core/rule-host-types.ts

@@ -76,7 +76,7 @@ export interface LoadedImplementation {
   implId: string;
   ruleId: string;
   meta: RuleHostMeta;
-  /* eslint-disable no-unused-vars -- Reason: _input parameter name in interface type definition intentionally unused - actual implementation uses different param names */
+   
   evaluate: (_input: RuleHostInput) => RuleHostResult;
-  /* eslint-enable no-unused-vars */
+   
 }

package/src/core/rule-host.ts

@@ -36,9 +36,9 @@ import type {
 import type { Implementation } from '../types/principle-tree-schema.js';
 
 export interface RuleHostLogger {
-  /* eslint-disable no-unused-vars -- Reason: logger callback param name intentionally unused - callback only invoked for side effects */
+   
   warn?: (_message: string) => void;
-  /* eslint-enable no-unused-vars */
+   
 }
 
 export class RuleHost {
@@ -69,7 +69,7 @@ export class RuleHost {
       }
 
       // Merge decisions from all active implementations
-      // eslint-disable-next-line @typescript-eslint/init-declarations -- undefined is valid zero value, checked before use
+       
       let blocked: RuleHostResult | undefined;
       const approvals: RuleHostResult[] = [];
 
@@ -218,12 +218,12 @@ export class RuleHost {
 
       // Return a loaded implementation that wraps the compiled evaluate
       // with the actual helpers from the input at evaluation time
-      /* eslint-disable no-unused-vars -- Reason: type cast params intentionally unused - they're just type annotations, actual function uses different params */
+       
       const rawEvaluate = moduleExports.evaluate as (
         _input: RuleHostInput,
         _helpers: ReturnType<typeof createRuleHostHelpers>
       ) => RuleHostResult;
-      /* eslint-enable no-unused-vars */
+       
 
       return {
         implId: impl.id,

package/src/core/schema/db-types.ts

@@ -3,7 +3,7 @@
  * Kept separate to avoid circular dependencies between schema-definitions and migration-runner.
  */
 
-/* eslint-disable no-unused-vars -- Reason: interface method param names are part of type signature */
+ 
 
 /** Minimal interface for better-sqlite3 Database instances. */
 export interface Db {

package/src/core/schema/schema-definitions.ts

@@ -35,7 +35,7 @@ export interface Migration {
   name: string;
   /** Which database file this migration applies to */
   db: DbType;
-  /* eslint-disable no-unused-vars -- Reason: interface callback params are part of type signature */
+   
   /** Apply this migration */
   up: (_db: Db) => void;
   /** Revert this migration */

package/src/core/session-tracker.ts

@@ -33,6 +33,7 @@ export interface SessionState {
     lastErrorSource?: string;
     lastErrorHash: string;
     consecutiveErrors: number;
+    lastGfiDecayAt?: number;  // Timestamp of last GFI decay (for time-based decay)
     
     // Daily statistics (persisted)
     dailyToolCalls: number;
@@ -82,7 +83,7 @@ export function initPersistence(stateDir: string): void {
     }
     
     // Load all existing sessions
-    // eslint-disable-next-line @typescript-eslint/no-use-before-define -- Reason: loadAllSessions is defined later in this file, called here for organizational reasons
+     
     loadAllSessions();
 }
 
@@ -138,6 +139,14 @@ function persistSession(state: SessionState): void {
     
     try {
         fs.writeFileSync(sessionPath, JSON.stringify(state, null, 2), 'utf-8');
+        // Log successful persistence with GFI snapshot for debugging
+        if (state.currentGfi > 0) {
+            SystemLogger.log(
+                state.workspaceDir,
+                'GFI_PERSIST',
+                `Session ${state.sessionId.slice(0, 8)} persisted: GFI=${state.currentGfi.toFixed(1)}, sources=${JSON.stringify(state.gfiBySource)}`
+            );
+        }
     } catch (error) {
         logSessionTrackerWarning(`Failed to persist session ${state.sessionId}`, error);
     }
@@ -171,7 +180,7 @@ export function flushAllSessions(): void {
     }
 }
 
-// eslint-disable-next-line @typescript-eslint/max-params -- Reason: session creation requires all 4 params (sessionId, workspaceDir, sessionKey, trigger) - refactoring would break API
+ 
 function getOrCreateSession(sessionId: string, workspaceDir?: string, sessionKey?: string, trigger?: string): SessionState {
     let state = sessions.get(sessionId);
     if (!state) {
@@ -194,6 +203,7 @@ function getOrCreateSession(sessionId: string, workspaceDir?: string, sessionKey
             lastErrorSource: '',
             lastErrorHash: '',
             consecutiveErrors: 0,
+            lastGfiDecayAt: Date.now(),
             dailyToolCalls: 0,
             dailyToolFailures: 0,
             dailyPainSignals: 0,
@@ -232,7 +242,7 @@ export function trackToolRead(sessionId: string, filePath: string, workspaceDir?
     return state;
 }
 
-// eslint-disable-next-line @typescript-eslint/max-params -- Reason: LLM output tracking requires all 6 params - refactoring would break API
+ 
 export function trackLlmOutput(sessionId: string, usage: TokenUsage | undefined, config?: PainConfig, workspaceDir?: string, sessionKey?: string, trigger?: string): SessionState {
     const state = getOrCreateSession(sessionId, workspaceDir, sessionKey, trigger);
     state.llmTurns += 1;
@@ -271,7 +281,7 @@ export function trackLlmOutput(sessionId: string, usage: TokenUsage | undefined,
 /**
  * Tracks physical friction based on tool execution failures.
  */
-// eslint-disable-next-line @typescript-eslint/max-params -- Reason: friction tracking requires all 5 params - refactoring would break API
+ 
 export function trackFriction(
     sessionId: string,
     deltaF: number,
@@ -305,6 +315,8 @@ export function trackFriction(
     state.dailyGfiPeak = Math.max(state.dailyGfiPeak, state.currentGfi);
     
     // Schedule persistence
+    // Update decay anchor to prevent retroactive decay of the new friction
+    state.lastGfiDecayAt = Date.now();
     schedulePersistence(state);
     
     return state;
@@ -516,3 +528,83 @@ export function resetDailyStats(sessionId: string): void {
         schedulePersistence(state);
     }
 }
+
+/**
+ * Apply time-based decay to GFI using segmented exponential decay.
+ * 
+ * Decay rates:
+ * - GFI >= 70 (severe): 3%/min - fast recovery to avoid prolonged blocking
+ * - GFI 40-70 (moderate): 2%/min - medium decay
+ * - GFI < 40 (mild): 1%/min - slow decay to retain as warning
+ * 
+ * Formula: GFI_new = GFI * (1 - λ)^elapsedMinutes
+ * 
+ * @param sessionId - The session to decay
+ * @param elapsedMinutes - Minutes since last decay
+ * @returns Updated session state, or undefined if session not found or GFI is 0
+ */
+export function decayGfi(sessionId: string, elapsedMinutes: number): SessionState | undefined {
+    const state = sessions.get(sessionId);
+    if (!state || state.currentGfi <= 0 || elapsedMinutes <= 0) return undefined;
+    
+    // Determine decay rate based on current GFI level (segmented)
+    let decayRate: number;
+    if (state.currentGfi >= 70) {
+      decayRate = 0.03;  // 3%/min for severe friction
+    } else if (state.currentGfi >= 40) {
+      decayRate = 0.02;  // 2%/min for moderate friction
+    } else {
+      decayRate = 0.01;  // 1%/min for mild friction
+    }
+    
+    // Exponential decay: GFI_new = GFI * (1-λ)^Δt
+    const decayFactor = Math.pow(1 - decayRate, elapsedMinutes);
+    const previousGfi = state.currentGfi;
+    state.currentGfi = Math.max(0, state.currentGfi * decayFactor);
+    
+    // Apply same decay factor to all sources
+    const ledger = ensureGfiLedger(state);
+    for (const source of Object.keys(ledger)) {
+      ledger[source] = Math.max(0, ledger[source] * decayFactor);
+      // Remove sources that have decayed below 0.1
+      if (ledger[source] < 0.1) {
+        delete ledger[source];
+      }
+    }
+    
+    // Round to 1 decimal place
+    state.currentGfi = Math.round(state.currentGfi * 10) / 10;
+    
+    // Update last decay timestamp
+    state.lastGfiDecayAt = Date.now();
+    
+    // Log if significant decay
+    const decayedAmount = previousGfi - state.currentGfi;
+    if (decayedAmount >= 1) {
+      SystemLogger.log(
+        state.workspaceDir,
+        'GFI_DECAY',
+        `GFI decayed by ${decayedAmount.toFixed(1)} (${elapsedMinutes}min at ${decayRate*100}%/min). ${previousGfi.toFixed(1)} → ${state.currentGfi.toFixed(1)}`
+      );
+    }
+    
+    schedulePersistence(state);
+    return state;
+}
+
+/**
+ * Check if GFI decay should be applied and return elapsed minutes since last decay.
+ * @param sessionId - The session to check
+ * @returns Elapsed minutes since last decay, or 0 if no decay needed
+ */
+export function getGfiDecayElapsed(sessionId: string): number {
+  const state = sessions.get(sessionId);
+  if (!state || state.currentGfi <= 0) return 0;
+  
+  const now = Date.now();
+  const lastDecay = state.lastGfiDecayAt || state.lastControlActivityAt || state.lastActivityAt || now;
+  const elapsedMs = now - lastDecay;
+  
+  // Return elapsed minutes (floor to whole minutes)
+  return Math.floor(elapsedMs / 60000);
+}

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

@@ -222,12 +222,12 @@ function writeRegistry(stateDir: string, registry: ShadowRegistry): void {
 /**
  * Execute a read-modify-write under an exclusive file lock.
  */
-/* eslint-disable no-unused-vars -- Reason: registry param name in type signature intentionally unused - actual function uses different param name */
+ 
 function withShadowRegistryLock<T>(
   stateDir: string,
   fn: (_registry: ShadowRegistry) => T
 ): T {
-/* eslint-enable no-unused-vars */
+ 
   const registryPath = getRegistryPath(stateDir);
   return withLock(registryPath, () => {
     const registry = readRegistry(stateDir);
@@ -341,7 +341,7 @@ export function completeShadowObservation(
  * @param failureSignals - Runtime failure signals
  * @returns The updated ShadowObservation, or null if not found
  */
-// eslint-disable-next-line @typescript-eslint/max-params -- Reason: shadow observation completion requires all 4 params - refactoring would break API
+ 
 export function completeShadowObservationByTask(
   stateDir: string,
   taskFingerprint: string,

package/src/core/system-logger.ts

@@ -25,10 +25,10 @@ export const SystemLogger = {
             const logEntry = `[${timestamp}] [${eventType.padEnd(15)}] ${message}\n`;
             
             // Use fire-and-forget async append to prevent blocking
-            fs.appendFile(logFile, logEntry, 'utf8', (_err) => { // eslint-disable-line @typescript-eslint/no-unused-vars, no-unused-vars -- Reason: fire-and-forget, errors silently dropped
+            fs.appendFile(logFile, logEntry, 'utf8', (_err) => {  
                 // Silently drop errors (e.g. disk full) to not crash the gateway
             });
-        } catch (e) { // eslint-disable-line @typescript-eslint/no-unused-vars, no-unused-vars -- Reason: intentionally unused - silently fail if we can't setup the log
+        } catch (e) { // eslint-disable-line @typescript-eslint/no-unused-vars -- Reason: intentionally unused - silently fail if we can't setup the log
             // Silently fail if we can't setup the log
         }
     }

package/src/core/thinking-os-parser.ts

@@ -44,7 +44,7 @@ export function parseThinkingOsMd(content: string): ThinkingOsDirective[] {
 
   // Match all <directive ...> ... </directive> blocks
   const directiveRegex = /<directive\s+([^>]*)>([\s\S]*?)<\/directive>/gi;
-  /* eslint-disable @typescript-eslint/init-declarations, @typescript-eslint/no-use-before-define, @typescript-eslint/prefer-destructuring, no-useless-assignment, @typescript-eslint/no-unused-vars */
+   
   let match: RegExpExecArray | null = null;
 
   while ((match = directiveRegex.exec(content)) !== null) {

package/src/core/training-program.ts

@@ -565,9 +565,9 @@ export function processTrainerResult(
  * ```
  */
 export class TrainingProgram {
-  /* eslint-disable no-unused-vars -- Reason: stateDir is used via this.stateDir in createExperiment method */
+   
   constructor(private readonly stateDir: string) {}
-  /* eslint-enable no-unused-vars */
+   
 
   /**
    * Create a new training experiment.

package/src/core/trajectory.ts

@@ -208,7 +208,7 @@ 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;
-    /* eslint-disable @typescript-eslint/no-unused-vars, no-unused-vars -- Reason: _filePath extracted for potential future use but currently unused */
+    /* eslint-disable @typescript-eslint/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(`
@@ -587,7 +587,7 @@ export class TrajectoryDatabase {
     const limit = filters.limit ?? 100;
     const offset = filters.offset ?? 0;
 
-    // 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(`
@@ -783,7 +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 {
@@ -1324,7 +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;
@@ -1545,7 +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,
@@ -1610,7 +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);
@@ -1660,9 +1660,9 @@ export class TrajectoryRegistry {
     this.instances.clear();
   }
 
-  /* 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

@@ -21,13 +21,13 @@ import {
 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.

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

@@ -0,0 +1,85 @@
+import type { OpenClawPluginApi, PluginLogger } from '../openclaw-sdk.js';
+import { validateWorkspaceDir } from './workspace-dir-validation.js';
+
+export interface WorkspaceResolutionContext {
+  workspaceDir?: string;
+  agentId?: string;
+}
+
+export interface WorkspaceResolutionOptions {
+  source?: string;
+  required?: boolean;
+  fallbackAgentId?: string;
+  logger?: PluginLogger;
+}
+
+function buildResolutionFailureMessage(source: string, attempts: string[]): string {
+  const suffix = attempts.length > 0 ? ` Attempts: ${attempts.join(' | ')}` : '';
+  return `[PD:WorkspaceDir] ${source}: unable to resolve a valid workspace directory.${suffix}`;
+}
+
+function tryResolveFromAgent(
+  api: OpenClawPluginApi,
+  agentId: string,
+  attempts: string[],
+): string | undefined {
+  try {
+    const resolved = api.runtime.agent.resolveAgentWorkspaceDir(api.config, agentId);
+    const issue = validateWorkspaceDir(resolved);
+    if (!issue) {
+      return resolved;
+    }
+    attempts.push(`agent:${agentId} invalid (${issue})`);
+  } catch (error) {
+    attempts.push(`agent:${agentId} threw (${String(error)})`);
+  }
+
+  return undefined;
+}
+
+export function resolveWorkspaceDir(
+  api: OpenClawPluginApi,
+  ctx: WorkspaceResolutionContext,
+  options: WorkspaceResolutionOptions = {},
+): string | undefined {
+  const source = options.source ?? 'unknown';
+  const logger = options.logger ?? api.logger;
+  const attempts: string[] = [];
+
+  if (ctx.workspaceDir) {
+    const issue = validateWorkspaceDir(ctx.workspaceDir);
+    if (!issue) {
+      return ctx.workspaceDir;
+    }
+    attempts.push(`ctx.workspaceDir invalid (${issue})`);
+  } else {
+    attempts.push('ctx.workspaceDir missing');
+  }
+
+  const agentCandidates = [ctx.agentId, options.fallbackAgentId]
+    .filter((value, index, all): value is string => !!value && all.indexOf(value) === index);
+
+  for (const agentId of agentCandidates) {
+    const resolved = tryResolveFromAgent(api, agentId, attempts);
+    if (resolved) {
+      return resolved;
+    }
+  }
+
+  const message = buildResolutionFailureMessage(source, attempts);
+  if (options.required) {
+    logger.error(message);
+    throw new Error(message);
+  }
+
+  logger.warn(message);
+  return undefined;
+}
+
+export function resolveRequiredWorkspaceDir(
+  api: OpenClawPluginApi,
+  ctx: WorkspaceResolutionContext,
+  options: Omit<WorkspaceResolutionOptions, 'required'> = {},
+): string {
+  return resolveWorkspaceDir(api, ctx, { ...options, required: true }) as string;
+}