Summary

Fixes #1881 — gbrain sync --strategy code deleted a user's live git working tree.

The bug: recloneIfMissing (src/core/sources-ops.ts) deleted local_path whenever a source had a remote_url and a non-healthy on-disk state, with no check that gbrain actually created the clone. A source whose local_path pointed at a user's working tree (the federated shape a remote_url + external path produces) could have its directory removed and re-cloned over.

The fix — ownership, not path-containment:

• isOwnedClone() — gbrain re-clones/deletes only a clone it created, proven by a config.managed_clone marker (written by addSource --url) or exact normalized-path equality with defaultCloneDir(id) (back-compat for pre-marker default-location clones). Everything else is fail-closed (refused).
• recloneIfMissing — ownership guard aborts before any filesystem op (new unmanaged_path SourceOpError); EXDEV-safe sibling-temp clone + atomic swap (old aside → new in → drop old) with best-effort restore and an error that names where the original is preserved; symlink-leaf reject before the destructive rename.
• sync.ts validate_repo_state guards the reclone on isOwnedClone (no per-sync warning — surfacing lives in a follow-up doctor check).
• sources restore degrades to a warning for an unowned source instead of the misleading "missing clone, try sync" hint.

Reported by @zaqwery. The ownership-invariant correction came out of a cross-model plan + diff review (Codex outside-voice).

Test Coverage

isOwnedClone(5 branches) · unownedHint(healthy/degraded) · recloneIfMissing
(entry guard, sibling-temp clone, symlink-leaf reject, aside swap, residue-free
cleanup) · addSource marker · --clone-dir owned-via-marker · sync-level refusal ·
restore CV3 — all tested with side-effect assertions (working-tree + sentinel
survival, symlink-target survival, no swap residue).

AI-assessed coverage of the changed paths: 85% (gate PASS). The 2 untested branches are a deliberately-defensive unreachable TOCTOU re-check and a hard-to-provoke rename-failed restore catch.

Pre-Landing Review

Pre-landing review: ship as-is (no issues). Claude + Codex adversarial both flagged one item (lexical resolvePath ownership + symlinked clones-ancestor). Investigated: the proposed realpath-chain fix false-positives on system symlinks (macOS /var→/private/var) and doesn't address the real residual, which is DB-trust (a forged managed_clone marker), not path confusion — for an owned clone gbrain created the dir there (cloneRepo refuses a non-empty dest). Kept the leaf-symlink TOCTOU guard, improved the failed-swap message to name the preserved original, and filed the residual as a P2 TODO (CI guard that only addSource writes the marker + an on-disk ownership stamp).

Design Review

No frontend files changed — design review skipped.

Eval Results

No prompt-related files changed — evals skipped.

Plan Completion

All plan items DONE (eng-review plan + all accepted CV findings). Plan + GSTACK REVIEW REPORT at ~/.claude/plans/.

Verification Results

No dev server / web UI — CLI tool. Verified via the unit suite and the #1881 repro encoded as a regression test (federated row → throws unmanaged_path, working tree + sentinel survive).

TODOS

Filed 5 follow-ups (gbrain#1881 section): doctor misconfig check (P2), harden managed_clone against forgery + on-disk stamp (P2), .gbrain-reclone-* orphan sweep (P3), --clone-dir policy / dormant clone_dir_outside_gbrain (P3), CLI sources remove clone-storage leak (P3).

Documentation

• docs/architecture/KEY_FILES.md: added the missing src/core/sources-ops.ts entry capturing the v0.42.33.0 (gbrain sync --strategy code deleted the working directory (federated source with local_path, no --url) #1881) reclone-ownership invariant — gbrain only deletes/re-clones a clone it created (isOwnedClone: config.managed_clone marker or defaultCloneDir exact-match), never a user working tree. Covers the fail-closed unmanaged_path SourceOpError, EXDEV-safe sibling-temp swap, TOCTOU + symlink-leaf guards, shared unownedHint, and the read-only gbrain sources restore path.

Test plan

• Affected suites: 72 pass / 0 fail (sources-ops, sources-resync-recovery, sources-mcp)
• Full unit suite: 10073 pass; typecheck clean; jsonb guard pass
• 1 pre-existing failure (think-gateway-adapter / conversation-parser/llm-*) — not in this branch's files; environment-dependent (a local AI-gateway credential makes the adapter build a client with ANTHROPIC_API_KEY unset); passes in clean CI.

🤖 Generated with Claude Code