@relayfile/local-mount 0.10.22 → 0.10.23

package/dist/auto-sync.d.ts

@@ -30,6 +30,25 @@ export interface AutoSyncContext {
      */
     isNoSyncBack: (relPosix: string) => boolean;
     isReservedFile: (relPosix: string) => boolean;
+    /**
+     * True while the mount root still looks like a live mount (its marker
+     * file exists). Checked before any deletion is mirrored across trees: a
+     * mount directory that was torn down externally (crash cleanup, manual
+     * rm) must read as "the mount is gone", never as "the agent deleted
+     * every file" — without this, autosync would faithfully propagate the
+     * teardown as a mass delete of the user's project.
+     */
+    mountRootIntact: () => boolean;
+    /** Same guard for the project side: its disappearance must not empty the mount. */
+    projectRootIntact: () => boolean;
+    /**
+     * Sync state seeded by the mount population loop: one entry per copied
+     * file with both sides' mtimes recorded at copy time. When present,
+     * `startAutoSync` clones it instead of running the full-tree
+     * content-comparison priming pass — the copy already proved both sides
+     * identical, so re-reading every file pair only rediscovers that.
+     */
+    initialState?: ReadonlyMap<string, FileState>;
 }
 export interface AutoSyncOptions {
     /**
@@ -71,5 +90,18 @@ export interface AutoSyncHandle {
     totalChanges(): number;
     /** Resolves once both watchers have completed their initial scan. */
     ready(): Promise<void>;
+    /**
+     * Snapshot of the per-file sync state (both sides' last-synced mtimes),
+     * keyed by posix-relative path. Persist it alongside a kept mount and feed
+     * it to `attachMount` so the next session's first reconcile can
+     * distinguish deletions from creations. Run a full `reconcile()` first if
+     * the snapshot must cover paths only reconciles visit (e.g. `.git/**`
+     * under `includeGit`).
+     */
+    exportState(): Record<string, FileState>;
+}
+export interface FileState {
+    mountMtimeMs?: number;
+    projectMtimeMs?: number;
 }
 export declare function startAutoSync(ctx: AutoSyncContext, opts?: AutoSyncOptions): AutoSyncHandle;

package/dist/auto-sync.js

@@ -1,6 +1,7 @@
 import { chmodSync, constants as fsConstants, copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, } from 'node:fs';
 import path from 'node:path';
 import watcher from '@parcel/watcher';
+import { preserveMtime, statsImplySameContent } from './stat-compare.js';
 const STOP_EVENT_SETTLE_MS = 250;
 const DEFAULT_SCAN_INTERVAL_MS = 10_000;
 const DEFAULT_HEALTHY_SCAN_INTERVAL_MS = 60_000;
@@ -19,8 +20,13 @@ export function startAutoSync(ctx, opts = {}) {
     const healthyScanIntervalMs = normalizeScanInterval('healthyScanIntervalMs', opts.healthyScanIntervalMs, opts.scanIntervalMs === undefined ? DEFAULT_HEALTHY_SCAN_INTERVAL_MS : opts.scanIntervalMs);
     const debounceMs = opts.debounceMs ?? 50;
     const onError = opts.onError ?? (() => { });
-    const state = new Map();
-    primeState(state, ctx);
+    // Population-seeded state skips the priming walk entirely. Entries are
+    // cloned, not shared: the internal map mutates on every sync, and callers
+    // hold (or persist) their snapshot under a readonly contract.
+    const state = new Map(Array.from(ctx.initialState ?? [], ([rel, fileState]) => [rel, { ...fileState }]));
+    if (!ctx.initialState) {
+        primeState(state, ctx);
+    }
     let syncing = false;
     let pending = false;
     let stopping = false;
@@ -293,6 +299,7 @@ export function startAutoSync(ctx, opts = {}) {
         ready: async () => {
             await watchersReady;
         },
+        exportState: () => Object.fromEntries(Array.from(state, ([rel, fileState]) => [rel, { ...fileState }])),
     };
 }
 function buildIgnoreGlobs(ctx, watchRoot) {
@@ -478,7 +485,11 @@ function syncOneFile(relPosix, state, ctx) {
         if (mountChanged && !noSyncBack) {
             return doMountToProject(relPosix, state, ctx, mountAbs, projectAbs);
         }
-        // Project deleted externally and mount hasn't been touched since → mirror.
+        // Project deleted externally and mount hasn't been touched since →
+        // mirror — but only while the project root itself is still there. A
+        // vanished project tree is a teardown, not a per-file delete.
+        if (!ctx.projectRootIntact())
+            return false;
         return doDeleteMount(relPosix, state, mountAbs);
     }
     if (!mountStat && projectStat) {
@@ -490,6 +501,11 @@ function syncOneFile(relPosix, state, ctx) {
             // No-sync-back deletes in mount don't propagate; recreate from project.
             return doProjectToMount(relPosix, state, ctx, projectAbs, mountAbs, readonly);
         }
+        // Guard the catastrophic case: if the mount root itself is gone (torn
+        // down externally while this autosync was still alive), every mount
+        // file reads as "deleted" — propagating that would erase the project.
+        if (!ctx.mountRootIntact())
+            return false;
         return doDeleteProject(relPosix, state, projectAbs);
     }
     return false;
@@ -505,6 +521,9 @@ function doMountToProject(relPosix, state, ctx, mountAbs, projectAbs) {
         return false;
     }
     copyFileSync(mountAbs, target, fsConstants.COPYFILE_FICLONE);
+    const mountStat = safeFileStat(mountAbs);
+    if (mountStat)
+        preserveMtime(target, mountStat);
     updateState(state, relPosix, mountAbs, target);
     return true;
 }
@@ -527,6 +546,9 @@ function doProjectToMount(relPosix, state, ctx, projectAbs, mountAbs, readonly)
         catch { /* best effort */ }
     }
     copyFileSync(projectAbs, target, fsConstants.COPYFILE_FICLONE);
+    const sourceStat = safeFileStat(projectAbs);
+    if (sourceStat)
+        preserveMtime(target, sourceStat);
     if (readonly) {
         try {
             chmodSync(target, 0o444);
@@ -620,6 +642,22 @@ function isSymlinkTarget(target) {
     }
 }
 function sameContent(left, right) {
+    try {
+        const leftStat = statSync(left);
+        const rightStat = statSync(right);
+        if (leftStat.size !== rightStat.size)
+            return false;
+        // Copies preserve source mtimes, so equal size plus (near-)equal mtime
+        // means "same write" — skip re-reading both files.
+        if (statsImplySameContent(leftStat, rightStat))
+            return true;
+    }
+    catch {
+        return false;
+    }
+    return sameContentBytes(left, right);
+}
+function sameContentBytes(left, right) {
     try {
         const a = statSync(left);
         const b = statSync(right);

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { createMount, type MountOptions, type MountHandle, } from './mount.js';
-export { type AutoSyncOptions, type AutoSyncHandle, } from './auto-sync.js';
+export { createMount, attachMount, type MountOptions, type MountHandle, } from './mount.js';
+export { type AutoSyncOptions, type AutoSyncHandle, type FileState, } from './auto-sync.js';
 export { readAgentDotfiles, type ReadAgentDotfilesOptions, type AgentDotfilePatterns, } from './dotfiles.js';
 export { launchOnMount, type LaunchOnMountOptions, type LaunchOnMountResult, } from './launch.js';

package/dist/index.js

@@ -1,3 +1,3 @@
-export { createMount, } from './mount.js';
+export { createMount, attachMount, } from './mount.js';
 export { readAgentDotfiles, } from './dotfiles.js';
 export { launchOnMount, } from './launch.js';

package/dist/mount.d.ts

@@ -1,4 +1,4 @@
-import { type AutoSyncHandle, type AutoSyncOptions } from './auto-sync.js';
+import { type AutoSyncHandle, type AutoSyncOptions, type FileState } from './auto-sync.js';
 export interface MountOptions {
     ignoredPatterns: string[];
     readonlyPatterns: string[];
@@ -27,11 +27,37 @@ export interface MountOptions {
      * excluded unless `includeGit` is true, even when this is false.
      */
     includeDefaultExcludeDirs?: boolean;
+    /**
+     * How the initial mount population enumerates project files.
+     *
+     * - `'walk'` (default): recursive directory walk honoring the exclude and
+     *   ignore rules. Copies every non-excluded file it encounters, including
+     *   gitignored build outputs and caches the default excludes don't cover.
+     * - `'git'`: enumerate via `git ls-files --cached --others
+     *   --exclude-standard` — exactly the tracked plus untracked-unignored
+     *   set, so gitignored trees (nested caches, worktrees, build outputs at
+     *   any depth) never enter the mount. Exclude and ignore rules still apply
+     *   on top. Throws if the project is not a usable git checkout.
+     * - `'auto'`: `'git'` when the project has a `.git`, no `.gitmodules`, and
+     *   `git ls-files` succeeds; silently falls back to `'walk'` otherwise.
+     *
+     * With `includeGit: true`, git-list population copies `.git` as one
+     * timestamp-preserving bulk clone (copy-on-write where the filesystem
+     * supports it) instead of walking it file-by-file. When any ignored or
+     * readonly pattern targets `.git` itself, population falls back to
+     * `'walk'` so those patterns keep applying inside `.git`.
+     */
+    population?: 'walk' | 'git' | 'auto';
 }
 export interface MountHandle {
     mountDir: string;
     initialFileCount?: number;
     initialMountDurationMs?: number;
+    /**
+     * Which population strategy actually ran (after `'auto'` resolution), or
+     * `'reattach'` for handles from {@link attachMount}.
+     */
+    population: 'git' | 'walk' | 'reattach';
     syncBack(opts?: {
         signal?: AbortSignal;
         paths?: Iterable<string>;
@@ -46,3 +72,18 @@ export interface MountHandle {
     cleanup(): void;
 }
 export declare function createMount(projectDir: string, mountDir: string, options: MountOptions): Promise<MountHandle>;
+/**
+ * Reattach to a mount directory a previous `createMount` populated (and a
+ * previous session left behind) without wiping or re-copying anything.
+ *
+ * The caller owns correctness of the reuse: pass the same patterns the mount
+ * was created with, and pass `initialState` from a prior
+ * `AutoSyncHandle.exportState()` so the first reconcile can tell "unchanged
+ * since last session" from "changed on one side" — without it, files deleted
+ * from the project while the mount sat idle would be treated as new
+ * mount-side creations and resurrected. Refuses directories that don't carry
+ * the mount marker.
+ */
+export declare function attachMount(projectDir: string, mountDir: string, options: MountOptions & {
+    initialState?: Record<string, FileState>;
+}): Promise<MountHandle>;

package/dist/mount.js

@@ -1,7 +1,10 @@
-import { chmodSync, constants as fsConstants, copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { chmodSync, constants as fsConstants, copyFileSync, cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { spawnSync } from 'node:child_process';
 import ignore from 'ignore';
+import os from 'node:os';
 import path from 'node:path';
 import { startAutoSync, } from './auto-sync.js';
+import { preserveMtime, statsImplySameContent } from './stat-compare.js';
 const DEFAULT_ANY_DEPTH_EXCLUDES = [
     '.git',
     'node_modules',
@@ -15,6 +18,13 @@ const DEFAULT_ANY_DEPTH_EXCLUDES = [
     '.turbo',
     '.cache',
     '.DS_Store',
+    // Virtualenvs are never mount material and routinely nest below the root
+    // (e.g. packages/*/py/.venv). They also self-ignore via an internal
+    // `.gitignore` that root-level rules never see, so without an any-depth
+    // exclude the sync layers would happily mirror thousands of interpreter
+    // files.
+    '.venv',
+    'venv',
 ];
 const DEFAULT_ROOT_EXCLUDES = [
     'target',
@@ -22,8 +32,6 @@ const DEFAULT_ROOT_EXCLUDES = [
     'dist',
     'build',
     'out',
-    '.venv',
-    'venv',
     'env',
     'coverage',
 ];
@@ -37,7 +45,6 @@ export async function createMount(projectDir, mountDir, options) {
     const ignoredPatterns = [...options.ignoredPatterns];
     const includeGit = options.includeGit === true;
     const readonlyMatcher = createPathMatcher(readonlyPatterns);
-    const ignoredMatcher = createPathMatcher(ignoredPatterns);
     const includeDefaultExcludeDirs = options.includeDefaultExcludeDirs !== false;
     // `.git` is in the default any-depth excludes so the mount stays small and git
     // operations don't accidentally cross-mutate the host repo. When the caller
@@ -46,6 +53,20 @@ export async function createMount(projectDir, mountDir, options) {
     const excludeRules = createExcludeRules(options.excludeDirs, includeGit, includeDefaultExcludeDirs);
     const noSyncBackPatterns = includeGit ? ['.git', '.git/**'] : [];
     const noSyncBackMatcher = createPathMatcher(noSyncBackPatterns);
+    const requestedPopulation = options.population ?? 'walk';
+    const gitPopulation = requestedPopulation !== 'walk'
+        ? prepareGitPopulation(resolvedProjectDir, ignoredPatterns, readonlyPatterns, includeGit)
+        : null;
+    if (requestedPopulation === 'git' && gitPopulation === null) {
+        throw new Error(`population: 'git' requires a plain git checkout at ${resolvedProjectDir} ` +
+            "(no submodules, no pattern negations, no ignored/readonly patterns matching '.git')");
+    }
+    const population = gitPopulation === null ? 'walk' : 'git';
+    // Git-list population must keep the *sync* layers in agreement with what it
+    // mounted: gitignored files never enter the mount, so reconcile/syncBack
+    // must treat them as ignored too or the first full reconcile would copy
+    // every gitignored tree into the mount after all.
+    const isIgnored = buildIgnoredPredicate(createPathMatcher(ignoredPatterns), gitPopulation);
     // Guard against mountDir === projectDir. We compare both the realpath'd
     // project dir and the plain resolved project dir so callers that pass the
     // same argument for both are caught even when the path is a symlink (e.g.
@@ -61,41 +82,147 @@ export async function createMount(projectDir, mountDir, options) {
     const realMountDir = realpathSync(resolvedMountDir);
     writeFileSync(path.join(realMountDir, MOUNT_MARKER_FILENAME), MOUNT_MARKER_CONTENT, 'utf8');
     const initialMountStartedAt = Date.now();
-    const initialFileCount = await walkProjectTree(resolvedProjectDir, resolvedProjectDir, realMountDir, realMountDir, excludeRules, readonlyMatcher, ignoredMatcher);
+    // Sync state seeded during population: every copy records both sides'
+    // mtimes, so autosync can skip its full-tree content-comparison priming
+    // pass — the copy loop already proved the two sides identical.
+    const initialState = new Map();
+    let initialFileCount;
+    if (gitPopulation !== null) {
+        initialFileCount = await populateFromGitFileList(resolvedProjectDir, realMountDir, gitPopulation.files, excludeRules, readonlyMatcher, isIgnored, initialState);
+        if (includeGit) {
+            initialFileCount += cloneGitInto(resolvedProjectDir, realMountDir);
+            // The clone bypasses the per-file copy loop, so seed its state
+            // explicitly: without entries, project-side .git deletions (pack-refs,
+            // gc) would never propagate, and pre-autosync mount-side .git setup
+            // writes would be clobbered by the first reconcile's no-history path.
+            seedClonedGitState(resolvedProjectDir, realMountDir, initialState);
+        }
+    }
+    else {
+        initialFileCount = await walkProjectTree(resolvedProjectDir, resolvedProjectDir, realMountDir, realMountDir, excludeRules, readonlyMatcher, isIgnored, initialState);
+    }
     const initialMountDurationMs = Date.now() - initialMountStartedAt;
     const readmePath = resolveSafeCopyTarget(realMountDir, path.join(realMountDir, MOUNT_README_FILENAME));
     if (!readmePath) {
         throw new Error('Failed to create mount readme inside mountDir');
     }
     writeFileSync(readmePath, buildMountReadme(options.agentName, readonlyPatterns, ignoredPatterns), 'utf8');
+    return buildMountHandle({
+        resolvedProjectDir,
+        resolvedMountDir,
+        realMountDir,
+        excludeRules,
+        readonlyMatcher,
+        isIgnored,
+        noSyncBackMatcher,
+        initialState,
+        initialFileCount,
+        initialMountDurationMs,
+        population,
+    });
+}
+/**
+ * Reattach to a mount directory a previous `createMount` populated (and a
+ * previous session left behind) without wiping or re-copying anything.
+ *
+ * The caller owns correctness of the reuse: pass the same patterns the mount
+ * was created with, and pass `initialState` from a prior
+ * `AutoSyncHandle.exportState()` so the first reconcile can tell "unchanged
+ * since last session" from "changed on one side" — without it, files deleted
+ * from the project while the mount sat idle would be treated as new
+ * mount-side creations and resurrected. Refuses directories that don't carry
+ * the mount marker.
+ */
+export async function attachMount(projectDir, mountDir, options) {
+    const resolvedProjectDir = realpathSync(projectDir);
+    const resolvedMountDir = path.resolve(mountDir);
+    const readonlyPatterns = [...options.readonlyPatterns];
+    const ignoredPatterns = [...options.ignoredPatterns];
+    const includeGit = options.includeGit === true;
+    const readonlyMatcher = createPathMatcher(readonlyPatterns);
+    // A reattached mount must ignore exactly what its population did: when the
+    // caller requests git-mode semantics, re-derive the same gitignore-aware
+    // predicate (the guards re-run too, so a repo that has since grown
+    // submodules degrades to plain caller patterns — matching what a fresh
+    // createMount would do).
+    const gitPopulation = (options.population ?? 'walk') !== 'walk'
+        ? prepareGitPopulation(resolvedProjectDir, ignoredPatterns, readonlyPatterns, includeGit)
+        : null;
+    const isIgnored = buildIgnoredPredicate(createPathMatcher(ignoredPatterns), gitPopulation);
+    const includeDefaultExcludeDirs = options.includeDefaultExcludeDirs !== false;
+    const excludeRules = createExcludeRules(options.excludeDirs, includeGit, includeDefaultExcludeDirs);
+    const noSyncBackPatterns = includeGit ? ['.git', '.git/**'] : [];
+    const noSyncBackMatcher = createPathMatcher(noSyncBackPatterns);
+    if (resolvedMountDir === resolvedProjectDir ||
+        resolvedMountDir === path.resolve(projectDir)) {
+        throw new Error('mountDir must be different from projectDir');
+    }
+    if ((options.population ?? 'walk') === 'git' && gitPopulation === null) {
+        throw new Error(`population: 'git' requires a plain git checkout at ${resolvedProjectDir} ` +
+            "(no submodules, no pattern negations, no ignored/readonly patterns matching '.git')");
+    }
+    const markerPath = path.join(resolvedMountDir, MOUNT_MARKER_FILENAME);
+    if (!existsSync(markerPath)) {
+        throw new Error(`attachMount: ${resolvedMountDir} is missing the ${MOUNT_MARKER_FILENAME} marker; ` +
+            'only directories previously populated by createMount can be reattached.');
+    }
+    const realMountDir = realpathSync(resolvedMountDir);
+    // Same root/overlap validation as createMount: cleanup() recursively
+    // removes the mount dir, so a marked directory that overlaps the project
+    // must never be attachable. Unlike createMount, the mount dir exists here
+    // (marker just verified), so both sides compare as realpaths — otherwise
+    // symlinked temp roots (macOS /var → /private/var) would defeat the check.
+    assertMountDirSafeToRemove(realMountDir, resolvedProjectDir);
+    const initialState = new Map(Object.entries(options.initialState ?? {}));
+    return buildMountHandle({
+        resolvedProjectDir,
+        resolvedMountDir,
+        realMountDir,
+        excludeRules,
+        readonlyMatcher,
+        isIgnored,
+        noSyncBackMatcher,
+        initialState,
+        population: 'reattach',
+    });
+}
+function buildMountHandle(input) {
+    const { resolvedProjectDir, resolvedMountDir, realMountDir, excludeRules, readonlyMatcher, isIgnored, noSyncBackMatcher, initialState, } = input;
     const autoSyncContext = {
         realMountDir,
         realProjectDir: resolvedProjectDir,
         isExcluded: (relPosix) => isExcludedPath(relPosix, excludeRules),
         excludedAnyDepthNames: [...excludeRules.anyDepthNames],
         excludedRootPrefixes: [...excludeRules.rootPrefixes],
-        isIgnored: (relPosix, isDir) => isPathMatched(relPosix, ignoredMatcher, isDir),
+        isIgnored,
         isReadonly: (relPosix) => isPathMatched(relPosix, readonlyMatcher),
         isNoSyncBack: (relPosix) => isPathMatched(relPosix, noSyncBackMatcher),
         isReservedFile: (relPosix) => relPosix === MOUNT_README_FILENAME || relPosix === MOUNT_MARKER_FILENAME,
+        mountRootIntact: () => existsSync(path.join(realMountDir, MOUNT_MARKER_FILENAME)),
+        projectRootIntact: () => existsSync(resolvedProjectDir),
+        initialState,
     };
     return {
         mountDir: resolvedMountDir,
-        initialFileCount,
-        initialMountDurationMs,
+        initialFileCount: input.initialFileCount,
+        initialMountDurationMs: input.initialMountDurationMs,
+        population: input.population,
         async syncBack(opts) {
             let synced = 0;
             const realProjectDir = realpathSync(resolvedProjectDir);
             const realMountDir = realpathSync(resolvedMountDir);
+            // No-sync-back subtrees (`.git/**` under includeGit) can never produce
+            // a sync, so don't descend into them at all — `.git` alone is often
+            // thousands of entries.
             const files = opts?.paths
                 ? syncBackPathsToFiles(realMountDir, opts.paths)
-                : listFiles(realMountDir);
+                : listFiles(realMountDir, (relPosix) => isPathMatched(relPosix, noSyncBackMatcher, true));
             const signal = opts?.signal;
             for (const sourceFile of files) {
                 if (signal?.aborted) {
                     break;
                 }
-                const syncedForFile = syncMountedFileBack(sourceFile, realMountDir, realProjectDir, readonlyMatcher, ignoredMatcher, noSyncBackMatcher, (relPosix) => isExcludedPath(relPosix, excludeRules));
+                const syncedForFile = syncMountedFileBack(sourceFile, realMountDir, realProjectDir, readonlyMatcher, isIgnored, noSyncBackMatcher, (relPosix) => isExcludedPath(relPosix, excludeRules));
                 synced += syncedForFile;
                 if (signal && syncedForFile > 0 && !signal.aborted) {
                     // Intentionally uses setTimeout(resolve, 0) rather than the
@@ -160,7 +287,7 @@ function assertMountDirSafeToRemove(mountDir, projectDir) {
 // tick during init even on flat directories with thousands of entries. The
 // goal is not throughput; it is keeping the parent event loop unblocked.
 const WALK_YIELD_EVERY = 64;
-async function walkProjectTree(projectDir, currentDir, mountDir, currentMountDir, excludeRules, readonlyMatcher, ignoredMatcher) {
+async function walkProjectTree(projectDir, currentDir, mountDir, currentMountDir, excludeRules, readonlyMatcher, isIgnored, state) {
     await yieldToEventLoop();
     const entries = readdirSync(currentDir, { withFileTypes: true });
     let processed = 0;
@@ -181,7 +308,7 @@ async function walkProjectTree(projectDir, currentDir, mountDir, currentMountDir
         if (isExcludedPath(relativePath, excludeRules)) {
             continue;
         }
-        if (isPathMatched(relativePath, ignoredMatcher, entry.isDirectory())) {
+        if (isIgnored(relativePath, entry.isDirectory())) {
             continue;
         }
         const mountPath = path.join(currentMountDir, entry.name);
@@ -190,11 +317,11 @@ async function walkProjectTree(projectDir, currentDir, mountDir, currentMountDir
             if (!safeMountDir) {
                 continue;
             }
-            copiedFiles += await walkProjectTree(projectDir, absolutePath, mountDir, safeMountDir, excludeRules, readonlyMatcher, ignoredMatcher);
+            copiedFiles += await walkProjectTree(projectDir, absolutePath, mountDir, safeMountDir, excludeRules, readonlyMatcher, isIgnored, state);
             continue;
         }
         if (entry.isSymbolicLink()) {
-            if (copySymlinkedFile(projectDir, mountDir, absolutePath, mountPath, relativePath, readonlyMatcher)) {
+            if (copySymlinkedFile(projectDir, mountDir, absolutePath, mountPath, relativePath, readonlyMatcher, state)) {
                 copiedFiles += 1;
             }
             continue;
@@ -202,16 +329,319 @@ async function walkProjectTree(projectDir, currentDir, mountDir, currentMountDir
         if (!entry.isFile()) {
             continue;
         }
-        if (copyMountedFile(projectDir, mountDir, absolutePath, mountPath, relativePath, readonlyMatcher)) {
+        if (copyMountedFile(projectDir, mountDir, absolutePath, mountPath, relativePath, readonlyMatcher, state)) {
+            copiedFiles += 1;
+        }
+    }
+    return copiedFiles;
+}
+/**
+ * Populate the mount from a git-provided file list instead of a full tree
+ * walk. The list is exactly `git ls-files --cached --others
+ * --exclude-standard` output, so gitignored trees never even get visited;
+ * exclude and ignore rules are still applied per path so callers' patterns
+ * behave identically to walk mode.
+ */
+async function populateFromGitFileList(projectDir, mountDir, gitFiles, excludeRules, readonlyMatcher, isIgnored, state) {
+    // Sorted order keeps sibling files adjacent so the ensure-directory cache
+    // inside resolveSafeCopyTarget hits its realpath cache line after line.
+    const sorted = [...gitFiles].sort();
+    let processed = 0;
+    let copiedFiles = 0;
+    for (const raw of sorted) {
+        if (processed > 0 && processed % WALK_YIELD_EVERY === 0) {
+            await yieldToEventLoop();
+        }
+        processed += 1;
+        const relativePath = normalizeRelativePosix(raw);
+        if (!relativePath || relativePath.startsWith('..') || path.isAbsolute(raw)) {
+            continue;
+        }
+        if (isExcludedPath(relativePath, excludeRules)) {
+            continue;
+        }
+        if (isIgnored(relativePath, false)) {
+            continue;
+        }
+        const absolutePath = path.join(projectDir, ...relativePath.split('/'));
+        if (isPathWithinRoot(absolutePath, mountDir)) {
+            continue;
+        }
+        let entryStat;
+        try {
+            entryStat = lstatSync(absolutePath);
+        }
+        catch {
+            // Listed but deleted from the working tree (staged deletes) — skip.
+            continue;
+        }
+        const mountPath = path.join(mountDir, ...relativePath.split('/'));
+        if (entryStat.isSymbolicLink()) {
+            if (copySymlinkedFile(projectDir, mountDir, absolutePath, mountPath, relativePath, readonlyMatcher, state)) {
+                copiedFiles += 1;
+            }
+            continue;
+        }
+        // Non-files (submodule gitlinks appear as directories, sockets, fifos)
+        // are never mount candidates.
+        if (!entryStat.isFile()) {
+            continue;
+        }
+        if (copyMountedFile(projectDir, mountDir, absolutePath, mountPath, relativePath, readonlyMatcher, state)) {
             copiedFiles += 1;
         }
     }
     return copiedFiles;
 }
+/**
+ * The "is this path hidden from the mount and its sync?" decision.
+ *
+ * Walk mode: caller patterns only (historical behavior). Git mode: caller
+ * patterns first (they always win), then the repo's gitignore rules — except
+ * for tracked-but-gitignored files (and their ancestor directories, so walk
+ * pruning can't hide them), which git itself treats as ordinary content.
+ */
+function buildIgnoredPredicate(callerMatcher, gitPopulation) {
+    if (gitPopulation === null) {
+        return (relPosix, isDirectory) => isPathMatched(relPosix, callerMatcher, isDirectory);
+    }
+    const gitignoreMatcher = createPathMatcher(gitPopulation.gitignoreLines);
+    // Nested .gitignore files scope to their directory: rules match paths
+    // relative to the rule file's location, exactly as git applies them.
+    const nested = gitPopulation.nestedIgnores.map(({ prefix, lines }) => ({
+        prefix: prefix === '' ? '' : `${prefix}/`,
+        matcher: createPathMatcher(lines),
+    }));
+    const trackedIgnored = new Set(gitPopulation.trackedIgnoredFiles);
+    const trackedIgnoredDirs = new Set();
+    for (const file of gitPopulation.trackedIgnoredFiles) {
+        let dir = file;
+        while (dir.includes('/')) {
+            dir = dir.slice(0, dir.lastIndexOf('/'));
+            trackedIgnoredDirs.add(dir);
+        }
+    }
+    return (relPosix, isDirectory) => {
+        if (isPathMatched(relPosix, callerMatcher, isDirectory))
+            return true;
+        if (isDirectory ? trackedIgnoredDirs.has(relPosix) : trackedIgnored.has(relPosix)) {
+            return false;
+        }
+        if (isPathMatched(relPosix, gitignoreMatcher, isDirectory))
+            return true;
+        for (const { prefix, matcher } of nested) {
+            if (prefix !== '' && !relPosix.startsWith(prefix))
+                continue;
+            const scoped = prefix === '' ? relPosix : relPosix.slice(prefix.length);
+            if (scoped && isPathMatched(scoped, matcher, isDirectory))
+                return true;
+        }
+        return false;
+    };
+}
+function runGitLsFiles(projectDir, args) {
+    let result;
+    try {
+        result = spawnSync('git', ['-C', projectDir, 'ls-files', '-z', ...args], {
+            maxBuffer: 1024 * 1024 * 1024,
+        });
+    }
+    catch {
+        return null;
+    }
+    if (result.error || result.status !== 0)
+        return null;
+    return result.stdout.toString('utf8').split('\0').filter(Boolean);
+}
+function readIgnoreRuleLines(filePath) {
+    try {
+        return readFileSync(filePath, 'utf8').split('\n');
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Decide whether git-list population applies and gather its inputs.
+ * Returns null (→ walk fallback) when any precondition fails:
+ *
+ * - not a git checkout, or git itself fails;
+ * - `.gitmodules` present — submodule working trees are populated by the
+ *   walk but invisible to a plain `ls-files` call;
+ * - caller patterns contain negations (`!keep`) — those can re-include
+ *   gitignored paths, which a git-derived file list can never surface;
+ * - with `includeGit`, patterns that match the root `.git` tree — the bulk
+ *   `.git` clone doesn't consult matchers, only the walk does.
+ */
+function prepareGitPopulation(projectDir, ignoredPatterns, readonlyPatterns, includeGit) {
+    if (!existsSync(path.join(projectDir, '.git')))
+        return null;
+    if (existsSync(path.join(projectDir, '.gitmodules')))
+        return null;
+    const allPatterns = [...ignoredPatterns, ...readonlyPatterns];
+    if (allPatterns.some((p) => p.trim().startsWith('!')))
+        return null;
+    // Probe the actual matchers rather than inspecting pattern strings: this
+    // catches every syntax that can reach inside `.git` (globs included)
+    // without false-positiving on `.github` / `.gitignore`-style names.
+    if (includeGit && patternsMatchGitDir(allPatterns))
+        return null;
+    const trackedIgnored = runGitLsFiles(projectDir, ['--cached', '-i', '--exclude-standard']);
+    if (trackedIgnored === null)
+        return null;
+    const listed = runGitLsFiles(projectDir, ['--cached', '--others', '--exclude-standard']);
+    if (listed === null)
+        return null;
+    // Belt and braces: ls-files never emits `.git` paths, but the mount must
+    // not trust a spawned tool's output for that invariant.
+    const files = listed.filter((p) => p !== '.git' && !p.startsWith('.git/'));
+    // Nested .gitignore files scope their rules to their own directory; the
+    // listing honors them already, the sync predicate needs them explicitly.
+    const nestedIgnores = [];
+    for (const file of files) {
+        if (!file.endsWith('/.gitignore'))
+            continue;
+        const prefix = normalizeRelativePosix(file.slice(0, -'/.gitignore'.length));
+        const lines = readIgnoreRuleLines(path.join(projectDir, ...file.split('/')));
+        const hasRules = lines.some((l) => {
+            const t = l.trim();
+            return t !== '' && !t.startsWith('#');
+        });
+        if (hasRules && prefix !== '')
+            nestedIgnores.push({ prefix, lines });
+    }
+    return {
+        files,
+        gitignoreLines: [
+            ...readIgnoreRuleLines(path.join(projectDir, '.gitignore')),
+            ...readIgnoreRuleLines(path.join(projectDir, '.git', 'info', 'exclude')),
+            // The user's global excludes also shaped the listing; without them the
+            // sync layers would re-import globally-ignored files (.DS_Store etc.).
+            ...readGlobalGitExcludeLines(projectDir),
+        ],
+        nestedIgnores,
+        trackedIgnoredFiles: trackedIgnored.map((p) => normalizeRelativePosix(p)),
+    };
+}
+/**
+ * Would any caller pattern hide or freeze something under the root `.git`?
+ * Tested against representative `.git` paths through the real matcher so
+ * glob spellings are covered; `.github`-style names don't match.
+ */
+function patternsMatchGitDir(patterns) {
+    const matcher = createPathMatcher([...patterns]);
+    return (isPathMatched('.git', matcher, true) ||
+        matcher.ignores('.git/config') ||
+        matcher.ignores('.git/hooks/pre-commit'));
+}
+/**
+ * Record autosync state for every file the `.git` bulk clone produced. The
+ * clone preserved timestamps, so this is a stat-only sweep of both sides —
+ * no content reads. Files whose project counterpart vanished between clone
+ * and sweep are simply skipped and take the first-sight path later.
+ */
+function seedClonedGitState(projectDir, mountDir, state) {
+    const mountGit = path.join(mountDir, '.git');
+    if (!existsSync(mountGit))
+        return;
+    for (const mountAbs of listFiles(mountGit)) {
+        const rel = normalizeRelativePosix(path.relative(mountDir, mountAbs));
+        if (!rel || rel.startsWith('..'))
+            continue;
+        try {
+            const mountStat = lstatSync(mountAbs);
+            if (!mountStat.isFile())
+                continue;
+            const projectStat = lstatSync(path.join(projectDir, ...rel.split('/')));
+            if (!projectStat.isFile())
+                continue;
+            state.set(rel, {
+                mountMtimeMs: mountStat.mtimeMs,
+                projectMtimeMs: projectStat.mtimeMs,
+            });
+        }
+        catch {
+            /* skipped entries take autosync's first-sight path */
+        }
+    }
+}
+/** Lines from the user's global git excludes file (core.excludesFile or the XDG default). */
+function readGlobalGitExcludeLines(projectDir) {
+    let configured = null;
+    try {
+        const result = spawnSync('git', ['-C', projectDir, 'config', '--path', '--get', 'core.excludesfile'], { maxBuffer: 1024 * 1024 });
+        if (!result.error && result.status === 0) {
+            configured = result.stdout.toString('utf8').trim() || null;
+        }
+    }
+    catch {
+        /* fall through to the XDG default */
+    }
+    const candidate = configured !== null
+        ? // `--path` expands `~`; a bare relative value (a misconfiguration git
+            // itself resolves against its process cwd) resolves against the
+            // project dir here, matching the `git -C projectDir` listing calls.
+            path.resolve(projectDir, configured)
+        : path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'git', 'ignore');
+    return readIgnoreRuleLines(candidate);
+}
+/**
+ * Copy the project's `.git` into the mount as a single timestamp-preserving
+ * bulk clone (copy-on-write via FICLONE where the filesystem supports it).
+ * Returns the entry count contribution for `initialFileCount` (0 or 1 — the
+ * per-file count of the walk path isn't worth a second traversal here).
+ *
+ * A worktree-style `.git` *file* (gitdir pointer) is copied as-is, matching
+ * the walk path's behavior.
+ */
+function cloneGitInto(projectDir, mountDir) {
+    const source = path.join(projectDir, '.git');
+    let sourceStat;
+    try {
+        sourceStat = lstatSync(source);
+    }
+    catch {
+        return 0;
+    }
+    const target = path.join(mountDir, '.git');
+    try {
+        if (!sourceStat.isDirectory()) {
+            // A worktree-style `.git` *file* is a gitdir pointer into the host
+            // checkout's private worktree metadata. Copying it verbatim would let
+            // git commands inside the mount mutate the host's index/HEAD, so
+            // linked worktrees get no sandboxed `.git` at all under git
+            // population. (The legacy walk still copies the pointer; fixing that
+            // pre-existing behavior is out of scope here.)
+            return 0;
+        }
+        cpSync(source, target, {
+            recursive: true,
+            force: true,
+            preserveTimestamps: true,
+            mode: fsConstants.COPYFILE_FICLONE,
+            // Sockets and fifos (e.g. fsmonitor--daemon.ipc) can't be copied.
+            filter: (src) => {
+                try {
+                    const st = lstatSync(src);
+                    return st.isDirectory() || st.isFile() || st.isSymbolicLink();
+                }
+                catch {
+                    return false;
+                }
+            },
+        });
+        return 1;
+    }
+    catch {
+        // Best-effort: a partially cloned .git is still more useful than a
+        // failed mount. Git commands inside the mount surface any gaps.
+        return 0;
+    }
+}
 function yieldToEventLoop() {
     return new Promise((resolve) => setImmediate(resolve));
 }
-function copySymlinkedFile(projectDir, mountDir, sourcePath, mountPath, relativePath, readonlyMatcher) {
+function copySymlinkedFile(projectDir, mountDir, sourcePath, mountPath, relativePath, readonlyMatcher, state) {
     let realSource;
     let resolvedStat;
     try {
@@ -224,9 +654,15 @@ function copySymlinkedFile(projectDir, mountDir, sourcePath, mountPath, relative
     if (!isPathWithinRoot(realSource, projectDir) || !resolvedStat.isFile()) {
         return false;
     }
-    return copyMountedFile(projectDir, mountDir, realSource, mountPath, relativePath, readonlyMatcher, resolvedStat.mode);
+    return copyMountedFile(projectDir, mountDir, realSource, mountPath, relativePath, readonlyMatcher, 
+    // Auto-sync stats the project side with a symlink-rejecting lstat, so a
+    // seeded entry for a symlink's path would read as "project side gone,
+    // mount unchanged" on the first reconcile and delete the mount copy.
+    // Leave symlink copies unseeded — they take the historical
+    // first-sight path, whose symlink-target write guard keeps them alive.
+    null, resolvedStat.mode);
 }
-function copyMountedFile(sourceRoot, mountDir, sourcePath, mountPath, relativePath, readonlyMatcher, sourceMode) {
+function copyMountedFile(sourceRoot, mountDir, sourcePath, mountPath, relativePath, readonlyMatcher, state, sourceMode) {
     const safeMountPath = resolveSafeCopyTarget(mountDir, mountPath);
     if (!safeMountPath) {
         return false;
@@ -235,15 +671,38 @@ function copyMountedFile(sourceRoot, mountDir, sourcePath, mountPath, relativePa
     if (!safeSourcePath) {
         return false;
     }
+    const sourceStat = statSync(safeSourcePath);
     copyFileSync(safeSourcePath, safeMountPath, fsConstants.COPYFILE_FICLONE);
+    // Carry the source mtime onto the copy so both trees stat as "the same
+    // write" — reconcile and syncBack can then trust the stat quick check
+    // instead of re-reading file contents.
+    preserveMtime(safeMountPath, sourceStat);
+    if (state)
+        recordCopiedState(state, relativePath, safeMountPath, sourceStat);
     if (isPathMatched(relativePath, readonlyMatcher)) {
         chmodSync(safeMountPath, 0o444);
         return true;
     }
-    const mode = sourceMode ?? statSync(safeSourcePath).mode;
+    const mode = sourceMode ?? sourceStat.mode;
     chmodSync(safeMountPath, mode & 0o777);
     return true;
 }
+/**
+ * Seed the autosync state for a file the population loop just copied. The
+ * mount side is stat'd after the mtime carry-over so the recorded value is
+ * exactly what a later stat will report.
+ */
+function recordCopiedState(state, relativePath, mountPath, sourceStat) {
+    try {
+        state.set(normalizeRelativePosix(relativePath), {
+            mountMtimeMs: statSync(mountPath).mtimeMs,
+            projectMtimeMs: sourceStat.mtimeMs,
+        });
+    }
+    catch {
+        /* unseeded entries just take autosync's first-sight path */
+    }
+}
 function ensureDirectory(pathValue) {
     mkdirSync(pathValue, { recursive: true });
 }
@@ -260,7 +719,7 @@ function ensureDirectoryWithinRoot(rootPath, dirPath) {
         return null;
     }
 }
-function listFiles(baseDir) {
+function listFiles(baseDir, skipDir) {
     const files = [];
     const stack = [baseDir];
     while (stack.length > 0) {
@@ -271,6 +730,11 @@ function listFiles(baseDir) {
         for (const entry of entries) {
             const entryPath = path.join(current, entry.name);
             if (entry.isDirectory()) {
+                if (skipDir) {
+                    const relPosix = normalizeRelativePosix(path.relative(baseDir, entryPath));
+                    if (relPosix && skipDir(relPosix))
+                        continue;
+                }
                 stack.push(entryPath);
             }
             else if (entry.isFile() || entry.isSymbolicLink()) {
@@ -361,10 +825,12 @@ function hasSameContent(left, right) {
         if (leftStat.size !== rightStat.size) {
             return false;
         }
-        // Same size: fall back to a full byte comparison. Buffer.equals short-
-        // circuits internally but we still read both files; for very large files
-        // callers may want a streaming approach, though in practice mounts are
-        // dominated by source code where this is cheap.
+        // Population preserves source mtimes onto copies, so equal size plus
+        // (near-)equal mtime means "same write" without re-reading either side.
+        if (statsImplySameContent(leftStat, rightStat)) {
+            return true;
+        }
+        // Same size but diverged mtimes: fall back to a full byte comparison.
         const leftContent = readFileSync(left);
         const rightContent = readFileSync(right);
         return leftContent.equals(rightContent);
@@ -373,8 +839,8 @@ function hasSameContent(left, right) {
         return false;
     }
 }
-function syncMountedFileBack(sourceFile, mountDir, projectDir, readonlyMatcher, ignoredMatcher, noSyncBackMatcher, isExcluded) {
-    const relative = resolveSyncRelativePath(sourceFile, mountDir, readonlyMatcher, ignoredMatcher, noSyncBackMatcher, isExcluded);
+function syncMountedFileBack(sourceFile, mountDir, projectDir, readonlyMatcher, isIgnored, noSyncBackMatcher, isExcluded) {
+    const relative = resolveSyncRelativePath(sourceFile, mountDir, readonlyMatcher, isIgnored, noSyncBackMatcher, isExcluded);
     if (!relative)
         return 0;
     const safeTargetPath = resolveVerifiedSyncTarget(projectDir, relative);
@@ -384,9 +850,17 @@ function syncMountedFileBack(sourceFile, mountDir, projectDir, readonlyMatcher,
         return 0;
     }
     copyFileSync(sourceFile, safeTargetPath);
+    // Keep both sides stat-identical so a later pass (or a reused mount) can
+    // take the quick check instead of re-reading content.
+    try {
+        preserveMtime(safeTargetPath, statSync(sourceFile));
+    }
+    catch {
+        /* best effort */
+    }
     return 1;
 }
-function resolveSyncRelativePath(sourceFile, mountDir, readonlyMatcher, ignoredMatcher, noSyncBackMatcher, isExcluded) {
+function resolveSyncRelativePath(sourceFile, mountDir, readonlyMatcher, isIgnored, noSyncBackMatcher, isExcluded) {
     const relative = path.relative(mountDir, sourceFile);
     if (relative === '' || relative.startsWith('..'))
         return null;
@@ -397,7 +871,7 @@ function resolveSyncRelativePath(sourceFile, mountDir, readonlyMatcher, ignoredM
         return null;
     if (isExcluded(relativePosix) ||
         isPathMatched(relative, readonlyMatcher) ||
-        isPathMatched(relative, ignoredMatcher) ||
+        isIgnored(relativePosix) ||
         isPathMatched(relative, noSyncBackMatcher))
         return null;
     try {

package/dist/stat-compare.d.ts

@@ -0,0 +1,37 @@
+import type { Stats } from 'node:fs';
+/**
+ * Window inside which two mtimes are considered "the same write".
+ *
+ * Mount population preserves source mtimes onto copies via utimes, which
+ * round-trips through fractional-second floats with sub-microsecond error —
+ * and Node's own `cpSync({ preserveTimestamps: true })` truncates to whole
+ * milliseconds. 2ms absorbs both while staying far below the pace at which
+ * real writes to the same path land.
+ */
+export declare const MTIME_QUICK_EQUAL_TOLERANCE_MS = 2;
+/**
+ * Files written within this window are never quick-checked: a just-written
+ * file is exactly the case where a same-size rewrite could land inside the
+ * mtime tolerance and masquerade as unchanged. Stale mtimes (anything older
+ * than a few seconds) can only be within tolerance of each other because one
+ * side is a preserved-mtime copy of the other.
+ */
+export declare const RECENT_WRITE_GUARD_MS = 5000;
+/**
+ * rsync-style quick check: equal sizes plus (near-)equal mtimes imply equal
+ * content, letting sync paths skip a full byte comparison. Only meaningful
+ * for regular files whose copies were made with mtime preservation; callers
+ * fall back to byte comparison when this returns false.
+ *
+ * Guarded two ways: mtimes must agree within the tolerance (absorbing utimes
+ * float round-trips and `cpSync({ preserveTimestamps })` millisecond
+ * truncation), and neither side may have been written inside the recency
+ * window — fresh writes always take the byte-comparison path.
+ */
+export declare function statsImplySameContent(a: Stats, b: Stats): boolean;
+/**
+ * Carry a source file's mtime onto its copy so the two sides stat as "the
+ * same write" and the quick check applies. Best-effort: when it fails, the
+ * quick check simply degrades to a byte comparison.
+ */
+export declare function preserveMtime(targetPath: string, sourceStat: Stats): void;

package/dist/stat-compare.js

@@ -0,0 +1,51 @@
+import { utimesSync } from 'node:fs';
+/**
+ * Window inside which two mtimes are considered "the same write".
+ *
+ * Mount population preserves source mtimes onto copies via utimes, which
+ * round-trips through fractional-second floats with sub-microsecond error —
+ * and Node's own `cpSync({ preserveTimestamps: true })` truncates to whole
+ * milliseconds. 2ms absorbs both while staying far below the pace at which
+ * real writes to the same path land.
+ */
+export const MTIME_QUICK_EQUAL_TOLERANCE_MS = 2;
+/**
+ * Files written within this window are never quick-checked: a just-written
+ * file is exactly the case where a same-size rewrite could land inside the
+ * mtime tolerance and masquerade as unchanged. Stale mtimes (anything older
+ * than a few seconds) can only be within tolerance of each other because one
+ * side is a preserved-mtime copy of the other.
+ */
+export const RECENT_WRITE_GUARD_MS = 5_000;
+/**
+ * rsync-style quick check: equal sizes plus (near-)equal mtimes imply equal
+ * content, letting sync paths skip a full byte comparison. Only meaningful
+ * for regular files whose copies were made with mtime preservation; callers
+ * fall back to byte comparison when this returns false.
+ *
+ * Guarded two ways: mtimes must agree within the tolerance (absorbing utimes
+ * float round-trips and `cpSync({ preserveTimestamps })` millisecond
+ * truncation), and neither side may have been written inside the recency
+ * window — fresh writes always take the byte-comparison path.
+ */
+export function statsImplySameContent(a, b) {
+    if (a.size !== b.size)
+        return false;
+    if (Math.abs(a.mtimeMs - b.mtimeMs) > MTIME_QUICK_EQUAL_TOLERANCE_MS)
+        return false;
+    const newest = Math.max(a.mtimeMs, b.mtimeMs);
+    return Date.now() - newest > RECENT_WRITE_GUARD_MS;
+}
+/**
+ * Carry a source file's mtime onto its copy so the two sides stat as "the
+ * same write" and the quick check applies. Best-effort: when it fails, the
+ * quick check simply degrades to a byte comparison.
+ */
+export function preserveMtime(targetPath, sourceStat) {
+    try {
+        utimesSync(targetPath, sourceStat.atimeMs / 1000, sourceStat.mtimeMs / 1000);
+    }
+    catch {
+        /* quick check falls back to content comparison */
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayfile/local-mount",
-  "version": "0.10.22",
+  "version": "0.10.23",
   "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",