@pellux/goodvibes-agent 1.1.7 → 1.3.0

package/src/input/agent-workspace-review-packet-utils.ts

@@ -0,0 +1,265 @@
+import type { ArtifactDescriptor } from '@pellux/goodvibes-sdk/platform/artifacts';
+import type { AgentWorkspaceRecentReviewerHandoffArtifact, AgentWorkspaceReviewPacketPresetLineage } from './agent-workspace-types.ts';
+import { readArtifactMetadataNumber, readArtifactMetadataString, readArtifactMetadataStringList } from './agent-workspace-artifact-metadata.ts';
+
+export function isoToEpoch(value: string): number {
+  const timestamp = Date.parse(value);
+  return Number.isFinite(timestamp) ? timestamp : 0;
+}
+
+export function compactTimelineText(value: string, maxLength = 96): string {
+  const normalized = value.replace(/\s+/g, ' ').trim();
+  if (normalized.length <= maxLength) return normalized;
+  return `${normalized.slice(0, Math.max(0, maxLength - 3)).trimEnd()}...`;
+}
+
+export function uniqueStrings(values: readonly (string | null | undefined)[], limit: number): readonly string[] {
+  const seen = new Set<string>();
+  const result: string[] = [];
+  for (const value of values) {
+    const trimmed = value?.trim();
+    if (!trimmed || seen.has(trimmed)) continue;
+    seen.add(trimmed);
+    result.push(trimmed);
+    if (result.length >= limit) break;
+  }
+  return result;
+}
+
+export function isReviewerHandoffArtifact(artifact: ArtifactDescriptor): boolean {
+  const purpose = readArtifactMetadataString(artifact.metadata, 'purpose');
+  if (purpose === 'agent-model-compare-handoff') return true;
+  if (purpose.length > 0) return false;
+  return (artifact.filename ?? '').startsWith('blind-model-comparison-handoff-');
+}
+
+export function isModelCompareArtifact(artifact: ArtifactDescriptor): boolean {
+  const purpose = readArtifactMetadataString(artifact.metadata, 'purpose');
+  if (purpose === 'agent-model-compare') return true;
+  if (purpose.length > 0) return false;
+  return (artifact.filename ?? '').startsWith('blind-model-comparison-cmp_');
+}
+
+export function isModelCompareJudgmentArtifact(artifact: ArtifactDescriptor): boolean {
+  const purpose = readArtifactMetadataString(artifact.metadata, 'purpose');
+  if (purpose === 'agent-model-compare-judgment') return true;
+  if (purpose.length > 0) return false;
+  return (artifact.filename ?? '').startsWith('blind-model-comparison-judgment-');
+}
+
+export function isDocumentExportArtifact(artifact: ArtifactDescriptor): boolean {
+  return readArtifactMetadataString(artifact.metadata, 'purpose') === 'agent-document-export';
+}
+
+export function isModelCompareExportArtifact(artifact: ArtifactDescriptor): boolean {
+  return readArtifactMetadataString(artifact.metadata, 'purpose') === 'agent-model-compare-export';
+}
+
+export function isReviewerHandoffArchiveArtifact(artifact: ArtifactDescriptor): boolean {
+  return readArtifactMetadataString(artifact.metadata, 'purpose') === 'agent-model-compare-handoff-archive';
+}
+
+export function isModelCompareRouteDecisionArtifact(artifact: ArtifactDescriptor): boolean {
+  return readArtifactMetadataString(artifact.metadata, 'purpose') === 'agent-model-compare-route-decision';
+}
+
+export function isReviewPacketPresetArtifact(artifact: ArtifactDescriptor): boolean {
+  return readArtifactMetadataString(artifact.metadata, 'purpose') === 'agent-review-packet-preset';
+}
+
+export function artifactById(artifacts: readonly ArtifactDescriptor[], artifactId: string): ArtifactDescriptor | null {
+  return artifacts.find((artifact) => artifact.id === artifactId) ?? null;
+}
+
+export function firstArtifactMetadataString(
+  artifacts: readonly ArtifactDescriptor[],
+  artifactIds: readonly string[],
+  keys: readonly string[],
+): string {
+  for (const artifactId of artifactIds) {
+    const artifact = artifactById(artifacts, artifactId);
+    if (!artifact) continue;
+    for (const key of keys) {
+      const value = readArtifactMetadataString(artifact.metadata, key);
+      if (value) return value;
+    }
+  }
+  return '';
+}
+
+export function latestMatchingArtifact(
+  artifacts: readonly ArtifactDescriptor[],
+  currentArtifactId: string,
+  predicate: (artifact: ArtifactDescriptor) => boolean,
+): ArtifactDescriptor | null {
+  const current = artifactById(artifacts, currentArtifactId);
+  const currentCreatedAt = current?.createdAt ?? -1;
+  return artifacts
+    .filter((artifact) => artifact.id !== currentArtifactId && artifact.createdAt > currentCreatedAt && predicate(artifact))
+    .sort((left, right) => right.createdAt - left.createdAt || left.id.localeCompare(right.id))[0] ?? null;
+}
+
+export function reviewPacketPresetFreshness(
+  preset: ArtifactDescriptor,
+  artifacts: readonly ArtifactDescriptor[],
+): { readonly missingCount: number; readonly newerCount: number; readonly summary: string; readonly status: 'info' | 'attention' } {
+  const metadata = preset.metadata;
+  const primaryIds = [
+    readArtifactMetadataString(metadata, 'documentExportArtifactId'),
+    readArtifactMetadataString(metadata, 'comparisonArtifactId'),
+    readArtifactMetadataString(metadata, 'judgmentArtifactId'),
+    readArtifactMetadataString(metadata, 'revealedJudgmentArtifactId'),
+    readArtifactMetadataString(metadata, 'routeDecisionArtifactId'),
+    readArtifactMetadataString(metadata, 'handoffArtifactId'),
+    readArtifactMetadataString(metadata, 'handoffArchiveArtifactId'),
+  ].filter(Boolean);
+  const relatedIds = readArtifactMetadataStringList(metadata, 'relatedArtifactIds');
+  const referencedIds = uniqueStrings([...primaryIds, ...relatedIds], 40);
+  const missingCount = referencedIds.filter((artifactId) => !artifactById(artifacts, artifactId)).length;
+  const documentId = readArtifactMetadataString(metadata, 'documentId')
+    || firstArtifactMetadataString(artifacts, primaryIds, ['documentId', 'sourceDocumentId']);
+  const comparisonId = firstArtifactMetadataString(artifacts, primaryIds, ['comparisonId']);
+  const sourceArtifactId = firstArtifactMetadataString(artifacts, primaryIds, ['sourceArtifactId'])
+    || readArtifactMetadataString(metadata, 'documentExportArtifactId');
+  const handoffSourceArtifactId = readArtifactMetadataString(metadata, 'revealedJudgmentArtifactId')
+    || readArtifactMetadataString(metadata, 'judgmentArtifactId')
+    || readArtifactMetadataString(metadata, 'comparisonArtifactId')
+    || readArtifactMetadataString(metadata, 'documentExportArtifactId');
+  const judgmentArtifactId = readArtifactMetadataString(metadata, 'revealedJudgmentArtifactId')
+    || readArtifactMetadataString(metadata, 'judgmentArtifactId')
+    || firstArtifactMetadataString(artifacts, [readArtifactMetadataString(metadata, 'routeDecisionArtifactId')], ['judgmentArtifactId']);
+  const handoffArtifactId = readArtifactMetadataString(metadata, 'handoffArtifactId')
+    || firstArtifactMetadataString(artifacts, [readArtifactMetadataString(metadata, 'handoffArchiveArtifactId')], ['handoffArtifactId']);
+  const documentExportArtifactId = readArtifactMetadataString(metadata, 'documentExportArtifactId');
+  const comparisonArtifactId = readArtifactMetadataString(metadata, 'comparisonArtifactId');
+  const judgmentPresetArtifactId = readArtifactMetadataString(metadata, 'judgmentArtifactId');
+  const revealedJudgmentArtifactId = readArtifactMetadataString(metadata, 'revealedJudgmentArtifactId');
+  const routeDecisionArtifactId = readArtifactMetadataString(metadata, 'routeDecisionArtifactId');
+  const handoffPresetArtifactId = readArtifactMetadataString(metadata, 'handoffArtifactId');
+  const handoffArchiveArtifactId = readArtifactMetadataString(metadata, 'handoffArchiveArtifactId');
+  const freshnessChecks: Array<ArtifactDescriptor | null> = [
+    documentId && documentExportArtifactId
+      ? latestMatchingArtifact(artifacts, documentExportArtifactId, (artifact) => (
+        isDocumentExportArtifact(artifact) && readArtifactMetadataString(artifact.metadata, 'documentId') === documentId
+      ))
+      : null,
+    comparisonArtifactId && (documentId || sourceArtifactId)
+      ? latestMatchingArtifact(artifacts, comparisonArtifactId, (artifact) => (
+        isModelCompareArtifact(artifact)
+        && (
+          Boolean(documentId && readArtifactMetadataString(artifact.metadata, 'documentId') === documentId)
+          || Boolean(sourceArtifactId && readArtifactMetadataString(artifact.metadata, 'sourceArtifactId') === sourceArtifactId)
+        )
+      ))
+      : null,
+    judgmentPresetArtifactId && (comparisonId || sourceArtifactId || documentId)
+      ? latestMatchingArtifact(artifacts, judgmentPresetArtifactId, (artifact) => (
+        isModelCompareJudgmentArtifact(artifact)
+        && (
+          Boolean(comparisonId && readArtifactMetadataString(artifact.metadata, 'comparisonId') === comparisonId)
+          || Boolean(documentId && readArtifactMetadataString(artifact.metadata, 'documentId') === documentId)
+          || Boolean(sourceArtifactId && readArtifactMetadataString(artifact.metadata, 'sourceArtifactId') === sourceArtifactId)
+        )
+      ))
+      : null,
+    revealedJudgmentArtifactId && (comparisonId || sourceArtifactId || documentId)
+      ? latestMatchingArtifact(artifacts, revealedJudgmentArtifactId, (artifact) => (
+        isModelCompareJudgmentArtifact(artifact)
+        && artifact.metadata.revealIncludedInJudgment === true
+        && readArtifactMetadataString(artifact.metadata, 'winnerModel').length > 0
+        && (
+          Boolean(comparisonId && readArtifactMetadataString(artifact.metadata, 'comparisonId') === comparisonId)
+          || Boolean(documentId && readArtifactMetadataString(artifact.metadata, 'documentId') === documentId)
+          || Boolean(sourceArtifactId && readArtifactMetadataString(artifact.metadata, 'sourceArtifactId') === sourceArtifactId)
+        )
+      ))
+      : null,
+    routeDecisionArtifactId && (comparisonId || judgmentArtifactId)
+      ? latestMatchingArtifact(artifacts, routeDecisionArtifactId, (artifact) => (
+        isModelCompareRouteDecisionArtifact(artifact)
+        && (
+          Boolean(judgmentArtifactId && readArtifactMetadataString(artifact.metadata, 'judgmentArtifactId') === judgmentArtifactId)
+          || Boolean(comparisonId && readArtifactMetadataString(artifact.metadata, 'comparisonId') === comparisonId)
+        )
+      ))
+      : null,
+    handoffPresetArtifactId && (comparisonId || handoffSourceArtifactId)
+      ? latestMatchingArtifact(artifacts, handoffPresetArtifactId, (artifact) => (
+        isReviewerHandoffArtifact(artifact)
+        && (
+          Boolean(handoffSourceArtifactId && readArtifactMetadataString(artifact.metadata, 'sourceArtifactId') === handoffSourceArtifactId)
+          || Boolean(comparisonId && readArtifactMetadataString(artifact.metadata, 'comparisonId') === comparisonId)
+        )
+      ))
+      : null,
+    handoffArchiveArtifactId && (comparisonId || handoffArtifactId)
+      ? latestMatchingArtifact(artifacts, handoffArchiveArtifactId, (artifact) => (
+        isReviewerHandoffArchiveArtifact(artifact)
+        && (
+          Boolean(handoffArtifactId && readArtifactMetadataString(artifact.metadata, 'handoffArtifactId') === handoffArtifactId)
+          || Boolean(comparisonId && readArtifactMetadataString(artifact.metadata, 'comparisonId') === comparisonId)
+        )
+      ))
+      : null,
+  ];
+  const newerCount = new Set(freshnessChecks.filter((artifact): artifact is ArtifactDescriptor => artifact !== null).map((artifact) => artifact.id)).size;
+  const needsReview = missingCount > 0 || newerCount > 0;
+  return {
+    missingCount,
+    newerCount,
+    summary: needsReview ? `freshness needs review: ${missingCount} missing, ${newerCount} newer` : 'freshness current',
+    status: needsReview ? 'attention' : 'info',
+  };
+}
+
+export function buildReviewPacketPresetLineage(preset: ArtifactDescriptor | null): AgentWorkspaceReviewPacketPresetLineage | null {
+  if (!preset) return null;
+  const metadata = preset.metadata;
+  const refreshedFromArtifactId = readArtifactMetadataString(metadata, 'refreshOfArtifactId') || null;
+  const refreshedFromPresetId = readArtifactMetadataString(metadata, 'refreshOfPresetId') || null;
+  const freshnessMissingCount = readArtifactMetadataNumber(metadata, 'freshnessMissingCount');
+  const freshnessSupersededCount = readArtifactMetadataNumber(metadata, 'freshnessSupersededCount');
+  const freshnessUnresolvedCount = readArtifactMetadataNumber(metadata, 'freshnessUnresolvedCount');
+  const repairedCount = (freshnessMissingCount ?? 0) + (freshnessSupersededCount ?? 0);
+  const name = readArtifactMetadataString(metadata, 'name') || null;
+  const presetId = readArtifactMetadataString(metadata, 'presetId') || null;
+  const displayName = name ?? preset.filename ?? preset.id;
+  const summary = refreshedFromArtifactId
+    ? [
+      `${displayName} refreshed from ${refreshedFromArtifactId}`,
+      refreshedFromPresetId ? `source preset ${refreshedFromPresetId}` : '',
+      `repaired ${repairedCount}`,
+      `unresolved ${freshnessUnresolvedCount ?? 0}`,
+    ].filter(Boolean).join('; ')
+    : [
+      `${displayName} has no refresh lineage`,
+      presetId ? `preset ${presetId}` : '',
+    ].filter(Boolean).join('; ');
+  return {
+    artifactId: preset.id,
+    presetId,
+    name,
+    refreshed: Boolean(refreshedFromArtifactId),
+    refreshedFromArtifactId,
+    refreshedFromPresetId,
+    freshnessMissingCount,
+    freshnessSupersededCount,
+    freshnessUnresolvedCount,
+    summary,
+    inspectRoute: `agent_review_packet_presets show artifactId:"${preset.id}"`,
+  };
+}
+
+export function summarizeReviewerHandoffArtifact(artifact: ArtifactDescriptor): AgentWorkspaceRecentReviewerHandoffArtifact {
+  const metadata = artifact.metadata;
+  return {
+    id: artifact.id,
+    filename: artifact.filename ?? '(unnamed handoff artifact)',
+    createdAt: artifact.createdAt,
+    handoffId: readArtifactMetadataString(metadata, 'handoffId') || 'unknown-handoff',
+    comparisonId: readArtifactMetadataString(metadata, 'comparisonId') || 'unknown-comparison',
+    sourceArtifactId: readArtifactMetadataString(metadata, 'sourceArtifactId') || '(missing source)',
+    sourceKind: readArtifactMetadataString(metadata, 'sourceKind') || 'unknown',
+    relatedArtifactCount: readArtifactMetadataStringList(metadata, 'relatedArtifactIds').length,
+  };
+}

package/src/input/agent-workspace-settings.ts

@@ -56,6 +56,95 @@ export interface TuiSettingsImportOutcome extends SettingMutationOutcome {
   readonly runtimeSnapshot: AgentWorkspaceRuntimeSnapshot | null;
 }
 
+type TuiImportStatus = 'would_import' | 'unchanged' | 'skipped';
+
+interface TuiSettingsImportSource {
+  readonly id: string;
+  readonly label: string;
+  readonly path: string;
+  readonly sourcePackage: string;
+  readonly surfaceRoot: string;
+  readonly scope: 'user' | 'project';
+  readonly ownership: 'source-owned';
+  readonly mutatesSource: false;
+  readonly status: 'missing' | 'loaded' | 'invalid' | 'error';
+  readonly importableSettings: number;
+  readonly error?: string;
+}
+
+interface GoodVibesSettingsImportSourceCatalogEntry {
+  readonly packageId: string;
+  readonly surfaceRoot: string;
+  readonly scopes: readonly string[];
+  readonly status: 'implemented';
+  readonly ownership: 'source-owned';
+  readonly mutatesSource: false;
+}
+
+interface TuiSettingImportPlanEntry {
+  readonly key: string;
+  readonly source: string;
+  readonly value: unknown;
+  readonly status: TuiImportStatus;
+  readonly current: unknown;
+  readonly incoming: unknown;
+  readonly reason?: string;
+}
+
+interface TuiSubscriptionImportPlanEntry {
+  readonly provider?: string;
+  readonly kind: 'active' | 'pending';
+  readonly status: TuiImportStatus;
+  readonly reason?: string;
+}
+
+interface TuiSettingsImportPlan {
+  readonly sources: readonly TuiSettingsImportSource[];
+  readonly settings: readonly TuiSettingImportPlanEntry[];
+  readonly subscriptions: readonly TuiSubscriptionImportPlanEntry[];
+  readonly parseErrors: readonly string[];
+}
+
+export interface TuiSettingsImportPreview {
+  readonly summary: {
+    readonly settingsToImport: number;
+    readonly settingsUnchanged: number;
+    readonly settingsSkipped: number;
+    readonly activeSubscriptionsToImport: number;
+    readonly pendingSubscriptionsToImport: number;
+    readonly subscriptionsUnchanged: number;
+    readonly subscriptionsSkipped: number;
+    readonly parseErrors: number;
+  };
+  readonly sourceCatalog: readonly GoodVibesSettingsImportSourceCatalogEntry[];
+  readonly sources: readonly TuiSettingsImportSource[];
+  readonly settings: readonly {
+    readonly key: string;
+    readonly source: string;
+    readonly status: TuiImportStatus;
+    readonly current: unknown;
+    readonly incoming: unknown;
+    readonly reason?: string;
+  }[];
+  readonly subscriptions: readonly TuiSubscriptionImportPlanEntry[];
+  readonly policy: {
+    readonly effect: 'read-only' | 'state';
+    readonly confirmation: 'required-for-apply';
+    readonly boundary: string;
+  };
+}
+
+const GOODVIBES_SETTINGS_IMPORT_SOURCE_CATALOG: readonly GoodVibesSettingsImportSourceCatalogEntry[] = [
+  {
+    packageId: 'goodvibes-tui',
+    surfaceRoot: GOODVIBES_TUI_SURFACE_ROOT,
+    scopes: ['user-settings', 'project-settings', 'provider-subscriptions'],
+    status: 'implemented',
+    ownership: 'source-owned',
+    mutatesSource: false,
+  },
+];
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -84,6 +173,36 @@ function valuesMatch(left: unknown, right: unknown): boolean {
   return JSON.stringify(left) === JSON.stringify(right);
 }
 
+function isSecretLikeSettingKey(key: string): boolean {
+  const normalized = key.replace(/([a-z0-9])([A-Z])/g, '$1.$2').toLowerCase();
+  if (normalized.endsWith('secret.policy')) return false;
+  return /(?:secret|token|password|api[-_.]?key|api\.key|signing)/i.test(normalized);
+}
+
+function compactSettingValue(key: string, value: unknown): string {
+  if (value === undefined || value === null) return '(unset)';
+  if (isSecretLikeSettingKey(key)) return value === '' ? '(empty)' : '(secret)';
+  if (typeof value === 'boolean') return value ? 'true' : 'false';
+  if (typeof value === 'number') return Number.isFinite(value) ? String(value) : '(invalid)';
+  if (typeof value === 'string') {
+    if (value.length === 0) return '(empty)';
+    if (value.startsWith('goodvibes://secrets/')) return '(secret)';
+    return value.length > 36 ? `${value.slice(0, 33)}...` : value;
+  }
+  if (Array.isArray(value)) return `[${value.length} item${value.length === 1 ? '' : 's'}]`;
+  if (isRecord(value)) return '{...}';
+  return String(value);
+}
+
+function redactImportValue(key: string, value: unknown): unknown {
+  if (typeof value !== 'string') return value;
+  if (!value) return value;
+  if (isSecretLikeSettingKey(key)) {
+    return value.startsWith('goodvibes://secrets/') ? '<secret-ref>' : '<redacted>';
+  }
+  return value;
+}
+
 function readRecordMap(record: Record<string, unknown>, key: string): readonly unknown[] {
   const value = record[key];
   return isRecord(value) ? Object.values(value) : [];
@@ -109,7 +228,45 @@ function isPendingSubscriptionLogin(value: unknown): value is PendingSubscriptio
     && typeof value.createdAt === 'number';
 }
 
-function importTuiSubscriptions(context: CommandContext, parseErrors: string[]): {
+function planTuiSubscriptions(context: CommandContext, parseErrors: string[]): readonly TuiSubscriptionImportPlanEntry[] {
+  const shellPaths = context.workspace.shellPaths;
+  const manager = context.platform.subscriptionManager;
+  const result: TuiSubscriptionImportPlanEntry[] = [];
+  if (!shellPaths || !manager) return result;
+
+  const sourcePath = shellPaths.resolveUserPath(GOODVIBES_TUI_SURFACE_ROOT, 'subscriptions.json');
+  try {
+    const store = readJsonRecord(sourcePath);
+    if (!store) return result;
+    for (const entry of readRecordMap(store, 'subscriptions')) {
+      if (!isProviderSubscription(entry)) {
+        result.push({ kind: 'active', status: 'skipped', reason: 'active subscription with invalid shape' });
+        continue;
+      }
+      if (valuesMatch(manager.get(entry.provider), entry)) {
+        result.push({ provider: entry.provider, kind: 'active', status: 'unchanged' });
+        continue;
+      }
+      result.push({ provider: entry.provider, kind: 'active', status: 'would_import' });
+    }
+    for (const entry of readRecordMap(store, 'pending')) {
+      if (!isPendingSubscriptionLogin(entry)) {
+        result.push({ kind: 'pending', status: 'skipped', reason: 'pending subscription with invalid shape' });
+        continue;
+      }
+      if (valuesMatch(manager.getPending(entry.provider), entry)) {
+        result.push({ provider: entry.provider, kind: 'pending', status: 'unchanged' });
+        continue;
+      }
+      result.push({ provider: entry.provider, kind: 'pending', status: 'would_import' });
+    }
+  } catch (error) {
+    parseErrors.push(`subscriptions: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  return result;
+}
+
+function applyTuiSubscriptions(context: CommandContext, parseErrors: string[]): {
   readonly importedActive: string[];
   readonly importedPending: string[];
   readonly unchangedActive: string[];
@@ -233,6 +390,36 @@ export function buildAgentWorkspaceSettingActionEffect(
   };
 }
 
+export function buildAgentWorkspaceSettingActionPreview(
+  context: CommandContext | null,
+  action: AgentWorkspaceAction,
+): string | null {
+  const settingKey = action.settingKey?.trim();
+  const configManager = context?.platform?.configManager;
+  if (!settingKey || !configManager) return null;
+
+  const setting = agentWorkspaceSettingSchema(context, settingKey);
+  const currentValue = configManager.get(settingKey as ConfigKey);
+  let proposedValue: unknown;
+
+  if (action.settingValueHint !== undefined) {
+    proposedValue = action.settingValueHint;
+  } else if (setting?.type === 'boolean') {
+    proposedValue = !Boolean(currentValue);
+  } else if (setting?.type === 'enum' && setting.enumValues && setting.enumValues.length > 0) {
+    const currentIndex = Math.max(0, setting.enumValues.indexOf(String(currentValue)));
+    proposedValue = setting.enumValues[(currentIndex + 1) % setting.enumValues.length]!;
+  } else if (setting?.type === 'number' || setting?.type === 'string') {
+    proposedValue = 'edit value';
+  } else if (typeof currentValue === 'boolean') {
+    proposedValue = !currentValue;
+  } else {
+    proposedValue = 'choose value';
+  }
+
+  return `${settingKey}: ${compactSettingValue(settingKey, currentValue)} -> ${compactSettingValue(settingKey, proposedValue)}`;
+}
+
 export async function applyAgentWorkspaceSettingValue(
   context: CommandContext | null,
   setting: ConfigSetting,
@@ -275,51 +462,147 @@ export async function applyAgentWorkspaceSettingValue(
   }
 }
 
-export async function importAgentWorkspaceTuiSettings(context: CommandContext | null): Promise<TuiSettingsImportOutcome> {
+function buildTuiSettingsImportPlan(context: CommandContext | null): TuiSettingsImportPlan | null {
   const shellPaths = context?.workspace?.shellPaths;
   const configManager = context?.platform?.configManager;
-  if (!context || !shellPaths || !configManager) {
-    return {
-      status: 'GoodVibes TUI settings import is unavailable in this runtime.',
-      runtimeSnapshot: null,
-      result: {
-        kind: 'error',
-        title: 'Import unavailable',
-        detail: 'The workspace cannot locate shell paths or the Agent config manager.',
-        safety: 'safe',
-      },
-    };
-  }
+  if (!context || !shellPaths || !configManager) return null;
 
-  const sources = [
-    { label: 'user', path: shellPaths.resolveUserPath(GOODVIBES_TUI_SURFACE_ROOT, 'settings.json') },
-    { label: 'project', path: shellPaths.resolveProjectPath(GOODVIBES_TUI_SURFACE_ROOT, 'settings.json') },
+  const sourceInputs: readonly Omit<TuiSettingsImportSource, 'status' | 'importableSettings' | 'error'>[] = [
+    {
+      id: 'goodvibes-tui:user-settings',
+      label: 'goodvibes-tui user settings',
+      path: shellPaths.resolveUserPath(GOODVIBES_TUI_SURFACE_ROOT, 'settings.json'),
+      sourcePackage: 'goodvibes-tui',
+      surfaceRoot: GOODVIBES_TUI_SURFACE_ROOT,
+      scope: 'user',
+      ownership: 'source-owned',
+      mutatesSource: false,
+    },
+    {
+      id: 'goodvibes-tui:project-settings',
+      label: 'goodvibes-tui project settings',
+      path: shellPaths.resolveProjectPath(GOODVIBES_TUI_SURFACE_ROOT, 'settings.json'),
+      sourcePackage: 'goodvibes-tui',
+      surfaceRoot: GOODVIBES_TUI_SURFACE_ROOT,
+      scope: 'project',
+      ownership: 'source-owned',
+      mutatesSource: false,
+    },
   ];
   const values = new Map<string, { readonly value: unknown; readonly source: string }>();
   const parseErrors: string[] = [];
-  for (const source of sources) {
+  const sources: TuiSettingsImportSource[] = [];
+  for (const source of sourceInputs) {
+    if (!existsSync(source.path)) {
+      sources.push({ ...source, status: 'missing', importableSettings: 0 });
+      continue;
+    }
     try {
       const record = readJsonRecord(source.path);
-      if (!record) continue;
+      if (!record) {
+        const message = `${source.label}: settings store is not an object`;
+        parseErrors.push(message);
+        sources.push({ ...source, status: 'invalid', importableSettings: 0, error: message });
+        continue;
+      }
+      let importableSettings = 0;
       for (const setting of configManager.getSchema()) {
         if (!canImportTuiSetting(setting.key)) continue;
         const value = readNestedSettingValue(record, setting.key);
-        if (value !== undefined) values.set(setting.key, { value, source: source.label });
+        if (value === undefined) continue;
+        importableSettings += 1;
+        values.set(setting.key, { value, source: source.id });
       }
+      sources.push({ ...source, status: 'loaded', importableSettings });
     } catch (error) {
-      parseErrors.push(`${source.label}: ${error instanceof Error ? error.message : String(error)}`);
+      const message = `${source.label}: ${error instanceof Error ? error.message : String(error)}`;
+      parseErrors.push(message);
+      sources.push({ ...source, status: 'error', importableSettings: 0, error: message });
     }
   }
-  const subscriptions = importTuiSubscriptions(context, parseErrors);
+
+  const settings: TuiSettingImportPlanEntry[] = [];
+  for (const [key, entry] of values) {
+    const setting = agentWorkspaceSettingSchema(context, key);
+    if (!setting) continue;
+    const current = configManager.get(setting.key as ConfigKey);
+    const status: TuiImportStatus = valuesMatch(current, entry.value) ? 'unchanged' : 'would_import';
+    settings.push({
+      key: setting.key,
+      source: entry.source,
+      value: entry.value,
+      status,
+      current: redactImportValue(setting.key, current),
+      incoming: redactImportValue(setting.key, entry.value),
+    });
+  }
+  const subscriptions = planTuiSubscriptions(context, parseErrors);
+  return { sources, settings, subscriptions, parseErrors };
+}
+
+export function previewAgentWorkspaceTuiSettingsImport(context: CommandContext | null): TuiSettingsImportPreview | null {
+  const plan = buildTuiSettingsImportPlan(context);
+  if (!plan) return null;
+  return {
+    summary: {
+      settingsToImport: plan.settings.filter((entry) => entry.status === 'would_import').length,
+      settingsUnchanged: plan.settings.filter((entry) => entry.status === 'unchanged').length,
+      settingsSkipped: plan.settings.filter((entry) => entry.status === 'skipped').length,
+      activeSubscriptionsToImport: plan.subscriptions.filter((entry) => entry.kind === 'active' && entry.status === 'would_import').length,
+      pendingSubscriptionsToImport: plan.subscriptions.filter((entry) => entry.kind === 'pending' && entry.status === 'would_import').length,
+      subscriptionsUnchanged: plan.subscriptions.filter((entry) => entry.status === 'unchanged').length,
+      subscriptionsSkipped: plan.subscriptions.filter((entry) => entry.status === 'skipped').length,
+      parseErrors: plan.parseErrors.length,
+    },
+    sourceCatalog: GOODVIBES_SETTINGS_IMPORT_SOURCE_CATALOG,
+    sources: plan.sources,
+    settings: plan.settings.map((entry) => ({
+      key: entry.key,
+      source: entry.source,
+      status: entry.status,
+      current: entry.current,
+      incoming: entry.incoming,
+      ...(entry.reason ? { reason: entry.reason } : {}),
+    })),
+    subscriptions: plan.subscriptions,
+    policy: {
+      effect: 'read-only',
+      confirmation: 'required-for-apply',
+      boundary: 'Preview does not mutate state. Apply imports only Agent-owned settings and provider subscriptions from published GoodVibes platform sources.',
+    },
+  };
+}
+
+export async function importAgentWorkspaceTuiSettings(context: CommandContext | null): Promise<TuiSettingsImportOutcome> {
+  const shellPaths = context?.workspace?.shellPaths;
+  const configManager = context?.platform?.configManager;
+  if (!context || !shellPaths || !configManager) {
+    return {
+      status: 'GoodVibes settings import is unavailable in this runtime.',
+      runtimeSnapshot: null,
+      result: {
+        kind: 'error',
+        title: 'Import unavailable',
+        detail: 'The workspace cannot locate shell paths or the Agent config manager.',
+        safety: 'safe',
+      },
+    };
+  }
+
+  const plan = buildTuiSettingsImportPlan(context);
+  const values = plan?.settings ?? [];
+  const subscriptionParseErrors: string[] = [];
+  const subscriptions = applyTuiSubscriptions(context, subscriptionParseErrors);
+  const parseErrors: string[] = [...new Set([...(plan?.parseErrors ?? []), ...subscriptionParseErrors])];
   const subscriptionImports = subscriptions.importedActive.length + subscriptions.importedPending.length;
   const subscriptionUnchanged = subscriptions.unchangedActive.length + subscriptions.unchangedPending.length;
 
-  if (values.size === 0 && subscriptionImports === 0 && subscriptionUnchanged === 0 && subscriptions.skipped.length === 0) {
+  if (values.length === 0 && subscriptionImports === 0 && subscriptionUnchanged === 0 && subscriptions.skipped.length === 0) {
     const detail = parseErrors.length > 0
       ? `No importable settings or subscriptions found. ${parseErrors.join('; ')}`
-      : 'No GoodVibes TUI settings or subscription store with importable Agent-owned state was found.';
+      : 'No GoodVibes settings or subscription store with importable Agent-owned state was found.';
     return {
-      status: 'No GoodVibes TUI settings imported.',
+      status: 'No GoodVibes settings imported.',
       runtimeSnapshot: null,
       result: {
         kind: parseErrors.length > 0 ? 'error' : 'guidance',
@@ -333,10 +616,10 @@ export async function importAgentWorkspaceTuiSettings(context: CommandContext |
   const imported: string[] = [];
   const unchanged: string[] = [];
   const skipped: string[] = [];
-  for (const [key, entry] of values) {
-    const setting = agentWorkspaceSettingSchema(context, key);
+  for (const entry of values) {
+    const setting = agentWorkspaceSettingSchema(context, entry.key);
     if (!setting) continue;
-    if (valuesMatch(configManager.get(setting.key as ConfigKey), entry.value)) {
+    if (entry.status === 'unchanged' || valuesMatch(configManager.get(setting.key as ConfigKey), entry.value)) {
       unchanged.push(setting.key);
       continue;
     }
@@ -352,11 +635,11 @@ export async function importAgentWorkspaceTuiSettings(context: CommandContext |
   const unchangedCount = unchanged.length + subscriptionUnchanged;
 
   return {
-    status: changedCount > 0 ? `Imported ${changedCount} GoodVibes TUI item(s).` : 'No GoodVibes TUI settings changed.',
+    status: changedCount > 0 ? `Imported ${changedCount} GoodVibes settings item(s).` : 'No GoodVibes settings changed.',
     runtimeSnapshot: context ? buildAgentWorkspaceRuntimeSnapshot(context) : null,
     result: {
       kind: skipped.length > 0 && changedCount === 0 ? 'error' : changedCount > 0 ? 'refreshed' : 'guidance',
-      title: changedCount > 0 ? 'GoodVibes TUI settings imported' : 'No settings changed',
+      title: changedCount > 0 ? 'GoodVibes settings imported' : 'No settings changed',
       detail: [
         imported.length > 0 ? `Imported: ${imported.slice(0, 10).join(', ')}${imported.length > 10 ? `, +${imported.length - 10} more` : ''}.` : '',
         subscriptions.importedActive.length > 0 ? `Imported active subscription(s): ${subscriptions.importedActive.join(', ')}.` : '',