fix: persistent web link with crash-safe writes, optimistic UI, and race-condition guard

- Add persistentWebLink setting and two IPC handlers (persistCurrentToken / clearPersistentToken)
- Crash-safe write ordering: flag before token on enable, flag before token on disable
- UUID v4 validation of stored tokens in web-server-factory with auto-regeneration fallback
- Optimistic UI updates with stale-request sequence counter scoped inside Zustand closure
- Toggle disabled state (isPersistPending) with aria-busy during IPC round-trip
- clearPersistentToken handler surfaces disk errors via try/catch for renderer rollback
- Shared SettingsStoreInterface extracted to stores/types.ts
- Comprehensive tests: IPC handlers, factory token scenarios, store race-condition rollbacks

Note: silent token regeneration notification is intentionally omitted (out of scope)

Author: jSydorowicz21

src/__tests__/main/ipc/handlers/web.test.ts

@@ -359,14 +359,22 @@ describe('web handlers', () => {
 	});
 
 	describe('live:persistCurrentToken', () => {
-		it('should persist the current server token and enable the flag atomically', async () => {
+		it('should write flag before token for crash safety', async () => {
 			const handler = registeredHandlers.get('live:persistCurrentToken');
 			const result = await handler!({});
 
 			expect(mockWebServer.getSecurityToken).toHaveBeenCalled();
-			expect(mockSettingsStore.set).toHaveBeenCalledWith('webAuthToken', 'mock-security-token');
 			expect(mockSettingsStore.set).toHaveBeenCalledWith('persistentWebLink', true);
+			expect(mockSettingsStore.set).toHaveBeenCalledWith('webAuthToken', 'mock-security-token');
 			expect(result).toEqual({ success: true });
+
+			// Verify crash-safe write order: flag enabled before token.
+			// A crash between the two writes leaves persistentWebLink=true with
+			// a missing token, which the factory handles by generating a fresh UUID.
+			const setCalls = vi.mocked(mockSettingsStore.set).mock.calls;
+			const flagIndex = setCalls.findIndex(([key]) => key === 'persistentWebLink');
+			const tokenIndex = setCalls.findIndex(([key]) => key === 'webAuthToken');
+			expect(flagIndex).toBeLessThan(tokenIndex);
 		});
 
 		it('should return failure when web server is null', async () => {
@@ -390,13 +398,33 @@ describe('web handlers', () => {
 	});
 
 	describe('live:clearPersistentToken', () => {
-		it('should clear both settings atomically', async () => {
+		it('should clear flag before token for crash safety', async () => {
 			const handler = registeredHandlers.get('live:clearPersistentToken');
 			const result = await handler!({});
 
+			// Verify both writes are made
 			expect(mockSettingsStore.set).toHaveBeenCalledWith('persistentWebLink', false);
 			expect(mockSettingsStore.set).toHaveBeenCalledWith('webAuthToken', null);
 			expect(result).toEqual({ success: true });
+
+			// Verify crash-safe write order: flag cleared before token.
+			// A crash between the two writes must leave persistentWebLink=false
+			// so the factory ignores the stale token on next startup.
+			const setCalls = vi.mocked(mockSettingsStore.set).mock.calls;
+			const flagIndex = setCalls.findIndex(([key]) => key === 'persistentWebLink');
+			const tokenIndex = setCalls.findIndex(([key]) => key === 'webAuthToken');
+			expect(flagIndex).toBeLessThan(tokenIndex);
+		});
+
+		it('should return failure when settings write throws', async () => {
+			mockSettingsStore.set.mockImplementationOnce(() => {
+				throw new Error('disk full');
+			});
+
+			const handler = registeredHandlers.get('live:clearPersistentToken');
+			const result = await handler!({});
+
+			expect(result).toEqual({ success: false, message: 'disk full' });
 		});
 	});
 

src/__tests__/main/web-server/web-server-factory.test.ts

@@ -218,7 +218,7 @@ describe('web-server/web-server-factory', () => {
 		});
 
 		it('should use stored token when persistentWebLink is true and token is a valid UUID', () => {
-			const validUuid = '550e8400-e29b-41d4-a716-446655440000';
+			const validUuid = '550e8400-e29b-4bd4-a716-446655440000';
 			vi.mocked(mockSettingsStore.get).mockImplementation((key: string, defaultValue?: any) => {
 				if (key === 'persistentWebLink') return true;
 				if (key === 'webAuthToken') return validUuid;
@@ -245,6 +245,15 @@ describe('web-server/web-server-factory', () => {
 			expect((server as any).securityToken).not.toBe('not-a-valid-uuid');
 			expect((server as any).securityToken).toBeDefined();
 			expect(mockSettingsStore.set).toHaveBeenCalledWith('webAuthToken', expect.any(String));
+			// Token written to settings must match the one given to the server
+			const storedToken = vi
+				.mocked(mockSettingsStore.set)
+				.mock.calls.find(([key]) => key === 'webAuthToken')?.[1];
+			expect((server as any).securityToken).toBe(storedToken);
+			// Generated replacement must be a valid UUID v4
+			expect(storedToken).toMatch(
+				/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+			);
 		});
 
 		it('should generate and store new token when persistentWebLink is true and no token exists', () => {
@@ -261,6 +270,15 @@ describe('web-server/web-server-factory', () => {
 			expect((server as any).securityToken).toBeDefined();
 			expect(typeof (server as any).securityToken).toBe('string');
 			expect(mockSettingsStore.set).toHaveBeenCalledWith('webAuthToken', expect.any(String));
+			// Token written to settings must match the one given to the server
+			const storedToken = vi
+				.mocked(mockSettingsStore.set)
+				.mock.calls.find(([key]) => key === 'webAuthToken')?.[1];
+			expect((server as any).securityToken).toBe(storedToken);
+			// Generated token must be a valid UUID v4
+			expect(storedToken).toMatch(
+				/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+			);
 		});
 	});
 

src/__tests__/renderer/stores/settingsStore.test.ts

@@ -1636,7 +1636,138 @@ describe('settingsStore', () => {
 	});
 
 	// ========================================================================
-	// 13. Non-React Access
+	// 13. setPersistentWebLink race-condition and rollback tests
+	// ========================================================================
+
+	describe('setPersistentWebLink', () => {
+		beforeEach(() => {
+			useSettingsStore.setState({ persistentWebLink: false });
+		});
+
+		it('should optimistically set persistentWebLink to true and call persistCurrentToken', async () => {
+			const { setPersistentWebLink } = useSettingsStore.getState();
+			await setPersistentWebLink(true);
+
+			expect(useSettingsStore.getState().persistentWebLink).toBe(true);
+			expect(window.maestro.live.persistCurrentToken).toHaveBeenCalledOnce();
+		});
+
+		it('should rollback to false on soft IPC failure (result.success === false)', async () => {
+			vi.mocked(window.maestro.live.persistCurrentToken).mockResolvedValueOnce({
+				success: false,
+				message: 'Web server is not running.',
+			});
+
+			const { setPersistentWebLink } = useSettingsStore.getState();
+			await setPersistentWebLink(true);
+
+			expect(useSettingsStore.getState().persistentWebLink).toBe(false);
+		});
+
+		it('should rollback to false on hard IPC failure (thrown exception)', async () => {
+			vi.mocked(window.maestro.live.persistCurrentToken).mockRejectedValueOnce(
+				new Error('IPC timeout')
+			);
+
+			const { setPersistentWebLink } = useSettingsStore.getState();
+			await setPersistentWebLink(true);
+
+			expect(useSettingsStore.getState().persistentWebLink).toBe(false);
+		});
+
+		it('should call clearPersistentToken when disabling', async () => {
+			useSettingsStore.setState({ persistentWebLink: true });
+
+			const { setPersistentWebLink } = useSettingsStore.getState();
+			await setPersistentWebLink(false);
+
+			expect(useSettingsStore.getState().persistentWebLink).toBe(false);
+			expect(window.maestro.live.clearPersistentToken).toHaveBeenCalledOnce();
+		});
+
+		it('should rollback to true on clearPersistentToken hard failure (thrown exception)', async () => {
+			useSettingsStore.setState({ persistentWebLink: true });
+			vi.mocked(window.maestro.live.clearPersistentToken).mockRejectedValueOnce(
+				new Error('IPC timeout')
+			);
+
+			const { setPersistentWebLink } = useSettingsStore.getState();
+			await setPersistentWebLink(false);
+
+			expect(useSettingsStore.getState().persistentWebLink).toBe(true);
+		});
+
+		it('should rollback to true on clearPersistentToken soft failure (result.success === false)', async () => {
+			useSettingsStore.setState({ persistentWebLink: true });
+			vi.mocked(window.maestro.live.clearPersistentToken).mockResolvedValueOnce({
+				success: false,
+				message: 'Settings write failed.',
+			} as any);
+
+			const { setPersistentWebLink } = useSettingsStore.getState();
+			await setPersistentWebLink(false);
+
+			expect(useSettingsStore.getState().persistentWebLink).toBe(true);
+		});
+
+		it('should handle rapid double-toggle (enable then disable) correctly', async () => {
+			// Simulate enable call that resolves slowly
+			let resolveEnable: (value: any) => void;
+			const slowEnable = new Promise((resolve) => {
+				resolveEnable = resolve;
+			});
+			vi.mocked(window.maestro.live.persistCurrentToken).mockReturnValueOnce(slowEnable as any);
+
+			const { setPersistentWebLink } = useSettingsStore.getState();
+
+			// Start enable (will be in-flight)
+			const enablePromise = setPersistentWebLink(true);
+			// Immediately disable (supersedes the enable)
+			const disablePromise = setPersistentWebLink(false);
+
+			// Resolve the slow enable after disable was called
+			resolveEnable!({ success: true });
+
+			await enablePromise;
+			await disablePromise;
+
+			// Final state should reflect the last user intent: disabled
+			expect(useSettingsStore.getState().persistentWebLink).toBe(false);
+			expect(window.maestro.live.clearPersistentToken).toHaveBeenCalled();
+		});
+
+		it('should handle rapid reverse toggle (disable then enable) correctly', async () => {
+			// Start with enabled state
+			useSettingsStore.setState({ persistentWebLink: true });
+
+			// Simulate disable call that resolves slowly
+			let resolveClear: (value: any) => void;
+			const slowClear = new Promise((resolve) => {
+				resolveClear = resolve;
+			});
+			vi.mocked(window.maestro.live.clearPersistentToken).mockReturnValueOnce(slowClear as any);
+
+			const { setPersistentWebLink } = useSettingsStore.getState();
+
+			// Start disable (will be in-flight)
+			const disablePromise = setPersistentWebLink(false);
+			// Immediately re-enable (supersedes the disable)
+			const enablePromise = setPersistentWebLink(true);
+
+			// Resolve the slow clear after enable was called
+			resolveClear!({ success: true });
+
+			await disablePromise;
+			await enablePromise;
+
+			// Final state should reflect the last user intent: enabled
+			expect(useSettingsStore.getState().persistentWebLink).toBe(true);
+			expect(window.maestro.live.persistCurrentToken).toHaveBeenCalled();
+		});
+	});
+
+	// ========================================================================
+	// 14. Non-React Access
 	// ========================================================================
 
 	describe('non-React access', () => {

src/__tests__/setup.ts

@@ -404,6 +404,18 @@ const mockMaestro = {
 		importPlaybook: vi.fn().mockResolvedValue({ success: true, playbook: {}, importedDocs: [] }),
 		onManifestChanged: vi.fn().mockReturnValue(() => {}),
 	},
+	live: {
+		toggle: vi.fn().mockResolvedValue({ live: false, url: null }),
+		getStatus: vi.fn().mockResolvedValue({ live: false, url: null }),
+		getDashboardUrl: vi.fn().mockResolvedValue(null),
+		getLiveSessions: vi.fn().mockResolvedValue([]),
+		broadcastActiveSession: vi.fn().mockResolvedValue(undefined),
+		startServer: vi.fn().mockResolvedValue({ success: true, url: 'http://localhost:3000' }),
+		stopServer: vi.fn().mockResolvedValue({ success: true }),
+		persistCurrentToken: vi.fn().mockResolvedValue({ success: true }),
+		clearPersistentToken: vi.fn().mockResolvedValue({ success: true }),
+		disableAll: vi.fn().mockResolvedValue({ success: true, count: 0 }),
+	},
 	web: {
 		broadcastAutoRunState: vi.fn(),
 		broadcastSessionState: vi.fn(),

src/main/ipc/handlers/web.ts

@@ -13,6 +13,8 @@
  * - live:broadcastActiveSession: Broadcast active session change
  * - live:startServer: Start the web server
  * - live:stopServer: Stop the web server
+ * - live:persistCurrentToken: Persist the running server's token and enable persistent web link
+ * - live:clearPersistentToken: Clear the persisted token and disable persistent web link
  * - live:disableAll: Disable all live sessions and stop server
  * - webserver:getUrl: Get the web server URL
  * - webserver:getConnectedClients: Get connected client count
@@ -261,27 +263,35 @@ export function registerWebHandlers(deps: WebHandlerDependencies): void {
 		}
 	});
 
-	// Persist the current web server's security token and enable persistent web link
-	// Writes both webAuthToken and persistentWebLink atomically on the main side
-	// to prevent inconsistent disk state if the app is force-quit mid-operation
+	// Persist the current web server's security token and enable persistent web link.
+	// Flag is written first: a crash between the two writes leaves
+	// persistentWebLink=true with a missing/stale token, which the factory
+	// handles by generating and persisting a fresh UUID on next startup.
 	ipcMain.handle('live:persistCurrentToken', async () => {
 		const webServer = getWebServer();
 		if (!webServer || !webServer.isActive()) {
 			return { success: false, message: 'Web server is not running.' };
 		}
 		const currentToken = webServer.getSecurityToken();
-		settingsStore.set('webAuthToken', currentToken);
 		settingsStore.set('persistentWebLink', true);
+		settingsStore.set('webAuthToken', currentToken);
 		logger.info('Persisted current web server token and enabled persistent web link', 'WebServer');
 		return { success: true };
 	});
 
-	// Clear persistent web link token and disable the flag atomically on the main side
+	// Clear persistent web link token and disable the flag on the main side.
+	// Flag is cleared first: a crash between the two writes leaves
+	// persistentWebLink=false with a stale token, which the factory ignores.
 	ipcMain.handle('live:clearPersistentToken', async () => {
-		settingsStore.set('persistentWebLink', false);
-		settingsStore.set('webAuthToken', null);
-		logger.info('Cleared persistent web link token and disabled flag', 'WebServer');
-		return { success: true };
+		try {
+			settingsStore.set('persistentWebLink', false);
+			settingsStore.set('webAuthToken', null);
+			logger.info('Cleared persistent web link token and disabled flag', 'WebServer');
+			return { success: true };
+		} catch (error: any) {
+			logger.error(`Failed to clear persistent token: ${error.message}`, 'WebServer');
+			return { success: false, message: error.message };
+		}
 	});
 
 	// Disable all live sessions and stop the server

src/main/stores/types.ts

@@ -159,5 +159,9 @@ export interface AgentSessionOriginsData {
 /** Generic read/write store interface for settings */
 export interface SettingsStoreInterface {
 	get<T>(key: string, defaultValue?: T): T;
-	set(key: string, value: any): void;
+	/** Type-safe set for known settings keys */
+	set<K extends keyof MaestroSettings>(key: K, value: MaestroSettings[K]): void;
+	/** Fallback for dynamic keys — used by the generic settings:set IPC handler
+	 *  in persistence.ts which accepts arbitrary key/value pairs from the renderer */
+	set(key: string, value: unknown): void;
 }

src/main/web-server/WebServer.ts

@@ -117,13 +117,10 @@ export class WebServer {
 		});
 
 		// Use provided token (persistent mode) or generate a new one (ephemeral mode)
-		if (securityToken && securityToken.length > 0) {
+		if (securityToken) {
 			this.securityToken = securityToken;
 			logger.debug('Using persistent security token', LOG_CONTEXT);
 		} else {
-			if (securityToken === '') {
-				logger.warn('Empty security token provided, generating ephemeral token', LOG_CONTEXT);
-			}
 			this.securityToken = randomUUID();
 			logger.debug('Security token generated', LOG_CONTEXT);
 		}

src/main/web-server/web-server-factory.ts

@@ -11,10 +11,12 @@ import { getHistoryManager } from '../history-manager';
 import { logger } from '../utils/logger';
 import { isWebContentsAvailable } from '../utils/safe-send';
 import type { ProcessManager } from '../process-manager';
-import type { StoredSession } from '../stores/types';
+import type { StoredSession, SettingsStoreInterface as SettingsStore } from '../stores/types';
 import type { Group } from '../../shared/types';
 
-import type { SettingsStoreInterface as SettingsStore } from '../stores/types';
+/** UUID v4 format regex for validating stored security tokens.
+ *  Enforces version nibble (4) and variant bits ([89ab]). */
+const UUID_V4_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 
 /** Store interface for sessions */
 interface SessionsStore {
@@ -63,8 +65,7 @@ export function createWebServerFactory(deps: WebServerFactoryDependencies) {
 		if (persistentWebLink) {
 			const storedToken = settingsStore.get<string | null>('webAuthToken', null);
 			// Validate stored token is a proper UUID before trusting it
-			const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-			if (storedToken && UUID_REGEX.test(storedToken)) {
+			if (storedToken && UUID_V4_REGEX.test(storedToken)) {
 				securityToken = storedToken;
 			} else {
 				if (storedToken) {