bug(mcp): a Claude Code write to ~/.claude.json can be lost between gentle-ai's merge and rename

[Denver2828]

Pre-flight Checks

• I have searched existing issues and this is not a duplicate
• I understand this issue needs status:approved before a PR can be opened

Bug Description

La explicacion simple: dos personas editan el mismo documento en papel. Una lo fotocopia, le agrega un parrafo y vuelve a dejar su copia en la mesa. Si la otra escribio algo en el original mientras tanto, ese algo desaparece cuando la copia pisa al original. No importa que rapido fotocopies.. siempre hay un instante donde puede pasar.

Lo tecnico: MergeUserConfig (PR #1909) hace read → merge → re-read → compare → rename atomico sobre ~/.claude.json. El re-read achica la ventana y el lock advisory (PR de la cadena #1868) la CIERRA entre procesos de gentle-ai, porque todos cooperan tomando el mismo lock. Pero Claude Code no toma ningun lock sobre su propio archivo: puede refrescar la sesion OAuth entre el compare final y el rename, y el archivo mergeado (viejo) pisa esa escritura. Con primitivas de filesystem esto no tiene solucion completa.. no existe compare-and-swap atomico sobre archivos contra un escritor que no coopera.

Señalado por @dnlrsls en la review del PR #1909 (punto 2 de la ronda del 29/7). Abro este issue para decidir el diseño en vez de meterlo de contrabando en un PR.

Steps to Reproduce

1. Proceso A: gentle-ai sync entra a MergeUserConfig y pasa el compare final
2. Proceso B: Claude Code escribe ~/.claude.json (refresh de sesion) en ese instante
3. Proceso A: rename atomico pisa la escritura de B

Es una carrera: reproducirla a mano requiere timing, pero la ventana existe en cada sync.

Expected Behavior

Ninguna escritura de Claude Code se pierde. Opciones a discutir:

1. Delegar en el CLI de Claude Code: cuando el binario claude esta disponible, registrar via claude mcp add-json <name> <json> --scope user.. el dueño del archivo hace la escritura y la carrera desaparece. Fallback al merge actual si no esta el binario. Costo: dependencia runtime del CLI y de la estabilidad de sus comandos.
2. Aceptar la ventana documentada: el retry + lock ya cubren gentle-ai vs gentle-ai; la ventana restante contra Claude Code es minima y de bajo impacto (el proximo arranque de Claude Code regenera su estado). Documentarlo y cerrar.
3. Alguna otra que los maintainers prefieran.

Mi voto es la opcion 1 con fallback.. es la unica que elimina la carrera de verdad.

Actual Behavior

Ventana TOCTOU entre compare y rename contra escritores que no toman el lock de gentle-ai.

Operating System

Windows

Agent / Client

Claude Code

Shell

bash (Git Bash)