@principles/pd-cli 1.101.0 → 1.103.0

package/tests/commands/pri-393-runtime-config-unification.test.ts

@@ -0,0 +1,284 @@
+/**
+ * PRI-393: Runtime config unification tests
+ *
+ * Validates that all MVP mainline execution paths (probe, run-once, diagnose,
+ * pain-retry) read from .pd/config.yaml, NOT from .state/workflows.yaml.
+ *
+ * ERR refs:
+ * - EP-02: production path wiring — tests exercise real production entry points
+ * - EP-03: fail loud — no silent fallback
+ * - EP-07: runtime state source alignment — doctor/probe/run-once agree
+ * - EP-09: test reality gap — production schema fixtures
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import * as yaml from 'js-yaml';
+import {
+  assertMainlineContract,
+  type MainlineSnapshot,
+} from '@principles/core/runtime-v2';
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function mkTmpDir(prefix = 'pri-393-'): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+}
+
+function rmTmpDir(dir: string): void {
+  try { fs.rmSync(dir, { recursive: true, force: true }); } catch { /* ignore */ }
+}
+
+function writeConfigYaml(workspaceDir: string, content: object): void {
+  const pdDir = path.join(workspaceDir, '.pd');
+  fs.mkdirSync(pdDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(pdDir, 'config.yaml'),
+    yaml.dump(content, { lineWidth: -1 }),
+    'utf8',
+  );
+}
+
+function writeLegacyWorkflowsYaml(workspaceDir: string, content: string): void {
+  const stateDir = path.join(workspaceDir, '.state');
+  fs.mkdirSync(stateDir, { recursive: true });
+  fs.writeFileSync(path.join(stateDir, 'workflows.yaml'), content, 'utf8');
+}
+
+/** Minimal valid .pd/config.yaml with a pi-ai runtime profile for diagnostician. */
+function makeValidConfigYaml(overrides?: { provider?: string; model?: string }): object {
+  return {
+    version: 1,
+    features: {
+      prompt: { enabled: true, category: 'core' },
+      correction_observer: { enabled: false, category: 'quiet' },
+    },
+    runtimeProfiles: {
+      lmstudio: {
+        type: 'pi-ai',
+        provider: overrides?.provider ?? 'lmstudio',
+        model: overrides?.model ?? 'local-model',
+        apiKeyEnv: 'LMSTUDIO_API_KEY',
+        baseUrl: 'http://localhost:1234/v1',
+      },
+    },
+    internalAgents: {
+      defaultRuntime: 'lmstudio',
+      agents: {
+        diagnostician: {
+          enabled: true,
+          runtimeProfile: 'lmstudio',
+        },
+      },
+    },
+  };
+}
+
+// ── Tests ──────────────────────────────────────────────────────────────────
+
+describe('PRI-393: runtime config unification', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = mkTmpDir();
+  });
+
+  afterEach(() => {
+    rmTmpDir(tmpDir);
+  });
+
+  describe('Guard: legacy resolveRuntimeConfig not imported by production commands', () => {
+    it('production command source files do NOT import legacy resolveRuntimeConfig', () => {
+      // Read the source of each production command and verify the import
+      const commandFiles = [
+        'packages/pd-cli/src/commands/runtime.ts',
+        'packages/pd-cli/src/commands/runtime-internalization-run-once.ts',
+        'packages/pd-cli/src/commands/diagnose.ts',
+        'packages/pd-cli/src/commands/pain-retry.ts',
+      ];
+
+      for (const file of commandFiles) {
+        const fullPath = path.resolve(file);
+        if (!fs.existsSync(fullPath)) continue;
+        const source = fs.readFileSync(fullPath, 'utf8');
+
+        // Check that resolveRuntimeConfig is NOT imported from @principles/core/runtime-v2
+        // (it may appear in comments or as resolveRuntimeConfigFromPdConfig)
+        // Match the full import block (handles multi-line imports)
+        const importPattern = /import\s*[\s\S]*?@principles\/core\/runtime-v2['";]/g;
+        const importBlocks: string[] = [];
+        let match;
+        while ((match = importPattern.exec(source)) !== null) {
+          importBlocks.push(match[0]);
+        }
+
+        for (const block of importBlocks) {
+          // Allow resolveRuntimeConfigFromPdConfig but NOT bare resolveRuntimeConfig
+          if (block.includes('resolveRuntimeConfig') && !block.includes('resolveRuntimeConfigFromPdConfig')) {
+            // This is the legacy import — fail
+            expect.fail(
+              `${file} still imports legacy resolveRuntimeConfig from @principles/core/runtime-v2. ` +
+              `Use resolveRuntimeFromPdConfig() from services/resolve-runtime-from-pd-config.ts instead.`,
+            );
+          }
+        }
+      }
+    });
+  });
+
+  describe('Config source alignment via mainline contract', () => {
+    function makeBaseSnapshot(readiness: Partial<MainlineSnapshot['readiness']>): MainlineSnapshot {
+      return {
+        readiness: {
+          configDoctorProfile: null,
+          runtimeProbeProfile: null,
+          configSource: '.pd/config.yaml',
+          probeConfigSource: '.pd/config.yaml',
+          diagnosticianReady: true,
+          ...readiness,
+        },
+        chain: {
+          painId: null,
+          diagnosisTask: null,
+          diagnosticianArtifact: null,
+          candidate: null,
+          dreamerTask: null,
+          dreamerContext: null,
+          successor: null,
+          principle: null,
+        },
+      };
+    }
+
+    it('violation: doctor and probe use different config sources (drift)', () => {
+      const snapshot = makeBaseSnapshot({
+        configDoctorProfile: 'pi-ai.lmstudio',
+        runtimeProbeProfile: 'pi-ai.sensenova-cn',
+        configSource: '.pd/config.yaml',
+        probeConfigSource: '.state/workflows.yaml',
+      });
+
+      const verdict = assertMainlineContract(snapshot);
+      const alignmentStage = verdict.stages.find((s) => s.stage === 'config_source_alignment');
+
+      expect(alignmentStage).toBeDefined();
+      expect(alignmentStage!.status).toBe('violation');
+      expect(alignmentStage!.reason).toContain('drift');
+      expect(alignmentStage!.nextAction).toContain('.pd/config.yaml');
+    });
+
+    it('violation: profiles match but probe reads from workflows.yaml (coincidental)', () => {
+      const snapshot = makeBaseSnapshot({
+        configDoctorProfile: 'pi-ai.lmstudio',
+        runtimeProbeProfile: 'pi-ai.lmstudio',
+        configSource: '.pd/config.yaml',
+        probeConfigSource: '.state/workflows.yaml',
+      });
+
+      const verdict = assertMainlineContract(snapshot);
+      const alignmentStage = verdict.stages.find((s) => s.stage === 'config_source_alignment');
+
+      expect(alignmentStage).toBeDefined();
+      expect(alignmentStage!.status).toBe('violation');
+      expect(alignmentStage!.reason).toContain('coincidental');
+    });
+
+    it('ok: doctor and probe agree on same profile from .pd/config.yaml', () => {
+      const snapshot = makeBaseSnapshot({
+        configDoctorProfile: 'pi-ai.lmstudio',
+        runtimeProbeProfile: 'pi-ai.lmstudio',
+        configSource: '.pd/config.yaml',
+        probeConfigSource: '.pd/config.yaml',
+      });
+
+      const verdict = assertMainlineContract(snapshot);
+      const alignmentStage = verdict.stages.find((s) => s.stage === 'config_source_alignment');
+
+      expect(alignmentStage).toBeDefined();
+      expect(alignmentStage!.status).toBe('ok');
+      expect(alignmentStage!.reason).toContain('.pd/config.yaml');
+    });
+  });
+
+  describe('resolveRuntimeFromPdConfig reads .pd/config.yaml', () => {
+    it('resolves pi-ai config from .pd/config.yaml', async () => {
+      writeConfigYaml(tmpDir, makeValidConfigYaml());
+
+      // Dynamically import to avoid module resolution issues
+      const { resolveRuntimeFromPdConfig } = await import('../../src/services/resolve-runtime-from-pd-config.js');
+      const resolved = resolveRuntimeFromPdConfig(tmpDir, () => 'test-key');
+
+      expect(resolved.configSource).toBe('.pd/config.yaml');
+      expect(resolved.result).toBeDefined();
+      // Should not be an error when config is valid
+      const { isRuntimeConfigError: isErr } = await import('@principles/core/runtime-v2');
+      expect(isErr(resolved.result)).toBe(false);
+    });
+
+    it('ignores conflicting .state/workflows.yaml when .pd/config.yaml exists', async () => {
+      // Write .pd/config.yaml with lmstudio
+      writeConfigYaml(tmpDir, makeValidConfigYaml({ provider: 'lmstudio', model: 'local-model' }));
+
+      // Write conflicting .state/workflows.yaml
+      writeLegacyWorkflowsYaml(tmpDir, `version: '1'
+funnels:
+  - workflowId: pd-runtime-v2-diagnosis
+    stages: []
+    policy:
+      runtimeKind: pi-ai
+      provider: sensenova-cn
+      model: deepseek-v4-flash
+      apiKeyEnv: SENSENOVA_API_KEY
+`);
+
+      const { resolveRuntimeFromPdConfig } = await import('../../src/services/resolve-runtime-from-pd-config.js');
+      const resolved = resolveRuntimeFromPdConfig(tmpDir, () => 'test-key');
+
+      // Should have legacy warning
+      expect(resolved.legacyWarnings.length).toBeGreaterThan(0);
+      expect(resolved.legacyWarnings[0]).toContain('workflows.yaml');
+
+      // Should resolve from .pd/config.yaml, NOT workflows.yaml
+      const { isRuntimeConfigError: isErr } = await import('@principles/core/runtime-v2');
+      if (!isErr(resolved.result)) {
+        expect(resolved.result.provider).not.toBe('sensenova-cn');
+      }
+      expect(resolved.configSource).toBe('.pd/config.yaml');
+    });
+
+    it('fail loud when .pd/config.yaml is malformed', async () => {
+      const pdDir = path.join(tmpDir, '.pd');
+      fs.mkdirSync(pdDir, { recursive: true });
+      fs.writeFileSync(path.join(pdDir, 'config.yaml'), 'version: [unterminated', 'utf8');
+
+      const { resolveRuntimeFromPdConfig } = await import('../../src/services/resolve-runtime-from-pd-config.js');
+      const { isRuntimeConfigError: isErr } = await import('@principles/core/runtime-v2');
+      const resolved = resolveRuntimeFromPdConfig(tmpDir, () => 'test-key');
+
+      // Malformed config must produce a RuntimeConfigError — never fall back to defaults
+      expect(resolved.configLoadResult.ok).toBe(false);
+      expect(resolved.configSource).toBe('.pd/config.yaml');
+      expect(isErr(resolved.result)).toBe(true);
+      if (isErr(resolved.result)) {
+        expect(resolved.result.reason).toContain('config_malformed');
+        expect(resolved.result.nextAction).toBeTruthy();
+      }
+    });
+  });
+
+  describe('JSON output purity', () => {
+    it('resolveRuntimeFromPdConfig result serializes to valid JSON', async () => {
+      writeConfigYaml(tmpDir, makeValidConfigYaml());
+
+      const { resolveRuntimeFromPdConfig } = await import('../../src/services/resolve-runtime-from-pd-config.js');
+      const resolved = resolveRuntimeFromPdConfig(tmpDir, () => 'test-key');
+
+      const jsonStr = JSON.stringify(resolved.result);
+      const parsed = JSON.parse(jsonStr);
+      expect(parsed).toBeDefined();
+      expect(typeof parsed).toBe('object');
+    });
+  });
+});

package/tests/commands/runtime-internalization-integrity.test.ts

@@ -1,11 +1,18 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
+import * as path from 'path';
 
 const mockCheck = vi.hoisted(() => vi.fn());
+const mockAssemble = vi.hoisted(() => vi.fn());
 
 vi.mock('../../src/resolve-workspace.js', () => ({
   resolveWorkspaceDir: vi.fn().mockReturnValue('/fake/workspace'),
 }));
 
+vi.mock('../../src/services/mainline-snapshot-assembler.js', () => ({
+  assembleMainlineSnapshot: mockAssemble,
+  assertMainlineContract: vi.fn(),
+}));
+
 vi.mock('@principles/core/runtime-v2', () => ({
   InternalizationChainIntegrityReadModel: vi.fn().mockImplementation(function () {
     return { check: mockCheck };
@@ -14,9 +21,32 @@ vi.mock('@principles/core/runtime-v2', () => ({
 }));
 
 import { handleRuntimeInternalizationIntegrity } from '../../src/commands/runtime-internalization-integrity.js';
+import { InternalizationChainIntegrityReadModel } from '@principles/core/runtime-v2';
 
 const WS = '/fake/workspace';
 
+function fakeSnapshot() {
+  return {
+    readiness: {
+      configDoctorProfile: 'openclaw.default',
+      runtimeProbeProfile: 'openclaw.default',
+      configSource: '.pd/config.yaml',
+      probeConfigSource: '.pd/config.yaml',
+      diagnosticianReady: true,
+    },
+    chain: {
+      painId: 'pain-test',
+      diagnosisTask: null,
+      diagnosticianArtifact: null,
+      candidate: null,
+      dreamerTask: null,
+      dreamerContext: null,
+      successor: null,
+      principle: null,
+    },
+  };
+}
+
 function okResult() {
   return {
     overallStatus: 'ok' as const,
@@ -59,6 +89,7 @@ describe('handleRuntimeInternalizationIntegrity', () => {
 
   beforeEach(() => {
     vi.clearAllMocks();
+    mockAssemble.mockResolvedValue({ snapshot: fakeSnapshot(), warnings: [], resolvedPainId: 'pain-test' });
     consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
     consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
   });
@@ -68,6 +99,12 @@ describe('handleRuntimeInternalizationIntegrity', () => {
 
     await handleRuntimeInternalizationIntegrity({ workspace: WS, json: true });
 
+    const resolvedWorkspace = path.resolve(WS);
+    expect(mockAssemble).toHaveBeenCalledWith({ workspaceDir: resolvedWorkspace });
+    const modelCallArgs = (InternalizationChainIntegrityReadModel as unknown as ReturnType<typeof vi.fn>).mock.calls[0][0];
+    expect(modelCallArgs.workspaceDir).toBe(resolvedWorkspace);
+    expect(modelCallArgs.mainlineSnapshot).toEqual(fakeSnapshot());
+
     const jsonOutput = JSON.parse(consoleLogSpy.mock.calls[0][0]);
     expect(jsonOutput.overallStatus).toBe('ok');
     expect(jsonOutput.brokenLinks).toEqual([]);

package/tests/commands/runtime-internalization-run-once.test.ts

@@ -20,6 +20,27 @@ vi.mock('../../src/resolve-workspace.js', () => ({
   resolveWorkspaceDir: vi.fn().mockReturnValue('/fake/workspace'),
 }));
 
+const { mockResolveRuntimeFromPdConfig } = vi.hoisted(() => {
+  const mockResolveRuntimeFromPdConfig = vi.fn().mockReturnValue({
+    result: {
+      runtimeKind: 'pi-ai',
+      provider: 'test-provider',
+      model: 'test-model',
+      apiKeyEnv: 'TEST_API_KEY',
+      timeoutMs: 300_000,
+      agentId: 'main',
+    },
+    legacyWarnings: [],
+    configSource: '.pd/config.yaml',
+    configLoadResult: { ok: true, effective: {}, defaults: {}, legacyFilesDetected: [] },
+  });
+  return { mockResolveRuntimeFromPdConfig };
+});
+
+vi.mock('../../src/services/resolve-runtime-from-pd-config.js', () => ({
+  resolveRuntimeFromPdConfig: mockResolveRuntimeFromPdConfig,
+}));
+
 vi.mock('@principles/core/runtime-v2', () => ({
   RuntimeStateManager: vi.fn().mockImplementation(function () {
     return {
@@ -120,8 +141,9 @@ vi.mock('@principles/core/runtime-v2', () => ({
     model: 'test-model',
     apiKeyEnv: 'TEST_API_KEY',
   }),
-  isRuntimeConfigError: vi.fn().mockReturnValue(false),
+  isRuntimeConfigError: vi.fn().mockImplementation((result: unknown) => result != null && typeof result === 'object' && Object.hasOwn(result, 'reason') && !Object.hasOwn(result, 'runtimeKind')),
   validateRuntimeConfig: vi.fn(),
+  resolveRuntimeConfigFromPdConfig: vi.fn().mockReturnValue({ runtimeKind: 'pi-ai', provider: 'test-provider', model: 'test-model', apiKeyEnv: 'TEST_API_KEY', timeoutMs: 300_000, agentId: 'main' }),
   resolveOutputLanguage: vi.fn().mockReturnValue({ outputLanguage: 'zh-CN' }),
 }));
 
@@ -381,12 +403,16 @@ describe('handleRuntimeInternalizationRunOnce', () => {
   });
 
   it('--runtime openclaw-cli resolves OpenClawCliRuntimeAdapter', async () => {
-    const { resolveRuntimeConfig } = await import('@principles/core/runtime-v2');
-    vi.mocked(resolveRuntimeConfig).mockReturnValue({
-      runtimeKind: 'openclaw-cli',
-      openclawMode: 'local',
-      timeoutMs: 300_000,
-      agentId: 'main',
+    mockResolveRuntimeFromPdConfig.mockReturnValueOnce({
+      result: {
+        runtimeKind: 'openclaw-cli',
+        openclawMode: 'local',
+        timeoutMs: 300_000,
+        agentId: 'main',
+      },
+      legacyWarnings: [],
+      configSource: '.pd/config.yaml',
+      configLoadResult: { ok: true, effective: {}, defaults: {}, legacyFilesDetected: [] },
     });
 
     mockWakeOnce.mockResolvedValue({
@@ -412,31 +438,7 @@ describe('handleRuntimeInternalizationRunOnce', () => {
     expect(OpenClawMock).toHaveBeenCalled();
   });
 
-  it('--runtime config resolves adapter from workflows.yaml', async () => {
-    mockWakeOnce.mockResolvedValue({
-      decision: 'would_lease',
-      taskId: 'task-dreamer-008',
-      taskKind: 'dreamer',
-    });
-
-    mockRun.mockResolvedValue({
-      status: 'succeeded',
-      taskId: 'task-dreamer-008',
-      runId: 'run-008',
-      artifactId: 'pi-art-task-dreamer-008-run-008',
-      resultRef: 'dreamer://run-008',
-      attemptCount: 1,
-    });
-
-    await handleRuntimeInternalizationRunOnce({ workspace: WS, runtime: 'config', json: true });
-
-    const ResolveConfigMock = vi.mocked(
-      await import('@principles/core/runtime-v2').then(m => m.resolveRuntimeConfig),
-    );
-    expect(ResolveConfigMock).toHaveBeenCalled();
-  });
-
-  it('--runtime config reads from workspaceDir/.state (not .pd)', async () => {
+  it('--runtime config resolves adapter from .pd/config.yaml with workspace path (PRI-393)', async () => {
     mockWakeOnce.mockResolvedValue({
       decision: 'would_lease',
       taskId: 'task-dreamer-009',
@@ -455,12 +457,10 @@ describe('handleRuntimeInternalizationRunOnce', () => {
     const customWs = '/tmp/test-workspace';
     await handleRuntimeInternalizationRunOnce({ workspace: customWs, runtime: 'config', json: true });
 
-    const ResolveConfigMock = vi.mocked(
-      await import('@principles/core/runtime-v2').then(m => m.resolveRuntimeConfig),
+    // PRI-393: verify resolveRuntimeFromPdConfig was called with workspace dir
+    expect(mockResolveRuntimeFromPdConfig).toHaveBeenCalledWith(
+      expect.stringContaining('test-workspace'),
     );
-    const resolvedWorkspace = path.resolve(customWs);
-    const expectedStateDir = path.join(resolvedWorkspace, '.state');
-    expect(ResolveConfigMock).toHaveBeenCalledWith(expectedStateDir, { requestedRuntimeKind: 'config' });
   });
 
   it('--runner philosopher dispatches PhilosopherRunner', async () => {
@@ -810,7 +810,7 @@ describe('handleRuntimeInternalizationRunOnce', () => {
     expect(output.timeoutSource).toBe('runner_poll');
   });
 
-  it('--timeout-ms overrides workflows.yaml timeoutMs for PiAiRuntimeAdapter', async () => {
+  it('--timeout-ms overrides .pd/config.yaml timeoutMs for PiAiRuntimeAdapter (PRI-393)', async () => {
     mockWakeOnce.mockResolvedValue({
       decision: 'would_lease',
       taskId: 'task-dreamer-ov',
@@ -1258,14 +1258,17 @@ describe('handleRuntimeInternalizationRunOnce', () => {
   });
 
   it('--runtime config with missing config outputs structured JSON error', async () => {
-    const { resolveRuntimeConfig, isRuntimeConfigError } = await import('@principles/core/runtime-v2');
-    vi.mocked(resolveRuntimeConfig).mockReturnValue({
-      ok: false,
-      reason: 'explicit_config_missing',
-      message: 'runtime=config requested but no workflows.yaml funnel policy found',
-      nextAction: 'Create a pd-runtime-v2-diagnosis funnel policy in workflows.yaml',
+    // PRI-393: mock resolveRuntimeFromPdConfig to return config error
+    mockResolveRuntimeFromPdConfig.mockReturnValueOnce({
+      result: {
+        reason: 'explicit_config_missing',
+        message: 'runtime=config requested but no .pd/config.yaml runtime binding found',
+        nextAction: 'Add runtime binding to .pd/config.yaml',
+      },
+      legacyWarnings: [],
+      configSource: '.pd/config.yaml',
+      configLoadResult: { ok: false, effective: {}, defaults: {}, legacyFilesDetected: [] },
     });
-    vi.mocked(isRuntimeConfigError).mockReturnValue(true);
 
     mockWakeOnce.mockResolvedValue({
       decision: 'would_lease',
@@ -1283,14 +1286,17 @@ describe('handleRuntimeInternalizationRunOnce', () => {
   });
 
   it('--runtime config with missing config outputs text error', async () => {
-    const { resolveRuntimeConfig, isRuntimeConfigError } = await import('@principles/core/runtime-v2');
-    vi.mocked(resolveRuntimeConfig).mockReturnValue({
-      ok: false,
-      reason: 'explicit_config_missing',
-      message: 'runtime=config requested but no workflows.yaml funnel policy found',
-      nextAction: 'Create a pd-runtime-v2-diagnosis funnel policy in workflows.yaml',
-    });
-    vi.mocked(isRuntimeConfigError).mockReturnValue(true);
+    // PRI-393: mock resolveRuntimeFromPdConfig to return config error
+    mockResolveRuntimeFromPdConfig.mockReturnValueOnce({
+      result: {
+        reason: 'explicit_config_missing',
+        message: 'runtime=config requested but no .pd/config.yaml runtime binding found',
+        nextAction: 'Add runtime binding to .pd/config.yaml',
+      },
+      legacyWarnings: [],
+      configSource: '.pd/config.yaml',
+      configLoadResult: { ok: false, effective: {}, defaults: {}, legacyFilesDetected: [] },
+    });
 
     mockWakeOnce.mockResolvedValue({
       decision: 'would_lease',

package/tests/commands/runtime.test.ts

@@ -1,7 +1,36 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { handleRuntimeProbe, type RuntimeProbeOptions } from '../../src/commands/runtime.js';
 
-// Mock probeRuntime
+// Mock resolveRuntimeWithOverrides
+const { mockResolveRuntimeWithOverrides } = vi.hoisted(() => {
+  const fn = vi.fn().mockReturnValue({
+    result: {
+      runtimeKind: 'pi-ai',
+      provider: 'test-provider',
+      model: 'test-model',
+      apiKeyEnv: 'TEST_API_KEY',
+      maxRetries: 2,
+      timeoutMs: 180_000,
+    },
+    mergedConfig: {
+      runtimeKind: 'pi-ai',
+      provider: 'test-provider',
+      model: 'test-model',
+      apiKeyEnv: 'TEST_API_KEY',
+      maxRetries: 2,
+      timeoutMs: 180_000,
+    },
+    legacyWarnings: [],
+    configSource: '.pd/config.yaml',
+    configLoadResult: { ok: true, effective: {}, defaults: {}, legacyFilesDetected: [] },
+  });
+  return { mockResolveRuntimeWithOverrides: fn };
+});
+
+vi.mock('../../src/services/resolve-runtime-from-pd-config.js', () => ({
+  resolveRuntimeWithOverrides: mockResolveRuntimeWithOverrides,
+}));
+
 vi.mock('@principles/core/runtime-v2', () => ({
   probeRuntime: vi.fn().mockResolvedValue({
     runtimeKind: 'openclaw-cli',
@@ -260,4 +289,98 @@ describe('pd runtime probe', () => {
     consoleErrorSpy.mockRestore();
     exitSpy.mockRestore();
   });
+
+  // ── pi-ai probe: maxRetries backfill from .pd/config.yaml ───────────────
+  it('PRI-393: pi-ai probe reads maxRetries from .pd/config.yaml when --maxRetries not passed', async () => {
+    process.env.TEST_API_KEY = 'test-value';
+    const { probeRuntime } = await import('@principles/core/runtime-v2');
+    vi.mocked(probeRuntime).mockResolvedValue({
+      runtimeKind: 'pi-ai',
+      provider: 'test-provider',
+      model: 'test-model',
+      health: { healthy: true, degraded: false, warnings: [], lastCheckedAt: '2026-06-14T00:00:00.000Z' },
+      capabilities: {},
+    });
+
+    const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => undefined) as () => never);
+
+    // mockResolveRuntimeWithOverrides returns maxRetries: 2
+    // No --maxRetries CLI flag
+    await handleRuntimeProbe({
+      runtime: 'pi-ai',
+      provider: 'test-provider',
+      model: 'test-model',
+      apiKeyEnv: 'TEST_API_KEY',
+      workspace: '/tmp/ws',
+      json: true,
+    } as RuntimeProbeOptions);
+
+    expect(vi.mocked(probeRuntime)).toHaveBeenCalledWith(
+      expect.objectContaining({ maxRetries: 2 }),
+    );
+
+    delete process.env.TEST_API_KEY;
+    consoleSpy.mockRestore();
+    exitSpy.mockRestore();
+  });
+
+  it('PRI-393: CLI --maxRetries overrides .pd/config.yaml maxRetries', async () => {
+    process.env.TEST_API_KEY = 'test-value';
+    const { probeRuntime } = await import('@principles/core/runtime-v2');
+    vi.mocked(probeRuntime).mockResolvedValue({
+      runtimeKind: 'pi-ai',
+      provider: 'test-provider',
+      model: 'test-model',
+      health: { healthy: true, degraded: false, warnings: [], lastCheckedAt: '2026-06-14T00:00:00.000Z' },
+      capabilities: {},
+    });
+
+    const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => undefined) as () => never);
+
+    await handleRuntimeProbe({
+      runtime: 'pi-ai',
+      provider: 'test-provider',
+      model: 'test-model',
+      apiKeyEnv: 'TEST_API_KEY',
+      maxRetries: 5,
+      workspace: '/tmp/ws',
+      json: true,
+    } as RuntimeProbeOptions);
+
+    expect(vi.mocked(probeRuntime)).toHaveBeenCalledWith(
+      expect.objectContaining({ maxRetries: 5 }),
+    );
+
+    delete process.env.TEST_API_KEY;
+    consoleSpy.mockRestore();
+    exitSpy.mockRestore();
+  });
+
+  it('PRI-393: env var missing → process.exit(1) and does NOT call probeRuntime', async () => {
+    const { probeRuntime } = await import('@principles/core/runtime-v2');
+    vi.mocked(probeRuntime).mockClear();
+
+    // Ensure NONEXISTENT_VAR is NOT set
+    delete process.env.NONEXISTENT_VAR;
+
+    const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => undefined) as () => never);
+
+    await handleRuntimeProbe({
+      runtime: 'pi-ai',
+      provider: 'test-provider',
+      model: 'test-model',
+      apiKeyEnv: 'NONEXISTENT_VAR',
+      json: true,
+    } as RuntimeProbeOptions);
+
+    expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('NONEXISTENT_VAR'));
+    expect(exitSpy).toHaveBeenCalledWith(1);
+    expect(vi.mocked(probeRuntime)).not.toHaveBeenCalled();
+
+    consoleErrorSpy.mockRestore();
+    exitSpy.mockRestore();
+  });
 });