Shadow Sentinel – Linux filesystem revision guard with loop-coupling

Shadow Sentinel is a new zero-dependency Python daemon that uses Linux kernel inotify to capture atomic .bak revisions and unified .diff files on every file modification, letting developers undo destructive writes from AI coding agents with a single `sentinel restore <ID>` command. The tool seals the previous version of a file before it closes, debounces rapid writes with a 3-second quiet window, caps storage at 10 revisions per file, and uses a `sentinel_marker` file to set a per-directory size ceiling that ejects oversized files from the vault. Its loop-coupling design re-captures the overwritten version during a restore, so a mistaken restore can itself be undone.

Autonomous OS-Level Revision & Backup Daemon with Decentralized Marker Control and Loop-Coupling. Shadow Sentinel monitors directory trees in real-time via the Linux kernel inotify , captures atomic .bak revisions and unified diffs .diff on every file modification, and provides instant 1-command restores with loop-coupling safety. Autonomous AI coding agents, Copilots, and LLM automation pipelines are transforming development. However, they introduce a terrifying new failure mode: silent, automated destruction of code . Large Language Models have a notorious habit of code "laziness" and structural truncation: - Replacing hundreds of lines of critical logic with: // ... rest of implementation remains unchanged ... - Overwriting multi-thousand-line configuration files with incomplete, summarized snippets. - Truncating files or writing empty 0-byte files when token limits, parser errors, or API timeouts occur. - Hallucinating breaking parameter changes across multiple scripts simultaneously. - If you catch it immediately: You still waste stressful hours digging through editor undo buffers, stash queues, or attempting to manually reconstruct what the model wiped out. - If you catch it hours or days later: The damage is catastrophic. The agent continued running, git working trees are dirty, commits were never made, and the original, working code is gone forever. Regular backups taken once a day or once a week cannot save intraday edits. Shadow Sentinel runs silently in the background directly under the agent's feet at the OS level. The microsecond an AI agent or automated script calls write or overwrites a file: 1. Sentinel's kernel-level inotify intercept catches the write before the file closes. 2. The previous working version is sealed into an atomic, timestamped .bak revision. 3. A human-readable unified .diff is generated showing exactly what the agent altered or removed. 4. If an agent ruins a file, you restore it with a single command: sentinel restore <ID . 1. Decentralized Marker Control sentinel marker : - No tedious editing of central configuration files. - Simply run sentinel init MB in any directory or place a sentinel marker file. - Sentinel automatically discovers all marked roots on startup and monitors them and all nested subdirectories recursively. 2. Retroactive Legacy Backup Onboarding : - On service startup, Sentinel scans for pre-existing .bak revisions on the drive and silently indexes them into its catalog. Legacy backups become immediately restoreable via sentinel restore <ID . - Backup storage directories are isolated to prevent recursive self-monitoring loops. 3. On service startup, Sentinel scans for pre-existing 4. Dynamic File-Size Ceiling Self-Pruning Vault : - The value inside sentinel marker sets the protected size ceiling e.g. 5 for 5 MB . - If a file such as a runaway logfile exceeds this ceiling, it is automatically ejected from the shadow vault. Small scripts, configurations, and source code stay 100% protected. 5. The value inside 6. Loop-Coupling Undo-Safe Restore : - Restoring a file with sentinel restore <ID overwrites the target file. - The running inotify daemon immediately intercepts this write and seals the overwritten version into a brand-new backup revision. Mistaken restores can instantly be undone 7. Restoring a file with 8. Flapping & Cooldown Debounce : - Rapid consecutive writes are debounced with a 3-second quiet window to prevent spam. 9. Zero Dependencies : - Pure Python standard library with native ctypes bindings directly to libc.so.6 . - No external tools like inotifywait or background Git daemons required. 10. Pure Python standard library with native Sentinel guarantees that it will never exhaust disk space through a 4-tier automated policy: 1. Version Cap per File Max 10 Revisions : Only the 10 most recent .bak and .diff files per target are kept. Older versions are deleted. 2. Version Age Expiration 14 Days : Revisions older than 14 days are automatically pruned. 3. Log Expiration 30 Days : Daily audit diff logs diff-YYYYMMDD.log are removed after 30 days. 4. Emergency Storage Ceiling 500 MB Cap : If total backup directory size exceeds 500 MB, an emergency purge trims the oldest backups across all files until total disk usage drops back down to 80% 400 MB . 5. Active Vault Ejection : Files that grow beyond the MB ceiling in sentinel marker are immediately removed from the .shadow vault to recover disk space instantly. The pruning engine runs automatically every 6 hours and immediately upon service startup. pip install shadow-sentinel Set up and start the systemd background service in one step: sudo sentinel service install Navigate to the directory and run: sentinel init 5 Creates sentinel marker with a 5 MB file size limit . Simply type in any terminal: sentinel Automatically detects the nearest marker upwards and lists all protected revisions. Optionally pass a search filter: sentinel .py sentinel restore 3 sentinel diff 3 sentinel markers sentinel help - Root Daemon: /var/lib/shadow-sentinel/ - User Daemon: ~/.local/share/shadow-sentinel/ To store backups, vaults, and indices in a custom directory, create: /etc/shadow-sentinel/config.json for root or ~/.config/shadow-sentinel/config.json for user : { "storage dir": "/custom/path/to/backups" } export SENTINEL STORAGE DIR=/custom/path/to/backups