@relayfile/local-mount 0.7.7 → 0.7.9

package/README.md

@@ -21,7 +21,7 @@ const handle = await createMount(projectDir, mountDir, options);
 
 interface MountHandle {
   mountDir: string;
-  syncBack(opts?: { signal?: AbortSignal }): Promise<number>;
+  syncBack(opts?: { signal?: AbortSignal; paths?: Iterable<string> }): Promise<number>;
   startAutoSync(opts?: AutoSyncOptions): AutoSyncHandle;
   cleanup(): void;
 }
@@ -58,8 +58,8 @@ const { ignoredPatterns, readonlyPatterns } = readAgentDotfiles(projectDir, {
 
 High-level helper that:
 1. creates a mount,
-2. starts bidirectional auto-sync (see below, controllable via `autoSync`),
-3. runs a CLI inside the mount,
+2. starts bidirectional auto-sync (see below, controllable via `autoSync`) and waits for the watchers to be ready when auto-sync is enabled,
+3. runs `onBeforeLaunch`, then runs a CLI inside the mount,
 4. forwards `SIGINT` and `SIGTERM`,
 5. stops auto-sync and runs a final sync-back pass after the child exits,
 6. cleans up the mount directory.
@@ -84,7 +84,10 @@ interface AutoSyncOptions {
 
 interface AutoSyncHandle {
   stop(opts?: { signal?: AbortSignal }): Promise<void>;
+  flushPending(opts?: { signal?: AbortSignal }): Promise<number>;
   reconcile(opts?: { signal?: AbortSignal }): Promise<number>;
+  getDirtyPaths(): IterableIterator<string>;
+  watchersHealthy(): boolean;
   totalChanges(): number;
   ready(): Promise<void>;
 }
@@ -103,6 +106,7 @@ launchOnMount({ /* ... */, autoSync: { scanIntervalMs: 5_000, debounceMs: 100 }
 How it works:
 - [@parcel/watcher](https://www.npmjs.com/package/@parcel/watcher) watches both the mount and the project tree using native FSEvents/inotify/ReadDirectoryChangesW
 - every `scanIntervalMs`, a full reconcile walks both trees as a safety net for missed events
+- watcher events are tracked as dirty paths, so shutdown can flush pending path-level work and make the final sync-back proportional to the number of mount-side changes when the watcher state stayed healthy
 - `stop({ signal })` still closes watchers if aborted, but skips the final draining reconcile
 - per-file `mtime` is tracked at the last sync, so the scan skips files that haven't changed
 
@@ -267,6 +271,8 @@ The returned number is the count of files written back to `projectDir` in that p
 
 `syncBack({ signal })` checks for aborts between files. If the signal aborts during shutdown, it returns the partial count accumulated so far instead of throwing, which lets callers report a partial sync and still run cleanup.
 
+`syncBack({ paths })` limits the pass to explicit mount-relative paths. This is used by auto-sync shutdown after `watchersHealthy()` confirms both watchers subscribed and no watcher error was observed; otherwise callers should omit `paths` to keep the full-walk safety net.
+
 `reconcile({ signal })` and the internal tree walk also poll for aborts between file visits so an in-flight draining scan can stop cooperatively.
 
 ## Safety constraints

package/dist/auto-sync.d.ts

@@ -46,10 +46,18 @@ export interface AutoSyncHandle {
     stop(opts?: {
         signal?: AbortSignal;
     }): Promise<void>;
+    /** Drain currently debounced watcher events. Falls back to reconcile if watchers are degraded. */
+    flushPending(opts?: {
+        signal?: AbortSignal;
+    }): Promise<number>;
     /** Force a reconcile now; returns number of files copied/deleted. */
     reconcile(opts?: {
         signal?: AbortSignal;
     }): Promise<number>;
+    /** Mount-side paths that still need a final one-shot syncBack check. */
+    getDirtyPaths(): IterableIterator<string>;
+    /** True once both watchers subscribed and no watcher error has been observed. */
+    watchersHealthy(): boolean;
     /** Cumulative files changed (copied or deleted) since autosync started. */
     totalChanges(): number;
     /** Resolves once both watchers have completed their initial scan. */

package/dist/auto-sync.js

@@ -1,6 +1,7 @@
 import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, } from 'node:fs';
 import path from 'node:path';
 import watcher from '@parcel/watcher';
+const STOP_EVENT_SETTLE_MS = 250;
 export function startAutoSync(ctx, opts = {}) {
     const scanIntervalMs = opts.scanIntervalMs ?? 10_000;
     const debounceMs = opts.debounceMs ?? 50;
@@ -9,9 +10,60 @@ export function startAutoSync(ctx, opts = {}) {
     primeState(state, ctx);
     let syncing = false;
     let pending = false;
+    let stopping = false;
     let stopped = false;
+    let watchersReadySettled = false;
+    let watcherDegraded = false;
     let totalChanges = 0;
+    const pendingPaths = new Set();
     const pendingDebounces = new Map();
+    const dirtyMountPaths = new Set();
+    const watchersHealthy = () => watchersReadySettled && !watcherDegraded;
+    const markWatcherDegraded = (err) => {
+        watcherDegraded = true;
+        onError(err);
+    };
+    const clearPendingDebounces = () => {
+        for (const t of pendingDebounces.values())
+            clearTimeout(t);
+        pendingDebounces.clear();
+    };
+    const syncPath = (relPosix) => {
+        if (!isSyncCandidate(relPosix, ctx)) {
+            dirtyMountPaths.delete(relPosix);
+            return 0;
+        }
+        try {
+            const changed = syncOneFile(relPosix, state, ctx);
+            dirtyMountPaths.delete(relPosix);
+            return changed ? 1 : 0;
+        }
+        catch (err) {
+            onError(err);
+            return 0;
+        }
+    };
+    const flushPendingPaths = async (opts) => {
+        const signal = opts?.signal;
+        if (signal?.aborted) {
+            return 0;
+        }
+        let count = 0;
+        let processed = 0;
+        for (const relPosix of Array.from(pendingPaths)) {
+            if (signal?.aborted) {
+                break;
+            }
+            pendingPaths.delete(relPosix);
+            count += syncPath(relPosix);
+            processed += 1;
+            if (signal && processed % 64 === 0 && !signal.aborted) {
+                await new Promise((resolve) => setImmediate(resolve));
+            }
+        }
+        totalChanges += count;
+        return count;
+    };
     const runReconcile = async (opts) => {
         const signal = opts?.signal;
         if (signal?.aborted) {
@@ -23,8 +75,10 @@ export function startAutoSync(ctx, opts = {}) {
         }
         syncing = true;
         let count = 0;
+        let completed = false;
         try {
             count = reconcile(state, ctx, onError, signal);
+            completed = !signal?.aborted;
         }
         catch (err) {
             onError(err);
@@ -36,53 +90,71 @@ export function startAutoSync(ctx, opts = {}) {
             pending = false;
             try {
                 count += reconcile(state, ctx, onError, signal);
+                completed = !signal?.aborted;
             }
             catch (err) {
                 onError(err);
+                completed = false;
             }
         }
+        if (completed) {
+            pendingPaths.clear();
+            dirtyMountPaths.clear();
+        }
         totalChanges += count;
         return count;
     };
-    const syncPathFromRoot = (root, absPath) => {
-        const rel = path.relative(root, absPath);
-        if (rel === '' || rel.startsWith('..'))
-            return;
-        const relPosix = rel.split(path.sep).join('/');
-        if (!isSyncCandidate(relPosix, ctx))
-            return;
+    const flushPending = async (opts) => {
+        if (opts?.signal?.aborted) {
+            return 0;
+        }
         try {
-            const changed = syncOneFile(relPosix, state, ctx);
-            if (changed)
-                totalChanges += 1;
+            await watchersReady;
         }
-        catch (err) {
-            onError(err);
+        catch {
+            // Subscription setup failure is already marked degraded and surfaced.
+        }
+        if (opts?.signal?.aborted) {
+            return 0;
         }
+        clearPendingDebounces();
+        if (!watchersHealthy()) {
+            return runReconcile(opts);
+        }
+        return flushPendingPaths(opts);
     };
     const schedulePathSync = (root, absPath) => {
-        // Once stop() has begun, refuse to schedule new timers. Watcher
-        // callbacks can still fire during the unsubscribe await (native
-        // backends deliver queued events asynchronously); without this guard
-        // those events would create timers that outlive stop() and do file
-        // work against a mount the caller may have already cleaned up.
         if (stopped)
             return;
+        const relPosix = root === ctx.realMountDir
+            ? toRelPosix(absPath, ctx)
+            : toRelPosixFromProject(absPath, ctx);
+        if (relPosix === null || !isSyncCandidate(relPosix, ctx))
+            return;
+        pendingPaths.add(relPosix);
+        if (root === ctx.realMountDir) {
+            dirtyMountPaths.add(relPosix);
+        }
+        // During stop(), keep accepting queued watcher events so the final flush
+        // can process them, but don't create timers that could outlive teardown.
+        if (stopping)
+            return;
         // Coalesce bursts of events for the same path. The reconcile path
         // re-checks content via mtime+bytes, so a partial-write event that
         // races a later write is harmless.
-        const existing = pendingDebounces.get(absPath);
+        const existing = pendingDebounces.get(relPosix);
         if (existing)
             clearTimeout(existing);
         const t = setTimeout(() => {
-            pendingDebounces.delete(absPath);
-            syncPathFromRoot(root, absPath);
+            pendingDebounces.delete(relPosix);
+            pendingPaths.delete(relPosix);
+            totalChanges += syncPath(relPosix);
         }, debounceMs);
-        pendingDebounces.set(absPath, t);
+        pendingDebounces.set(relPosix, t);
     };
     const subscribeTo = (root) => watcher.subscribe(root, (err, events) => {
         if (err) {
-            onError(err);
+            markWatcherDegraded(err);
             return;
         }
         for (const ev of events) {
@@ -105,8 +177,11 @@ export function startAutoSync(ctx, opts = {}) {
         if (projectResult.status === 'fulfilled')
             projectSub = projectResult.value;
         if (mountResult.status === 'fulfilled' && projectResult.status === 'fulfilled') {
+            watchersReadySettled = true;
             return;
         }
+        watchersReadySettled = true;
+        watcherDegraded = true;
         await Promise.allSettled([
             mountSub?.unsubscribe(),
             projectSub?.unsubscribe(),
@@ -120,7 +195,7 @@ export function startAutoSync(ctx, opts = {}) {
     // If subscription setup fails, surface via onError rather than an unhandled
     // rejection. stop() still awaits the same promise and will observe the
     // rejection after the cleanup above has already run.
-    watchersReady.catch((err) => onError(err));
+    watchersReady.catch((err) => markWatcherDegraded(err));
     const interval = setInterval(() => {
         void runReconcile();
     }, scanIntervalMs);
@@ -128,10 +203,6 @@ export function startAutoSync(ctx, opts = {}) {
     interval.unref?.();
     return {
         async stop(opts) {
-            // Flip the flag first so any watcher callbacks delivered during the
-            // awaits below refuse to schedule new timers.
-            stopped = true;
-            clearInterval(interval);
             try {
                 await watchersReady;
             }
@@ -139,23 +210,37 @@ export function startAutoSync(ctx, opts = {}) {
                 // Setup failed and already cleaned up any partial subscription;
                 // mountSub / projectSub were reset to undefined before the throw.
             }
+            if (!opts?.signal?.aborted && watchersHealthy()) {
+                await new Promise((resolve) => setTimeout(resolve, STOP_EVENT_SETTLE_MS));
+            }
+            stopping = true;
+            clearInterval(interval);
+            clearPendingDebounces();
             await Promise.allSettled([
                 mountSub?.unsubscribe(),
                 projectSub?.unsubscribe(),
             ]);
-            // Clear debounces *after* unsubscribe resolves: any timer scheduled
-            // between stop() being called and the watcher actually quiescing is
-            // gathered here, so none fire after stop() returns.
-            for (const t of pendingDebounces.values())
-                clearTimeout(t);
-            pendingDebounces.clear();
+            clearPendingDebounces();
             if (opts?.signal?.aborted) {
+                stopped = true;
+                stopping = false;
                 return;
             }
-            // Drain any pending work so callers can rely on "stopped means quiesced".
-            await runReconcile(opts);
+            // Drain pending watcher work when the watcher state is trusted; otherwise
+            // keep the historical full-reconcile safety net.
+            if (watchersHealthy()) {
+                await flushPendingPaths(opts);
+            }
+            else {
+                await runReconcile(opts);
+            }
+            stopped = true;
+            stopping = false;
         },
+        flushPending,
         reconcile: runReconcile,
+        getDirtyPaths: () => new Set(dirtyMountPaths).values(),
+        watchersHealthy,
         totalChanges: () => totalChanges,
         ready: async () => {
             await watchersReady;

package/dist/launch.js

@@ -11,20 +11,40 @@ export async function launchOnMount(opts) {
     let syncedCount = 0;
     let finalized = false;
     let autoSync;
+    let autoSyncReadyBeforeWrites = false;
     const finalize = async () => {
         if (finalized)
             return;
         finalized = true;
         try {
             let autoSyncChanges = 0;
+            let finalSyncBackPaths;
             if (autoSync) {
                 await autoSync.stop({ signal: opts.shutdownSignal });
                 autoSyncChanges = autoSync.totalChanges();
+                if (autoSyncReadyBeforeWrites && autoSync.watchersHealthy()) {
+                    const dirty = Array.from(autoSync.getDirtyPaths());
+                    // Only take the fast path when there's at least one dirty
+                    // path to sync. An empty dirty set is ambiguous after
+                    // autoSync.stop() — the healthy-path flush already drained
+                    // pending events, so the set could be empty either because
+                    // nothing changed or because edits raced past the watcher
+                    // (short-lived runs where the watcher hadn't enqueued
+                    // anything before stop). Fall through to the full walk in
+                    // that case as a safety net; it's cheap on no-change runs
+                    // and prevents dropped mount edits at shutdown.
+                    if (dirty.length > 0) {
+                        finalSyncBackPaths = dirty;
+                    }
+                }
                 autoSync = undefined;
             }
             if (!handle)
                 return;
-            const finalSynced = await handle.syncBack({ signal: opts.shutdownSignal });
+            const finalSynced = await handle.syncBack({
+                signal: opts.shutdownSignal,
+                ...(finalSyncBackPaths ? { paths: finalSyncBackPaths } : {}),
+            });
             syncedCount = autoSyncChanges + finalSynced;
             if (opts.onAfterSync) {
                 await opts.onAfterSync(syncedCount);
@@ -43,12 +63,21 @@ export async function launchOnMount(opts) {
             includeGit: opts.includeGit,
             includeDefaultExcludeDirs: opts.includeDefaultExcludeDirs,
         });
-        if (opts.onBeforeLaunch) {
-            await opts.onBeforeLaunch(handle.mountDir);
-        }
         if (opts.autoSync !== false) {
             const autoSyncOpts = typeof opts.autoSync === 'object' ? opts.autoSync : undefined;
             autoSync = handle.startAutoSync(autoSyncOpts);
+            try {
+                await autoSync.ready();
+                autoSyncReadyBeforeWrites = autoSync.watchersHealthy();
+            }
+            catch {
+                // Keep launching with degraded auto-sync; shutdown will use the full
+                // syncBack sweep because dirty-path state was never trustworthy.
+                autoSyncReadyBeforeWrites = false;
+            }
+        }
+        if (opts.onBeforeLaunch) {
+            await opts.onBeforeLaunch(handle.mountDir);
         }
         const envVars = {
             ...process.env,

package/dist/mount.d.ts

@@ -32,6 +32,7 @@ export interface MountHandle {
     mountDir: string;
     syncBack(opts?: {
         signal?: AbortSignal;
+        paths?: Iterable<string>;
     }): Promise<number>;
     /**
      * Start bidirectional auto-sync: watches both the mount and project trees

package/dist/mount.js

@@ -83,7 +83,9 @@ export async function createMount(projectDir, mountDir, options) {
             let synced = 0;
             const realProjectDir = realpathSync(resolvedProjectDir);
             const realMountDir = realpathSync(resolvedMountDir);
-            const files = listFiles(realMountDir);
+            const files = opts?.paths
+                ? syncBackPathsToFiles(realMountDir, opts.paths)
+                : listFiles(realMountDir);
             const signal = opts?.signal;
             for (const sourceFile of files) {
                 if (signal?.aborted) {
@@ -92,7 +94,14 @@ export async function createMount(projectDir, mountDir, options) {
                 const syncedForFile = syncMountedFileBack(sourceFile, realMountDir, realProjectDir, readonlyMatcher, ignoredMatcher, noSyncBackMatcher, (relPosix) => isExcludedPath(relPosix, excludeRules));
                 synced += syncedForFile;
                 if (signal && syncedForFile > 0 && !signal.aborted) {
-                    await new Promise((resolve) => setImmediate(resolve));
+                    // Intentionally uses setTimeout(resolve, 0) rather than the
+                    // setImmediate-based yieldToEventLoop helper below: aborts
+                    // mid-walk are scheduled via setTimeout (see mount.test.ts
+                    // "syncBack: returns a partial count when aborted mid-walk"),
+                    // and matching the same queue makes the abort observable
+                    // between file syncs. setImmediate runs after timer
+                    // callbacks in a single I/O cycle and races the abort.
+                    await new Promise((resolve) => setTimeout(resolve, 0));
                 }
             }
             return synced;
@@ -260,6 +269,27 @@ function listFiles(baseDir) {
     }
     return files;
 }
+function syncBackPathsToFiles(mountDir, relPaths) {
+    const files = [];
+    const seen = new Set();
+    for (const relPath of relPaths) {
+        const sourceFile = resolveSyncBackSource(mountDir, relPath);
+        if (!sourceFile || seen.has(sourceFile)) {
+            continue;
+        }
+        seen.add(sourceFile);
+        files.push(sourceFile);
+    }
+    return files;
+}
+function resolveSyncBackSource(mountDir, relPath) {
+    const normalized = normalizeRelativePosix(relPath);
+    if (!normalized || path.isAbsolute(normalized)) {
+        return null;
+    }
+    const candidate = path.resolve(mountDir, ...normalized.split('/').filter(Boolean));
+    return isPathWithinRoot(candidate, mountDir) ? candidate : null;
+}
 function normalizeRelativePosix(filePath) {
     return filePath.split(path.sep).join('/');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayfile/local-mount",
-  "version": "0.7.7",
+  "version": "0.7.9",
   "description": "Create a symlink/copy mount of a project directory with .agentignore/.agentreadonly semantics, then launch a CLI inside it and sync writable changes back on exit",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",