@principles/pd-cli 1.73.0

package/src/commands/runtime-canary.ts

@@ -0,0 +1,371 @@
+import * as path from 'path';
+import { OperatorHealthReadModel, SchemaConformanceReadModel, PruningReadModel, createInternalizationQueueReadModel, auditCandidateLedgerConsistency, buildGfiWorkspaceSnapshot, classifyGfiWorkspaceHealth } from '@principles/core/runtime-v2';
+import type { OperatorHealthSnapshot, SchemaConformanceResult, OrphanDetectionResult, InternalizationQueueSnapshot, GfiWorkspaceSnapshot, CandidateAuditResult } from '@principles/core/runtime-v2';
+import { resolveWorkspaceDir } from '../resolve-workspace.js';
+import { loadEffectiveFeatureFlags } from '../services/feature-flag-loader.js';
+
+export interface CanaryCheck {
+  name: string;
+  status: 'healthy' | 'degraded' | 'error';
+  summary: string;
+  details?: unknown;
+  error?: string;
+}
+
+export interface CanaryOutput {
+  overallStatus: 'healthy' | 'degraded' | 'error';
+  checks: CanaryCheck[];
+  recommendedNextActions: string[];
+  generatedAt: string;
+  internalizationQueueSummary?: InternalizationQueueSummary;
+}
+
+export interface InternalizationQueueSummary {
+  readyCount: number;
+  retryWaitCount: number;
+  pendingCount: number;
+  nextReadyTaskKind: string | null;
+  nextReadyTaskId: string | null;
+  noReadyReason: string | null;
+}
+
+interface CanaryOptions {
+  workspace?: string;
+  json?: boolean;
+}
+
+function computeOverallStatus(checks: CanaryCheck[]): 'healthy' | 'degraded' | 'error' {
+  let hasError = false;
+  let hasDegraded = false;
+  for (const check of checks) {
+    if (check.status === 'error') hasError = true;
+    if (check.status === 'degraded') hasDegraded = true;
+  }
+  if (hasError) return 'error';
+  if (hasDegraded) return 'degraded';
+  return 'healthy';
+}
+
+function buildRecommendedActions(checks: CanaryCheck[]): string[] {
+  const actions: string[] = [];
+  for (const check of checks) {
+    if (check.status === 'healthy') continue;
+    switch (check.name) {
+      case 'schema_conformance':
+        actions.push('Run workspace initialization to migrate schema: open DB with writable SqliteConnection.');
+        break;
+      case 'candidate_audit':
+        actions.push('Run `pd candidate audit --workspace <path> --json` for details.');
+        break;
+      case 'gfi_snapshot': {
+        const gfiDetails = check.details as { warnings?: string[]; configPath?: string } | undefined;
+        if (gfiDetails && gfiDetails.warnings && gfiDetails.warnings.length > 0) {
+          actions.push(`Review .pd/feature-flags.yaml and rerun \`pd runtime features --workspace <path> --json\`.`);
+        } else {
+          actions.push('Investigate GFI sessions — consider cleanup or session lifecycle review.');
+        }
+        break;
+      }
+      case 'pruning_orphans':
+        actions.push('Run `pd runtime pruning orphans --workspace <path> --dry-run` to inspect orphan candidates.');
+        break;
+      case 'internalization_queue': {
+        const queueDetails = check.details as InternalizationQueueSnapshot | undefined;
+        if (queueDetails && queueDetails.noReadyTasks?.reason === 'no_candidates' && queueDetails.noReadyTasks.inspectedCount === 0) {
+          actions.push('No internalization tasks found. If candidates exist, run `pd candidate internalization backfill --dry-run` to check, then `--confirm` to create dreamer tasks.');
+        } else {
+          actions.push('Check internalization queue for blocked or dependency-failed tasks.');
+        }
+        break;
+      }
+      case 'runtime_health': {
+        const details = check.details as OperatorHealthSnapshot | undefined;
+        if (details && details.totalTaskCount === 0) {
+          actions.push('Runtime V2 pipeline has never been exercised. Run `pd pain record --reason "test" --workspace <path>` to trigger the pain-to-principle chain.');
+        } else if (details && details.painChain.lastSuccessfulChain === null) {
+          actions.push('Run `pd runtime uat --workspace <path> --count 3` to establish baseline.');
+        } else {
+          actions.push('Review runtime health snapshot for specific failure categories.');
+        }
+        break;
+      }
+      case 'pd_shim_info':
+        actions.push('Verify pd CLI installation and sync-plugin configuration.');
+        break;
+    }
+  }
+  return actions;
+}
+
+export async function runCanaryChecks(workspaceDir: string): Promise<CanaryOutput> {
+  const generatedAt = new Date().toISOString();
+
+  const checkPromises: Promise<CanaryCheck>[] = [
+    (async (): Promise<CanaryCheck> => {
+      try {
+        const model = new SchemaConformanceReadModel({ workspaceDir });
+        const result: SchemaConformanceResult = model.check();
+        const status = result.overallStatus === 'ok' ? 'healthy' : result.overallStatus === 'degraded' ? 'degraded' : 'error';
+        const missingCount = Object.values(result.tables).filter(t => !t.exists || t.missingColumns.length > 0).length;
+        return {
+          name: 'schema_conformance',
+          status,
+          summary: status === 'healthy'
+            ? 'All tables and columns conform to expected schema.'
+            : `${missingCount} table(s) have missing columns or do not exist. Migrations needed: ${result.migrationsNeeded.join(', ')}`,
+          details: result,
+        };
+      } catch (err) {
+        return { name: 'schema_conformance', status: 'error', summary: 'Schema conformance check failed.', error: String(err) };
+      }
+    })(),
+    (async (): Promise<CanaryCheck> => {
+      try {
+        const result: CandidateAuditResult = await auditCandidateLedgerConsistency(workspaceDir);
+        const status = result.status === 'ok' ? 'healthy' : result.status === 'degraded' ? 'degraded' : 'error';
+        return {
+          name: 'candidate_audit',
+          status,
+          summary: status === 'healthy'
+            ? 'Candidate/ledger consistency OK.'
+            : `Audit status: ${result.status}. Orphan candidates: ${result.orphanCandidateCount}, Missing ledger: ${result.missingLedgerCount}`,
+          details: result,
+        };
+      } catch (err) {
+        return { name: 'candidate_audit', status: 'error', summary: 'Candidate audit check failed.', error: String(err) };
+      }
+    })(),
+    (async (): Promise<CanaryCheck> => {
+      try {
+        const featureFlags = loadEffectiveFeatureFlags(workspaceDir);
+        const gfiFlag = featureFlags.flags.gfi;
+        if (!gfiFlag || !gfiFlag.enabled) {
+          if (featureFlags.warnings.length > 0) {
+            return {
+              name: 'gfi_snapshot',
+              status: 'degraded',
+              summary: `GFI disabled but config has warnings: ${featureFlags.warnings.join('; ')}`,
+              details: { warnings: featureFlags.warnings, configPath: featureFlags.configPath },
+            };
+          }
+          return {
+            name: 'gfi_snapshot',
+            status: 'healthy',
+            summary: 'GFI feature flag disabled — skipping snapshot.',
+          };
+        }
+        const sessionDir = path.join(workspaceDir, '.state', 'sessions');
+        const fs = await import('fs');
+        const sessions: { sessionId: string; currentGfi: number; lastActivityAt: number; consecutiveErrors: number }[] = [];
+        if (fs.existsSync(sessionDir)) {
+          for (const file of fs.readdirSync(sessionDir)) {
+            if (!file.endsWith('.json')) continue;
+            try {
+              const raw = fs.readFileSync(path.join(sessionDir, file), 'utf8');
+              const parsed = JSON.parse(raw);
+              if (parsed?.sessionId) {
+                sessions.push({
+                  sessionId: parsed.sessionId,
+                  currentGfi: parsed.currentGfi ?? 0,
+                  lastActivityAt: parsed.lastActivityAt ?? parsed.lastControlActivityAt ?? 0,
+                  consecutiveErrors: parsed.consecutiveErrors ?? 0,
+                });
+              }
+            } catch { /* skip malformed */ }
+          }
+        }
+        const snapshot: GfiWorkspaceSnapshot = buildGfiWorkspaceSnapshot({ sessions, nowMs: Date.now() });
+        const health = classifyGfiWorkspaceHealth(snapshot);
+        const {status} = health;
+        return {
+          name: 'gfi_snapshot',
+          status,
+          summary: status === 'healthy'
+            ? `GFI snapshot OK. ${snapshot.activeSessionCount} active, ${snapshot.staleSessionCount} stale sessions.`
+            : `GFI degraded: ${health.reason}`,
+          details: { ...snapshot, healthAssessment: health },
+        };
+      } catch (err) {
+        return { name: 'gfi_snapshot', status: 'error', summary: 'GFI snapshot check failed.', error: String(err) };
+      }
+    })(),
+    (async (): Promise<CanaryCheck> => {
+      try {
+        const model = new PruningReadModel({ workspaceDir });
+        const result: OrphanDetectionResult = model.getOrphanDerivedCandidates();
+        const status = result.candidates.length > 0 ? 'degraded' : 'healthy';
+        return {
+          name: 'pruning_orphans',
+          status,
+          summary: status === 'healthy'
+            ? 'No orphan derived candidates found.'
+            : `${result.candidates.length} orphan derived candidate(s) found. dbReadable: ${result.dbReadable}`,
+          details: { orphanDerivedCandidateCount: result.candidates.length, dbReadable: result.dbReadable, samples: result.candidates.slice(0, 5) },
+        };
+      } catch (err) {
+        return { name: 'pruning_orphans', status: 'error', summary: 'Pruning orphan check failed.', error: String(err) };
+      }
+    })(),
+    (async (): Promise<CanaryCheck> => {
+      try {
+        const featureFlags = loadEffectiveFeatureFlags(workspaceDir);
+        const enabledChannels = new Set(
+          Object.values(featureFlags.flags)
+            .filter(f => f.enabled)
+            .map(f => f.id),
+        );
+        const { readModel, close } = await createInternalizationQueueReadModel({ workspaceDir, readonly: true, enabledChannels });
+        try {
+          const snapshot: InternalizationQueueSnapshot = await readModel.getSnapshot();
+          const hasBlocked = snapshot.blockedSummary.count > 0;
+          const hasDepFailed = snapshot.dependencyFailedSummary.count > 0;
+          const hasInvalid = snapshot.invalidMetadataCount > 0;
+          const hasLeaseConflicts = snapshot.leaseConflictSummary.count > 0;
+          // Suppressed tasks (disabled channels / non-MVP kinds) do NOT degrade health
+          const status = (hasBlocked || hasDepFailed || hasInvalid || hasLeaseConflicts) ? 'degraded' : 'healthy';
+          const suppressedNote = snapshot.suppressedTasks.length > 0
+            ? ` (${snapshot.suppressedTasks.length} suppressed non-MVP)`
+            : '';
+          return {
+            name: 'internalization_queue',
+            status,
+            summary: status === 'healthy'
+              ? `Queue OK. ${snapshot.readyTasks.length} ready, ${snapshot.pendingCount} pending, ${snapshot.retryWaitCount} retry_wait${suppressedNote}.`
+              : `Queue degraded: ${snapshot.blockedSummary.count} blocked, ${snapshot.dependencyFailedSummary.count} dep-failed, ${snapshot.invalidMetadataCount} invalid metadata, ${snapshot.leaseConflictSummary.count} lease conflicts${suppressedNote}.`,
+            details: snapshot,
+          };
+        } finally {
+          await close();
+        }
+      } catch (err) {
+        return { name: 'internalization_queue', status: 'error', summary: 'Internalization queue check failed.', error: String(err) };
+      }
+    })(),
+    (async (): Promise<CanaryCheck> => {
+      try {
+        const model = new OperatorHealthReadModel({ workspaceDir });
+        try {
+          const snapshot: OperatorHealthSnapshot = await model.getSnapshot();
+          const status = snapshot.overallStatus === 'healthy' ? 'healthy' : snapshot.overallStatus === 'degraded' ? 'degraded' : 'error';
+          return {
+            name: 'runtime_health',
+            status,
+            summary: status === 'healthy'
+              ? 'Runtime health OK.'
+              : `Runtime health: ${snapshot.overallStatus}. Actions: ${snapshot.recommendedActions.join('; ')}`,
+            details: snapshot,
+          };
+        } finally {
+          await model.close();
+        }
+      } catch (err) {
+        return { name: 'runtime_health', status: 'error', summary: 'Runtime health check failed.', error: String(err) };
+      }
+    })(),
+    (async (): Promise<CanaryCheck> => {
+      try {
+        const fs = await import('fs');
+        const cliPath = path.resolve(process.argv[1] ?? '');
+        const cliExists = fs.existsSync(cliPath);
+        const status = cliExists ? 'healthy' : 'degraded';
+        return {
+          name: 'pd_shim_info',
+          status,
+          summary: status === 'healthy'
+            ? `PD CLI accessible at ${cliPath}`
+            : 'PD CLI entrypoint not found — verify installation.',
+          details: { cliPath, exists: cliExists, version: '0.1.0' },
+        };
+      } catch (err) {
+        return { name: 'pd_shim_info', status: 'error', summary: 'PD shim check failed.', error: String(err) };
+      }
+    })(),
+  ];
+
+  const checkResults = await Promise.allSettled(checkPromises);
+  const checks: CanaryCheck[] = checkResults.map((result, index) => {
+    if (result.status === 'fulfilled') return result.value;
+    return {
+      name: `check_${index}`,
+      status: 'error' as const,
+      summary: 'Check failed unexpectedly.',
+      error: result.reason ? String(result.reason) : 'Unknown error',
+    };
+  });
+
+  const overallStatus = computeOverallStatus(checks);
+  const recommendedNextActions = buildRecommendedActions(checks);
+
+  const internalizationQueueCheck = checks.find(c => c.name === 'internalization_queue');
+  const internalizationQueueSummary: InternalizationQueueSummary | undefined =
+    internalizationQueueCheck && internalizationQueueCheck.details
+      ? (() => {
+          const snapshot = internalizationQueueCheck.details as InternalizationQueueSnapshot;
+          const firstReady = snapshot.readyTasks[0] ?? null;
+          return {
+            readyCount: snapshot.readyTasks.length,
+            retryWaitCount: snapshot.retryWaitCount,
+            pendingCount: snapshot.pendingCount,
+            nextReadyTaskKind: firstReady ? firstReady.taskKind : null,
+            nextReadyTaskId: firstReady ? firstReady.taskId : null,
+            noReadyReason: snapshot.noReadyTasks?.reason ?? null,
+          };
+        })()
+      : undefined;
+
+  return {
+    overallStatus,
+    checks,
+    recommendedNextActions,
+    generatedAt,
+    ...(internalizationQueueSummary ? { internalizationQueueSummary } : {}),
+  };
+}
+
+function formatTextOutput(output: CanaryOutput): string {
+  const lines: string[] = [];
+  const icon = output.overallStatus === 'healthy' ? '✓' : '✗';
+
+  lines.push('PD Control Plane Canary');
+  lines.push(`generatedAt: ${output.generatedAt}`);
+  lines.push(`OVERALL: ${icon} ${output.overallStatus.toUpperCase()}`);
+  lines.push('');
+
+  for (const check of output.checks) {
+    const checkIcon = check.status === 'healthy' ? '✓' : check.status === 'degraded' ? '⚠' : '✗';
+    lines.push(`  ${checkIcon} ${check.name}: ${check.summary}`);
+    if (check.error) {
+      lines.push(`    error: ${check.error}`);
+    }
+  }
+
+  if (output.recommendedNextActions.length > 0) {
+    lines.push('');
+    lines.push('Recommended next actions:');
+    for (const action of output.recommendedNextActions) {
+      lines.push(`  [!] ${action}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+export async function handleRuntimeCanary(opts: CanaryOptions): Promise<void> {
+  const workspaceDir = opts.workspace
+    ? path.resolve(opts.workspace)
+    : resolveWorkspaceDir();
+
+  const output = await runCanaryChecks(workspaceDir);
+
+  if (opts.json) {
+    console.log(JSON.stringify(output, null, 2));
+  } else {
+    console.log(formatTextOutput(output));
+  }
+
+  if (output.overallStatus !== 'healthy') {
+    console.error('');
+    console.error(`FAIL: overallStatus=${output.overallStatus}`);
+    process.exitCode = 1;
+  }
+}

package/src/commands/runtime-diagnostics-export.ts

@@ -0,0 +1,229 @@
+import * as path from 'path';
+import * as fs from 'fs';
+import {
+  OperatorHealthReadModel,
+  SchemaConformanceReadModel,
+  PruningReadModel,
+  createInternalizationQueueReadModel,
+  InternalizationChainIntegrityReadModel,
+  auditCandidateLedgerConsistency,
+  buildGfiWorkspaceSnapshot,
+} from '@principles/core/runtime-v2';
+import { runCanaryChecks } from './runtime-canary.js';
+import { resolveWorkspaceDir } from '../resolve-workspace.js';
+
+export interface BundleManifestArtifact {
+  name: string;
+  path: string;
+  status: 'ok' | 'failed';
+  error?: string;
+}
+
+export interface BundleManifest {
+  generatedAt: string;
+  workspace: string;
+  outputDir: string;
+  artifacts: BundleManifestArtifact[];
+}
+
+export interface DiagnosticsExportOptions {
+  workspace?: string;
+  out?: string;
+  json?: boolean;
+}
+
+function validateOutputPath(outDir: string, workspaceDir: string): string {
+  const resolvedOut = path.resolve(outDir);
+  const resolvedWs = path.resolve(workspaceDir);
+  const relative = path.relative(resolvedWs, resolvedOut);
+  if (relative.startsWith('..') || path.isAbsolute(relative)) {
+    throw new Error('Output path must be within workspace directory');
+  }
+  return resolvedOut;
+}
+
+function sanitizeForExport(data: unknown): unknown {
+  if (data === null || data === undefined) return data;
+  if (typeof data === 'string') {
+    return data.replace(/(?:api[_-]?key|secret|token|password|authorization|bearer)\s*[:=]\s*\S+/gi, '[REDACTED]');
+  }
+  if (Array.isArray(data)) return data.map(sanitizeForExport);
+  if (typeof data === 'object') {
+    const result: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(data as Record<string, unknown>)) {
+      const lowerKey = key.toLowerCase();
+      if (/key|secret|token|password|auth|bearer|credential/i.test(lowerKey)) {
+        result[key] = '[REDACTED]';
+      } else {
+        result[key] = sanitizeForExport(value);
+      }
+    }
+    return result;
+  }
+  return data;
+}
+
+interface CollectArtifactContext {
+  name: string;
+  fileName: string;
+  outputDir: string;
+  collector: () => Promise<unknown> | unknown;
+  artifacts: BundleManifestArtifact[];
+  errors: { artifact: string; error: string }[];
+}
+
+async function collectArtifact(ctx: CollectArtifactContext): Promise<void> {
+  try {
+    const data = await ctx.collector();
+    const sanitized = sanitizeForExport(data);
+    const filePath = path.join(ctx.outputDir, ctx.fileName);
+    fs.writeFileSync(filePath, JSON.stringify(sanitized, null, 2), 'utf8');
+    ctx.artifacts.push({ name: ctx.name, path: ctx.fileName, status: 'ok' });
+  } catch (err) {
+    ctx.artifacts.push({ name: ctx.name, path: ctx.fileName, status: 'failed', error: String(err) });
+    ctx.errors.push({ artifact: ctx.name, error: String(err) });
+  }
+}
+
+export async function exportDiagnosticsBundle(workspaceDir: string, outDir: string): Promise<BundleManifest> {
+  const generatedAt = new Date().toISOString();
+  const resolvedOut = validateOutputPath(outDir, workspaceDir);
+  const artifacts: BundleManifestArtifact[] = [];
+  const errors: { artifact: string; error: string }[] = [];
+
+  fs.mkdirSync(resolvedOut, { recursive: true });
+
+  const baseCtx = { outputDir: resolvedOut, artifacts, errors };
+
+  await collectArtifact({ ...baseCtx, name: 'runtime-health', fileName: 'runtime-health.json', collector: async () => {
+    const model = new OperatorHealthReadModel({ workspaceDir });
+    try {
+      return await model.getSnapshot();
+    } finally {
+      await model.close();
+    }
+  } });
+
+  await collectArtifact({ ...baseCtx, name: 'canary', fileName: 'canary.json', collector: async () => {
+    return await runCanaryChecks(workspaceDir);
+  } });
+
+  await collectArtifact({ ...baseCtx, name: 'schema-conformance', fileName: 'schema-conformance.json', collector: () => {
+    const model = new SchemaConformanceReadModel({ workspaceDir });
+    return model.check();
+  } });
+
+  await collectArtifact({ ...baseCtx, name: 'candidate-audit', fileName: 'candidate-audit.json', collector: async () => {
+    return await auditCandidateLedgerConsistency(workspaceDir);
+  } });
+
+  await collectArtifact({ ...baseCtx, name: 'gfi-snapshot', fileName: 'gfi-snapshot.json', collector: () => {
+    const sessionDir = path.join(workspaceDir, '.state', 'sessions');
+    const sessions: { sessionId: string; currentGfi: number; lastActivityAt: number; consecutiveErrors: number }[] = [];
+    if (fs.existsSync(sessionDir)) {
+      for (const file of fs.readdirSync(sessionDir)) {
+        if (!file.endsWith('.json')) continue;
+        try {
+          const raw = fs.readFileSync(path.join(sessionDir, file), 'utf8');
+          const parsed = JSON.parse(raw);
+          if (parsed?.sessionId) {
+            sessions.push({
+              sessionId: parsed.sessionId,
+              currentGfi: parsed.currentGfi ?? 0,
+              lastActivityAt: parsed.lastActivityAt ?? parsed.lastControlActivityAt ?? 0,
+              consecutiveErrors: parsed.consecutiveErrors ?? 0,
+            });
+          }
+        } catch { /* skip malformed */ }
+      }
+    }
+    return buildGfiWorkspaceSnapshot({ sessions, nowMs: Date.now() });
+  } });
+
+  await collectArtifact({ ...baseCtx, name: 'pruning-orphans', fileName: 'pruning-orphans.json', collector: () => {
+    const model = new PruningReadModel({ workspaceDir });
+    return model.getOrphanDerivedCandidates();
+  } });
+
+  await collectArtifact({ ...baseCtx, name: 'internalization-queue', fileName: 'internalization-queue.json', collector: async () => {
+    const { readModel, close } = await createInternalizationQueueReadModel({ workspaceDir, readonly: true });
+    try {
+      return await readModel.getSnapshot();
+    } finally {
+      await close();
+    }
+  } });
+
+  await collectArtifact({ ...baseCtx, name: 'internalization-integrity', fileName: 'internalization-integrity.json', collector: () => {
+    const model = new InternalizationChainIntegrityReadModel({ workspaceDir });
+    return model.check();
+  } });
+
+  await collectArtifact({ ...baseCtx, name: 'recent-session-summary', fileName: 'recent-session-summary.json', collector: () => {
+    const sessionDir = path.join(workspaceDir, '.state', 'sessions');
+    const summaries: { sessionId: string; status: string; lastActivityAt: number }[] = [];
+    if (fs.existsSync(sessionDir)) {
+      for (const file of fs.readdirSync(sessionDir)) {
+        if (!file.endsWith('.json')) continue;
+        try {
+          const raw = fs.readFileSync(path.join(sessionDir, file), 'utf8');
+          const parsed = JSON.parse(raw);
+          if (parsed?.sessionId) {
+            summaries.push({
+              sessionId: parsed.sessionId,
+              status: parsed.status ?? 'unknown',
+              lastActivityAt: parsed.lastActivityAt ?? parsed.lastControlActivityAt ?? 0,
+            });
+          }
+        } catch { /* skip */ }
+      }
+    }
+    return { sessionCount: summaries.length, sessions: summaries.slice(0, 20) };
+  } });
+
+  if (errors.length > 0) {
+    await collectArtifact({ outputDir: resolvedOut, artifacts, errors: [], name: 'errors', fileName: 'errors.json', collector: () => errors });
+  }
+
+  const manifest: BundleManifest = {
+    generatedAt,
+    workspace: workspaceDir,
+    outputDir: resolvedOut,
+    artifacts,
+  };
+
+  fs.writeFileSync(
+    path.join(resolvedOut, 'manifest.json'),
+    JSON.stringify(manifest, null, 2),
+    'utf8',
+  );
+
+  return manifest;
+}
+
+export async function handleRuntimeDiagnosticsExport(opts: DiagnosticsExportOptions): Promise<void> {
+  const workspaceDir = opts.workspace
+    ? path.resolve(opts.workspace)
+    : resolveWorkspaceDir();
+
+  const outDir = opts.out
+    ? path.resolve(workspaceDir, opts.out)
+    : path.resolve(workspaceDir, '.state', 'control-plane-observation', 'snapshots');
+
+  const manifest = await exportDiagnosticsBundle(workspaceDir, outDir);
+
+  if (opts.json) {
+    console.log(JSON.stringify(manifest, null, 2));
+  } else {
+    console.log(`Diagnostic bundle exported to: ${manifest.outputDir}`);
+    console.log(`Artifacts: ${manifest.artifacts.length}`);
+    for (const artifact of manifest.artifacts) {
+      const icon = artifact.status === 'ok' ? '✓' : '✗';
+      console.log(`  ${icon} ${artifact.name} (${artifact.path})`);
+    }
+    const failedCount = manifest.artifacts.filter(a => a.status === 'failed').length;
+    if (failedCount > 0) {
+      console.log(`\n${failedCount} artifact(s) failed to generate. See errors.json for details.`);
+    }
+  }
+}