@principles/pd-cli 1.142.3 → 1.143.0

package/src/services/version-report.ts

@@ -0,0 +1,203 @@
+/**
+ * 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 type VersionReportSource = 'official-installer' | 'official-legacy-overlay' | 'unknown';
+
+export interface VersionReport {
+  readonly productVersion: string;
+  readonly releaseId: string;
+  readonly components: Readonly<Record<string, string>>;
+  readonly bootstrapVersion: string;
+  readonly channel: 'stable' | 'candidate';
+  readonly source: VersionReportSource;
+  readonly generation: number;
+  readonly health: 'healthy' | 'degraded' | 'corrupt';
+  readonly lastTransaction: Readonly<{ id: string; kind: string; outcome: string }> | null;
+}
+
+export class VersionReportError extends Error {
+  readonly reason: string;
+  readonly nextAction: string;
+
+  constructor(reason: string, message: string, nextAction: string) {
+    super(message);
+    this.name = 'VersionReportError';
+    this.reason = reason;
+    this.nextAction = nextAction;
+  }
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function readJsonIfPresent(filePath: string): Record<string, unknown> | null {
+  if (!fs.existsSync(filePath)) return null;
+  let value: unknown;
+  try {
+    value = JSON.parse(fs.readFileSync(filePath, 'utf8')) as unknown;
+  } 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: Pick<VersionReport, 'productVersion' | 'releaseId'>): string {
+  return `Principles Disciple ${report.productVersion} (${report.releaseId.slice(0, 12)})`;
+}
+
+function buildLegacyOverlayReport(overlayDir: string, bootstrap: Record<string, unknown> | null): VersionReport {
+  // 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: string): VersionReport['lastTransaction'] {
+  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: unknown;
+  try {
+    value = JSON.parse(lastLine) as unknown;
+  } 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: string = os.homedir()): VersionReport {
+  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: VersionReport['health'] = releaseManifest === null
+    ? 'degraded'
+    : releaseMetadataMatchesActive ? 'healthy' : 'corrupt';
+
+  const components: Record<string, string> = {};
+  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')),
+  };
+}

package/tests/commands/console-open.test.ts

@@ -826,15 +826,22 @@ describe('CLI command wiring (pd console open)', () => {
       }
     });
 
-    it('[::1] is accepted and normalized to ::1 (not refused)', () => {
+    it('[::1] is accepted and normalized to ::1 (not refused)', async (ctx) => {
+      // PRI-581 / ERR-111: IPv6 loopback is an optional host capability — a
+      // global TUN VPN / WFP filter driver can silently block ::1 connections
+      // (bind succeeds, connect returns EACCES) while the IPv6 stack itself is
+      // healthy. Probe-and-skip instead of hard-failing for 8s on such hosts.
+      if (!(await isIpv6LoopbackUsable())) {
+        ctx.skip({ reason: 'IPv6 loopback (::1) is filtered on this machine (VPN/WFP filter driver? — see ERR-111 / PRI-581)' });
+        return;
+      }
       // May spawn a long-lived server, use timeout.
       const out = runPd(['console', 'open', '--workspace', tmp, '--host', '[::1]', '--json', '--no-browser'], workspaceRoot, 8_000);
       if (out.trim() === '') {
         // The CLI was still in its 15s ready-poll when execFileSync timed out.
-        // Known environment limitation: on Windows hosts where IPv6 loopback
-        // connections are refused (EACCES), the health probe on ::1 never
-        // succeeds. CI (Linux) is unaffected.
-        throw new Error('CLI produced no JSON within 8s — ::1 health probe never succeeded (IPv6 loopback may be blocked on this machine)');
+        // The capability probe above passed, so this is a genuine failure —
+        // the health probe on ::1 never succeeded despite ::1 being reachable.
+        throw new Error('CLI produced no JSON within 8s — ::1 health probe never succeeded (IPv6 loopback probe passed; this is a real failure)');
       }
       const parsed = JSON.parse(out);
       // Should NOT be refused — [::1] is loopback
@@ -861,6 +868,49 @@ describe('CLI command wiring (pd console open)', () => {
   });
 });
 
+/**
+ * Probe whether IPv6 loopback (::1) is actually usable on this machine.
+ * Mirrors the production path (TCP connect), not ICMP ping: on hosts where a
+ * VPN/WFP filter driver intercepts ::1 (bind OK + connect EACCES — ERR-111 /
+ * PRI-581), the console health probe on ::1 can never succeed, so the CLI
+ * test above must skip rather than hard-fail for environmental reasons.
+ */
+function isIpv6LoopbackUsable(): Promise<boolean> {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    let settled = false;
+    const finish = (ok: boolean) => {
+      if (settled) return;
+      settled = true;
+      server.close();
+      resolve(ok);
+    };
+    const timer = setTimeout(() => finish(false), 1_500);
+    server.once('error', () => {
+      clearTimeout(timer);
+      finish(false);
+    });
+    server.listen(0, '::1', () => {
+      const addr = server.address();
+      const port = addr !== null && typeof addr === 'object' ? addr.port : 0;
+      if (port === 0) {
+        clearTimeout(timer);
+        finish(false);
+        return;
+      }
+      const socket = net.connect({ port, host: '::1' }, () => {
+        socket.destroy();
+        clearTimeout(timer);
+        finish(true);
+      });
+      socket.once('error', () => {
+        clearTimeout(timer);
+        finish(false);
+      });
+    });
+  });
+}
+
 function runPd(args: string[], cwd: string, timeoutMs?: number): string {
   try {
     return execFileSync('node', [getBuiltPdCliPath(), ...args], {

package/tests/commands/pain-record.test.ts

@@ -55,6 +55,7 @@ vi.mock('@principles/core/runtime-v2', () => ({
     agentId: 'main',
   }),
   isRuntimeConfigError: vi.fn().mockReturnValue(false),
+  isBuiltinPiAiProvider: vi.fn().mockReturnValue(true),
   resolveOutputLanguage: vi.fn().mockReturnValue({ outputLanguage: 'zh-CN' }),
   isFeatureEnabled: vi.fn().mockReturnValue(false),
 }));
@@ -76,6 +77,7 @@ vi.mock('../../src/services/pd-config-loader.js', () => ({
 }));
 
 import { handlePainRecord } from '../../src/commands/pain-record.js';
+import { isBuiltinPiAiProvider } from '@principles/core/runtime-v2';
 import type { PainToPrincipleOutput, PainToPrincipleInput, FailureCategory } from '@principles/core/runtime-v2';
 
 // ── Helpers ─────────────────────────────────────────────────────────────────
@@ -478,4 +480,28 @@ describe('pd pain record', () => {
     errorSpy.mockRestore();
     exitSpy.mockRestore();
   });
+
+  // 9. PRI-621 PR2: the provider catalog is queried through @principles/core.
+  // A provider outside the builtin pi-ai catalog without baseUrl is reported
+  // as missing configuration — it must not be silently accepted.
+  it('reports baseUrl as missing configuration for a non-builtin provider', async () => {
+    mockRecordPainResult = makeFailedResult({
+      failureCategory: 'config_missing' as FailureCategory,
+      message: 'provider not in builtin catalog',
+    });
+    vi.mocked(isBuiltinPiAiProvider).mockReturnValue(false);
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const exitSpy = mockProcessExit();
+
+    await handlePainRecord({ reason: 'test pain' });
+
+    const printed = errorSpy.mock.calls.map((c) => String(c[0])).join('\n');
+    expect(printed).toContain('Missing configuration:');
+    expect(printed).toContain('- baseUrl');
+    expect(exitSpy).toHaveBeenCalledWith(1);
+
+    vi.mocked(isBuiltinPiAiProvider).mockReturnValue(true);
+    errorSpy.mockRestore();
+    exitSpy.mockRestore();
+  });
 });

package/tests/commands/runtime-activation-shadow-telemetry.test.ts

@@ -0,0 +1,130 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {
+  collectRuleCodeEventEntries,
+  readShadowSummaryForActivation,
+} from '../../src/commands/runtime-activation.js';
+
+/**
+ * PRI-577 regression tests — RuleCode shadow telemetry directory mismatch.
+ *
+ * Production writes rulehost_evaluated events to `{workspace}/.state/logs/` via the
+ * v1 EventLog component, while the reader used to scan only `{workspace}/.pd/logs/`
+ * (a directory no production code ever creates). These tests pin the real-world
+ * directory layout so a future refactor cannot silently re-break the channel.
+ */
+
+const ACTIVATION_ID = 'act_code_test-rule';
+
+function makeEventLine(eventOverrides: Record<string, unknown> = {}, dataOverrides: Record<string, unknown> = {}): string {
+  return JSON.stringify({
+    ts: '2026-08-21T00:47:00.469Z',
+    type: 'rulehost_evaluated',
+    category: 'evaluated',
+    data: {
+      toolName: 'write_file',
+      filePath: '<redacted>',
+      matched: true,
+      decision: 'block',
+      ruleId: 'rule-1',
+      activationId: ACTIVATION_ID,
+      activationMode: 'shadow',
+      ...dataOverrides,
+    },
+    ...eventOverrides,
+  });
+}
+
+describe('PRI-577 shadow telemetry dual-directory reading', () => {
+  let workspaceDir: string;
+
+  beforeEach(() => {
+    workspaceDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pri577-ws-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(workspaceDir, { recursive: true, force: true });
+  });
+
+  function writeEventsFile(relLogsDir: string, date: string, lines: string[]): void {
+    const dir = path.join(workspaceDir, ...relLogsDir.split('/'));
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, `events_${date}.jsonl`), lines.join('\n') + '\n', 'utf8');
+  }
+
+  it('reads shadow metrics when events live only in legacy .state/logs (production layout)', () => {
+    writeEventsFile('.state/logs', '2026-08-21', [
+      makeEventLine(),
+      makeEventLine({}, { toolName: 'exec', filePath: 'x', matched: false, decision: 'allow' }),
+    ]);
+
+    const summary = readShadowSummaryForActivation(workspaceDir, ACTIVATION_ID);
+    expect(summary.observed).toBe(2);
+    expect(summary.matched).toBe(1);
+    expect(summary.wouldBlock).toBe(1);
+    expect(summary.firstObservedAt).not.toBeNull();
+  });
+
+  it('merges entries when both .pd/logs and .state/logs exist', () => {
+    writeEventsFile('.state/logs', '2026-08-21', [makeEventLine()]);
+    writeEventsFile('.pd/logs', '2026-08-22', [
+      makeEventLine({ ts: '2026-08-22T10:00:00.000Z' }),
+    ]);
+    const summary = readShadowSummaryForActivation(workspaceDir, ACTIVATION_ID);
+    expect(summary.observed).toBe(2);
+    expect(summary.lastObservedAt).toBe('2026-08-22T10:00:00.000Z');
+  });
+
+  it('keeps distinct events from same-named daily files and deduplicates exact copied lines', () => {
+    const copied = makeEventLine();
+    writeEventsFile('.state/logs', '2026-08-21', [
+      copied,
+      makeEventLine({}, { toolName: 'exec', filePath: 'x', matched: false, decision: 'allow' }),
+    ]);
+    writeEventsFile('.pd/logs', '2026-08-21', [copied]);
+
+    const summary = readShadowSummaryForActivation(workspaceDir, ACTIVATION_ID);
+    expect(summary.observed).toBe(2);
+    expect(summary.wouldAllow).toBe(1);
+  });
+
+  it('reports zero (not unavailable) when a log dir exists but has no matching events', () => {
+    writeEventsFile('.state/logs', '2026-08-21', [
+      JSON.stringify({ ts: '2026-08-21T00:00:00.000Z', type: 'other_event', category: 'x', data: {} }),
+    ]);
+
+    const summary = readShadowSummaryForActivation(workspaceDir, ACTIVATION_ID);
+    // Distinguishes "channel alive, no data" (zeros) from "no channel" (nulls).
+    expect(summary.observed).toBe(0);
+    expect(summary.matched).toBe(0);
+  });
+
+  it('returns unavailable summary only when neither candidate directory exists', () => {
+    const summary = readShadowSummaryForActivation(workspaceDir, ACTIVATION_ID);
+    expect(summary).toEqual({
+      observed: null, matched: null, wouldBlock: null, wouldAllow: null,
+      requireApproval: null, autoCorrect: null, errors: null, neutralControl: null,
+      firstObservedAt: null, lastObservedAt: null,
+    });
+  });
+
+  it('does not report an unreadable candidate path as a healthy zero-event channel', () => {
+    fs.mkdirSync(path.join(workspaceDir, '.state'), { recursive: true });
+    fs.writeFileSync(path.join(workspaceDir, '.state', 'logs'), 'not a directory');
+    const summary = readShadowSummaryForActivation(workspaceDir, ACTIVATION_ID);
+    expect(summary.observed).toBeNull();
+  });
+
+  it('excludes malformed telemetry lines instead of failing the whole scan', () => {
+    writeEventsFile('.state/logs', '2026-08-21', [
+      '{not-valid-json',
+      makeEventLine(),
+    ]);
+
+    const collected = collectRuleCodeEventEntries(workspaceDir);
+    expect(collected.entries.length).toBe(1);
+    expect(collected.sourceDirsFound).toBeGreaterThanOrEqual(1);
+  });
+});

package/tests/commands/runtime-activation.test.ts

@@ -1,4 +1,8 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { createHash } from 'node:crypto';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
 
 const mockRuleHostWriterConfigs = vi.hoisted(() => [] as Array<{ featureFlagProbe?: (flagId: string) => boolean }>);
 const mockFeatureFlags = vi.hoisted(() => ({
@@ -100,7 +104,7 @@ vi.mock('@principles/core/runtime-v2', async (importOriginal) => {
     }),
     RuleHostWriter: vi.fn().mockImplementation(function (config) {
       mockRuleHostWriterConfigs.push(config);
-      return { channel: 'code_tool_hook' };
+      return { channel: 'code_tool_hook', canActivate: async () => ({ ok: true }) };
     }),
     resolveOutputLanguage: vi.fn().mockReturnValue({ outputLanguage: 'zh-CN' }),
   };
@@ -1007,6 +1011,68 @@ describe('handleRuntimeActivationPromote', () => {
     expect(mockPromoteActivation).not.toHaveBeenCalled();
     expect(process.exitCode).toBe(1);
   });
+
+  it('P0-3: commit store failure emits structured refusal JSON and exit code 1', async () => {
+    mockFeatureFlags.flags.rulecode_owner_live_decision.enabled = true;
+    vi.stubEnv('PD_CONSOLE_TOKEN', 'configured-secret');
+    vi.stubEnv('PD_OWNER_ID', 'owner-1');
+    vi.stubEnv('PD_OWNER_CREDENTIAL_ID', 'credential-1');
+
+    const artifact = makeArtifact({
+      artifactId: 'art-002',
+      lineageArtifactIds: ['task-000'],
+      contentJson: JSON.stringify({
+        principleId: 'P_001',
+        affectedTools: ['Bash'],
+        goldenTrace: {
+          traceId: 'trace-1',
+          sourcePainId: 'pain-1',
+          cases: [{ caseId: 'c1', kind: 'positive', toolName: 'Bash', params: {}, expectedDecision: 'allow' }],
+          createdAt: '2026-01-01T00:00:00.000Z',
+        },
+      }),
+    });
+    mockGetArtifactById.mockResolvedValue(artifact);
+    const artifactDigest = `sha256:${createHash('sha256').update(JSON.stringify(artifact), 'utf8').digest('hex')}`;
+
+    // PRI-577 fail-loud contract: readiness is unavailable without a readable
+    // shadow telemetry source, so seed a real events file before promoting.
+    const wsDir = mkdtempSync(path.join(tmpdir(), 'pd-cli-p03-'));
+    mkdirSync(path.join(wsDir, '.pd', 'logs'), { recursive: true });
+    writeFileSync(
+      path.join(wsDir, '.pd', 'logs', 'events_20260821.jsonl'),
+      `${JSON.stringify({ type: 'rulehost_evaluated', ts: '2026-08-21T00:00:00.000Z', data: { activationId: 'act-hook-1', activationMode: 'shadow', matched: true, decision: 'allow' } })}\n`,
+      'utf8',
+    );
+
+    try {
+      await handleRuntimeActivationPromote({
+        workspace: wsDir,
+        activationId: 'act-hook-1',
+        confirm: true,
+        json: true,
+        artifactId: 'art-002',
+        artifactDigest,
+        controlVersion: 1,
+        idempotencyKey: 'promote-commit-fail-1',
+        reasonCode: 'controlled_rollout',
+        note: 'Owner accepts limited evidence for a controlled rollout.',
+      });
+
+      const output = JSON.parse(consoleLogSpy.mock.calls[0][0]) as {
+        ok: boolean; decision: string; reasonCode: string; summary?: string; nextAction?: string;
+      };
+      expect(output.ok).toBe(false);
+      expect(output.decision).toBe('refused');
+      expect(output.reasonCode).toBe('promotion_commit_failed');
+      expect(output.summary).toContain('durable safety store');
+      expect(output.nextAction).toContain('retry');
+      expect(process.exitCode).toBe(1);
+      expect(mockPromoteActivation).not.toHaveBeenCalled();
+    } finally {
+      try { rmSync(wsDir, { recursive: true, force: true }); } catch { /* best effort */ }
+    }
+  });
 });
 
 // P1 #2 fix: Edit pending approval command tests

package/tests/commands/runtime-internalization-enqueue-successors.test.ts

@@ -13,7 +13,12 @@ vi.mock('../../src/resolve-workspace.js', () => ({
   resolveWorkspaceDir: vi.fn().mockReturnValue('/fake/workspace'),
 }));
 
-vi.mock('@principles/core/runtime-v2', () => ({
+// PRI-612: spread the real barrel exports so pure constants consumed by the
+// command (PD_TASK_STATUSES) stay authentic; only the stateful classes are
+// mocked. Previously a bare factory mock left new barrel exports undefined
+// at runtime (ERR-083 vi.mock variant — 19 tests failed on CI).
+vi.mock('@principles/core/runtime-v2', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('@principles/core/runtime-v2')>()),
   RuntimeStateManager: vi.fn().mockImplementation(function (opts: Record<string, unknown>) {
     mockRuntimeStateManagerOpts(opts);
     return {