fix(mountsync): prioritize writeback during full pulls

[khaliqgant]

Summary

• let latency-sensitive mount writeback acquire the Syncer state lock while a full export/tree/tar pull is blocked on remote I/O
• preserve serialization for every state mutation and remember paths only after a proven accepted write/delete so a resumed point-in-time snapshot cannot overwrite or tombstone a newer local draft
• start the daemon watcher before initial bootstrap, eliminating the draft blind window during a large first mirror
• serialize watcher and mount-loop status/auth transitions exposed by the earlier watcher startup

Root cause

syncReserved held the single Syncer.mu across the complete full-pull wall clock. HandleLocalChange, /fs/bulk admission, and durable receipt polling all need that mutex, so a multi-minute down-mirror serialized local writeback behind it. The daemon also started its watcher only after initial bootstrap returned.

The lock split is deliberately narrow: full-pull transport/body reads release mu; export/tree/tar apply and all state changes remain under it. Large apply loops yield between files. Paths whose write was accepted by /fs/bulk, successfully deleted, or observed already absent are skipped by stale content and snapshot-delete application. No-op watcher events and per-path write errors leave the snapshot authoritative.

Starting the watcher earlier also made its callback concurrent with initial runCycle, exposing a status tuple race that already existed during periodic cycles. A mount-loop-local mutex now protects only tuple copies/transitions (degraded, stall/recovery timing, attempts, and lastSuccess) and is never held across auth, sync, watcher writeback, logging, network, or file I/O. Credential refresh is independently serialized.

Covered down-path variants:

• atomic ExportFiles
• paginated ListTree plus parallel ReadFile
• GitHub manifest/cursor/tree/tar request
• streaming tar body reads and close
• bounded cursor resolution immediately bracketing bootstrap

Red-first evidence

TestFullPullDoesNotStarveLocalDraftAdmissionOrReceiptSettlement captures an export snapshot, blocks its return, writes a Slack draft, and requires /fs/bulk, GetOperation, and the acked receipt to complete before releasing the export.

On baseline it deterministically failed at the 750ms bound:

local /fs/bulk admission and receipt settlement were starved by the blocked full pull (pull=<nil> write=<nil>)

Both calls completed only after the export was released.

The TAR and TREE variants fail at the same 750ms starvation bound with the baseline lock behavior. Their green versions explicitly prove GitHub tar dispatch and paginated tree/parallel-read dispatch, receipt settlement, and non-clobber.

Two no-op regressions fail on the first PR head: Chmod on unchanged content incorrectly claims the up-path and suppresses an authoritative remote update or confirmed remote delete. Paired green tests prove only genuine accepted upload/delete ownership defeats a stale snapshot.

TestMountLoopSerializesStatusWhenWatcherAndInitialBootstrapFailTogether releases simultaneous credential failures from a blocked initial export and watcher writeback. Before the status fix, go test -race deterministically reports races on degraded and lastDegradedNotice; it is green after serialization.

Validation

• go test ./... -count=1 — green across every package
• go test -race ./internal/mountsync ./cmd/relayfile-cli -count=1 — green (122.566s, 92.257s)
• focused TAR/TREE/export, no-op update/delete, genuine upload/delete, and watcher/status concurrency tests under -race — green
• go vet ./... — green
• make build — green for CLI, server, and mount binaries
• git diff --check — green

Safety

• no API/schema behavior change
• no production, credential, or live-workspace actions
• no merge requested or performed

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[coderabbitai]

Warning

Review limit reached

@khaliqgant, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 22 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: dd9e9966-348d-4eb9-a3ed-b9ff7ac6d1a3

📥 Commits

Reviewing files that changed from the base of the PR and between 8d046d4 and 31d1522.

📒 Files selected for processing (4)

• cmd/relayfile-cli/main.go
• cmd/relayfile-cli/mount_up_path_priority_test.go
• internal/mountsync/syncer.go
• internal/mountsync/syncer_test.go

📝 Walkthrough

Walkthrough

The mount loop now starts its local watcher before initial reconciliation. Full pulls release locks around remote I/O, track concurrent local changes, and avoid replaying stale snapshot data or tombstones over those changes. Regression tests cover blocked bootstrap and full-pull concurrency.

Changes

Mount bootstrap concurrency

Layer / File(s)	Summary
Full-pull lock splitting and touched-path protection internal/mountsync/syncer.go, internal/mountsync/syncer_test.go	Full pulls release synchronization locks around remote operations, yield during snapshot application, track locally touched paths, and skip stale file replay or tombstones. Tests coordinate blocked exports and verify draft admission, receipt settlement, and preservation.
Watcher startup before initial reconciliation cmd/relayfile-cli/main.go, cmd/relayfile-cli/mount_up_path_priority_test.go	Non-once mounts start the watcher before the initial cycle; tests verify local writes are uploaded and settled while bootstrap export remains blocked.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant runMountLoop
  participant FileWatcher
  participant Syncer
  participant RemoteClient
  runMountLoop->>FileWatcher: Start before initial reconciliation
  FileWatcher->>Syncer: HandleLocalChange for local draft
  Syncer->>RemoteClient: WriteFilesBulk
  Syncer->>RemoteClient: GetOperation
  runMountLoop->>Syncer: runCycle(true)

Loading

Possibly related PRs

• AgentWorkforce/relayfile#261: Both changes modify applyRemoteFile handling for specific remote-path conditions.

Suggested reviewers: kjgbot

Poem

I’m a rabbit who watches the tree,
While bootstrap waits patiently.
Fresh drafts hop through the queue,
Old snapshots cannot overwrite what’s new.
Locks yield, receipts glow—
Happy burrows now flow!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title accurately summarizes the main change: prioritizing local writeback during full pulls.
Description check	✅ Passed	The description is directly about the mountsync concurrency and watcher-start changes in this PR.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/mount-up-path-nonstarvation

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Relayfile Eval Review

Run: .relayfile/evals/runs/2026-07-14T18-49-51-360Z-HEAD-provider
Mode: provider
Git SHA: 43bf0a4

Passed: 4 | Needs human: 0 | Reviewable: 0 | Missing output: 0 | Failed: 0 | Skipped: 0

Human Review Cases

No reviewable human-review cases captured Relayfile output.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8d046d44ad

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[cubic-dev-ai]

All reported issues were addressed across 4 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[khaliqgant]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.