Module layout_pin 

XDG layout commitment pin (GL #623 / #624).

paths::single_dir_override re-derives which directory is canonical purely from on-disk markers on every operation. Without a commitment signal a single stray ~/.lean-ctx/<marker> (a legacy residue, a restored backup, a concurrent older binary, a half-finished migration) permanently re-collapses config/data/state/cache back onto that one directory — exactly the “XDG layout not stable” report (GL #623): config stops being found and the graph disappears from the dashboard.

The pin is a tiny layout.toml in the config dir ($XDG_CONFIG_HOME/lean-ctx/layout.toml). It is resolved through the XDG config base directly — never through the single-dir collapse it governs — so it can never depend on the decision it is meant to make (no cycle). Its presence with mode = "xdg" tells the resolver: this install is committed to XDG, so ignore a legacy ~/.lean-ctx / mixed $XDG_CONFIG_HOME data marker.

Determinism (#498): the resolver only ever reads the pin (a pure function of the filesystem). Writes happen at explicit, idempotent call sites (setup, doctor, daemon/server start) and the body is byte-stable.

Functions

ensure_pinned

Pin this install to the XDG layout — but only when it genuinely is XDG:

heal

Self-heal the layout at startup. Idempotent and best-effort:

is_xdg_pinned

Runtime read honoring the same env resolution as the resolver ($XDG_CONFIG_HOME/lean-ctx). Used by doctor/diagnostics.