@principles/pd-cli 1.108.0 → 1.108.1

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);
+    });
+}

package/src/index.ts

@@ -24,7 +24,7 @@ import { handleContextBuild } from './commands/context.js';
 import { handleLegacyImportOpenClaw } from './commands/legacy-import.js';
 import { handleLegacyCleanup } from './commands/legacy-cleanup.js';
 import { handleDiagnoseStatus, handleDiagnoseRun } from './commands/diagnose.js';
-import { handleRuntimeProbe } from './commands/runtime.js';
+import { registerRuntimeProbeCommand } from './commands/runtime.js';
 import { handleFlowShow } from './commands/flow.js';
 import { handleTraceShow } from './commands/trace.js';
 import { handlePruningReport, handlePruningExplain, handlePruningReview, handlePruningRollback, handlePruningOrphans } from './commands/runtime-pruning.js';
@@ -430,24 +430,7 @@ demoCmd
     });
   });
 
-runtimeCmd
-  .command('probe')
-  .description('Probe runtime health and capabilities (HG-01 HARD GATE)')
-  .requiredOption('-r, --runtime <kind>', "Runtime kind: 'openclaw-cli' or 'pi-ai'")
-  .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) 鈥?for pi-ai, falls back to --workspace workflows.yaml')
-  .option('--model <id>', 'Model ID (e.g., anthropic/claude-sonnet-4) 鈥?for pi-ai, falls back to --workspace workflows.yaml')
-  .option('--apiKeyEnv <name>', 'Env var name for API key (e.g., OPENROUTER_API_KEY) 鈥?for pi-ai, falls back to --workspace workflows.yaml')
-  .option('--baseUrl <url>', 'Custom base URL for OpenAI-compatible providers 鈥?for pi-ai, falls back to --workspace workflows.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 鈥?loads pi-ai policy from .state/workflows.yaml')
-  .option('--json', 'Output raw JSON')
-  .action(async (opts) => {
-    await handleRuntimeProbe(opts);
-  });
+registerRuntimeProbeCommand(runtimeCmd);
 
 const flowCmd = runtimeCmd
   .command('flow')

package/src/services/mainline-snapshot-assembler.ts

@@ -20,6 +20,7 @@ import {
   assertMainlineContract,
   EMPTY_CONTEXT_SENTINEL,
   hydratePITaskRecord,
+  resolveAgentRuntimeBinding,
   type MainlineSnapshot,
   type RuntimeReadinessSnapshot,
   type DiagnosisTaskSnapshot,
@@ -140,13 +141,32 @@ function buildDefaultReadiness(workspaceDir: string, warnings: string[]): Runtim
     warnings.push(...configLoadResult.warnings);
   }
 
+  // PRI-402: resolve real runtimeProbeProfile from .pd/config.yaml
+  // so smoke's config_source_alignment + diagnostician_readiness can judge correctly
+  let runtimeProbeProfile: string | null = null;
+  let diagnosticianReady = false;
+  let diagnosticianReadinessReason = 'No readiness snapshot provided; run "pd runtime probe" first.';
+
+  if (configLoadResult.ok) {
+    const bindingResult = resolveAgentRuntimeBinding(configLoadResult.effective, 'diagnostician');
+    if (bindingResult.ok) {
+      runtimeProbeProfile = bindingResult.profileId;
+      // Profile exists and is bound — readiness is at least "configured"
+      // Actual connectivity is unknown without probe, but config alignment is satisfied
+      diagnosticianReady = true;
+      diagnosticianReadinessReason = `Profile '${bindingResult.profileId}' resolved from .pd/config.yaml (connectivity not probed)`;
+    } else {
+      diagnosticianReadinessReason = bindingResult.reason;
+    }
+  }
+
   return {
     configDoctorProfile: defaultProfile,
-    runtimeProbeProfile: null,
+    runtimeProbeProfile,
     configSource: '.pd/config.yaml',
     probeConfigSource: '.pd/config.yaml',
-    diagnosticianReady: false,
-    diagnosticianReadinessReason: 'No readiness snapshot provided; run "pd runtime probe" first.',
+    diagnosticianReady,
+    diagnosticianReadinessReason,
   };
 }
 

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

@@ -16,6 +16,7 @@
 import {
   resolveRuntimeConfigFromPdConfig,
   isRuntimeConfigError,
+  resolveAgentRuntimeBinding,
 } from '@principles/core/runtime-v2';
 import type {
   RuntimeConfigResult,
@@ -34,6 +35,33 @@ export interface ResolvedRuntimeFromPdConfig {
   configLoadResult: PdConfigLoadResult;
   /** Canonical config source label, e.g. ".pd/config.yaml". */
   configSource: string;
+  /**
+   * PRI-402: Resolved runtime profile ID for the diagnostician agent.
+   * e.g. "pi-ai.lmstudio". null when config resolution fails or profile is not found.
+   */
+  runtimeProfileId: string | null;
+  /**
+   * PRI-402: Human-readable runtime profile label for the diagnostician agent.
+   * e.g. "pi-ai: lmstudio/qwen3.6-27b-mtp". null when config resolution fails.
+   * Matches the label format used by `pd config doctor`.
+   */
+  runtimeProfileLabel: string | null;
+}
+
+/**
+ * Build a profile label matching the format used by `pd config doctor`.
+ * Mirrors `buildProfileLabel` in `pd-config-redaction.ts` (core).
+ */
+function buildProfileLabel(profileId: string, profile: { type: string; provider?: string; model?: string; source?: string }): string {
+  if (profile.type === 'openclaw') {
+    const parts: string[] = ['openclaw'];
+    if (profile.provider) parts.push(profile.provider);
+    if (profile.model) parts.push(profile.model);
+    if (profile.source && !profile.provider && !profile.model) parts.push(profile.source);
+    return parts.join(': ');
+  }
+  // pi-ai
+  return `pi-ai: ${profile.provider ?? 'unknown'}/${profile.model ?? 'unknown'}`;
 }
 
 /**
@@ -77,11 +105,22 @@ export function resolveRuntimeFromPdConfig(
       legacyWarnings,
       configLoadResult,
       configSource: '.pd/config.yaml',
+      runtimeProfileId: null,
+      runtimeProfileLabel: null,
     };
   }
 
   const result = resolveRuntimeConfigFromPdConfig(configLoadResult.effective, getEnvVar);
 
+  // PRI-402: Extract profile ID and label for probe output alignment with doctor
+  let runtimeProfileId: string | null = null;
+  let runtimeProfileLabel: string | null = null;
+  const bindingResult = resolveAgentRuntimeBinding(configLoadResult.effective, 'diagnostician');
+  if (bindingResult.ok) {
+    runtimeProfileId = bindingResult.profileId;
+    runtimeProfileLabel = buildProfileLabel(bindingResult.profileId, bindingResult.profile);
+  }
+
   const legacyWarnings = configLoadResult.legacyFilesDetected.length > 0
     ? [
         `Legacy config files detected: ${configLoadResult.legacyFilesDetected.join(', ')}. ` +
@@ -94,6 +133,8 @@ export function resolveRuntimeFromPdConfig(
     legacyWarnings,
     configLoadResult,
     configSource: '.pd/config.yaml',
+    runtimeProfileId,
+    runtimeProfileLabel,
   };
 }