[veryCrunchy]

Outcome

Completes #477 for the remaining desktop file writes. After the server accepts a write, the caller gets the server result promptly. The local refresh (retained-folder refresh, virtual-file metadata and read-cache invalidation, hydration scheduling) runs in the background, and its result is reported as localFollowUp, the same way executeFileMutation has worked since #498.

Before this change, these writes refreshed local state inline and could wait on virtualFileProviderLock, an uninterruptible lock that Windows Cloud Files and Linux mounts can hold for a long time:

• saveTextFile, createTextFileIfAbsent, createDirectoryIfAbsent
• setFileFavorite and restoreFileVersion
• folder-sync upload commits (fileSyncEngine.onRemoteMutationCommitted) and Linux mount writes (afterMutationInvalidated)

Changes:

• DesktopFileWrites.kt (new): owns the desktop write operations behind a narrow transport interface. Each write uses the same reconcile-then-bounded-wait pattern, so these all carry over: account fencing and abandonment, first-result-wins, attaching to a queued or running refresh, a typed Failed on a full queue, and the dropped-reconciliation error for an unknown result that cannot be queued.
• DesktopFileMutationFollowUps.afterBackgroundMutation: used by sync uploads and mount writes, which have no waiting caller. It queues without blocking. On a full queue it refreshes on the calling thread and records a diagnostic instead of dropping the refresh, because no caller would see a failure.
• UI: the text editor save, create folder and create file notice, favorite notice, and version restore message show the shared FileMutationLocalFollowUp.reportFor copy when the local follow-up is still running or failed. Uploads still report "uploaded" only after server confirmation.
• Android: save, create, folder creation and favorite report a failed cache invalidation instead of ignoring it. Version restore now invalidates the read cache.
• Lock order: every refresh path keeps the fix(desktop): take virtual-file locks in one order #510 order (provider lock, then activation monitor via tryActivateVirtualFileResource). The follow-up queue's lock is never held while a refresh runs.

DesktopNextcloudServices.kt shrinks from 6161 to 5987 lines, and its baseline is lowered. A new "Local follow-up after file writes" section in ADAPTER_ARCHITECTURE.md documents the behavior.

Out of scope: the downloadFile 404 refresh (a read) can still wait on the same lock. It is tracked in #523.

Verification

• Every check relevant to the changed scope passes, or each unrun check is listed below with a reason

• bash tools/check-repository.sh passes

• A new changes/unreleased/ fragment records the change

• No credentials, private server data, machine-local paths, or generated output are included

• New DesktopFileWritesTest (6 tests) uses a test thread holding a stand-in provider lock that each refresh waits on:

  • each of the six writes returns promptly with StillRunning and the shared copy;
  • caller cancellation surfaces as CancellationException while the queued refresh still runs;
  • account abandonment fails running and queued writes and ignores the late completion;
  • a full queue gives the typed result;
  • an unknown result does not wait for the stuck refresh;
  • a 412 queues nothing.

• DesktopFileMutationFollowUpsTest (+3): background refreshes never block, refresh inline on a full queue, and stop after teardown.

• TextEditorStateTest and FileVersionHistoryTest (+1 each): copy for each follow-up state.

• Full :ui:desktopTest --rerun (4082 tests, 71 skipped, 0 failures) and :androidApp:testDebugUnitTest --rerun (1183 tests, 0 failures), on Windows with JDK 21.

• :ui:lintAnalyzeRelease, bash tools/check-kotlin-architecture.sh and bash tools/check-repository.sh pass.

Limit: the lock tests target DesktopFileWrites with a stand-in lock, not the private virtualFileProviderLock, because constructing DesktopNextcloudServices in a test needs real preferences and a real secret store. No manual run against a live Windows Cloud Files or Linux mount was done.

Compatibility and risk

Desktop and Android. Return types changed for createDirectoryIfAbsent (now DirectoryCreation), setFileFavorite and restoreFileVersion (now FileMutationLocalFollowUp). SavedTextFile gained localFollowUp, which defaults to completed. Network failures in the newly routed desktop writes now surface as not-sent or outcome-unknown errors, matching executeFileMutation.

Visual changes

Not applicable. Only status copy changes when local follow-up is incomplete.

[obiente-cloud]

Obiente preview

NC Native · 48435531e62f · Ready

Open preview

View in Obiente

_{Obiente updates this comment as the preview changes.}

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-25T14:44:00.838716Z	9e0072f	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.