Skip to content

Local Change-Feed Delta Sync

Local change-feed delta sync uses a dedicated runner to observe filesystem changes on a local source path and plan targeted updates after a trusted baseline exists.

When you will see it

Local change-feed controls appear only for local-source jobs assigned to a dedicated runner that reports local change-feed support. They are hidden for non-local source jobs.

The assigned runner must be online before you can run readiness checks or enable monitoring.

What operators should expect

  • the setting is job-specific
  • the source must be a local filesystem path visible to the assigned runner
  • the runner must report a supported operating system and watcher capability
  • preflight includes the smoke test and is the single readiness action
  • the first live run may still perform a full-tree baseline before targeted change-feed delta can be trusted
  • if watcher context is missing or unsafe, the job falls back to scoped or full sync behavior instead of trusting incomplete local events

Readiness workflow

  1. Assign the job to the dedicated runner that can see the local source path.
  2. Select local change-feed delta in the job Sync Strategy tab.
  3. Save the job configuration.
  4. Run preflight from the job detail local change-feed panel.
  5. Review the latest preflight and smoke-test results.
  6. Enable monitoring only after preflight reports Ready.
  7. Run the first live baseline if the job has not completed one yet.

Preflight checks path visibility, source identity, watcher support, and required runner host limits. The integrated smoke test asks the runner to prove that expected local events can be observed for the selected source root.

Watcher session and cursor behavior

A watcher session is the runner's current observation of a local source path. It reports state such as monitoring, paused, degraded, blocked, or reset required.

The change-feed cursor is not just a timestamp. It is the trusted watcher resume state plus related metadata that tells the system where the next local-event window can safely continue. A timestamp can help explain recency, but it is not enough by itself to prove event continuity.

Full-tree baseline runs reset the local change-feed cursor because the target has been reconciled from the complete source tree. After that reset, new trusted watcher events can become the next targeted delta input.

Fallback behavior

Fallback sync is expected when the system cannot safely trust a targeted local event plan. Common reasons include:

  • no trusted watcher session has been reported yet
  • preflight has not returned Ready
  • the runner was offline or stale
  • the source mount identity changed
  • the cursor was reset by a full-tree baseline
  • a folder-level event is safer to apply as a scoped folder sync

Fallback should use the configured source and target paths. If a run appears to sync an unexpected location, stop and review the job source path, target path, runner assignment, and latest preflight result before continuing.

Operating system support

Local change-feed support depends on the runner host operating system. macOS and Linux runners can report their local watcher capability when configured correctly. Windows support requires the runner to report Windows host metadata and use a Windows filesystem watcher implementation before local change-feed monitoring should be enabled for Windows paths.

Until a Windows runner reports that capability, use ordinary tree sync for Windows local-source jobs.

Operational checks

Review the local change-feed panel on the job detail page for:

  • runner status
  • monitoring intent
  • preflight status
  • latest preflight result
  • latest smoke-test result
  • watcher state
  • cursor status
  • latest local event
  • reconciliation scan timing

Run a reconciliation scan when local change-feed activity has been running for a while, after watcher resets, or after a period of degraded monitoring.

See also