@principles/pd-cli 1.108.0 → 1.109.0

package/src/commands/__tests__/runtime-probe-config.test.ts

@@ -0,0 +1,431 @@
+/**
+ * PRI-402: pd runtime probe reads .pd/config.yaml for pi-ai config.
+ *
+ * Tests cover:
+ *   - probe reads config from .pd/config.yaml when --workspace is provided
+ *   - JSON output includes configSource, runtimeProfileId, runtimeProfileLabel
+ *   - explicit --provider overrides config.yaml
+ *   - fail-loud JSON when config.yaml is missing or incomplete
+ *   - program.parseAsync against real Commander registration (EP-04)
+ *
+ * ERR refs:
+ *   - EP-04 (CLI gate): --json stdout single object, process.exit(1) + return
+ *   - EP-03 (fail loud): structured JSON with reason + nextAction on failure
+ *   - EP-07 (source alignment): probe and doctor read same config source
+ *   - ERR-004 (source alignment): profileId/label must match doctor output
+ *   - ERR-021 (handler-only tests): add program.parseAsync tests
+ *   - ERR-029 (fail-loud JSON): config missing → structured JSON, not bare error
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { Command } from 'commander';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+// ─── Mocks ─────────────────────────────────────────────────────────────────
+
+// Mock only probeRuntime so we don't need a real LLM provider.
+// All other core functions (validatePdConfig, computeEffectivePdConfig,
+// resolveAgentRuntimeBinding, etc.) use their real implementations.
+const mockProbeRuntime = vi.fn();
+vi.mock('@principles/core/runtime-v2', async (importOriginal) => {
+  const actual = await importOriginal<Record<string, unknown>>();
+  return {
+    ...actual,
+    probeRuntime: mockProbeRuntime,
+  };
+});
+
+const { handleRuntimeProbe } = await import('../runtime.js');
+
+// ─── Test Setup ─────────────────────────────────────────────────────────────
+
+const capturedStdout: string[] = [];
+const capturedStderr: string[] = [];
+let capturedExitCode: number | null = null;
+
+const originalExit = process.exit;
+const originalLog = console.log;
+const originalError = console.error;
+const originalWarn = console.warn;
+const originalEnv = { ...process.env };
+
+beforeEach(() => {
+  capturedExitCode = null;
+  capturedStdout.length = 0;
+  capturedStderr.length = 0;
+  process.exit = vi.fn(((code?: number) => {
+    capturedExitCode = code ?? 0;
+  }) as typeof process.exit);
+  console.log = vi.fn((...args: unknown[]) => { capturedStdout.push(args.join(' ')); });
+  console.error = vi.fn((...args: unknown[]) => { capturedStderr.push(args.join(' ')); });
+  console.warn = vi.fn(() => { /* capture warnings */ });
+  mockProbeRuntime.mockReset();
+  process.env = { ...originalEnv, LMSTUDIO_API_KEY: 'test-key-for-pri-402' };
+});
+
+afterEach(() => {
+  process.exit = originalExit;
+  console.log = originalLog;
+  console.error = originalError;
+  console.warn = originalWarn;
+  process.env = originalEnv;
+});
+
+// ─── Helper: create temp workspace with .pd/config.yaml ────────────────────
+
+function createTempWorkspace(configYaml: string): string {
+  const tmpDir = path.join(os.tmpdir(), `pd-probe-test-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+  const pdDir = path.join(tmpDir, '.pd');
+  fs.mkdirSync(pdDir, { recursive: true });
+  // Replace __WORKSPACE_DIR__ placeholder with actual path
+  const resolvedYaml = configYaml.replace(/__WORKSPACE_DIR__/g, tmpDir.replace(/\\/g, '/'));
+  fs.writeFileSync(path.join(pdDir, 'config.yaml'), resolvedYaml, 'utf-8');
+  return tmpDir;
+}
+
+function cleanupWorkspace(dir: string): void {
+  try {
+    fs.rmSync(dir, { recursive: true, force: true });
+  } catch {
+    // best effort
+  }
+}
+
+const PI_AI_CONFIG_YAML = `
+version: 1
+features:
+  prompt: { category: core, enabled: true }
+  code_tool_hook: { category: core, enabled: true }
+  defer_archive: { category: core, enabled: true }
+workspace:
+  default: __WORKSPACE_DIR__
+internalAgents:
+  defaultRuntime: pi-ai.lmstudio
+  agents:
+    diagnostician:
+      enabled: true
+      runtimeProfile: pi-ai.lmstudio
+    dreamer:
+      enabled: true
+    philosopher:
+      enabled: true
+    scribe:
+      enabled: true
+    artificer:
+      enabled: true
+runtimeProfiles:
+  pi-ai.lmstudio:
+    type: pi-ai
+    provider: lmstudio
+    model: qwen3.6-27b-mtp
+    apiKeyEnv: LMSTUDIO_API_KEY
+    baseUrl: http://localhost:1234/v1
+`;
+
+// ─── Tests: probe reads config from .pd/config.yaml ────────────────────────
+
+describe('PRI-402: probe reads .pd/config.yaml for pi-ai config', () => {
+  it('reads provider/model from config.yaml when --workspace provided without --provider', async () => {
+    const workspace = createTempWorkspace(PI_AI_CONFIG_YAML);
+    try {
+      mockProbeRuntime.mockResolvedValue({
+        runtimeKind: 'pi-ai',
+        provider: 'lmstudio',
+        model: 'qwen3.6-27b-mtp',
+        health: { healthy: true, degraded: false, warnings: [], lastCheckedAt: '2026-01-01T00:00:00Z' },
+        capabilities: { streaming: true },
+      });
+
+      await handleRuntimeProbe({
+        runtime: 'pi-ai',
+        workspace,
+        json: true,
+      });
+
+      // probeRuntime should be called with config.yaml values
+      expect(mockProbeRuntime).toHaveBeenCalled();
+      const callArgs = mockProbeRuntime.mock.calls[0]?.[0];
+      expect(callArgs?.provider).toBe('lmstudio');
+      expect(callArgs?.model).toBe('qwen3.6-27b-mtp');
+      expect(callArgs?.apiKeyEnv).toBe('LMSTUDIO_API_KEY');
+
+      // JSON output should contain configSource, runtimeProfileId, runtimeProfileLabel
+      const output = JSON.parse(capturedStdout.join(''));
+      expect(output.configSource).toBe('.pd/config.yaml');
+      expect(output.runtimeProfileId).toBe('pi-ai.lmstudio');
+      expect(output.runtimeProfileLabel).toBe('pi-ai: lmstudio/qwen3.6-27b-mtp');
+      expect(output.ok).toBe(true);
+    } finally {
+      cleanupWorkspace(workspace);
+    }
+  });
+
+  it('explicit --provider overrides config.yaml value', async () => {
+    const workspace = createTempWorkspace(PI_AI_CONFIG_YAML);
+    try {
+      mockProbeRuntime.mockResolvedValue({
+        runtimeKind: 'pi-ai',
+        provider: 'openrouter',
+        model: 'qwen3.6-27b-mtp',
+        health: { healthy: true, degraded: false, warnings: [], lastCheckedAt: '2026-01-01T00:00:00Z' },
+        capabilities: { streaming: true },
+      });
+
+      await handleRuntimeProbe({
+        runtime: 'pi-ai',
+        workspace,
+        provider: 'openrouter',
+        model: 'anthropic/claude-sonnet-4',
+        apiKeyEnv: 'OPENROUTER_API_KEY',
+        json: true,
+      });
+
+      const callArgs = mockProbeRuntime.mock.calls[0]?.[0];
+      // CLI flags override config.yaml
+      expect(callArgs?.provider).toBe('openrouter');
+      expect(callArgs?.model).toBe('anthropic/claude-sonnet-4');
+      expect(callArgs?.apiKeyEnv).toBe('OPENROUTER_API_KEY');
+
+      // Profile info still comes from config.yaml (EP-07: source alignment)
+      const output = JSON.parse(capturedStdout.join(''));
+      expect(output.configSource).toBe('.pd/config.yaml');
+      expect(output.runtimeProfileId).toBe('pi-ai.lmstudio');
+    } finally {
+      cleanupWorkspace(workspace);
+    }
+  });
+
+  it('fail-loud JSON when config.yaml is missing and no --provider', async () => {
+    const workspace = path.join(os.tmpdir(), `pd-probe-test-missing-${Date.now()}`);
+    fs.mkdirSync(workspace, { recursive: true });
+    // No .pd/config.yaml created
+    try {
+      await handleRuntimeProbe({
+        runtime: 'pi-ai',
+        workspace,
+        json: true,
+      });
+
+      expect(capturedExitCode).toBe(1);
+      const output = JSON.parse(capturedStdout.join(''));
+      expect(output.ok).toBe(false);
+      expect(output.status).toBe('failed');
+      expect(typeof output.reason).toBe('string');
+      expect(typeof output.nextAction).toBe('string');
+      // Single parseable JSON object (EP-04 Rule 1)
+      expect(Array.isArray(output)).toBe(false);
+    } finally {
+      cleanupWorkspace(workspace);
+    }
+  });
+
+  it('fail-loud JSON when provider missing from config.yaml', async () => {
+    const workspace = createTempWorkspace(`
+version: 1
+features:
+  prompt: { category: core, enabled: true }
+  code_tool_hook: { category: core, enabled: true }
+  defer_archive: { category: core, enabled: true }
+workspace:
+  default: __WORKSPACE_DIR__
+internalAgents:
+  defaultRuntime: pi-ai.broken
+  agents:
+    diagnostician:
+      enabled: true
+      runtimeProfile: pi-ai.broken
+runtimeProfiles:
+  pi-ai.broken:
+    type: pi-ai
+    # Missing provider, model, apiKeyEnv
+`);
+    try {
+      await handleRuntimeProbe({
+        runtime: 'pi-ai',
+        workspace,
+        json: true,
+      });
+
+      expect(capturedExitCode).toBe(1);
+      const output = JSON.parse(capturedStdout.join(''));
+      expect(output.ok).toBe(false);
+      expect(output.status).toBe('failed');
+      expect(typeof output.reason).toBe('string');
+      expect(typeof output.nextAction).toBe('string');
+    } finally {
+      cleanupWorkspace(workspace);
+    }
+  });
+
+  it('fail-loud JSON when apiKeyEnv env var is not set', async () => {
+    const workspace = createTempWorkspace(PI_AI_CONFIG_YAML);
+    try {
+      // Remove the API key env var
+      delete process.env.LMSTUDIO_API_KEY;
+
+      await handleRuntimeProbe({
+        runtime: 'pi-ai',
+        workspace,
+        json: true,
+      });
+
+      expect(capturedExitCode).toBe(1);
+      const output = JSON.parse(capturedStdout.join(''));
+      expect(output.ok).toBe(false);
+      // When apiKeyEnv is not set, resolveRuntimeConfigFromPdConfig returns
+      // a config error (not_ready), so the error comes from the config resolution path
+      expect(typeof output.reason).toBe('string');
+      expect(typeof output.nextAction).toBe('string');
+    } finally {
+      cleanupWorkspace(workspace);
+    }
+  });
+
+  it('human-readable output includes Profile and Config lines', async () => {
+    const workspace = createTempWorkspace(PI_AI_CONFIG_YAML);
+    try {
+      mockProbeRuntime.mockResolvedValue({
+        runtimeKind: 'pi-ai',
+        provider: 'lmstudio',
+        model: 'qwen3.6-27b-mtp',
+        health: { healthy: true, degraded: false, warnings: [], lastCheckedAt: '2026-01-01T00:00:00Z' },
+        capabilities: { streaming: true },
+      });
+
+      await handleRuntimeProbe({
+        runtime: 'pi-ai',
+        workspace,
+        json: false,
+      });
+
+      const output = capturedStdout.join('\n');
+      expect(output).toContain('Profile:');
+      expect(output).toContain('pi-ai: lmstudio/qwen3.6-27b-mtp');
+      expect(output).toContain('Config:');
+      expect(output).toContain('.pd/config.yaml');
+    } finally {
+      cleanupWorkspace(workspace);
+    }
+  });
+});
+
+// ─── Tests: program.parseAsync against real Commander registration (EP-04) ──
+
+// Import the real command registration function to test actual production wiring
+const { registerRuntimeProbeCommand } = await import('../runtime.js');
+
+interface CapturedAction {
+  opts: Record<string, unknown> | null;
+}
+
+function attachCapture(cmd: Command, state: CapturedAction): void {
+  // Override the action handler to capture opts without calling the real handler
+  cmd.action((...args: unknown[]) => {
+    // Find the opts object (last non-Command, non-null object arg)
+    let optsArg: Record<string, unknown> | null = null;
+    for (let i = args.length - 1; i >= 0; i--) {
+      const arg: unknown = args[i];
+      if (arg !== null && typeof arg === 'object' && !(arg instanceof Command)) {
+        optsArg = arg as Record<string, unknown>;
+        break;
+      }
+    }
+    state.opts = optsArg ?? {};
+    // Do NOT call original action (would call handleRuntimeProbe which needs real runtime)
+  });
+}
+
+function freshProgram(): Command {
+  const program = new Command();
+  program.name('pd').exitOverride();
+  return program;
+}
+
+describe('PRI-402: probe command flag wiring (EP-04 real registration)', () => {
+  it('registers --runtime as required option via real registration', () => {
+    const program = freshProgram();
+    const runtimeCmd = program.command('runtime');
+    const probeCmd = registerRuntimeProbeCommand(runtimeCmd);
+
+    const runtimeOpt = probeCmd.options.find((o) => o.long === '--runtime');
+    expect(runtimeOpt).toBeDefined();
+    expect(runtimeOpt?.required).toBe(true);
+  });
+
+  it('registers --workspace with -w shorthand via real registration', () => {
+    const program = freshProgram();
+    const runtimeCmd = program.command('runtime');
+    const probeCmd = registerRuntimeProbeCommand(runtimeCmd);
+
+    const wsOpt = probeCmd.options.find((o) => o.short === '-w');
+    expect(wsOpt).toBeDefined();
+    expect(wsOpt?.long).toBe('--workspace');
+  });
+
+  it('parses --runtime pi-ai --workspace <dir> --json correctly via real registration', async () => {
+    const program = freshProgram();
+    const runtimeCmd = program.command('runtime');
+    const probeCmd = registerRuntimeProbeCommand(runtimeCmd);
+    const captured: CapturedAction = { opts: null };
+    attachCapture(probeCmd, captured);
+
+    await program.parseAsync(['node', 'pd', 'runtime', 'probe', '--runtime', 'pi-ai', '--workspace', '/tmp/test', '--json']);
+
+    expect(captured.opts).not.toBeNull();
+    if (!captured.opts) throw new Error('captured.opts is null');
+    expect(captured.opts.runtime).toBe('pi-ai');
+    expect(captured.opts.workspace).toBe('/tmp/test');
+    expect(captured.opts.json).toBe(true);
+  });
+
+  it('parses --runtime config --workspace <dir> correctly via real registration', async () => {
+    const program = freshProgram();
+    const runtimeCmd = program.command('runtime');
+    const probeCmd = registerRuntimeProbeCommand(runtimeCmd);
+    const captured: CapturedAction = { opts: null };
+    attachCapture(probeCmd, captured);
+
+    await program.parseAsync(['node', 'pd', 'runtime', 'probe', '--runtime', 'config', '--workspace', '/tmp/test']);
+
+    expect(captured.opts).not.toBeNull();
+    if (!captured.opts) throw new Error('captured.opts is null');
+    expect(captured.opts.runtime).toBe('config');
+    expect(captured.opts.workspace).toBe('/tmp/test');
+  });
+});
+
+// ─── Tests: resolve-runtime-from-pd-config profile extraction ───────────────
+
+describe('PRI-402: resolveRuntimeWithOverrides returns profile info', () => {
+  it('returns runtimeProfileId and runtimeProfileLabel from config.yaml', async () => {
+    const workspace = createTempWorkspace(PI_AI_CONFIG_YAML);
+    try {
+      const { resolveRuntimeWithOverrides } = await import('../../services/resolve-runtime-from-pd-config.js');
+      const result = resolveRuntimeWithOverrides(workspace, {});
+
+      expect(result.configSource).toBe('.pd/config.yaml');
+      expect(result.runtimeProfileId).toBe('pi-ai.lmstudio');
+      expect(result.runtimeProfileLabel).toBe('pi-ai: lmstudio/qwen3.6-27b-mtp');
+    } finally {
+      cleanupWorkspace(workspace);
+    }
+  });
+
+  it('returns default profile when config.yaml is missing', async () => {
+    const workspace = path.join(os.tmpdir(), `pd-probe-test-noprofile-${Date.now()}`);
+    fs.mkdirSync(workspace, { recursive: true });
+    try {
+      const { resolveRuntimeWithOverrides } = await import('../../services/resolve-runtime-from-pd-config.js');
+      const result = resolveRuntimeWithOverrides(workspace, {});
+
+      // Missing config → defaults, which use openclaw.default as defaultRuntime
+      expect(result.configSource).toBe('.pd/config.yaml');
+      expect(result.runtimeProfileId).toBe('openclaw.default');
+      expect(typeof result.runtimeProfileLabel).toBe('string');
+    } finally {
+      cleanupWorkspace(workspace);
+    }
+  });
+});

package/src/commands/config-doctor.ts

@@ -109,6 +109,10 @@ function formatTextOutput(output: DoctorOutput): string {
     for (const f of output.legacyFilesDetected) {
       lines.push(`  [!] ${f}`);
     }
+    // PRI-404: Show nextAction for each legacy file
+    for (const na of output.legacyFileNextActions) {
+      lines.push(`  → ${na}`);
+    }
     lines.push('');
   }
 

package/src/commands/runtime.ts

@@ -8,8 +8,8 @@
  * HG-01 HARD GATE: This command must deliver.
  */
 import * as path from 'path';
-import { probeRuntime } from '@principles/core/runtime-v2';
-import { PDRuntimeError, isRuntimeConfigError } from '@principles/core/runtime-v2';
+import type { Command } from 'commander';
+import { probeRuntime, PDRuntimeError, isRuntimeConfigError } from '@principles/core/runtime-v2';
 import { resolveRuntimeFromPdConfig, resolveRuntimeWithOverrides } from '../services/resolve-runtime-from-pd-config.js';
 
 interface RuntimeProbeOptions {
@@ -132,6 +132,11 @@ async function handleOpenClawProbe(opts: RuntimeProbeOptions): Promise<void> {
 
 /**
  * pi-ai probe branch — validates flags, calls probeRuntime, formats output.
+ *
+ * PRI-402: When --workspace is provided without explicit --provider,
+ * reads pi-ai config from .pd/config.yaml via resolveRuntimeWithOverrides.
+ * JSON output includes configSource, runtimeProfileId, runtimeProfileLabel
+ * for alignment with `pd config doctor`.
  */
 async function handlePiAiProbe(opts: RuntimeProbeOptions): Promise<void> {
   // D-01: flags are required for pi-ai probe unless --workspace is provided (policy fallback)
@@ -142,6 +147,11 @@ async function handlePiAiProbe(opts: RuntimeProbeOptions): Promise<void> {
   let baseUrl = opts.baseUrl ?? '';
   let { timeoutMs, maxRetries } = opts;
 
+  // PRI-402: Track config source and profile info for JSON output
+  let configSource: string | null = null;
+  let runtimeProfileId: string | null = null;
+  let runtimeProfileLabel: string | null = null;
+
   // PRI-393: always load workspace policy from .pd/config.yaml (not .state/workflows.yaml)
   if (workspaceDir) {
     const resolved = resolveRuntimeWithOverrides(workspaceDir, {
@@ -153,6 +163,10 @@ async function handlePiAiProbe(opts: RuntimeProbeOptions): Promise<void> {
       timeoutMs: opts.timeoutMs,
     });
     for (const w of resolved.legacyWarnings) console.warn(`Warning: ${w}`);
+
+    // PRI-402: capture profile info regardless of merge result
+    ({ configSource, runtimeProfileId, runtimeProfileLabel } = resolved);
+
     if (resolved.mergedConfig) {
       provider = provider || resolved.mergedConfig.provider || '';
       model = model || resolved.mergedConfig.model || '';
@@ -161,32 +175,92 @@ async function handlePiAiProbe(opts: RuntimeProbeOptions): Promise<void> {
       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}`);
+      // PRI-402: fail-loud JSON when config.yaml is broken (EP-03, EP-04)
+      if (opts.json) {
+        console.log(JSON.stringify({
+          ok: false,
+          status: 'failed',
+          reason: resolved.result.reason,
+          message: resolved.result.message,
+          nextAction: resolved.result.nextAction,
+          configSource: resolved.configSource,
+        }, null, 2));
+      } else {
+        console.error(`error: could not resolve runtime from .pd/config.yaml — ${resolved.result.message}`);
+        console.error(`nextAction: ${resolved.result.nextAction}`);
+      }
+      process.exit(1);
+      return;
     }
   }
 
   if (!provider) {
-    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");
+    // PRI-402: fail-loud JSON when provider is missing (EP-03, EP-04)
+    if (opts.json) {
+      console.log(JSON.stringify({
+        ok: false,
+        status: 'failed',
+        reason: 'provider_missing',
+        message: '--provider is required for --runtime pi-ai (or set in .pd/config.yaml)',
+        nextAction: 'Set provider in .pd/config.yaml runtimeProfiles, or pass --provider explicitly',
+        configSource,
+      }, null, 2));
+    } else {
+      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 .pd/config.yaml)");
-    console.error("  e.g.: pd runtime probe --runtime pi-ai --provider openrouter --model anthropic/claude-sonnet-4 --apiKeyEnv OPENROUTER_API_KEY");
+    if (opts.json) {
+      console.log(JSON.stringify({
+        ok: false,
+        status: 'failed',
+        reason: 'model_missing',
+        message: '--model is required for --runtime pi-ai (or set in .pd/config.yaml)',
+        nextAction: 'Set model in .pd/config.yaml runtimeProfiles, or pass --model explicitly',
+        configSource,
+      }, null, 2));
+    } else {
+      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 .pd/config.yaml)");
-    console.error("  e.g.: pd runtime probe --runtime pi-ai --provider openrouter --model anthropic/claude-sonnet-4 --apiKeyEnv OPENROUTER_API_KEY");
+    if (opts.json) {
+      console.log(JSON.stringify({
+        ok: false,
+        status: 'failed',
+        reason: 'apiKeyEnv_missing',
+        message: '--apiKeyEnv is required for --runtime pi-ai (or set in .pd/config.yaml)',
+        nextAction: 'Set apiKeyEnv in .pd/config.yaml runtimeProfiles, or pass --apiKeyEnv explicitly',
+        configSource,
+      }, null, 2));
+    } else {
+      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`);
+    if (opts.json) {
+      console.log(JSON.stringify({
+        ok: false,
+        status: 'failed',
+        reason: 'api_key_not_set',
+        message: `Environment variable '${apiKeyEnv}' is not set`,
+        nextAction: `Set the environment variable '${apiKeyEnv}' with a valid API key`,
+        configSource,
+      }, null, 2));
+    } else {
+      console.error(`error: environment variable '${apiKeyEnv}' is not set`);
+    }
     process.exit(1);
     return;
   }
@@ -215,7 +289,9 @@ async function handlePiAiProbe(opts: RuntimeProbeOptions): Promise<void> {
     if (!result.health.healthy) exitCode = 1;
 
     if (opts.json) {
-      console.log(JSON.stringify({
+      // PRI-402: include configSource, runtimeProfileId, runtimeProfileLabel in JSON output
+      const jsonOutput: Record<string, unknown> = {
+        ok: result.health.healthy,
         status,
         runtimeKind: result.runtimeKind,
         provider: result.provider,
@@ -223,7 +299,11 @@ async function handlePiAiProbe(opts: RuntimeProbeOptions): Promise<void> {
         baseUrlPresent: !!baseUrl,
         health: result.health,
         capabilities: result.capabilities,
-      }, null, 2));
+      };
+      if (configSource) jsonOutput.configSource = configSource;
+      if (runtimeProfileId) jsonOutput.runtimeProfileId = runtimeProfileId;
+      if (runtimeProfileLabel) jsonOutput.runtimeProfileLabel = runtimeProfileLabel;
+      console.log(JSON.stringify(jsonOutput, null, 2));
       if (exitCode !== 0) process.exit(exitCode);
       return;
     }
@@ -233,6 +313,8 @@ async function handlePiAiProbe(opts: RuntimeProbeOptions): Promise<void> {
     console.log(`Provider: ${result.provider}`);
     console.log(`Model:    ${result.model}`);
     if (baseUrl) console.log(`BaseUrl:  ${baseUrl}`);
+    if (runtimeProfileLabel) console.log(`Profile:  ${runtimeProfileLabel}`);
+    if (configSource) console.log(`Config:   ${configSource}`);
     console.log(`Status:   ${status}`);
     console.log('');
     console.log('Health:');
@@ -260,10 +342,12 @@ async function handlePiAiProbe(opts: RuntimeProbeOptions): Promise<void> {
     }
     if (opts.json) {
       console.log(JSON.stringify({
+        ok: false,
         status: 'failed',
         errorCategory,
         message,
         runtimeKind: 'pi-ai',
+        configSource,
       }, null, 2));
     } else {
       console.error(`error: ${message} (${errorCategory})`);
@@ -279,7 +363,17 @@ async function handlePiAiProbe(opts: RuntimeProbeOptions): Promise<void> {
 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');
+    if (opts.json) {
+      console.log(JSON.stringify({
+        ok: false,
+        status: 'failed',
+        reason: 'workspace_missing',
+        message: '--workspace is required for --runtime config',
+        nextAction: 'Provide --workspace <path> pointing to a PD workspace directory',
+      }, null, 2));
+    } else {
+      console.error('error: --workspace is required for --runtime config');
+    }
     process.exit(1);
     return;
   }
@@ -290,6 +384,7 @@ async function handleConfigProbe(opts: RuntimeProbeOptions): Promise<void> {
   if (isRuntimeConfigError(resolved.result)) {
     if (opts.json) {
       console.log(JSON.stringify({
+        ok: false,
         status: 'failed',
         errorCategory: 'config_error',
         message: resolved.result.message,
@@ -351,3 +446,28 @@ export async function handleRuntimeProbe(opts: RuntimeProbeOptions): Promise<voi
   process.exit(1);
   return;
 }
+
+/**
+ * Register the `pd runtime probe` command on a Commander instance.
+ * Used by index.ts and tests to ensure real command wiring is verified (EP-04).
+ */
+export function registerRuntimeProbeCommand(runtimeCmd: Command): Command {
+  return runtimeCmd
+    .command('probe')
+    .description('Probe runtime health and capabilities (HG-01 HARD GATE)')
+    .requiredOption('-r, --runtime <kind>', "Runtime kind: 'openclaw-cli', 'pi-ai', or 'config'")
+    .option('--openclaw-local', 'Use local OpenClaw (mutually exclusive with --openclaw-gateway)')
+    .option('--openclaw-gateway', 'Use gateway OpenClaw (mutually exclusive with --openclaw-local)')
+    .option('-a, --agent <agentId>', 'Agent ID to probe')
+    .option('--provider <name>', 'LLM provider (e.g., openrouter) \u2014 for pi-ai, falls back to .pd/config.yaml')
+    .option('--model <id>', 'Model ID (e.g., anthropic/claude-sonnet-4) \u2014 for pi-ai, falls back to .pd/config.yaml')
+    .option('--apiKeyEnv <name>', 'Env var name for API key (e.g., OPENROUTER_API_KEY) \u2014 for pi-ai, falls back to .pd/config.yaml')
+    .option('--baseUrl <url>', 'Custom base URL for OpenAI-compatible providers \u2014 for pi-ai, falls back to .pd/config.yaml')
+    .option('--maxRetries <n>', 'Max retry attempts for LLM failures', parseInt)
+    .option('--timeoutMs <ms>', 'Timeout in milliseconds for probe', parseInt)
+    .option('-w, --workspace <path>', 'Workspace directory \u2014 loads pi-ai config from .pd/config.yaml')
+    .option('--json', 'Output raw JSON')
+    .action(async (opts) => {
+      await handleRuntimeProbe(opts);
+    });
+}