feat(paths): follow XDG Base Directory Specification

[Sayt-0]

Summary

docker-agent now follows the XDG Base Directory Specification for its config, data and cache directories. This resolves #1638: docker-agent polluted $HOME with ~/.cagent while also creating ~/.config/cagent, and ignored XDG and OS-native conventions.

Resolved locations

XDG_* variables are honoured on every platform (not only Linux), so users who set them, including on macOS, get the location they expect; otherwise the OS-native directory is used.

Dir	Env var (all platforms)	Linux default	macOS default	Windows default
config	XDG_CONFIG_HOME	~/.config/cagent	~/Library/Application Support/cagent	%AppData%\cagent
data	XDG_DATA_HOME	~/.local/share/cagent	~/Library/Application Support/cagent	%LocalAppData%\cagent
cache	XDG_CACHE_HOME	~/.cache/cagent	~/Library/Caches/cagent	%LocalAppData%\cagent

Migration of existing installs

On first run (root PersistentPreRunE), paths.MigrateLegacy() relocates the historical layout:

• ~/.cagent to the data dir
• ~/.config/cagent to the config dir

Properties:

• per-entry os.Rename, merging into the destination without clobbering existing entries (on macOS config and data resolve to the same dir, so a merge is required);
• the legacy directory is removed only once fully drained;
• skipped for any directory overridden via --data-dir/--config-dir/--cache-dir or paths.SetRoot, so embedders (e.g. Gordon) are untouched;
• until migration runs, the getters fall back to the legacy directory, so a failed or skipped move never loses data.

Related fixes exposed by the move

Issue	Before	After
OCI store, models.dev cache, prompt history	hardcoded ~/.cagent	go through the paths package
--session-db default	baked from ~/.cagent/session.db at flag-registration time, ignoring --data-dir	resolved lazily from the data dir, so --data-dir and SetRoot are honoured
sandbox delegation	forwarded --data-dir/--cache-dir into the container (never bind-mounted)	stripped; only the config dir is mounted

Issue #1638 expectations

Expectation	Status
Support the XDG spec	yes, honoured on all platforms
Stop polluting $HOME with ~/.cagent	yes, data moves to the XDG/native data dir
Cross-platform, native conventions (incl. Windows)	yes, OS-native fallback when XDG unset
No data loss for existing installs	yes, one-time merge migration with legacy fallback

Testing

• unit tests: resolution, XDG-env honouring, legacy fallback, migrateDir (move/merge/no-clobber/remove-empty/no-op), MigrateLegacy (default layout, macOS shared-dir collision, override skip), native default, and the --session-db regression;
• go build ./..., go vet, gofmt, golangci-lint clean;
• end-to-end with the real binary: a populated ~/.cagent + ~/.config/cagent were migrated into the XDG/native dir with content intact and the legacy dirs removed;
• sandbox path verified: sbx create mounts the config dir at the resolved XDG path read-only and forwards no data/cache host path.

Note on dependency

This reproduces github.com/adrg/xdg's behaviour in three small helpers rather than taking the dependency (suggested in the issue). Swapping to adrg/xdg is a one-line change per helper if maintainers prefer the library.

[Sayt-0]

Migration hardening

The follow-up commit hardens MigrateLegacy against failure modes the initial implementation did not handle.

Problems addressed

Problem	Before	After
Legacy and XDG dirs on different filesystems	os.Rename fails with EXDEV, migration never happens	crash-safe copy-then-delete fallback
All moves fail after MkdirAll(dst)	empty dst left behind, getters resolve to it and existing state becomes unreachable	dst is removed if created but left empty, so the legacy fallback stays effective
Crash mid-copy	a truncated file under its final name would be treated as already migrated	entries are copied to a reserved .cagent-migrate-* name, fsynced, then renamed atomically; stale temporaries are cleaned up on the next run
Concurrent processes	migrateOnce is per-process only, two instances could interleave moves and deletions	cross-process lock file (flock / LockFileEx) with a bounded wait; a contended run is skipped and retried on next start
Durability	no fsync barrier before removing the source	file contents and the destination dir are synced before the source is deleted
Symlinks, permissions, irregular files	undefined under a copy	modes and symlinks preserved; sockets/FIFOs left in place instead of failing the entry

Properties

• the migration logic moved to its own file (pkg/paths/migrate.go) with platform lock primitives following the existing pkg/cache pattern;
• rename remains the fast path; the copy fallback only kicks in when it fails;
• at any point in time an entry either exists intact at the source or complete at the destination, never partially under its final name.

Testing

• new unit tests: cross-device copy (content, permissions, symlinks), recovery from a crashed mid-copy run, empty-destination regression (legacy fallback stays active), skip under a concurrently held lock and pick-up on the next run;
• go build ./..., go vet, gofmt, golangci-lint clean; cross-compiled for linux and windows.