CS-11062: protect local edits in `boxel realm watch start` by FadhlanR · Pull Request #4844 · cardstack/boxel

FadhlanR · 2026-05-15T10:03:47Z

Summary

boxel realm watch start no longer silently overwrites local edits. When the local copy of a remotely-changed file diverges from .boxel-sync.json, the watcher skips the download (or unlink), logs ⚠ skipped <file>: local diverges from sync manifest …, and keeps polling.
A new --overwrite-local flag restores the previous unconditional mirror behavior.
Skipped files keep their old lastKnownMtimes so the warning re-fires every poll until the user reconciles via boxel realm sync … (e.g. --prefer-newest) or reruns watch with --overwrite-local.

How

Divergence gate lives in RealmWatcher.flushPending so both first-tick (tickAll) and steady-state polls hit one code path. Per-flush, the manifest is loaded once and reused across all checks in that flush.
FlushResult gains skipped: string[]; logFlush prints one yellow ⚠ skipped … line per file.
watchRealms threads overwriteLocal from CLI → RealmWatcher constructor.
No changes to sync-manifest.ts / sync-logic.ts / realm-sync-base.ts — computeFileHash / loadManifest are reused.
.boxel-history checkpoint creation is now skipped on fully-skipped flushes (changes.length === 0); applied flushes still snapshot as before.

Tests added (in `packages/boxel-cli/tests/integration/realm-watch.test.ts`)

skips download when the local file diverges from the sync manifest
overwrites diverged local files when overwriteLocal is enabled
skips first-run downloads when local files exist at remote paths and no manifest
downloads when the local file still matches the manifest hash
does not delete a locally-edited file when the remote disappears
deletes the local file when the remote disappears and the local matches the manifest
keeps re-detecting a skipped divergence on subsequent polls until resolved

Test plan

CI runs packages/boxel-cli integration suite green (it wasn't run locally — needs Synapse + realm-server up).
Manual smoke against a real realm: sync a dir, edit a file locally, change the same file remotely (e.g. via UI), run watch start → expect the yellow ⚠ skipped … line and the local file untouched.
Same setup with --overwrite-local → expect the local file replaced and no skipped line.
Delete .boxel-sync.json from a populated dir, run watch start → expect every existing file to skip with a warning on the first poll; non-overlapping remote files still pulled.
Reconcile with boxel realm sync --prefer-newest → re-run watch and confirm the warning stops.

Notes

Plugin plugin.json version bump is intentionally deferred to the final pre-merge commit.
Skill prose in plugin/skills/realm-sync/SKILL.md documents both the new default and the "run boxel realm pull first when seeding a pre-populated directory" caveat (otherwise every file looks diverged on first poll).

🤖 Generated with Claude Code

Flip the default so the watcher skips a remote-driven download (or unlink) when the local file's hash diverges from `.boxel-sync.json`, instead of silently overwriting. Pass `--overwrite-local` to opt back into the old unconditional mirror behavior. Skipped files keep their old `lastKnownMtimes` so the warning re-fires on every poll until the user reconciles via `boxel realm sync …` or reruns with `--overwrite-local`. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0f8063d966

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

chatgpt-codex-connector · 2026-05-15T10:15:39Z

+    const manifest = this.overwriteLocal
+      ? null
+      : await loadManifest(this.options.localDir);


Ignore manifests from other realms before divergence checks

Treating any .boxel-sync.json as the divergence baseline can silently bypass the new local-edit protection when the manifest belongs to a different realm. In that case, localDivergesFromManifest may see a matching hash and allow overwrite/delete, even though this watch session has no valid sync baseline for this realm. initialize() already guards remoteMtimes with a realm URL match, so flushPending() should similarly discard mismatched manifests (or pass null) before hash comparisons to avoid unintended local data loss.

Useful? React with 👍 / 👎.

Copilot

Pull request overview

This PR changes boxel realm watch start so remote changes no longer overwrite locally diverged files by default, while adding an opt-in flag to restore prior mirroring behavior.

Changes:

Adds divergence detection during watcher flushes and reports skipped files.
Threads --overwrite-local through the CLI and watcher options.
Adds integration coverage and updates realm-sync skill docs for the new behavior.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.

File	Description
`packages/boxel-cli/src/commands/realm/watch/start.ts`	Implements skipped flush results, divergence checks, logging, and CLI flag wiring.
`packages/boxel-cli/tests/integration/realm-watch.test.ts`	Adds integration tests for skipped downloads/deletes and overwrite behavior.
`packages/boxel-cli/plugin/skills/realm-sync/SKILL.md`	Documents the new watch default and `--overwrite-local` option.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+   * True when a local file exists at `localPath` but its content no longer
+   * matches the hash recorded for `relPath` in the sync manifest (or the
+   * manifest has no record of it at all). False when no local file exists
+   * — there's nothing to protect.
+   */
+  private async localDivergesFromManifest(
+    localPath: string,
+    relPath: string,
+    manifest: SyncManifest | null,
+  ): Promise<boolean> {
+    let localHash: string;
+    try {
+      localHash = await computeFileHash(localPath);
+    } catch (err: any) {
+      if (err.code === 'ENOENT') return false;
+      throw err;
+    }
+    const manifestHash = manifest?.files[relPath];


+    const manifest = this.overwriteLocal
+      ? null
+      : await loadManifest(this.options.localDir);
+
    for (const [file, info] of drained) {
+      const localPath = path.join(this.options.localDir, file);
+
+      if (
+        !this.overwriteLocal &&
+        (await this.localDivergesFromManifest(localPath, file, manifest))


+    let checkpoint: Checkpoint | null = null;
+    if (changes.length > 0) {
+      await this.persistManifest(pulled, deleted);
+      checkpoint = await this.checkpointManager.createCheckpoint(



 `push` and `pull` have their own `--delete` and `--dry-run` flags but no `--prefer-*` flags (they're one-directional). When in doubt, dry-run first.

+`watch` protects local edits without a flag: by default any file whose local hash differs from the sync manifest is skipped (with a yellow `⚠ skipped …` line) instead of overwritten. The warning re-fires on every poll until the user reconciles via `boxel realm sync …` (e.g. `--prefer-newest`) or rerun watch with `--overwrite-local` to accept the remote.


FadhlanR marked this pull request as ready for review May 15, 2026 10:12

FadhlanR requested a review from a team May 15, 2026 10:12

chatgpt-codex-connector Bot reviewed May 15, 2026

View reviewed changes

habdelra requested a review from Copilot May 15, 2026 13:10

jurgenwerk approved these changes May 18, 2026

View reviewed changes

habdelra requested review from Copilot and removed request for Copilot May 18, 2026 12:39

Copilot started reviewing on behalf of habdelra May 18, 2026 12:40 View session

Copilot AI reviewed May 18, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CS-11062: protect local edits in `boxel realm watch start`#4844

CS-11062: protect local edits in `boxel realm watch start`#4844
FadhlanR wants to merge 1 commit into
mainfrom
cs-11062-make-realm-watch-avoid-overwriting-local-changes

FadhlanR commented May 15, 2026 •

edited

Loading

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot May 15, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		`push` and `pull` have their own `--delete` and `--dry-run` flags but no `--prefer-*` flags (they're one-directional). When in doubt, dry-run first.

		`watch` protects local edits without a flag: by default any file whose local hash differs from the sync manifest is skipped (with a yellow `⚠ skipped …` line) instead of overwritten. The warning re-fires on every poll until the user reconciles via `boxel realm sync …` (e.g. `--prefer-newest`) or rerun watch with `--overwrite-local` to accept the remote.

Conversation

FadhlanR commented May 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

How

Tests added (in packages/boxel-cli/tests/integration/realm-watch.test.ts)

Test plan

Notes

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot May 15, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

FadhlanR commented May 15, 2026 •

edited

Loading

Tests added (in `packages/boxel-cli/tests/integration/realm-watch.test.ts`)