Summary

Fixes a bug where recompiling the Mac gateway app caused all user configuration settings to be lost. After this fix, gateway settings persist across app rebuilds and partial config updates preserve existing fields.

Problem

Symptoms: When rebuilding the Mac app via swift build, users lost all gateway configuration (auth settings, provider tokens, custom ports, etc.).

Root Causes:

1. Startup overwrite (src/gateway/server.ts:580): The gateway unconditionally called writeConfigFile(migrated) on every launch, overwriting existing user configuration with the migrated version.

2. Partial update stripping (src/gateway/server.ts:1281, 3802): The config.set handler validated partial updates directly with Zod's ClawdisSchema. Since the schema lacked .passthrough() at the top level (only skills.entries had it), validating a partial config stripped away any fields not present in the update payload.

   Example: Updating only { agent: { model: "claude-3" } } would delete gateway.port, telegram.botToken, etc.

Solution

1. Startup fix: Wrap the config write in if (!configSnapshot.exists) so migration only happens on first run. Existing config files are never overwritten at startup.

2. Deep merge for partial updates: Added deepMergeConfig() helper that recursively merges nested objects while preserving existing fields. The config.set handler now merges the partial update with the existing config before validation.

Changes

src/gateway/server.ts

1. New deepMergeConfig() function (lines 528-559): Recursively merges config objects, preserving nested structures. Arrays are replaced entirely (standard config behavior).

2. Startup guard (lines 572-595): Only writes config on first run (!configSnapshot.exists). Logs a warning for legacy configs instead of overwriting.

3. config.set merge fix: add @lid format support and allowFrom wildcard handling #1 (lines 1322-1329): Merges partial update with existing config before validation in the WebSocket-JSON handler.

4. config.set merge Login fails with 'WebSocket Error (socket hang up)' ECONNRESET #2 (lines 3851-3858): Same merge logic in the WebSocket-response handler.

src/gateway/server-utils.test.ts (new file)

8 comprehensive tests covering:

• Shallow object merging
• Nested object deep merging
• Array replacement behavior
• Null/undefined handling
• Empty objects
• Full config.set partial update simulation

Test Plan

• pnpm test --run server-utils.test.ts - 8 tests passed
• pnpm build - TypeScript build succeeded
• Manual: After merge, rebuild Mac app and confirm settings persist

Technical Details

Why not add .passthrough() to ClawdisSchema?

The schema is defined without .passthrough() intentionally to enforce strict validation. Adding it would allow arbitrary fields through, potentially masking misconfigurations. The deep merge approach preserves the existing strict validation while adding the missing preservation behavior.

Deep merge semantics:

• Objects: Recursively merged (target overrides base)
• Arrays: Replaced entirely (target array becomes the new array)
• Primitives: Target value replaces base value
• null/undefined: Handled per standard merge rules

Related Issues

This is the config preservation portion of the work from closed PRs #141, #142, #145, #146. Those PRs were monolithic (1000+ lines) and overlapped with other features. This is the minimal, atomic fix for just the config preservation issue.