@doubling/compound-sync 1.7.1 → 1.10.1

package/org-sync.js

@@ -0,0 +1,710 @@
+// Per-org sync loop, extracted from sync.js so it can be driven in
+// tests against the Firebase emulator (org-sync.test.js, DOU-156)
+// instead of only by launching the daemon. `startOrgSync` wires the
+// Firestore listeners (pull) and the chokidar watcher (push) for one
+// org given injected Firebase handles, and returns a `stop()` that
+// tears down every listener and the watcher.
+//
+// This is a faithful extraction of the former in-sync.js `setupOrgSync`:
+// module globals it used (db, storage, USER_ID, MAX_UPLOAD_BYTES) are
+// now parameters, and the localPath is expected pre-resolved by the
+// 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 } 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';
+
+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;
+    }
+  }
+  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');
+
+  // 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-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}`);
+    }
+  }
+  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);
+        }
+      } 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}`);
+        }
+      } catch (e) { /* doesn't exist */ }
+    }
+  }
+
+  // Static (user-level) folders. Team folders are created per-team by
+  // setupTeam below as soon as the registry sees each teamspace.
+  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';
+
+    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);
+      return;
+    }
+
+    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);
+
+    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);
+    // 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);
+    }
+    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. Wired into the
+  // TeamRegistry; called once per teamspace as it appears.
+  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 => {
+        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}`);
+  };
+
+  // Live listener on the teams collection. Initial snapshot bootstraps
+  // the known teamspaces; subsequent changes pick up new/renamed/
+  // removed teamspaces without restarting the daemon. We await the
+  // first snapshot so the local watcher sees a populated teamIdsByName
+  // before it tries to route any addDir/add events.
+  let teamsUnsub = null;
+  await new Promise((resolve, reject) => {
+    let firstSnapshotResolved = false;
+    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(),
+        });
+      });
+      if (!firstSnapshotResolved) {
+        firstSnapshotResolved = true;
+        console.log(`  [${orgId}] Teams: ${teamRegistry.names().join(', ') || 'none'}`);
+        resolve();
+      }
+    }, (err) => {
+      console.error(`  [${orgId}] Teams listener error:`, err);
+      if (!firstSnapshotResolved) {
+        firstSnapshotResolved = true;
+        reject(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);
+
+          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;
+          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`);
+    }
+  }
+
+  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.
+    const contentHash = computeContentHash(data);
+    if (lastSyncedHash.get(trackingKey) === contentHash) return;
+
+    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);
+
+    // Baseline = what we last saw as the remote contentHash for this
+    // path. pushFileToCloud uses it as a compare-and-swap precondition
+    // (DOU-167): if the remote has moved past this baseline, refuse
+    // the push and surface the conflict to the caller.
+    const baseline = lastSyncedHash.get(trackingKey);
+
+    const result = await pushFileToCloud({
+      filesRef,
+      storage,
+      orgId,
+      userId,
+      scope,
+      teamId,
+      docPath,
+      data,
+      mimeType,
+      now,
+      localModifiedAt,
+      expectedRemoteHash: baseline,
+    });
+
+    // 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 (result.action === 'created' || result.action === 'updated' || result.action === 'noop') {
+      setBaseline(trackingKey, contentHash);
+    } 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);
+    } else if (result.action === 'conflict') {
+      // Another writer landed an edit in the gap between our last sync
+      // and this push. Preserve the user's would-be push as a sibling
+      // conflict copy, pull the new remote state into the live file,
+      // and advance the baseline so the next push (or further edits)
+      // can proceed against the new ground truth.
+      const conflictPath = writeConflictCopy(filePath, data);
+      await pullRemoteIntoLocal(result.remoteData, filePath);
+      setBaseline(trackingKey, result.remoteHash);
+      lastKnownUpdate.delete(trackingKey);
+      console.log(
+        `  [${orgId}] [local → firestore] CONFLICT ${docPath}: ` +
+        `remote changed; local saved to ${path.basename(conflictPath)}`,
+      );
+      return;
+    }
+
+    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}`);
+    }
+  }
+
+  /** Write the proposed (rejected) push to a sibling conflict file.
+   * Returns the new path. Suppresses chokidar so the conflict file's
+   * creation doesn't trigger its own push. */
+  function writeConflictCopy(filePath, data) {
+    const parsed = path.parse(filePath);
+    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+    const conflictPath = path.join(parsed.dir, `${parsed.name}.conflict-${ts}${parsed.ext}`);
+    suppressLocal.add(conflictPath);
+    fs.writeFileSync(conflictPath, data);
+    setTimeout(() => suppressLocal.delete(conflictPath), 1000);
+    return conflictPath;
+  }
+
+  /** Pull the remote blob into the live local path after a conflict.
+   * Uses suppressLocal so chokidar doesn't re-emit the write. */
+  async function pullRemoteIntoLocal(remoteData, localFilePath) {
+    const ext = extFromPath(remoteData.path);
+    const extDerivedMime = mimeTypeFromExt(ext);
+    const isText = isTextMimeType(remoteData.mimeType) || isTextMimeType(extDerivedMime);
+    suppressLocal.add(localFilePath);
+    const blobReadArgs = { storage, orgId, fileId: remoteData.id, ext };
+    const retryOpts = { expectedHash: remoteData.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);
+    }
+    setTimeout(() => suppressLocal.delete(localFilePath), 1000);
+  }
+
+  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})`);
+    }
+  }
+
+  // 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,
+      scope,
+      teamId,
+      userId,
+      docPath,
+    });
+
+    if (result.action === 'deleted') {
+      console.log(`  [${orgId}] [local → firestore] RMFOLDER ${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
+    }
+    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();
+    pushToFirestore(filePath, data, mimeType, localModifiedAt).catch(err =>
+      console.error(`  [${orgId}] Push error: ${err.message}`)
+    );
+  }
+
+  function handleLocalDirAdded(dirPath) {
+    if (suppressLocal.has(dirPath)) return;
+    const rel = path.relative(LOCAL_PATH, dirPath);
+    if (!isSyncableLocalDir(rel)) return;
+    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;
+    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,
+      },
+    });
+
+    watcher.on('add', filePath => handleLocalChange(filePath));
+    watcher.on('change', filePath => handleLocalChange(filePath));
+    watcher.on('unlink', filePath => {
+      if (suppressLocal.has(filePath)) return;
+      deleteFromFirestore(filePath).catch(err => console.error(`  [${orgId}] Delete error: ${err.message}`));
+    });
+    watcher.on('addDir', dirPath => handleLocalDirAdded(dirPath));
+    watcher.on('unlinkDir', dirPath => handleLocalDirRemoved(dirPath));
+
+    // 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. Returns the watcher's
+    // close() promise so callers/tests can await full shutdown.
+    stop() {
+      for (const unsub of unsubscribers) {
+        try { unsub(); } catch (e) { /* ignore */ }
+      }
+      for (const unsub of teamUnsubscribers.values()) {
+        try { unsub(); } catch (e) { /* ignore */ }
+      }
+      teamUnsubscribers.clear();
+      return watcher ? watcher.close() : Promise.resolve();
+    },
+  };
+}