feat(vault-sync): opt-in symlink following

[LinuxIsCool]

Summary

• Adds VAULT_SYNC_FOLLOW_SYMLINKS env flag (default: false) to allow vault sync to follow symlinks in the Shared/ folder
• Enables symlinking external files (journal entries, research docs) into the shared folder without copying — single source of truth
• Zero behavioral change without the flag — fully backward compatible

Motivation

When sharing files between KOI-net peers, users currently must copy files into ~/Documents/Notes/Shared/. This creates stale duplicates when the source file is updated elsewhere (e.g., a journal entry managed by another tool).

Symlink support lets users ln -s /path/to/source.md ~/Documents/Notes/Shared/source.md and have vault sync read through the symlink to the target content. The sync protocol uses the symlink name as the relative path, not the target path — so peers see the file at the expected location.

Safety guards

Guard	Purpose
Disabled by default	Zero change for existing deployments
Path.resolve(strict=True)	Catches circular and broken symlinks (raises OSError)
Blocked path prefixes	Prevents resolving into /etc, /root, /proc, /sys
Outbound-only	Incoming files never overwrite existing symlinks (apply-side guard preserved)
rel_path from symlink name	Peer sees the link name, not the host filesystem structure

Changes

api/vault_sync.py (1 file, +61 -8):

• New constant: FOLLOW_SYMLINKS from VAULT_SYNC_FOLLOW_SYMLINKS env var
• New function: _resolve_if_symlink(path, vault_root) — safe resolution with guards
• Reconcile scan (~line 711): follows symlinks for hash comparison
• Main scan loop (~line 918): follows symlinks for file discovery, stat, read, hash
• Apply guard (~line 1125): comment added, behavior unchanged — incoming files never clobber symlinks

Usage

# In config/personal.env (or export before starting the API):
VAULT_SYNC_FOLLOW_SYMLINKS=true

# Then symlink any file into the shared folder:
ln -s ~/.claude/local/journal/legion/2026/03/16/entry.md ~/Documents/Notes/Shared/entry.md

Test plan

• Existing vault sync tests pass (all 44 — requires darrenzal DB role for full suite)
• Module imports cleanly with FOLLOW_SYMLINKS=false (default)
• Module imports cleanly with VAULT_SYNC_FOLLOW_SYMLINKS=true
• Symlinked .md file in Shared/ is picked up by scan when flag is enabled
• Broken symlink is skipped (no crash)
• Circular symlink is skipped (no crash)
• Symlink to /etc/passwd is blocked
• Incoming file does not overwrite existing symlink at same path
• Without flag, symlinks are skipped (backward compat)

🤖 Generated with Claude Code