principles-disciple 1.59.0 → 1.60.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.59.0",
+  "version": "1.60.0",
   "skills": [
     "./skills"
   ],
@@ -76,8 +76,8 @@
     }
   },
   "buildFingerprint": {
-    "gitSha": "f37ee1dec538",
-    "bundleMd5": "f578c460a9849e9b6e6c573d13e48f12",
-    "builtAt": "2026-04-18T07:51:05.292Z"
+    "gitSha": "b300ef0761c5",
+    "bundleMd5": "3c16a5198f3559b097d028b6e987cf5b",
+    "builtAt": "2026-04-18T11:02:10.525Z"
   }
 }

package/package.json

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

package/src/commands/archive-impl.ts

@@ -19,6 +19,7 @@ import {
 } from '../core/principle-tree-ledger.js';
 import type { Implementation, ImplementationLifecycleState } from '../types/principle-tree-schema.js';
 import type { PluginCommandContext, PluginCommandResult } from '../openclaw-sdk.js';
+import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 
 /**
  * Get all implementations from the ledger.
@@ -43,7 +44,7 @@ function canArchive(state: ImplementationLifecycleState): boolean {
  *   /pd-archive-impl list       - List archivable implementations
  */
 export function handleArchiveImplCommand(ctx: PluginCommandContext): PluginCommandResult {
-  const workspaceDir = (ctx.config?.workspaceDir as string) || process.cwd();
+  const workspaceDir = resolvePluginCommandWorkspaceDir(ctx, 'archive-impl');
   const {stateDir} = WorkspaceContext.fromHookContext({ ...ctx, workspaceDir });
   const lang = (ctx.config?.language as string) || 'en';
   const isZh = lang === 'zh';

package/src/commands/capabilities.ts

@@ -4,6 +4,7 @@ import * as path from 'path';
 import type { PluginCommandContext, PluginCommandResult } from '../openclaw-sdk.js';
 import { WorkspaceContext } from '../core/workspace-context.js';
 import { atomicWriteFileSync } from '../utils/io.js';
+import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 
 const TOOLS_TO_SCAN = [
   { name: 'rg', cmd: ['rg', '--version'] },
@@ -50,7 +51,7 @@ function scanEnvironment(wctx: WorkspaceContext): any {
 }
 
 export function handleBootstrapTools(ctx: PluginCommandContext): PluginCommandResult {
-  const workspaceDir = (ctx.config?.workspaceDir as string) || process.cwd();
+  const workspaceDir = resolvePluginCommandWorkspaceDir(ctx, 'capabilities');
   const wctx = WorkspaceContext.fromHookContext({ workspaceDir, ...ctx.config });
 
   try {

package/src/commands/context.ts

@@ -2,6 +2,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import type { PluginCommandContext, PluginCommandResult } from '../openclaw-sdk.js';
+import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 import { atomicWriteFileSync } from '../utils/io.js';
 import type { ContextInjectionConfig} from '../types.js';
 import { defaultContextConfig } from '../types.js';
@@ -11,11 +12,8 @@ import { loadContextInjectionConfig } from '../hooks/prompt.js';
  * Get workspace directory from context
  */
 function getWorkspaceDir(ctx: PluginCommandContext): string {
-    const workspaceDir = (ctx.config?.workspaceDir as string) || process.cwd();
-    if (!workspaceDir) {
-        throw new Error('[PD:Context] workspaceDir is required but not provided');
-    }
-    return workspaceDir;
+    // resolvePluginCommandWorkspaceDir throws on failure — never returns falsy
+    return resolvePluginCommandWorkspaceDir(ctx, 'context');
 }
 
 /**

package/src/commands/disable-impl.ts

@@ -21,6 +21,7 @@ import {
 } from '../core/principle-tree-ledger.js';
 import type { Implementation, ImplementationLifecycleState } from '../types/principle-tree-schema.js';
 import type { PluginCommandContext, PluginCommandResult } from '../openclaw-sdk.js';
+import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 
 /**
  * Get all implementations from the ledger.
@@ -133,7 +134,7 @@ function _handleDisableImpl(
  */
      
 export function handleDisableImplCommand(ctx: PluginCommandContext): PluginCommandResult {
-  const workspaceDir = (ctx.config?.workspaceDir as string) || process.cwd();
+  const workspaceDir = resolvePluginCommandWorkspaceDir(ctx, 'disable-impl');
   const {stateDir} = WorkspaceContext.fromHookContext({ ...ctx, workspaceDir });
   const lang = (ctx.config?.language as string) || 'en';
   const isZh = lang === 'zh';

package/src/commands/evolution-status.ts

@@ -4,6 +4,7 @@ import { WorkspaceContext } from '../core/workspace-context.js';
 import { normalizeLanguage } from '../i18n/commands.js';
 import type { PluginCommandContext } from '../openclaw-sdk.js';
 import { RuntimeSummaryService } from '../service/runtime-summary-service.js';
+import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 
 function formatNumber(value: number | null): string {
   if (value === null || Number.isNaN(value)) {
@@ -168,7 +169,7 @@ function buildChineseOutput(
 }
 
 export function handleEvolutionStatusCommand(ctx: PluginCommandContext): { text: string } {
-  const workspaceDir = (ctx.config?.workspaceDir as string) || process.cwd();
+  const workspaceDir = resolvePluginCommandWorkspaceDir(ctx, 'evolution-status');
   const sessionId = (ctx as { sessionId?: string | null }).sessionId ?? null;
   // #207/#210: Use WorkspaceContext to get evolutionReducer with stateDir
   const wctx = WorkspaceContext.fromHookContext({ workspaceDir });

package/src/commands/export.ts

@@ -1,5 +1,6 @@
 import { WorkspaceContext } from '../core/workspace-context.js';
 import type { PluginCommandContext, PluginCommandResult } from '../openclaw-sdk.js';
+import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 import { exportORPOSamples, listExports } from '../core/nocturnal-export.js';
 
 function isZh(ctx: PluginCommandContext): boolean {
@@ -7,7 +8,7 @@ function isZh(ctx: PluginCommandContext): boolean {
 }
 
 export function handleExportCommand(ctx: PluginCommandContext): PluginCommandResult {
-  const workspaceDir = (ctx.config?.workspaceDir as string) || process.cwd();
+  const workspaceDir = resolvePluginCommandWorkspaceDir(ctx, 'export');
   const zh = isZh(ctx);
   const args = (ctx.args || '').trim();
   const parts = args.split(/\s+/).filter(Boolean);

package/src/commands/focus.ts

@@ -13,6 +13,7 @@ import * as path from 'path';
 import type { PluginCommandContext, PluginCommandResult, OpenClawPluginApi } from '../openclaw-sdk.js';
 import { WorkspaceContext } from '../core/workspace-context.js';
 import { atomicWriteFileSync } from '../utils/io.js';
+import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 import {
   getHistoryDir,
   backupToHistory,
@@ -28,11 +29,7 @@ import {
  * 获取工作区目录
  */
 function getWorkspaceDir(ctx: PluginCommandContext): string {
-  const workspaceDir = ctx.config?.workspaceDir as string | undefined;
-  if (!workspaceDir) {
-    throw new Error('[PD:Focus] workspaceDir is required but not provided');
-  }
-  return workspaceDir;
+  return resolvePluginCommandWorkspaceDir(ctx, 'focus');
 }
 
 /**

package/src/commands/nocturnal-review.ts

@@ -34,6 +34,7 @@ import {
 } from '../core/nocturnal-dataset.js';
 import { getPrincipleState, setPrincipleState } from '../core/principle-training-state.js';
 import type { PluginCommandContext, PluginCommandResult } from '../openclaw-sdk.js';
+import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 
 function isZh(ctx: PluginCommandContext): boolean {
   return String(ctx.config?.language || 'en').startsWith('zh');
@@ -91,7 +92,7 @@ function statusLabel(status: NocturnalReviewStatus, zh: boolean): string {
 }
 
 export function handleNocturnalReviewCommand(ctx: PluginCommandContext): PluginCommandResult {
-  const workspaceDir = (ctx.config?.workspaceDir as string) || process.cwd();
+  const workspaceDir = resolvePluginCommandWorkspaceDir(ctx, 'nocturnal-review');
   const zh = isZh(ctx);
   const args = (ctx.args || '').trim();
   const parts = args.split(/\s+/).filter(Boolean);

package/src/commands/nocturnal-rollout.ts

@@ -25,6 +25,7 @@
  */
 
 import type { PluginCommandContext, PluginCommandResult } from '../openclaw-sdk.js';
+import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 import {
   evaluatePromotionGate,
   advancePromotion,
@@ -99,7 +100,7 @@ function formatConstraintCheck(
 }
 
 export function handleNocturnalRolloutCommand(ctx: PluginCommandContext): PluginCommandResult {
-  const workspaceDir = (ctx.config?.workspaceDir as string) || process.cwd();
+  const workspaceDir = resolvePluginCommandWorkspaceDir(ctx, 'nocturnal-rollout');
   const zh = isZh(ctx);
   const args = (ctx.args || '').trim();
   const parts = args.split(/\s+/).filter(Boolean);

package/src/commands/nocturnal-train.ts

@@ -28,6 +28,7 @@ import { execFileSync, spawn } from 'child_process';
 import { fileURLToPath } from 'url';
 import { atomicWriteFileSync } from '../utils/io.js';
 import type { PluginCommandContext, PluginCommandResult } from '../openclaw-sdk.js';
+import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 import {
   type TrainerBackendKind,
   type HardwareTier,
@@ -100,7 +101,7 @@ function formatTrainingRun(run: ReturnType<typeof getTrainingRun>, zh: boolean):
 }
 
 export async function handleNocturnalTrainCommand(ctx: PluginCommandContext): Promise<PluginCommandResult> {
-  const workspaceDir = (ctx.config?.workspaceDir as string) || process.cwd();
+  const workspaceDir = resolvePluginCommandWorkspaceDir(ctx, 'nocturnal-train');
   const zh = isZh(ctx);
   const args = (ctx.args || '').trim();
   const parts = args.split(/\s+/).filter(Boolean);

package/src/commands/pain.ts

@@ -1,6 +1,7 @@
 import { resetFriction, getSession } from '../core/session-tracker.js';
 import { WorkspaceContext } from '../core/workspace-context.js';
 import type { PluginCommandContext, PluginCommandResult } from '../openclaw-sdk.js';
+import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 import type { EmpathyEventStats } from '../types/event-types.js';
 
 /**
@@ -92,7 +93,7 @@ interface SessionAwareCommandContext extends PluginCommandContext {
  * Handles the /pd-status command
  */
 export function handlePainCommand(ctx: PluginCommandContext): PluginCommandResult {
-    const workspaceDir = (ctx.config?.workspaceDir as string) || process.cwd();
+    const workspaceDir = resolvePluginCommandWorkspaceDir(ctx, 'pain');
     
     const wctx = WorkspaceContext.fromHookContext({ workspaceDir, ...ctx.config });
     const lang = (ctx.config?.language as string) || 'en';

package/src/commands/pd-reflect.ts

@@ -8,6 +8,7 @@
 import type { PluginCommandDefinition, PluginCommandContext, PluginCommandResult, OpenClawPluginApi } from '../openclaw-sdk.js';
 import { acquireQueueLock, EVOLUTION_QUEUE_LOCK_SUFFIX } from '../service/evolution-worker.js';
 import { atomicWriteFileSync } from '../utils/io.js';
+import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 import * as fs from 'fs';
 import * as path from 'path';
 
@@ -23,11 +24,7 @@ export const handlePdReflect: PluginCommandDefinition = {
   requireAuth: false,
   handler: async (ctx: PdReflectContext): Promise<PluginCommandResult> => {
     try {
-       
-      const workspaceDir = ctx.workspaceDir;
-      if (!workspaceDir) {
-        return { text: 'Cannot determine workspace directory. Ensure you are in an active workspace.', isError: true };
-      }
+      const workspaceDir = resolvePluginCommandWorkspaceDir(ctx, 'pd-reflect');
 
       const stateDir = path.join(workspaceDir, '.state');
       const queuePath = path.join(stateDir, 'evolution_queue.json');
@@ -80,9 +77,10 @@ export const handlePdReflect: PluginCommandDefinition = {
       return {
         text: `Nocturnal reflection task enqueued: \`${taskId}\`\n\nIt will be processed in the next evolution worker cycle (~15s). Check .state/nocturnal/samples/ for results.`,
       };
-    } catch (error) {
+    } catch (err: unknown) {
+      const message = err instanceof Error ? err.message : String(err);
       return {
-        text: `Failed to trigger reflection: ${String(error)}`,
+        text: `Failed to trigger reflection: ${message}`,
         isError: true,
       };
     }

package/src/commands/principle-rollback.ts

@@ -1,9 +1,10 @@
 import { WorkspaceContext } from '../core/workspace-context.js';
 import type { PluginCommandContext } from '../openclaw-sdk.js';
+import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 
      
 export function handlePrincipleRollbackCommand(ctx: PluginCommandContext): { text: string } {
-  const workspaceDir = (ctx.config?.workspaceDir as string) || process.cwd();
+  const workspaceDir = resolvePluginCommandWorkspaceDir(ctx, 'principle-rollback');
   const argText = (ctx.args || '').trim();
   const [principleId = '', ...reasonParts] = argText.split(/\s+/);
   const reason = (reasonParts.join(' ') || 'manual rollback').trim();

package/src/commands/promote-impl.ts

@@ -28,6 +28,7 @@ import {
 } from '../core/principle-tree-ledger.js';
 import { WorkspaceContext } from '../core/workspace-context.js';
 import type { PluginCommandContext, PluginCommandResult } from '../openclaw-sdk.js';
+import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 import type { Implementation, ImplementationLifecycleState } from '../types/principle-tree-schema.js';
 import { withLock } from '../utils/file-lock.js';
 import { atomicWriteFileSync } from '../utils/io.js';
@@ -250,7 +251,7 @@ function _handlePromoteImpl(options: PromoteImplOptions): PluginCommandResult {
 }
 
 export function handlePromoteImplCommand(ctx: PluginCommandContext): PluginCommandResult {
-  const workspaceDir = (ctx.config?.workspaceDir as string) || process.cwd();
+  const workspaceDir = resolvePluginCommandWorkspaceDir(ctx, 'promote-impl');
   const {stateDir} = WorkspaceContext.fromHookContext({ ...ctx, workspaceDir });
   const lang = (ctx.config?.language as string) || 'en';
   const isZh = lang === 'zh';

package/src/commands/rollback-impl.ts

@@ -25,6 +25,7 @@ import {
 } from '../core/principle-tree-ledger.js';
 import type { Implementation } from '../types/principle-tree-schema.js';
 import type { PluginCommandContext, PluginCommandResult } from '../openclaw-sdk.js';
+import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 
 /**
  * Get all implementations from the ledger.
@@ -44,7 +45,7 @@ function getAllImplementations(stateDir: string): Implementation[] {
  */
      
 export function handleRollbackImplCommand(ctx: PluginCommandContext): PluginCommandResult {
-  const workspaceDir = (ctx.config?.workspaceDir as string) || process.cwd();
+  const workspaceDir = resolvePluginCommandWorkspaceDir(ctx, 'rollback-impl');
   const {stateDir} = WorkspaceContext.fromHookContext({ ...ctx, workspaceDir });
   const lang = (ctx.config?.language as string) || 'en';
   const isZh = lang === 'zh';

package/src/commands/rollback.ts

@@ -1,6 +1,7 @@
 import { WorkspaceContext } from '../core/workspace-context.js';
 import { resetFriction } from '../core/session-tracker.js';
 import type { PluginCommandContext, PluginCommandResult } from '../openclaw-sdk.js';
+import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 
 /**
  * Extended context interface that includes sessionId injected by the plugin framework.
@@ -18,7 +19,7 @@ interface SessionAwareCommandContext extends PluginCommandContext {
  *   /pd-rollback last        - Rollback the last empathy event in current session
  */
 export function handleRollbackCommand(ctx: PluginCommandContext): PluginCommandResult {
-    const workspaceDir = (ctx.config?.workspaceDir as string) || process.cwd();
+    const workspaceDir = resolvePluginCommandWorkspaceDir(ctx, 'rollback');
     
     const wctx = WorkspaceContext.fromHookContext({ workspaceDir, ...ctx.config });
     const lang = (ctx.config?.language as string) || 'en';

package/src/commands/samples.ts

@@ -1,12 +1,13 @@
 import { WorkspaceContext } from '../core/workspace-context.js';
 import type { PluginCommandContext, PluginCommandResult } from '../openclaw-sdk.js';
+import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 
 function isZh(ctx: PluginCommandContext): boolean {
   return String(ctx.config?.language || 'en').startsWith('zh');
 }
 
 export function handleSamplesCommand(ctx: PluginCommandContext): PluginCommandResult {
-  const workspaceDir = (ctx.config?.workspaceDir as string) || process.cwd();
+  const workspaceDir = resolvePluginCommandWorkspaceDir(ctx, 'samples');
   const zh = isZh(ctx);
   const args = (ctx.args || '').trim();
   const wctx = WorkspaceContext.fromHookContext({ workspaceDir, ...ctx.config });

package/src/commands/strategy.ts

@@ -1,8 +1,9 @@
 import type { PluginCommandContext, PluginCommandResult } from '../openclaw-sdk.js';
+import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 import { WorkspaceContext } from '../core/workspace-context.js';
 
 export function handleInitStrategy(ctx: PluginCommandContext): PluginCommandResult {
-  const workspaceDir = (ctx.config?.workspaceDir as string) || process.cwd();
+  const workspaceDir = resolvePluginCommandWorkspaceDir(ctx, 'strategy');
   const wctx = WorkspaceContext.fromHookContext({ workspaceDir, ...ctx.config });
 
   const okrDir = wctx.resolve('OKR_DIR').replace(workspaceDir, '').replace(/^\/+/, '');
@@ -20,7 +21,7 @@ export function handleInitStrategy(ctx: PluginCommandContext): PluginCommandResu
 }
 
 export function handleManageOkr(ctx: PluginCommandContext): PluginCommandResult {
-  const workspaceDir = (ctx.config?.workspaceDir as string) || process.cwd();
+  const workspaceDir = resolvePluginCommandWorkspaceDir(ctx, 'strategy:manageOkr');
   const wctx = WorkspaceContext.fromHookContext({ workspaceDir, ...ctx.config });
 
   const focusPath = wctx.resolve('CURRENT_FOCUS').replace(workspaceDir, '').replace(/^\/+/, '');

package/src/commands/thinking-os.ts

@@ -1,10 +1,11 @@
  
 import * as fs from 'fs';
 import type { PluginCommandContext, PluginCommandResult } from '../openclaw-sdk.js';
+import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 import { WorkspaceContext } from '../core/workspace-context.js';
 
 function getWorkspaceDir(ctx: PluginCommandContext): string {
-    return (ctx.config?.workspaceDir as string) || process.cwd();
+    return resolvePluginCommandWorkspaceDir(ctx, 'thinking-os');
 }
 
 function getModels(wctx: WorkspaceContext): Record<string, string> {

package/src/commands/workflow-debug.ts

@@ -1,5 +1,6 @@
 import { WorkflowStore } from '../service/subagent-workflow/workflow-store.js';
 import type { PluginCommandContext } from '../openclaw-sdk.js';
+import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 
 function formatTimestamp(ts: number | null | undefined): string {
     if (!ts) return '--';
@@ -85,7 +86,7 @@ function buildOutput(
 export function handleWorkflowDebugCommand(
     ctx: PluginCommandContext & { args?: string }
 ): { text: string } {
-    const workspaceDir = (ctx.config?.workspaceDir as string) || process.cwd();
+    const workspaceDir = resolvePluginCommandWorkspaceDir(ctx, 'workflow-debug');
     
     // Parse workflow ID from args
     const args = (ctx as { args?: string }).args?.trim() || '';

package/src/utils/workspace-resolver.ts

@@ -4,7 +4,7 @@
  * Shared helpers for resolving workspace directories across commands and hooks.
  */
 
-import type { OpenClawPluginApi } from '../openclaw-sdk.js';
+import type { OpenClawPluginApi, PluginCommandContext } from '../openclaw-sdk.js';
 import { validateWorkspaceDir, type WorkspaceResolutionContext } from '../core/workspace-dir-validation.js';
 import { resolveWorkspaceDir } from '../core/workspace-dir-service.js';
 import { resolveWorkspaceDirFromApi } from '../core/path-resolver.js';
@@ -25,7 +25,10 @@ export function resolveCommandWorkspaceDir(
   if (ctx.workspaceDir) {
     const issue = validateWorkspaceDir(ctx.workspaceDir);
     if (!issue) return ctx.workspaceDir;
-    api.logger.error(`[PD:Command] ctx.workspaceDir="${ctx.workspaceDir}" is invalid: ${issue}`);
+    // Validation failed — fail immediately, do not silently fall back
+    const errorMsg = `[PD:Command] ctx.workspaceDir="${ctx.workspaceDir}" is invalid: ${issue}`;
+    api.logger.error(errorMsg);
+    throw new Error(errorMsg);
   }
 
   // 2. Official OpenClaw API → env vars → config file
@@ -34,13 +37,51 @@ export function resolveCommandWorkspaceDir(
 
   // CRITICAL FAILURE: Cannot determine workspace directory
   const errorMsg = `[PD:Command] CRITICAL: Cannot resolve workspace directory. ` +
-    `ctx.workspaceDir="${ctx.workspaceDir}" is invalid, and all fallbacks failed. ` +
+    `ctx.workspaceDir="${ctx.workspaceDir ?? ''}" is invalid, and all fallbacks failed. ` +
     `Commands will NOT execute to prevent data corruption.`;
   api.logger.error(errorMsg);
 
   throw new Error(errorMsg);
 }
 
+/**
+ * Resolve workspace directory for plugin command execution.
+ *
+ * Chain: ctx.workspaceDir (canonical) → ctx.config.workspaceDir (dispatcher fallback)
+ *
+ * CRITICAL: Throws if workspaceDir cannot be resolved. Commands must NEVER silently
+ * fall back to process.cwd() as this masks configuration errors and can corrupt
+ * the wrong workspace.
+ *
+ * @param ctx - Plugin command context (has workspaceDir + config properties)
+ * @param source - Source label for error messages (e.g. 'evolution-status', 'pain')
+ */
+export function resolvePluginCommandWorkspaceDir(
+  ctx: PluginCommandContext,
+  source: string,
+): string {
+  // 1. Canonical workspaceDir field (set by OpenClaw command dispatcher)
+  if (ctx.workspaceDir) {
+    const issue = validateWorkspaceDir(ctx.workspaceDir);
+    if (!issue) return ctx.workspaceDir;
+    throw new Error(`[PD:Command:${source}] ctx.workspaceDir="${ctx.workspaceDir}" is invalid: ${issue}`);
+  }
+
+  // 2. Dispatcher may also put workspaceDir in config (legacy/alternative path)
+  const configWorkspaceDir = ctx.config?.workspaceDir as string | undefined;
+  if (configWorkspaceDir) {
+    const issue = validateWorkspaceDir(configWorkspaceDir);
+    if (!issue) return configWorkspaceDir;
+    throw new Error(`[PD:Command:${source}] ctx.config.workspaceDir="${configWorkspaceDir}" is invalid: ${issue}`);
+  }
+
+  // CRITICAL FAILURE: No workspace directory available
+  throw new Error(
+    `[PD:Command:${source}] CRITICAL: workspaceDir is not set in ctx.workspaceDir or ctx.config.workspaceDir. ` +
+    `Commands cannot execute without a valid workspace. Set OPENCLAW_WORKSPACE_DIR env var or ensure the workspace is properly initialized.`,
+  );
+}
+
 /**
  * Resolve workspace directory for tool hook execution (safe version).
  * Returns undefined instead of throwing if resolution fails.

package/tests/commands/pd-reflect.test.ts

@@ -20,7 +20,7 @@ describe('pd-reflect command', () => {
   it('requires an explicit resolved workspace directory', async () => {
     const result = await handlePdReflect.handler({} as any);
     expect(result.isError).toBe(true);
-    expect(result.text).toContain('Cannot determine workspace directory');
+    expect(result.text).toContain('workspaceDir is not set');
   });
 
   it('enqueues into the provided active workspace', async () => {