private sidecar file

Error message

private sidecar file {path} must be one regular filesystem link

What it means

validate_private_regular_file (unix) checks that a freshly opened sidecar file (lock or read file) is a regular file with exactly one hard link (nlink == 1). Extra links mean someone hard-linked the private sidecar, and non-regular files mean it is a device/fifo or the open resolved through something unexpected — both break the privacy/conflict-detection assumptions, so the open fails with InvalidData.

Solutions

Inspect the sidecar with `stat` and `find -samefile`; remove the extra hard link(s) so nlink returns to 1.
Delete the suspect sidecar (lock files are safe to recreate) and let the manager recreate it.
Check the sessions directory for tampering — unexpected hard links or special files — before resuming.
Restore the directory from a clean backup if tooling (rsync -H, git hard-link caches) rewired links.

Example fix

// before
$ stat sessions/abc.lock  # Links: 2
// after
$ rm sessions/abc.lock    # manager recreates a fresh single-link lock on next open

Defensive patterns

Strategy: try-catch

Try / catch

match open_private_lock_file(&path) {
    Err(e) if e.kind() == io::ErrorKind::InvalidData => {
        // suspect tampering or hard-linked sidecar: surface a loud warning,
        // do not silently recreate over a possibly malicious link
    }
    other => other?,
}

Prevention

Keep session state directories private (0700) so nothing else can link into them.
Avoid hard-link-based backup/sync tools (rsync -H) against the sessions directory.
Investigate any InvalidData on sidecar open as potential tampering, not a transient fault.
Delete and let the manager recreate lock sidecars rather than repairing links in place.

When it happens

Trigger: open_private_lock_file or open_private_read_file opening a session sidecar whose inode has nlink > 1 (hard-linked elsewhere) or whose metadata is not a regular file; typically detected right after O_CREAT-style open under a private directory.

Common situations: An attacker or accident hard-linked the lock file into another location to subvert or share locking; backup/restore tooling recreated sidecars with hard links; a symlink or FIFO was placed where the sidecar should be; the sessions directory was restored from an rsync/hard-link-based backup.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

AI-assisted analysis of Hmbown/CodeWhale@73e0f67d83 (2026-09-22). Data as JSON: /api/errors/bd0dac6b57729d41. Report an issue: GitHub.

Appendix: source

Thrown at crates/tui/src/session_manager.rs:191

    }
    #[cfg(windows)]
    {
        use std::os::windows::fs::OpenOptionsExt as _;
        use windows_sys::Win32::Storage::FileSystem::FILE_FLAG_OPEN_REPARSE_POINT;
        options.custom_flags(FILE_FLAG_OPEN_REPARSE_POINT);
    }
    let file = options.open(path)?;
    validate_private_regular_file(&file, path)?;
    Ok(file)
}

#[cfg(unix)]
fn validate_private_regular_file(file: &fs::File, path: &Path) -> io::Result<()> {
    use std::os::unix::fs::MetadataExt as _;

    let metadata = file.metadata()?;
    if !metadata.is_file() || metadata.nlink() != 1 {
        return Err(io::Error::new(
            io::ErrorKind::InvalidData,
            format!(
                "private sidecar file {} must be one regular filesystem link",
                path.display()
            ),
        ));
    }
    Ok(())
}

#[cfg(windows)]
fn validate_private_regular_file(file: &fs::File, path: &Path) -> io::Result<()> {
    use std::os::windows::fs::MetadataExt as _;
    use std::os::windows::io::AsRawHandle as _;
    use windows_sys::Win32::Storage::FileSystem::{
        BY_HANDLE_FILE_INFORMATION, FILE_ATTRIBUTE_REPARSE_POINT, GetFileInformationByHandle,
    };

View on GitHub (pinned to 73e0f67d83)