@principles/pd-cli 1.101.0 → 1.102.0

package/src/commands/runtime-internalization-run-once.ts

@@ -20,13 +20,13 @@ import {
   TestDoubleRuntimeAdapter,
   PiAiRuntimeAdapter,
   OpenClawCliRuntimeAdapter,
-  resolveRuntimeConfig,
   isRuntimeConfigError,
   validateRuntimeConfig,
 } from '@principles/core/runtime-v2';
 import type { WakeOnceResult, DreamerRunnerResult, PhilosopherRunnerResult, ScribeRunnerResult, ArtificerRunnerResult, EvaluatorRunnerResult, RolloutReviewerRunnerResult, TrainerRunnerResult, PDRuntimeAdapter, PeerRunnerKind, OutputLanguage } from '@principles/core/runtime-v2';
 import { resolveWorkspaceDir } from '../resolve-workspace.js';
 import { readOutputLanguageFromWorkspace } from '../config-reader.js';
+import { resolveRuntimeFromPdConfig } from '../services/resolve-runtime-from-pd-config.js';
 
 interface RunOnceOptions {
   workspace?: string;
@@ -472,19 +472,20 @@ function resolveRuntimeAdapter(opts: ResolveAdapterOptions): PDRuntimeAdapter {
     });
   }
 
-  const stateDir = path.join(opts.workspaceDir, '.state');
-  const configResult = resolveRuntimeConfig(stateDir, { requestedRuntimeKind: opts.runtimeKind });
+  // PRI-393: resolve runtime from .pd/config.yaml (not .state/workflows.yaml)
+  const resolved = resolveRuntimeFromPdConfig(opts.workspaceDir);
+  const configResult = resolved.result;
 
   if (isRuntimeConfigError(configResult)) {
     throw new ConfigResolutionError(
-      `Config resolution failed: ${configResult.reason}. ` +
+      `Config resolution from .pd/config.yaml failed: ${configResult.reason}. ` +
       `${configResult.message}. nextAction: ${configResult.nextAction}`,
     );
   }
 
   if (opts.runtimeKind === 'pi-ai' || (opts.runtimeKind === 'config' && configResult.runtimeKind === 'pi-ai')) {
     validateRuntimeConfig(configResult);
-    // CLI --timeout-ms overrides workflows.yaml timeoutMs
+    // CLI --timeout-ms overrides config timeoutMs
     const adapterTimeoutMs = opts.timeoutMs ?? configResult.timeoutMs;
     return new PiAiRuntimeAdapter({
       provider: String(configResult.provider),
@@ -502,8 +503,8 @@ function resolveRuntimeAdapter(opts: ResolveAdapterOptions): PDRuntimeAdapter {
     if (!openclawMode) {
       throw new ConfigResolutionError(
         `runtimeKind 'openclaw-cli' requires openclawMode. ` +
-        `Provide --openclaw-local or --openclaw-gateway, or set openclawMode in workflows.yaml. ` +
-        `nextAction: Add openclawMode: local|gateway to your funnel policy or use CLI flags.`,
+        `Provide --openclaw-local or --openclaw-gateway, or set openclawMode in .pd/config.yaml. ` +
+        `nextAction: Add openclawMode: local|gateway to your .pd/config.yaml runtime profile or use CLI flags.`,
       );
     }
     return new OpenClawCliRuntimeAdapter({
@@ -533,7 +534,7 @@ export async function handleRuntimeInternalizationRunOnce(opts: RunOnceOptions):
   if (runtimeKind === 'test-double' && !opts.allowTestDouble) {
     console.error('Error: test-double runtime mutates real queue state (leases tasks, marks them succeeded with empty output).');
     console.error('Use --runtime test-double --allow-test-double to acknowledge this risk.');
-    console.error('For production use, use --runtime config (reads from workflows.yaml) or --runtime pi-ai / openclaw-cli.');
+    console.error('For production use, use --runtime config (reads from .pd/config.yaml) or --runtime pi-ai / openclaw-cli.');
     process.exitCode = 1;
     return;
   }
@@ -716,7 +717,7 @@ export async function handleRuntimeInternalizationRunOnce(opts: RunOnceOptions):
         decision: isConfigError ? 'config_error' : 'runtime_error',
         reason: message,
         nextAction: isConfigError
-          ? 'Fix the workflows.yaml funnel policy, or use --runtime pi-ai / openclaw-cli with explicit flags'
+          ? 'Fix the .pd/config.yaml runtime profile, or use --runtime pi-ai / openclaw-cli with explicit flags'
           : 'Check runner logs and workspace state; re-run with --runtime test-double to isolate',
       }, null, 2));
     } else {

package/src/commands/runtime.ts

@@ -9,7 +9,8 @@
  */
 import * as path from 'path';
 import { probeRuntime } from '@principles/core/runtime-v2';
-import { PDRuntimeError } from '@principles/core/runtime-v2';
+import { PDRuntimeError, isRuntimeConfigError } from '@principles/core/runtime-v2';
+import { resolveRuntimeFromPdConfig, resolveRuntimeWithOverrides } from '../services/resolve-runtime-from-pd-config.js';
 
 interface RuntimeProbeOptions {
   runtime: string;
@@ -139,48 +140,55 @@ async function handlePiAiProbe(opts: RuntimeProbeOptions): Promise<void> {
   let model = opts.model ?? '';
   let apiKeyEnv = opts.apiKeyEnv ?? '';
   let baseUrl = opts.baseUrl ?? '';
-  let {timeoutMs} = opts;
+  let { timeoutMs, maxRetries } = opts;
 
-  // D-01: always load workspace policy; CLI values take priority as override
+  // PRI-393: always load workspace policy from .pd/config.yaml (not .state/workflows.yaml)
   if (workspaceDir) {
-    try {
-      const { resolveRuntimeConfig, isRuntimeConfigError } = await import('@principles/core/runtime-v2');
-      const configResult = resolveRuntimeConfig(path.join(workspaceDir, '.state'));
-      if (isRuntimeConfigError(configResult)) {
-        console.warn(`Warning: could not load workspace runtime config — ${configResult.message}`);
-      } else {
-        const config = configResult;
-        provider = provider || config.provider || '';
-        model = model || config.model || '';
-        apiKeyEnv = apiKeyEnv || config.apiKeyEnv || '';
-        baseUrl = baseUrl || config.baseUrl || '';
-        timeoutMs = timeoutMs ?? config.timeoutMs;
-      }
-    } catch (err) {
-      console.warn(`Warning: could not load workspace runtime config — policy fallback disabled: ${err instanceof Error ? err.message : String(err)}`);
+    const resolved = resolveRuntimeWithOverrides(workspaceDir, {
+      provider: opts.provider,
+      model: opts.model,
+      apiKeyEnv: opts.apiKeyEnv,
+      baseUrl: opts.baseUrl,
+      maxRetries: opts.maxRetries,
+      timeoutMs: opts.timeoutMs,
+    });
+    for (const w of resolved.legacyWarnings) console.warn(`Warning: ${w}`);
+    if (resolved.mergedConfig) {
+      provider = provider || resolved.mergedConfig.provider || '';
+      model = model || resolved.mergedConfig.model || '';
+      apiKeyEnv = apiKeyEnv || resolved.mergedConfig.apiKeyEnv || '';
+      baseUrl = baseUrl || resolved.mergedConfig.baseUrl || '';
+      timeoutMs = timeoutMs ?? resolved.mergedConfig.timeoutMs;
+      maxRetries = maxRetries ?? resolved.mergedConfig.maxRetries;
+    } else if (isRuntimeConfigError(resolved.result)) {
+      console.warn(`Warning: could not resolve runtime from .pd/config.yaml — ${resolved.result.message}`);
     }
   }
 
   if (!provider) {
-    console.error("error: --provider is required for --runtime pi-ai (or set in --workspace workflows.yaml)");
+    console.error("error: --provider is required for --runtime pi-ai (or set in .pd/config.yaml)");
     console.error("  e.g.: pd runtime probe --runtime pi-ai --provider openrouter --model anthropic/claude-sonnet-4 --apiKeyEnv OPENROUTER_API_KEY");
     process.exit(1);
+    return;
   }
   if (!model) {
-    console.error("error: --model is required for --runtime pi-ai (or set in --workspace workflows.yaml)");
+    console.error("error: --model is required for --runtime pi-ai (or set in .pd/config.yaml)");
     console.error("  e.g.: pd runtime probe --runtime pi-ai --provider openrouter --model anthropic/claude-sonnet-4 --apiKeyEnv OPENROUTER_API_KEY");
     process.exit(1);
+    return;
   }
   if (!apiKeyEnv) {
-    console.error("error: --apiKeyEnv is required for --runtime pi-ai (or set in --workspace workflows.yaml)");
+    console.error("error: --apiKeyEnv is required for --runtime pi-ai (or set in .pd/config.yaml)");
     console.error("  e.g.: pd runtime probe --runtime pi-ai --provider openrouter --model anthropic/claude-sonnet-4 --apiKeyEnv OPENROUTER_API_KEY");
     process.exit(1);
+    return;
   }
 
   // D-09: check env var exists before calling probeRuntime
   if (!process.env[apiKeyEnv]) {
     console.error(`error: environment variable '${apiKeyEnv}' is not set`);
     process.exit(1);
+    return;
   }
 
   try {
@@ -190,7 +198,7 @@ async function handlePiAiProbe(opts: RuntimeProbeOptions): Promise<void> {
       model,
       apiKeyEnv,
       baseUrl,
-      maxRetries: opts.maxRetries,
+      maxRetries: maxRetries,
       timeoutMs: timeoutMs ?? 120_000, // D-04: probe timeout 120s (matches Runtime defaults)
     });
 
@@ -265,7 +273,66 @@ async function handlePiAiProbe(opts: RuntimeProbeOptions): Promise<void> {
 }
 
 /**
- * pd runtime probe — dispatches to openclaw-cli or pi-ai branch.
+ * --runtime config probe branch — PRI-393
+ * Resolves runtime from .pd/config.yaml, then dispatches to pi-ai or openclaw-cli probe.
+ */
+async function handleConfigProbe(opts: RuntimeProbeOptions): Promise<void> {
+  const workspaceDir = opts.workspace ? path.resolve(opts.workspace) : undefined;
+  if (!workspaceDir) {
+    console.error('error: --workspace is required for --runtime config');
+    process.exit(1);
+    return;
+  }
+
+  const resolved = resolveRuntimeFromPdConfig(workspaceDir);
+  for (const w of resolved.legacyWarnings) console.warn(`Warning: ${w}`);
+
+  if (isRuntimeConfigError(resolved.result)) {
+    if (opts.json) {
+      console.log(JSON.stringify({
+        status: 'failed',
+        errorCategory: 'config_error',
+        message: resolved.result.message,
+        reason: resolved.result.reason,
+        nextAction: resolved.result.nextAction,
+        configSource: resolved.configSource,
+      }, null, 2));
+    } else {
+      console.error(`error: ${resolved.result.message}`);
+      console.error(`nextAction: ${resolved.result.nextAction}`);
+    }
+    process.exit(1);
+    return;
+  }
+
+  const config = resolved.result;
+  // Dispatch to the appropriate runtime probe
+  if (config.runtimeKind === 'pi-ai') {
+    return handlePiAiProbe({
+      ...opts,
+      provider: opts.provider ?? config.provider,
+      model: opts.model ?? config.model,
+      apiKeyEnv: opts.apiKeyEnv ?? config.apiKeyEnv,
+      baseUrl: opts.baseUrl ?? config.baseUrl,
+      timeoutMs: opts.timeoutMs ?? config.timeoutMs,
+    });
+  }
+
+  if (config.runtimeKind === 'openclaw-cli') {
+    return handleOpenClawProbe({
+      ...opts,
+      openclawLocal: config.openclawMode === 'local' ? true : opts.openclawLocal,
+      openclawGateway: config.openclawMode === 'gateway' ? true : opts.openclawGateway,
+    });
+  }
+
+  console.error(`error: unsupported runtimeKind '${config.runtimeKind}' from .pd/config.yaml`);
+  process.exit(1);
+  return;
+}
+
+/**
+ * pd runtime probe — dispatches to openclaw-cli, pi-ai, or config branch.
  */
 export async function handleRuntimeProbe(opts: RuntimeProbeOptions): Promise<void> {
   if (opts.runtime === 'openclaw-cli') {
@@ -276,6 +343,11 @@ export async function handleRuntimeProbe(opts: RuntimeProbeOptions): Promise<voi
     return handlePiAiProbe(opts);
   }
 
-  console.error(`error: unsupported --runtime '${opts.runtime}' (supported: openclaw-cli, pi-ai)`);
+  if (opts.runtime === 'config') {
+    return handleConfigProbe(opts);
+  }
+
+  console.error(`error: unsupported --runtime '${opts.runtime}' (supported: openclaw-cli, pi-ai, config)`);
   process.exit(1);
+  return;
 }

package/src/services/resolve-runtime-from-pd-config.ts

@@ -0,0 +1,142 @@
+/**
+ * Unified runtime config resolver from .pd/config.yaml — PRI-393
+ *
+ * All MVP mainline execution paths (probe, run-once, diagnose, pain-retry)
+ * MUST use this helper instead of the legacy resolveRuntimeConfig(stateDir)
+ * which reads .state/workflows.yaml.
+ *
+ * Canonical source: .pd/config.yaml via loadPdConfig → resolveRuntimeConfigFromPdConfig.
+ * .state/workflows.yaml is reported as a legacy warning only.
+ *
+ * ERR refs:
+ * - ERR-002: fail loud with reason + nextAction
+ * - EP-07: runtime state source alignment
+ */
+
+import {
+  resolveRuntimeConfigFromPdConfig,
+  isRuntimeConfigError,
+} from '@principles/core/runtime-v2';
+import type {
+  RuntimeConfigResult,
+  RuntimeConfig,
+  RuntimeConfigError,
+} from '@principles/core/runtime-v2';
+import { loadPdConfig } from './pd-config-loader.js';
+import type { PdConfigLoadResult } from './pd-config-loader.js';
+
+export interface ResolvedRuntimeFromPdConfig {
+  /** The resolved runtime config (or error). */
+  result: RuntimeConfigResult;
+  /** Legacy files detected (.state/workflows.yaml etc.) — informational only. */
+  legacyWarnings: string[];
+  /** The PD config load result for downstream use (feature flags, etc.). */
+  configLoadResult: PdConfigLoadResult;
+  /** Canonical config source label, e.g. ".pd/config.yaml". */
+  configSource: string;
+}
+
+/**
+ * Resolve runtime configuration exclusively from .pd/config.yaml.
+ *
+ * This is the ONLY production entry point for runtime config resolution
+ * in pd-cli commands. Legacy resolveRuntimeConfig(stateDir) must NOT be
+ * called by probe/run-once/diagnose/pain-retry.
+ *
+ * @param workspaceDir - The resolved workspace directory.
+ * @param getEnvVar - Env var accessor, defaults to process.env.
+ * @returns Resolved runtime config with legacy warnings.
+ */
+export function resolveRuntimeFromPdConfig(
+  workspaceDir: string,
+  getEnvVar: (name: string) => string | undefined = (name) => process.env[name],
+): ResolvedRuntimeFromPdConfig {
+  const configLoadResult = loadPdConfig(workspaceDir);
+
+  // Malformed config → fail loud. Do NOT fall back to defaults for execution.
+  // Missing config is ok (loadPdConfig returns ok:true with defaults), but
+  // ok:false always means the file exists and is broken.
+  if (!configLoadResult.ok) {
+    const [firstError] = configLoadResult.errors;
+    const result: RuntimeConfigError = {
+      ok: false,
+      reason: `config_malformed:${firstError?.reason ?? 'unknown'}`,
+      message: firstError?.reason ?? '.pd/config.yaml is malformed',
+      nextAction: firstError?.nextAction ?? 'Fix .pd/config.yaml syntax and retry',
+    };
+
+    const legacyWarnings = configLoadResult.legacyFilesDetected.length > 0
+      ? [
+          `Legacy config files detected: ${configLoadResult.legacyFilesDetected.join(', ')}. ` +
+          `These are NOT used for runtime resolution. PD uses .pd/config.yaml exclusively.`,
+        ]
+      : [];
+
+    return {
+      result,
+      legacyWarnings,
+      configLoadResult,
+      configSource: '.pd/config.yaml',
+    };
+  }
+
+  const result = resolveRuntimeConfigFromPdConfig(configLoadResult.effective, getEnvVar);
+
+  const legacyWarnings = configLoadResult.legacyFilesDetected.length > 0
+    ? [
+        `Legacy config files detected: ${configLoadResult.legacyFilesDetected.join(', ')}. ` +
+        `These are NOT used for runtime resolution. PD uses .pd/config.yaml exclusively.`,
+      ]
+    : [];
+
+  return {
+    result,
+    legacyWarnings,
+    configLoadResult,
+    configSource: '.pd/config.yaml',
+  };
+}
+
+
+/**
+ * Resolve runtime config from .pd/config.yaml, then merge with CLI flag overrides.
+ *
+ * CLI flags take priority over config values (same semantics as before PRI-393,
+ * but reading from .pd/config.yaml instead of .state/workflows.yaml).
+ *
+ * @param workspaceDir - The resolved workspace directory.
+ * @param overrides - CLI flag overrides (provider, model, apiKeyEnv, etc.).
+ * @param getEnvVar - Env var accessor.
+ */
+export function resolveRuntimeWithOverrides(
+  workspaceDir: string,
+  overrides: {
+    provider?: string;
+    model?: string;
+    apiKeyEnv?: string;
+    baseUrl?: string;
+    maxRetries?: number;
+    timeoutMs?: number;
+  },
+  getEnvVar: (name: string) => string | undefined = (name) => process.env[name],
+): ResolvedRuntimeFromPdConfig & { mergedConfig: RuntimeConfig | null } {
+  const base = resolveRuntimeFromPdConfig(workspaceDir, getEnvVar);
+
+  if (isRuntimeConfigError(base.result)) {
+    return { ...base, mergedConfig: null };
+  }
+
+  const config = base.result;
+  // CLI flags override config values
+  const merged: RuntimeConfig = {
+    ...config,
+    provider: overrides.provider || config.provider,
+    model: overrides.model || config.model,
+    apiKeyEnv: overrides.apiKeyEnv || config.apiKeyEnv,
+    baseUrl: overrides.baseUrl || config.baseUrl,
+    maxRetries: overrides.maxRetries ?? config.maxRetries,
+    timeoutMs: overrides.timeoutMs ?? config.timeoutMs,
+  };
+
+  return { ...base, mergedConfig: merged };
+}

package/tests/commands/console-launcher-edge-cases.test.ts

@@ -55,65 +55,32 @@ describe('Port competition scenarios', () => {
   });
 
   it('findAvailablePort skips occupied ports in sequence', async () => {
-    // Occupy 3 consecutive ports using dynamically allocated base port
-    const servers: net.Server[] = [];
-    // First, get a dynamic port to use as base
-    const probeServer = net.createServer();
-    const basePort = await new Promise<number>((resolve) => {
-      probeServer.listen(0, '127.0.0.1', () => {
-        const addr = probeServer.address();
-        if (typeof addr === 'object' && addr) resolve(addr.port);
-      });
-    });
-    await new Promise<void>((resolve) => probeServer.close(() => resolve()));
-
-    for (let i = 0; i < 3; i++) {
-      const s = net.createServer();
-      await new Promise<void>((resolve) => {
-        s.listen(basePort + i, '127.0.0.1', () => resolve());
-      });
-      servers.push(s);
-    }
-
+    // Use mock to simulate 3 consecutive occupied ports — avoids flaky real-network I/O
+    const basePort = 49200;
+    (globalThis as any).__mockIsPortInUse = async (_host: string, port: number) => {
+      return port >= basePort && port <= basePort + 2;
+    };
     try {
-      // Should skip all 3 and return the next free one
       const port = await findAvailablePort('127.0.0.1', basePort, 5);
+      // Should skip basePort, basePort+1, basePort+2 and return basePort+3
       expect(port).toBe(basePort + 3);
     } finally {
-      for (const s of servers) {
-        await new Promise<void>((resolve) => s.close(() => resolve()));
-      }
+      delete (globalThis as any).__mockIsPortInUse;
     }
   });
 
   it('returns null when all fallback ports are exhausted', async () => {
-    // Occupy a range of ports using dynamically allocated base port
-    const servers: net.Server[] = [];
-    const probeServer = net.createServer();
-    const basePort = await new Promise<number>((resolve) => {
-      probeServer.listen(0, '127.0.0.1', () => {
-        const addr = probeServer.address();
-        if (typeof addr === 'object' && addr) resolve(addr.port);
-      });
-    });
-    await new Promise<void>((resolve) => probeServer.close(() => resolve()));
-
-    for (let i = 0; i < 10; i++) {
-      const s = net.createServer();
-      await new Promise<void>((resolve) => {
-        s.listen(basePort + i, '127.0.0.1', () => resolve());
-      });
-      servers.push(s);
-    }
-
+    // Use mock to simulate all ports occupied — avoids flaky real-network I/O
+    const basePort = 49300;
+    (globalThis as any).__mockIsPortInUse = async (_host: string, port: number) => {
+      return port >= basePort && port <= basePort + 9;
+    };
     try {
-      // With limit=5, should return null after exhausting fallback
+      // With limit=5, all 5 candidates are occupied → null
       const port = await findAvailablePort('127.0.0.1', basePort, 5);
       expect(port).toBeNull();
     } finally {
-      for (const s of servers) {
-        await new Promise<void>((resolve) => s.close(() => resolve()));
-      }
+      delete (globalThis as any).__mockIsPortInUse;
     }
   });
 });

package/tests/commands/diagnose.test.ts

@@ -41,6 +41,23 @@ const { MockPrincipleTreeLedgerAdapter } = vi.hoisted(() => {
   return { MockPrincipleTreeLedgerAdapter };
 });
 
+const { mockResolveRuntimeFromPdConfig } = vi.hoisted(() => {
+  const mockResolveRuntimeFromPdConfig = vi.fn().mockReturnValue({
+    result: {
+      runtimeKind: 'pi-ai',
+      provider: 'test-provider',
+      model: 'test-model',
+      apiKeyEnv: 'TEST_KEY',
+      timeoutMs: 300000,
+      agentId: 'main',
+    },
+    legacyWarnings: [],
+    configSource: '.pd/config.yaml',
+    configLoadResult: { ok: true, effective: {}, defaults: {}, legacyFilesDetected: [] },
+  });
+  return { mockResolveRuntimeFromPdConfig };
+});
+
 vi.mock('../../src/resolve-workspace.js', () => ({
   resolveWorkspaceDir: vi.fn().mockReturnValue('/tmp/fake-workspace'),
 }));
@@ -122,6 +139,10 @@ vi.mock('../../src/services/pd-config-loader.js', () => ({
   computeFlagsFromLoadResult: vi.fn().mockReturnValue({}),
 }));
 
+vi.mock('../../src/services/resolve-runtime-from-pd-config.js', () => ({
+  resolveRuntimeFromPdConfig: mockResolveRuntimeFromPdConfig,
+}));
+
 import { handleDiagnoseRun, handleDiagnoseStatus, type DiagnoseRunOptions } from '../../src/commands/diagnose.js';
 
 const SUCCEEDED_RESULT = {
@@ -177,14 +198,18 @@ describe('pd diagnose run --runtime routing', () => {
     exitSpy.mockRestore();
   });
 
-  it('HG-03: --runtime openclaw-cli without mode (no file config) fails via resolveRuntimeConfig', async () => {
-    mockResolveRuntimeConfig.mockReturnValueOnce({
-      ok: false,
-      reason: 'missing_openclaw_mode',
-      message: 'runtimeKind is openclaw-cli but no mode specified',
-      nextAction: 'Provide exactly one mode',
+  it('HG-03: --runtime openclaw-cli without mode (no file config) fails via resolveRuntimeFromPdConfig', async () => {
+    mockResolveRuntimeFromPdConfig.mockReturnValueOnce({
+      result: {
+        ok: false,
+        reason: 'missing_openclaw_mode',
+        message: 'runtimeKind is openclaw-cli but no mode specified',
+        nextAction: 'Provide exactly one mode',
+      },
+      legacyWarnings: [],
+      configSource: '.pd/config.yaml',
+      configLoadResult: { ok: true, effective: {}, defaults: {}, legacyFilesDetected: [] },
     });
-    mockIsRuntimeConfigError.mockReturnValueOnce(true);
 
     const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
     const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => undefined) as () => never);
@@ -196,7 +221,7 @@ describe('pd diagnose run --runtime routing', () => {
       json: false,
     } as DiagnoseRunOptions);
 
-    expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('no mode specified'));
+    expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('no mode resolved'));
     expect(exitSpy).toHaveBeenCalledWith(1);
 
     consoleErrorSpy.mockRestore();
@@ -226,13 +251,17 @@ describe('pd diagnose run --runtime routing', () => {
   });
 
   it('DPB-09: openclaw-cli with file config openclawMode succeeds without CLI flag', async () => {
-    mockResolveRuntimeConfig.mockReturnValueOnce({
-      runtimeKind: 'openclaw-cli',
-      openclawMode: 'local',
-      timeoutMs: 300000,
-      agentId: 'main',
+    mockResolveRuntimeFromPdConfig.mockReturnValueOnce({
+      result: {
+        runtimeKind: 'openclaw-cli',
+        openclawMode: 'local',
+        timeoutMs: 300000,
+        agentId: 'main',
+      },
+      legacyWarnings: [],
+      configSource: '.pd/config.yaml',
+      configLoadResult: { ok: true, effective: {}, defaults: {}, legacyFilesDetected: [] },
     });
-    mockIsRuntimeConfigError.mockReturnValueOnce(false);
 
     const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
     const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => undefined) as () => never);
@@ -250,14 +279,18 @@ describe('pd diagnose run --runtime routing', () => {
     exitSpy.mockRestore();
   });
 
-  it('DPB-09: openclaw-cli flag overrides file config mode', async () => {
-    mockResolveRuntimeConfig.mockReturnValueOnce({
-      runtimeKind: 'openclaw-cli',
-      openclawMode: 'gateway',
-      timeoutMs: 300000,
-      agentId: 'main',
+  it('DPB-09: openclaw-cli flag overrides file config mode (config=gateway, flag=local → runtimeMode=local)', async () => {
+    mockResolveRuntimeFromPdConfig.mockReturnValueOnce({
+      result: {
+        runtimeKind: 'openclaw-cli',
+        openclawMode: 'gateway',
+        timeoutMs: 300000,
+        agentId: 'main',
+      },
+      legacyWarnings: [],
+      configSource: '.pd/config.yaml',
+      configLoadResult: { ok: true, effective: {}, defaults: {}, legacyFilesDetected: [] },
     });
-    mockIsRuntimeConfigError.mockReturnValueOnce(false);
 
     const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
     const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => undefined) as () => never);
@@ -270,6 +303,13 @@ describe('pd diagnose run --runtime routing', () => {
       json: false,
     } as DiagnoseRunOptions);
 
+    // Flag override: config says gateway, flag says local → adapter gets local
+    const OpenClawCliMock = vi.mocked(
+      await import('@principles/core/runtime-v2').then(m => m.OpenClawCliRuntimeAdapter),
+    );
+    expect(OpenClawCliMock).toHaveBeenCalledWith(
+      expect.objectContaining({ runtimeMode: 'local' }),
+    );
     expect(exitSpy).not.toHaveBeenCalledWith(1);
 
     consoleSpy.mockRestore();
@@ -277,13 +317,17 @@ describe('pd diagnose run --runtime routing', () => {
   });
 
   it('DPB-09: openclaw-cli missing mode (--json) outputs JSON error', async () => {
-    mockResolveRuntimeConfig.mockReturnValueOnce({
-      ok: false,
-      reason: 'missing_openclaw_mode',
-      message: 'runtimeKind is openclaw-cli but no mode specified',
-      nextAction: 'Provide exactly one mode',
+    mockResolveRuntimeFromPdConfig.mockReturnValueOnce({
+      result: {
+        runtimeKind: 'openclaw-cli',
+        openclawMode: undefined,
+        timeoutMs: 300000,
+        agentId: 'main',
+      },
+      legacyWarnings: [],
+      configSource: '.pd/config.yaml',
+      configLoadResult: { ok: true, effective: {}, defaults: {}, legacyFilesDetected: [] },
     });
-    mockIsRuntimeConfigError.mockReturnValueOnce(true);
 
     const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
     const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => undefined) as () => never);
@@ -323,13 +367,17 @@ describe('pd diagnose run --runtime routing', () => {
   });
 
   it('DPB-09: openclaw-cli --openclaw-gateway constructs adapter with runtimeMode=gateway', async () => {
-    mockResolveRuntimeConfig.mockReturnValueOnce({
-      runtimeKind: 'openclaw-cli',
-      openclawMode: 'gateway',
-      timeoutMs: 300000,
-      agentId: 'main',
+    mockResolveRuntimeFromPdConfig.mockReturnValueOnce({
+      result: {
+        runtimeKind: 'openclaw-cli',
+        openclawMode: 'gateway',
+        timeoutMs: 300000,
+        agentId: 'main',
+      },
+      legacyWarnings: [],
+      configSource: '.pd/config.yaml',
+      configLoadResult: { ok: true, effective: {}, defaults: {}, legacyFilesDetected: [] },
     });
-    mockIsRuntimeConfigError.mockReturnValueOnce(false);
 
     const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
     const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => undefined) as () => never);
@@ -355,13 +403,17 @@ describe('pd diagnose run --runtime routing', () => {
   });
 
   it('DPB-09: openclaw-cli --openclaw-local constructs adapter with runtimeMode=local', async () => {
-    mockResolveRuntimeConfig.mockReturnValueOnce({
-      runtimeKind: 'openclaw-cli',
-      openclawMode: 'local',
-      timeoutMs: 300000,
-      agentId: 'main',
+    mockResolveRuntimeFromPdConfig.mockReturnValueOnce({
+      result: {
+        runtimeKind: 'openclaw-cli',
+        openclawMode: 'local',
+        timeoutMs: 300000,
+        agentId: 'main',
+      },
+      legacyWarnings: [],
+      configSource: '.pd/config.yaml',
+      configLoadResult: { ok: true, effective: {}, defaults: {}, legacyFilesDetected: [] },
     });
-    mockIsRuntimeConfigError.mockReturnValueOnce(false);
 
     const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
     const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => undefined) as () => never);