@principles/pd-cli 1.142.3 → 1.142.4

package/dist/services/version-report.js

@@ -0,0 +1,152 @@
+/**
+ * Canonical version report builder (SPEC §12).
+ *
+ * `pd --version` prints one stable short text line; `pd version --json`
+ * exposes the full canonical report: productVersion, releaseId, components,
+ * bootstrapVersion, channel, source, generation, health, and the last
+ * transaction. The canonical product identity comes from the installation
+ * state under ~/.pd — never from a checkout's package.json.
+ *
+ * The record shapes here mirror the canonical contracts owned by
+ * create-principles-disciple/src/update/ (the deep ReleaseManager module);
+ * this reader is deliberately thin: it READS installation state and never
+ * performs update logic.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+export class VersionReportError extends Error {
+    reason;
+    nextAction;
+    constructor(reason, message, nextAction) {
+        super(message);
+        this.name = 'VersionReportError';
+        this.reason = reason;
+        this.nextAction = nextAction;
+    }
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function readJsonIfPresent(filePath) {
+    if (!fs.existsSync(filePath))
+        return null;
+    let value;
+    try {
+        value = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    }
+    catch (error) {
+        throw new VersionReportError('state_corrupt', `Installation state file is not valid JSON: ${filePath} (${error instanceof Error ? error.message : String(error)})`, 'Run the official installer recovery, or re-run the official installer to repair the installation record.');
+    }
+    if (!isPlainObject(value)) {
+        throw new VersionReportError('state_corrupt', `Installation state file is not a JSON object: ${filePath}`, 'Run the official installer recovery, or re-run the official installer to repair the installation record.');
+    }
+    return value;
+}
+/** `pd --version` short stable text contract. */
+export function formatShortVersion(report) {
+    return `Principles Disciple ${report.productVersion} (${report.releaseId.slice(0, 12)})`;
+}
+function buildLegacyOverlayReport(overlayDir, bootstrap) {
+    // The current official installer copies the plugin package directly into
+    // the OpenClaw extension root. Older overlay bundles kept it under plugin/;
+    // accept that layout only when the canonical root manifest is absent.
+    const rootManifest = readJsonIfPresent(path.join(overlayDir, 'package.json'));
+    const pluginManifest = rootManifest ?? readJsonIfPresent(path.join(overlayDir, 'plugin', 'package.json'));
+    const version = pluginManifest?.version;
+    if (typeof version !== 'string' || version.length === 0) {
+        throw new VersionReportError('legacy_overlay_manifest_invalid', `The legacy overlay at ${overlayDir} has no readable plugin version.`, 'Re-install PD with the official installer to migrate this installation into the supported layout.');
+    }
+    const bootstrapVersion = bootstrap?.bootstrapVersion;
+    return {
+        productVersion: version,
+        releaseId: '0'.repeat(64),
+        components: { plugin: version },
+        bootstrapVersion: typeof bootstrapVersion === 'string' ? bootstrapVersion : 'unknown',
+        channel: 'stable',
+        source: 'official-legacy-overlay',
+        generation: 0,
+        health: 'degraded',
+        lastTransaction: null,
+    };
+}
+function readLastTransaction(historyPath) {
+    if (!fs.existsSync(historyPath))
+        return null;
+    const lines = fs.readFileSync(historyPath, 'utf8').split('\n').filter((line) => line.trim().length > 0);
+    const lastLine = lines[lines.length - 1];
+    if (lastLine === undefined)
+        return null;
+    let value;
+    try {
+        value = JSON.parse(lastLine);
+    }
+    catch (error) {
+        throw new VersionReportError('state_corrupt', `The last transaction record is not valid JSON: ${historyPath} (${error instanceof Error ? error.message : String(error)})`, 'Run the official installer recovery to reconcile the transaction journal before trusting the installed version.');
+    }
+    if (!isPlainObject(value))
+        return null;
+    const { transactionId, kind, outcome } = value;
+    if (typeof transactionId !== 'string' || typeof kind !== 'string' || typeof outcome !== 'string') {
+        return null;
+    }
+    return { id: transactionId, kind, outcome };
+}
+/**
+ * Builds the canonical version report from the installation state. Throws
+ * VersionReportError with an installer next-action when no installation
+ * exists at all.
+ */
+export function buildVersionReport(homeDir = os.homedir()) {
+    const pdHome = path.join(homeDir, '.pd');
+    const active = readJsonIfPresent(path.join(pdHome, 'active.json'));
+    const bootstrap = readJsonIfPresent(path.join(pdHome, 'bootstrap', 'bootstrap.json'));
+    const installConfig = readJsonIfPresent(path.join(pdHome, 'install.json'));
+    const overlayDir = path.join(homeDir, '.openclaw', 'extensions', 'principles-disciple');
+    if (active === null && fs.existsSync(overlayDir)) {
+        return buildLegacyOverlayReport(overlayDir, bootstrap);
+    }
+    if (active === null && !fs.existsSync(pdHome)) {
+        throw new VersionReportError('not_installed', 'No PD installation was found under ~/.pd or the legacy overlay location.', 'Install PD with the official installer (npx create-principles-disciple), then run pd version again.');
+    }
+    if (active === null) {
+        throw new VersionReportError('active_record_missing', 'The ~/.pd installation exists but has no active release record.', 'Run the official installer to complete the installation, or re-run it to repair the record.');
+    }
+    const { generation, releaseId, productVersion } = active;
+    if (typeof generation !== 'number' || !Number.isSafeInteger(generation) || generation < 1
+        || typeof releaseId !== 'string' || releaseId.length === 0
+        || typeof productVersion !== 'string' || productVersion.length === 0) {
+        throw new VersionReportError('active_record_corrupt', 'The active release record under ~/.pd is malformed.', 'Run the official installer recovery, or re-run the official installer to repair the installation record.');
+    }
+    const releaseDir = path.join(pdHome, 'releases', releaseId);
+    const releaseManifest = readJsonIfPresent(path.join(releaseDir, 'metadata.json'));
+    const releaseMetadataMatchesActive = releaseManifest !== null
+        && releaseManifest.productVersion === productVersion
+        && releaseManifest.releaseId === releaseId
+        && releaseManifest.metadataDigest === active.releaseMetadataDigest;
+    const health = releaseManifest === null
+        ? 'degraded'
+        : releaseMetadataMatchesActive ? 'healthy' : 'corrupt';
+    const components = {};
+    for (const component of ['plugin', 'console', 'core', 'pd-cli', 'host-runtime', 'install-layout']) {
+        const manifest = readJsonIfPresent(path.join(releaseDir, component, 'package.json'));
+        const version = manifest?.version;
+        if (typeof version === 'string') {
+            components[component] = version;
+        }
+    }
+    const bootstrapVersion = bootstrap?.bootstrapVersion;
+    const channelValue = installConfig?.channel;
+    return {
+        productVersion,
+        releaseId,
+        components,
+        bootstrapVersion: typeof bootstrapVersion === 'string' ? bootstrapVersion : 'unknown',
+        channel: channelValue === 'candidate' ? 'candidate' : 'stable',
+        source: 'official-installer',
+        generation,
+        health,
+        lastTransaction: readLastTransaction(path.join(pdHome, 'logs', 'history.jsonl')),
+    };
+}
+//# sourceMappingURL=version-report.js.map

package/dist/services/version-report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-report.js","sourceRoot":"","sources":["../../src/services/version-report.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principles/pd-cli",
-  "version": "1.142.3",
+  "version": "1.142.4",
   "description": "PD CLI — Pain recording, sample management, and governance tasks for Principles Disciple",
   "type": "module",
   "bin": {
@@ -16,6 +16,7 @@
     "@principles/core": "^1.74.1",
     "@principles/codex-adapter": "^0.1.0",
     "@principles/host-runtime": "^0.1.0",
+    "@principles/install-layout": "0.1.0",
     "principles-disciple": "^1.74.1",
     "better-sqlite3": "^13.0.3",
     "commander": "^12.0.0",

package/src/commands/__tests__/telemetry-flag-wiring.test.ts

@@ -0,0 +1,84 @@
+/**
+ * pd telemetry — parser-level flag wiring tests (PRI-597, CLI Operator Gate
+ * rule 7 / EP-04).
+ *
+ * Exercises the real Commander tree via registerTelemetryCommand; actions are
+ * captured so no handler logic runs.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { Command } from 'commander';
+import { registerTelemetryCommand } from '../telemetry.js';
+
+function freshProgram(): Command {
+  const program = new Command();
+  program.name('pd').exitOverride();
+  return program;
+}
+
+function requireCmd(cmd: Command | undefined, name: string): Command {
+  if (cmd === undefined) {
+    throw new Error(`Command '${name}' not found in tree`);
+  }
+  return cmd;
+}
+
+function telemetrySub(name: string): Command {
+  const program = freshProgram();
+  registerTelemetryCommand(program);
+  const telemetry = requireCmd(program.commands.find((c) => c.name() === 'telemetry'), 'telemetry');
+  return requireCmd(telemetry.commands.find((c) => c.name() === name), `telemetry ${name}`);
+}
+
+describe('pd telemetry — command registration', () => {
+  it('registers the telemetry group with all five subcommands', () => {
+    const program = freshProgram();
+    registerTelemetryCommand(program);
+    const telemetry = requireCmd(program.commands.find((c) => c.name() === 'telemetry'), 'telemetry');
+    const subNames = telemetry.commands.map((c) => c.name()).sort();
+    expect(subNames).toEqual(['disable', 'enable', 'preview', 'reset', 'status']);
+  });
+
+  it('status registers --workspace (-w) and --json', () => {
+    const status = telemetrySub('status');
+    expect(status.options.find((o) => o.long === '--workspace')?.short).toBe('-w');
+    expect(status.options.find((o) => o.long === '--json')).toBeDefined();
+  });
+
+  it('enable/disable/reset register the dry-run/confirm pair (cli-4) plus --workspace and --json', () => {
+    for (const name of ['enable', 'disable', 'reset']) {
+      const cmd = telemetrySub(name);
+      expect(cmd.options.find((o) => o.long === '--dry-run'), name).toBeDefined();
+      expect(cmd.options.find((o) => o.long === '--confirm'), name).toBeDefined();
+      expect(cmd.options.find((o) => o.long === '--workspace'), name).toBeDefined();
+      expect(cmd.options.find((o) => o.long === '--json'), name).toBeDefined();
+    }
+  });
+
+  it('preview registers --workspace (-w) and --json', () => {
+    const preview = telemetrySub('preview');
+    expect(preview.options.find((o) => o.long === '--workspace')?.short).toBe('-w');
+    expect(preview.options.find((o) => o.long === '--json')).toBeDefined();
+  });
+
+  it('parser dispatches telemetry enable with --confirm as opts.confirm === true', async () => {
+    const program = freshProgram();
+    registerTelemetryCommand(program);
+    const holder: { opts: Record<string, unknown> | null } = { opts: null };
+    const telemetry = requireCmd(program.commands.find((c) => c.name() === 'telemetry'), 'telemetry');
+    const enable = requireCmd(telemetry.commands.find((c) => c.name() === 'enable'), 'enable');
+    enable.action((...args: unknown[]) => {
+      for (let i = args.length - 1; i >= 0; i--) {
+        const arg = args[i];
+        if (arg !== null && typeof arg === 'object' && !(arg instanceof Command)) {
+          holder.opts = arg as Record<string, unknown>;
+          break;
+        }
+      }
+    });
+    await program.parseAsync(['node', 'pd', 'telemetry', 'enable', '--confirm', '--json']);
+    expect(holder.opts).not.toBeNull();
+    expect(holder.opts?.confirm).toBe(true);
+    expect(holder.opts?.json).toBe(true);
+  });
+});

package/src/commands/__tests__/version.test.ts

@@ -0,0 +1,141 @@
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { buildVersionReport, formatShortVersion, VersionReportError } from '../../services/version-report.js';
+
+const temporaryDirectories: string[] = [];
+
+function tempHome(): string {
+  const root = fs.mkdtempSync(path.join(fs.realpathSync(os.tmpdir()), 'pd-version-'));
+  temporaryDirectories.push(root);
+  return root;
+}
+
+function writeDualSlotHome(home: string): void {
+  const pdHome = path.join(home, '.pd');
+  fs.mkdirSync(path.join(pdHome, 'releases', 'b'.repeat(64), 'plugin'), { recursive: true });
+  fs.mkdirSync(path.join(pdHome, 'bootstrap'), { recursive: true });
+  fs.mkdirSync(path.join(pdHome, 'logs'), { recursive: true });
+  fs.writeFileSync(path.join(pdHome, 'active.json'), JSON.stringify({
+    schemaVersion: 1,
+    generation: 4,
+    releaseId: 'b'.repeat(64),
+    releaseMetadataDigest: '2'.repeat(64),
+    previousReleaseId: 'a'.repeat(64),
+    transactionId: 'txn-9',
+    productVersion: '1.223.0',
+  }));
+  fs.writeFileSync(path.join(pdHome, 'bootstrap', 'bootstrap.json'), JSON.stringify({
+    bootstrapVersion: '1.1.0',
+    installedAt: '2026-08-25T00:00:00Z',
+  }));
+  fs.writeFileSync(path.join(pdHome, 'install.json'), JSON.stringify({ channel: 'candidate', autoCheck: true }));
+  fs.writeFileSync(path.join(pdHome, 'releases', 'b'.repeat(64), 'metadata.json'), JSON.stringify({
+    productVersion: '1.223.0',
+    releaseId: 'b'.repeat(64),
+    metadataDigest: '2'.repeat(64),
+  }));
+  fs.writeFileSync(path.join(pdHome, 'releases', 'b'.repeat(64), 'plugin', 'package.json'), JSON.stringify({ version: '1.76.1' }));
+  fs.writeFileSync(path.join(pdHome, 'logs', 'history.jsonl'), [
+    JSON.stringify({ at: '2026-08-24T00:00:00Z', kind: 'update', outcome: 'succeeded', transactionId: 'txn-8' }),
+    JSON.stringify({ at: '2026-08-25T00:00:00Z', kind: 'recovery', outcome: 'recovered', transactionId: 'txn-9' }),
+  ].join('\n') + '\n');
+}
+
+afterEach(() => {
+  while (temporaryDirectories.length > 0) {
+    const directory = temporaryDirectories.pop();
+    if (directory) fs.rmSync(directory, { recursive: true, force: true, maxRetries: 10, retryDelay: 200 });
+  }
+});
+
+describe('canonical version report (SPEC 12 / 18-1, 18-10)', () => {
+  it('reports the canonical product identity from ~/.pd, not package.json', () => {
+    const home = tempHome();
+    writeDualSlotHome(home);
+    const report = buildVersionReport(home);
+    expect(report).toMatchObject({
+      productVersion: '1.223.0',
+      releaseId: 'b'.repeat(64),
+      bootstrapVersion: '1.1.0',
+      channel: 'candidate',
+      source: 'official-installer',
+      generation: 4,
+      health: 'healthy',
+    });
+    expect(report.components.plugin).toBe('1.76.1');
+    expect(report.lastTransaction).toEqual({ id: 'txn-9', kind: 'recovery', outcome: 'recovered' });
+    expect(formatShortVersion(report)).toBe(`Principles Disciple 1.223.0 (${'b'.repeat(12)})`);
+  });
+
+  it('classifies a legacy overlay installation with an installer next action', () => {
+    const home = tempHome();
+    // The current official installer creates ~/.pd/bin before the transactional
+    // dual-slot layout is activated. That support directory must not make a
+    // valid legacy overlay look like a corrupt partial dual-slot install.
+    fs.mkdirSync(path.join(home, '.pd', 'bin'), { recursive: true });
+    const overlay = path.join(home, '.openclaw', 'extensions', 'principles-disciple');
+    fs.mkdirSync(overlay, { recursive: true });
+    fs.writeFileSync(path.join(overlay, 'package.json'), JSON.stringify({ version: '1.218.0' }));
+    const report = buildVersionReport(home);
+    expect(report).toMatchObject({
+      productVersion: '1.218.0',
+      source: 'official-legacy-overlay',
+      health: 'degraded',
+      generation: 0,
+    });
+  });
+
+  it('retains compatibility with the older nested legacy overlay manifest', () => {
+    const home = tempHome();
+    const overlay = path.join(home, '.openclaw', 'extensions', 'principles-disciple', 'plugin');
+    fs.mkdirSync(overlay, { recursive: true });
+    fs.writeFileSync(path.join(overlay, 'package.json'), JSON.stringify({ version: '1.202.0' }));
+    expect(buildVersionReport(home)).toMatchObject({
+      productVersion: '1.202.0', source: 'official-legacy-overlay', health: 'degraded',
+    });
+  });
+
+  it('refuses with a structured reason and next action when nothing is installed', () => {
+    const home = tempHome();
+    try {
+      buildVersionReport(home);
+      throw new Error('expected VersionReportError');
+    } catch (error) {
+      expect(error).toBeInstanceOf(VersionReportError);
+      const refusal = error as VersionReportError;
+      expect(refusal.reason).toBe('not_installed');
+      expect(refusal.nextAction).toMatch(/official installer/i);
+    }
+  });
+
+  it('reports degraded health when the active release directory is incomplete', () => {
+    const home = tempHome();
+    writeDualSlotHome(home);
+    fs.rmSync(path.join(home, '.pd', 'releases', 'b'.repeat(64), 'metadata.json'), { force: true });
+    const report = buildVersionReport(home);
+    expect(report.health).toBe('degraded');
+  });
+
+  it('reports corrupt health when release metadata exists but disagrees with active.json', () => {
+    const home = tempHome();
+    writeDualSlotHome(home);
+    fs.writeFileSync(path.join(home, '.pd', 'releases', 'b'.repeat(64), 'metadata.json'), '{}');
+    const report = buildVersionReport(home);
+    expect(report.health).toBe('corrupt');
+  });
+
+  it('refuses a malformed active record loudly instead of guessing', () => {
+    const home = tempHome();
+    fs.mkdirSync(path.join(home, '.pd'), { recursive: true });
+    fs.writeFileSync(path.join(home, '.pd', 'active.json'), JSON.stringify({ generation: 'four' }));
+    try {
+      buildVersionReport(home);
+      throw new Error('expected VersionReportError');
+    } catch (error) {
+      expect(error).toBeInstanceOf(VersionReportError);
+      expect((error as VersionReportError).reason).toBe('active_record_corrupt');
+    }
+  });
+});

package/src/commands/console.ts

@@ -2,6 +2,13 @@ import * as path from 'path';
 import * as fs from 'fs';
 import { spawn, type ChildProcess } from 'child_process';
 import { resolveWorkspaceDir } from '../resolve-workspace.js';
+import {
+  getConsoleServerEntry,
+  getConsoleWebIndex,
+  getInstallLayoutPaths,
+  resolveInstallLayout,
+  type InstallLayoutMode,
+} from '@principles/install-layout';
 import {
   planConsoleLaunch,
   openBrowser,
@@ -36,11 +43,25 @@ interface ConsoleOptions {
   json?: boolean;
 }
 
-function getConsoleDir(): string | null {
+function getConsoleDir(): { dir: string; mode: InstallLayoutMode } | null {
   const homeDir = process.env.HOME || process.env.USERPROFILE;
   if (!homeDir) return null;
-  const consoleDir = path.join(homeDir, '.openclaw', 'extensions', 'principles-disciple', 'console');
-  return fs.existsSync(consoleDir) ? consoleDir : null;
+  const paths = getInstallLayoutPaths(homeDir);
+  let manifest: unknown;
+  try {
+    manifest = JSON.parse(fs.readFileSync(paths.manifest, 'utf8')) as unknown;
+  } catch {
+    manifest = undefined;
+  }
+  const resolved = resolveInstallLayout({
+    homeDir,
+    manifest,
+    canonicalRuntimeExists: fs.existsSync(paths.runtimeDir),
+    legacyExtensionExists: fs.existsSync(paths.openClawExtensionDir),
+  });
+  if (resolved.mode === 'missing') return null;
+  const dir = resolved.mode === 'canonical' ? paths.consoleDir : path.join(paths.openClawExtensionDir, 'console');
+  return { dir, mode: resolved.mode };
 }
 
 export async function handleConsole(opts: ConsoleOptions = {}): Promise<void> {
@@ -48,8 +69,8 @@ export async function handleConsole(opts: ConsoleOptions = {}): Promise<void> {
     ? path.resolve(opts.workspace)
     : resolveWorkspaceDir();
 
-  const consoleDir = getConsoleDir();
-  if (!consoleDir) {
+  const consoleLocation = getConsoleDir();
+  if (!consoleLocation) {
     const msg = 'pd-console is not installed. Run: npx create-principles-disciple to install.';
     if (opts.json) {
       console.log(JSON.stringify({ success: false, reason: msg, nextAction: 'npx create-principles-disciple' }));
@@ -60,7 +81,8 @@ export async function handleConsole(opts: ConsoleOptions = {}): Promise<void> {
     return;
   }
 
-  const serverEntry = path.join(consoleDir, 'dist', 'server.js');
+  const paths = getInstallLayoutPaths(process.env.HOME || process.env.USERPROFILE || '.');
+  const serverEntry = getConsoleServerEntry(paths, consoleLocation.mode);
   if (!fs.existsSync(serverEntry)) {
     const msg = `Console server entry not found at ${serverEntry}. Re-run installer.`;
     if (opts.json) {
@@ -74,7 +96,7 @@ export async function handleConsole(opts: ConsoleOptions = {}): Promise<void> {
 
   // EP-06 regression guard (PR #1169): verify web UI bundle exists before launch.
   // Without dist/web/index.html the server returns 404 "Run npm run build:ui first".
-  const webIndex = path.join(consoleDir, 'dist', 'web', 'index.html');
+  const webIndex = getConsoleWebIndex(paths, consoleLocation.mode);
   if (!fs.existsSync(webIndex)) {
     const msg = `Console web UI not found at ${webIndex}. The console bundle is corrupted. Re-run installer.`;
     if (opts.json) {
@@ -274,8 +296,8 @@ export async function handleConsoleOpen(opts: ConsoleOpenOptions = {}): Promise<
   }
 
   // 3) Check that the console runtime is installed (ERR-040: fail loud if missing)
-  const consoleDir = getConsoleDir();
-  if (!consoleDir) {
+  const consoleLocation = getConsoleDir();
+  if (!consoleLocation) {
     const result: ConsoleLaunchResult = {
       status: 'failed',
       url: '',
@@ -296,7 +318,8 @@ export async function handleConsoleOpen(opts: ConsoleOpenOptions = {}): Promise<
     process.exit(1);
     return;
   }
-  const serverEntry = path.join(consoleDir, 'dist', 'server.js');
+  const paths = getInstallLayoutPaths(process.env.HOME || process.env.USERPROFILE || '.');
+  const serverEntry = getConsoleServerEntry(paths, consoleLocation.mode);
   if (!fs.existsSync(serverEntry)) {
     const result: ConsoleLaunchResult = {
       status: 'failed',
@@ -322,7 +345,7 @@ export async function handleConsoleOpen(opts: ConsoleOpenOptions = {}): Promise<
   // EP-06 regression guard (PR #1169): verify web UI bundle exists before launch.
   // Without dist/web/index.html the server returns 404 "Run npm run build:ui first"
   // — a fatal first-impression bug for new users.
-  const webIndex = path.join(consoleDir, 'dist', 'web', 'index.html');
+  const webIndex = getConsoleWebIndex(paths, consoleLocation.mode);
   if (!fs.existsSync(webIndex)) {
     const result: ConsoleLaunchResult = {
       status: 'failed',

package/src/commands/pain-record.ts

@@ -12,6 +12,7 @@ import {
   resolveRuntimeConfig,
   isRuntimeConfigError,
   isFeatureEnabled,
+  isBuiltinPiAiProvider,
 } from '@principles/core/runtime-v2';
 import { resolveWorkspaceDir } from '../resolve-workspace.js';
 import { loadPdConfig, computeFlagsFromLoadResult } from '../services/pd-config-loader.js';
@@ -141,19 +142,11 @@ export async function handlePainRecord(opts: RecordOptions): Promise<void> {
     if (!config.model) missing.push('model');
     if (!config.apiKeyEnv) missing.push('apiKeyEnv');
     if (config.provider) {
-      try {
-        // pi-ai is an optional peer; the package may or may not resolve depending on
-        // the package manager (pnpm local vs npm in CI). @ts-ignore (not @ts-expect-error)
-        // is intentional: it suppresses TS2307 when absent and is silently ignored when present.
-        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-        // @ts-ignore
-        const { getProviders } = await import('@mariozechner/pi-ai');
-        const knownProviders = getProviders() as readonly string[];
-        if (!knownProviders.includes(config.provider) && !config.baseUrl) {
-          missing.push('baseUrl');
-        }
-      } catch {
-        // pi-ai may not be available
+      // PRI-621 PR2 review: the pi-ai catalog lookup is a core capability —
+      // the CLI queries it through @principles/core and must not depend on
+      // pi-ai directly (EP-06).
+      if (!isBuiltinPiAiProvider(config.provider) && !config.baseUrl) {
+        missing.push('baseUrl');
       }
     }