@firenet-designs/fnd-cli 2.2.0 → 2.3.1

package/README.md

@@ -20,7 +20,7 @@ $ npm install -g @firenet-designs/fnd-cli
 $ fnd COMMAND
 running command...
 $ fnd (--version)
-@firenet-designs/fnd-cli/2.2.0 linux-x64 node-v24.18.0
+@firenet-designs/fnd-cli/2.3.1 linux-x64 node-v24.18.0
 $ fnd --help [COMMAND]
 USAGE
   $ fnd COMMAND
@@ -62,7 +62,7 @@ EXAMPLES
   $ fnd backfill-project my-store "extra hints"
 ```
 
-_See code: [src/commands/backfill-project.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.2.0/src/commands/backfill-project.ts)_
+_See code: [src/commands/backfill-project.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.3.1/src/commands/backfill-project.ts)_
 
 ## `fnd create-app`
 
@@ -83,7 +83,7 @@ EXAMPLES
   $ fnd create-app
 ```
 
-_See code: [src/commands/create-app.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.2.0/src/commands/create-app.ts)_
+_See code: [src/commands/create-app.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.3.1/src/commands/create-app.ts)_
 
 ## `fnd create-project [SHOP]`
 
@@ -113,7 +113,7 @@ EXAMPLES
   $ fnd create-project my-store "Acme storefront, Klaviyo"
 ```
 
-_See code: [src/commands/create-project.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.2.0/src/commands/create-project.ts)_
+_See code: [src/commands/create-project.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.3.1/src/commands/create-project.ts)_
 
 ## `fnd help [COMMAND]`
 
@@ -165,67 +165,76 @@ EXAMPLES
   $ fnd token -s mystore -i <id> -c <secret> --write ./.mcp.json
 ```
 
-_See code: [src/commands/token.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.2.0/src/commands/token.ts)_
+_See code: [src/commands/token.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.3.1/src/commands/token.ts)_
 
 ## `fnd workspace`
 
-Open a remote workspace: mirror the current directory onto a remote Linux box via reverse SSHFS and drop into a shell there, cleaning everything up on exit.
+Open a remote workspace: two-way sync the current directory to a remote Linux box with Mutagen and drop into a shell there, tearing the sync down on exit.
 
 ```
 USAGE
-  $ fnd workspace --ssh <value> [--local-ssh-port <value>] [--mount-base <value>] [-p <value>]
+  $ fnd workspace --ssh <value> [--devtools <value>] [--remote-base <value>] [--source remote|local]
 
 FLAGS
-  -p, --port=<value>            reverse-tunnel port opened on the remote (random 20000-60000 if omitted)
-      --local-ssh-port=<value>  [default: 22] port your LOCAL SSH server listens on (the tunnel forwards back to this)
-      --mount-base=<value>      [default: /home/fnd] base dir on the remote; the mount lands at
-                                <base>/<local-user>/<dir-name>
-      --ssh=<value>             (required) remote to connect to, as user@host
+  --devtools=<value>     expose your LOCAL browser to Claude on the remote via the chrome-devtools MCP. Value is "port"
+                         (same port both ends) or "remote:local" (local = this machine, where the browser runs). Your
+                         browser must already be listening with --remote-debugging-port=<local>.
+  --remote-base=<value>  [default: /home/fnd] base dir on the remote; the workspace lands at
+                         <base>/<local-user>/<dir-name>
+  --source=<option>      which side wins on conflict: "remote" = this server (where the workspace shell runs), "local" =
+                         the machine you ran fnd workspace from. Omit to flag conflicts instead of auto-resolving them.
+                         <options: remote|local>
+  --ssh=<value>          (required) remote to connect to, as user@host
 
 DESCRIPTION
-  Open a remote workspace: mirror the current directory onto a remote Linux box via reverse SSHFS and drop into a shell
-  there, cleaning everything up on exit.
+  Open a remote workspace: two-way sync the current directory to a remote Linux box with Mutagen and drop into a shell
+  there, tearing the sync down on exit.
 
-  The remote reaches your machine through the ssh tunnel (-R), so your local SSH server is never exposed to the internet
-  or port-forwarded. For the back-connection the remote authenticates with its OWN SSH key, which is temporarily added
-  to your local authorized_keys and removed again on exit. Locally you need an SSH *server* running (sshd), not sshfs —
-  sshfs runs on the remote.
+  Both sides keep a real copy on local disk and only deltas cross the network, so the remote reads files at native
+  speed. Conflicting edits on both ends are flagged rather than silently overwritten; pass --source to auto-resolve them
+  in favour of one side. Mutagen connects the normal direction (this machine → remote over SSH) and auto-deploys its
+  agent to the remote, so no local SSH server, reverse tunnel, or authorized_keys trust is required. You need the
+  Mutagen CLI installed on THIS machine.
 
 EXAMPLES
   $ fnd workspace --ssh user@203.0.113.4
 
-  $ fnd workspace --ssh user@host --port 40222
+  $ fnd workspace --ssh user@host --source local
 
-  $ fnd workspace --ssh user@host --mount-base /home/fnd --local-ssh-port 2222
+  $ fnd workspace --ssh user@host --remote-base /home/fnd
+
+  $ fnd workspace --ssh user@host --devtools 9222
+
+  $ fnd workspace --ssh user@host --devtools 9333:9222
 ```
 
-_See code: [src/commands/workspace/index.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.2.0/src/commands/workspace/index.ts)_
+_See code: [src/commands/workspace/index.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.3.1/src/commands/workspace/index.ts)_
 
 ## `fnd workspace cleanup`
 
-Unmount a leftover reverse-SSHFS mount on the remote — use this if a workspace session dropped before it could clean up after itself.
+Tear down a leftover workspace — use this if a `workspace` session dropped before it could clean up after itself.
 
 ```
 USAGE
-  $ fnd workspace cleanup --ssh <value> [--mount <value>] [--mount-base <value>]
+  $ fnd workspace cleanup --ssh <value> [--remote-base <value>] [--remote-dir <value>]
 
 FLAGS
-  --mount=<value>       exact remote mount path to unmount (defaults to the current dir mapping)
-  --mount-base=<value>  [default: /home/fnd] base dir on the remote, used to derive the default mount path
-  --ssh=<value>         (required) remote to connect to, as user@host
+  --remote-base=<value>  [default: /home/fnd] base dir on the remote, used to derive the default remote directory path
+  --remote-dir=<value>   exact remote directory to target (defaults to the current dir mapping)
+  --ssh=<value>          (required) remote to connect to, as user@host
 
 DESCRIPTION
-  Unmount a leftover reverse-SSHFS mount on the remote — use this if a workspace session dropped before it could clean
-  up after itself.
+  Tear down a leftover workspace — use this if a `workspace` session dropped before it could clean up after itself.
 
-  Unmounts the remote mount and removes the matching entry from your local authorized_keys. With no --mount, it targets
-  the same path `workspace` would use for the current directory.
+  Terminates any Mutagen sync sessions this machine started for the directory and strips the matching chrome-devtools
+  MCP entry from the remote. With no --remote-dir, it targets the same path `workspace` would use for the current
+  directory. The synced files themselves are left in place.
 
 EXAMPLES
   $ fnd workspace cleanup --ssh user@host
 
-  $ fnd workspace cleanup --ssh user@host --mount /home/fnd/cole/fnd-cli
+  $ fnd workspace cleanup --ssh user@host --remote-dir /home/fnd/cole/fnd-cli
 ```
 
-_See code: [src/commands/workspace/cleanup.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.2.0/src/commands/workspace/cleanup.ts)_
+_See code: [src/commands/workspace/cleanup.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.3.1/src/commands/workspace/cleanup.ts)_
 <!-- commandsstop -->

package/dist/commands/workspace/cleanup.d.ts

@@ -3,8 +3,8 @@ export default class WorkspaceCleanup extends Command {
     static description: string;
     static examples: string[];
     static flags: {
-        mount: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
-        'mount-base': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'remote-base': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'remote-dir': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         ssh: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
     };
     run(): Promise<void>;

package/dist/commands/workspace/cleanup.js

@@ -1,19 +1,20 @@
 import { Command, Flags } from '@oclif/core';
 import chalk from 'chalk';
-import { buildContext, DEFAULT_MOUNT_BASE, hasSshClient, keyCommentForMount, parseSshTarget, removeAuthorizedKey, runRemoteCleanup, } from '../../lib/workspace.js';
+import { basename } from 'node:path';
+import { buildContext, buildMutagenTerminateSelectorArgs, DEFAULT_MOUNT_BASE, hasMutagen, hasSshClient, parseSshTarget, runMutagen, runRemoteCleanup, slugify, } from '../../lib/workspace.js';
 export default class WorkspaceCleanup extends Command {
-    static description = 'Unmount a leftover reverse-SSHFS mount on the remote — use this if a workspace session dropped before it could clean up after itself.\n\nUnmounts the remote mount and removes the matching entry from your local authorized_keys. With no --mount, it targets the same path `workspace` would use for the current directory.';
+    static description = 'Tear down a leftover workspace — use this if a `workspace` session dropped before it could clean up after itself.\n\nTerminates any Mutagen sync sessions this machine started for the directory and strips the matching chrome-devtools MCP entry from the remote. With no --remote-dir, it targets the same path `workspace` would use for the current directory. The synced files themselves are left in place.';
     static examples = [
         '<%= config.bin %> <%= command.id %> --ssh user@host',
-        '<%= config.bin %> <%= command.id %> --ssh user@host --mount /home/fnd/cole/fnd-cli',
+        '<%= config.bin %> <%= command.id %> --ssh user@host --remote-dir /home/fnd/cole/fnd-cli',
     ];
     static flags = {
-        mount: Flags.string({
-            description: 'exact remote mount path to unmount (defaults to the current dir mapping)',
-        }),
-        'mount-base': Flags.string({
+        'remote-base': Flags.string({
             default: DEFAULT_MOUNT_BASE,
-            description: 'base dir on the remote, used to derive the default mount path',
+            description: 'base dir on the remote, used to derive the default remote directory path',
+        }),
+        'remote-dir': Flags.string({
+            description: 'exact remote directory to target (defaults to the current dir mapping)',
         }),
         ssh: Flags.string({
             description: 'remote to connect to, as user@host',
@@ -26,21 +27,30 @@ export default class WorkspaceCleanup extends Command {
             this.error('No `ssh` client found on PATH. Install OpenSSH client and try again.', { code: '1' });
         }
         const target = parseSshTarget(flags.ssh);
-        const mount = flags.mount ?? buildContext({ cwd: process.cwd(), mountBase: flags['mount-base'] }).mount;
-        this.log(chalk.bold('Cleaning up remote mount'));
-        this.log(`  ${chalk.dim('remote:')} ${target.user}@${target.host}`);
-        this.log(`  ${chalk.dim('mount:')}  ${mount}`);
+        const target2 = `${target.user}@${target.host}`;
+        const remoteDir = flags['remote-dir'] ??
+            buildContext({ cwd: process.cwd(), remoteBase: flags['remote-base'] }).remoteDir;
+        const slug = slugify(basename(remoteDir));
+        this.log(chalk.bold('Cleaning up workspace'));
+        this.log(`  ${chalk.dim('remote:')}     ${target2}`);
+        this.log(`  ${chalk.dim('remote dir:')} ${remoteDir}`);
         this.log('');
-        const code = await runRemoteCleanup(`${target.user}@${target.host}`, mount);
-        // Revoke local trust for this workspace's key regardless of the remote result.
-        removeAuthorizedKey(keyCommentForMount(mount));
+        // Terminate any lingering sync sessions for this directory (a local Mutagen op).
+        if (hasMutagen()) {
+            this.log(chalk.dim('Terminating any leftover Mutagen sync sessions…'));
+            await runMutagen(buildMutagenTerminateSelectorArgs(slug)).catch(() => 1);
+        }
+        else {
+            this.log(chalk.yellow('Mutagen CLI not found on PATH — skipping sync termination.'));
+        }
+        // Strip any chrome-devtools MCP config this workspace left on the remote.
+        this.log(chalk.dim('Removing any leftover chrome-devtools MCP config on the remote…'));
+        const code = await runRemoteCleanup(target2, remoteDir);
         if (code === 0) {
-            this.log(chalk.green('✓ Done. Local authorized_keys entry removed.'));
+            this.log(chalk.green('✓ Done.'));
         }
         else {
-            this.error(`Cleanup ssh session exited with code ${code} (local authorized_keys entry still removed).`, {
-                code: '1',
-            });
+            this.error(`Remote cleanup ssh session exited with code ${code}.`, { code: '1' });
         }
     }
 }

package/dist/commands/workspace/index.d.ts

@@ -3,13 +3,13 @@ export default class Workspace extends Command {
     static description: string;
     static examples: string[];
     static flags: {
-        'local-ssh-port': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
-        'mount-base': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
-        port: import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        devtools: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'remote-base': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        source: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         ssh: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
-    /** Verify the local machine can actually host the tunnel before we connect. */
+    /** Verify this machine can drive the sync before we connect. */
     private preflight;
     private printPlan;
     /** Run the interactive ssh session, inheriting the TTY so the remote shell is fully interactive. */

package/dist/commands/workspace/index.js

@@ -1,26 +1,27 @@
 import { Command, Flags } from '@oclif/core';
 import chalk from 'chalk';
 import { spawn } from 'node:child_process';
-import { addAuthorizedKey, buildContext, buildRemoteScript, DEFAULT_LOCAL_SSH_PORT, DEFAULT_MOUNT_BASE, fetchRemotePublicKey, hasSshClient, isLocalSshdReachable, parseSshTarget, removeAuthorizedKey, runRemoteCleanup, sshServerInstructions, } from '../../lib/workspace.js';
+import { browserDebugInstructions, buildContext, buildMutagenCreateArgs, buildMutagenFlushArgs, buildMutagenTerminateArgs, buildRemoteScript, DEFAULT_MOUNT_BASE, hasMutagen, hasSshClient, isLocalDebugPortLive, mutagenInstallInstructions, parseDevtoolsPort, parseSshTarget, runMutagen, runRemoteCleanup, } from '../../lib/workspace.js';
 export default class Workspace extends Command {
-    static description = 'Open a remote workspace: mirror the current directory onto a remote Linux box via reverse SSHFS and drop into a shell there, cleaning everything up on exit.\n\nThe remote reaches your machine through the ssh tunnel (-R), so your local SSH server is never exposed to the internet or port-forwarded. For the back-connection the remote authenticates with its OWN SSH key, which is temporarily added to your local authorized_keys and removed again on exit. Locally you need an SSH *server* running (sshd), not sshfs — sshfs runs on the remote.';
+    static description = 'Open a remote workspace: two-way sync the current directory to a remote Linux box with Mutagen and drop into a shell there, tearing the sync down on exit.\n\nBoth sides keep a real copy on local disk and only deltas cross the network, so the remote reads files at native speed. Conflicting edits on both ends are flagged rather than silently overwritten; pass --source to auto-resolve them in favour of one side. Mutagen connects the normal direction (this machine → remote over SSH) and auto-deploys its agent to the remote, so no local SSH server, reverse tunnel, or authorized_keys trust is required. You need the Mutagen CLI installed on THIS machine.';
     static examples = [
         '<%= config.bin %> <%= command.id %> --ssh user@203.0.113.4',
-        '<%= config.bin %> <%= command.id %> --ssh user@host --port 40222',
-        '<%= config.bin %> <%= command.id %> --ssh user@host --mount-base /home/fnd --local-ssh-port 2222',
+        '<%= config.bin %> <%= command.id %> --ssh user@host --source local',
+        '<%= config.bin %> <%= command.id %> --ssh user@host --remote-base /home/fnd',
+        '<%= config.bin %> <%= command.id %> --ssh user@host --devtools 9222',
+        '<%= config.bin %> <%= command.id %> --ssh user@host --devtools 9333:9222',
     ];
     static flags = {
-        'local-ssh-port': Flags.integer({
-            default: DEFAULT_LOCAL_SSH_PORT,
-            description: 'port your LOCAL SSH server listens on (the tunnel forwards back to this)',
+        devtools: Flags.string({
+            description: 'expose your LOCAL browser to Claude on the remote via the chrome-devtools MCP. Value is "port" (same port both ends) or "remote:local" (local = this machine, where the browser runs). Your browser must already be listening with --remote-debugging-port=<local>.',
         }),
-        'mount-base': Flags.string({
+        'remote-base': Flags.string({
             default: DEFAULT_MOUNT_BASE,
-            description: 'base dir on the remote; the mount lands at <base>/<local-user>/<dir-name>',
+            description: 'base dir on the remote; the workspace lands at <base>/<local-user>/<dir-name>',
         }),
-        port: Flags.integer({
-            char: 'p',
-            description: 'reverse-tunnel port opened on the remote (random 20000-60000 if omitted)',
+        source: Flags.string({
+            description: 'which side wins on conflict: "remote" = this server (where the workspace shell runs), "local" = the machine you ran fnd workspace from. Omit to flag conflicts instead of auto-resolving them.',
+            options: ['remote', 'local'],
         }),
         ssh: Flags.string({
             description: 'remote to connect to, as user@host',
@@ -30,71 +31,103 @@ export default class Workspace extends Command {
     async run() {
         const { flags } = await this.parse(Workspace);
         const target = parseSshTarget(flags.ssh);
-        const ctx = buildContext({ cwd: process.cwd(), mountBase: flags['mount-base'], port: flags.port });
-        await this.preflight(flags['local-ssh-port']);
-        this.printPlan(ctx, `${target.user}@${target.host}`);
-        // Read the remote's own public key and trust it locally for the back-connection.
         const target2 = `${target.user}@${target.host}`;
-        this.log(chalk.dim('Fetching the remote SSH key and trusting it locally…'));
-        const remotePublicKey = fetchRemotePublicKey(target2);
-        addAuthorizedKey(remotePublicKey, ctx.keyComment);
+        const devtools = flags.devtools === undefined ? undefined : parseDevtoolsPort(flags.devtools);
+        const ctx = buildContext({
+            cwd: process.cwd(),
+            devtools,
+            remoteBase: flags['remote-base'],
+            source: flags.source,
+        });
+        await this.preflight(devtools);
+        this.printPlan(ctx, target2);
+        // Start the two-way sync. Mutagen auto-deploys its agent to the remote over SSH.
+        this.log(chalk.dim('Starting the Mutagen sync session…'));
+        const createCode = await runMutagen(buildMutagenCreateArgs(ctx, target2));
+        if (createCode !== 0) {
+            this.error(`mutagen sync create failed (exit ${createCode}). Check that the remote is reachable over SSH and try again.`, { code: '1' });
+        }
         let code;
         try {
+            // Block until the first full sync lands so the files exist before the shell opens.
+            this.log(chalk.dim('Performing the initial sync…'));
+            const flushCode = await runMutagen(buildMutagenFlushArgs(ctx.syncName));
+            if (flushCode !== 0) {
+                this.error(`Initial mutagen sync flush failed (exit ${flushCode}).`, { code: '1' });
+            }
             const script = buildRemoteScript(ctx);
-            code = await this.runSsh(target2, ctx.port, flags['local-ssh-port'], script);
+            code = await this.runSsh(target2, script, ctx.devtools);
         }
         finally {
-            // Tear down from the local side (the remote script has no trap). Best-effort:
-            // if the connection is truly gone, unmounting won't reach the remote either.
+            // Best-effort: flush the last edits back, then tear the session down.
             this.log('');
-            this.log(chalk.dim('Cleaning up the remote mount…'));
-            try {
-                await runRemoteCleanup(target2, ctx.mount);
-            }
-            catch (error) {
-                this.log(chalk.yellow(`Could not reach the remote to unmount (${error.message}). ` +
-                    `Run later:\n  fnd workspace cleanup --ssh ${target2} --mount ${ctx.mount}`));
+            this.log(chalk.dim('Flushing final changes and stopping the sync…'));
+            await runMutagen(buildMutagenFlushArgs(ctx.syncName)).catch(() => 1);
+            await runMutagen(buildMutagenTerminateArgs(ctx.syncName)).catch(() => 1);
+            // Only reach back to the remote if we put a devtools MCP config there to remove.
+            if (ctx.devtools) {
+                this.log(chalk.dim('Removing the remote chrome-devtools MCP config…'));
+                try {
+                    await runRemoteCleanup(target2, ctx.remoteDir);
+                }
+                catch (error) {
+                    this.log(chalk.yellow(`Could not reach the remote to remove the devtools config (${error.message}).`));
+                }
             }
-            // Always revoke local trust, even if the session crashed or was killed.
-            removeAuthorizedKey(ctx.keyComment);
         }
         this.log('');
         this.log(code === 0
-            ? chalk.green('✓ Workspace closed. Remote mount unmounted and local trust removed.')
+            ? chalk.green('✓ Workspace closed. Sync stopped; the remote copy is left in place.')
             : chalk.yellow(`Session ended with exit code ${code}. Cleanup attempted above.`));
     }
-    /** Verify the local machine can actually host the tunnel before we connect. */
-    async preflight(localSshPort) {
+    /** Verify this machine can drive the sync before we connect. */
+    async preflight(devtools) {
         if (!hasSshClient()) {
             this.error('No `ssh` client found on PATH. Install OpenSSH client and try again.', { code: '1' });
         }
-        const reachable = await isLocalSshdReachable(localSshPort);
-        if (!reachable) {
-            this.log(chalk.red(`✗ No local SSH server answering on 127.0.0.1:${localSshPort}.`));
-            this.log(chalk.yellow('The remote mounts your files by sshing back through the tunnel, so your machine must be running an SSH server.'));
+        if (!hasMutagen()) {
+            this.log(chalk.red('✗ Mutagen CLI not found on PATH.'));
+            this.log(chalk.yellow('`fnd workspace` uses Mutagen to two-way sync your files to the remote.'));
             this.log('');
-            this.log(sshServerInstructions());
-            this.log('');
-            this.log(chalk.dim('If your sshd listens on another port, pass --local-ssh-port <port>.'));
-            this.error('Local SSH server is required. Aborting before connecting.', { code: '1' });
+            this.log(mutagenInstallInstructions());
+            this.error('Mutagen is required on this machine. Aborting before connecting.', { code: '1' });
+        }
+        // With --devtools, confirm the local browser's debug port is live BEFORE we
+        // connect — otherwise the tunneled MCP would have nothing to reach.
+        if (devtools) {
+            const live = await isLocalDebugPortLive(devtools.local);
+            if (!live) {
+                this.log(chalk.red(`✗ No browser debug endpoint answering on 127.0.0.1:${devtools.local}.`));
+                this.log(chalk.yellow('The chrome-devtools MCP on the remote drives your LOCAL browser through the tunnel.'));
+                this.log('');
+                this.log(browserDebugInstructions(devtools.local));
+                this.error('Local browser remote-debugging port is required for --devtools. Aborting.', { code: '1' });
+            }
         }
     }
     printPlan(ctx, target) {
+        const sync = ctx.source === undefined
+            ? 'two-way, conflicts flagged (pass --source to auto-resolve)'
+            : `two-way, conflicts resolved in favour of ${ctx.source === 'remote' ? 'the remote (this server)' : 'local (the machine you called from)'}`;
         this.log(chalk.bold('Opening remote workspace'));
         this.log(`  ${chalk.dim('remote:')}      ${target}`);
-        this.log(`  ${chalk.dim('mirroring:')}   ${ctx.localCwd}`);
-        this.log(`  ${chalk.dim('mounted at:')}  ${ctx.mount}`);
-        this.log(`  ${chalk.dim('tunnel port:')} ${ctx.port}`);
+        this.log(`  ${chalk.dim('local dir:')}   ${ctx.localCwd}`);
+        this.log(`  ${chalk.dim('remote dir:')}  ${ctx.remoteDir}`);
+        this.log(`  ${chalk.dim('sync:')}        ${sync}`);
+        if (ctx.devtools) {
+            this.log(`  ${chalk.dim('devtools:')}     remote 127.0.0.1:${ctx.devtools.remote} → local browser 127.0.0.1:${ctx.devtools.local}`);
+        }
         this.log('');
     }
     /** Run the interactive ssh session, inheriting the TTY so the remote shell is fully interactive. */
-    runSsh(target, port, localSshPort, script) {
+    runSsh(target, script, devtools) {
         const args = [
             '-t', // allocate a remote PTY for the interactive shell session
-            '-o',
-            'ExitOnForwardFailure=yes', // fail loudly if the remote can't open the -R port
-            '-R',
-            `${port}:localhost:${localSshPort}`,
+            // Reverse tunnel for --devtools only: remote 127.0.0.1:<remote> → this
+            // machine's browser at 127.0.0.1:<local>, so the remote's MCP can reach it.
+            ...(devtools
+                ? ['-o', 'ExitOnForwardFailure=yes', '-R', `${devtools.remote}:localhost:${devtools.local}`]
+                : []),
             target,
             script,
         ];

package/dist/lib/workspace.d.ts

@@ -1,89 +1,134 @@
 /**
- * Reverse-SSHFS workspace helpers.
+ * Mutagen-backed workspace helpers.
  *
  * The topology this supports:
  *
- *   local machine (any OS)                 remote machine (always Linux)
+ *   local machine (any OS)    Internet     remote machine (always Linux)
  *   ┌─────────────────────┐                ┌──────────────────────────────┐
- *   │ fnd workspace        │  ssh -R  ───►  │ sshd                          │
- *   │ your cwd is served   │                │  └─ sshfs -p <port> back ──┐  │
- *   │ by the LOCAL sshd  ◄─┼── tunnel ──────┼─ localhost:<port> ─────────┘  │
- *   │ (port 22 by default) │                │  mounts your cwd at <mount>   │
+ *   │ fnd workspace       │                │ sshd                         │
+ *   │  └─ mutagen CLI ────┼── ssh ────────►│  └─ mutagen-agent            │
+ *   │     (orchestrator)  │  (two-way sync)│     real copy on local disk  │
+ *   │  your cwd (a real   │◄───────────────┼─ <base>/<user>/<dir>         │
+ *   │  copy on disk)      │   deltas only  │                              │
  *   └─────────────────────┘                └──────────────────────────────┘
  *
- * Because the remote reaches your machine THROUGH the ssh tunnel (`-R`), your
- * local SSH server never has to be exposed to the internet or port-forwarded.
+ * BOTH sides hold a real copy on local disk and Mutagen propagates only the
+ * deltas. The remote therefore reads files at native disk speed (no per-file
+ * network round-trips), so lint/build/test on the remote are not IO-bound on
+ * the tunnel.
  *
- * The back-connection authenticates with the REMOTE's own SSH key: we read the
- * remote's public key, add it to your local authorized_keys (tagged with a
- * marker comment), and remove exactly that line on cleanup. We never generate
- * key material and never delete the remote's key.
+ * Mutagen connects the normal direction (local → remote over SSH), so we need
+ * NO local SSH server, NO reverse tunnel, and NO authorized_keys trust dance.
+ * Mutagen auto-deploys its agent to the remote over that same SSH connection;
+ * nothing to install on the remote by hand.
  *
- * IMPORTANT: locally you need an SSH *server* (sshd) running — NOT sshfs. sshfs
- * runs on the remote, which is why we check for it there, not here.
+ * The one reverse tunnel that remains is optional and unrelated to files: with
+ * --devtools we open `ssh -R` so the remote's chrome-devtools MCP can reach the
+ * caller's LOCAL browser.
  */
 export interface SshTarget {
     host: string;
     user: string;
 }
+export interface DevtoolsPorts {
+    /** Remote-debugging port of the browser on the caller's LOCAL machine. */
+    local: number;
+    /** Port opened on the REMOTE (via `ssh -R`) that tunnels back to the local browser. */
+    remote: number;
+}
+/**
+ * Which side wins when the same path changed on both ends since the last sync.
+ * `remote` = this server (the box where the workspace shell runs); `local` = the
+ * machine `fnd workspace` was invoked from. Maps to Mutagen's alpha endpoint in
+ * two-way-resolved mode (alpha always wins conflicts). When left undefined the
+ * session uses two-way-safe mode, which flags conflicts instead of resolving them.
+ */
+export type SyncSource = 'local' | 'remote';
 export interface WorkspaceContext {
-    /** authorized_keys marker tying the trusted key to this workspace (derivable from the mount). */
-    keyComment: string;
-    /** Absolute path of the current dir on the LOCAL machine (what gets mirrored). */
+    /** Chrome DevTools MCP tunnel, when --devtools was passed; undefined otherwise. */
+    devtools?: DevtoolsPorts;
+    /** Absolute path of the current dir on the LOCAL machine (one side of the sync). */
     localCwd: string;
-    /** Basename of the local cwd — the leaf of the remote mount path. */
+    /** Basename of the local cwd — the leaf of the remote directory path. */
     localDirName: string;
-    /** Username on the LOCAL machine — used both for the mount path and to auth the sshfs back-connection. */
+    /** Username on the LOCAL machine — used to namespace the remote directory path. */
     localUser: string;
-    /** Where the mirror is mounted on the REMOTE, e.g. /home/fnd/<localUser>/<localDirName>. */
-    mount: string;
-    /** The reverse-tunnel port opened on the remote (`-R <port>:localhost:<localSshPort>`). */
-    port: number;
+    /** Where the mirror lives on the REMOTE, e.g. /home/fnd/<localUser>/<localDirName>. */
+    remoteDir: string;
+    /** Which endpoint wins conflicts (the Mutagen alpha in two-way-resolved); undefined flags conflicts instead. */
+    source?: SyncSource;
+    /** Unique Mutagen session name for this workspace. */
+    syncName: string;
 }
 export declare const DEFAULT_MOUNT_BASE = "/home/fnd";
-export declare const DEFAULT_LOCAL_SSH_PORT = 22;
 /** Parse a `user@host` string, throwing a friendly error otherwise. */
 export declare const parseSshTarget: (raw: string) => SshTarget;
-/** The authorized_keys marker comment for a given mount — used to add and later remove the key. */
-export declare const keyCommentForMount: (mount: string) => string;
+/**
+ * Turn an arbitrary directory name into a Mutagen-safe slug (lowercase, only
+ * letters/digits/hyphens). Used both in the session name and the `dir` label so
+ * cleanup can find sessions for a directory without knowing the random suffix.
+ */
+export declare const slugify: (value: string) => string;
+/** A unique Mutagen session name for a workspace on the given local directory. */
+export declare const buildSyncName: (dirName: string) => string;
+/**
+ * Parse the --devtools value. Accepts `port` (same port on both ends) or
+ * `remote:local`, where `local` is the caller's machine (where the browser runs)
+ * and `remote` is the port opened on the workspace host.
+ */
+export declare const parseDevtoolsPort: (raw: string) => DevtoolsPorts;
 /** Build the immutable facts for a workspace session from the local environment + flags. */
 export declare const buildContext: (opts: {
     cwd: string;
-    mountBase: string;
-    port?: number;
+    devtools?: DevtoolsPorts;
+    remoteBase: string;
+    source?: SyncSource;
 }) => WorkspaceContext;
 /** POSIX single-quote a string so it can be embedded safely in the remote shell script. */
 export declare const shQuote: (value: string) => string;
 /**
- * Read the remote's SSH public key so we can trust it locally for the back
- * connection. Ensures an ed25519 key exists on the remote (creating one only if
- * the remote has none) and prints it. Returns the single public-key line.
+ * The bash script the remote runs for the interactive session. Mutagen already
+ * keeps the directory in sync, so this just makes sure the directory exists,
+ * optionally wires up the chrome-devtools MCP, and drops into a login shell.
  */
-export declare const fetchRemotePublicKey: (target: string) => string;
-/** Path to the local user's authorized_keys (cross-platform via os.homedir()). */
-export declare const authorizedKeysPath: () => string;
-/**
- * Trust the remote's public key locally so it can ssh back in. The marker
- * comment is appended so cleanup can remove exactly this line later.
- */
-export declare const addAuthorizedKey: (publicKey: string, comment: string) => void;
-/** Remove any authorized_keys line carrying the given marker comment. */
-export declare const removeAuthorizedKey: (comment: string) => void;
+export declare const buildRemoteScript: (ctx: WorkspaceContext) => string;
+/** Run the remote-side teardown (strip this project's chrome-devtools MCP) over a fresh ssh connection. */
+export declare const runRemoteCleanup: (target: string, remoteDir: string) => Promise<number>;
 /**
- * The bash script the remote runs. It mounts the local cwd via reverse sshfs
- * (authenticating with its own default key) and drops into an interactive
- * shell. Teardown (unmount + rmdir) is driven from the LOCAL side in
- * a `finally` via runRemoteCleanup — no in-script trap, which proved brittle
- * inside the PTY session.
+ * The remote-side teardown script: strip this project's chrome-devtools MCP via
+ * the `claude` CLI. Runs from inside the workspace dir so local scope resolves to
+ * the right project. A no-op if there is nothing to undo. The synced files
+ * themselves are left in place — they are a real copy, not a mount.
  */
-export declare const buildRemoteScript: (ctx: WorkspaceContext) => string;
-/** Run the remote-side teardown (unmount + rmdir) over a fresh ssh connection. */
-export declare const runRemoteCleanup: (target: string, mount: string) => Promise<number>;
-/** The remote-side teardown script (unmount only — the key is the remote's own). */
-export declare const buildCleanupScript: (mount: string) => string;
+export declare const buildCleanupScript: (remoteDir: string) => string;
 /** True if an `ssh` client is on PATH (works on Windows, macOS, Linux). */
 export declare const hasSshClient: () => boolean;
-/** Resolve true if a local SSH server is accepting connections on 127.0.0.1:<port>. */
-export declare const isLocalSshdReachable: (port: number, timeoutMs?: number) => Promise<boolean>;
-/** Platform-specific instructions for turning on the local OpenSSH server. */
-export declare const sshServerInstructions: (platform?: NodeJS.Platform) => string;
+/** True if the Mutagen CLI is on PATH and runnable. */
+export declare const hasMutagen: () => boolean;
+/**
+ * Arguments for `mutagen sync create`. With no `source`, the session runs in
+ * two-way-safe mode, which halts and flags conflicts rather than picking a
+ * winner. When a `source` is given, it becomes the Mutagen alpha endpoint and
+ * the mode switches to two-way-resolved (alpha always wins conflicts), so
+ * `--source remote` puts the server first and `--source local` puts this
+ * machine first. Labels let `workspace cleanup` find and terminate orphans.
+ */
+export declare const buildMutagenCreateArgs: (ctx: WorkspaceContext, target: string) => string[];
+/** Arguments for `mutagen sync flush <name>` — block until one full sync completes. */
+export declare const buildMutagenFlushArgs: (name: string) => string[];
+/** Arguments for `mutagen sync terminate <name>` — stop this exact session. */
+export declare const buildMutagenTerminateArgs: (name: string) => string[];
+/** Arguments for terminating any orphaned workspace sessions for a given directory slug. */
+export declare const buildMutagenTerminateSelectorArgs: (dirSlug: string) => string[];
+/** Run a Mutagen CLI command, inheriting stdio so its progress reaches the user. */
+export declare const runMutagen: (args: string[]) => Promise<number>;
+/**
+ * Resolve true if a Chrome/Chromium remote-debugging endpoint answers on
+ * 127.0.0.1:<port> — GET /json/version returns HTTP 200. This is the caller's
+ * LOCAL browser, checked before we open the workspace.
+ */
+export declare const isLocalDebugPortLive: (port: number, timeoutMs?: number) => Promise<boolean>;
+/** Hint for launching a browser with remote debugging enabled on the given port. */
+export declare const browserDebugInstructions: (port: number) => string;
+/** Platform-specific instructions for installing the Mutagen CLI on the machine running `fnd workspace`. */
+export declare const mutagenInstallInstructions: (platform?: NodeJS.Platform) => string;

package/dist/lib/workspace.js

@@ -1,11 +1,8 @@
 import { spawn, spawnSync } from 'node:child_process';
 import { randomInt } from 'node:crypto';
-import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { connect } from 'node:net';
-import { homedir, userInfo } from 'node:os';
-import { basename, join } from 'node:path';
+import { userInfo } from 'node:os';
+import { basename } from 'node:path';
 export const DEFAULT_MOUNT_BASE = '/home/fnd';
-export const DEFAULT_LOCAL_SSH_PORT = 22;
 /** Parse a `user@host` string, throwing a friendly error otherwise. */
 export const parseSshTarget = (raw) => {
     const match = raw.trim().match(/^([^@\s]+)@([^@\s]+)$/);
@@ -13,202 +10,234 @@ export const parseSshTarget = (raw) => {
         throw new Error(`--ssh must be in the form user@host (got "${raw}")`);
     return { host: match[2], user: match[1] };
 };
-/** The authorized_keys marker comment for a given mount — used to add and later remove the key. */
-export const keyCommentForMount = (mount) => `fnd-workspace:${mount}`;
+/**
+ * Turn an arbitrary directory name into a Mutagen-safe slug (lowercase, only
+ * letters/digits/hyphens). Used both in the session name and the `dir` label so
+ * cleanup can find sessions for a directory without knowing the random suffix.
+ */
+export const slugify = (value) => value
+    .toLowerCase()
+    .replaceAll(/[^a-z0-9]+/g, '-')
+    .replaceAll(/^-+|-+$/g, '')
+    .slice(0, 40) || 'workspace';
+/** A unique Mutagen session name for a workspace on the given local directory. */
+export const buildSyncName = (dirName) => `fnd-ws-${slugify(dirName)}-${randomInt(0, 1_000_000).toString(36)}`;
+/**
+ * Parse the --devtools value. Accepts `port` (same port on both ends) or
+ * `remote:local`, where `local` is the caller's machine (where the browser runs)
+ * and `remote` is the port opened on the workspace host.
+ */
+export const parseDevtoolsPort = (raw) => {
+    const toPort = (value) => {
+        const n = Number(value);
+        if (!Number.isInteger(n) || n < 1 || n > 65_535) {
+            throw new Error(`--devtools port must be an integer 1-65535 (got "${value}")`);
+        }
+        return n;
+    };
+    const parts = raw.trim().split(':');
+    if (parts.length === 1) {
+        const p = toPort(parts[0]);
+        return { local: p, remote: p };
+    }
+    if (parts.length === 2) {
+        return { local: toPort(parts[1]), remote: toPort(parts[0]) };
+    }
+    throw new Error(`--devtools must be "port" or "remote:local" (got "${raw}")`);
+};
 /** Build the immutable facts for a workspace session from the local environment + flags. */
 export const buildContext = (opts) => {
     const localUser = userInfo().username;
     const localCwd = opts.cwd;
     const localDirName = basename(localCwd);
-    const base = opts.mountBase.replace(/\/+$/, '');
-    const mount = `${base}/${localUser}/${localDirName}`;
-    // Ephemeral-ish range, kept below 65535 and clear of most well-known ports.
-    const port = opts.port ?? randomInt(20_000, 60_000);
+    const base = opts.remoteBase.replace(/\/+$/, '');
+    const remoteDir = `${base}/${localUser}/${localDirName}`;
     return {
-        keyComment: keyCommentForMount(mount),
+        devtools: opts.devtools,
         localCwd,
         localDirName,
         localUser,
-        mount,
-        port,
+        remoteDir,
+        source: opts.source,
+        syncName: buildSyncName(localDirName),
     };
 };
 /** POSIX single-quote a string so it can be embedded safely in the remote shell script. */
 export const shQuote = (value) => `'${value.replaceAll("'", `'\\''`)}'`;
+/** MCP server name registered for the workspace's chrome-devtools tunnel. */
+const DEVTOOLS_MCP_NAME = 'chrome-devtools';
 /**
- * Read the remote's SSH public key so we can trust it locally for the back
- * connection. Ensures an ed25519 key exists on the remote (creating one only if
- * the remote has none) and prints it. Returns the single public-key line.
+ * Bash lines (run on the REMOTE, from inside the workspace dir) that register the
+ * chrome-devtools MCP with the `claude` CLI. Local scope keys off the current
+ * directory, so this only affects the workspace project — never a global server.
+ * A prior entry is cleared first so a re-connect after a crashed session is
+ * idempotent. Skips gracefully if the claude CLI is missing.
+ *
+ * The block runs inside a login shell (`$SHELL -lc`): the outer script arrives as
+ * a non-login ssh command whose PATH lacks the node/nvm/volta/Homebrew dirs that
+ * login profiles add, so a bare `command -v claude` misses an installed CLI. A
+ * login shell reproduces the same PATH the interactive session below gets.
  */
-export const fetchRemotePublicKey = (target) => {
-    const remoteScript = [
-        'set -e',
-        'KEY="$HOME/.ssh/id_ed25519"',
-        'mkdir -p "$HOME/.ssh" && chmod 700 "$HOME/.ssh"',
-        'if [ ! -f "$KEY.pub" ]; then ssh-keygen -t ed25519 -N "" -f "$KEY" -q; fi',
-        'cat "$KEY.pub"',
+const claudeDevtoolsAddScript = (remotePort, okMessage) => {
+    const body = [
+        'if command -v claude >/dev/null 2>&1; then',
+        `  claude mcp remove ${DEVTOOLS_MCP_NAME} >/dev/null 2>&1 || true`,
+        `  claude mcp add ${DEVTOOLS_MCP_NAME} -- npx -y chrome-devtools-mcp@latest --browserUrl http://127.0.0.1:${remotePort}`,
+        `  echo ${shQuote(okMessage)}`,
+        'else',
+        '  echo "WARNING: claude CLI not found on the remote; skipped chrome-devtools MCP config." >&2',
+        'fi',
     ].join('\n');
-    // stdout piped (we capture the key); stdin/stderr inherited so any password or
-    // passphrase prompt still reaches the user's terminal.
-    const result = spawnSync('ssh', [target, remoteScript], {
-        encoding: 'utf8',
-        stdio: ['inherit', 'pipe', 'inherit'],
-    });
-    if (result.error)
-        throw new Error(`Could not ssh to ${target}: ${result.error.message}`);
-    if (result.status !== 0)
-        throw new Error(`Could not read the remote's SSH key (ssh exited ${result.status}).`);
-    const key = (result.stdout ?? '').trim();
-    if (!key.startsWith('ssh-'))
-        throw new Error(`Unexpected remote key output: ${key.slice(0, 80)}`);
-    return key;
+    return [`"\${SHELL:-bash}" -lc ${shQuote(body)}`];
 };
-/** Path to the local user's authorized_keys (cross-platform via os.homedir()). */
-export const authorizedKeysPath = () => join(homedir(), '.ssh', 'authorized_keys');
 /**
- * Trust the remote's public key locally so it can ssh back in. The marker
- * comment is appended so cleanup can remove exactly this line later.
+ * Bash lines (run on the REMOTE, from inside the workspace dir) that remove the
+ * chrome-devtools MCP this workspace registered. Local scope keys off the current
+ * directory, so it targets only the workspace project. No-op if the entry or the
+ * claude CLI is absent. Runs under a login shell for the same PATH reason as
+ * `claudeDevtoolsAddScript`.
  */
-export const addAuthorizedKey = (publicKey, comment) => {
-    const sshDir = join(homedir(), '.ssh');
-    const file = authorizedKeysPath();
-    if (!existsSync(sshDir))
-        mkdirSync(sshDir, { mode: 0o700, recursive: true });
-    const line = `${publicKey.trim()} ${comment}`;
-    const existing = existsSync(file) ? readFileSync(file, 'utf8') : '';
-    const prefix = existing.length > 0 && !existing.endsWith('\n') ? '\n' : '';
-    appendFileSync(file, `${prefix}${line}\n`);
-    // sshd ignores authorized_keys with loose perms (POSIX); best-effort on Windows.
-    try {
-        chmodSync(file, 0o600);
-    }
-    catch {
-        /* Windows uses ACLs, not POSIX modes — nothing to do here. */
-    }
-};
-/** Remove any authorized_keys line carrying the given marker comment. */
-export const removeAuthorizedKey = (comment) => {
-    const file = authorizedKeysPath();
-    if (!existsSync(file))
-        return;
-    const kept = readFileSync(file, 'utf8')
-        .split('\n')
-        .filter((line) => line.length > 0 && !line.includes(comment));
-    writeFileSync(file, kept.length > 0 ? `${kept.join('\n')}\n` : '');
+const claudeDevtoolsRemoveScript = () => {
+    const body = ['if command -v claude >/dev/null 2>&1; then', `  claude mcp remove ${DEVTOOLS_MCP_NAME}`, 'fi'].join('\n');
+    return [`"\${SHELL:-bash}" -lc ${shQuote(body)}`];
 };
 /**
- * The bash script the remote runs. It mounts the local cwd via reverse sshfs
- * (authenticating with its own default key) and drops into an interactive
- * shell. Teardown (unmount + rmdir) is driven from the LOCAL side in
- * a `finally` via runRemoteCleanup — no in-script trap, which proved brittle
- * inside the PTY session.
+ * The bash script the remote runs for the interactive session. Mutagen already
+ * keeps the directory in sync, so this just makes sure the directory exists,
+ * optionally wires up the chrome-devtools MCP, and drops into a login shell.
  */
 export const buildRemoteScript = (ctx) => {
-    const mount = shQuote(ctx.mount);
-    // `user@localhost:/absolute/local/path` — quoted whole so spaces survive.
-    const remoteSource = shQuote(`${ctx.localUser}@localhost:${ctx.localCwd}`);
-    const sshfsOpts = [
-        // Connect to the -R tunnel's entrance on the REMOTE's loopback (ctx.port),
-        // which forwards back to the local sshd. NOT the local sshd port directly.
-        `port=${ctx.port}`,
-        'StrictHostKeyChecking=accept-new',
-        'ServerAliveInterval=15',
-        'ServerAliveCountMax=3',
-    ].join(',');
+    const dir = shQuote(ctx.remoteDir);
+    const devtoolsSetup = ctx.devtools
+        ? claudeDevtoolsAddScript(ctx.devtools.remote, `Configured chrome-devtools MCP for this workspace (browser via 127.0.0.1:${ctx.devtools.remote}).`)
+        : [];
     return [
         'set -u',
-        `MOUNT=${mount}`,
-        'AGENT_STARTED=0',
-        // Remote must have sshfs — it is always Linux, so give an apt hint.
-        'if ! command -v sshfs >/dev/null 2>&1; then',
-        '  echo "ERROR: sshfs is not installed on the remote. Install it, e.g.: sudo apt install sshfs" >&2',
-        '  exit 1',
-        'fi',
-        // sshfs daemonizes, so its ssh child can't reliably prompt for a key
-        // passphrase. Load the key into an ssh-agent ONCE (ssh-add prompts cleanly
-        // on this PTY); sshfs then authenticates through the agent, no re-prompts.
-        // eslint-disable-next-line no-template-curly-in-string -- shell parameter expansion, not a JS template
-        'if [ -n "${SSH_AUTH_SOCK:-}" ] && ssh-add -l >/dev/null 2>&1; then',
-        '  :', // an agent with keys is already available — reuse it
-        'else',
-        // eslint-disable-next-line no-template-curly-in-string -- shell parameter expansion, not a JS template
-        '  if [ -z "${SSH_AUTH_SOCK:-}" ]; then eval "$(ssh-agent -s)" >/dev/null && AGENT_STARTED=1; fi',
-        '  echo "Loading your SSH key into the agent (enter its passphrase once if prompted)..."',
-        '  ssh-add </dev/tty || echo "WARNING: ssh-add loaded no key; sshfs may fail to authenticate back to your machine." >&2',
-        'fi',
-        // Clear any stale mount left by a previous dropped session, then (re)create.
-        'fusermount -u "$MOUNT" 2>/dev/null || umount "$MOUNT" 2>/dev/null || true',
-        'mkdir -p "$MOUNT" || { echo "ERROR: could not create $MOUNT" >&2; exit 1; }',
-        'echo "Mounting your local directory over the reverse tunnel..."',
-        `sshfs -o ${sshfsOpts} ${remoteSource} "$MOUNT" || { echo "ERROR: sshfs mount failed" >&2; exit 1; }`,
-        // The mount authenticated at this point; if we started an agent just for
-        // that, kill it so the decrypted key doesn't sit in memory during the session.
-        // eslint-disable-next-line no-template-curly-in-string -- shell parameter expansion, not a JS template
-        '[ "$AGENT_STARTED" = 1 ] && kill "${SSH_AGENT_PID:-}" 2>/dev/null || true',
-        'cd "$MOUNT" || { echo "ERROR: could not enter $MOUNT" >&2; exit 1; }',
-        'echo "Workspace ready at $MOUNT — dropping into a shell (exit to clean up)."',
+        `DIR=${dir}`,
+        // Mutagen creates the sync root, but ensure it exists so `cd` never races it.
+        'mkdir -p "$DIR" || { echo "ERROR: could not create $DIR" >&2; exit 1; }',
+        'cd "$DIR" || { echo "ERROR: could not enter $DIR" >&2; exit 1; }',
+        // Register the MCP from inside $DIR: `claude mcp add` local scope keys off cwd.
+        ...devtoolsSetup,
+        'echo "Workspace ready at $DIR — files sync in the background (exit to stop syncing)."',
         // eslint-disable-next-line no-template-curly-in-string -- shell parameter expansion, not a JS template
         '"${SHELL:-bash}" -l',
     ].join('\n');
 };
-/** Run the remote-side teardown (unmount + rmdir) over a fresh ssh connection. */
-export const runRemoteCleanup = (target, mount) => new Promise((resolve, reject) => {
-    const child = spawn('ssh', [target, buildCleanupScript(mount)], { stdio: 'inherit' });
+/** Run the remote-side teardown (strip this project's chrome-devtools MCP) over a fresh ssh connection. */
+export const runRemoteCleanup = (target, remoteDir) => new Promise((resolve, reject) => {
+    const child = spawn('ssh', [target, buildCleanupScript(remoteDir)], { stdio: 'inherit' });
     child.once('error', reject);
     child.once('close', (code) => resolve(code ?? 0));
 });
-/** The remote-side teardown script (unmount only — the key is the remote's own). */
-export const buildCleanupScript = (mount) => {
-    const quotedMount = shQuote(mount);
-    return [
-        `MOUNT=${quotedMount}`,
-        'if fusermount -u "$MOUNT" 2>/dev/null || fusermount3 -u "$MOUNT" 2>/dev/null || umount "$MOUNT" 2>/dev/null; then',
-        '  echo "Unmounted $MOUNT"',
-        'else',
-        '  echo "Nothing mounted at $MOUNT (or already unmounted)"',
-        'fi',
-        'rmdir "$MOUNT" 2>/dev/null && echo "Removed empty $MOUNT" || true',
-    ].join('\n');
-};
+/**
+ * The remote-side teardown script: strip this project's chrome-devtools MCP via
+ * the `claude` CLI. Runs from inside the workspace dir so local scope resolves to
+ * the right project. A no-op if there is nothing to undo. The synced files
+ * themselves are left in place — they are a real copy, not a mount.
+ */
+export const buildCleanupScript = (remoteDir) => [
+    `DIR=${shQuote(remoteDir)}`,
+    'cd "$DIR" 2>/dev/null || { echo "Nothing to clean up: $DIR is gone." >&2; exit 0; }',
+    ...claudeDevtoolsRemoveScript(),
+].join('\n');
 /** True if an `ssh` client is on PATH (works on Windows, macOS, Linux). */
 export const hasSshClient = () => {
     const result = spawnSync('ssh', ['-V'], { stdio: 'ignore' });
     return !result.error;
 };
-/** Resolve true if a local SSH server is accepting connections on 127.0.0.1:<port>. */
-export const isLocalSshdReachable = (port, timeoutMs = 2000) => new Promise((resolve) => {
-    const socket = connect({ host: '127.0.0.1', port });
-    const done = (ok) => {
-        socket.destroy();
-        resolve(ok);
-    };
-    socket.setTimeout(timeoutMs);
-    socket.once('connect', () => done(true));
-    socket.once('timeout', () => done(false));
-    socket.once('error', () => done(false));
+/** True if the Mutagen CLI is on PATH and runnable. */
+export const hasMutagen = () => {
+    const result = spawnSync('mutagen', ['version'], { stdio: 'ignore' });
+    return !result.error && result.status === 0;
+};
+/**
+ * Arguments for `mutagen sync create`. With no `source`, the session runs in
+ * two-way-safe mode, which halts and flags conflicts rather than picking a
+ * winner. When a `source` is given, it becomes the Mutagen alpha endpoint and
+ * the mode switches to two-way-resolved (alpha always wins conflicts), so
+ * `--source remote` puts the server first and `--source local` puts this
+ * machine first. Labels let `workspace cleanup` find and terminate orphans.
+ */
+export const buildMutagenCreateArgs = (ctx, target) => {
+    const local = ctx.localCwd;
+    const remote = `${target}:${ctx.remoteDir}`;
+    // Alpha only matters as the conflict winner in resolved mode; in safe mode the
+    // order is cosmetic, so keep local-first for a stable, readable command.
+    const [alpha, beta] = ctx.source === 'remote' ? [remote, local] : [local, remote];
+    const syncMode = ctx.source === undefined ? 'two-way-safe' : 'two-way-resolved';
+    return [
+        'sync',
+        'create',
+        `--name=${ctx.syncName}`,
+        '--label=managed-by=fnd-workspace',
+        `--label=dir=${slugify(ctx.localDirName)}`,
+        `--sync-mode=${syncMode}`,
+        alpha,
+        beta,
+    ];
+};
+/** Arguments for `mutagen sync flush <name>` — block until one full sync completes. */
+export const buildMutagenFlushArgs = (name) => ['sync', 'flush', name];
+/** Arguments for `mutagen sync terminate <name>` — stop this exact session. */
+export const buildMutagenTerminateArgs = (name) => ['sync', 'terminate', name];
+/** Arguments for terminating any orphaned workspace sessions for a given directory slug. */
+export const buildMutagenTerminateSelectorArgs = (dirSlug) => [
+    'sync',
+    'terminate',
+    `--label-selector=managed-by=fnd-workspace,dir=${dirSlug}`,
+];
+/** Run a Mutagen CLI command, inheriting stdio so its progress reaches the user. */
+export const runMutagen = (args) => new Promise((resolve, reject) => {
+    const child = spawn('mutagen', args, { stdio: 'inherit' });
+    child.once('error', reject);
+    child.once('close', (code) => resolve(code ?? 0));
 });
-/** Platform-specific instructions for turning on the local OpenSSH server. */
-export const sshServerInstructions = (platform = process.platform) => {
+/**
+ * Resolve true if a Chrome/Chromium remote-debugging endpoint answers on
+ * 127.0.0.1:<port> — GET /json/version returns HTTP 200. This is the caller's
+ * LOCAL browser, checked before we open the workspace.
+ */
+export const isLocalDebugPortLive = async (port, timeoutMs = 2000) => {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetch(`http://127.0.0.1:${port}/json/version`, { signal: controller.signal });
+        return res.status === 200;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+};
+/** Hint for launching a browser with remote debugging enabled on the given port. */
+export const browserDebugInstructions = (port) => [
+    `Start your browser with remote debugging on port ${port}, e.g.:`,
+    `  Chrome/Chromium:  google-chrome --remote-debugging-port=${port}`,
+    `  macOS:            "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=${port}`,
+    `Then confirm it answers:  curl http://127.0.0.1:${port}/json/version`,
+].join('\n');
+/** Platform-specific instructions for installing the Mutagen CLI on the machine running `fnd workspace`. */
+export const mutagenInstallInstructions = (platform = process.platform) => {
     if (platform === 'win32') {
         return [
-            'Windows — enable the OpenSSH Server (run PowerShell as Administrator):',
-            '  Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0',
-            '  Start-Service sshd',
-            "  Set-Service -Name sshd -StartupType 'Automatic'",
-            '  New-NetFirewallRule -Name sshd -DisplayName "OpenSSH Server" -Enabled True -Direction Inbound -Protocol TCP -Action Allow -LocalPort 22',
+            'Windows — install the Mutagen CLI:',
+            '  scoop install mutagen',
+            '  # or: choco install mutagen',
+            '  # or download from https://github.com/mutagen-io/mutagen/releases and put mutagen.exe on PATH',
         ].join('\n');
     }
     if (platform === 'darwin') {
         return [
-            'macOS — turn on Remote Login (the built-in SSH server):',
-            '  sudo systemsetup -setremotelogin on',
-            '  # or: System Settings → General → Sharing → Remote Login',
+            'macOS — install the Mutagen CLI:',
+            '  brew install mutagen-io/mutagen/mutagen',
         ].join('\n');
     }
     return [
-        'Linux — install and start the OpenSSH server:',
-        '  Debian/Ubuntu:  sudo apt install openssh-server && sudo systemctl enable --now ssh',
-        '  Fedora/RHEL:    sudo dnf install openssh-server && sudo systemctl enable --now sshd',
-        '  Arch:           sudo pacman -S openssh && sudo systemctl enable --now sshd',
+        'Linux — install the Mutagen CLI:',
+        '  brew install mutagen-io/mutagen/mutagen',
+        '  # or download from https://github.com/mutagen-io/mutagen/releases and put mutagen on PATH',
     ].join('\n');
 };

package/oclif.manifest.json

@@ -186,23 +186,23 @@
     "workspace:cleanup": {
       "aliases": [],
       "args": {},
-      "description": "Unmount a leftover reverse-SSHFS mount on the remote — use this if a workspace session dropped before it could clean up after itself.\n\nUnmounts the remote mount and removes the matching entry from your local authorized_keys. With no --mount, it targets the same path `workspace` would use for the current directory.",
+      "description": "Tear down a leftover workspace — use this if a `workspace` session dropped before it could clean up after itself.\n\nTerminates any Mutagen sync sessions this machine started for the directory and strips the matching chrome-devtools MCP entry from the remote. With no --remote-dir, it targets the same path `workspace` would use for the current directory. The synced files themselves are left in place.",
       "examples": [
         "<%= config.bin %> <%= command.id %> --ssh user@host",
-        "<%= config.bin %> <%= command.id %> --ssh user@host --mount /home/fnd/cole/fnd-cli"
+        "<%= config.bin %> <%= command.id %> --ssh user@host --remote-dir /home/fnd/cole/fnd-cli"
       ],
       "flags": {
-        "mount": {
-          "description": "exact remote mount path to unmount (defaults to the current dir mapping)",
-          "name": "mount",
+        "remote-base": {
+          "description": "base dir on the remote, used to derive the default remote directory path",
+          "name": "remote-base",
+          "default": "/home/fnd",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
-        "mount-base": {
-          "description": "base dir on the remote, used to derive the default mount path",
-          "name": "mount-base",
-          "default": "/home/fnd",
+        "remote-dir": {
+          "description": "exact remote directory to target (defaults to the current dir mapping)",
+          "name": "remote-dir",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
@@ -235,35 +235,39 @@
     "workspace": {
       "aliases": [],
       "args": {},
-      "description": "Open a remote workspace: mirror the current directory onto a remote Linux box via reverse SSHFS and drop into a shell there, cleaning everything up on exit.\n\nThe remote reaches your machine through the ssh tunnel (-R), so your local SSH server is never exposed to the internet or port-forwarded. For the back-connection the remote authenticates with its OWN SSH key, which is temporarily added to your local authorized_keys and removed again on exit. Locally you need an SSH *server* running (sshd), not sshfs — sshfs runs on the remote.",
+      "description": "Open a remote workspace: two-way sync the current directory to a remote Linux box with Mutagen and drop into a shell there, tearing the sync down on exit.\n\nBoth sides keep a real copy on local disk and only deltas cross the network, so the remote reads files at native speed. Conflicting edits on both ends are flagged rather than silently overwritten; pass --source to auto-resolve them in favour of one side. Mutagen connects the normal direction (this machine → remote over SSH) and auto-deploys its agent to the remote, so no local SSH server, reverse tunnel, or authorized_keys trust is required. You need the Mutagen CLI installed on THIS machine.",
       "examples": [
         "<%= config.bin %> <%= command.id %> --ssh user@203.0.113.4",
-        "<%= config.bin %> <%= command.id %> --ssh user@host --port 40222",
-        "<%= config.bin %> <%= command.id %> --ssh user@host --mount-base /home/fnd --local-ssh-port 2222"
+        "<%= config.bin %> <%= command.id %> --ssh user@host --source local",
+        "<%= config.bin %> <%= command.id %> --ssh user@host --remote-base /home/fnd",
+        "<%= config.bin %> <%= command.id %> --ssh user@host --devtools 9222",
+        "<%= config.bin %> <%= command.id %> --ssh user@host --devtools 9333:9222"
       ],
       "flags": {
-        "local-ssh-port": {
-          "description": "port your LOCAL SSH server listens on (the tunnel forwards back to this)",
-          "name": "local-ssh-port",
-          "default": 22,
+        "devtools": {
+          "description": "expose your LOCAL browser to Claude on the remote via the chrome-devtools MCP. Value is \"port\" (same port both ends) or \"remote:local\" (local = this machine, where the browser runs). Your browser must already be listening with --remote-debugging-port=<local>.",
+          "name": "devtools",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
-        "mount-base": {
-          "description": "base dir on the remote; the mount lands at <base>/<local-user>/<dir-name>",
-          "name": "mount-base",
+        "remote-base": {
+          "description": "base dir on the remote; the workspace lands at <base>/<local-user>/<dir-name>",
+          "name": "remote-base",
           "default": "/home/fnd",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
-        "port": {
-          "char": "p",
-          "description": "reverse-tunnel port opened on the remote (random 20000-60000 if omitted)",
-          "name": "port",
+        "source": {
+          "description": "which side wins on conflict: \"remote\" = this server (where the workspace shell runs), \"local\" = the machine you ran fnd workspace from. Omit to flag conflicts instead of auto-resolving them.",
+          "name": "source",
           "hasDynamicHelp": false,
           "multiple": false,
+          "options": [
+            "remote",
+            "local"
+          ],
           "type": "option"
         },
         "ssh": {
@@ -292,5 +296,5 @@
       ]
     }
   },
-  "version": "2.2.0"
+  "version": "2.3.1"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@firenet-designs/fnd-cli",
   "description": "A new CLI generated with oclif",
-  "version": "2.2.0",
+  "version": "2.3.1",
   "author": "Cole Denslow",
   "contributors": [
     "Justin Schellenberg"
@@ -76,7 +76,7 @@
         "description": "Say hello to the world and others"
       },
       "workspace": {
-        "description": "Open a remote reverse-SSHFS workspace and run Claude on it"
+        "description": "Open a remote Mutagen workspace and run Claude on it"
       }
     }
   },
@@ -87,10 +87,12 @@
   "scripts": {
     "build": "shx rm -rf dist && tsc -b",
     "lint": "eslint",
+    "pack": "npm run prepack && npm run postpack",
     "postpack": "shx rm -f oclif.manifest.json",
     "posttest": "npm run lint",
     "prepack": "oclif manifest && oclif readme",
     "version": "oclif readme && git add README.md",
+    "prerelease": "npm run build && npm run prepack",
     "release": "npm run build && npm run prepack && npm publish --access public"
   },
   "types": "dist/index.d.ts"