@pellux/goodvibes-tui 0.20.3 → 0.22.0

package/src/runtime/bootstrap-core.ts

@@ -29,7 +29,59 @@ import { registerBootstrapHookBridge } from '@/runtime/index.ts';
 import { registerBootstrapRuntimeEvents } from '@/runtime/index.ts';
 import { createRuntimeServices, type RuntimeServices } from './services.ts';
 import { createUiRuntimeServices, type UiRuntimeServices } from './ui-services.ts';
+import { join } from 'node:path';
 import { installWrfcAgentToolGuard } from '../tools/wrfc-agent-guard.ts';
+import { createWrfcPersistence, type WrfcPersistence } from './wrfc-persistence.ts';
+import type { SystemMessagePriority } from '../panels/system-messages-panel.ts';
+
+// ---------------------------------------------------------------------------
+// Pre-router buffer
+// ---------------------------------------------------------------------------
+
+const PRE_ROUTER_BUFFER_MAX = 100;
+
+type BufferedWrfcMessage = {
+  readonly message: string;
+  readonly priority: SystemMessagePriority;
+};
+
+/**
+ * Small bounded queue that accumulates WRFC system messages emitted before
+ * the SystemMessageRouter is attached. On attach the queue flushes in order.
+ * If the queue overflows (> PRE_ROUTER_BUFFER_MAX), the oldest entries are
+ * dropped and a summary message is prepended to the first flushed message.
+ */
+export class WrfcPreRouterBuffer {
+  private readonly queue: BufferedWrfcMessage[] = [];
+  private overflowCount = 0;
+
+  push(message: string, priority: SystemMessagePriority): void {
+    if (this.queue.length >= PRE_ROUTER_BUFFER_MAX) {
+      this.queue.shift();
+      this.overflowCount++;
+    }
+    this.queue.push({ message, priority });
+  }
+
+  flush(router: import('../core/system-message-router.ts').SystemMessageRouter): void {
+    const dropped = this.overflowCount;
+    const pending = this.queue.splice(0);
+    this.overflowCount = 0;
+    if (dropped > 0) {
+      router.wrfc(
+        `[WRFC] Pre-router buffer overflowed: ${dropped} earliest message${dropped !== 1 ? 's' : ''} were dropped`,
+        'low',
+      );
+    }
+    for (const item of pending) {
+      router.wrfc(item.message, item.priority);
+    }
+  }
+
+  get size(): number {
+    return this.queue.length;
+  }
+}
 
 export interface BootstrapCoreState {
   readonly userSessionId: string;
@@ -62,6 +114,11 @@ export interface BootstrapCoreState {
   readonly requestRender: () => void;
   readonly setRenderRequest: (fn: () => void) => void;
   readonly runtimeSessionIdRef: { value: string };
+  /**
+   * WRFC chain persistence — call `rehydrate()` once after the SystemMessageRouter
+   * is wired so interrupted chains from a previous process are surfaced to the operator.
+   */
+  readonly wrfcPersistence: WrfcPersistence;
 }
 
 export type CompanionMessagePayload = Extract<SessionEvent, { type: 'COMPANION_MESSAGE_RECEIVED' }>;
@@ -222,9 +279,9 @@ export async function initializeBootstrapCore(
     overflowHandler: services.overflowHandler,
     changeTracker: services.sessionChangeTracker,
   });
-  installWrfcAgentToolGuard(toolRegistry, {
-    getLastUserMessage: () => conversation.getLastUserMessage(),
-  });
+  // Note: installWrfcAgentToolGuard is called after routeOrBuffer is defined
+  // (further below) so the onTrace callback can route guard decisions through
+  // the pre-router buffer.
   services.agentOrchestrator.setDependencies({
     surfaceRoot: 'tui',
     fileCache,
@@ -305,7 +362,26 @@ export async function initializeBootstrapCore(
   void approvalBroker.start();
   void sharedSessionBroker.start();
   const runtimeSessionIdRef = { value: userSessionId };
-  const systemMessageRouterRef: { value: SystemMessageRouter | null } = { value: null };
+  const wrfcBuffer = new WrfcPreRouterBuffer();
+  // Smart ref: setting .value auto-flushes the pre-router buffer so events
+  // buffered before the SystemMessageRouter attaches are not permanently lost.
+  const systemMessageRouterRef = ((): { value: SystemMessageRouter | null } => {
+    let _value: SystemMessageRouter | null = null;
+    const ref = {} as { value: SystemMessageRouter | null };
+    Object.defineProperty(ref, 'value', {
+      get(): SystemMessageRouter | null { return _value; },
+      set(router: SystemMessageRouter | null): void {
+        _value = router;
+        if (router && wrfcBuffer.size > 0) {
+          wrfcBuffer.flush(router);
+          requestRender();
+        }
+      },
+      enumerable: true,
+      configurable: true,
+    });
+    return ref;
+  })();
   const conversationFollowUpRef: { value: ((item: ConversationFollowUpItem) => void) | null } = { value: null };
   const { unsubs: runtimeUnsubs, agentStatusIntervalRef } = registerBootstrapRuntimeEvents({
     runtimeBus,
@@ -318,21 +394,69 @@ export async function initializeBootstrapCore(
     wrfcController: services.wrfcController,
   });
 
+  // ── WRFC chain persistence ──────────────────────────────────────────────────────────
+  const wrfcPersistence = createWrfcPersistence({
+    snapshotPath: join(workingDir, '.goodvibes', 'tui', 'wrfc-chains.json'),
+    getSystemMessageRouter: () => systemMessageRouterRef.value,
+    controller: services.wrfcController,
+  });
+  runtimeUnsubs.push(...wrfcPersistence.attach(runtimeBus));
+  // Flush any debounced snapshot on clean shutdown so final chain state is
+  // never silently dropped during a SIGINT/teardown (250ms debounce window).
+  bootstrapUnsubs.push(() => wrfcPersistence.flush());
+
   // ── TUI-specific WRFC constraint-propagation event subscriptions (SDK 0.23.0) ──
   // These supplement the SDK's registerBootstrapRuntimeEvents which handles the
   // core WORKFLOW_REVIEW_COMPLETED / WORKFLOW_CHAIN_CREATED messages.
   // The SDK does not surface constraint-specific system messages; the TUI layer
   // adds them here so operators can observe constraint enumeration and violations
   // in the SystemMessagesPanel and main conversation.
+  //
+  // Pre-router buffering: events that arrive before the SystemMessageRouter is
+  // attached are held in wrfcBuffer (bounded, 100 entries). When the router is
+  // set on systemMessageRouterRef, the smart setter flushes the buffer in order.
+  // If the buffer overflows, the oldest entries are dropped and a summary message
+  // is prepended to the first flushed batch.
+  const routeOrBuffer = (message: string, priority: SystemMessagePriority): void => {
+    const router = systemMessageRouterRef.value;
+    if (router) {
+      router.wrfc(message, priority);
+    } else {
+      wrfcBuffer.push(message, priority);
+    }
+  };
+
+  // Startup TLS banner — emitted via wrfcBuffer.push() because the
+  // SystemMessageRouter is not attached yet at this point in bootstrap. The
+  // smart-ref setter on systemMessageRouterRef auto-flushes the buffer when
+  // the router attaches, so the message will appear in the WRFC panel on startup.
+  {
+    const cpEnabled = Boolean(configManager.get('controlPlane.enabled'));
+    const cpHostMode = String(configManager.get('controlPlane.hostMode') ?? 'local');
+    const cpTlsMode = String(configManager.get('controlPlane.tls.mode') ?? 'off');
+    const hlEnabled = Boolean(configManager.get('danger.httpListener'));
+    const hlHostMode = String(configManager.get('httpListener.hostMode') ?? 'local');
+    const hlTlsMode = String(configManager.get('httpListener.tls.mode') ?? 'off');
+    const cpNetworkPlaintext = cpEnabled && cpHostMode !== 'local' && cpTlsMode === 'off';
+    const hlNetworkPlaintext = hlEnabled && hlHostMode !== 'local' && hlTlsMode === 'off';
+    if (cpNetworkPlaintext || hlNetworkPlaintext) {
+      const affected: string[] = [];
+      if (cpNetworkPlaintext) affected.push('control plane');
+      if (hlNetworkPlaintext) affected.push('HTTP listener');
+      wrfcBuffer.push(
+        `[SECURITY] TLS is off for the ${affected.join(' and ')} but it is network-reachable. All traffic (credentials, tokens, conversation content) travels in plaintext. Enable TLS (controlPlane.tls.mode / httpListener.tls.mode) or restrict to loopback before exposing to untrusted networks.`,
+        'high',
+      );
+    }
+  }
+
   runtimeUnsubs.push(
     runtimeBus.on<Extract<import('@/runtime/index.ts').WorkflowEvent, { type: 'WORKFLOW_CONSTRAINTS_ENUMERATED' }>>(
       'WORKFLOW_CONSTRAINTS_ENUMERATED',
       ({ payload }) => {
-        const router = systemMessageRouterRef.value;
-        if (!router) return;
         const count = payload.constraints.length;
         if (count > 0) {
-          router.wrfc(
+          routeOrBuffer(
             `[WRFC] Engineer enumerated ${count} constraint${count !== 1 ? 's' : ''} for chain ${payload.chainId.slice(0, 12)}`,
             'low',
           );
@@ -345,11 +469,9 @@ export async function initializeBootstrapCore(
     runtimeBus.on<Extract<import('@/runtime/index.ts').WorkflowEvent, { type: 'WORKFLOW_FIX_ATTEMPTED' }>>(
       'WORKFLOW_FIX_ATTEMPTED',
       ({ payload }) => {
-        const router = systemMessageRouterRef.value;
-        if (!router) return;
         const targetIds = payload.targetConstraintIds;
         if (targetIds && targetIds.length > 0) {
-          router.wrfc(
+          routeOrBuffer(
             `[WRFC] Fix #${payload.attempt} targeting ${targetIds.length} constraint${targetIds.length !== 1 ? 's' : ''} on chain ${payload.chainId.slice(0, 12)}`,
             'low',
           );
@@ -362,11 +484,9 @@ export async function initializeBootstrapCore(
     runtimeBus.on<Extract<import('@/runtime/index.ts').WorkflowEvent, { type: 'WORKFLOW_REVIEW_COMPLETED' }>>(
       'WORKFLOW_REVIEW_COMPLETED',
       ({ payload }) => {
-        const router = systemMessageRouterRef.value;
-        if (!router) return;
         const unsatisfied = payload.unsatisfiedConstraintIds;
         if (!payload.passed && unsatisfied && unsatisfied.length > 0) {
-          router.wrfc(
+          routeOrBuffer(
             `[WRFC] ✗ Chain ${payload.chainId.slice(0, 12)}: ${unsatisfied.length} constraint violation${unsatisfied.length !== 1 ? 's' : ''} forced failure`,
             'high',
           );
@@ -376,6 +496,17 @@ export async function initializeBootstrapCore(
     ),
   );
 
+  // Wire the WRFC agent-guard with the onTrace callback so routing decisions are
+  // observable via the same routeOrBuffer path as WORKFLOW_* events.
+  // Placed here (after routeOrBuffer is defined) so the closure is fully wired.
+  installWrfcAgentToolGuard(toolRegistry, {
+    getLastUserMessage: () => conversation.getLastUserMessage(),
+    onTrace: ({ kind, reason, task }) => {
+      const shortTask = task.length > 80 ? `${task.slice(0, 77)}...` : task;
+      routeOrBuffer(`[WRFC] Guard: ${reason} — task: "${shortTask}" (${kind})`, 'low');
+    },
+  });
+
   // Subscribe to companion main-chat messages received from the daemon's HTTP layer.
   // The daemon emits COMPANION_MESSAGE_RECEIVED on the runtime bus when a companion
   // POST /api/sessions/:id/messages with kind='message' arrives.
@@ -535,5 +666,6 @@ export async function initializeBootstrapCore(
       renderRequestRef.value = fn;
     },
     runtimeSessionIdRef,
+    wrfcPersistence,
   };
 }

package/src/runtime/bootstrap-shell.ts

@@ -40,6 +40,11 @@ export interface BootstrapShellState {
   readonly lastGitInfoRef: { value: GitHeaderInfo | undefined };
   readonly inputHistory: InputHistory;
   readonly systemMessageRouter: SystemMessageRouter;
+  /**
+   * Wire the agent detail modal opener after InputHandler is constructed.
+   * Call with `(id) => input.agentDetailModal.open(id)` from main.ts.
+   */
+  readonly setOpenAgentDetail: (fn: (agentId: string) => void) => void;
 }
 
 export interface BootstrapShellOptions {
@@ -103,6 +108,8 @@ export function createBootstrapShell(options: BootstrapShellOptions): BootstrapS
     providerRegistry: services.providerRegistry,
   });
 
+  const openAgentDetailRef: { fn: (agentId: string) => void } = { fn: (_agentId: string) => {} };
+
   let commandContextRef: CommandContext | null = null;
   registerBuiltinPanels(services.panelManager, {
     configManager,
@@ -143,6 +150,7 @@ export function createBootstrapShell(options: BootstrapShellOptions): BootstrapS
     hookActivityTracker: services.hookActivityTracker,
     hookWorkbench: services.hookWorkbench,
     mcpRegistry: services.mcpRegistry,
+    openAgentDetail: (agentId: string) => openAgentDetailRef.fn(agentId),
     daemonHomeDir: join(services.homeDirectory, '.goodvibes', 'daemon'),
   });
   services.panelManager.prewarmRegistered();
@@ -278,5 +286,8 @@ export function createBootstrapShell(options: BootstrapShellOptions): BootstrapS
     lastGitInfoRef,
     inputHistory,
     systemMessageRouter,
+    setOpenAgentDetail: (fn: (agentId: string) => void) => {
+      openAgentDetailRef.fn = fn;
+    },
   };
 }

package/src/runtime/bootstrap.ts

@@ -118,6 +118,11 @@ export type BootstrapContext = RuntimeContext & {
    * stay out of the main conversation and go to the SystemMessagesPanel instead.
    */
   systemMessageRouter: SystemMessageRouter;
+  /**
+   * Wire the agent detail modal opener after InputHandler is constructed in main.ts.
+   * Call with `(id) => input.agentDetailModal.open(id)` once the InputHandler is ready.
+   */
+  setOpenAgentDetail: (fn: (agentId: string) => void) => void;
 };
 
 // ── Bootstrap function ────────────────────────────────────────────────────
@@ -180,6 +185,7 @@ export async function bootstrapRuntime(
     requestRender,
     setRenderRequest,
     runtimeSessionIdRef,
+    wrfcPersistence,
   } = await initializeBootstrapCore(stdout, options, (limit) => controlPlaneRecentEventsRef.value(limit));
   const providerRegistry = services.providerRegistry;
   const {
@@ -285,11 +291,13 @@ export async function bootstrapRuntime(
   });
   const systemMessageRouter = shell.systemMessageRouter;
   systemMessageRouterRef.value = systemMessageRouter;
+  wrfcPersistence.rehydrate();
   const commandRegistry = shell.commandRegistry;
   const commandContext = shell.commandContext;
   const gitStatusProvider = shell.gitStatusProvider;
   const inputHistory = shell.inputHistory;
   const lastGitInfoRef = shell.lastGitInfoRef;
+  const setOpenAgentDetail = shell.setOpenAgentDetail;
   const pluginCommandRegistry = {
     register(command: {
       readonly name: string;
@@ -620,6 +628,7 @@ export async function bootstrapRuntime(
     _getConfiguredProviderIds: () => services.providerRegistry.getConfiguredProviderIds(),
     commandRegistry,
     systemMessageRouter,
+    setOpenAgentDetail,
     shutdown: async (sessionData) => {
       // Clear bootstrap-owned subscriptions
       bootstrapUnsubs.forEach(fn => fn());

package/src/runtime/onboarding/apply.ts

@@ -1,5 +1,5 @@
-import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
-import { dirname } from 'node:path';
+import { existsSync, readFileSync, unlinkSync } from 'node:fs';
+import { atomicWriteFileSync } from '../../config/atomic-write.ts';
 import { isSecretRefInput } from '@pellux/goodvibes-sdk/platform/config';
 import { CONFIG_SCHEMA, DEFAULT_CONFIG } from '../../config/index.ts';
 import type { FeatureFlagConfigKey } from '../surface-feature-flags.ts';
@@ -34,8 +34,7 @@ function readJsonObject(path: string): Record<string, unknown> {
 }
 
 function writeJsonObject(path: string, payload: Record<string, unknown>): void {
-  mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, `${JSON.stringify(payload, null, 2)}\n`, 'utf-8');
+  atomicWriteFileSync(path, `${JSON.stringify(payload, null, 2)}\n`, { mkdirp: true });
 }
 
 function setNestedValue(root: Record<string, unknown>, key: string, value: unknown): Record<string, unknown> {
@@ -76,8 +75,7 @@ function restoreFile(path: string, previous: string | null, reload?: () => void)
   if (previous === null) {
     if (existsSync(path)) unlinkSync(path);
   } else {
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, previous, 'utf-8');
+    atomicWriteFileSync(path, previous, { mkdirp: true });
   }
   reload?.();
 }

package/src/runtime/onboarding/index.ts

@@ -5,3 +5,4 @@ export * from './apply.ts';
 export * from './verify.ts';
 export * from './markers.ts';
 export * from './state.ts';
+export * from './progress.ts';

package/src/runtime/onboarding/markers.ts

@@ -1,5 +1,7 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname } from 'node:path';
+import { existsSync } from 'node:fs';
+import { atomicWriteFileSync } from '@/config/atomic-write.ts';
+import { readVersioned } from '@/config/read-versioned.ts';
+
 import type { ShellPathService } from '@/runtime/index.ts';
 import type {
   OnboardingCheckMarkerPayload,
@@ -25,50 +27,34 @@ function resolveMarkerPath(
     : shellPaths.resolveUserPath('tui', ONBOARDING_CHECK_MARKER_FILE);
 }
 
-function isObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null;
-}
-
-function isOnboardingMode(value: unknown): value is OnboardingCheckMarkerPayload['mode'] {
-  return value === 'new' || value === 'edit' || value === 'reopen';
-}
-
 function isCheckMarkerPayload(value: unknown): value is OnboardingCheckMarkerPayload {
-  return isObject(value)
-    && value.version === 1
-    && typeof value.checkedAt === 'number'
-    && Number.isFinite(value.checkedAt)
-    && typeof value.updatedAt === 'number'
-    && Number.isFinite(value.updatedAt)
-    && typeof value.source === 'string'
-    && (value.mode === undefined || isOnboardingMode(value.mode))
-    && (value.workspaceRoot === undefined || typeof value.workspaceRoot === 'string');
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const v = value as Record<string, unknown>;
+  return (
+    v['version'] === 1
+    && typeof v['checkedAt'] === 'number'
+    && Number.isFinite(v['checkedAt'] as number)
+    && typeof v['updatedAt'] === 'number'
+    && Number.isFinite(v['updatedAt'] as number)
+    && typeof v['source'] === 'string'
+    && (v['mode'] === undefined || v['mode'] === 'new' || v['mode'] === 'edit' || v['mode'] === 'reopen')
+    && (v['workspaceRoot'] === undefined || typeof v['workspaceRoot'] === 'string')
+  );
 }
 
 function buildMissingMarkerState(
   scope: OnboardingStateScope,
   path: string,
 ): OnboardingCheckMarkerState {
-  return {
-    scope,
-    path,
-    exists: false,
-    payload: null,
-  };
+  return { scope, path, exists: false, payload: null };
 }
 
-function buildParseErrorState(
+function buildErrorMarkerState(
   scope: OnboardingStateScope,
   path: string,
   parseError: string,
 ): OnboardingCheckMarkerState {
-  return {
-    scope,
-    path,
-    exists: true,
-    payload: null,
-    parseError,
-  };
+  return { scope, path, exists: true, payload: null, parseError };
 }
 
 function pickEffectiveMarker(
@@ -91,24 +77,32 @@ export function readOnboardingCheckMarker(
   scope: OnboardingStateScope = 'user',
 ): OnboardingCheckMarkerState {
   const path = resolveMarkerPath(shellPaths, scope);
-  if (!existsSync(path)) return buildMissingMarkerState(scope, path);
-
-  try {
-    const parsed = JSON.parse(readFileSync(path, 'utf-8')) as unknown;
-    if (!isCheckMarkerPayload(parsed)) {
-      return buildParseErrorState(scope, path, 'Invalid onboarding check marker payload.');
-    }
 
-    return {
+  const parsed = readVersioned<OnboardingCheckMarkerPayload & { version: number }>(
+    path,
+    { currentVersion: 1, onUnknown: 'quarantine' },
+  );
+
+  if (parsed === null) {
+    // readVersioned returns null for: missing, corrupt JSON, or unrecognised
+    // version (renamed to <path>.unrecognized).
+    const nowExists = existsSync(path);
+    const quarantined = existsSync(`${path}.unrecognized`);
+    if (!nowExists && !quarantined) return buildMissingMarkerState(scope, path);
+    return buildErrorMarkerState(
       scope,
       path,
-      exists: true,
-      payload: parsed,
-    };
-  } catch (error) {
-    const parseError = error instanceof Error ? error.message : String(error);
-    return buildParseErrorState(scope, path, parseError);
+      quarantined
+        ? 'Unrecognised or corrupt marker file; quarantined.'
+        : 'Invalid onboarding check marker payload.',
+    );
+  }
+
+  if (!isCheckMarkerPayload(parsed)) {
+    return buildErrorMarkerState(scope, path, 'Invalid onboarding check marker payload.');
   }
+
+  return { scope, path, exists: true, payload: parsed };
 }
 
 export function readOnboardingCheckMarkers(
@@ -140,8 +134,7 @@ export function writeOnboardingCheckMarker(
     ...(options.workspaceRoot ? { workspaceRoot: options.workspaceRoot } : {}),
   };
 
-  mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, `${JSON.stringify(payload, null, 2)}\n`, 'utf-8');
+  atomicWriteFileSync(path, `${JSON.stringify(payload, null, 2)}\n`, { mkdirp: true });
 
   return readOnboardingCheckMarker(shellPaths, scope);
 }

package/src/runtime/onboarding/progress.ts

@@ -0,0 +1,148 @@
+import { existsSync, unlinkSync } from 'node:fs';
+import { atomicWriteFileSync } from '@/config/atomic-write.ts';
+import { readVersioned } from '@/config/read-versioned.ts';
+
+import type {
+  OnboardingMode,
+  OnboardingShellPaths,
+  WizardProgressPayload,
+  WizardProgressState,
+} from './types.ts';
+
+const WIZARD_PROGRESS_FILE = 'onboarding-progress.json';
+
+function resolveProgressPath(shellPaths: OnboardingShellPaths): string {
+  return shellPaths.resolveUserPath('tui', WIZARD_PROGRESS_FILE);
+}
+
+function isWizardProgressPayload(value: unknown): value is WizardProgressPayload {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const v = value as Record<string, unknown>;
+  if (v['version'] !== 1) return false;
+  if (typeof v['savedAt'] !== 'number' || !Number.isFinite(v['savedAt'] as number)) return false;
+  const mode = v['mode'];
+  if (mode !== 'new' && mode !== 'edit' && mode !== 'reopen') return false;
+  if (typeof v['stepIndex'] !== 'number' || !Number.isFinite(v['stepIndex'] as number)) return false;
+  if (!Array.isArray(v['toggleState'])) return false;
+  if (!Array.isArray(v['radioState'])) return false;
+  if (!Array.isArray(v['textState'])) return false;
+  return true;
+}
+
+/**
+ * Path to the wizard progress file (user-scoped, in ~/.config/goodvibes/tui/).
+ */
+export function getWizardProgressPath(shellPaths: OnboardingShellPaths): string {
+  return resolveProgressPath(shellPaths);
+}
+
+/**
+ * Read the persisted wizard progress, if any.
+ *
+ * Returns a WizardProgressState with exists=false when no progress file is
+ * present. Returns exists=true, payload=null with a parseError when the file
+ * is present but unreadable or schema-mismatched (the bad file is left in
+ * place so the caller can decide whether to delete it).
+ */
+export function readWizardProgress(shellPaths: OnboardingShellPaths): WizardProgressState {
+  const path = resolveProgressPath(shellPaths);
+
+  const parsed = readVersioned<WizardProgressPayload & { version: number }>(
+    path,
+    { currentVersion: 1, onUnknown: 'quarantine' },
+  );
+
+  if (parsed === null) {
+    const nowExists = existsSync(path);
+    const quarantined = existsSync(`${path}.unrecognized`);
+    if (!nowExists && !quarantined) return { path, exists: false, payload: null };
+    return {
+      path,
+      exists: true,
+      payload: null,
+      parseError: quarantined
+        ? 'Unrecognised or corrupt wizard progress file; quarantined.'
+        : 'Invalid wizard progress payload.',
+    };
+  }
+
+  if (!isWizardProgressPayload(parsed)) {
+    return { path, exists: true, payload: null, parseError: 'Invalid wizard progress payload.' };
+  }
+
+  return { path, exists: true, payload: parsed };
+}
+
+export interface WriteWizardProgressOptions {
+  readonly mode: OnboardingMode;
+  readonly stepIndex: number;
+  readonly toggleState: ReadonlyArray<readonly [string, boolean]>;
+  readonly radioState: ReadonlyArray<readonly [string, string]>;
+  readonly textState: ReadonlyArray<readonly [string, string]>;
+  readonly clock?: () => number;
+}
+
+/**
+ * Atomically persist wizard progress to disk.
+ *
+ * Uses atomicWriteFileSync (write-to-tmp + rename) so a crash mid-write
+ * never leaves a torn file. The file is user-scoped so it survives across
+ * project switches and is shared with the resume-prompt check at startup.
+ *
+ * Masked (password) fields are deliberately excluded from the serialised
+ * textState by the caller — this function accepts whatever is passed in and
+ * does NOT filter. Callers must strip sensitive fields before calling.
+ */
+export function writeWizardProgress(
+  shellPaths: OnboardingShellPaths,
+  options: WriteWizardProgressOptions,
+): void {
+  const path = resolveProgressPath(shellPaths);
+  const payload: WizardProgressPayload = {
+    version: 1,
+    savedAt: (options.clock ?? Date.now)(),
+    mode: options.mode,
+    stepIndex: options.stepIndex,
+    toggleState: options.toggleState,
+    radioState: options.radioState,
+    textState: options.textState,
+  };
+  atomicWriteFileSync(path, `${JSON.stringify(payload, null, 2)}\n`, { mkdirp: true });
+}
+
+/**
+ * Delete the wizard progress file (best-effort; ignores ENOENT).
+ *
+ * Called after a successful apply so the resume prompt is not shown on
+ * next startup.
+ */
+export function deleteWizardProgress(shellPaths: OnboardingShellPaths): void {
+  const path = resolveProgressPath(shellPaths);
+  try { unlinkSync(path); } catch { /* best-effort: file may not exist */ }
+}
+
+/**
+ * Returns true when an in-progress wizard session was interrupted and is
+ * still recent enough to reopen on startup (the caller reopens the wizard
+ * at the saved step so the user can continue or dismiss it).
+ *
+ * A progress file is considered resumable when:
+ *   - it exists and can be parsed (payload !== null)
+ *   - it is less than PROGRESS_MAX_AGE_MS old (default: 7 days)
+ *
+ * Negative age (future-dated `savedAt`) is treated as non-resumable: it
+ * indicates clock skew or a tampered file and is safer to reject than to
+ * open a wizard with unknown-age state.
+ */
+const PROGRESS_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+
+export function hasResumableWizardProgress(
+  shellPaths: OnboardingShellPaths,
+  options: { now?: number; state?: WizardProgressState } = {},
+): boolean {
+  const state = options.state ?? readWizardProgress(shellPaths);
+  if (!state.payload) return false;
+  const age = (options.now ?? Date.now()) - state.payload.savedAt;
+  // age < 0 means savedAt is in the future (clock skew / tampered file) — treat as non-resumable.
+  return age >= 0 && age < PROGRESS_MAX_AGE_MS;
+}