@principles/pd-cli 1.152.11 → 1.152.13

package/src/services/rulehost-readiness.ts

@@ -1,326 +0,0 @@
-/**
- * RuleHost Readiness Resolver — PRI-461
- *
- * Checks all preconditions for `run-rulehost` BEFORE constructing adapters,
- * returning one of three user-visible statuses:
- *   - `ready`: all agents enabled with pi-ai profiles and API keys; code-rule capability ON
- *   - `text_principle_only`: dreamer/philosopher/scribe ready, but code-rule capability OFF
- *     (flag disabled, or artificer/evaluator not ready)
- *   - `refused`: dreamer/philosopher/scribe chain broken (disabled, wrong profile, missing API key,
- *     or config malformed)
- *
- * This module NEVER throws. It always returns a structured result with reason + nextAction,
- * so the CLI handler can emit a clear status instead of an opaque adapter-resolution failure.
- *
- * ERR refs:
- *   - EP-02 / ERR-024, ERR-025: wired into the production handler path (runtime-internalization-run-rulehost.ts)
- *   - EP-03: refused/text_principle_only include reason + nextAction
- *   - EP-07: uses the same config source as the pipeline (resolveRuntimeFromPdConfig)
- *   - EP-09: tests cover the default installed config pattern
- */
-
-import {
-  resolveAgentRuntimeBinding,
-  checkAgentRuntimeReadiness,
-  computeFeatureFlagsFromConfig,
-  isFeatureEnabled,
-} from '@principles/core/runtime-v2';
-import type {
-  EffectivePdConfig,
-  RuntimeProfile,
-} from '@principles/core/runtime-v2';
-import { resolveRuntimeFromPdConfig } from './resolve-runtime-from-pd-config.js';
-
-// ── Types ────────────────────────────────────────────────────────────────────
-
-export type RuleHostReadinessStatus = 'ready' | 'text_principle_only' | 'refused';
-
-export interface AgentReadiness {
-  readonly status: 'ready' | 'disabled' | 'not_ready' | 'needs_setup' | 'wrong_profile_type';
-  readonly reason?: string;
-  readonly nextAction?: string;
-  readonly profileId?: string;
-  readonly profileType?: string;
-}
-
-export interface CodeRuleCapabilityReadiness {
-  readonly enabled: boolean;
-  readonly disabledReason?: string;
-}
-
-export interface RuleHostReadinessResult {
-  readonly status: RuleHostReadinessStatus;
-  readonly reason: string;
-  readonly nextAction: string;
-  readonly agentStatuses: {
-    readonly dreamer: AgentReadiness;
-    readonly philosopher: AgentReadiness;
-    readonly scribe: AgentReadiness;
-    readonly artificer: AgentReadiness;
-    readonly evaluator: AgentReadiness;
-  };
-  readonly codeRuleCapability: CodeRuleCapabilityReadiness;
-}
-
-/**
- * The 5 internal agents that RuleHost readiness checks.
- * Narrowed from InternalAgentName so array iteration indexes a known-shape map.
- */
-type RuleHostAgentName = 'dreamer' | 'philosopher' | 'scribe' | 'artificer' | 'evaluator';
-
-/**
- * Mutable builder type for agentStatuses during construction.
- * The readonly RuleHostReadinessResult['agentStatuses'] is assigned from this.
- */
-interface AgentStatusesMap {
-  dreamer: AgentReadiness;
-  philosopher: AgentReadiness;
-  scribe: AgentReadiness;
-  artificer: AgentReadiness;
-  evaluator: AgentReadiness;
-}
-
-// ── Constants ─────────────────────────────────────────────────────────────────
-
-/**
- * Agents required for the text-principle path (dreamer → philosopher → scribe).
- * If any of these is not ready, the pipeline cannot produce even text principles.
- */
-const REQUIRED_AGENTS: readonly RuleHostAgentName[] = ['dreamer', 'philosopher', 'scribe'];
-
-/**
- * Agents required for the code-rule capability (artificer + evaluator).
- * Both must be ready for the adversarial loop to run.
- */
-const CODE_RULE_AGENTS: readonly RuleHostAgentName[] = ['artificer', 'evaluator'];
-
-// ── Implementation ────────────────────────────────────────────────────────────
-
-/**
- * Check a single agent's readiness for the RuleHost pipeline.
- *
- * Checks (in order):
- *   1. Agent enabled (via resolveAgentRuntimeBinding)
- *   2. Profile exists (via resolveAgentRuntimeBinding)
- *   3. Profile type is 'pi-ai' (RuleHost needs PiAiRuntimeAdapter)
- *   4. Profile is ready (via checkAgentRuntimeReadiness — provider/model/apiKeyEnv set, env var exists)
- *
- * Returns a structured AgentReadiness result. Never throws.
- */
-function checkAgentReadiness(
-  effective: EffectivePdConfig,
-  agentName: RuleHostAgentName,
-  getEnvVar: (name: string) => string | undefined,
-): AgentReadiness {
-  const binding = resolveAgentRuntimeBinding(effective, agentName);
-
-  if (!binding.ok) {
-    return {
-      status: binding.readiness === 'disabled' ? 'disabled' : binding.readiness === 'needs_setup' ? 'needs_setup' : 'not_ready',
-      reason: binding.reason,
-      nextAction: binding.nextAction,
-    };
-  }
-
-  const profile: RuntimeProfile = binding.profile;
-  const profileType = profile.type;
-
-  // RuleHost pipeline constructs PiAiRuntimeAdapter instances, so the profile
-  // must be pi-ai. OpenClaw profiles delegate to OpenClaw's own runtime, which
-  // is not available in the RuleHost pipeline context.
-  if (profileType !== 'pi-ai') {
-    return {
-      status: 'wrong_profile_type',
-      reason: `Agent '${agentName}' uses profile '${binding.profileId}' with type '${profileType}', but RuleHost requires pi-ai profile type`,
-      nextAction: `Add a pi-ai runtime profile to .pd/config.yaml and assign it to ${agentName} via internalAgents.agents.${agentName}.runtimeProfile`,
-      profileId: binding.profileId,
-      profileType,
-    };
-  }
-
-  const readiness = checkAgentRuntimeReadiness(profile, getEnvVar);
-  if (readiness.readiness !== 'ready') {
-    return {
-      status: readiness.readiness === 'needs_setup' ? 'needs_setup' : 'not_ready',
-      reason: readiness.reason,
-      nextAction: readiness.nextAction,
-      profileId: binding.profileId,
-      profileType,
-    };
-  }
-
-  return {
-    status: 'ready',
-    profileId: binding.profileId,
-    profileType,
-  };
-}
-
-// ── Helpers (defined before public function to satisfy no-use-before-define) ──
-
-interface ReadinessResultParts {
-  readonly agentStatuses: AgentStatusesMap;
-  readonly codeRuleCapability: CodeRuleCapabilityReadiness;
-}
-
-function emptyAgentStatuses(): AgentStatusesMap {
-  const empty: AgentReadiness = { status: 'not_ready', reason: 'not checked' };
-  return {
-    dreamer: empty,
-    philosopher: empty,
-    scribe: empty,
-    artificer: empty,
-    evaluator: empty,
-  };
-}
-
-function buildRefusedResult(
-  reason: string,
-  nextAction: string,
-  parts: ReadinessResultParts,
-): RuleHostReadinessResult {
-  return {
-    status: 'refused',
-    reason,
-    nextAction,
-    agentStatuses: parts.agentStatuses,
-    codeRuleCapability: parts.codeRuleCapability,
-  };
-}
-
-function buildTextPrincipleOnlyResult(
-  reason: string,
-  nextAction: string,
-  parts: ReadinessResultParts,
-): RuleHostReadinessResult {
-  return {
-    status: 'text_principle_only',
-    reason,
-    nextAction,
-    agentStatuses: parts.agentStatuses,
-    codeRuleCapability: parts.codeRuleCapability,
-  };
-}
-
-function resolveRuleHostReadinessUnchecked(
-  workspaceDir: string,
-  getEnvVar: (name: string) => string | undefined,
-): RuleHostReadinessResult {
-  // ── Step 1: Load config ──
-  const { configLoadResult } = resolveRuntimeFromPdConfig(workspaceDir, { getEnvVar });
-
-  if (!configLoadResult.ok) {
-    const [firstError] = configLoadResult.errors;
-    const reason = `config_malformed: ${firstError?.reason ?? 'unknown config error'}`;
-    const nextAction = firstError?.nextAction ?? 'Fix .pd/config.yaml syntax and retry';
-    return buildRefusedResult(reason, nextAction, {
-      agentStatuses: emptyAgentStatuses(),
-      codeRuleCapability: { enabled: false, disabledReason: 'config_malformed' },
-    });
-  }
-
-  const { effective } = configLoadResult;
-
-  // ── Step 2: Check required agents (dreamer, philosopher, scribe) ──
-  // Start with all 5 keys set to 'not checked'; updated as each agent is checked.
-  const agentStatuses: AgentStatusesMap = emptyAgentStatuses();
-  const requiredFailures: string[] = [];
-
-  for (const agentName of REQUIRED_AGENTS) {
-    const readiness = checkAgentReadiness(effective, agentName, getEnvVar);
-    agentStatuses[agentName] = readiness;
-    if (readiness.status !== 'ready') {
-      requiredFailures.push(`${agentName}: ${readiness.reason ?? readiness.status}`);
-    }
-  }
-
-  if (requiredFailures.length > 0) {
-    const reason = `required_agents_not_ready: ${requiredFailures.join('; ')}`;
-    const nextAction = `Fix the following agent issues in .pd/config.yaml: ${requiredFailures.join('; ')}. RuleHost requires dreamer, philosopher, and scribe agents to be enabled with pi-ai runtime profiles and valid API keys.`;
-    return buildRefusedResult(reason, nextAction, {
-      agentStatuses,
-      codeRuleCapability: { enabled: false, disabledReason: 'required_agents_not_ready' },
-    });
-  }
-
-  // ── Step 3: Check code_rule_capability feature flag ──
-  const featureFlags = computeFeatureFlagsFromConfig(effective);
-  if (!isFeatureEnabled(featureFlags, 'code_rule_capability')) {
-    const reason = 'code_rule_capability feature flag is disabled';
-    const nextAction = "Enable code_rule_capability in .pd/config.yaml features.code_rule_capability.enabled to run the full adversarial pipeline. Text-principle-only mode is available.";
-    // Still check artificer/evaluator for reporting, but they don't affect the status
-    for (const agentName of CODE_RULE_AGENTS) {
-      agentStatuses[agentName] = checkAgentReadiness(effective, agentName, getEnvVar);
-    }
-    return buildTextPrincipleOnlyResult(reason, nextAction, {
-      agentStatuses,
-      codeRuleCapability: { enabled: false, disabledReason: reason },
-    });
-  }
-
-  // ── Step 4: Check code-rule agents (artificer, evaluator) ──
-  const codeRuleFailures: string[] = [];
-
-  for (const agentName of CODE_RULE_AGENTS) {
-    const readiness = checkAgentReadiness(effective, agentName, getEnvVar);
-    agentStatuses[agentName] = readiness;
-    if (readiness.status !== 'ready') {
-      codeRuleFailures.push(`${agentName}: ${readiness.reason ?? readiness.status}`);
-    }
-  }
-
-  if (codeRuleFailures.length > 0) {
-    const reason = `code_rule_agents_not_ready: ${codeRuleFailures.join('; ')}`;
-    const nextAction = `Fix the following agent issues to enable code-rule capability: ${codeRuleFailures.join('; ')}. Text-principle-only mode is available with the current configuration.`;
-    return buildTextPrincipleOnlyResult(reason, nextAction, {
-      agentStatuses,
-      codeRuleCapability: { enabled: false, disabledReason: reason },
-    });
-  }
-
-  // ── Step 5: All checks pass → ready ──
-  return {
-    status: 'ready',
-    reason: 'All agents ready with pi-ai profiles and valid API keys. Code-rule capability is ON.',
-    nextAction: 'Pass --confirm to run the full pipeline.',
-    agentStatuses,
-    codeRuleCapability: { enabled: true },
-  };
-}
-
-/**
- * Resolve RuleHost readiness from the workspace's .pd/config.yaml.
- *
- * This is the production entry point called by the `run-rulehost` handler
- * BEFORE constructing any adapters. It returns a structured result so the
- * handler can emit a clear status instead of an opaque adapter-resolution failure.
- *
- * This function NEVER throws. Any unexpected exception from config loading,
- * feature-flag computation, agent checks, or getEnvVar is caught and converted
- * to a `refused` result with reason + nextAction (Runtime Contract #9).
- *
- * @param workspaceDir - The workspace directory containing .pd/config.yaml
- * @param getEnvVar - Env var accessor, defaults to process.env. Injected for testability.
- * @returns Structured readiness result. Never throws.
- */
-export function resolveRuleHostReadiness(
-  workspaceDir: string,
-  getEnvVar: (name: string) => string | undefined = (name) => process.env[name],
-): RuleHostReadinessResult {
-  try {
-    return resolveRuleHostReadinessUnchecked(workspaceDir, getEnvVar);
-  } catch (error: unknown) {
-    const message =
-      error instanceof Error && error.message.length > 0
-        ? error.message
-        : 'unknown readiness resolution error';
-    return buildRefusedResult(
-      `readiness_resolution_failed: ${message}`,
-      'Fix the readiness resolution error and retry. Run `pd config doctor` for diagnostics.',
-      {
-        agentStatuses: emptyAgentStatuses(),
-        codeRuleCapability: { enabled: false, disabledReason: 'readiness_resolution_failed' },
-      },
-    );
-  }
-}

package/src/services/runtime-adapter-resolver.ts

@@ -1,364 +0,0 @@
-/**
- * PRI-431 Step 3: Shared runtime-adapter resolver.
- *
- * Extracted from duplicated `resolveRuntimeAdapter` in:
- *   - packages/pd-cli/src/commands/runtime-internalization-run-once.ts (L222-551)
- *   - packages/pd-cli/src/commands/diagnose.ts (L186-334, inline)
- *
- * Design decisions:
- * - Test-double payloads stay call-site-specific via `testDoublePayloadBuilder` callback.
- *   The 7 internalization runner payloads (philosopher/scribe/artificer/...) are unique
- *   to run-once.ts; the diagnostician payload is unique to diagnose.ts. Unifying them
- *   would couple unrelated domains.
- * - CLI-gate concerns (process.exit, telemetry, help text) stay at call sites.
- *   This resolver throws structured `ConfigResolutionError` that handlers translate.
- * - Lives in pd-cli/services (NOT core) because it constructs adapters and reads
- *   PD config via `loadPdConfig` + `computeFlagsFromLoadResult`, which are pd-cli services.
- *
- * ERR refs:
- * - ERR-001 (no any): all types explicit
- * - ERR-005 (no as bypass): no type casts
- * - ERR-009 (fail-loud): ConfigResolutionError thrown with structured fields
- * - ERR-013 (Object.hasOwn): feature flag check uses Object.hasOwn
- * - ERR-002 (graceful degradation with reason): structured error includes reason + nextAction
- */
-
-import {
-  TestDoubleRuntimeAdapter,
-  PiAiRuntimeAdapter,
-  OpenClawCliRuntimeAdapter,
-  L2AgentLoopAdapter,
-  buildL2PrincipleReaderFromLedger,
-  isRuntimeConfigError,
-  validateRuntimeConfig,
-} from '@principles/core/runtime-v2';
-import type { PDRuntimeAdapter, PdL2ArtifactReader, RuntimeConfig, RuntimeConfigResult, InternalAgentName } from '@principles/core/runtime-v2';
-import { loadLedger } from '@principles/core/principle-tree-ledger';
-import { loadPdConfig, computeFlagsFromLoadResult } from './pd-config-loader.js';
-import { resolveRuntimeFromPdConfig } from './resolve-runtime-from-pd-config.js';
-import type { ResolvedRuntimeFromPdConfig } from './resolve-runtime-from-pd-config.js';
-
-// ── Error class ────────────────────────────────────────────────────────────
-
-export type ConfigResolutionErrorKind =
-  | 'missing-fields'
-  | 'invalid-config'
-  | 'unsupported-runtime'
-  | 'test-double-refused';
-
-export interface ConfigResolutionErrorDetails {
-  /** Required fields that are missing (for 'missing-fields' kind). */
-  missing?: string[];
-  /** Structured next action for the operator (CLI Operator Gate rule #6). */
-  nextAction?: string;
-}
-
-export class ConfigResolutionError extends Error {
-  readonly kind: ConfigResolutionErrorKind;
-  readonly missing?: string[];
-  readonly nextAction?: string;
-
-  constructor(
-    message: string,
-    kind: ConfigResolutionErrorKind,
-    details?: ConfigResolutionErrorDetails,
-  ) {
-    super(message);
-    this.name = 'ConfigResolutionError';
-    this.kind = kind;
-    this.missing = details?.missing;
-    this.nextAction = details?.nextAction;
-  }
-}
-
-// ── Options interface ──────────────────────────────────────────────────────
-
-export interface ResolveAdapterOptions {
-  /** Runtime kind: 'test-double' | 'pi-ai' | 'openclaw-cli' | 'config' */
-  runtimeKind: string;
-  /** Workspace directory (for config resolution + feature flags) */
-  workspaceDir: string;
-  /** Runner kind (for L2 dreamer routing). Optional. */
-  runnerKind?: string;
-  /**
-   * PRI-719: internal agent whose runtimeProfile binding resolves
-   * (default 'diagnostician'). run-once passes the selected runner's agent
-   * so each stage executes on its own declared profile.
-   */
-  agentName?: InternalAgentName;
-  /**
-   * PRI-719 review: resolve the binding even when the agent is disabled —
-   * peer execution scope is the internalization_full_chain flag (auto-
-   * consumer AND explicit run-once), not agents[kind].enabled. Omitted by
-   * non-peer callers (probe/diagnose) which keep honoring `enabled`.
-   */
-  ignoreAgentEnabled?: boolean;
-  /** CLI timeout override. Takes precedence over config timeoutMs. */
-  timeoutMs?: number;
-  /**
-   * Whether test-double runtime is allowed. Default: false.
-   * When false, 'test-double' runtimeKind throws ConfigResolutionError.
-   */
-  allowTestDouble?: boolean;
-  /**
-   * Call-site-specific test-double payload builder.
-   * Required when runtimeKind === 'test-double' and allowTestDouble === true.
-   * Receives the full opts object so the builder can access taskId, runnerKind, etc.
-   */
-  testDoublePayloadBuilder?: (opts: ResolveAdapterOptions) => PDRuntimeAdapter;
-  /**
-   * CLI overrides for pi-ai runtime (from --provider, --model, etc. flags).
-   * When provided, these take precedence over config values.
-   */
-  piAiOverrides?: {
-    provider?: string;
-    model?: string;
-    apiKeyEnv?: string;
-    baseUrl?: string;
-    maxRetries?: number;
-    maxTokens?: number;
-  };
-  /**
-   * CLI override for openclaw mode (from --openclaw-local / --openclaw-gateway flags).
-   * When provided, takes precedence over config openclawMode.
-   */
-  openclawMode?: 'local' | 'gateway';
-  /** PRI-419: L2 artifact reader (only used when l2_dreamer is on). */
-  l2ArtifactReader?: PdL2ArtifactReader;
-  /** PRI-419: workspace stateDir for L2 principle reader (only used when l2_dreamer is on). */
-  l2StateDir?: string;
-  /** PRI-431 Step 1d: CLI agentId override for openclaw-cli (from --agent flag). Default: 'main'. */
-  agentId?: string;
-  /**
-   * PRI-431 Step 1d: Whether config resolution errors are tolerated (proceed with CLI overrides alone).
-   * When true, pi-ai branch skips validateRuntimeConfig and uses manual missing-field check.
-   * Default: false (config errors throw ConfigResolutionError).
-   */
-  configOptional?: boolean;
-  /**
-   * PRI-431 Step 1d: Whether to validate that process.env[apiKeyEnv] is set before
-   * constructing PiAiRuntimeAdapter. Default: false (env var check stays at call site for backward compat).
-   */
-  validateApiKeyEnv?: boolean;
-  /**
-   * PRI-431 Step 1d: Callback invoked with the full resolved config object (including legacyWarnings)
-   * after successful config resolution. Useful for telemetry, legacyWarnings printing, etc.
-   * NOT called for test-double branch (no config resolution).
-   * Called even when config returns error IF configOptional is true.
-   */
-  onConfigResolved?: (resolved: ResolvedRuntimeFromPdConfig) => void;
-}
-
-// ── Resolver function ──────────────────────────────────────────────────────
-
-export function resolveRuntimeAdapterFromConfig(opts: ResolveAdapterOptions): PDRuntimeAdapter {
-  // ── test-double branch ──────────────────────────────────────────────────
-  if (opts.runtimeKind === 'test-double') {
-    if (!opts.allowTestDouble) {
-      throw new ConfigResolutionError(
-        'runtimeKind "test-double" requires allowTestDouble=true.',
-        'test-double-refused',
-        { nextAction: 'Pass --allow-test-double or use a production runtime kind.' },
-      );
-    }
-    if (!opts.testDoublePayloadBuilder) {
-      throw new ConfigResolutionError(
-        'runtimeKind "test-double" requires testDoublePayloadBuilder callback.',
-        'missing-fields',
-        {
-          missing: ['testDoublePayloadBuilder'],
-          nextAction:
-            'Provide a testDoublePayloadBuilder function that constructs the test-double adapter.',
-        },
-      );
-    }
-    return opts.testDoublePayloadBuilder(opts);
-  }
-
-  // ── Resolve config from .pd/config.yaml (for pi-ai, openclaw-cli, config) ──
-  const resolved = resolveRuntimeFromPdConfig(opts.workspaceDir, {
-    agentName: opts.agentName,
-    ignoreAgentEnabled: opts.ignoreAgentEnabled,
-  });
-  const configResult: RuntimeConfigResult = resolved.result;
-
-  // PRI-431 Step 1d: invoke onConfigResolved callback (for telemetry, legacyWarnings, etc.)
-  opts.onConfigResolved?.(resolved);
-
-  if (isRuntimeConfigError(configResult)) {
-    if (!opts.configOptional) {
-      throw new ConfigResolutionError(
-        `Config resolution from .pd/config.yaml failed: ${configResult.reason}. ${configResult.message}`,
-        'invalid-config',
-        { nextAction: configResult.nextAction },
-      );
-    }
-    // configOptional=true: proceed with CLI overrides alone (pi-ai branch handles missing fields)
-  }
-
-  // ── pi-ai branch ────────────────────────────────────────────────────────
-  // When runtimeKind === 'config', configResult must be a valid RuntimeConfig
-  // (if it were an error and !configOptional, we threw above; if configOptional,
-  // the caller passes an explicit runtimeKind, never 'config'). The type guard
-  // also narrows for TypeScript.
-  const isPiAi =
-    opts.runtimeKind === 'pi-ai' ||
-    (opts.runtimeKind === 'config' &&
-      !isRuntimeConfigError(configResult) &&
-      configResult.runtimeKind === 'pi-ai');
-  if (isPiAi) {
-    // PRI-431 Step 1d + PR review fix: validateRuntimeConfig is only called when
-    // config is valid AND configOptional is false. When configOptional=true (diagnose.ts),
-    // skip validateRuntimeConfig to match the original diagnose.ts behavior (which never
-    // called it — only did a manual missing-field check on merged values). This avoids
-    // a behavior change where validateRuntimeConfig would reject configs missing baseUrl
-    // for non-built-in providers, even when the user passes --baseUrl on the CLI.
-    if (!opts.configOptional && !isRuntimeConfigError(configResult)) {
-      try {
-        validateRuntimeConfig(configResult);
-      } catch (err) {
-        throw new ConfigResolutionError(
-          err instanceof Error ? err.message : String(err),
-          'invalid-config',
-        );
-      }
-    }
-
-    // Merge CLI overrides with config values (overrides take precedence)
-    // When configOptional and config failed, configResult fields are unavailable — use empty object
-    const configFields: Partial<RuntimeConfig> = isRuntimeConfigError(configResult) ? {} : configResult;
-    const provider = opts.piAiOverrides?.provider ?? configFields.provider;
-    const model = opts.piAiOverrides?.model ?? configFields.model;
-    const apiKeyEnv = opts.piAiOverrides?.apiKeyEnv ?? configFields.apiKeyEnv;
-    const baseUrl = opts.piAiOverrides?.baseUrl ?? configFields.baseUrl;
-    const maxRetries = opts.piAiOverrides?.maxRetries ?? configFields.maxRetries;
-    const maxTokens = opts.piAiOverrides?.maxTokens ?? configFields.maxTokens;
-    const adapterTimeoutMs = opts.timeoutMs ?? configFields.timeoutMs;
-
-    // PRI-431 Step 1d + PR review fix: manual missing-field check on MERGED values
-    // when configOptional=true. The original diagnose.ts always did this check on merged
-    // values (not just when config failed), so we replicate that here. This covers both
-    // the "config failed" case and the "config valid but missing fields not in config" case.
-    if (opts.configOptional) {
-      const missing: string[] = [];
-      if (!provider) missing.push('provider');
-      if (!model) missing.push('model');
-      if (!apiKeyEnv) missing.push('apiKeyEnv');
-      if (missing.length > 0) {
-        throw new ConfigResolutionError(
-          `Missing required pi-ai config: ${missing.join(', ')}.`,
-          'missing-fields',
-          {
-            missing,
-            nextAction:
-              'Pass --provider, --model, --apiKeyEnv flags or configure .pd/config.yaml runtime profile.',
-          },
-        );
-      }
-    }
-
-    // PRI-431 Step 1d: validate API key env var when requested
-    if (opts.validateApiKeyEnv && apiKeyEnv && !process.env[apiKeyEnv]) {
-      throw new ConfigResolutionError(
-        `Environment variable '${apiKeyEnv}' is not set.`,
-        'invalid-config',
-        {
-          nextAction:
-            'Set the env var (e.g., export OPENAI_API_KEY=...) or choose a different apiKeyEnv.',
-        },
-      );
-    }
-
-    // PRI-419: L2 dreamer sub-branch — when l2_dreamer flag is on AND this is the
-    // dreamer runner, route through the L2 multi-turn agent loop adapter.
-    // Other runners (philosopher/scribe/...) stay on L1.
-    if (opts.runnerKind === 'dreamer' && opts.l2ArtifactReader && opts.l2StateDir) {
-      const effectiveFlags = computeFlagsFromLoadResult(loadPdConfig(opts.workspaceDir));
-      const l2FlagDef = Object.hasOwn(effectiveFlags.flags, 'l2_dreamer')
-        ? effectiveFlags.flags.l2_dreamer
-        : undefined;
-      const l2Flag = l2FlagDef ? l2FlagDef.enabled : false;
-      if (l2Flag) {
-        return new L2AgentLoopAdapter(
-          {
-            provider: String(provider),
-            model: String(model),
-            apiKeyEnv: String(apiKeyEnv),
-            baseUrl,
-            workspace: opts.workspaceDir,
-            totalBudgetMs: adapterTimeoutMs,
-            // PRI-633: profile systemPrompt rides as the append layer.
-            ...(configFields.systemPrompt ? { systemPrompt: configFields.systemPrompt } : {}),
-          },
-          {
-            artifactReader: opts.l2ArtifactReader,
-            principleReader: buildL2PrincipleReaderFromLedger(loadLedger(opts.l2StateDir)),
-          },
-        );
-      }
-    }
-
-    return new PiAiRuntimeAdapter({
-      provider: String(provider),
-      model: String(model),
-      apiKeyEnv: String(apiKeyEnv),
-      maxRetries,
-      maxTokens,
-      timeoutMs: adapterTimeoutMs,
-      baseUrl,
-      workspace: opts.workspaceDir,
-      // PRI-758: profile reasoning level rides to pi-ai (always-thinking zai models).
-      ...(configFields.reasoning !== undefined ? { reasoning: configFields.reasoning } : {}),
-      ...(configFields.systemPrompt ? { systemPrompt: configFields.systemPrompt } : {}),
-    });
-  }
-
-  // ── openclaw-cli branch ─────────────────────────────────────────────────
-  const isOpenClawCli =
-    opts.runtimeKind === 'openclaw-cli' ||
-    (opts.runtimeKind === 'config' &&
-      !isRuntimeConfigError(configResult) &&
-      configResult.runtimeKind === 'openclaw-cli');
-  if (isOpenClawCli) {
-    // PRI-431 Step 1d: handle configOptional — when config failed, configFields is empty
-    const openclawConfigFields: Partial<RuntimeConfig> = isRuntimeConfigError(configResult)
-      ? {}
-      : configResult;
-    // CLI override takes precedence over config
-    const openclawMode = opts.openclawMode ?? openclawConfigFields.openclawMode;
-    if (!openclawMode) {
-      throw new ConfigResolutionError(
-        "runtimeKind 'openclaw-cli' requires openclawMode.",
-        'missing-fields',
-        {
-          missing: ['openclawMode'],
-          nextAction:
-            'Add openclawMode: local|gateway to your .pd/config.yaml runtime profile or use --openclaw-local/--openclaw-gateway flags.',
-        },
-      );
-    }
-    // PRI-431 Step 1d: only pass agentId when explicitly provided (backward compat with run-once.ts)
-    const openclawAdapterOpts: {
-      runtimeMode: 'local' | 'gateway';
-      workspaceDir: string;
-      agentId?: string;
-    } = {
-      runtimeMode: openclawMode,
-      workspaceDir: opts.workspaceDir,
-    };
-    if (opts.agentId !== undefined) {
-      openclawAdapterOpts.agentId = opts.agentId;
-    }
-    return new OpenClawCliRuntimeAdapter(openclawAdapterOpts);
-  }
-
-  // ── Unsupported runtime ────────────────────────────────────────────────
-  throw new Error(
-    `Unsupported runtime kind: ${opts.runtimeKind}. Supported: test-double, pi-ai, openclaw-cli, config`,
-  );
-}
-
-// ── Re-exports for call-site convenience ───────────────────────────────────
-// These allow call sites to import everything from one module.
-export type { RuntimeConfig, RuntimeConfigResult };
-export { TestDoubleRuntimeAdapter, isRuntimeConfigError, validateRuntimeConfig };