Note
AI / LLM Integration: This repository contains an llms.txt file providing machine-readable architecture guidelines, CLI interfaces, and safety contracts for AI coding assistants.
CloudLockFixer with Delayed Action Service (CLF-WDAS) is an autonomous Windows system tray and CLI tool that reliably performs file and folder operations (rename / move / delete) inside cloud synchronization folders — even when the Windows Cloud Files filter (cldflt.sys) or active sync engines are holding transient locks. You queue an action and it is carried out "eventually," automatically with bit-for-bit SHA-256 verification — fire & forget.
- Features
- Architecture & System Design
- Target Personas & Discoverability
- Comparative Matrix vs. Alternatives
- Dual Mermaid Diagrams
- Governance & Runtime Invariants
- Multi-Cloud Provider Support
- Cryptographic Copy+Delete Fallback
- Atomic Multi-Step Chains
- Visual Showcase & GUI Workflow
- Installation & Quickstart
- CLI & Automation Usage
- Queue File (
queue.txt) Integration - Cross-Platform Parity
- Testing & Quality Verification
- Third-Party Licenses & Transparency
- Sibling Ecosystem Matrix
- Security Policy & Statutory Notice
- Asynchronous Fire & Forget Operations: Queue file/folder renames, moves, and deletions without blocking interactive work or waiting for locks to release.
- Bit-for-Bit Cryptographic Copy+Delete Fallback: When Windows Cloud Files filter (
cldflt.sys) intercepts atomic renames withWinError 5/EXDEV, CLF streams bytes to the destination, verifies matching SHA-256 digests, and safely unlinks the source. - Ordered Multi-Step Atomic Chains: Chain 1–4 operations with
&&(e.g.move A -> B && delete C). Subsequent steps execute strictly if prerequisite steps succeed; destructive steps are skipped on upstream errors. - Omnichannel Ingestion: Add tasks via headless CLI (
clf add), plain-textqueue.txt, PySide6 System Tray Dialog, or Windows Explorer Right-Click Context Menu (HKCU). - 8-Provider Cloud Sensor: Automatic discovery and intelligent pause/resume for OneDrive, Dropbox, Google Drive, Box, iCloud, Nextcloud, pCloud, and Synology Drive.
- Virtual Mount Guard: Distinguishes between folder-mount providers (OneDrive, Dropbox) and virtual-drive mounts (Google Drive, pCloud), strictly preserving virtual mount stability.
- Deterministic Retry Engine: Configurable retry interval (default 2 h) and retry limits (
max_retries). Tasks transition idempotently betweenpending,retryable,blocked,failed_permanent, anddone. - 100% Local-First & Zero Egress: Zero outbound network traffic, zero analytics, zero external sockets. Verified by automated AST static analysis contract tests.
- Unprivileged Execution (
RunAsInvoker): Runs purely in user space without requiring administrator elevation, UAC prompts, or kernel-mode drivers.
For in-depth architectural specifications and safety models, see docs/DESIGN.md.
Windows Cloud Files mini-filter driver (cldflt.sys) acts as a filesystem filter for cloud sync engines (OneDrive, Dropbox, iCloud, Nextcloud, etc.). When a file is undergoing hydration, thumbnail extraction, or background replication, cldflt.sys intercepts standard Win32 rename() and MoveFileEx() calls, returning ERROR_ACCESS_DENIED (WinError 5) or cross-device link errors (EXDEV).
[User / Agent Task]
│
▼
[Queue Normalizer] ───► [queue.json Store]
│
▼
[Worker Thread Engine]
│
┌──────────────┴──────────────┐
▼ ▼
[Direct In-Place] [Provider Sensor]
(os.replace / atomic) (OneDrive, Dropbox, etc.)
│ │
Lock Detected? │
│ (WinError 5 / cldflt) ▼
▼ [Selective Pause]
[Copy+Delete Fallback] (Folder mounts only)
1. Stream to target │
2. SHA-256 Digest Match ▼
3. Defensive Source Unlink [Resume Sync Engine]
Microsoft's documented guidance for handling filter-driver sharing violations is replacing single-operation renames with verified copy-and-delete semantics. CloudLockFixer implements this pattern alongside durable disk queues, exponential backoff, process synchronization, and clean rollback safety.
CloudLockFixer addresses four distinct user personas:
[PERSONA-01]Desktop Power Users & Cloud Sync Workers:- Context: Managing daily project files inside OneDrive, Dropbox, Google Drive, or Nextcloud folders.
- Pain Point: Constant interruptions from "The action can't be completed because the file is open in another program" during active sync cycles.
- Benefit: Silent background resolution via the system tray; queue a rename or cleanup and continue working without interruptions.
[PERSONA-02]Autonomous AI Coding Agents & LLM Script Developers:- Context: AI coding assistants (Antigravity, Claude Code, Codex) executing repository refactors and file migrations.
- Pain Point: Fragile shell scripts crash when trying to move or delete files in cloud-synced local repositories.
- Benefit: Headless CLI (
clf add --chain ...), human/agent readablequeue.txt, and structuredllms.txtintegration with 100% predictable exit codes.
[PERSONA-03]DevOps Engineers, System Administrators & CI/CD Builders:- Context: Maintaining multi-host developer workstations, automated test runners, and scheduled build cleanups.
- Pain Point: Build steps intermittently fail due to file locks on temporary test directories and build caches.
- Benefit: Multi-step atomic chains (
op1 && op2 && op3), configurable retry limits, and cross-platform core support across Windows, Linux, and macOS.
[PERSONA-04]Open Source Maintainers, Security Auditors & File System Enthusiasts:- Context: Organizations requiring verified offline-first software without proprietary kernel drivers.
- Pain Point: Third-party file unlockers frequently bundle closed-source kernel drivers, ask for root/admin elevation, or ship adware.
- Benefit: Completely transparent MIT-licensed codebase, dynamic linking LGPL-3.0 isolation, zero-egress guarantee, and non-elevated
RunAsInvokermode.
| Query Theme | Target English Search Query | Target German Search Query |
|---|---|---|
| OneDrive Lock | onedrive file locked cannot rename move delete fix |
onedrive datei gesperrt umbenennen fehler beheben |
| Driver Lock | cldflt.sys file in use error python workaround |
cldflt fehler 0x8007016A datei verschieben |
| Delayed Queue | windows delayed action file queue open source |
cloud sync dateisperre automatisches verzögertes verschieben |
| Safe Fallback | copy delete fallback file unlocker python |
datei wird von einem anderen prozess verwendet cloud sync |
| Agent Tooling | automated file rename queue for ai coding agents |
python dateisystem queue ohne admin rechte |
| Feature / Dimension | CloudLockFixer (CLF-WDAS) | Windows Explorer / Shell | LockHunter / Unlocker | Generic Sleep Scripts | Cloud Sync Web UIs | Invariant Alignment |
|---|---|---|---|---|---|---|
| Non-Destructive Copy+Delete | ✅ Bit-for-bit SHA-256 verified | ❌ Fails on lock (WinError 5) |
❌ Force-closes handles | ❌ Not applicable | INV-HASH-03 |
|
| Kernel Filter Awareness | ✅ Tailored for cldflt.sys |
❌ Blocks immediately | ❌ None (blind retry) | ❌ None | INV-SENSOR-05 |
|
| Multi-Step Atomic Chains | ✅ 1–4 steps (&&) with halt |
❌ None | ❌ Single file only | ❌ None | INV-CHAIN-04 |
|
| Privilege Requirement | ✅ Unprivileged (RunAsInvoker) |
✅ User mode | ❌ Kernel Driver / Admin UAC | ✅ User mode | ✅ Browser session | INV-RUNAS-02 |
| Multi-Cloud Sensor | ✅ 8 providers auto-detected | ❌ None | ❌ None | ❌ None | ❌ Single cloud silo | INV-SENSOR-05 |
| Zero Egress & Telemetry | ✅ 100% Offline (AST tested) | ❌ Telemetry enabled | ❌ Closed source / Adware risk | ✅ Local script | ❌ Full cloud egress | INV-LOCAL-01 |
| Headless AI / CLI Interface | ✅ clf add + queue.txt + llms.txt |
❌ GUI only | ❌ Web UI only | INV-DOCS-09 |
||
| Single-Instance System Tray | ✅ PySide6 Tray + Dialogs | ❌ None | ✅ GUI window | ❌ None | ❌ None | INV-PLAT-08 |
| Deterministic Retry Model | ✅ Configurable backoff & states | ❌ Manual retry modal | ❌ Immediate kill | ❌ Cloud eventual | INV-IDEMP-06 |
|
| Security SLA & Support | ✅ 48h SLA / 5d Triage | ❌ Standard OS support | ❌ Abandonware / Unmaintained | ❌ None (unmaintained) | ❌ Enterprise portal | INV-SLA-10 |
flowchart TD
subgraph Inputs["1. Ingestion Channels"]
CLI["CLI Command<br/><code>clf add --chain ...</code>"]
TRAY["PySide6 System Tray<br/><code>Task Dialog</code>"]
QTXT["Queue File<br/><code>%LOCALAPPDATA%/.../queue.txt</code>"]
CTX["Explorer Context Menu<br/><code>HKCU Right-Click</code>"]
end
subgraph Core["2. Queue Orchestrator & State"]
PARSER["Queue Parser & Normalizer"]
VAL["Chain Validator<br/>(1-4 Steps: rename / move / delete)"]
STATE[("Local State Store<br/><code>queue.json</code>")]
end
subgraph Sensor["3. Multi-Cloud Provider Sensor"]
DETECT{"Active Sync Client?<br/>(OneDrive, Dropbox, Google Drive,<br/>Box, iCloud, Nextcloud, pCloud, Synology)"}
PROV_PAUSE["Selective Client Pause<br/>(Folder mounts only)"]
PROV_RESUME["Resume Sync Client"]
end
subgraph Engine["4. Resilient Execution Engine"]
DIRECT["In-Place Operation<br/>(Atomic <code>os.replace</code>)"]
CHECK_LOCK{"Lock Detected?<br/>(<code>cldflt.sys</code> / WinError 5)"}
COPY["Streaming Copy<br/>(Temporary Target)"]
HASH["SHA-256 Digest Verification<br/>(Bit-for-Bit Hash Check)"]
DEL["Defensive Source Unlink<br/>(Strip Read-Only & Delete)"]
end
subgraph Outcomes["5. Deterministic Outcomes"]
SUCCESS["Mark Step Done<br/>(Proceed to Next Step)"]
RETRY["Durable Retry Queue<br/>(Configurable Interval)"]
BLOCKED["Mark Blocked<br/>(Target Conflict / Missing Source)"]
end
CLI --> PARSER
TRAY --> PARSER
QTXT --> PARSER
CTX --> PARSER
PARSER --> VAL --> STATE
STATE --> DETECT
DETECT -- "Lock Escalation Needed" --> PROV_PAUSE --> DIRECT
DETECT -- "Standard Attempt" --> DIRECT
DIRECT -- "Success" --> SUCCESS
DIRECT -- "Locked / Denied" --> CHECK_LOCK
CHECK_LOCK -- "Yes" --> COPY --> HASH
HASH -- "Hash Verified" --> DEL --> PROV_RESUME --> SUCCESS
HASH -- "Mismatch / Locked" --> PROV_RESUME --> RETRY
CHECK_LOCK -- "Terminal Conflict" --> PROV_RESUME --> BLOCKED
sequenceDiagram
autonumber
actor User as User / AI Coding Agent
participant Ingest as Queue Ingestion (CLI / Tray / File)
participant Worker as Worker Thread Engine
participant Sensor as Provider Sensor
participant FS as Local Filesystem & cldflt Driver
User->>Ingest: Submit task (rename / move / delete chain)
Ingest->>Worker: Persist pending task in queue.json
Worker->>FS: Attempt atomic in-place operation (os.replace)
alt Operation succeeds immediately
FS-->>Worker: File replaced successfully
Worker->>User: Step completed (status: done)
else cldflt.sys lock / WinError 5 Access Denied
FS-->>Worker: Error: File locked by Cloud Files filter
Worker->>Sensor: Check responsible sync provider (OneDrive, Dropbox, etc.)
opt Folder-based provider with persistent lock
Sensor->>FS: Request temporary sync client pause
end
Worker->>FS: Fallback Step 1: Copy stream to destination
Worker->>FS: Fallback Step 2: Compute SHA-256 digest on source & copy
FS-->>Worker: SHA-256 match verified (100% bit-for-bit integrity)
Worker->>FS: Fallback Step 3: Unlink source file (defensive read-only strip)
opt Sync client was paused
Sensor->>FS: Resume sync client process
end
Worker->>User: Fallback successful (status: done, zero data loss)
else Irrecoverable Target Conflict
Worker->>User: Mark task blocked (status: blocked, preserves data)
end
| Invariant | Category | Behavior & Implementation | Governance & Safety Invariant |
|---|---|---|---|
INV-LOCAL-01 |
Local-First & Zero Egress | 100% offline-first execution with zero external network calls, tracking, analytics, or telemetry. |
Hermetic Isolation: Enforced and verified via AST static analysis contract tests (test_offline_zero_egress_no_network_imports). |
INV-RUNAS-02 |
Unprivileged User Mode | Runs entirely in unprivileged user space (RunAsInvoker). |
Confined Scope: Autostart registry keys and context menus live purely within HKCU without UAC prompts or root requirements. |
INV-HASH-03 |
Cryptographic Copy+Delete | When cldflt.sys blocks atomic moves, CLF streams content to destination and verifies matching SHA-256 hashes. |
Zero Data Loss: Source files are never unlinked until destination digest matches bit-for-bit. |
INV-CHAIN-04 |
Atomic Multi-Step Chains | Supports ordered chains of 1–4 operations (rename, move, delete separated by &&). |
Conditional Safety: Step |
INV-SENSOR-05 |
Multi-Cloud Engine Sensor | Automatically inspects and detects 8 cloud sync engines: OneDrive, Dropbox, Google Drive, Box, iCloud, Nextcloud, pCloud, Synology Drive. | Selective Pause: Only folder-backed sync engines are temporarily paused during persistent locks; virtual mounts are never paused. |
INV-IDEMP-06 |
Deterministic Idempotent Retry | Tasks transition between pending, done, retryable, blocked, and failed_permanent. |
State Resilience: Missing sources without targets are safely blocked; already completed tasks remain idempotent successes. |
INV-TRIM-07 |
Defensive Source & Read-Only Handling | Read-only attributes are stripped defensively prior to deletion; case-only renames are safely handled on case-insensitive filesystems. | Filesystem Cleanliness: Protects against locked read-only remnants and corrupt intermediate states. |
INV-PLAT-08 |
Cross-Platform Foundation | Cross-platform core and data directory logic supporting Windows, Linux (XDG autostart), and macOS (LaunchAgents). | Platform Parity: Core queue and worker run cleanly across all major desktop operating systems. |
INV-DOCS-09 |
1:1 Bilingual Documentation | Symmetrical 18-point documentation parity across English (README.md) and German (README.de.md) backed by llms.txt. |
Architectural Transparency: Complete operational guidelines accessible to both human developers and autonomous AI coding agents. |
INV-SLA-10 |
Open Source Governance & SLA | MIT License, public GitHub issue tracker, and committed security SLA. |
Security Commitment: 48-hour initial response SLA and 5-business-day triage commitment documented in SECURITY.md. |
CloudLockFixer detects and manages synchronization engines across 8 major cloud providers:
| Provider | Mount Type | Detection Mechanism | Pause/Resume Support | Safety Policy |
|---|---|---|---|---|
| OneDrive | Folder Mount | Registry & Environment (OneDriveConsumer / OneDriveCommercial) |
Yes (OneDrive.exe) |
Pauses only during persistent lock on folder-backed paths |
| Dropbox | Folder Mount | %LOCALAPPDATA%\Dropbox\info.json |
Yes (Dropbox.exe) |
Pauses only during persistent lock on folder-backed paths |
| Google Drive | Virtual Mount | Mounted drive letter scan & Registry | No (Safe Virtual Mount Guard) | Virtual drive mount — never paused to prevent drive unmount crashes |
| Box | Folder Mount | Registry HKCU\Software\Box\Box |
Yes (Box.exe) |
Pauses only during persistent lock on folder-backed paths |
| iCloud | Folder Mount | Default root %USERPROFILE%\iCloudDrive |
Yes (iCloudDrive.exe) |
Pauses only during persistent lock on folder-backed paths |
| Nextcloud | Folder Mount | Config file %APPDATA%\Nextcloud\nextcloud.cfg |
Yes (nextcloud.exe) |
Pauses only during persistent lock on folder-backed paths |
| pCloud | Virtual Mount | Volume label check (pCloud) |
No (Safe Virtual Mount Guard) | Virtual drive mount — never paused to prevent drive unmount crashes |
| Synology Drive | Folder Mount | Config %LOCALAPPDATA%\SynologyDrive\data\session |
Yes (SynologyDrive.exe) |
Pauses only during persistent lock on folder-backed paths |
When operating in cloud-synchronized directories, os.replace() or MoveFileEx() frequently encounters ERROR_SHARING_VIOLATION or cldflt filter blocks. CloudLockFixer resolves this via a 3-phase verified sequence:
- Streaming Copy: Streams file or directory contents to a temporary destination using buffered I/O.
- Cryptographic SHA-256 Digest Verification: Computes the SHA-256 hash of both source and target files. If any bit mismatch is detected, the operation aborts immediately and the target is discarded.
- Defensive Source Removal: Strips read-only file attributes and removes the source. If removal fails, the target is preserved and the operation enters the retry queue.
CloudLockFixer supports chaining up to 4 sequential operations using the && operator:
clf add --chain 'move "C:\local\build.bin" "C:\onedrive\build.bin" && delete "C:\onedrive\old.bin"'-
Strict Prerequisite Execution: Step
$N$ executes strictly after Step$N-1$ reports statusdone. - Fail-Safe Abort: If an intermediate step fails or encounters a target conflict, the remaining steps are skipped, preventing destructive deletions of un-migrated data.
-
Persistent Progress: Progress is preserved in
queue.json, allowing resumed tasks to continue from the exact failed step without re-executing completed operations.
CloudLockFixer runs quietly in the Windows notification area (System Tray). Key tray menu features:
- Add Task Dialog: Intuitive GUI dialog allowing users to browse for files or folders and select delayed actions (
Rename,Move,Delete). - Run Now: Triggers immediate processing of all pending queue items (with optional one-click sync client pause).
- Retry Controls: View and re-trigger individual failed tasks or trigger
Retry All. - Configurable Interval: Adjust worker background cycle (30-min intervals up to 12 hours; default 2 h).
- Max Retries: Configure retry limits (Unlimited, 3, 5, 10, 20 attempts).
- Desktop Notifications: Toggle native Windows toast notifications on permanent task failure or block.
- Autostart with Windows: Toggles
HKCUregistry autostart entry without admin privileges. - Open Data Folder: Direct access to
%LOCALAPPDATA%\CloudLockFixercontainingqueue.txt,queue.json, and runtime logs.
- Operating System: Windows 10/11 (for
cldflt.sysfilter resolution and Explorer integration; headless Linux/macOS supported). - Python: Version 3.10, 3.11, 3.12, or 3.13.
- GUI Engine: PySide6 (
>=6.7.0).
# 1. Clone the repository
git clone https://github.com/file-bricks/CloudLockFixer.git
cd CloudLockFixer
# 2. Install dependencies
pip install -r requirements.txt
# 3. Launch the System Tray application
START.bat
# Or via Python module directly:
PYTHONPATH=src python -m cloudlockfixerCloudLockFixer provides a rich CLI interface designed for developers, automation scripts, and autonomous AI coding agents:
# Add single operations
clf add --rename "C:\OneDrive\Project" "Project_Archived"
clf add --move "C:\Local\Artifacts" "C:\OneDrive\Artifacts"
clf add --delete "C:\OneDrive\TempCache"
# Add atomic multi-step chain
clf add --chain 'move "C:\Build\bin" "C:\OneDrive\bin" && delete "C:\OneDrive\old_bin"'
# Inspect queue status
clf list
# Retry failed or blocked tasks
clf retry <task-id>
clf retry-all
# Execute queue immediately
clf run-now
clf run-now --pause
clf run-now --max-retries 5
# Diagnostics
clf diagnose(Development invocation: PYTHONPATH=src python -m cloudlockfixer.cli ...)
For scriptless or human-friendly queuing, CloudLockFixer continuously watches the plain-text queue file at:
%LOCALAPPDATA%\CloudLockFixer\queue.txt
Lines are formatted as standard commands:
rename "C:\OneDrive\OldName" "NewName"
move "C:\Temp\Data.zip" "C:\OneDrive\Data.zip"
delete "C:\OneDrive\ObsoleteFolder"
move "C:\Src\A" "C:\Dst\A" && delete "C:\Dst\Old"
When processed by the background worker, completed lines are atomically commented out with #> and timestamped, preserving a human-auditable execution log.
While cldflt.sys filter mitigation is specific to Windows, CloudLockFixer features a fully decoupled, cross-platform architecture:
- Windows: Standard native runtime utilizing
HKCUregistry entries, Win32 error codes, and Explorer right-click integration. - Linux: Headless execution with XDG Base Directory specification compliance (
$XDG_DATA_HOME/cloudlockfixer),.desktopautostart entries (~/.config/autostart), GNOME/Nautilus scripts (~/.local/share/nautilus/scripts/CloudLockFixer), and KDE/Dolphin ServiceMenus (~/.local/share/kio/servicemenus/cloudlockfixer.desktop). - macOS: Headless execution with standard
~/Library/Application Support/CloudLockFixerdata directory, User LaunchAgent plists (~/Library/LaunchAgents), and Finder Quick Actions / Services workflows (~/Library/Services/).
The repository enforces strict continuous verification with 277 automated tests (pytest, 277 passing, 0 failures, 100% green):
# Run the complete test suite
PYTHONIOENCODING=utf-8 python -m pytest -ra -v
# Run code style and lint inspection
ruff check .
# Run bytecode compilation verification
python -m compileall -q src tests
# Run cross-platform source smoke tests
python -m pytest tests/source_platform_smoke.py -vTest coverage includes unit tests, audit fixes, multi-step chains, crypto-hash verification, provider sensor mock suites, cross-platform autostart roundtrips, zero-egress AST static analysis, and PEP 621 metadata contract tests.
CloudLockFixer is open source software licensed under the permissive MIT License.
All runtime and development dependencies are rigorously tracked and audited in THIRD_PARTY_LICENSES.md:
- PySide6 & shiboken6: Licensed under LGPL-3.0-only. PySide6 is used as an unmodified dynamically linked dependency via official CPython wheels.
- Zero-Copyleft Isolation: No proprietary GPL/AGPL source code is bundled into the application core.
- Unprivileged Certification: Runs purely in user space (
RunAsInvoker) without administrative privileges.
CloudLockFixer integrates into the file-bricks and open-bricks desktop and developer ecosystem:
| Repository | Scope & Specialty | Role in Ecosystem | Link |
|---|---|---|---|
| file-bricks/CloudLockFixer | Delayed file/folder operations & cldflt filter unlocker |
Local filesystem resilience | Repository |
| file-bricks/SoftwareCenter | Desktop application portfolio and local environment hub | Central workstation cockpit | Repository |
| file-bricks/knowledgedigest | Multi-source knowledge indexing and digest engine | Desktop document analysis | Repository |
| open-bricks | Umbrella open-source software and tooling collective | Architectural governance | Repository |
| ellmos-ai/system-auditor | Multi-host system auditor and configuration inspector | Operational verification | Repository |
| ellmos-ai/file-collect-sort-action | Declarative file organization and lifecycle automation | Invariant-driven file sorter | Repository |
| dev-bricks/automizer-for-claude-desktop | Safe process staging and configuration injector | Agentic desktop automation | Repository |
| doc-bricks/USR_pic2pic | Offline image format conversion and visual QA | Local-first media tooling | Repository |
| doc-bricks/USR_PDFunlock | Offline PDF access and document security manager | Document processing utility | Repository |
CloudLockFixer operates under strict security and privacy guarantees:
- 100% Local-First & Zero-Egress: The tool performs no telemetry, analytics, or outbound internet communication.
- Cryptographic Verification: SHA-256 verification ensures that files are never lost during copy+delete fallbacks.
- Vulnerability SLA: Coordinated vulnerability disclosure with a committed 48-hour initial response and 5-business-day triage SLA detailed in
SECURITY.md.