{"slug": "shadow-sentinel-linux-filesystem-revision-guard-with-loop-coupling", "title": "Shadow Sentinel – Linux filesystem revision guard with loop-coupling", "summary": "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.", "body_md": "**Autonomous OS-Level Revision & Backup Daemon with Decentralized Marker Control and Loop-Coupling.**\n\nShadow Sentinel monitors directory trees in real-time via the Linux kernel (`inotify`), captures\natomic `.bak` revisions and unified diffs (`.diff`) on every file modification, and provides\ninstant 1-command restores with loop-coupling safety.\n\nAutonomous AI coding agents, Copilots, and LLM automation pipelines are transforming development.\nHowever, they introduce a terrifying new failure mode: **silent, automated destruction of code**.\n\nLarge Language Models have a notorious habit of code \"laziness\" and structural truncation:\n\n- Replacing hundreds of lines of critical logic with:\n`// ... rest of implementation remains unchanged ...`\n- Overwriting multi-thousand-line configuration files with incomplete, summarized snippets.\n- Truncating files or writing empty 0-byte files when token limits, parser errors, or API timeouts occur.\n- Hallucinating breaking parameter changes across multiple scripts simultaneously.\n\n- **If you catch it immediately:** You still waste stressful hours digging through editor undo buffers,\nstash queues, or attempting to manually reconstruct what the model wiped out.\n- **If you catch it hours or days later:** The damage is catastrophic. The agent continued running,\ngit working trees are dirty, commits were never made, and the original, working code is gone forever.\nRegular backups taken once a day or once a week cannot save intraday edits.\n\nShadow Sentinel runs silently in the background directly under the agent's feet at the OS level.\nThe microsecond an AI agent or automated script calls `write()` or overwrites a file:\n\n1. Sentinel's kernel-level inotify intercept catches the write before the file closes.\n2. The previous working version is sealed into an atomic, timestamped `.bak` revision.\n3. A human-readable unified `.diff` is generated showing exactly what the agent altered or removed.\n4. If an agent ruins a file, you restore it with a single command: `sentinel restore <ID>` .\n\n1. \n**Decentralized Marker Control (`sentinel_marker`)** :\n  - No tedious editing of central configuration files.\n  - Simply run `sentinel init [MB]` in any directory or place a`sentinel_marker` file.\n  - Sentinel automatically discovers all marked roots on startup and monitors them and all nested subdirectories recursively.\n2. \n**Retroactive Legacy Backup Onboarding** :\n  - On service startup, Sentinel scans for pre-existing `.bak` revisions on the drive and\nsilently indexes them into its catalog. Legacy backups become immediately restoreable via`sentinel restore <ID>` .\n  - Backup storage directories are isolated to prevent recursive self-monitoring loops.\n3. On service startup, Sentinel scans for pre-existing \n4. \n**Dynamic File-Size Ceiling (Self-Pruning Vault)** :\n  - The value inside `sentinel_marker` sets the protected size ceiling (e.g.`5` for 5 MB).\n  - 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.\n5. The value inside \n6. \n**Loop-Coupling (Undo-Safe Restore)** :\n  - Restoring a file with `sentinel restore <ID>` overwrites the target file.\n  - 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!\n7. Restoring a file with \n8. \n**Flapping & Cooldown Debounce** :\n  - Rapid consecutive writes are debounced with a 3-second quiet window to prevent spam.\n9. \n**Zero Dependencies** :\n  - Pure Python standard library with native `ctypes` bindings directly to`libc.so.6` .\n  - No external tools like `inotifywait` or background Git daemons required.\n10. Pure Python standard library with native \n\nSentinel guarantees that it will never exhaust disk space through a 4-tier automated policy:\n\n1. \n**Version Cap per File (Max 10 Revisions)** :\nOnly the 10 most recent`.bak` and`.diff` files per target are kept. Older versions are deleted.\n2. \n**Version Age Expiration (14 Days)** :\nRevisions older than 14 days are automatically pruned.\n3. \n**Log Expiration (30 Days)** :\nDaily audit diff logs (`diff-YYYYMMDD.log` ) are removed after 30 days.\n4. \n**Emergency Storage Ceiling (500 MB Cap)** :\nIf total backup directory size exceeds 500 MB, an emergency purge trims the oldest backups\nacross all files until total disk usage drops back down to 80% (400 MB).\n5. \n**Active Vault Ejection** :\nFiles that grow beyond the MB ceiling in`sentinel_marker` are immediately removed from\nthe`.shadow_vault` to recover disk space instantly.\n\n*The pruning engine runs automatically every 6 hours and immediately upon service startup.*\n\n```\npip install shadow-sentinel\n```\n\nSet up and start the systemd background service in one step:\n\n```\nsudo sentinel service install\n```\n\nNavigate to the directory and run:\n\n```\nsentinel init 5\n```\n\n*(Creates `sentinel_marker` with a 5 MB file size limit).*\n\nSimply type in any terminal:\n\n```\nsentinel\n```\n\nAutomatically detects the nearest marker upwards and lists all protected revisions. Optionally pass a search filter:\n\n```\nsentinel .py\nsentinel restore 3\nsentinel diff 3\nsentinel markers\nsentinel help\n```\n\n- **Root Daemon:**`/var/lib/shadow-sentinel/`\n- **User Daemon:**`~/.local/share/shadow-sentinel/`\n\nTo store backups, vaults, and indices in a custom directory, create:\n`/etc/shadow-sentinel/config.json` (for root) or `~/.config/shadow-sentinel/config.json` (for user):\n\n```\n{\n    \"storage_dir\": \"/custom/path/to/backups\"\n}\nexport SENTINEL_STORAGE_DIR=/custom/path/to/backups\n```\n\n", "url": "https://wpnews.pro/news/shadow-sentinel-linux-filesystem-revision-guard-with-loop-coupling", "canonical_source": "https://github.com/automatician/shadow-sentinel", "published_at": "2026-10-17 11:43:01+00:00", "updated_at": "2026-10-17 12:02:47.725411+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "ai-safety"], "entities": ["Shadow Sentinel", "Linux", "inotify", "libc.so.6"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/shadow-sentinel-linux-filesystem-revision-guard-with-loop-coupling", "markdown": "https://wpnews.pro/news/shadow-sentinel-linux-filesystem-revision-guard-with-loop-coupling.md", "text": "https://wpnews.pro/news/shadow-sentinel-linux-filesystem-revision-guard-with-loop-coupling.txt", "jsonld": "https://wpnews.pro/news/shadow-sentinel-linux-filesystem-revision-guard-with-loop-coupling.jsonld"}}