Merge pull request #68 from AgentWorkforce/feat/local-mount-include-git

feat(local-mount): add includeGit option for one-way .git sync

Author: willwashburn

packages/local-mount/CHANGELOG.md

@@ -6,7 +6,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-_No unreleased changes._
+### Added
+- `MountOptions.includeGit` (also exposed on `launchOnMount`) opts the project's `.git` directory back into the mount with one-way project→mount sync. Git operations work inside the mount; mount-side `.git` mutations stay sandboxed and are discarded on cleanup. Fixes [#66](https://github.com/AgentWorkforce/relayfile/issues/66).
 
 ## [0.5.3] - 2026-04-24
 

packages/local-mount/README.md

@@ -29,7 +29,7 @@ Behavior:
 - Copies regular files into the mount
 - Applies ignore rules from `ignoredPatterns`
 - Marks read-only matches as mode `0o444`
-- Excludes `.git` and `node_modules` by default
+- Excludes `.git` and `node_modules` by default. Pass `includeGit: true` to opt the project's `.git` directory back in (see [Including `.git`](#including-git))
 - Writes `_MOUNT_README.md` and `.relayfile-local-mount` into the mount
 - Skips syncing `_MOUNT_README.md`, `.relayfile-local-mount`, ignored files, read-only files, and symlinks back to the source project
 
@@ -110,6 +110,28 @@ Conflict and delete rules:
 - readonly paths never flow mount→project; project-side edits still flow into the mount (the mount copy is re-chmodded `0o444`)
 - `_MOUNT_README.md`, `.relayfile-local-mount`, ignored paths, and excluded directories never cross
 
+## Including `.git`
+
+By default, the project's `.git` directory is excluded from the mount, which means git commands inside the mount fail with `fatal: not a git repository`. Pass `includeGit: true` (on `createMount` or `launchOnMount`) to copy `.git` into the mount with **one-way project→mount sync**:
+
+- `.git` is copied on mount creation, so `git status`, `git log`, `git diff`, `git commit`, etc. all work inside the mount.
+- Project-side changes under `.git/**` flow into the mount (e.g. if a teammate's tooling moves `HEAD` while the agent is running).
+- Mount-side changes under `.git/**` are **not** synced back to the project. Branches, commits, or refs the agent creates in the mount stay sandboxed and are discarded on cleanup.
+
+If the agent needs its commits to survive, push to a remote from inside the mount. Source files outside `.git` continue to follow the normal bidirectional sync rules.
+
+```ts
+launchOnMount({
+  cli: 'claude',
+  args: ['--print', 'Inspect the diff and propose a fix.'],
+  projectDir,
+  mountDir,
+  includeGit: true,
+});
+```
+
+Note that `.git` can be sizable (hundreds of MB on long-lived repos); the initial mount creation copies the whole tree.
+
 ## Dotfile semantics
 
 `@relayfile/local-mount` uses glob-style patterns, powered by [`ignore`](https://www.npmjs.com/package/ignore).

packages/local-mount/src/auto-sync.test.ts

@@ -320,6 +320,68 @@ describe('startAutoSync', () => {
     }
   });
 
+  it('includeGit: project-side .git edits flow into the mount', async () => {
+    write(path.join(projectDir, '.git/HEAD'), 'ref: refs/heads/main\n');
+
+    const handle = createMount(projectDir, mountDir, {
+      ignoredPatterns: [],
+      readonlyPatterns: [],
+      excludeDirs: [],
+      includeGit: true,
+    });
+
+    const auto = handle.startAutoSync({ debounceMs: 50, scanIntervalMs: 10_000 });
+    await auto.ready();
+    try {
+      writeFileSync(
+        path.join(projectDir, '.git/HEAD'),
+        'ref: refs/heads/feature\n',
+        'utf8'
+      );
+      await waitFor(() =>
+        readFileSync(path.join(handle.mountDir, '.git/HEAD'), 'utf8') ===
+          'ref: refs/heads/feature\n'
+      );
+    } finally {
+      await auto.stop();
+      handle.cleanup();
+    }
+  });
+
+  it('includeGit: mount-side .git edits do NOT flow back to the project', async () => {
+    write(path.join(projectDir, '.git/HEAD'), 'ref: refs/heads/main\n');
+
+    const handle = createMount(projectDir, mountDir, {
+      ignoredPatterns: [],
+      readonlyPatterns: [],
+      excludeDirs: [],
+      includeGit: true,
+    });
+
+    const auto = handle.startAutoSync({ debounceMs: 50, scanIntervalMs: 10_000 });
+    await auto.ready();
+    try {
+      writeFileSync(
+        path.join(handle.mountDir, '.git/HEAD'),
+        'ref: refs/heads/feature\n',
+        'utf8'
+      );
+      writeFileSync(path.join(handle.mountDir, '.git/COMMIT_EDITMSG'), 'wip\n', 'utf8');
+
+      // Give autosync time to notice and choose not to propagate.
+      await new Promise((r) => setTimeout(r, 300));
+      await auto.reconcile();
+
+      expect(readFileSync(path.join(projectDir, '.git/HEAD'), 'utf8')).toBe(
+        'ref: refs/heads/main\n'
+      );
+      expect(existsSync(path.join(projectDir, '.git/COMMIT_EDITMSG'))).toBe(false);
+    } finally {
+      await auto.stop();
+      handle.cleanup();
+    }
+  });
+
   it('does not sync the _MOUNT_README.md or marker files', async () => {
     const handle = createMount(projectDir, mountDir, {
       ignoredPatterns: [],

packages/local-mount/src/auto-sync.ts

@@ -26,6 +26,13 @@ export interface AutoSyncContext {
    */
   isIgnored: (relPosix: string, isDirectory?: boolean) => boolean;
   isReadonly: (relPosix: string) => boolean;
+  /**
+   * One-way project→mount paths. Project-side changes flow into the mount,
+   * but mount-side changes never flow back. Unlike readonly, the mount copy
+   * is left writable so tools (e.g. git) can mutate it locally; those
+   * mutations are simply discarded on cleanup.
+   */
+  isNoSyncBack: (relPosix: string) => boolean;
   isReservedFile: (relPosix: string) => boolean;
 }
 
@@ -323,11 +330,16 @@ function reconcile(
  * Resolution rules ("mount wins"):
  * - If both sides changed since last sync → mount→project.
  * - Only mount changed → mount→project (unless mount-side change is disallowed
- *   for readonly files; then drop the mount change).
+ *   for readonly / noSyncBack files; then drop the mount change).
  * - Only project changed → project→mount.
  * - One side missing:
  *   • Other side changed since last sync → recreate the missing side.
  *   • Otherwise → propagate the delete.
+ *
+ * `readonly` and `noSyncBack` both forbid mount→project. The split exists so
+ * the chmod 0o444 only fires for true readonly entries (e.g. `.agentreadonly`
+ * matches), while noSyncBack entries (e.g. `.git/**` when `includeGit: true`)
+ * stay writable in the mount so tools can mutate them locally.
  */
 function syncOneFile(
   relPosix: string,
@@ -342,6 +354,7 @@ function syncOneFile(
 
   const prev = state.get(relPosix);
   const readonly = ctx.isReadonly(relPosix);
+  const noSyncBack = readonly || ctx.isNoSyncBack(relPosix);
 
   if (!mountStat && !projectStat) {
     state.delete(relPosix);
@@ -359,15 +372,15 @@ function syncOneFile(
         return false;
       }
       // Differ with no history: arbitrary tiebreak → mount wins.
-      if (readonly) {
-        // Readonly can't accept mount-side writes; fall back to project→mount.
+      if (noSyncBack) {
+        // Mount-side writes never flow back; fall back to project→mount.
         return doProjectToMount(relPosix, state, ctx, projectAbs, mountAbs, readonly);
       }
       return doMountToProject(relPosix, state, ctx, mountAbs, projectAbs);
     }
     if (mountStat && !projectStat) {
-      if (readonly) {
-        // New file in mount with a readonly pattern → cannot sync back.
+      if (noSyncBack) {
+        // New file in mount with a no-sync-back pattern → cannot sync back.
         return false;
       }
       return doMountToProject(relPosix, state, ctx, mountAbs, projectAbs);
@@ -389,7 +402,7 @@ function syncOneFile(
 
   if (mountStat && projectStat) {
     if (!mountChanged && !projectChanged) return false;
-    if (mountChanged && !readonly) {
+    if (mountChanged && !noSyncBack) {
       return doMountToProject(relPosix, state, ctx, mountAbs, projectAbs);
     }
     if (projectChanged) {
@@ -399,7 +412,7 @@ function syncOneFile(
   }
 
   if (mountStat && !projectStat) {
-    if (mountChanged && !readonly) {
+    if (mountChanged && !noSyncBack) {
       return doMountToProject(relPosix, state, ctx, mountAbs, projectAbs);
     }
     // Project deleted externally and mount hasn't been touched since → mirror.
@@ -411,8 +424,8 @@ function syncOneFile(
       return doProjectToMount(relPosix, state, ctx, projectAbs, mountAbs, readonly);
     }
     // Mount deleted and project hasn't been touched since → mirror to project.
-    if (readonly) {
-      // Readonly deletes in mount don't sync back; recreate mount from project.
+    if (noSyncBack) {
+      // No-sync-back deletes in mount don't propagate; recreate from project.
       return doProjectToMount(relPosix, state, ctx, projectAbs, mountAbs, readonly);
     }
     return doDeleteProject(relPosix, state, projectAbs);

packages/local-mount/src/launch.ts

@@ -17,6 +17,12 @@ export interface LaunchOnMountOptions {
   readonlyPatterns?: string[];
   /** Extra directory names to exclude from the mount on top of defaults. */
   excludeDirs?: string[];
+  /**
+   * Include the project's `.git` directory inside the mount with one-way
+   * project→mount sync. Defaults to false. See {@link MountOptions.includeGit}
+   * for details.
+   */
+  includeGit?: boolean;
   /** Extra env vars merged on top of `process.env`. */
   env?: NodeJS.ProcessEnv;
   /** Optional agent name, used in the _MOUNT_README.md "Agent:" line. */
@@ -66,6 +72,7 @@ export async function launchOnMount(opts: LaunchOnMountOptions): Promise<LaunchO
     readonlyPatterns: opts.readonlyPatterns ?? [],
     excludeDirs: opts.excludeDirs ?? [],
     agentName: opts.agentName,
+    includeGit: opts.includeGit,
   });
 
   let syncedCount = 0;

packages/local-mount/src/mount.test.ts

@@ -99,6 +99,59 @@ describe('createMount', () => {
     handle.cleanup();
   });
 
+  it('includeGit: copies .git into the mount and leaves it writable', () => {
+    write(path.join(projectDir, '.git/HEAD'), 'ref: refs/heads/main\n');
+    write(path.join(projectDir, '.git/refs/heads/main'), 'deadbeef\n');
+    write(path.join(projectDir, 'src/code.ts'), 'code');
+
+    const handle = createMount(projectDir, mountDir, {
+      ignoredPatterns: [],
+      readonlyPatterns: [],
+      excludeDirs: [],
+      includeGit: true,
+    });
+
+    expect(existsSync(path.join(handle.mountDir, '.git/HEAD'))).toBe(true);
+    expect(existsSync(path.join(handle.mountDir, '.git/refs/heads/main'))).toBe(true);
+
+    // Mount-side .git files must be writable so tools (git itself) can mutate
+    // them locally — the noSyncBack guard, not 0o444, is what keeps changes
+    // out of the project.
+    const headMode = statSync(path.join(handle.mountDir, '.git/HEAD')).mode & 0o777;
+    expect(headMode).not.toBe(0o444);
+
+    handle.cleanup();
+  });
+
+  it('includeGit: syncBack does not propagate .git mount edits to the project', async () => {
+    write(path.join(projectDir, '.git/HEAD'), 'ref: refs/heads/main\n');
+    write(path.join(projectDir, 'src/code.ts'), 'code');
+
+    const handle = createMount(projectDir, mountDir, {
+      ignoredPatterns: [],
+      readonlyPatterns: [],
+      excludeDirs: [],
+      includeGit: true,
+    });
+
+    // Simulate a git command in the mount mutating .git internals AND a normal
+    // source-file edit. Only the source edit should reach the project.
+    writeFileSync(path.join(handle.mountDir, '.git/HEAD'), 'ref: refs/heads/feature\n', 'utf8');
+    writeFileSync(path.join(handle.mountDir, '.git/COMMIT_EDITMSG'), 'wip\n', 'utf8');
+    writeFileSync(path.join(handle.mountDir, 'src/code.ts'), 'edited', 'utf8');
+
+    const synced = await handle.syncBack();
+
+    expect(synced).toBe(1);
+    expect(readFileSync(path.join(projectDir, '.git/HEAD'), 'utf8')).toBe(
+      'ref: refs/heads/main\n'
+    );
+    expect(existsSync(path.join(projectDir, '.git/COMMIT_EDITMSG'))).toBe(false);
+    expect(readFileSync(path.join(projectDir, 'src/code.ts'), 'utf8')).toBe('edited');
+
+    handle.cleanup();
+  });
+
   it('syncBack: writes back writable changes, skips readonly, skips _MOUNT_README.md, returns count', async () => {
     write(path.join(projectDir, 'writable.txt'), 'original');
     write(path.join(projectDir, 'readonly.txt'), 'original-ro');

packages/local-mount/src/mount.ts

@@ -30,6 +30,19 @@ export interface MountOptions {
    * If omitted, the doc uses a generic "agent" value.
    */
   agentName?: string;
+  /**
+   * Include the project's `.git` directory inside the mount with one-way
+   * project→mount sync. Default: false (`.git` is excluded entirely, matching
+   * historical behavior).
+   *
+   * When true:
+   * - `.git` is copied into the mount on creation, so git commands work inside.
+   * - Project-side changes under `.git/**` flow into the mount.
+   * - Mount-side changes under `.git/**` do NOT flow back to the project, so
+   *   commits/branches the agent creates inside the mount stay sandboxed and
+   *   are discarded with the mount on cleanup. Push to a remote to keep them.
+   */
+  includeGit?: boolean;
 }
 
 export interface MountHandle {
@@ -59,13 +72,23 @@ export function createMount(
   const resolvedMountDir = path.resolve(mountDir);
   const readonlyPatterns = [...options.readonlyPatterns];
   const ignoredPatterns = [...options.ignoredPatterns];
+  const includeGit = options.includeGit === true;
   const readonlyMatcher = createPathMatcher(readonlyPatterns);
   const ignoredMatcher = createPathMatcher(ignoredPatterns);
+  // `.git` is in DEFAULT_EXCLUDED_DIRS so the mount stays small and git
+  // operations don't accidentally cross-mutate the host repo. When the caller
+  // opts in via `includeGit`, drop it from the defaults and instead route it
+  // through the noSyncBack matcher below so it stays one-way.
+  const defaultExcludes = includeGit
+    ? DEFAULT_EXCLUDED_DIRS.filter((d) => d !== '.git')
+    : DEFAULT_EXCLUDED_DIRS;
   const excludeSet = new Set(
-    [...DEFAULT_EXCLUDED_DIRS, ...options.excludeDirs]
+    [...defaultExcludes, ...options.excludeDirs]
       .map((entry) => normalizeRelativePosix(entry).replace(/^\/+|\/+$/g, ''))
       .filter(Boolean)
   );
+  const noSyncBackPatterns = includeGit ? ['.git', '.git/**'] : [];
+  const noSyncBackMatcher = createPathMatcher(noSyncBackPatterns);
 
   // Guard against mountDir === projectDir. We compare both the realpath'd
   // project dir and the plain resolved project dir so callers that pass the
@@ -111,6 +134,7 @@ export function createMount(
     isExcluded: (relPosix) => isExcludedPath(relPosix, excludeSet),
     isIgnored: (relPosix, isDir) => isPathMatched(relPosix, ignoredMatcher, isDir),
     isReadonly: (relPosix) => isPathMatched(relPosix, readonlyMatcher),
+    isNoSyncBack: (relPosix) => isPathMatched(relPosix, noSyncBackMatcher),
     isReservedFile: (relPosix) =>
       relPosix === MOUNT_README_FILENAME || relPosix === MOUNT_MARKER_FILENAME,
   };
@@ -134,7 +158,8 @@ export function createMount(
           realMountDir,
           realProjectDir,
           readonlyMatcher,
-          ignoredMatcher
+          ignoredMatcher,
+          noSyncBackMatcher
         );
         synced += syncedForFile;
 
@@ -387,9 +412,16 @@ function syncMountedFileBack(
   mountDir: string,
   projectDir: string,
   readonlyMatcher: Ignore,
-  ignoredMatcher: Ignore
+  ignoredMatcher: Ignore,
+  noSyncBackMatcher: Ignore
 ): number {
-  const relative = resolveSyncRelativePath(sourceFile, mountDir, readonlyMatcher, ignoredMatcher);
+  const relative = resolveSyncRelativePath(
+    sourceFile,
+    mountDir,
+    readonlyMatcher,
+    ignoredMatcher,
+    noSyncBackMatcher
+  );
   if (!relative) return 0;
 
   const safeTargetPath = resolveVerifiedSyncTarget(projectDir, relative);
@@ -407,14 +439,19 @@ function resolveSyncRelativePath(
   sourceFile: string,
   mountDir: string,
   readonlyMatcher: Ignore,
-  ignoredMatcher: Ignore
+  ignoredMatcher: Ignore,
+  noSyncBackMatcher: Ignore
 ): string | null {
   const relative = path.relative(mountDir, sourceFile);
   if (relative === '' || relative.startsWith('..')) return null;
   const relativePosix = normalizeRelativePosix(relative);
   if (relativePosix === MOUNT_README_FILENAME) return null;
   if (relativePosix === MOUNT_MARKER_FILENAME) return null;
-  if (isPathMatched(relative, readonlyMatcher) || isPathMatched(relative, ignoredMatcher)) return null;
+  if (
+    isPathMatched(relative, readonlyMatcher) ||
+    isPathMatched(relative, ignoredMatcher) ||
+    isPathMatched(relative, noSyncBackMatcher)
+  ) return null;
 
   try {
     if (lstatSync(sourceFile).isSymbolicLink()) return null;