@pellux/goodvibes-tui 0.20.3 → 0.22.0

package/src/cli/config-overrides.ts

@@ -1,3 +1,4 @@
+import { existsSync, readFileSync } from 'node:fs';
 import type { ConfigKey, ConfigManager, ConfigSetting, GoodVibesConfig, PersistedFlagState } from '../config/index.ts';
 import { CONFIG_SCHEMA, ConfigError } from '../config/index.ts';
 import type { GoodVibesCliCommand, GoodVibesCliFlags } from './types.ts';
@@ -62,6 +63,73 @@ function setNestedConfigValue(config: GoodVibesConfig, key: ConfigKey, value: un
   (cursor as Record<string, unknown>)[parts[parts.length - 1]!] = value;
 }
 
+/**
+ * Typed accessor for the SDK's private file paths on ConfigManager.
+ *
+ * SDK coupling: configPath and projectConfigPath are declared `private readonly`
+ * in the SDK's ConfigManager (see manager.d.ts — configPath, projectConfigPath). No public accessors exist
+ * as of the SDK version pinned in this project. This cast is the narrowest
+ * possible workaround. SDK public-accessor request: see HANDOFF-FROM-TUI-SESSION-20260611.md,
+ * Item 6 area. If the SDK ever exposes getConfigPath()/getProjectConfigPath(), replace
+ * this cast with those calls and remove this comment.
+ *
+ * Fail-open: if the cast produces undefined (SDK internal rename), the paths are
+ * treated as absent and the default is applied safely.
+ */
+function getPersistedPaths(configManager: ConfigManager): { configPath: string | undefined; projectConfigPath: string | undefined } {
+  const manager = configManager as unknown as { configPath?: string; projectConfigPath?: string };
+  return {
+    configPath: typeof manager.configPath === 'string' ? manager.configPath : undefined,
+    projectConfigPath: typeof manager.projectConfigPath === 'string' ? manager.projectConfigPath : undefined,
+  };
+}
+
+/**
+ * Returns true if the given dot-path key is explicitly present anywhere
+ * in the provided raw JSON object.
+ */
+function isKeyPresentInRaw(raw: Record<string, unknown>, key: ConfigKey): boolean {
+  const parts = key.split('.');
+  let cursor: unknown = raw;
+  for (const part of parts) {
+    if (cursor == null || typeof cursor !== 'object' || !(part in (cursor as object))) {
+      return false;
+    }
+    cursor = (cursor as Record<string, unknown>)[part];
+  }
+  return true;
+}
+
+/**
+ * Apply a TUI default to a config key, but ONLY if the user has not explicitly
+ * set the key in EITHER their global OR project persisted settings files.
+ * Reads the raw settings JSON from disk (bypasses the in-memory merged config)
+ * so a user's explicit `false` in either file is never silently overridden at startup.
+ *
+ * Each settings file is read independently: a parse failure on one file
+ * contributes nothing but does NOT prevent the other file from being checked.
+ * The default is applied only when the key is absent from every readable file
+ * (e.g. new install, both files missing, or both unparseable).
+ */
+export function applyRuntimeConfigDefault(configManager: ConfigManager, key: ConfigKey, defaultValue: unknown): void {
+  const { configPath, projectConfigPath } = getPersistedPaths(configManager);
+  // Check each settings file independently. A read/parse failure on one path
+  // contributes nothing but must not prevent the other path from being checked.
+  for (const filePath of [configPath, projectConfigPath]) {
+    if (typeof filePath !== 'string' || !existsSync(filePath)) continue;
+    try {
+      const raw = JSON.parse(readFileSync(filePath, 'utf-8')) as Record<string, unknown>;
+      if (isKeyPresentInRaw(raw, key)) {
+        // Key is explicitly set in this persisted config — respect the user's value.
+        return;
+      }
+    } catch {
+      // Unreadable or malformed JSON — this file contributes nothing; continue to next.
+    }
+  }
+  applyRuntimeConfigValue(configManager, key, defaultValue);
+}
+
 export function applyRuntimeConfigValue(configManager: ConfigManager, key: ConfigKey, value: unknown): void {
   const setting = CONFIG_SCHEMA_BY_KEY.get(key);
   if (!setting) {

package/src/cli/entrypoint.ts

@@ -61,6 +61,12 @@ export async function prepareShellCliRuntime(
     process.exit(2);
   }
 
+  if (cli.warnings.length > 0) {
+    for (const warning of cli.warnings) {
+      console.warn(`[goodvibes] warning: ${warning}`);
+    }
+  }
+
   if (cli.flags.help || cli.command === 'help') {
     const helpTopic = cli.command === 'help'
       ? cli.commandArgs[0]

package/src/cli/help.ts

@@ -71,12 +71,14 @@ export function renderGoodVibesHelp(binary = 'goodvibes'): string {
     '      --json                     Alias for --output-format json',
     '      --no-alt-screen            Keep output in normal terminal scrollback',
     '      --port <port>              Port for server/web commands',
-    '      --hostname <host>          Hostname for server/web commands',
+    '      --hostname <host>          Hostname for server/web commands (--host is an alias)',
     '      --open                     Open browser when supported',
     '  -r, --resume [id|latest]       Resume saved session when supported',
     '  -s, --session <id>             Use a specific session when supported',
     '      --continue                 Continue the latest session when supported',
-    '      --fork                     Fork session when supported',
+    '      --fork [id]                Fork session (current or specific id) when supported',
+    '  -y, --yes                      Auto-confirm prompts (non-interactive)',
+    '      --non-interactive          Disable all interactive prompts (implies --yes)',
     '  -h, --help                     Print help',
     '  -v, --version                  Print version',
     '',

package/src/cli/management-commands.ts

@@ -9,7 +9,7 @@ import { getOrCreateCompanionToken, buildCompanionConnectionInfo, encodeConnecti
 import { generateQrMatrix, renderQrToString } from '@pellux/goodvibes-sdk/platform/pairing';
 import { resolveRuntimeEndpointBinding } from './endpoints.ts';
 import { classifyBindPosture, isNetworkFacing } from './network-posture.ts';
-import type { CliCommandRuntime } from './management.ts';
+import type { CliCommandRuntime } from './types.ts';
 import { extractAuthorizationCode, formatJsonOrText, hasCommandFlag, openBrowser, probeTcp, readAuthPaths, runNonInteractiveAgent, urlHostForBindHost, withRuntimeServices, yesNo } from './management.ts';
 
 export async function renderSubscriptions(runtime: CliCommandRuntime): Promise<string> {

package/src/cli/management.ts

@@ -21,7 +21,7 @@ import { beginOpenAICodexLogin, exchangeOpenAICodexCode } from '@pellux/goodvibe
 import { inspectProviderAuth } from '@/runtime/index.ts';
 import { getOrCreateCompanionToken, buildCompanionConnectionInfo, encodeConnectionPayload, formatConnectionBlock } from '@pellux/goodvibes-sdk/platform/pairing';
 import { generateQrMatrix, renderQrToString } from '@pellux/goodvibes-sdk/platform/pairing';
-import type { GoodVibesCliParseResult } from './types.ts';
+import type { CliCommandRuntime, GoodVibesCliParseResult } from './types.ts';
 import { formatProviderAuthRoute, summarizeProviderAuthRoutes } from './provider-auth-routes.ts';
 import { classifyProviderSetup } from './provider-classification.ts';
 import { resolveRuntimeEndpointBinding } from './endpoints.ts';
@@ -32,13 +32,6 @@ import { handleBundleCommand } from './bundle-command.ts';
 import { buildListenerTestResult, formatListenerTestResult, handleSurfacesCommand } from './surface-command.ts';
 import { buildControlPlaneStatusResult, formatControlPlaneStatus, handleSecrets, handleSessions, handleTasks, renderPairing, renderRemote, renderSubscriptions, renderWeb } from './management-commands.ts';
 
-export interface CliCommandRuntime {
-  readonly cli: GoodVibesCliParseResult;
-  readonly configManager: ConfigManager;
-  readonly workingDirectory: string;
-  readonly homeDirectory: string;
-}
-
 interface CliCommandResult {
   readonly handled: boolean;
   readonly exitCode: number;

package/src/cli/parser.ts

@@ -76,9 +76,9 @@ function createDefaultFlags(): GoodVibesCliFlags {
     continueLast: false,
     resume: undefined,
     session: undefined,
-    fork: false,
-    rawOutput: false,
-    acceptRawOutputRisk: false,
+    fork: undefined,
+    yes: false,
+    nonInteractive: false,
   };
 }
 
@@ -132,9 +132,9 @@ function parsePort(value: string | undefined, optionName: string, errors: string
   return port;
 }
 
-function normalizeOutputFormat(value: string | undefined, errors: string[]): GoodVibesCliOutputFormat {
+function normalizeOutputFormat(value: string | undefined, flagName: string, errors: string[]): GoodVibesCliOutputFormat {
   if (value === 'text' || value === 'json' || value === 'stream-json') return value;
-  errors.push('--output-format must be one of: text, json, stream-json.');
+  errors.push(`${flagName} must be one of: text, json, stream-json.`);
   return 'text';
 }
 
@@ -174,6 +174,7 @@ export function parseGoodVibesCli(
   const commandArgs: string[] = [];
   const positionals: string[] = [];
   const errors: string[] = [];
+  const warnings: string[] = [];
   let sawCommand = false;
   let passthrough = false;
 
@@ -238,15 +239,17 @@ export function parseGoodVibesCli(
       continue;
     }
     if (name === '--fork') {
-      flags = withFlag(flags, 'fork', true);
+      const consumed = getOptionalValue(argv, index, inlineValue);
+      index = consumed.nextIndex;
+      flags = withFlag(flags, 'fork', consumed.value ?? true);
       continue;
     }
-    if (name === '--raw-output') {
-      flags = withFlag(flags, 'rawOutput', true);
+    if (name === '--yes' || name === '-y') {
+      flags = withFlag(flags, 'yes', true);
       continue;
     }
-    if (name === '--accept-raw-output-risk') {
-      flags = withFlag(flags, 'acceptRawOutputRisk', true);
+    if (name === '--non-interactive') {
+      flags = withFlag(withFlag(flags, 'nonInteractive', true), 'yes', true);
       continue;
     }
 
@@ -289,16 +292,13 @@ export function parseGoodVibesCli(
     if (name === '--output-format' || name === '--output' || name === '-o') {
       const consumed = getValue(argv, index, inlineValue, name, errors);
       index = consumed.nextIndex;
-      flags = withFlag(flags, 'outputFormat', normalizeOutputFormat(consumed.value, errors));
-      continue;
-    }
-    if (name === '--config') {
-      const consumed = getValue(argv, index, inlineValue, name, errors);
-      index = consumed.nextIndex;
-      if (consumed.value !== undefined) flags = appendFlagArray(flags, 'configOverrides', consumed.value);
+      flags = withFlag(flags, 'outputFormat', normalizeOutputFormat(consumed.value, name, errors));
+      if (name === '--output-format') {
+        warnings.push('--output-format is deprecated; use --output (or -o) instead.');
+      }
       continue;
     }
-    if (name === '-c') {
+    if (name === '--config' || name === '-c') {
       const consumed = getValue(argv, index, inlineValue, name, errors);
       index = consumed.nextIndex;
       if (consumed.value !== undefined) flags = appendFlagArray(flags, 'configOverrides', consumed.value);
@@ -357,6 +357,18 @@ export function parseGoodVibesCli(
     errors.push(`Unknown command: ${rawCommand}`);
   }
 
+  // Session lifecycle conflict detection — only one of --continue / --resume / --fork may be used.
+  const sessionLifecycleFlags = [
+    flags.continueLast ? '--continue' : undefined,
+    flags.resume !== undefined ? '--resume' : undefined,
+    flags.fork !== undefined ? '--fork' : undefined,
+  ].filter((f): f is string => f !== undefined);
+  if (sessionLifecycleFlags.length > 1) {
+    errors.push(
+      `Conflicting session lifecycle flags: ${sessionLifecycleFlags.join(' and ')}. Use only one of --continue, --resume, or --fork.`,
+    );
+  }
+
   return {
     binary,
     command,
@@ -365,5 +377,6 @@ export function parseGoodVibesCli(
     positionals,
     flags,
     errors,
+    warnings,
   };
 }

package/src/cli/service-command.ts

@@ -1,5 +1,5 @@
 import { mkdirSync } from 'node:fs';
-import type { CliCommandRuntime } from './management.ts';
+import type { CliCommandRuntime } from './types.ts';
 import { buildCliServicePosture, createPlatformServiceManager, formatCliServicePosture, getServiceStateRoot } from './service-posture.ts';
 import type { CliCommandOutput } from './types.ts';
 

package/src/cli/surface-command.ts

@@ -8,7 +8,7 @@ import {
 import { enableFeatureFlags, getMissingSurfaceFeatureFlags, getServerSurfaceFeatureFlags } from '../runtime/surface-feature-flags.ts';
 import { resolveRuntimeEndpointBinding } from './endpoints.ts';
 import { classifyBindPosture, isNetworkFacing } from './network-posture.ts';
-import type { CliCommandRuntime } from './management.ts';
+import type { CliCommandRuntime } from './types.ts';
 import {
   applyTargetEndpointFlagsOrDefault,
   enableEndpointLanDefault,

package/src/cli/tui-startup.ts

@@ -1,32 +1,94 @@
 import type { CommandContext, CommandRegistry } from '../input/command-registry.ts';
 import type { InputHandler } from '../input/handler.ts';
-import { readOnboardingCheckMarker } from '../runtime/onboarding/index.ts';
+import { hasResumableWizardProgress, readOnboardingCheckMarker, readWizardProgress } from '../runtime/onboarding/index.ts';
+import { readLastSessionPointer } from '@/runtime/index.ts';
 import type { GoodVibesCliParseResult } from './types.ts';
 
+export type TuiStartupShellPaths = Parameters<typeof readOnboardingCheckMarker>[0] & {
+  readonly workingDirectory: string;
+  readonly homeDirectory: string;
+};
+
 export function applyInitialTuiCliState(options: {
   readonly cli: GoodVibesCliParseResult;
   readonly input: InputHandler;
   readonly commandRegistry: CommandRegistry;
   readonly commandContext: CommandContext;
-  readonly shellPaths: Parameters<typeof readOnboardingCheckMarker>[0];
+  readonly shellPaths: TuiStartupShellPaths;
   readonly render: () => void;
-}): void {
+}): Promise<void> | undefined {
   const { cli, input, commandRegistry, commandContext, shellPaths, render } = options;
   const globalOnboardingMarker = readOnboardingCheckMarker(shellPaths, 'user');
+
+  // Seeded prompt is always applied synchronously, regardless of session branch.
+  const seededPrompt = cli.flags.prompt ?? (cli.rawCommand === undefined && cli.positionals.length > 0 ? cli.positionals.join(' ') : undefined);
+  if (seededPrompt) {
+    input.prompt = seededPrompt;
+    input.cursorPos = seededPrompt.length;
+  }
+
   if (cli.command === 'onboarding') {
     input.openOnboardingWizard({ mode: 'edit', reset: true });
   } else if (cli.command === 'sessions' && cli.commandArgs[0] === 'resume') {
     const target = cli.commandArgs.slice(1).join(' ').trim();
     if (target) {
-      void commandRegistry.execute('session', ['resume', target], commandContext).then(() => render());
+      return commandRegistry.execute('session', ['resume', target], commandContext).then(() => render());
+    }
+  } else if (cli.flags.continueLast) {
+    // --continue: resume the last session tracked by the pointer file
+    const lastId = readLastSessionPointer({
+      workingDirectory: shellPaths.workingDirectory,
+      homeDirectory: shellPaths.homeDirectory,
+      surfaceRoot: 'tui',
+    });
+    if (lastId) {
+      return commandRegistry.execute('session', ['resume', lastId], commandContext).then(() => render());
+    }
+  } else if (cli.flags.resume !== undefined) {
+    // --resume [id]: explicit id dispatches directly; bare form (sentinel 'latest') resolves via pointer
+    if (cli.flags.resume !== 'latest') {
+      return commandRegistry.execute('session', ['resume', cli.flags.resume], commandContext).then(() => render());
+    } else {
+      const lastId = readLastSessionPointer({
+        workingDirectory: shellPaths.workingDirectory,
+        homeDirectory: shellPaths.homeDirectory,
+        surfaceRoot: 'tui',
+      });
+      if (lastId) {
+        return commandRegistry.execute('session', ['resume', lastId], commandContext).then(() => render());
+      }
+    }
+  } else if (cli.flags.fork !== undefined) {
+    // --fork [id]: fork specific session (true = bare fork-current; string = explicit id to resume then fork)
+    if (cli.flags.fork === true) {
+      // Bare --fork: fork the current session without a prior resume
+      return commandRegistry.execute('session', ['fork'], commandContext).then(() => render());
+    } else {
+      // Explicit id: resume the named session first, then fork
+      return commandRegistry.execute('session', ['resume', cli.flags.fork], commandContext)
+        .then(() => commandRegistry.execute('session', ['fork'], commandContext))
+        .then(() => render());
     }
   } else if (!globalOnboardingMarker.exists) {
     input.openOnboardingWizard({ mode: 'new', reset: true });
-  }
-
-  const seededPrompt = cli.flags.prompt ?? (cli.rawCommand === undefined && cli.positionals.length > 0 ? cli.positionals.join(' ') : undefined);
-  if (seededPrompt) {
-    input.prompt = seededPrompt;
-    input.cursorPos = seededPrompt.length;
+  } else {
+    // User has completed onboarding before but left a wizard session in progress.
+    // Reopen the wizard at the last saved step so they can continue or dismiss.
+    const progressState = readWizardProgress(shellPaths);
+    if (hasResumableWizardProgress(shellPaths, { state: progressState })) {
+      const { payload } = progressState;
+      if (payload !== null) {
+        input.openOnboardingWizard({
+          mode: payload.mode,
+          reset: true,
+          preload: (wizard) => {
+            wizard.setStep(payload.stepIndex);
+            for (const [fieldId, value] of payload.toggleState) wizard.toggleState.set(fieldId, value);
+            for (const [fieldId, value] of payload.radioState) wizard.radioState.set(fieldId, value);
+            for (const [fieldId, value] of payload.textState) wizard.textState.set(fieldId, value);
+          },
+        });
+      }
+    }
   }
 }

package/src/cli/types.ts

@@ -1,3 +1,5 @@
+import type { ConfigManager } from '../config/index.ts';
+
 export type GoodVibesCliCommand =
   | 'tui'
   | 'run'
@@ -53,9 +55,9 @@ export interface GoodVibesCliFlags {
   readonly continueLast: boolean;
   readonly resume: string | undefined;
   readonly session: string | undefined;
-  readonly fork: boolean;
-  readonly rawOutput: boolean;
-  readonly acceptRawOutputRisk: boolean;
+  readonly fork: string | true | undefined;
+  readonly yes: boolean;
+  readonly nonInteractive: boolean;
 }
 
 export interface GoodVibesCliParseResult {
@@ -66,4 +68,13 @@ export interface GoodVibesCliParseResult {
   readonly positionals: readonly string[];
   readonly flags: GoodVibesCliFlags;
   readonly errors: readonly string[];
+  /** Deprecation and soft-warning messages (non-fatal). Callers should surface these to users. */
+  readonly warnings: readonly string[];
+}
+
+export interface CliCommandRuntime {
+  readonly cli: GoodVibesCliParseResult;
+  readonly configManager: ConfigManager;
+  readonly workingDirectory: string;
+  readonly homeDirectory: string;
 }

package/src/cli-flags.ts

@@ -1,6 +1,7 @@
 // Compatibility wrapper for older imports. New CLI code lives in src/cli.
 export type { GoodVibesCliFlags as CliFlags } from './cli/types.ts';
 export {
+  applyRuntimeConfigDefault,
   applyRuntimeConfigOverrides,
   applyRuntimeConfigValue,
   applyRuntimeCommandEndpointFlagOverrides,

package/src/config/atomic-write.ts

@@ -0,0 +1,70 @@
+import { closeSync, fsyncSync, mkdirSync, openSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { dirname } from 'node:path';
+
+export interface AtomicWriteOptions {
+  /**
+   * File permission mode for the written file. Defaults to 0o600 (owner read/write only).
+   */
+  readonly mode?: number;
+  /**
+   * When true, creates parent directories if they do not exist. Defaults to false.
+   */
+  readonly mkdirp?: boolean;
+}
+
+/**
+ * Writes `data` to `path` atomically: writes to a sibling temp file, fsyncs
+ * it, then renames it into place. On POSIX, rename(2) is atomic so readers
+ * always see either the old file or the new file — never a partial write.
+ *
+ * If the write or fsync fails, the temp file is cleaned up before rethrowing.
+ *
+ * @param path   Destination file path.
+ * @param data   UTF-8 string content to write.
+ * @param opts   Optional mode and mkdirp flags.
+ */
+export function atomicWriteFileSync(
+  path: string,
+  data: string,
+  opts: AtomicWriteOptions = {},
+): void {
+  const mode = opts.mode ?? 0o600;
+
+  if (opts.mkdirp) {
+    mkdirSync(dirname(path), { recursive: true });
+  }
+
+  const tmp = `${path}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`;
+
+  try {
+    writeFileSync(tmp, data, { mode });
+
+    // fsync the temp file to flush OS write buffers before rename.
+    const fd = openSync(tmp, 'r+');
+    try {
+      fsyncSync(fd);
+    } finally {
+      closeSync(fd);
+    }
+
+    renameSync(tmp, path);
+
+    // fsync the parent directory to ensure the renamed directory entry is
+    // flushed. Without this, a hard crash immediately after rename could lose
+    // the entry on some filesystems (ext3/ext4 with data=ordered, etc.).
+    const dirFd = openSync(dirname(path), 'r');
+    try {
+      fsyncSync(dirFd);
+    } finally {
+      closeSync(dirFd);
+    }
+  } catch (err) {
+    try {
+      unlinkSync(tmp);
+    } catch {
+      // Best-effort cleanup — original error takes priority.
+    }
+    throw err;
+  }
+}

package/src/config/goodvibes-home-audit.ts

@@ -117,6 +117,8 @@ const KNOWN_DYNAMIC_KEYS = [
   /^featureFlags(?:\.|$)/,
   /^notifications\.webhookUrls$/,
   /^wrfc\.gates$/,
+  // TUI-bridged setting awaiting SDK schema registration (handoff Item 5b)
+  /^tts\.speed$/,
 ];
 
 export const GOODVIBES_ALLOWED_WRITE_ROOTS = ['tui/', 'daemon/'] as const;

package/src/config/read-versioned.ts

@@ -0,0 +1,115 @@
+import { existsSync, readFileSync, renameSync } from 'node:fs';
+
+/**
+ * A migration function that transforms data from version N to N+1.
+ * Receives the raw parsed object and must return the upgraded object.
+ */
+export type VersionMigration = (data: Record<string, unknown>) => Record<string, unknown>;
+
+export interface ReadVersionedOptions {
+  /**
+   * The version number this reader expects. When the file version equals
+   * `currentVersion`, no migrations are run. When it is lower, migrations
+   * are applied stepwise. When it is higher or unrecognised, `onUnknown`
+   * behaviour fires.
+   */
+  readonly currentVersion: number;
+
+  /**
+   * Optional stepwise migrations indexed by the FROM version.
+   * `migrations[1]` upgrades version-1 data to version-2 data.
+   * Applied in ascending order until `currentVersion` is reached.
+   */
+  readonly migrations?: Readonly<Record<number, VersionMigration>>;
+
+  /**
+   * What to do when the file version is unrecognised (higher than
+   * `currentVersion` or missing/non-numeric).
+   *
+   * `'quarantine'` — rename the file to `<path>.unrecognized` and return null.
+   */
+  readonly onUnknown: 'quarantine';
+}
+
+/**
+ * Migration-aware, quarantine-on-failure versioned file reader.
+ *
+ * Parse flow:
+ *   1. If the file does not exist → return null.
+ *   2. If JSON is corrupt → quarantine to `<path>.unrecognized`, return null.
+ *   3. If the version field is missing or higher than currentVersion →
+ *      quarantine, return null.
+ *   4. If the version is lower than currentVersion → apply stepwise migrations.
+ *      If no migration exists for a version gap, or a migration throws,
+ *      quarantine and return null.
+ *   5. Return the (possibly migrated) object. Callers are responsible for
+ *      narrowing the returned value — this helper handles versioning and
+ *      corruption only, not schema validation.
+ */
+export function readVersioned<T extends { version: number }>(
+  path: string,
+  options: ReadVersionedOptions,
+): T | null {
+  if (!existsSync(path)) return null;
+
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(path, 'utf-8'));
+  } catch {
+    quarantine(path);
+    return null;
+  }
+
+  if (!isPlainObject(raw)) {
+    quarantine(path);
+    return null;
+  }
+
+  const fileVersion = raw['version'];
+  if (typeof fileVersion !== 'number' || !Number.isFinite(fileVersion)) {
+    quarantine(path);
+    return null;
+  }
+
+  if (fileVersion > options.currentVersion) {
+    // Produced by a newer process — quarantine rather than corrupt.
+    quarantine(path);
+    return null;
+  }
+
+  let data: Record<string, unknown> = raw;
+
+  if (fileVersion < options.currentVersion) {
+    const migrations = options.migrations ?? {};
+    for (let v = fileVersion; v < options.currentVersion; v++) {
+      const migrate = migrations[v];
+      if (!migrate) {
+        // No migration path for this version gap — quarantine.
+        quarantine(path);
+        return null;
+      }
+      try {
+        data = migrate(data);
+      } catch {
+        quarantine(path);
+        return null;
+      }
+    }
+  }
+
+  return data as T;
+}
+
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function quarantine(path: string): void {
+  try {
+    renameSync(path, `${path}.unrecognized`);
+  } catch {
+    // Best-effort — if rename fails (e.g. race), proceed silently.
+  }
+}