headquarter/openspec/changes/live-git-config-mount-refresh/design.md

Design: Live Git Config Mount Refresh

Canonical source

Each selected Config Profile owns canonical Git clone directories beneath:

<instance-root>/config-profiles/<profile-id>/git-mounts/<identity>/repo

identity is a stable hash of normalized remote URL, requested ref, and credential scope. Sources are deliberately profile-scoped; clones are never shared across users.

Runtime behavior

1. Resolve Git mounts and map them to canonical sources.
2. Acquire an exclusive lock for clone, fetch, ref resolution, and checkout.
3. Clone into a temporary sibling, then rename on initial creation.
4. For refresh, fetch and update the existing working tree in place.
5. Bind directory mappings read-only. Existing containers see changed directory contents without recreation.
6. When profile and Git mount paths overlap, the instance-local composite source must be synchronized in place during refresh; replacing its root directory would leave a running bind mount attached to the old inode.

Boundaries

• URL/ref/source/target/mode changes, direct-file mappings, and changed glob result sets return restart_required.
• Refresh failure is reported without mutating a known-good checkout.
• No non-Git profile content may be copied into a Git checkout; overlapping targets are rejected or reported.
• Containers must not write to shared Git mount sources.
• A browser editor that already has a file open is not a filesystem watcher; the user must reload that editor buffer after the mounted source changes.

Security

Host Git operations use only an authorized server-side credential source. Credentials are not part of the mounted checkout and are not exposed to containers.