@doubling/compound-sync 1.12.4 → 1.12.6

package/org-sync.js

@@ -11,1270 +11,1223 @@
 // caller. Behavior is otherwise unchanged (including the known
 // mtime-based decision quirks DOU-154 will rework, those stay so the
 // scenario tests can pin them red first).
-
 import chokidar from 'chokidar';
-import fs from 'fs';
-import path from 'path';
-import { collection, query, where, onSnapshot, getDocs } from 'firebase/firestore';
-import {
-  pushFileToCloud,
-  deleteFileFromCloud,
-  pushFolderToCloud,
-  deleteFolderFromCloud,
-  readBlob,
-  readBlobAsText,
-  extFromPath,
-  isTextMimeType,
-  mimeTypeFromExt,
-  computeContentHash,
-} from './files.js';
-import {
-  scopeFromLocalPath,
-  teamFolderName,
-  PRIVATE_FOLDER,
-  SHARED_WITH_ME_FOLDER,
-  SHARED_BY_ME_FOLDER,
-} from './paths.js';
+import fs from 'node:fs';
+import path from 'node:path';
+import { collection, query, where, onSnapshot, getDocs, } from 'firebase/firestore';
+import { pushFileToCloud, deleteFileFromCloud, pushFolderToCloud, deleteFolderFromCloud, readBlob, readBlobAsText, extFromPath, isTextMimeType, mimeTypeFromExt, computeContentHash, } from './files.js';
+import { scopeFromLocalPath, teamFolderName, PRIVATE_FOLDER, SHARED_WITH_ME_FOLDER, SHARED_BY_ME_FOLDER, } from './paths.js';
 import { TeamRegistry } from './team-registry.js';
 import { loadSyncState, saveSyncState } from './sync-state.js';
 import { createManifestStore } from './manifest.js';
 import { shouldPersistLocalSyncState } from './push-outcome.js';
 import { FirestoreUpdateStore } from './yjs-firestore-update-store.js';
 import { YjsFileBinding } from './yjs-file-binding.js';
-import {
-  loadBindingState, saveBindingState, deleteBindingState,
-} from './yjs-binding-state.js';
-
+import { loadBindingState, saveBindingState, deleteBindingState, } from './yjs-binding-state.js';
 const DEFAULT_MAX_UPLOAD_BYTES = 25 * 1024 * 1024;
-
-// Retry a blob download until either the bytes appear at all (covers
-// the create race: doc written before blob upload) AND the content
-// hash matches the metadata's `contentHash` (covers the update race:
-// the blob still has the old bytes when the new doc is already
-// visible). Backs off 100/200/400/800 ms (1.5s total) across both
-// failure modes. Other errors throw immediately.
 async function readBlobWithRetry(read, { expectedHash = null, maxAttempts = 5 } = {}) {
-  let delay = 100;
-  let lastErr;
-  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-    try {
-      const content = await read();
-      if (!expectedHash || computeContentHash(content) === expectedHash) {
-        return content;
-      }
-      lastErr = new Error(
-        `blob hash does not match metadata contentHash (attempt ${attempt}/${maxAttempts})`,
-      );
-    } catch (err) {
-      if (err?.code !== 'storage/object-not-found') throw err;
-      lastErr = err;
-    }
-    if (attempt < maxAttempts) {
-      await new Promise((resolve) => setTimeout(resolve, delay));
-      delay *= 2;
+    let delay = 100;
+    let lastErr;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            const content = await read();
+            if (!expectedHash || computeContentHash(content) === expectedHash) {
+                return content;
+            }
+            lastErr = new Error(`blob hash does not match metadata contentHash (attempt ${attempt}/${maxAttempts})`);
+        }
+        catch (err) {
+            if (err?.code !== 'storage/object-not-found')
+                throw err;
+            lastErr = err;
+        }
+        if (attempt < maxAttempts) {
+            await new Promise((resolve) => setTimeout(resolve, delay));
+            delay *= 2;
+        }
     }
-  }
-  throw lastErr;
+    throw lastErr;
 }
-
 // Start the per-org sync loop. Returns { stop } to unsubscribe all
 // listeners and close the watcher (used by tests and by graceful
 // shutdown). `localPath` must already be absolute/expanded.
-export async function startOrgSync({
-  db,
-  storage,
-  userId,
-  orgId,
-  localPath,
-  maxUploadBytes = DEFAULT_MAX_UPLOAD_BYTES,
-  statePath,
-}) {
-  const LOCAL_PATH = localPath;
-  const filesRef = collection(db, `orgs/${orgId}/files`);
-  // Where the per-folder content baseline is persisted. Default: a
-  // dotfile in the synced folder (ignored by the watcher), so it travels
-  // with the folder and needs no extra wiring from the caller.
-  const STATE_PATH = statePath ?? path.join(LOCAL_PATH, '.compound-sync-state.json');
-  const manifestStore = createManifestStore(LOCAL_PATH);
-
-  // Teardown handles: every onSnapshot unsub plus the chokidar watcher.
-  const unsubscribers = [];
-  let watcher = null;
-
-  const lastKnownUpdate = new Map();
-  // Content hash of each file as of the last successful sync (push or
-  // pull), keyed by trackingKey. This "baseline" decides pull/push
-  // direction by CONTENT rather than filesystem mtime (which an editor
-  // like Obsidian bumps without a content change). Loaded from
-  // STATE_PATH so it survives restarts; persisted on every change.
-  const lastSyncedHash = new Map(Object.entries(loadSyncState(STATE_PATH)));
-  function persistBaseline() {
-    saveSyncState(STATE_PATH, Object.fromEntries(lastSyncedHash));
-  }
-  function setBaseline(key, hash) { lastSyncedHash.set(key, hash); persistBaseline(); }
-  function deleteBaseline(key) { lastSyncedHash.delete(key); persistBaseline(); }
-  const suppressLocal = new Set();
-
-  // Per-file Yjs bindings, created on first sight of a text file
-  // (DOU-178 PR 3). The binding owns the live Y.Doc that mirrors
-  // orgs/.../yupdates and the debounced disk flush. We keep two
-  // indexes: by fileId (so handleFirestoreChange can dispose on
-  // 'removed' and re-use across events) and by local path (so the
-  // chokidar handler can route disk edits into the binding without
-  // re-resolving the fileId).
-  const bindings = new Map();
-  const bindingsByPath = new Map();
-
-  // DOU-205: per-fileId record of the most recently observed Firestore
-  // metadata (local path + tracking key). Used to detect renames /
-  // moves on subsequent 'modified' snapshot events: when the file
-  // doc's path changes server-side (via the web rename UI), the local
-  // path computed from the new data also changes, and this map lets
-  // the handler relocate the local file in place (fs.renameSync,
-  // which preserves Obsidian's inode-level tracking) rather than
-  // leaving the old file orphaned at its previous location.
-  const knownPaths = new Map();
-
-  // Track which fileIds already have a binding (or one being set
-  // up) so we never double-create. `stoppedRef` is read by the
-  // background retry loops so they can abandon work after sync.stop.
-  // `pendingPromises` lets stop() await any in-flight setup OR any
-  // fire-and-forget snapshot/chokidar handler work before returning.
-  // Without this, the next test's clearFirestore + terminate can
-  // race a handler that's still flushing storage from this test,
-  // surfacing as "Firebase app was deleted" errors in the daemon log
-  // and (suspected) accumulating gRPC stream state that the next
-  // listener attach receives as a single oversize Listen message.
-  const pendingBindings = new Set();
-  const pendingPromises = new Set();
-  const stoppedRef = { value: false };
-
-  // Helper: register a promise with pendingPromises so stop() awaits
-  // it, and auto-remove on settle. Returns the same promise so call
-  // sites can keep their chaining shape.
-  function track(p) {
-    pendingPromises.add(p);
-    p.finally(() => pendingPromises.delete(p));
-    return p;
-  }
-
-  // DOU-254: per-local-path operation queue. chokidar can fire `add`
-  // then `unlink` for the same path within a few hundred ms (a test
-  // writes a file, waits only for the Firestore doc to appear, then
-  // deletes locally). Without serialization, the push (setDoc +
-  // uploadBlob) and the delete (preRecheck + deleteBlob + deleteDoc)
-  // race against each other on the same fileId, and uploadBlob can
-  // land AFTER deleteBlob, leaving an orphaned blob after the doc is
-  // gone. Chain ops keyed by local path so the next op starts only
-  // after the previous one settles.
-  const localOpQueues = new Map();
-  function enqueueLocalOp(filePath, op) {
-    const prev = localOpQueues.get(filePath) || Promise.resolve();
-    // Swallow the previous op's rejection so a failed push doesn't
-    // skip the subsequent delete (or vice versa); each op handles
-    // its own errors via the .catch() at the call site.
-    const next = prev.catch(() => {}).then(op);
-    localOpQueues.set(filePath, next);
-    next.finally(() => {
-      if (localOpQueues.get(filePath) === next) localOpQueues.delete(filePath);
-    });
-    return next;
-  }
-
-  // Fire-and-forget binding setup. Returns nothing because the
-  // common shape "ensureBinding then read its ytext" runs straight
-  // into a race: the daemon's onSnapshot fires on Alice's own
-  // optimistic write before the file doc is server-committed, and
-  // the Firestore rules engine evaluates the yupdates/yjs nested
-  // rule via a server-side get() against the parent files/{id}
-  // doc. That get() sees no doc and returns null, so binding.start
-  // fails with permission-denied; the right behavior is to retry
-  // until the commit propagates, not to block handleFirestoreChange
-  // for seconds. Callers fall back to the blob path while the
-  // binding is still being set up; once it lands in
-  // bindings/bindingsByPath, subsequent events take the Yjs path.
-  function ensureBinding(fileId, localFilePath) {
-    if (bindings.has(fileId) || pendingBindings.has(fileId)) return;
-    pendingBindings.add(fileId);
-    const onDiskWrite = (text) => {
-      suppressLocal.add(localFilePath);
-      ensureDir(localFilePath);
-      fs.writeFileSync(localFilePath, text, 'utf-8');
-      setTimeout(() => suppressLocal.delete(localFilePath), 1000);
-    };
-    // DOU-209: persist the Y.Doc binary state after every stable
-    // change so the next daemon restart has the right baseline to
-    // merge offline disk edits without losing offline web edits.
-    const onDocStateChange = (encoded) => saveBindingState(LOCAL_PATH, fileId, encoded);
-    // DOU-209: feed the binding's startup-merge with the daemon's
-    // last view (initialDocState) and the current disk content. If
-    // they diverge, the binding applies the diff as Yjs ops so disk-
-    // side offline edits survive the cloud-side replay.
-    const initialDocState = loadBindingState(LOCAL_PATH, fileId);
-    let currentDiskText = null;
-    try {
-      if (fs.existsSync(localFilePath)) {
-        currentDiskText = fs.readFileSync(localFilePath, 'utf-8');
-      }
-    } catch (err) {
-      console.error(`  [${orgId}] could not read ${localFilePath} for binding setup: ${err && err.message}`);
+export async function startOrgSync({ db, storage, userId, orgId, localPath, maxUploadBytes = DEFAULT_MAX_UPLOAD_BYTES, statePath, }) {
+    const LOCAL_PATH = localPath;
+    const filesRef = collection(db, `orgs/${orgId}/files`);
+    // Where the per-folder content baseline is persisted. Default: a
+    // dotfile in the synced folder (ignored by the watcher), so it travels
+    // with the folder and needs no extra wiring from the caller.
+    const STATE_PATH = statePath ?? path.join(LOCAL_PATH, '.compound-sync-state.json');
+    const manifestStore = createManifestStore(LOCAL_PATH);
+    // Teardown handles: every onSnapshot unsub plus the chokidar watcher.
+    const unsubscribers = [];
+    let watcher = null;
+    const lastKnownUpdate = new Map();
+    // Content hash of each file as of the last successful sync (push or
+    // pull), keyed by trackingKey. This "baseline" decides pull/push
+    // direction by CONTENT rather than filesystem mtime (which an editor
+    // like Obsidian bumps without a content change). Loaded from
+    // STATE_PATH so it survives restarts; persisted on every change.
+    const lastSyncedHash = new Map(Object.entries(loadSyncState(STATE_PATH)));
+    function persistBaseline() {
+        saveSyncState(STATE_PATH, Object.fromEntries(lastSyncedHash));
+    }
+    function setBaseline(key, hash) { lastSyncedHash.set(key, hash); persistBaseline(); }
+    function deleteBaseline(key) { lastSyncedHash.delete(key); persistBaseline(); }
+    const suppressLocal = new Set();
+    // Per-file Yjs bindings, created on first sight of a text file
+    // (DOU-178 PR 3). The binding owns the live Y.Doc that mirrors
+    // orgs/.../yupdates and the debounced disk flush. We keep two
+    // indexes: by fileId (so handleFirestoreChange can dispose on
+    // 'removed' and re-use across events) and by local path (so the
+    // chokidar handler can route disk edits into the binding without
+    // re-resolving the fileId).
+    const bindings = new Map();
+    const bindingsByPath = new Map();
+    // DOU-205: per-fileId record of the most recently observed Firestore
+    // metadata (local path + tracking key). Used to detect renames /
+    // moves on subsequent 'modified' snapshot events: when the file
+    // doc's path changes server-side (via the web rename UI), the local
+    // path computed from the new data also changes, and this map lets
+    // the handler relocate the local file in place (fs.renameSync,
+    // which preserves Obsidian's inode-level tracking) rather than
+    // leaving the old file orphaned at its previous location.
+    const knownPaths = new Map();
+    // Track which fileIds already have a binding (or one being set
+    // up) so we never double-create. `stoppedRef` is read by the
+    // background retry loops so they can abandon work after sync.stop.
+    // `pendingPromises` lets stop() await any in-flight setup OR any
+    // fire-and-forget snapshot/chokidar handler work before returning.
+    // Without this, the next test's clearFirestore + terminate can
+    // race a handler that's still flushing storage from this test,
+    // surfacing as "Firebase app was deleted" errors in the daemon log
+    // and (suspected) accumulating gRPC stream state that the next
+    // listener attach receives as a single oversize Listen message.
+    const pendingBindings = new Set();
+    const pendingPromises = new Set();
+    const stoppedRef = { value: false };
+    // Helper: register a promise with pendingPromises so stop() awaits
+    // it, and auto-remove on settle. Returns the same promise so call
+    // sites can keep their chaining shape.
+    function track(p) {
+        pendingPromises.add(p);
+        p.finally(() => pendingPromises.delete(p));
+        return p;
     }
-    const setupPromise = (async () => {
-      // Retry binding.start on permission-denied. See note above
-      // about the optimistic-write race with the nested-rule get().
-      // YjsProvider rejects double-start, so each retry needs a
-      // fresh binding (and a fresh provider underneath it).
-      for (let attempt = 0; attempt < 8; attempt++) {
-        if (stoppedRef.value) return;
-        const store = new FirestoreUpdateStore(db, orgId, fileId);
-        const binding = new YjsFileBinding(store, {
-          onDiskWrite, onDocStateChange, initialDocState, currentDiskText,
+    // DOU-254: per-local-path operation queue. chokidar can fire `add`
+    // then `unlink` for the same path within a few hundred ms (a test
+    // writes a file, waits only for the Firestore doc to appear, then
+    // deletes locally). Without serialization, the push (setDoc +
+    // uploadBlob) and the delete (preRecheck + deleteBlob + deleteDoc)
+    // race against each other on the same fileId, and uploadBlob can
+    // land AFTER deleteBlob, leaving an orphaned blob after the doc is
+    // gone. Chain ops keyed by local path so the next op starts only
+    // after the previous one settles.
+    const localOpQueues = new Map();
+    function enqueueLocalOp(filePath, op) {
+        const prev = localOpQueues.get(filePath) ?? Promise.resolve();
+        // Swallow the previous op's rejection so a failed push doesn't
+        // skip the subsequent delete (or vice versa); each op handles
+        // its own errors via the .catch() at the call site.
+        const next = prev.catch(() => undefined).then(op);
+        localOpQueues.set(filePath, next);
+        next.finally(() => {
+            if (localOpQueues.get(filePath) === next)
+                localOpQueues.delete(filePath);
         });
-        try {
-          await binding.start();
-          if (stoppedRef.value) {
-            await binding.stop().catch(() => {});
+        return next;
+    }
+    // Fire-and-forget binding setup. Returns nothing because the
+    // common shape "ensureBinding then read its ytext" runs straight
+    // into a race: the daemon's onSnapshot fires on Alice's own
+    // optimistic write before the file doc is server-committed, and
+    // the Firestore rules engine evaluates the yupdates/yjs nested
+    // rule via a server-side get() against the parent files/{id}
+    // doc. That get() sees no doc and returns null, so binding.start
+    // fails with permission-denied; the right behavior is to retry
+    // until the commit propagates, not to block handleFirestoreChange
+    // for seconds. Callers fall back to the blob path while the
+    // binding is still being set up; once it lands in
+    // bindings/bindingsByPath, subsequent events take the Yjs path.
+    function ensureBinding(fileId, localFilePath) {
+        if (bindings.has(fileId) || pendingBindings.has(fileId))
             return;
-          }
-          bindings.set(fileId, binding);
-          bindingsByPath.set(localFilePath, binding);
-          return;
-        } catch (err) {
-          if (stoppedRef.value) return;
-          if (err?.code !== 'permission-denied' || attempt === 7) {
-            console.error(`  [${orgId}] Yjs binding setup failed for ${fileId}: ${err && err.message}`);
+        pendingBindings.add(fileId);
+        const onDiskWrite = (text) => {
+            suppressLocal.add(localFilePath);
+            ensureDir(localFilePath);
+            fs.writeFileSync(localFilePath, text, 'utf-8');
+            setTimeout(() => suppressLocal.delete(localFilePath), 1000);
+        };
+        // DOU-209: persist the Y.Doc binary state after every stable
+        // change so the next daemon restart has the right baseline to
+        // merge offline disk edits without losing offline web edits.
+        const onDocStateChange = (encoded) => saveBindingState(LOCAL_PATH, fileId, encoded);
+        // DOU-209: feed the binding's startup-merge with the daemon's
+        // last view (initialDocState) and the current disk content. If
+        // they diverge, the binding applies the diff as Yjs ops so disk-
+        // side offline edits survive the cloud-side replay.
+        const initialDocState = loadBindingState(LOCAL_PATH, fileId);
+        let currentDiskText = null;
+        try {
+            if (fs.existsSync(localFilePath)) {
+                currentDiskText = fs.readFileSync(localFilePath, 'utf-8');
+            }
+        }
+        catch (err) {
+            console.error(`  [${orgId}] could not read ${localFilePath} for binding setup: ${err?.message}`);
+        }
+        const setupPromise = (async () => {
+            // Retry binding.start on permission-denied. See note above
+            // about the optimistic-write race with the nested-rule get().
+            // YjsProvider rejects double-start, so each retry needs a
+            // fresh binding (and a fresh provider underneath it).
+            for (let attempt = 0; attempt < 8; attempt++) {
+                if (stoppedRef.value)
+                    return;
+                const store = new FirestoreUpdateStore(db, orgId, fileId);
+                const binding = new YjsFileBinding(store, {
+                    onDiskWrite, onDocStateChange, initialDocState, currentDiskText,
+                });
+                try {
+                    await binding.start();
+                    if (stoppedRef.value) {
+                        await binding.stop().catch(() => undefined);
+                        return;
+                    }
+                    bindings.set(fileId, binding);
+                    bindingsByPath.set(localFilePath, binding);
+                    return;
+                }
+                catch (err) {
+                    if (stoppedRef.value)
+                        return;
+                    const code = err?.code;
+                    if (code !== 'permission-denied' || attempt === 7) {
+                        console.error(`  [${orgId}] Yjs binding setup failed for ${fileId}: ${err?.message}`);
+                        return;
+                    }
+                    await new Promise((r) => setTimeout(r, 150 * (attempt + 1)));
+                }
+            }
+        })().finally(() => {
+            pendingBindings.delete(fileId);
+            pendingPromises.delete(setupPromise);
+        });
+        pendingPromises.add(setupPromise);
+    }
+    async function disposeBinding(fileId, localFilePath) {
+        const binding = bindings.get(fileId);
+        if (!binding)
             return;
-          }
-          await new Promise((r) => setTimeout(r, 150 * (attempt + 1)));
+        bindings.delete(fileId);
+        if (localFilePath)
+            bindingsByPath.delete(localFilePath);
+        await binding.stop();
+        // DOU-209: drop the per-file Y.Doc state so deleted files don't
+        // accumulate stale binding-state blobs under .compound-yjs-binding/.
+        deleteBindingState(LOCAL_PATH, fileId);
+    }
+    // Per-team Firestore-listener unsubscribe handles, keyed by teamId.
+    const teamUnsubscribers = new Map();
+    // Hoisted forward-decl: setupTeam closes over handleFirestoreChange,
+    // which is defined later in this function. Wired below.
+    let setupTeam = () => { };
+    function teardownTeam(teamId, teamData) {
+        const unsub = teamUnsubscribers.get(teamId);
+        if (unsub) {
+            try {
+                unsub();
+            }
+            catch { /* ignore */ }
+            teamUnsubscribers.delete(teamId);
+            const folder = teamData && teamData.name ? teamFolderName(teamData.name) : teamId;
+            console.log(`  [${orgId}]   Stopped listening: ${folder}`);
         }
-      }
-    })().finally(() => {
-      pendingBindings.delete(fileId);
-      pendingPromises.delete(setupPromise);
+    }
+    const teamRegistry = new TeamRegistry({
+        onSetup: (teamId, teamData) => setupTeam(teamId, teamData),
+        onTeardown: teardownTeam,
     });
-    pendingPromises.add(setupPromise);
-  }
-
-  async function disposeBinding(fileId, localFilePath) {
-    const binding = bindings.get(fileId);
-    if (!binding) return;
-    bindings.delete(fileId);
-    if (localFilePath) bindingsByPath.delete(localFilePath);
-    await binding.stop();
-    // DOU-209: drop the per-file Y.Doc state so deleted files don't
-    // accumulate stale binding-state blobs under .compound-yjs-binding/.
-    deleteBindingState(LOCAL_PATH, fileId);
-  }
-
-  // Per-team Firestore-listener unsubscribe handles, keyed by teamId.
-  const teamUnsubscribers = new Map();
-  // Hoisted forward-decl: setupTeam closes over handleFirestoreChange,
-  // which is defined later in this function. Wired below.
-  let setupTeam = () => {};
-  function teardownTeam(teamId, teamData) {
-    const unsub = teamUnsubscribers.get(teamId);
-    if (unsub) {
-      try { unsub(); } catch (e) { /* ignore */ }
-      teamUnsubscribers.delete(teamId);
-      const folder = teamData && teamData.name ? teamFolderName(teamData.name) : teamId;
-      console.log(`  [${orgId}]   Stopped listening: ${folder}`);
+    // scopeFromLocalPath expects a Map<teamName, teamId>; the registry
+    // exposes one matching that shape via teamIdsByNameMap().
+    const teamIdsByName = teamRegistry.teamIdsByNameMap();
+    console.log('');
+    console.log(`  [${orgId}] Local: ${LOCAL_PATH}`);
+    function ensureDir(filePath) {
+        const dir = path.dirname(filePath);
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
     }
-  }
-  const teamRegistry = new TeamRegistry({
-    onSetup: (teamId, teamData) => setupTeam(teamId, teamData),
-    onTeardown: teardownTeam,
-  });
-  // scopeFromLocalPath expects a Map<teamName, teamId>; the registry
-  // exposes one matching that shape.
-  const teamIdsByName = teamRegistry.teamIdsByName;
-
-  console.log('');
-  console.log(`  [${orgId}] Local: ${LOCAL_PATH}`);
-
-  function ensureDir(filePath) {
-    const dir = path.dirname(filePath);
-    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-  }
-
-  function updateSharedByMeSymlink(fileDoc, realPath) {
-    const sharedWith = fileDoc.sharedWith || [];
-    const symlinkPath = path.join(LOCAL_PATH, SHARED_BY_ME_FOLDER, fileDoc.path);
-
-    if (sharedWith.length > 0) {
-      ensureDir(symlinkPath);
-      const relativeTo = path.relative(path.dirname(symlinkPath), realPath);
-      try {
-        if (fs.existsSync(symlinkPath) || fs.lstatSync(symlinkPath).isSymbolicLink()) {
-          fs.unlinkSync(symlinkPath);
+    function updateSharedByMeSymlink(fileDoc, realPath) {
+        const sharedWith = fileDoc['sharedWith'] ?? [];
+        const docPath = fileDoc['path'];
+        // Bail out on a missing / non-string path: path.join would resolve
+        // to the Shared-by-Me root, and a subsequent symlinkSync /
+        // unlinkSync there could clobber the entire folder.
+        if (typeof docPath !== 'string' || !docPath)
+            return;
+        const symlinkPath = path.join(LOCAL_PATH, SHARED_BY_ME_FOLDER, docPath);
+        // Check whether `symlinkPath` exists as anything (regular file,
+        // directory, or symlink including a dangling one). Uses lstatSync,
+        // returns null on ENOENT, rethrows other errors. Beats
+        // `existsSync || lstatSync(...).isSymbolicLink()` which leaned on
+        // a throw-and-catch for the not-found case and could mask real
+        // filesystem errors.
+        function lstatOrNull(p) {
+            try {
+                return fs.lstatSync(p);
+            }
+            catch (e) {
+                if (e?.code === 'ENOENT')
+                    return null;
+                throw e;
+            }
         }
-      } catch (e) { /* doesn't exist */ }
-      try {
-        fs.symlinkSync(relativeTo, symlinkPath);
-        console.log(`  [${orgId}] [symlink] ${fileDoc.path} → Shared by Me/`);
-      } catch (e) {
-        if (e.code !== 'EEXIST') console.error(`  [${orgId}] Symlink error: ${e.message}`);
-      }
-    } else {
-      try {
-        if (fs.lstatSync(symlinkPath).isSymbolicLink()) {
-          fs.unlinkSync(symlinkPath);
-          console.log(`  [${orgId}] [symlink] removed Shared by Me/${fileDoc.path}`);
+        if (sharedWith.length > 0) {
+            ensureDir(symlinkPath);
+            const relativeTo = path.relative(path.dirname(symlinkPath), realPath);
+            const existing = lstatOrNull(symlinkPath);
+            if (existing) {
+                fs.unlinkSync(symlinkPath);
+            }
+            try {
+                fs.symlinkSync(relativeTo, symlinkPath);
+                console.log(`  [${orgId}] [symlink] ${docPath} → Shared by Me/`);
+            }
+            catch (e) {
+                const code = e?.code;
+                if (code !== 'EEXIST')
+                    console.error(`  [${orgId}] Symlink error: ${e?.message}`);
+            }
         }
-      } catch (e) { /* doesn't exist */ }
-    }
-  }
-
-  // Static (user-level) folders. Team folders are mkdir'd by setupTeam,
-  // which runs after manifest reconcile (see startup ordering below).
-  function ensureFolderStructure() {
-    const privatePath = path.join(LOCAL_PATH, PRIVATE_FOLDER);
-    if (!fs.existsSync(privatePath)) fs.mkdirSync(privatePath, { recursive: true });
-
-    const sharedWithMePath = path.join(LOCAL_PATH, SHARED_WITH_ME_FOLDER);
-    if (!fs.existsSync(sharedWithMePath)) fs.mkdirSync(sharedWithMePath, { recursive: true });
-
-    const sharedByMePath = path.join(LOCAL_PATH, SHARED_BY_ME_FOLDER);
-    if (!fs.existsSync(sharedByMePath)) fs.mkdirSync(sharedByMePath, { recursive: true });
-  }
-
-  ensureFolderStructure();
-
-  async function handleFirestoreChange(change, getLocalPath) {
-    const data = change.doc.data();
-    const docPath = data.path;
-    if (!docPath) return;
-
-    const localFilePath = getLocalPath(data);
-    const trackingKey = `${data.scope || 'team'}:${docPath}`;
-    const isFolder = data.type === 'folder';
-
-    // DOU-205: rename / move detection. On a 'modified' snapshot for
-    // a fileId we've seen before, if the computed local path differs
-    // from what we last recorded, the server's path field has
-    // changed. Move the local file in place (fs.renameSync preserves
-    // Obsidian's inode tracking so notes don't lose their metadata,
-    // backlinks, or recent-files entries) and migrate the tracking
-    // maps from the old key to the new. We do this before the
-    // freshness check below because the rename happens irrespective
-    // of whether the content changed in the same update.
-    const fileId = change.doc.id;
-    const prevKnown = knownPaths.get(fileId);
-    if (change.type === 'modified' && prevKnown && prevKnown.localPath !== localFilePath) {
-      suppressLocal.add(prevKnown.localPath);
-      suppressLocal.add(localFilePath);
-      try {
-        if (fs.existsSync(prevKnown.localPath)) {
-          ensureDir(localFilePath);
-          fs.renameSync(prevKnown.localPath, localFilePath);
-          console.log(`  [${orgId}] [firestore → local] RENAME ${prevKnown.localPath} -> ${localFilePath}`);
+        else {
+            const existing = lstatOrNull(symlinkPath);
+            if (existing && existing.isSymbolicLink()) {
+                fs.unlinkSync(symlinkPath);
+                console.log(`  [${orgId}] [symlink] removed Shared by Me/${docPath}`);
+            }
         }
-      } catch (err) {
-        console.error(`  [${orgId}] [firestore → local] RENAME failed: ${err && err.message}`);
-      }
-      if (lastKnownUpdate.has(prevKnown.trackingKey)) {
-        lastKnownUpdate.set(trackingKey, lastKnownUpdate.get(prevKnown.trackingKey));
-        lastKnownUpdate.delete(prevKnown.trackingKey);
-      }
-      if (lastSyncedHash.has(prevKnown.trackingKey)) {
-        setBaseline(trackingKey, lastSyncedHash.get(prevKnown.trackingKey));
-        deleteBaseline(prevKnown.trackingKey);
-      }
-      const manifestEntry = manifestStore.getEntry(prevKnown.trackingKey);
-      if (manifestEntry) {
-        manifestStore.removeEntry(prevKnown.trackingKey);
-        manifestStore.upsertEntry(trackingKey, manifestEntry);
-      }
-      const binding = bindings.get(fileId);
-      if (binding && bindingsByPath.get(prevKnown.localPath) === binding) {
-        bindingsByPath.delete(prevKnown.localPath);
-        bindingsByPath.set(localFilePath, binding);
-      }
-      setTimeout(() => {
-        suppressLocal.delete(prevKnown.localPath);
-        suppressLocal.delete(localFilePath);
-      }, 1000);
     }
-
-    if (change.type === 'removed') {
-      if (isFolder) {
-        // Best-effort directory removal. The daemon's own file-delete
-        // events should have cleared all children by the time we get
-        // here; if not, rmdirSync throws ENOTEMPTY and we keep the
-        // directory rather than risk losing data the user hasn't seen.
-        try {
-          suppressLocal.add(localFilePath);
-          fs.rmdirSync(localFilePath);
-          console.log(`  [${orgId}] [firestore → local] RMDIR ${docPath}`);
-          setTimeout(() => suppressLocal.delete(localFilePath), 1000);
-        } catch (err) {
-          suppressLocal.delete(localFilePath);
-          if (err.code !== 'ENOENT' && err.code !== 'ENOTEMPTY') {
-            console.error(`  [${orgId}] [firestore → local] RMDIR ${docPath} failed: ${err.message}`);
-          }
-        }
-      } else if (fs.existsSync(localFilePath)) {
-        console.log(`  [${orgId}] [firestore → local] DELETE ${docPath}`);
-        suppressLocal.add(localFilePath);
-        fs.unlinkSync(localFilePath);
-        setTimeout(() => suppressLocal.delete(localFilePath), 1000);
-      }
-      lastKnownUpdate.delete(trackingKey);
-      deleteBaseline(trackingKey);
-      manifestStore.removeEntry(trackingKey);
-      knownPaths.delete(fileId);
-      await disposeBinding(change.doc.id, localFilePath);
-      return;
+    // Static (user-level) folders. Team folders are mkdir'd by setupTeam,
+    // which runs after manifest reconcile (see startup ordering below).
+    function ensureFolderStructure() {
+        const privatePath = path.join(LOCAL_PATH, PRIVATE_FOLDER);
+        if (!fs.existsSync(privatePath))
+            fs.mkdirSync(privatePath, { recursive: true });
+        const sharedWithMePath = path.join(LOCAL_PATH, SHARED_WITH_ME_FOLDER);
+        if (!fs.existsSync(sharedWithMePath))
+            fs.mkdirSync(sharedWithMePath, { recursive: true });
+        const sharedByMePath = path.join(LOCAL_PATH, SHARED_BY_ME_FOLDER);
+        if (!fs.existsSync(sharedByMePath))
+            fs.mkdirSync(sharedByMePath, { recursive: true });
     }
-
-    // Record (or refresh) the per-fileId path so the next 'modified'
-    // event can detect a rename / move by comparing against this.
-    knownPaths.set(fileId, { localPath: localFilePath, trackingKey });
-
-    // Kick off Yjs binding setup for text files. Fire-and-forget so
-    // a slow start (retrying past the rules-engine race on a fresh
-    // doc) does not stall the legacy blob pull. Once the binding is
-    // registered, future events take the Yjs path; until then the
-    // blob path still keeps disk in sync.
-    if (!isFolder) {
-      const ext = extFromPath(docPath);
-      const extDerivedMime = mimeTypeFromExt(ext);
-      const isText = isTextMimeType(data.mimeType) || isTextMimeType(extDerivedMime);
-      if (isText) ensureBinding(change.doc.id, localFilePath);
-    }
-
-    const remoteUpdated = data.updatedAt || data.createdAt || '';
-    const lastKnown = lastKnownUpdate.get(trackingKey);
-    if (lastKnown && lastKnown >= remoteUpdated) return;
-
-    if (isFolder) {
-      // Folder docs mirror to a local directory. No blob, no content
-      // comparison; if the directory doesn't exist yet, create it.
-      if (!fs.existsSync(localFilePath)) {
+    ensureFolderStructure();
+    async function handleFirestoreChange(change, getLocalPath) {
+        const data = change.doc.data();
+        const docPath = data['path'];
+        if (typeof docPath !== 'string' || !docPath)
+            return;
+        const localFilePath = getLocalPath(data);
+        const trackingKey = `${data['scope'] || 'team'}:${docPath}`;
+        const isFolder = data['type'] === 'folder';
+        // DOU-205: rename / move detection. On a 'modified' snapshot for
+        // a fileId we've seen before, if the computed local path differs
+        // from what we last recorded, the server's path field has
+        // changed. Move the local file in place (fs.renameSync preserves
+        // Obsidian's inode tracking so notes don't lose their metadata,
+        // backlinks, or recent-files entries) and migrate the tracking
+        // maps from the old key to the new. We do this before the
+        // freshness check below because the rename happens irrespective
+        // of whether the content changed in the same update.
+        const fileId = change.doc.id;
+        const prevKnown = knownPaths.get(fileId);
+        if (change.type === 'modified' && prevKnown && prevKnown.localPath !== localFilePath) {
+            suppressLocal.add(prevKnown.localPath);
+            suppressLocal.add(localFilePath);
+            try {
+                if (fs.existsSync(prevKnown.localPath)) {
+                    ensureDir(localFilePath);
+                    fs.renameSync(prevKnown.localPath, localFilePath);
+                    console.log(`  [${orgId}] [firestore → local] RENAME ${prevKnown.localPath} -> ${localFilePath}`);
+                }
+            }
+            catch (err) {
+                console.error(`  [${orgId}] [firestore → local] RENAME failed: ${err?.message}`);
+            }
+            const prevLastKnown = lastKnownUpdate.get(prevKnown.trackingKey);
+            if (prevLastKnown !== undefined) {
+                lastKnownUpdate.set(trackingKey, prevLastKnown);
+                lastKnownUpdate.delete(prevKnown.trackingKey);
+            }
+            const prevBaseline = lastSyncedHash.get(prevKnown.trackingKey);
+            if (prevBaseline !== undefined) {
+                setBaseline(trackingKey, prevBaseline);
+                deleteBaseline(prevKnown.trackingKey);
+            }
+            const manifestEntry = manifestStore.getEntry(prevKnown.trackingKey);
+            if (manifestEntry) {
+                manifestStore.removeEntry(prevKnown.trackingKey);
+                manifestStore.upsertEntry(trackingKey, manifestEntry);
+            }
+            const binding = bindings.get(fileId);
+            if (binding && bindingsByPath.get(prevKnown.localPath) === binding) {
+                bindingsByPath.delete(prevKnown.localPath);
+                bindingsByPath.set(localFilePath, binding);
+            }
+            setTimeout(() => {
+                suppressLocal.delete(prevKnown.localPath);
+                suppressLocal.delete(localFilePath);
+            }, 1000);
+        }
+        if (change.type === 'removed') {
+            if (isFolder) {
+                // Best-effort directory removal. The daemon's own file-delete
+                // events should have cleared all children by the time we get
+                // here; if not, rmdirSync throws ENOTEMPTY and we keep the
+                // directory rather than risk losing data the user hasn't seen.
+                try {
+                    suppressLocal.add(localFilePath);
+                    fs.rmdirSync(localFilePath);
+                    console.log(`  [${orgId}] [firestore → local] RMDIR ${docPath}`);
+                    setTimeout(() => suppressLocal.delete(localFilePath), 1000);
+                }
+                catch (err) {
+                    suppressLocal.delete(localFilePath);
+                    const code = err?.code;
+                    if (code !== 'ENOENT' && code !== 'ENOTEMPTY') {
+                        console.error(`  [${orgId}] [firestore → local] RMDIR ${docPath} failed: ${err?.message}`);
+                    }
+                }
+            }
+            else if (fs.existsSync(localFilePath)) {
+                console.log(`  [${orgId}] [firestore → local] DELETE ${docPath}`);
+                suppressLocal.add(localFilePath);
+                fs.unlinkSync(localFilePath);
+                setTimeout(() => suppressLocal.delete(localFilePath), 1000);
+            }
+            lastKnownUpdate.delete(trackingKey);
+            deleteBaseline(trackingKey);
+            manifestStore.removeEntry(trackingKey);
+            knownPaths.delete(fileId);
+            await disposeBinding(change.doc.id, localFilePath);
+            return;
+        }
+        // Record (or refresh) the per-fileId path so the next 'modified'
+        // event can detect a rename / move by comparing against this.
+        knownPaths.set(fileId, { localPath: localFilePath, trackingKey });
+        // Kick off Yjs binding setup for text files. Fire-and-forget so
+        // a slow start (retrying past the rules-engine race on a fresh
+        // doc) does not stall the legacy blob pull. Once the binding is
+        // registered, future events take the Yjs path; until then the
+        // blob path still keeps disk in sync.
+        if (!isFolder) {
+            const ext = extFromPath(docPath);
+            const extDerivedMime = mimeTypeFromExt(ext);
+            const isText = isTextMimeType(data['mimeType']) || isTextMimeType(extDerivedMime);
+            if (isText)
+                ensureBinding(change.doc.id, localFilePath);
+        }
+        const remoteUpdated = data['updatedAt'] || data['createdAt'] || '';
+        const lastKnown = lastKnownUpdate.get(trackingKey);
+        if (lastKnown && lastKnown >= remoteUpdated)
+            return;
+        if (isFolder) {
+            // Folder docs mirror to a local directory. No blob, no content
+            // comparison; if the directory doesn't exist yet, create it.
+            if (!fs.existsSync(localFilePath)) {
+                suppressLocal.add(localFilePath);
+                fs.mkdirSync(localFilePath, { recursive: true });
+                console.log(`  [${orgId}] [firestore → local] MKDIR ${docPath}`);
+                setTimeout(() => suppressLocal.delete(localFilePath), 1000);
+            }
+            lastKnownUpdate.set(trackingKey, remoteUpdated);
+            return;
+        }
+        if (fs.existsSync(localFilePath)) {
+            const baseline = lastSyncedHash.get(trackingKey);
+            if (baseline !== undefined) {
+                // We have a record of what we last synced: decide by content,
+                // not mtime. (Obsidian keeps the mtime fresh, which made the old
+                // mtime guard wrongly skip web edits.)
+                const localHash = computeContentHash(fs.readFileSync(localFilePath));
+                if (localHash === data['contentHash']) {
+                    // Local already matches the incoming server content; nothing
+                    // to write.
+                    lastKnownUpdate.set(trackingKey, remoteUpdated);
+                    setBaseline(trackingKey, data['contentHash']);
+                    return;
+                }
+                if (localHash !== baseline) {
+                    // Local changed since our last sync AND the server changed:
+                    // a genuine conflict. Keep the local copy rather than clobber
+                    // it. (Writing a "conflicted copy" is the next increment.)
+                    console.log(`  [${orgId}] [conflict] ${docPath}: local and server both changed; keeping local`);
+                    return;
+                }
+                // localHash === baseline: local is untouched since last sync, so
+                // the server is authoritative -> fall through and pull.
+            }
+            else {
+                // No baseline at all: a local file this daemon has never synced
+                // (e.g. created locally while offline, or a folder adopted from
+                // elsewhere). We can't tell by content who is newer, so fall
+                // back to the mtime heuristic. Conflict copies (next increment)
+                // will replace this last-resort with a no-loss outcome.
+                const localMtime = fs.statSync(localFilePath).mtime.toISOString();
+                if (localMtime > remoteUpdated)
+                    return;
+            }
+        }
+        const action = change.type === 'added' ? 'CREATE' : 'UPDATE';
+        console.log(`  [${orgId}] [firestore → local] ${action} ${docPath} (${data['scope'] || 'team'})`);
+        ensureDir(localFilePath);
         suppressLocal.add(localFilePath);
-        fs.mkdirSync(localFilePath, { recursive: true });
-        console.log(`  [${orgId}] [firestore → local] MKDIR ${docPath}`);
-        setTimeout(() => suppressLocal.delete(localFilePath), 1000);
-      }
-      lastKnownUpdate.set(trackingKey, remoteUpdated);
-      return;
-    }
-
-    if (fs.existsSync(localFilePath)) {
-      const baseline = lastSyncedHash.get(trackingKey);
-      if (baseline !== undefined) {
-        // We have a record of what we last synced: decide by content,
-        // not mtime. (Obsidian keeps the mtime fresh, which made the old
-        // mtime guard wrongly skip web edits.)
-        const localHash = computeContentHash(fs.readFileSync(localFilePath));
-        if (localHash === data.contentHash) {
-          // Local already matches the incoming server content; nothing
-          // to write.
-          lastKnownUpdate.set(trackingKey, remoteUpdated);
-          setBaseline(trackingKey, data.contentHash);
-          return;
+        const ext = extFromPath(docPath);
+        // Extension is used as a fallback authority when the stored
+        // mimeType claims non-text but the extension maps to a text mime
+        // in EXT_TO_MIME. This heals files uploaded before their extension
+        // was registered as text (e.g. .base files uploaded prior to the
+        // text/yaml mapping landing): on the next pull the daemon writes
+        // them as UTF-8 so text-aware features (line diffing, conflict
+        // markers) can apply.
+        const extDerivedMime = mimeTypeFromExt(ext);
+        const isText = isTextMimeType(data['mimeType']) || isTextMimeType(extDerivedMime);
+        // Yjs path (DOU-178 PR 3): if a binding for this file is already
+        // up and carries non-empty ytext, the debounced flush owns the
+        // disk write and the legacy blob pull is skipped. Bindings that
+        // are still being set up, or that loaded empty ytext (pre-Yjs
+        // files), fall through to the blob path; PR 4 retires the blob
+        // path entirely.
+        if (isText) {
+            const binding = bindings.get(change.doc.id);
+            if (binding && binding.ytext.length > 0) {
+                lastKnownUpdate.set(trackingKey, remoteUpdated);
+                setBaseline(trackingKey, data['contentHash']);
+                setTimeout(() => suppressLocal.delete(localFilePath), 1000);
+                return;
+            }
         }
-        if (localHash !== baseline) {
-          // Local changed since our last sync AND the server changed:
-          // a genuine conflict. Keep the local copy rather than clobber
-          // it. (Writing a "conflicted copy" is the next increment.)
-          console.log(`  [${orgId}] [conflict] ${docPath}: local and server both changed; keeping local`);
-          return;
+        // Storage rules require the Firestore doc to exist before they
+        // authorize a blob upload, so writers must create the doc first
+        // and upload second. That leaves a window where the metadata is
+        // visible (this listener fires) but the blob is not yet uploaded.
+        // Retry on object-not-found with exponential backoff covers that
+        // race; on a persistent miss we fall through to the original
+        // catch upstream.
+        const blobReadArgs = { storage, orgId, fileId: change.doc.id, ext };
+        const retryOpts = { expectedHash: data['contentHash'] };
+        if (isText) {
+            const content = await readBlobWithRetry(() => readBlobAsText(blobReadArgs), retryOpts);
+            fs.writeFileSync(localFilePath, content || '', 'utf-8');
+        }
+        else {
+            const bytes = await readBlobWithRetry(() => readBlob(blobReadArgs), retryOpts);
+            fs.writeFileSync(localFilePath, bytes);
         }
-        // localHash === baseline: local is untouched since last sync, so
-        // the server is authoritative -> fall through and pull.
-      } else {
-        // No baseline at all: a local file this daemon has never synced
-        // (e.g. created locally while offline, or a folder adopted from
-        // elsewhere). We can't tell by content who is newer, so fall
-        // back to the mtime heuristic. Conflict copies (next increment)
-        // will replace this last-resort with a no-loss outcome.
-        const localMtime = fs.statSync(localFilePath).mtime.toISOString();
-        if (localMtime > remoteUpdated) return;
-      }
-    }
-
-    const action = change.type === 'added' ? 'CREATE' : 'UPDATE';
-    console.log(`  [${orgId}] [firestore → local] ${action} ${docPath} (${data.scope || 'team'})`);
-    ensureDir(localFilePath);
-    suppressLocal.add(localFilePath);
-
-    const ext = extFromPath(docPath);
-    // Extension is used as a fallback authority when the stored
-    // mimeType claims non-text but the extension maps to a text mime
-    // in EXT_TO_MIME. This heals files uploaded before their extension
-    // was registered as text (e.g. .base files uploaded prior to the
-    // text/yaml mapping landing): on the next pull the daemon writes
-    // them as UTF-8 so text-aware features (line diffing, conflict
-    // markers) can apply.
-    const extDerivedMime = mimeTypeFromExt(ext);
-    const isText = isTextMimeType(data.mimeType) || isTextMimeType(extDerivedMime);
-
-    // Yjs path (DOU-178 PR 3): if a binding for this file is already
-    // up and carries non-empty ytext, the debounced flush owns the
-    // disk write and the legacy blob pull is skipped. Bindings that
-    // are still being set up, or that loaded empty ytext (pre-Yjs
-    // files), fall through to the blob path; PR 4 retires the blob
-    // path entirely.
-    if (isText) {
-      const binding = bindings.get(change.doc.id);
-      if (binding && binding.ytext.length > 0) {
         lastKnownUpdate.set(trackingKey, remoteUpdated);
-        setBaseline(trackingKey, data.contentHash);
+        setBaseline(trackingKey, data['contentHash']);
         setTimeout(() => suppressLocal.delete(localFilePath), 1000);
-        return;
-      }
     }
-
-    // Storage rules require the Firestore doc to exist before they
-    // authorize a blob upload, so writers must create the doc first
-    // and upload second. That leaves a window where the metadata is
-    // visible (this listener fires) but the blob is not yet uploaded.
-    // Retry on object-not-found with exponential backoff covers that
-    // race; on a persistent miss we fall through to the original
-    // catch upstream.
-    const blobReadArgs = { storage, orgId, fileId: change.doc.id, ext };
-    const retryOpts = { expectedHash: data.contentHash };
-    if (isText) {
-      const content = await readBlobWithRetry(() => readBlobAsText(blobReadArgs), retryOpts);
-      fs.writeFileSync(localFilePath, content || '', 'utf-8');
-    } else {
-      const bytes = await readBlobWithRetry(() => readBlob(blobReadArgs), retryOpts);
-      fs.writeFileSync(localFilePath, bytes);
+    // Set up per-team resources: mkdir the local folder, register the
+    // Firestore listener for that team's files. On startup, called once
+    // per bootstrapped team after reconcile; thereafter via TeamRegistry
+    // when the live teams-collection listener reports add/modify/remove.
+    setupTeam = (teamId, teamData) => {
+        // The pre-migration JS coerced a missing name to the literal
+        // "undefined" string via `name + ' Teamspace'`. Preserve that
+        // faithfully (String(undefined) === 'undefined'): a team without
+        // a name still gets a folder + listener, just under an
+        // obviously-broken display name that surfaces the bug instead of
+        // silently hiding the team.
+        const teamFolder = teamFolderName(String(teamData.name));
+        const teamPath = path.join(LOCAL_PATH, teamFolder);
+        if (!fs.existsSync(teamPath))
+            fs.mkdirSync(teamPath, { recursive: true });
+        const q = query(filesRef, where('scope', '==', 'team'), where('teamId', '==', teamId));
+        const unsubscribe = onSnapshot(q, (snapshot) => {
+            snapshot.docChanges().forEach((change) => {
+                track(handleFirestoreChange(change, (data) => path.join(LOCAL_PATH, teamFolder, data['path'])).catch((err) => console.error(`  [${orgId}] Firestore change handler error:`, err?.message)));
+            });
+        }, (err) => console.error(`  [${orgId}] Team "${teamFolder}" listener error:`, err));
+        teamUnsubscribers.set(teamId, unsubscribe);
+        console.log(`  [${orgId}]   Listening: ${teamFolder}`);
+    };
+    // Bootstrap team metadata synchronously so manifest reconcile can
+    // query team-scoped cloud files before any file onSnapshot handlers
+    // run (DOU-55). Populating teamIdsByName here also lets chokidar
+    // route local paths once the watcher starts. Per-team file listeners
+    // and the live teams-collection onSnapshot are wired after reconcile
+    // completes so their initial snapshots cannot race with startup cleanup.
+    const teamsSnap = await getDocs(collection(db, `orgs/${orgId}/teams`));
+    for (const teamDoc of teamsSnap.docs) {
+        teamRegistry.bootstrap(teamDoc.id, teamDoc.data());
     }
-    lastKnownUpdate.set(trackingKey, remoteUpdated);
-    setBaseline(trackingKey, data.contentHash);
-    setTimeout(() => suppressLocal.delete(localFilePath), 1000);
-  }
-
-  // Set up per-team resources: mkdir the local folder, register the
-  // Firestore listener for that team's files. On startup, called once
-  // per bootstrapped team after reconcile; thereafter via TeamRegistry
-  // when the live teams-collection listener reports add/modify/remove.
-  setupTeam = (teamId, teamData) => {
-    const teamFolder = teamFolderName(teamData.name);
-    const teamPath = path.join(LOCAL_PATH, teamFolder);
-    if (!fs.existsSync(teamPath)) fs.mkdirSync(teamPath, { recursive: true });
-
-    const q = query(filesRef, where('scope', '==', 'team'), where('teamId', '==', teamId));
-    const unsubscribe = onSnapshot(q, snapshot => {
-      snapshot.docChanges().forEach(change => {
-        track(handleFirestoreChange(change, data =>
-          path.join(LOCAL_PATH, teamFolder, data.path),
-        ).catch(err => console.error(`  [${orgId}] Firestore change handler error:`, err && err.message)));
-      });
-    }, err => console.error(`  [${orgId}] Team "${teamFolder}" listener error:`, err));
-
-    teamUnsubscribers.set(teamId, unsubscribe);
-    console.log(`  [${orgId}]   Listening: ${teamFolder}`);
-  };
-
-  // Bootstrap team metadata synchronously so manifest reconcile can
-  // query team-scoped cloud files before any file onSnapshot handlers
-  // run (DOU-55). Populating teamIdsByName here also lets chokidar
-  // route local paths once the watcher starts. Per-team file listeners
-  // and the live teams-collection onSnapshot are wired after reconcile
-  // completes so their initial snapshots cannot race with startup cleanup.
-  const teamsSnap = await getDocs(collection(db, `orgs/${orgId}/teams`));
-  for (const teamDoc of teamsSnap.docs) {
-    teamRegistry.bootstrap(teamDoc.id, teamDoc.data());
-  }
-  console.log(`  [${orgId}] Teams: ${teamRegistry.names().join(', ') || 'none'}`);
-
-  function trackingKeyFromDocData(data) {
-    return `${data.scope || 'team'}:${data.path}`;
-  }
-
-  // Paths the daemon does not scan or sync. Add checks here as needed
-  // (extensions, .compoundignore, etc.).
-  function shouldSkipLocalPath(name, rel) {
-    if (name.startsWith('.') || name === 'node_modules') return true;
-    if (rel.startsWith(SHARED_WITH_ME_FOLDER + path.sep)) return true;
-    if (rel.startsWith(SHARED_BY_ME_FOLDER + path.sep)) return true;
-    return false;
-  }
-
-  function walkLocalSyncableFiles(absDir, files) {
-    let entries;
-    try {
-      entries = fs.readdirSync(absDir, { withFileTypes: true });
-    } catch (err) {
-      const rel = path.relative(LOCAL_PATH, absDir) || '.';
-      console.warn(`  [${orgId}] [local scan] could not read directory ${rel}: ${err.message}`);
-      return;
+    console.log(`  [${orgId}] Teams: ${teamRegistry.names().join(', ') || 'none'}`);
+    function trackingKeyFromDocData(data) {
+        return `${data['scope'] || 'team'}:${data['path']}`;
     }
-    for (const ent of entries) {
-      const abs = path.join(absDir, ent.name);
-      const rel = path.relative(LOCAL_PATH, abs);
-      if (shouldSkipLocalPath(ent.name, rel)) continue;
-      if (ent.isDirectory()) {
-        walkLocalSyncableFiles(abs, files);
-      } else if (ent.isFile()) {
-        files.push(abs);
-      }
+    // Paths the daemon does not scan or sync. Add checks here as needed
+    // (extensions, .compoundignore, etc.).
+    function shouldSkipLocalPath(name, rel) {
+        if (name.startsWith('.') || name === 'node_modules')
+            return true;
+        if (rel.startsWith(SHARED_WITH_ME_FOLDER + path.sep))
+            return true;
+        if (rel.startsWith(SHARED_BY_ME_FOLDER + path.sep))
+            return true;
+        return false;
     }
-  }
-
-  function collectLocalSyncableFiles() {
-    const files = [];
-    walkLocalSyncableFiles(LOCAL_PATH, files);
-    return files;
-  }
-
-  function readLocalFilePayload(filePath) {
-    const rel = path.relative(LOCAL_PATH, filePath);
-    const ext = extFromPath(rel);
-    const mimeType = mimeTypeFromExt(ext);
-    const data = isTextMimeType(mimeType)
-      ? fs.readFileSync(filePath, 'utf-8')
-      : fs.readFileSync(filePath);
-    return { data, mimeType, contentHash: computeContentHash(data) };
-  }
-
-  async function pushLocalFileAtPath(filePath) {
-    let stat;
-    try {
-      stat = fs.statSync(filePath);
-    } catch {
-      return;
+    function walkLocalSyncableFiles(absDir, files) {
+        let entries;
+        try {
+            entries = fs.readdirSync(absDir, { withFileTypes: true });
+        }
+        catch (err) {
+            const rel = path.relative(LOCAL_PATH, absDir) || '.';
+            console.warn(`  [${orgId}] [local scan] could not read directory ${rel}: ${err?.message}`);
+            return;
+        }
+        for (const ent of entries) {
+            const abs = path.join(absDir, ent.name);
+            const rel = path.relative(LOCAL_PATH, abs);
+            if (shouldSkipLocalPath(ent.name, rel))
+                continue;
+            if (ent.isDirectory()) {
+                walkLocalSyncableFiles(abs, files);
+            }
+            else if (ent.isFile()) {
+                files.push(abs);
+            }
+        }
     }
-    if (!stat.isFile() || stat.size > maxUploadBytes) return;
-    const { data, mimeType } = readLocalFilePayload(filePath);
-    await pushToFirestore(filePath, data, mimeType, stat.mtime.toISOString());
-  }
-
-  // Sync local cleanup during startup manifest reconcile. Runs before
-  // Firestore listeners and Yjs bindings are wired, so no async cloud or
-  // binding teardown is needed here.
-  function deleteLocalReconcile(localFilePath, fileId, trackingKey) {
-    suppressLocal.add(localFilePath);
-    if (fs.existsSync(localFilePath)) {
-      console.log(`  [${orgId}] [manifest reconcile] DELETE local ${path.relative(LOCAL_PATH, localFilePath)}`);
-      fs.unlinkSync(localFilePath);
+    function collectLocalSyncableFiles() {
+        const files = [];
+        walkLocalSyncableFiles(LOCAL_PATH, files);
+        return files;
     }
-    lastKnownUpdate.delete(trackingKey);
-    deleteBaseline(trackingKey);
-    manifestStore.removeEntry(trackingKey);
-    if (fileId) {
-      knownPaths.delete(fileId);
+    function readLocalFilePayload(filePath) {
+        const rel = path.relative(LOCAL_PATH, filePath);
+        const ext = extFromPath(rel);
+        const mimeType = mimeTypeFromExt(ext);
+        const data = isTextMimeType(mimeType)
+            ? fs.readFileSync(filePath, 'utf-8')
+            : fs.readFileSync(filePath);
+        return { data, mimeType, contentHash: computeContentHash(data) };
     }
-    setTimeout(() => suppressLocal.delete(localFilePath), 1000);
-  }
-
-  async function deleteRemoteReconcile(cloudData, trackingKey) {
-    const scope = cloudData.scope || 'team';
-    const teamId = cloudData.teamId;
-    const docPath = cloudData.path;
-    const result = await deleteFileFromCloud({
-      filesRef,
-      storage,
-      orgId,
-      userId,
-      scope,
-      teamId,
-      docPath,
-    });
-    if (result.action === 'deleted') {
-      console.log(`  [${orgId}] [manifest reconcile] DELETE cloud ${docPath}`);
+    async function pushLocalFileAtPath(filePath) {
+        let stat;
+        try {
+            stat = fs.statSync(filePath);
+        }
+        catch {
+            return;
+        }
+        if (!stat.isFile() || stat.size > maxUploadBytes)
+            return;
+        const { data, mimeType } = readLocalFilePayload(filePath);
+        await pushToFirestore(filePath, data, mimeType, stat.mtime.toISOString());
     }
-    manifestStore.removeEntry(trackingKey);
-  }
-
-  function localPathForCloudData(data) {
-    if (!data?.path) return null;
-    if (data.scope === 'private') {
-      if (data.ownerId === userId) {
-        return path.join(LOCAL_PATH, PRIVATE_FOLDER, data.path);
-      }
-      return path.join(LOCAL_PATH, SHARED_WITH_ME_FOLDER, data.path);
+    // Sync local cleanup during startup manifest reconcile. Runs before
+    // Firestore listeners and Yjs bindings are wired, so no async cloud or
+    // binding teardown is needed here.
+    function deleteLocalReconcile(localFilePath, fileId, trackingKey) {
+        suppressLocal.add(localFilePath);
+        if (fs.existsSync(localFilePath)) {
+            console.log(`  [${orgId}] [manifest reconcile] DELETE local ${path.relative(LOCAL_PATH, localFilePath)}`);
+            fs.unlinkSync(localFilePath);
+        }
+        lastKnownUpdate.delete(trackingKey);
+        deleteBaseline(trackingKey);
+        manifestStore.removeEntry(trackingKey);
+        if (fileId) {
+            knownPaths.delete(fileId);
+        }
+        setTimeout(() => suppressLocal.delete(localFilePath), 1000);
     }
-    if (data.scope === 'team' && data.teamId) {
-      const team = teamRegistry.get(data.teamId);
-      if (!team?.name) return null;
-      return path.join(LOCAL_PATH, teamFolderName(team.name), data.path);
+    async function deleteRemoteReconcile(cloudData, trackingKey) {
+        const scope = cloudData['scope'] || 'team';
+        const teamId = cloudData['teamId'];
+        const docPath = cloudData['path'];
+        const result = await deleteFileFromCloud({
+            filesRef,
+            storage,
+            orgId,
+            userId,
+            scope,
+            teamId,
+            docPath,
+        });
+        if (result.action === 'deleted') {
+            console.log(`  [${orgId}] [manifest reconcile] DELETE cloud ${docPath}`);
+        }
+        manifestStore.removeEntry(trackingKey);
     }
-    return null;
-  }
-
-  async function fetchCloudFilesByKey() {
-    const cloudByKey = new Map();
-
-    function ingestDoc(d) {
-      const data = d.data();
-      if (data.type === 'folder' || !data.path) return;
-      const key = trackingKeyFromDocData(data);
-      cloudByKey.set(key, { fileId: d.id, data });
+    function localPathForCloudData(data) {
+        const docPath = data['path'];
+        if (typeof docPath !== 'string' || !docPath)
+            return null;
+        if (data['scope'] === 'private') {
+            if (data['ownerId'] === userId) {
+                return path.join(LOCAL_PATH, PRIVATE_FOLDER, docPath);
+            }
+            return path.join(LOCAL_PATH, SHARED_WITH_ME_FOLDER, docPath);
+        }
+        if (data['scope'] === 'team' && data['teamId']) {
+            const team = teamRegistry.get(data['teamId']);
+            if (!team?.name)
+                return null;
+            return path.join(LOCAL_PATH, teamFolderName(team.name), docPath);
+        }
+        return null;
     }
-
-    for (const [teamId] of teamRegistry.entries()) {
-      const teamSnap = await getDocs(query(
-        filesRef,
-        where('scope', '==', 'team'),
-        where('teamId', '==', teamId),
-      ));
-      teamSnap.docs.forEach(ingestDoc);
+    async function fetchCloudFilesByKey() {
+        const cloudByKey = new Map();
+        function ingestDoc(d) {
+            const data = d.data();
+            if (data['type'] === 'folder' || !data['path'])
+                return;
+            const key = trackingKeyFromDocData(data);
+            cloudByKey.set(key, { fileId: d.id, data });
+        }
+        for (const [teamId] of teamRegistry.entries()) {
+            const teamSnap = await getDocs(query(filesRef, where('scope', '==', 'team'), where('teamId', '==', teamId)));
+            teamSnap.docs.forEach(ingestDoc);
+        }
+        if (userId) {
+            const privateSnap = await getDocs(query(filesRef, where('scope', '==', 'private'), where('ownerId', '==', userId)));
+            privateSnap.docs.forEach(ingestDoc);
+            const sharedSnap = await getDocs(query(filesRef, where('scope', '==', 'private'), where('sharedWith', 'array-contains', userId)));
+            sharedSnap.docs.forEach(ingestDoc);
+        }
+        return cloudByKey;
     }
-
-    if (userId) {
-      const privateSnap = await getDocs(query(
-        filesRef,
-        where('scope', '==', 'private'),
-        where('ownerId', '==', userId),
-      ));
-      privateSnap.docs.forEach(ingestDoc);
-
-      const sharedSnap = await getDocs(query(
-        filesRef,
-        where('scope', '==', 'private'),
-        where('sharedWith', 'array-contains', userId),
-      ));
-      sharedSnap.docs.forEach(ingestDoc);
+    // Runs after team metadata is loaded but before any file listeners or
+    // chokidar. See docs/features/sync/sync-manifest-design.md.
+    async function reconcileManifestOnStartup() {
+        console.log(`  [${orgId}] Reconciling local manifest...`);
+        const cloudByKey = await fetchCloudFilesByKey();
+        const localByKey = new Map();
+        for (const filePath of collectLocalSyncableFiles()) {
+            const { scope, docPath } = scopeFromLocalPath(filePath, LOCAL_PATH, teamIdsByName);
+            if (!docPath)
+                continue;
+            localByKey.set(`${scope}:${docPath}`, filePath);
+        }
+        // Bootstrap manifest entries for files already in sync before DOU-55.
+        for (const [key, cloud] of cloudByKey) {
+            if (manifestStore.getEntry(key))
+                continue;
+            const localFilePath = localByKey.get(key);
+            if (!localFilePath || !fs.existsSync(localFilePath))
+                continue;
+            try {
+                const { contentHash } = readLocalFilePayload(localFilePath);
+                if (contentHash === cloud.data['contentHash']) {
+                    manifestStore.upsertEntry(key, {
+                        fileId: cloud.fileId,
+                        contentHash,
+                        lastSyncedAt: cloud.data['updatedAt'] || cloud.data['createdAt'] || new Date().toISOString(),
+                    });
+                }
+            }
+            catch {
+                // skip unreadable locals
+            }
+        }
+        const allKeys = new Set([
+            ...Object.keys(manifestStore.getState().entries),
+            ...localByKey.keys(),
+            ...cloudByKey.keys(),
+        ]);
+        for (const trackingKey of allKeys) {
+            const entry = manifestStore.getEntry(trackingKey);
+            let localFilePath = localByKey.get(trackingKey) ?? null;
+            const cloud = cloudByKey.get(trackingKey) ?? null;
+            if (!localFilePath && cloud) {
+                localFilePath = localPathForCloudData(cloud.data);
+            }
+            const onDisk = !!(localFilePath && fs.existsSync(localFilePath));
+            if (entry && onDisk && !cloud) {
+                let localHash;
+                try {
+                    ({ contentHash: localHash } = readLocalFilePayload(localFilePath));
+                }
+                catch {
+                    localHash = null;
+                }
+                if (localHash === null) {
+                    console.warn(`  [${orgId}] [manifest reconcile] skip unreadable local file ${trackingKey}`);
+                }
+                else if (entry.contentHash && localHash !== entry.contentHash) {
+                    await pushLocalFileAtPath(localFilePath);
+                }
+                else {
+                    deleteLocalReconcile(localFilePath, entry.fileId, trackingKey);
+                }
+            }
+            else if (!entry && onDisk && !cloud) {
+                const baselineHash = lastSyncedHash.get(trackingKey);
+                let localHash;
+                try {
+                    ({ contentHash: localHash } = readLocalFilePayload(localFilePath));
+                }
+                catch {
+                    localHash = null;
+                }
+                if (localHash === null) {
+                    console.warn(`  [${orgId}] [manifest reconcile] skip unreadable local file ${trackingKey}`);
+                }
+                else if (baselineHash && localHash === baselineHash) {
+                    deleteLocalReconcile(localFilePath, null, trackingKey);
+                }
+                else {
+                    await pushLocalFileAtPath(localFilePath);
+                }
+            }
+            else if (entry && !onDisk && cloud) {
+                await deleteRemoteReconcile(cloud.data, trackingKey);
+            }
+            else if ((entry || cloud) && onDisk && cloud) {
+                manifestStore.upsertEntry(trackingKey, {
+                    fileId: cloud.fileId,
+                    contentHash: cloud.data['contentHash'],
+                    lastSyncedAt: cloud.data['updatedAt'] || cloud.data['createdAt'] || new Date().toISOString(),
+                });
+            }
+            else if (!entry && onDisk && cloud) {
+                manifestStore.upsertEntry(trackingKey, {
+                    fileId: cloud.fileId,
+                    contentHash: cloud.data['contentHash'],
+                    lastSyncedAt: cloud.data['updatedAt'] || cloud.data['createdAt'] || new Date().toISOString(),
+                });
+            }
+        }
+        manifestStore.flush();
+        console.log(`  [${orgId}] Manifest reconcile complete.`);
     }
-
-    return cloudByKey;
-  }
-
-  // Runs after team metadata is loaded but before any file listeners or
-  // chokidar. See docs/features/sync/sync-manifest-design.md.
-  async function reconcileManifestOnStartup() {
-    console.log(`  [${orgId}] Reconciling local manifest...`);
-    const cloudByKey = await fetchCloudFilesByKey();
-
-    const localByKey = new Map();
-    for (const filePath of collectLocalSyncableFiles()) {
-      const { scope, docPath } = scopeFromLocalPath(filePath, LOCAL_PATH, teamIdsByName);
-      if (!docPath) continue;
-      localByKey.set(`${scope}:${docPath}`, filePath);
+    await reconcileManifestOnStartup();
+    // Wire per-team file listeners and the live teams-collection watcher
+    // after reconcile so initial onSnapshot deliveries cannot race with
+    // startup cleanup (DOU-55). applyChange on the live listener picks
+    // up teamspaces created/renamed/removed after daemon start without
+    // restarting sync.
+    for (const [teamId, teamData] of teamRegistry.entries()) {
+        setupTeam(teamId, teamData);
     }
-
-    // Bootstrap manifest entries for files already in sync before DOU-55.
-    for (const [key, cloud] of cloudByKey) {
-      if (manifestStore.getEntry(key)) continue;
-      const localFilePath = localByKey.get(key);
-      if (!localFilePath || !fs.existsSync(localFilePath)) continue;
-      try {
-        const { contentHash } = readLocalFilePayload(localFilePath);
-        if (contentHash === cloud.data.contentHash) {
-          manifestStore.upsertEntry(key, {
-            fileId: cloud.fileId,
-            contentHash,
-            lastSyncedAt: cloud.data.updatedAt || cloud.data.createdAt || new Date().toISOString(),
-          });
+    const teamsUnsub = onSnapshot(collection(db, `orgs/${orgId}/teams`), (snapshot) => {
+        snapshot.docChanges().forEach((change) => {
+            teamRegistry.applyChange({
+                type: change.type,
+                id: change.doc.id,
+                data: change.doc.data(),
+            });
+        });
+    }, (err) => console.error(`  [${orgId}] Teams listener error:`, err));
+    unsubscribers.push(teamsUnsub);
+    function startFirestoreListeners() {
+        console.log(`  [${orgId}] Starting Firestore listeners...`);
+        if (userId) {
+            const privateQ = query(filesRef, where('scope', '==', 'private'), where('ownerId', '==', userId));
+            const privateUnsub = onSnapshot(privateQ, snapshot => {
+                snapshot.docChanges().forEach(change => {
+                    const data = change.doc.data();
+                    const realPath = path.join(LOCAL_PATH, PRIVATE_FOLDER, data['path']);
+                    track(handleFirestoreChange(change, () => realPath)
+                        .catch(err => console.error(`  [${orgId}] Firestore change handler error:`, err && err.message)));
+                    if (change.type !== 'removed') {
+                        updateSharedByMeSymlink(data, realPath);
+                    }
+                    else {
+                        const symlinkPath = path.join(LOCAL_PATH, SHARED_BY_ME_FOLDER, data['path']);
+                        try {
+                            fs.lstatSync(symlinkPath);
+                            fs.unlinkSync(symlinkPath);
+                        }
+                        catch (e) { /* ok */ }
+                    }
+                });
+            }, err => console.error(`  [${orgId}] Private files listener error:`, err));
+            unsubscribers.push(privateUnsub);
+            console.log(`  [${orgId}]   Listening: Private files + Shared by Me symlinks`);
+            // scope=='private' is required: Firestore rules only grant
+            // sharedWith-based reads on private files, so the query must
+            // constrain scope or the whole listen is denied (rules are not
+            // filters). See tests/rules.test.js "shared-with-me query".
+            const sharedQ = query(filesRef, where('scope', '==', 'private'), where('sharedWith', 'array-contains', userId));
+            const sharedUnsub = onSnapshot(sharedQ, snapshot => {
+                snapshot.docChanges().forEach(change => {
+                    const data = change.doc.data();
+                    if (data['ownerId'] === userId)
+                        return;
+                    track(handleFirestoreChange(change, () => path.join(LOCAL_PATH, SHARED_WITH_ME_FOLDER, data['path'])).catch(err => console.error(`  [${orgId}] Firestore change handler error:`, err && err.message)));
+                });
+            }, err => console.error(`  [${orgId}] Shared with me listener error:`, err));
+            unsubscribers.push(sharedUnsub);
+            console.log(`  [${orgId}]   Listening: Shared with Me`);
         }
-      } catch {
-        // skip unreadable locals
-      }
     }
-
-    const allKeys = new Set([
-      ...Object.keys(manifestStore.getState().entries),
-      ...localByKey.keys(),
-      ...cloudByKey.keys(),
-    ]);
-
-    for (const trackingKey of allKeys) {
-      const entry = manifestStore.getEntry(trackingKey);
-      let localFilePath = localByKey.get(trackingKey) ?? null;
-      const cloud = cloudByKey.get(trackingKey) ?? null;
-      if (!localFilePath && cloud) {
-        localFilePath = localPathForCloudData(cloud.data);
-      }
-      const onDisk = !!(localFilePath && fs.existsSync(localFilePath));
-
-      if (entry && onDisk && !cloud) {
-        let localHash;
-        try {
-          ({ contentHash: localHash } = readLocalFilePayload(localFilePath));
-        } catch {
-          localHash = null;
+    async function firestoreDocExists({ scope, teamId, docPath, contentHash, }) {
+        let q;
+        if (scope === 'private') {
+            q = query(filesRef, where('scope', '==', 'private'), where('ownerId', '==', userId), where('path', '==', docPath));
         }
-        if (localHash === null) {
-          console.warn(`  [${orgId}] [manifest reconcile] skip unreadable local file ${trackingKey}`);
-        } else if (entry.contentHash && localHash !== entry.contentHash) {
-          await pushLocalFileAtPath(localFilePath);
-        } else {
-          deleteLocalReconcile(localFilePath, entry.fileId, trackingKey);
+        else if (scope === 'team' && teamId) {
+            q = query(filesRef, where('scope', '==', 'team'), where('teamId', '==', teamId), where('path', '==', docPath));
         }
-      } else if (!entry && onDisk && !cloud) {
-        const baselineHash = lastSyncedHash.get(trackingKey);
-        let localHash;
-        try {
-          ({ contentHash: localHash } = readLocalFilePayload(localFilePath));
-        } catch {
-          localHash = null;
+        else {
+            return false;
         }
-        if (localHash === null) {
-          console.warn(`  [${orgId}] [manifest reconcile] skip unreadable local file ${trackingKey}`);
-        } else if (baselineHash && localHash === baselineHash) {
-          deleteLocalReconcile(localFilePath, null, trackingKey);
-        } else {
-          await pushLocalFileAtPath(localFilePath);
+        const snap = await getDocs(q);
+        if (snap.empty)
+            return false;
+        // Also require the doc's contentHash to match the baseline. A doc
+        // with the same path but a different hash means a web edit
+        // happened that the daemon didn't observe; treat as "missing" so
+        // the push side proceeds and the pull side can reconcile.
+        const firstDoc = snap.docs[0];
+        return firstDoc ? firstDoc.data()['contentHash'] === contentHash : false;
+    }
+    async function pushToFirestore(filePath, data, mimeType, localModifiedAt) {
+        const { scope, teamId, docPath } = scopeFromLocalPath(filePath, LOCAL_PATH, teamIdsByName);
+        const trackingKey = `${scope}:${docPath}`;
+        // Skip if the local content is unchanged since the last sync. This
+        // is the push-side counterpart of the content baseline: an editor
+        // re-saving or touching a file (or the watcher re-emitting it on
+        // startup) must not push stale bytes over a newer server edit. Only
+        // a genuine content change proceeds.
+        //
+        // DOU-217: trust the baseline ONLY after verifying the Firestore
+        // doc actually exists. DOU-55 startup reconcile deletes local orphans
+        // when the manifest records a remote delete; this guard applies when
+        // pushToFirestore runs at runtime (chokidar add/change) and the
+        // baseline would otherwise suppress re-upload forever.
+        const contentHash = computeContentHash(data);
+        if (lastSyncedHash.get(trackingKey) === contentHash) {
+            if (await firestoreDocExists({ scope, teamId, docPath, contentHash })) {
+                return;
+            }
+            console.log(`  [${orgId}] [reconcile] dropping stale baseline for ${docPath} (Firestore doc missing); re-pushing`);
+            deleteBaseline(trackingKey);
         }
-      } else if (entry && !onDisk && cloud) {
-        await deleteRemoteReconcile(cloud.data, trackingKey);
-      } else if ((entry || cloud) && onDisk && cloud) {
-        manifestStore.upsertEntry(trackingKey, {
-          fileId: cloud.fileId,
-          contentHash: cloud.data.contentHash,
-          lastSyncedAt: cloud.data.updatedAt || cloud.data.createdAt || new Date().toISOString(),
-        });
-      } else if (!entry && onDisk && cloud) {
-        manifestStore.upsertEntry(trackingKey, {
-          fileId: cloud.fileId,
-          contentHash: cloud.data.contentHash,
-          lastSyncedAt: cloud.data.updatedAt || cloud.data.createdAt || new Date().toISOString(),
+        const now = new Date().toISOString();
+        // Set the echo-suppression marker BEFORE writing. Our own write
+        // round-trips through the Firestore listener; without a marker
+        // already in place, that echo is treated as an incoming change and
+        // triggers a spurious self-pull, which (a) reads the blob before it
+        // is uploaded (object-not-found) and (b) adds the path to
+        // suppressLocal, swallowing a subsequent rename's unlink (leaving a
+        // duplicate doc). Pre-setting it suppresses the echo.
+        lastKnownUpdate.set(trackingKey, now);
+        const result = await pushFileToCloud({
+            filesRef,
+            storage,
+            orgId,
+            userId,
+            scope,
+            teamId,
+            docPath,
+            data,
+            mimeType,
+            now,
+            localModifiedAt,
         });
-      }
+        // Record the synced content baseline whenever local matches the
+        // server (created/updated, or already-equal noop), so the pull side
+        // can tell "local unchanged" from "local edited" by content.
+        if (shouldPersistLocalSyncState(result)) {
+            setBaseline(trackingKey, contentHash);
+            // Narrow to the variants that actually carry fileId (every
+            // variant shouldPersistLocalSyncState accepts: created, updated,
+            // noop). The skipped/skipped-stale variants are gated out above.
+            if (result.action === 'created' || result.action === 'updated' || result.action === 'noop') {
+                manifestStore.upsertEntry(trackingKey, {
+                    fileId: result.fileId,
+                    contentHash,
+                    lastSyncedAt: now,
+                });
+                manifestStore.flush();
+            }
+        }
+        else if (result.action === 'skipped-stale') {
+            // The server copy is genuinely newer; clear the pre-set marker so
+            // its firestore -> local snapshot is allowed through to update the
+            // local file.
+            lastKnownUpdate.delete(trackingKey);
+        }
+        if (result.action === 'created') {
+            console.log(`  [${orgId}] [local → firestore] CREATE ${docPath} (${scope}, ${mimeType})`);
+        }
+        else if (result.action === 'updated') {
+            console.log(`  [${orgId}] [local → firestore] UPDATE ${docPath} (${scope})`);
+        }
+        else if (result.action === 'skipped-stale') {
+            console.log(`  [${orgId}] [local → firestore] SKIP ${docPath} (server copy is newer)`);
+        }
+        if ((result.action === 'created' || result.action === 'updated') && result.storageError) {
+            console.error(`  [${orgId}] [storage] upload failed for ${docPath}: ${result.storageError?.message}`);
+        }
     }
-
-    manifestStore.flush();
-    console.log(`  [${orgId}] Manifest reconcile complete.`);
-  }
-
-  await reconcileManifestOnStartup();
-
-  // Wire per-team file listeners and the live teams-collection watcher
-  // after reconcile so initial onSnapshot deliveries cannot race with
-  // startup cleanup (DOU-55). applyChange on the live listener picks
-  // up teamspaces created/renamed/removed after daemon start without
-  // restarting sync.
-  for (const [teamId, teamData] of teamRegistry.entries()) {
-    setupTeam(teamId, teamData);
-  }
-  const teamsUnsub = onSnapshot(collection(db, `orgs/${orgId}/teams`), (snapshot) => {
-    snapshot.docChanges().forEach((change) => {
-      teamRegistry.applyChange({
-        type: change.type,
-        id: change.doc.id,
-        data: change.doc.data(),
-      });
-    });
-  }, (err) => console.error(`  [${orgId}] Teams listener error:`, err));
-  unsubscribers.push(teamsUnsub);
-
-  function startFirestoreListeners() {
-    console.log(`  [${orgId}] Starting Firestore listeners...`);
-
-    if (userId) {
-      const privateQ = query(filesRef, where('scope', '==', 'private'), where('ownerId', '==', userId));
-      const privateUnsub = onSnapshot(privateQ, snapshot => {
-        snapshot.docChanges().forEach(change => {
-          const data = change.doc.data();
-          const realPath = path.join(LOCAL_PATH, PRIVATE_FOLDER, data.path);
-
-          track(handleFirestoreChange(change, () => realPath)
-            .catch(err => console.error(`  [${orgId}] Firestore change handler error:`, err && err.message)));
-
-          if (change.type !== 'removed') {
-            updateSharedByMeSymlink(data, realPath);
-          } else {
-            const symlinkPath = path.join(LOCAL_PATH, SHARED_BY_ME_FOLDER, data.path);
-            try { fs.lstatSync(symlinkPath); fs.unlinkSync(symlinkPath); } catch (e) { /* ok */ }
-          }
+    async function deleteFromFirestore(filePath) {
+        const { scope, teamId, docPath } = scopeFromLocalPath(filePath, LOCAL_PATH, teamIdsByName);
+        const trackingKey = `${scope}:${docPath}`;
+        lastKnownUpdate.delete(trackingKey);
+        const result = await deleteFileFromCloud({
+            filesRef,
+            storage,
+            orgId,
+            userId,
+            scope,
+            teamId,
+            docPath,
         });
-      }, err => console.error(`  [${orgId}] Private files listener error:`, err));
-      unsubscribers.push(privateUnsub);
-      console.log(`  [${orgId}]   Listening: Private files + Shared by Me symlinks`);
-
-      // scope=='private' is required: Firestore rules only grant
-      // sharedWith-based reads on private files, so the query must
-      // constrain scope or the whole listen is denied (rules are not
-      // filters). See tests/rules.test.js "shared-with-me query".
-      const sharedQ = query(
-        filesRef,
-        where('scope', '==', 'private'),
-        where('sharedWith', 'array-contains', userId),
-      );
-      const sharedUnsub = onSnapshot(sharedQ, snapshot => {
-        snapshot.docChanges().forEach(change => {
-          const data = change.doc.data();
-          if (data.ownerId === userId) return;
-          track(handleFirestoreChange(change, () =>
-            path.join(LOCAL_PATH, SHARED_WITH_ME_FOLDER, data.path),
-          ).catch(err => console.error(`  [${orgId}] Firestore change handler error:`, err && err.message)));
-        });
-      }, err => console.error(`  [${orgId}] Shared with me listener error:`, err));
-      unsubscribers.push(sharedUnsub);
-      console.log(`  [${orgId}]   Listening: Shared with Me`);
-    }
-  }
-
-  // DOU-217 helper: does a doc with this path + matching contentHash
-  // exist in Firestore right now? Startup reconcile (DOU-55) handles
-  // manifest-present orphans; this check covers the runtime push path
-  // when chokidar re-emits a file whose baseline still matches but the
-  // Firestore doc is gone (e.g. corrupt/missing manifest).
-  async function firestoreDocExists({ scope, teamId, docPath, contentHash }) {
-    let q;
-    if (scope === 'private') {
-      q = query(filesRef,
-        where('scope', '==', 'private'),
-        where('ownerId', '==', userId),
-        where('path', '==', docPath));
-    } else if (scope === 'team' && teamId) {
-      q = query(filesRef,
-        where('scope', '==', 'team'),
-        where('teamId', '==', teamId),
-        where('path', '==', docPath));
-    } else {
-      return false;
+        if (result.action === 'deleted') {
+            console.log(`  [${orgId}] [local → firestore] DELETE ${docPath} (${scope})`);
+            manifestStore.removeEntry(trackingKey);
+        }
     }
-    const snap = await getDocs(q);
-    if (snap.empty) return false;
-    // Also require the doc's contentHash to match the baseline. A doc
-    // with the same path but a different hash means a web edit
-    // happened that the daemon didn't observe; treat as "missing" so
-    // the push side proceeds and the pull side can reconcile.
-    return snap.docs[0].data().contentHash === contentHash;
-  }
-
-  async function pushToFirestore(filePath, data, mimeType, localModifiedAt) {
-    const { scope, teamId, docPath } = scopeFromLocalPath(filePath, LOCAL_PATH, teamIdsByName);
-    const trackingKey = `${scope}:${docPath}`;
-
-    // Skip if the local content is unchanged since the last sync. This
-    // is the push-side counterpart of the content baseline: an editor
-    // re-saving or touching a file (or the watcher re-emitting it on
-    // startup) must not push stale bytes over a newer server edit. Only
-    // a genuine content change proceeds.
-    //
-    // DOU-217: trust the baseline ONLY after verifying the Firestore
-    // doc actually exists. DOU-55 startup reconcile deletes local orphans
-    // when the manifest records a remote delete; this guard applies when
-    // pushToFirestore runs at runtime (chokidar add/change) and the
-    // baseline would otherwise suppress re-upload forever.
-    const contentHash = computeContentHash(data);
-    if (lastSyncedHash.get(trackingKey) === contentHash) {
-      if (await firestoreDocExists({ scope, teamId, docPath, contentHash })) {
-        return;
-      }
-      console.log(`  [${orgId}] [reconcile] dropping stale baseline for ${docPath} (Firestore doc missing); re-pushing`);
-      deleteBaseline(trackingKey);
+    // Determine whether a local path corresponds to a syncable directory.
+    // Excludes the scope-root directories themselves (Private, Shared
+    // with Me, Shared by Me, and the per-team roots) since those are
+    // managed by ensureFolderStructure, not the user.
+    function isSyncableLocalDir(rel) {
+        if (!rel)
+            return false;
+        if (rel === PRIVATE_FOLDER || rel === SHARED_WITH_ME_FOLDER || rel === SHARED_BY_ME_FOLDER) {
+            return false;
+        }
+        if (rel.startsWith(SHARED_WITH_ME_FOLDER + path.sep))
+            return false;
+        if (rel.startsWith(SHARED_BY_ME_FOLDER + path.sep))
+            return false;
+        const parts = rel.split(path.sep);
+        // A bare team root (e.g. "Engineering Teamspace") corresponds to
+        // the scope root, not a subdirectory. Skip these.
+        if (parts.length === 1 && parts[0]?.endsWith(' Teamspace'))
+            return false;
+        return true;
     }
-
-    const now = new Date().toISOString();
-
-    // Set the echo-suppression marker BEFORE writing. Our own write
-    // round-trips through the Firestore listener; without a marker
-    // already in place, that echo is treated as an incoming change and
-    // triggers a spurious self-pull, which (a) reads the blob before it
-    // is uploaded (object-not-found) and (b) adds the path to
-    // suppressLocal, swallowing a subsequent rename's unlink (leaving a
-    // duplicate doc). Pre-setting it suppresses the echo.
-    lastKnownUpdate.set(trackingKey, now);
-
-    const result = await pushFileToCloud({
-      filesRef,
-      storage,
-      orgId,
-      userId,
-      scope,
-      teamId,
-      docPath,
-      data,
-      mimeType,
-      now,
-      localModifiedAt,
-    });
-
-    // Record the synced content baseline whenever local matches the
-    // server (created/updated, or already-equal noop), so the pull side
-    // can tell "local unchanged" from "local edited" by content.
-    if (shouldPersistLocalSyncState(result)) {
-      setBaseline(trackingKey, contentHash);
-      if (result.fileId) {
-        manifestStore.upsertEntry(trackingKey, {
-          fileId: result.fileId,
-          contentHash,
-          lastSyncedAt: now,
+    async function pushDirToFirestore(dirPath) {
+        const { scope, teamId, docPath } = scopeFromLocalPath(dirPath, LOCAL_PATH, teamIdsByName);
+        if (!docPath)
+            return; // scope root
+        const trackingKey = `${scope}:${docPath}`;
+        const now = new Date().toISOString();
+        lastKnownUpdate.set(trackingKey, now);
+        const result = await pushFolderToCloud({
+            filesRef,
+            scope,
+            teamId,
+            userId,
+            docPath,
+            now,
         });
-        manifestStore.flush();
-      }
-    } else if (result.action === 'skipped-stale') {
-      // The server copy is genuinely newer; clear the pre-set marker so
-      // its firestore -> local snapshot is allowed through to update the
-      // local file.
-      lastKnownUpdate.delete(trackingKey);
-    }
-
-    if (result.action === 'created') {
-      console.log(`  [${orgId}] [local → firestore] CREATE ${docPath} (${scope}, ${mimeType})`);
-    } else if (result.action === 'updated') {
-      console.log(`  [${orgId}] [local → firestore] UPDATE ${docPath} (${scope})`);
-    } else if (result.action === 'skipped-stale') {
-      console.log(`  [${orgId}] [local → firestore] SKIP ${docPath} (server copy is newer)`);
-    }
-    if (result.storageError) {
-      console.error(`  [${orgId}] [storage] upload failed for ${docPath}: ${result.storageError.message}`);
-    }
-  }
-
-  async function deleteFromFirestore(filePath) {
-    const { scope, teamId, docPath } = scopeFromLocalPath(filePath, LOCAL_PATH, teamIdsByName);
-    const trackingKey = `${scope}:${docPath}`;
-    lastKnownUpdate.delete(trackingKey);
-
-    const result = await deleteFileFromCloud({
-      filesRef,
-      storage,
-      orgId,
-      userId,
-      scope,
-      teamId,
-      docPath,
-    });
-
-    if (result.action === 'deleted') {
-      console.log(`  [${orgId}] [local → firestore] DELETE ${docPath} (${scope})`);
-      manifestStore.removeEntry(trackingKey);
-    }
-  }
-
-  // Determine whether a local path corresponds to a syncable directory.
-  // Excludes the scope-root directories themselves (Private, Shared
-  // with Me, Shared by Me, and the per-team roots) since those are
-  // managed by ensureFolderStructure, not the user.
-  function isSyncableLocalDir(rel) {
-    if (!rel) return false;
-    if (rel === PRIVATE_FOLDER || rel === SHARED_WITH_ME_FOLDER || rel === SHARED_BY_ME_FOLDER) {
-      return false;
-    }
-    if (rel.startsWith(SHARED_WITH_ME_FOLDER + path.sep)) return false;
-    if (rel.startsWith(SHARED_BY_ME_FOLDER + path.sep)) return false;
-    const parts = rel.split(path.sep);
-    // A bare team root (e.g. "Engineering Teamspace") corresponds to
-    // the scope root, not a subdirectory. Skip these.
-    if (parts.length === 1 && parts[0].endsWith(' Teamspace')) return false;
-    return true;
-  }
-
-  async function pushDirToFirestore(dirPath) {
-    const { scope, teamId, docPath } = scopeFromLocalPath(dirPath, LOCAL_PATH, teamIdsByName);
-    if (!docPath) return; // scope root
-    const trackingKey = `${scope}:${docPath}`;
-    const now = new Date().toISOString();
-    lastKnownUpdate.set(trackingKey, now);
-
-    const result = await pushFolderToCloud({
-      filesRef,
-      scope,
-      teamId,
-      userId,
-      docPath,
-      now,
-    });
-
-    if (result.action === 'ensured' && result.folderId) {
-      console.log(`  [${orgId}] [local → firestore] FOLDER ${docPath} (${scope})`);
-    }
-  }
-
-  async function deleteDirFromFirestore(dirPath) {
-    const { scope, teamId, docPath } = scopeFromLocalPath(dirPath, LOCAL_PATH, teamIdsByName);
-    if (!docPath) return;
-    const trackingKey = `${scope}:${docPath}`;
-    lastKnownUpdate.delete(trackingKey);
-
-    const result = await deleteFolderFromCloud({
-      filesRef,
-      storage,
-      orgId,
-      scope,
-      teamId,
-      userId,
-      docPath,
-    });
-
-    if (result.action === 'deleted') {
-      // childCount > 0 means cascade did real work; useful in logs
-      // when investigating future folder-delete reports.
-      const childSuffix = result.childCount > 0 ? ` (+${result.childCount} children)` : '';
-      console.log(`  [${orgId}] [local → firestore] RMFOLDER ${docPath} (${scope})${childSuffix}`);
+        if (result.action === 'ensured' && result.folderId) {
+            console.log(`  [${orgId}] [local → firestore] FOLDER ${docPath} (${scope})`);
+        }
     }
-  }
-
-  function handleLocalChange(filePath) {
-    if (suppressLocal.has(filePath)) return;
-
-    const rel = path.relative(LOCAL_PATH, filePath);
-    if (rel.startsWith(SHARED_WITH_ME_FOLDER + path.sep)) return;
-    if (rel.startsWith(SHARED_BY_ME_FOLDER + path.sep)) return;
-
-    let stat;
-    try {
-      stat = fs.statSync(filePath);
-    } catch (err) {
-      return; // disappeared between event and read
+    async function deleteDirFromFirestore(dirPath) {
+        const { scope, teamId, docPath } = scopeFromLocalPath(dirPath, LOCAL_PATH, teamIdsByName);
+        if (!docPath)
+            return;
+        const trackingKey = `${scope}:${docPath}`;
+        lastKnownUpdate.delete(trackingKey);
+        const result = await deleteFolderFromCloud({
+            filesRef,
+            storage,
+            orgId,
+            scope,
+            teamId,
+            userId,
+            docPath,
+        });
+        if (result.action === 'deleted') {
+            // childCount > 0 means cascade did real work; useful in logs
+            // when investigating future folder-delete reports.
+            const childSuffix = result.childCount > 0 ? ` (+${result.childCount} children)` : '';
+            console.log(`  [${orgId}] [local → firestore] RMFOLDER ${docPath} (${scope})${childSuffix}`);
+        }
     }
-    if (!stat.isFile()) return;
-    if (stat.size > maxUploadBytes) {
-      console.error(`  [${orgId}] [skip] ${rel} exceeds ${maxUploadBytes} byte cap (${stat.size} bytes)`);
-      return;
+    function handleLocalChange(filePath) {
+        if (suppressLocal.has(filePath))
+            return;
+        const rel = path.relative(LOCAL_PATH, filePath);
+        if (rel.startsWith(SHARED_WITH_ME_FOLDER + path.sep))
+            return;
+        if (rel.startsWith(SHARED_BY_ME_FOLDER + path.sep))
+            return;
+        let stat;
+        try {
+            stat = fs.statSync(filePath);
+        }
+        catch {
+            return; // disappeared between event and read
+        }
+        if (!stat.isFile())
+            return;
+        if (stat.size > maxUploadBytes) {
+            console.error(`  [${orgId}] [skip] ${rel} exceeds ${maxUploadBytes} byte cap (${stat.size} bytes)`);
+            return;
+        }
+        const ext = extFromPath(rel);
+        const mimeType = mimeTypeFromExt(ext);
+        // Text files: read as a UTF-8 string so future text-aware features
+        // (line-level diffing, conflict markers) can work. Binary files:
+        // read as a Buffer so bytes round-trip without corruption.
+        const data = isTextMimeType(mimeType)
+            ? fs.readFileSync(filePath, 'utf-8')
+            : fs.readFileSync(filePath);
+        const localModifiedAt = stat.mtime.toISOString();
+        // Yjs path (DOU-178 PR 3): route text edits into the binding so
+        // the disk delta is published as a yupdate (preserving concurrent
+        // web edits via fast-diff). The binding only exists once the
+        // Firestore listener has seen the file; for the very first
+        // local-only save the binding hasn't been created yet, and the
+        // blob path is still the only writer. Subsequent saves go through
+        // both paths until PR 4 retires the blob upload.
+        if (typeof data === 'string' && isTextMimeType(mimeType)) {
+            const binding = bindingsByPath.get(filePath);
+            if (binding)
+                binding.applyDiskText(data);
+        }
+        track(enqueueLocalOp(filePath, () => pushToFirestore(filePath, data, mimeType, localModifiedAt).catch((err) => console.error(`  [${orgId}] Push error for ${rel}: ${err?.message}`))));
     }
-
-    const ext = extFromPath(rel);
-    const mimeType = mimeTypeFromExt(ext);
-    // Text files: read as a UTF-8 string so future text-aware features
-    // (line-level diffing, conflict markers) can work. Binary files:
-    // read as a Buffer so bytes round-trip without corruption.
-    const data = isTextMimeType(mimeType)
-      ? fs.readFileSync(filePath, 'utf-8')
-      : fs.readFileSync(filePath);
-    const localModifiedAt = stat.mtime.toISOString();
-
-    // Yjs path (DOU-178 PR 3): route text edits into the binding so
-    // the disk delta is published as a yupdate (preserving concurrent
-    // web edits via fast-diff). The binding only exists once the
-    // Firestore listener has seen the file; for the very first
-    // local-only save the binding hasn't been created yet, and the
-    // blob path is still the only writer. Subsequent saves go through
-    // both paths until PR 4 retires the blob upload.
-    if (isTextMimeType(mimeType)) {
-      const binding = bindingsByPath.get(filePath);
-      if (binding) binding.applyDiskText(data);
+    function handleLocalDirAdded(dirPath) {
+        if (suppressLocal.has(dirPath))
+            return;
+        const rel = path.relative(LOCAL_PATH, dirPath);
+        if (!isSyncableLocalDir(rel))
+            return;
+        track(pushDirToFirestore(dirPath).catch((err) => console.error(`  [${orgId}] Folder push error for ${rel}: ${err?.message}`)));
     }
-
-    track(enqueueLocalOp(filePath, () =>
-      pushToFirestore(filePath, data, mimeType, localModifiedAt).catch(err =>
-        console.error(`  [${orgId}] Push error for ${rel}: ${err.message}`)
-      )
-    ));
-  }
-
-  function handleLocalDirAdded(dirPath) {
-    if (suppressLocal.has(dirPath)) return;
-    const rel = path.relative(LOCAL_PATH, dirPath);
-    if (!isSyncableLocalDir(rel)) return;
-    track(pushDirToFirestore(dirPath).catch(err =>
-      console.error(`  [${orgId}] Folder push error for ${rel}: ${err.message}`)
-    ));
-  }
-
-  function handleLocalDirRemoved(dirPath) {
-    if (suppressLocal.has(dirPath)) return;
-    const rel = path.relative(LOCAL_PATH, dirPath);
-    if (!isSyncableLocalDir(rel)) return;
-    track(deleteDirFromFirestore(dirPath).catch(err =>
-      console.error(`  [${orgId}] Folder delete error for ${rel}: ${err.message}`)
-    ));
-  }
-
-  function startLocalWatcher() {
-    console.log(`  [${orgId}] Watching local files...`);
-
-    watcher = chokidar.watch(LOCAL_PATH, {
-      ignored: [
-        // Dotfiles (the sync engine's own .compound-sync-state.json lives
-        // here, plus things like .DS_Store, .git, etc. that the user
-        // doesn't want syncing).
-        /(^|[\/\\])\./,
-        // node_modules: large dependency dirs, never appropriate to sync.
-        /node_modules/,
-      ],
-      persistent: true,
-      ignoreInitial: false,
-      followSymlinks: false,
-      awaitWriteFinish: {
-        stabilityThreshold: 500,
-        pollInterval: 100,
-      },
-    });
-
-    // Reusable per-event trace logging, gated by COMPOUND_CHOKIDAR_DEBUG.
-    // Writes to both stdout AND a file (default /tmp/chokidar-debug.log)
-    // so traces survive a process kill or buffered stdout. Used by the
-    // Test-on-demand workflow's `Dump diagnostic logs` step for
-    // chokidar-related diagnostic runs. Zero cost when the env var is
-    // unset.
-    const chokidarDebug = process.env.COMPOUND_CHOKIDAR_DEBUG === '1';
-    const chokidarLogPath = process.env.COMPOUND_CHOKIDAR_LOG || '/tmp/chokidar-debug.log';
-    function logEvent(event, p) {
-      if (chokidarDebug) {
-        const rel = path.relative(LOCAL_PATH, p);
-        const line = `  [${orgId}] [chokidar ${event}] ${rel} @ ${new Date().toISOString()}\n`;
-        try { fs.appendFileSync(chokidarLogPath, line); } catch (_) {}
-        console.log(line.trimEnd());
-      }
+    function handleLocalDirRemoved(dirPath) {
+        if (suppressLocal.has(dirPath))
+            return;
+        const rel = path.relative(LOCAL_PATH, dirPath);
+        if (!isSyncableLocalDir(rel))
+            return;
+        track(deleteDirFromFirestore(dirPath).catch((err) => console.error(`  [${orgId}] Folder delete error for ${rel}: ${err?.message}`)));
     }
-
-    watcher.on('add', filePath => { logEvent('add', filePath); handleLocalChange(filePath); });
-    watcher.on('change', filePath => { logEvent('change', filePath); handleLocalChange(filePath); });
-    watcher.on('unlink', filePath => {
-      logEvent('unlink', filePath);
-      if (suppressLocal.has(filePath)) return;
-      const rel = path.relative(LOCAL_PATH, filePath);
-      track(enqueueLocalOp(filePath, () =>
-        deleteFromFirestore(filePath).catch(err =>
-          console.error(`  [${orgId}] Delete error for ${rel}: ${err.message}`)
-        )
-      ));
-    });
-    watcher.on('addDir', dirPath => { logEvent('addDir', dirPath); handleLocalDirAdded(dirPath); });
-    watcher.on('unlinkDir', dirPath => { logEvent('unlinkDir', dirPath); handleLocalDirRemoved(dirPath); });
-    if (chokidarDebug) {
-      watcher.on('raw', (event, p, details) => {
-        const line = `  [${orgId}] [chokidar raw ${event}] ${p} @ ${new Date().toISOString()} ${JSON.stringify(details)}\n`;
-        try { fs.appendFileSync(chokidarLogPath, line); } catch (_) {}
-        console.log(line.trimEnd());
-      });
+    function startLocalWatcher() {
+        console.log(`  [${orgId}] Watching local files...`);
+        watcher = chokidar.watch(LOCAL_PATH, {
+            ignored: [
+                // Dotfiles (the sync engine's own .compound-sync-state.json lives
+                // here, plus things like .DS_Store, .git, etc. that the user
+                // doesn't want syncing).
+                /(^|[\/\\])\./,
+                // node_modules: large dependency dirs, never appropriate to sync.
+                /node_modules/,
+            ],
+            persistent: true,
+            ignoreInitial: false,
+            followSymlinks: false,
+            awaitWriteFinish: {
+                stabilityThreshold: 500,
+                pollInterval: 100,
+            },
+        });
+        // Reusable per-event trace logging, gated by COMPOUND_CHOKIDAR_DEBUG.
+        // Writes to both stdout AND a file (default /tmp/chokidar-debug.log)
+        // so traces survive a process kill or buffered stdout. Used by the
+        // Test-on-demand workflow's `Dump diagnostic logs` step for
+        // chokidar-related diagnostic runs. Zero cost when the env var is
+        // unset.
+        const chokidarDebug = process.env['COMPOUND_CHOKIDAR_DEBUG'] === '1';
+        const chokidarLogPath = process.env['COMPOUND_CHOKIDAR_LOG'] || '/tmp/chokidar-debug.log';
+        function logEvent(event, p) {
+            if (chokidarDebug) {
+                const rel = path.relative(LOCAL_PATH, p);
+                const line = `  [${orgId}] [chokidar ${event}] ${rel} @ ${new Date().toISOString()}\n`;
+                try {
+                    fs.appendFileSync(chokidarLogPath, line);
+                }
+                catch (_) { }
+                console.log(line.trimEnd());
+            }
+        }
+        // Local non-null alias so TS doesn't have to re-narrow `watcher`
+        // on every .on() call below.
+        const w = watcher;
+        w.on('add', (filePath) => { logEvent('add', filePath); handleLocalChange(filePath); });
+        w.on('change', (filePath) => { logEvent('change', filePath); handleLocalChange(filePath); });
+        w.on('unlink', (filePath) => {
+            logEvent('unlink', filePath);
+            if (suppressLocal.has(filePath))
+                return;
+            const rel = path.relative(LOCAL_PATH, filePath);
+            track(enqueueLocalOp(filePath, () => deleteFromFirestore(filePath).catch((err) => console.error(`  [${orgId}] Delete error for ${rel}: ${err?.message}`))));
+        });
+        w.on('addDir', (dirPath) => { logEvent('addDir', dirPath); handleLocalDirAdded(dirPath); });
+        w.on('unlinkDir', (dirPath) => { logEvent('unlinkDir', dirPath); handleLocalDirRemoved(dirPath); });
+        if (chokidarDebug) {
+            w.on('raw', (event, p, details) => {
+                const line = `  [${orgId}] [chokidar raw ${event}] ${p} @ ${new Date().toISOString()} ${JSON.stringify(details)}\n`;
+                try {
+                    fs.appendFileSync(chokidarLogPath, line);
+                }
+                catch { /* ignore */ }
+                console.log(line.trimEnd());
+            });
+        }
+        // Resolve only once chokidar has finished its initial scan and
+        // registered inotify (or FSEvents) watches on every existing
+        // subdirectory. Until 'ready' fires, files written to the watched
+        // tree can be silently missed because the OS-level watch hasn't
+        // attached yet. Callers awaiting startOrgSync get a guarantee
+        // that any local writes after the await are seen by the daemon.
+        return new Promise((resolve) => {
+            w.on('ready', () => {
+                console.log(`  [${orgId}] Local watcher ready.`);
+                resolve();
+            });
+        });
     }
-
-    // Resolve only once chokidar has finished its initial scan and
-    // registered inotify (or FSEvents) watches on every existing
-    // subdirectory. Until 'ready' fires, files written to the watched
-    // tree can be silently missed because the OS-level watch hasn't
-    // attached yet. Callers awaiting startOrgSync get a guarantee
-    // that any local writes after the await are seen by the daemon.
-    return new Promise((resolve) => {
-      watcher.on('ready', () => {
-        console.log(`  [${orgId}] Local watcher ready.`);
-        resolve();
-      });
-    });
-  }
-
-  startFirestoreListeners();
-  await startLocalWatcher();
-
-  return {
-    // Tear down all listeners and the watcher. Awaits every tracked
-    // in-flight handler so callers/tests get a strong "no daemon work
-    // is still running" guarantee on the resolved promise.
-    async stop() {
-      stoppedRef.value = true;
-      manifestStore.flush();
-      for (const unsub of unsubscribers) {
-        try { unsub(); } catch (e) { /* ignore */ }
-      }
-      for (const unsub of teamUnsubscribers.values()) {
-        try { unsub(); } catch (e) { /* ignore */ }
-      }
-      teamUnsubscribers.clear();
-
-      // Drain tracked promises in a loop, bounded by a 5s ceiling.
-      // A handler currently in flight (e.g., a snapshot callback
-      // already dispatched before unsub()) can chain follow-up work
-      // that gets added back to pendingPromises. Loop until the set
-      // quiesces so no daemon task outlives stop() in the common
-      // case. The cap protects against tests where a handler is
-      // genuinely stuck (e.g., emulator pause), so stop() never
-      // hangs indefinitely; anything still pending past 5s is
-      // abandoned and the next test's clearFirestore will sweep it.
-      const drainDeadline = Date.now() + 5000;
-      while (pendingPromises.size > 0 && Date.now() < drainDeadline) {
-        const remaining = Math.max(0, drainDeadline - Date.now());
-        await Promise.race([
-          Promise.all([...pendingPromises]),
-          new Promise((r) => setTimeout(r, remaining)),
-        ]);
-      }
-
-      await Promise.all(
-        [...bindings.values()].map((b) => b.stop().catch(() => {})),
-      );
-      bindings.clear();
-      bindingsByPath.clear();
-
-      if (watcher) await watcher.close();
-    },
-  };
+    startFirestoreListeners();
+    await startLocalWatcher();
+    return {
+        // Tear down all listeners and the watcher. Awaits every tracked
+        // in-flight handler so callers/tests get a strong "no daemon work
+        // is still running" guarantee on the resolved promise.
+        async stop() {
+            stoppedRef.value = true;
+            manifestStore.flush();
+            for (const unsub of unsubscribers) {
+                try {
+                    unsub();
+                }
+                catch (e) { /* ignore */ }
+            }
+            for (const unsub of teamUnsubscribers.values()) {
+                try {
+                    unsub();
+                }
+                catch (e) { /* ignore */ }
+            }
+            teamUnsubscribers.clear();
+            // Drain tracked promises in a loop, bounded by a 5s ceiling.
+            // A handler currently in flight (e.g., a snapshot callback
+            // already dispatched before unsub()) can chain follow-up work
+            // that gets added back to pendingPromises. Loop until the set
+            // quiesces so no daemon task outlives stop() in the common
+            // case. The cap protects against tests where a handler is
+            // genuinely stuck (e.g., emulator pause), so stop() never
+            // hangs indefinitely; anything still pending past 5s is
+            // abandoned and the next test's clearFirestore will sweep it.
+            const drainDeadline = Date.now() + 5000;
+            while (pendingPromises.size > 0 && Date.now() < drainDeadline) {
+                const remaining = Math.max(0, drainDeadline - Date.now());
+                await Promise.race([
+                    Promise.all([...pendingPromises]),
+                    new Promise((r) => setTimeout(r, remaining)),
+                ]);
+            }
+            await Promise.all([...bindings.values()].map((b) => b.stop().catch(() => { })));
+            bindings.clear();
+            bindingsByPath.clear();
+            if (watcher)
+                await watcher.close();
+        },
+    };
 }
+//# sourceMappingURL=org-sync.js.map