PathUnlocker

PathUnlocker is a native Windows utility that identifies processes holding a file or directory open and safely releases those locks. The first release is a single win-x64 executable invoked from the classic File Explorer context menu.

Design Constraints

• Windows 10/11 x64 first; ARM64 can be added as a separate release target.
• No runtime dependency on PowerShell, .NET, Appx, COM shell extensions, or a resident service.
• No automatic delete, move, or rename operation after unlocking.
• Normal-user scan first; UAC elevation only when a hard scan gap or an action requires administrator rights.
• Restart Manager and a native handle scanner are independent detectors whose results are merged and verified after action.
• Potentially blocking handle inspection runs in a time-bounded worker process.

See the architecture in docs/superpowers/specs/2026-07-14-path-unlocker-design.md and the execution plan in docs/superpowers/plans/2026-07-14-path-unlocker.md.

Workspace

crates/path-unlocker-core   Pure domain models, policies, and orchestration
crates/path-unlocker-win32  Windows API adapters and isolated unsafe code
crates/path-unlocker-app    Single executable, command routing, UI, and IPC

Development

cargo fmt --all --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
.\scripts\Verify.ps1

Release Package

Build the checked release package from the repository root:

.\scripts\Build-Release.ps1
Get-FileHash .\dist\win-x64\PathUnlocker.exe -Algorithm SHA256
Get-Content .\dist\win-x64\SHA256SUMS.txt

The package is dist\win-x64\PathUnlocker.exe with a matching SHA256SUMS.txt. The build requires the stable MSVC Rust toolchain and dumpbin.exe from the Visual C++ build tools. Packaging fails if the executable imports a dependency that is not a Windows system DLL or an API-set DLL.

Install And Uninstall

PathUnlocker installs one stable executable and two per-user classic Explorer verbs. Run install from the release executable, not from target or a source checkout. PathUnlocker uses the Windows GUI subsystem so Explorer invocations do not flash a console window; interactive PowerShell therefore needs an explicit pipeline to wait for command completion:

& .\dist\win-x64\PathUnlocker.exe install --install-dir D:\project\Toolkit\PathUnlocker | Out-Host

The default install directory is D:\project\Toolkit\PathUnlocker. The installer atomically copies the executable there, verifies it, then registers 解除占用 for files and directories under HKCU\Software\Classes. On Windows 11, select Show more options to find the classic verb.

To uninstall, run the installed executable when possible:

& D:\project\Toolkit\PathUnlocker\PathUnlocker.exe uninstall | Out-Host

When the executable is uninstalling itself, it starts a short-lived cleanup helper after the parent exits. Do not move or replace the installation directory while this is running. The installer and cleanup helper verify the recorded path, content identity, and installation generation before changing a verb or deleting a file; a moved, modified, or foreign executable is deliberately left in place.

UAC And Result States

Discovery starts as the current user. A UAC prompt appears only when the scan has a hard access gap or a selected action needs administrator rights. Declining the prompt is a Cancelled result, not success. A file can be reported with CompleteWithGaps when Restart Manager completed a target-specific scan with no owner, while the supplemental native handle scan could not inspect unrelated protected processes. These recorded soft gaps do not request UAC; directory targets, Restart Manager failures, detected owners, and structural native scan errors remain fail-closed.

• NoLock: a fresh complete scan, or the target-scoped CompleteWithGaps condition above, found no lock owner.
• Released: the same verified condition found no owner after action.
• StillLocked: one or more verified owners remain.
• Incomplete: an access denial, worker timeout, or detector error prevents a certain conclusion.
• Cancelled: elevation or an explicit risk action was declined.

An action return alone never proves that a path is released. The result always comes from a fresh scan.

Safety, Privacy, And Support

Ordinary applications may be asked to close and, only if still necessary, be terminated. Explorer is skipped by default and requires an explicit restart decision. Services are never force-terminated automatically; stopping one requires a separate explicit decision. Protected and critical processes are never terminated by the ordinary path.

PathUnlocker has no resident service, shell extension, cloud backend, or network upload. Diagnostic JSONL records are bounded and use a hash of the target path; they do not log raw target paths or file contents by default. diagnose --path <path> --json performs discovery and classification only, without closing or terminating anything. Its completeness field is a tagged enum with Complete, CompleteWithGaps, or Incomplete; JSON consumers must accept all three values. For an interactive PowerShell query, keep the executable in a pipeline so the shell waits for its JSON output:

$json = & .\dist\win-x64\PathUnlocker.exe diagnose --path .\example.txt --json | Out-String
$report = $json | ConvertFrom-Json

This release supports Windows 10 and Windows 11 on x64 only. ARM64, non-Windows systems, Windows 7/8, and the Windows 11 top-level context menu are unsupported. Unsigned builds can trigger Microsoft Defender SmartScreen. Verify the published SHA-256 checksum and use a release from a trusted source before choosing a SmartScreen override.

Recovery

If installation or cleanup is interrupted, first inspect the per-user verbs and the recorded cleanup status without changing unrelated Explorer settings:

Get-Item 'HKCU:\Software\Classes\*\shell\PathUnlocker' -ErrorAction SilentlyContinue
Get-Item 'HKCU:\Software\Classes\Directory\shell\PathUnlocker' -ErrorAction SilentlyContinue
Get-Content "$env:LOCALAPPDATA\PathUnlocker\cleanup-status.log" -ErrorAction SilentlyContinue

Then rerun PathUnlocker.exe uninstall from the recorded stable executable. It removes only verbs whose command still resolves to the installed PathUnlocker; do not manually delete a command that was changed to another product.