@principles/pd-cli 1.128.2 → 1.130.0

package/src/services/rulehost-readiness.ts

@@ -0,0 +1,326 @@
+/**
+ * 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

@@ -13,7 +13,7 @@
  * - 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
- *   CLI feature flags via `loadEffectiveFeatureFlags`, which is a pd-cli service.
+ *   PD config via `loadPdConfig` + `computeFlagsFromLoadResult`, which are pd-cli services.
  *
  * ERR refs:
  * - ERR-001 (no any): all types explicit
@@ -34,7 +34,7 @@ import {
 } from '@principles/core/runtime-v2';
 import type { PDRuntimeAdapter, PdL2ArtifactReader, RuntimeConfig, RuntimeConfigResult } from '@principles/core/runtime-v2';
 import { loadLedger } from '@principles/core/principle-tree-ledger';
-import { loadEffectiveFeatureFlags } from './feature-flag-loader.js';
+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';
 
@@ -255,7 +255,7 @@ export function resolveRuntimeAdapterFromConfig(opts: ResolveAdapterOptions): PD
     // 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 = loadEffectiveFeatureFlags(opts.workspaceDir);
+      const effectiveFlags = computeFlagsFromLoadResult(loadPdConfig(opts.workspaceDir));
       const l2FlagDef = Object.hasOwn(effectiveFlags.flags, 'l2_dreamer')
         ? effectiveFlags.flags.l2_dreamer
         : undefined;

package/tests/commands/run-rulehost-handler.test.ts

@@ -71,6 +71,11 @@ function parseJsonObject(text: string): Record<string, unknown> {
   return parsed;
 }
 
+/** Type guard: narrows `unknown` to `Record<string, unknown>` without `as`. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
 function captureStdio(fn: () => Promise<void>): Promise<StdIoState> {
   return new Promise((resolve, reject) => {
     const origExitCode = process.exitCode;
@@ -251,3 +256,275 @@ describe('handleRunRuleHost — dry-run mode output shape (with minimal pd-confi
     }
   });
 });
+
+// ── PRI-461: readiness integration tests ──────────────────────────────────
+//
+// Verifies the handler emits the three readiness statuses (ready /
+// text_principle_only / refused) with the correct exit codes and JSON shape.
+// These tests exercise the full path: config → resolveRuleHostReadiness →
+// handler output, ensuring the readiness gate is wired into production code
+// (EP-02) and that refused statuses fail loud with reason + nextAction (EP-03).
+
+function writeFullReadyConfig(workspaceDir: string): void {
+  const configDir = path.join(workspaceDir, '.pd');
+  fs.mkdirSync(configDir, { recursive: true });
+  const cfg = {
+    version: 1,
+    features: {
+      prompt: { category: 'core', enabled: true },
+      code_tool_hook: { category: 'core', enabled: true },
+      defer_archive: { category: 'core', enabled: true },
+      code_rule_capability: { category: 'core', enabled: true },
+    },
+    workspace: { default: workspaceDir },
+    runtimeProfiles: {
+      'pi-ai.default': { type: 'pi-ai', provider: 'anthropic', model: 'claude-sonnet', apiKeyEnv: 'ANTHROPIC_API_KEY' },
+    },
+    internalAgents: {
+      defaultRuntime: 'pi-ai.default',
+      agents: {
+        dreamer: { enabled: true, runtimeProfile: 'pi-ai.default' },
+        philosopher: { enabled: true, runtimeProfile: 'pi-ai.default' },
+        scribe: { enabled: true, runtimeProfile: 'pi-ai.default' },
+        artificer: { enabled: true, runtimeProfile: 'pi-ai.default' },
+        evaluator: { enabled: true, runtimeProfile: 'pi-ai.default' },
+      },
+    },
+  };
+  fs.writeFileSync(path.join(configDir, 'config.yaml'), yaml.dump(cfg), 'utf8');
+}
+
+function writeTextPrincipleOnlyConfig(workspaceDir: string): void {
+  // code_rule_capability explicitly OFF → text_principle_only
+  const configDir = path.join(workspaceDir, '.pd');
+  fs.mkdirSync(configDir, { recursive: true });
+  const cfg = {
+    version: 1,
+    features: {
+      prompt: { category: 'core', enabled: true },
+      code_tool_hook: { category: 'core', enabled: true },
+      defer_archive: { category: 'core', enabled: true },
+      code_rule_capability: { category: 'core', enabled: false },
+    },
+    workspace: { default: workspaceDir },
+    runtimeProfiles: {
+      'pi-ai.default': { type: 'pi-ai', provider: 'anthropic', model: 'claude-sonnet', apiKeyEnv: 'ANTHROPIC_API_KEY' },
+    },
+    internalAgents: {
+      defaultRuntime: 'pi-ai.default',
+      agents: {
+        dreamer: { enabled: true, runtimeProfile: 'pi-ai.default' },
+        philosopher: { enabled: true, runtimeProfile: 'pi-ai.default' },
+        scribe: { enabled: true, runtimeProfile: 'pi-ai.default' },
+        artificer: { enabled: true, runtimeProfile: 'pi-ai.default' },
+        evaluator: { enabled: true, runtimeProfile: 'pi-ai.default' },
+      },
+    },
+  };
+  fs.writeFileSync(path.join(configDir, 'config.yaml'), yaml.dump(cfg), 'utf8');
+}
+
+function writeEvaluatorDisabledConfig(workspaceDir: string): void {
+  const configDir = path.join(workspaceDir, '.pd');
+  fs.mkdirSync(configDir, { recursive: true });
+  const cfg = {
+    version: 1,
+    features: {
+      prompt: { category: 'core', enabled: true },
+      code_tool_hook: { category: 'core', enabled: true },
+      defer_archive: { category: 'core', enabled: true },
+      code_rule_capability: { category: 'core', enabled: true },
+    },
+    workspace: { default: workspaceDir },
+    runtimeProfiles: {
+      'pi-ai.default': { type: 'pi-ai', provider: 'anthropic', model: 'claude-sonnet', apiKeyEnv: 'ANTHROPIC_API_KEY' },
+    },
+    internalAgents: {
+      defaultRuntime: 'pi-ai.default',
+      agents: {
+        dreamer: { enabled: true, runtimeProfile: 'pi-ai.default' },
+        philosopher: { enabled: true, runtimeProfile: 'pi-ai.default' },
+        scribe: { enabled: true, runtimeProfile: 'pi-ai.default' },
+        artificer: { enabled: true, runtimeProfile: 'pi-ai.default' },
+        evaluator: { enabled: false, runtimeProfile: 'pi-ai.default' },
+      },
+    },
+  };
+  fs.writeFileSync(path.join(configDir, 'config.yaml'), yaml.dump(cfg), 'utf8');
+}
+
+function writeRefusedConfig(workspaceDir: string): void {
+  // dreamer disabled → required agent missing → refused
+  const configDir = path.join(workspaceDir, '.pd');
+  fs.mkdirSync(configDir, { recursive: true });
+  const cfg = {
+    version: 1,
+    features: {
+      prompt: { category: 'core', enabled: true },
+      code_tool_hook: { category: 'core', enabled: true },
+      defer_archive: { category: 'core', enabled: true },
+      code_rule_capability: { category: 'core', enabled: true },
+    },
+    workspace: { default: workspaceDir },
+    runtimeProfiles: {
+      'pi-ai.default': { type: 'pi-ai', provider: 'anthropic', model: 'claude-sonnet', apiKeyEnv: 'ANTHROPIC_API_KEY' },
+    },
+    internalAgents: {
+      defaultRuntime: 'pi-ai.default',
+      agents: {
+        dreamer: { enabled: false, runtimeProfile: 'pi-ai.default' },
+        philosopher: { enabled: true, runtimeProfile: 'pi-ai.default' },
+        scribe: { enabled: true, runtimeProfile: 'pi-ai.default' },
+        artificer: { enabled: true, runtimeProfile: 'pi-ai.default' },
+        evaluator: { enabled: true, runtimeProfile: 'pi-ai.default' },
+      },
+    },
+  };
+  fs.writeFileSync(path.join(configDir, 'config.yaml'), yaml.dump(cfg), 'utf8');
+}
+
+describe('handleRunRuleHost — PRI-461 readiness integration', () => {
+  let workspaceDir: string;
+  let savedEnv: NodeJS.ProcessEnv;
+
+  beforeEach(() => {
+    workspaceDir = mkTmpDir();
+    savedEnv = { ...process.env };
+    process.env.ANTHROPIC_API_KEY = 'sk-ant-test-key';
+  });
+
+  afterEach(() => {
+    process.env = savedEnv;
+    try { fs.rmSync(workspaceDir, { recursive: true, force: true }); } catch { /* ignore */ }
+  });
+
+  // ── ready ───────────────────────────────────────────────────────────────
+
+  it('emits readiness=ready in --json dry-run when all agents and code-rule capability are ON', async () => {
+    writeFullReadyConfig(workspaceDir);
+    const { stdout, exitCode } = await captureStdio(() =>
+      handleRunRuleHost({ painId: 'pain-1', dryRun: true, json: true, workspace: workspaceDir }),
+    );
+    const payload = parseJsonObject(stdout.trim());
+    expect(payload.status).toBe('dry_run');
+    expect(payload.readinessStatus).toBe('ready');
+    const readiness = payload.readiness;
+    expect(isRecord(readiness)).toBe(true);
+    if (!isRecord(readiness)) {
+      throw new Error('readiness is not a record');
+    }
+    expect(readiness.status).toBe('ready');
+    expect(exitCode).toBeUndefined();
+  });
+
+  it('emits readiness=ready in plain-text dry-run output', async () => {
+    writeFullReadyConfig(workspaceDir);
+    const { stdout } = await captureStdio(() =>
+      handleRunRuleHost({ painId: 'pain-1', dryRun: true, workspace: workspaceDir }),
+    );
+    expect(stdout).toMatch(/readiness:\s*READY/i);
+  });
+
+  // ── text_principle_only ─────────────────────────────────────────────────
+
+  it('emits readiness=text_principle_only in --json dry-run when code_rule_capability is OFF', async () => {
+    writeTextPrincipleOnlyConfig(workspaceDir);
+    const { stdout, exitCode } = await captureStdio(() =>
+      handleRunRuleHost({ painId: 'pain-1', dryRun: true, json: true, workspace: workspaceDir }),
+    );
+    const payload = parseJsonObject(stdout.trim());
+    expect(payload.status).toBe('dry_run');
+    expect(payload.readinessStatus).toBe('text_principle_only');
+    const readiness = payload.readiness;
+    expect(isRecord(readiness)).toBe(true);
+    if (!isRecord(readiness)) {
+      throw new Error('readiness is not a record');
+    }
+    expect(readiness.status).toBe('text_principle_only');
+    expect(typeof readiness.reason).toBe('string');
+    expect(typeof readiness.nextAction).toBe('string');
+    expect(exitCode).toBeUndefined();
+  });
+
+  it('does not reclassify evaluator-disabled text_principle_only as runtime resolution failure', async () => {
+    writeEvaluatorDisabledConfig(workspaceDir);
+    const { stdout, exitCode } = await captureStdio(() =>
+      handleRunRuleHost({ painId: 'pain-1', dryRun: true, json: true, workspace: workspaceDir }),
+    );
+    const payload = parseJsonObject(stdout.trim());
+    expect(payload.status).toBe('dry_run');
+    expect(payload.readinessStatus).toBe('text_principle_only');
+    const readiness = payload.readiness;
+    expect(isRecord(readiness)).toBe(true);
+    if (!isRecord(readiness)) {
+      throw new Error('readiness is not a record');
+    }
+    expect(readiness.status).toBe('text_principle_only');
+    expect(String(readiness.reason)).toContain('evaluator');
+    expect(String(payload.capabilityStatus)).toContain('evaluator');
+    expect(exitCode).toBeUndefined();
+  });
+
+  it('emits readiness=text_principle_only in plain-text dry-run output', async () => {
+    writeTextPrincipleOnlyConfig(workspaceDir);
+    const { stdout } = await captureStdio(() =>
+      handleRunRuleHost({ painId: 'pain-1', dryRun: true, workspace: workspaceDir }),
+    );
+    expect(stdout).toMatch(/readiness:\s*TEXT_PRINCIPLE_ONLY/i);
+  });
+
+  // ── refused ─────────────────────────────────────────────────────────────
+
+  it('exits with code=1 and emits status=refused in --json when dreamer is disabled', async () => {
+    writeRefusedConfig(workspaceDir);
+    const { stdout, exitCode } = await captureStdio(() =>
+      handleRunRuleHost({ painId: 'pain-1', dryRun: true, json: true, workspace: workspaceDir }),
+    );
+    const payload = parseJsonObject(stdout.trim());
+    expect(payload.status).toBe('refused');
+    expect(typeof payload.reason).toBe('string');
+    expect(typeof payload.nextAction).toBe('string');
+    expect(exitCode).toBe(1);
+  });
+
+  it('exits with code=1 and emits REFUSED in plain-text when dreamer is disabled', async () => {
+    writeRefusedConfig(workspaceDir);
+    const { stderr, exitCode } = await captureStdio(() =>
+      handleRunRuleHost({ painId: 'pain-1', dryRun: true, workspace: workspaceDir }),
+    );
+    expect(stderr).toMatch(/REFUSED/i);
+    expect(stderr).toMatch(/dreamer/i);
+    expect(exitCode).toBe(1);
+  });
+
+  it('refused status includes the full readiness object in --json output', async () => {
+    writeRefusedConfig(workspaceDir);
+    const { stdout } = await captureStdio(() =>
+      handleRunRuleHost({ painId: 'pain-1', dryRun: true, json: true, workspace: workspaceDir }),
+    );
+    const payload = parseJsonObject(stdout.trim());
+    expect(payload.readiness).toBeDefined();
+    const readiness = payload.readiness;
+    expect(isRecord(readiness)).toBe(true);
+    if (!isRecord(readiness)) {
+      throw new Error('readiness is not a record');
+    }
+    expect(readiness.status).toBe('refused');
+    expect(readiness.agentStatuses).toBeDefined();
+  });
+
+  it('refused status does NOT attempt pipeline execution or adapter construction', async () => {
+    // If the handler tried to construct adapters with a disabled dreamer,
+    // resolveRunRuleHostRuntime would throw. The readiness gate must prevent
+    // that by exiting before resolveRunRuleHostRuntime is called.
+    writeRefusedConfig(workspaceDir);
+    const { stdout, exitCode } = await captureStdio(() =>
+      handleRunRuleHost({ painId: 'pain-1', dryRun: true, json: true, workspace: workspaceDir }),
+    );
+    const payload = parseJsonObject(stdout.trim());
+    // Must be 'refused', NOT 'failed' with 'agent_runtime_resolution_failed'
+    expect(payload.status).toBe('refused');
+    expect(payload.reason).not.toMatch(/agent_runtime_resolution_failed/);
+    expect(exitCode).toBe(1);
+  });
+});