Cloud File Hydration Nudge

Cloud folder hydration nudge for visible but unreadable File Provider, iCloud, OneDrive, Dropbox, Drive, Box, or placeholder files.

Use this skill when files in a cloud-synced folder, shared folder, or macOS File Provider location are visible but cannot yet be read reliably by scripts, document tools, OCR, upload processors, or downstream automation.

Common symptoms:

• File appears in Finder or a directory listing with a normal name and size.
• cat, dd, checksum, parser, OCR, PDF tools, ZIP tools, or import scripts fail.
• Errors mention Resource deadlock avoided, permission/materialization failures, zero-byte reads, invalid file signatures, incomplete archives, or short reads.
• A manual Finder click, provider UI action, preview, or opening the parent folder makes the same file readable afterward.
• A folder marked available offline or always-keep-local still receives new placeholder files.

Do not treat metadata visibility, provider badges, or local-availability settings as proof of local readability. The proof is a successful bounded content read.

Privacy

Keep examples generic. Do not include real client names, private filenames, private paths, hostnames, URLs, account names, secrets, tokens, or document contents.

Use placeholders such as:

text

/path/to/source-cloud-folder
/path/to/source-cloud-folder/example.pdf
/path/to/state/logs

Workflow

1. Identify the blocked file or folder.
2. Confirm the file is visible without modifying it.
3. Run a bounded read probe, such as reading the first 64 KiB to /dev/null.
4. If the read succeeds, the issue is probably downstream, not hydration.
5. If the read fails, treat it as a cloud materialization/hydration problem unless other evidence proves corruption.
6. Inspect provider state when available.
7. Trigger the least-invasive hydration nudge suitable for the provider.
8. Repeat the exact same bounded read probe.
9. Continue with the downstream workflow only after the read succeeds.
10. Leave a short log note distinguishing pre-nudge failure, nudge action, post-nudge read result, and downstream outcome.

Read Probe

Use a bounded read rather than opening or copying the entire file first.

Example shape:

bash

dd if="/path/to/source-cloud-folder/example.pdf" of=/dev/null bs=64k count=1

For content-specific workflows, follow with a lightweight content-aware check:

• PDF: file, pdfinfo, or first-page extraction.
• ZIP/Office: unzip -t or central-directory check.
• Image: metadata probe.
• General files: checksum after hydration, not before.

macOS File Provider Notes

On macOS File Provider-backed folders, separate three questions:

• Can the automation enumerate the file path?
• Does provider metadata claim the file is downloaded/current or pinned?
• Can a normal process actually read stable bytes?

fileproviderctl evaluate <path> can inspect provider state and actions. Treat this as diagnostic information, not final proof of readability.

Finder metadata, Spotlight metadata, file size, provider downloaded state, and provider pinning state may still disagree with actual POSIX reads.

Offline Pinning Is Not Proof

Provider features such as Always Keep on This Device, Download Now, Make Available Offline, or folder pinning are useful preferences, but they are not reliable proof that every new child file is locally readable.

On some macOS/File Provider/provider-version combinations, a folder may appear downloaded/current while new files still arrive as cloud placeholders or dataless files. Some beta OS or provider builds may make this worse.

Use offline pinning as the first provider-level fix, but verify it causally:

1. Mark the folder available offline.
2. Add a new file from another device or the provider web UI.
3. Wait for the target machine to see the filename.
4. Run the bounded read probe before any manual click/open.
5. Trust the feature only if the read succeeds without another nudge.

iCloud Drive Nudge

For iCloud Drive files, the cleanest programmatic nudge is the native iCloud download request plus a bounded read wait.

Generic implementation shape:

1. Check whether the item is an iCloud ubiquitous item.
2. Call the platform API equivalent of startDownloadingUbiquitousItem.
3. Poll a bounded read until it succeeds or times out.
4. Return success only after the read succeeds.

In causal testing, an evicted iCloud file appeared as a normal-size dataless file and failed reads with Resource deadlock avoided. A Finder folder update alone did not hydrate it. The native iCloud download request plus bounded read polling did.

OneDrive Nudge

For OneDrive File Provider folders on macOS, folder-level Finder update/open and Always Keep on This Device may not be sufficient.

A proven pattern is file-level Quick Look:

1. Confirm pre-nudge read failure with a bounded read.
2. Confirm state when possible, such as dataless, isDownloaded = 0, or isMostRecentVersionDownloaded = 0.
3. Prefer a supported provider download/materialization action if one exists in the environment.
4. If no supported provider-native action is available, run a bounded file-level Quick Look preview/open action, such as qlmanage -p <file>, only as an explicit fallback.
5. Close/kill the preview after a short bounded interval.
6. Poll the same bounded read until it succeeds or times out.
7. Continue only after the read succeeds.

Because Quick Look may show UI and invokes file parsers, avoid running it blindly on a schedule. Trigger it only after a real read/materialization failure, preferably with explicit operator intent or a narrow allowlist, and keep the preview duration and post-nudge read wait bounded. Prefer provider-native folder/file download requests when available.

Other Providers

For Dropbox, Google Drive for Desktop, Box, Synology Drive, and similar providers, use the provider's normal local-availability mechanism:

• Always Keep on This Device
• Download Now
• Make Available Offline
• opening/updating the parent folder in Finder or provider UI
• a provider-specific CLI/API when available

Prefer provider-supported download/materialization actions over brittle UI scripting. If no CLI/API is available, a user-context Finder/Automator/Shortcuts wrapper may still be useful.

Do not assume an iCloud-specific API works for other providers.

Wrapper Pattern

When automation repeatedly fails because files are visible but unreadable, add a hydration wrapper before the downstream script or inside the first failure branch.

The wrapper should:

• enumerate or receive explicit file paths in the narrowest permission context available;
• try a bounded read first;
• request provider hydration only after the read fails;
• wait for a bounded read probe to succeed;
• pass only readable files to the downstream workflow;
• log retryable waiting states instead of treating placeholders as corruption.

The downstream workflow should still validate the full file before doing irreversible work.

Logging And Evidence

Keep logs useful but privacy-preserving. Distinguish these states without exposing private material:

• pre-nudge read failed: metadata is visible, bytes are not readable.
• hydrating: a provider-specific nudge is being attempted.
• post-nudge read succeeded: the same bounded read now works.
• post-nudge read timed out: leave the file in place for retry/manual provider handling.
• downstream complete: the consuming workflow independently verified its result.

Do not log real client names, private paths, private filenames, document contents, secrets, tokens, account names, URLs, or hostnames in reusable examples or shared reports. Use placeholders or local-only debug logs when exact filenames are necessary for immediate troubleshooting.

Causal Test Pattern

Do not claim the nudge works just because a freshly local file succeeds.

A stronger test is:

1. Create or obtain a file that is visible but not locally readable.
2. Prove pre-nudge read failure with a bounded read.
3. Capture provider/local state such as dataless, placeholder, or materialization error where available.
4. Run only the hydration nudge or wrapper.
5. Prove the same bounded read now succeeds.
6. Run the downstream workflow.
7. Verify the downstream result independently.
8. Clean up test records and artifacts when they were created only for the test.

Safety

Do not delete, move, or overwrite user documents while testing hydration.

Use disposable test files when possible. If cleanup is needed for generated test records or local artifacts, make sure they are yours or get explicit approval.

Avoid broad Full Disk Access changes for shell runtimes unless the user explicitly accepts the wider security surface. Prefer user-facing automation layers or provider-specific APIs with narrower scope.

Treat preview/Quick Look hydration as higher risk than provider-native download APIs because it invokes file parsers. Prefer provider-native folder/file download requests when available.