feat(remote): auto-manage mutagen for remote sync

Author: roodboi

docs/guides/remote-node-laptop-e2e.md

@@ -24,7 +24,7 @@ If you only need initial setup, use [Remote node quickstart](remote-node-quickst
 1. Both laptops have `hack` installed.
 2. Remote laptop is reachable via SSH from controller (`user@host`).
 3. Remote laptop has gateway enabled (`hack gateway setup`).
-4. `mutagen` is installed on controller (`mutagen version`).
+4. Controller can write to `~/.hack/bin` (Mutagen is auto-managed by `hack`).
 5. Optional but recommended: both laptops are on Tailscale.
 
 ## Build artifacts on controller
@@ -203,6 +203,9 @@ cat ~/.hack/registry/runs/<run-id>/summary.md
 8. `probe_failed (404): not_found` before workspace ensure
    - Cause: remote node is running an older daemon build that does not expose `/v1/node/git/probe`.
    - Fix: update `hack` on the remote node to the same build as controller, restart daemon, then retry.
+9. `Mutagen binary was not found on this machine`
+   - Cause: controller is missing mutagen and auto-install failed (permissions/network/tooling).
+   - Fix: run `hack doctor --fix` (or `hack global install`) and retry.
 
 ## Evidence capture
 

src/commands/doctor.ts

@@ -39,6 +39,10 @@ import {
   writeTextFileIfChanged,
 } from "../lib/fs.ts";
 import { resolveHackInvocation } from "../lib/hack-cli.ts";
+import {
+  ensureBundledMutagenInstalled,
+  getMutagenPath,
+} from "../lib/mutagen.ts";
 import { isMac } from "../lib/os.ts";
 import {
   findProjectContext,
@@ -139,6 +143,7 @@ const handleDoctor: CommandHandlerFor<typeof doctorSpec> = async ({
       checkTool({ name: "zellij (sessions)", cmd: "zellij", optional: true })
     )
   );
+  results.push(await runCheck(s, "mutagen", () => checkMutagenBinary()));
   results.push(
     await runCheck(s, "go", () =>
       checkTool({ name: "go (optional)", cmd: "go", optional: true })
@@ -488,6 +493,33 @@ function checkOptionalFzf(): CheckResult {
   return { name: "fzf (optional)", status: "ok", message: fzf };
 }
 
+async function checkMutagenBinary(): Promise<CheckResult> {
+  const mutagen = getMutagenPath();
+  if (!mutagen) {
+    return {
+      name: "mutagen",
+      status: "warn",
+      message: "Not found (run: hack doctor --fix)",
+    };
+  }
+
+  const version = await exec([mutagen, "version"], { stdin: "ignore" });
+  if (version.exitCode !== 0) {
+    return {
+      name: "mutagen",
+      status: "warn",
+      message: `${mutagen} (version probe failed)`,
+    };
+  }
+
+  const firstLine = version.stdout.trim().split("\n")[0]?.trim();
+  return {
+    name: "mutagen",
+    status: "ok",
+    message: firstLine && firstLine.length > 0 ? firstLine : mutagen,
+  };
+}
+
 async function checkDockerRunning(): Promise<CheckResult> {
   const res = await exec(["docker", "info"], { stdin: "ignore" });
   return {
@@ -1408,6 +1440,8 @@ async function runDoctorFix(): Promise<void> {
     return;
   }
 
+  await maybeInstallMutagenForDoctorFix();
+
   const dockerOk = await dockerInfoOk();
   if (!dockerOk) {
     note("Docker is not reachable; cannot apply fixes.", "doctor");
@@ -1440,6 +1474,34 @@ async function runDoctorFix(): Promise<void> {
   await maybeMigrateDnsmasq();
 }
 
+async function maybeInstallMutagenForDoctorFix(): Promise<void> {
+  if (getMutagenPath()) {
+    return;
+  }
+
+  const okMutagen = await confirmOrThrow({
+    message: "Install managed mutagen at ~/.hack/bin/mutagen?",
+    initialValue: true,
+  });
+  if (!okMutagen) {
+    return;
+  }
+
+  const installed = await ensureBundledMutagenInstalled();
+  if (installed.ok) {
+    note(
+      installed.installed
+        ? `Installed mutagen at ${installed.mutagenPath}`
+        : `Mutagen already installed at ${installed.mutagenPath}`,
+      "doctor"
+    );
+    return;
+  }
+
+  const detail = installed.message ? `: ${installed.message}` : "";
+  note(`Mutagen install failed (${installed.reason}${detail})`, "doctor");
+}
+
 async function confirmOrThrow(opts: {
   readonly message: string;
   readonly initialValue: boolean;

src/commands/global.ts

@@ -58,6 +58,10 @@ import {
 import { getString, isRecord } from "../lib/guards.ts";
 import { resolveHackInvocation } from "../lib/hack-cli.ts";
 import { parseJsonLines } from "../lib/json-lines.ts";
+import {
+  ensureBundledMutagenInstalled,
+  getMutagenPath,
+} from "../lib/mutagen.ts";
 import { isMac } from "../lib/os.ts";
 import { exec, execOrThrow, findExecutableInPath, run } from "../lib/shell.ts";
 import { resolveSessionsMuxMode } from "../mux/mux-config.ts";
@@ -487,6 +491,31 @@ async function globalInstall(): Promise<number> {
     }
   }
 
+  s.start("Ensuring mutagen…");
+  const mutagen = await ensureBundledMutagenInstalled();
+  if (mutagen.ok) {
+    s.stop(
+      mutagen.installed
+        ? "Installed managed mutagen"
+        : "mutagen already installed"
+    );
+  } else {
+    const systemMutagen = getMutagenPath();
+    s.stop(
+      systemMutagen ? "mutagen available on PATH" : "mutagen not installed"
+    );
+    if (!systemMutagen) {
+      const detail = mutagen.message ? `: ${mutagen.message}` : "";
+      logger.warn({
+        message: `mutagen install skipped (${mutagen.reason}${detail})`,
+      });
+      logger.warn({
+        message:
+          "Remote sync may fail without mutagen. Repair with: hack doctor --fix",
+      });
+    }
+  }
+
   if (isMac()) {
     await ensureMacChafa();
     await ensureMacMkcert();

src/commands/update.ts

@@ -6,6 +6,10 @@ import type { CommandHandlerFor } from "../cli/command.ts";
 import { defineCommand, defineOption, withHandler } from "../cli/command.ts";
 import { optJson } from "../cli/options.ts";
 import { ensureDir } from "../lib/fs.ts";
+import {
+  ensureBundledMutagenInstalled,
+  getMutagenPath,
+} from "../lib/mutagen.ts";
 import {
   compareVersions,
   downloadAndExtractRelease,
@@ -222,6 +226,8 @@ const handleUpdate: CommandHandlerFor<Spec> = async ({
     );
   }
 
+  const mutagenProvision = await ensureMutagenAfterUpdate();
+
   return writeResult({
     json: args.options.json === true,
     result: {
@@ -233,6 +239,7 @@ const handleUpdate: CommandHandlerFor<Spec> = async ({
       target,
       binaryPath: bin.path,
       assetsDir,
+      mutagen: mutagenProvision,
     },
     human: `Updated to v${latestVersion}.`,
   });
@@ -277,6 +284,43 @@ function resolveAssetsDir(): string {
   return resolve(".hack", "assets");
 }
 
+type MutagenProvisionResult = {
+  readonly available: boolean;
+  readonly installed: boolean;
+  readonly path: string | null;
+  readonly warning?: string;
+};
+
+async function ensureMutagenAfterUpdate(): Promise<MutagenProvisionResult> {
+  const existing = getMutagenPath();
+  if (existing) {
+    return {
+      available: true,
+      installed: false,
+      path: existing,
+    };
+  }
+
+  const installed = await ensureBundledMutagenInstalled();
+  if (installed.ok) {
+    return {
+      available: true,
+      installed: installed.installed,
+      path: installed.mutagenPath,
+    };
+  }
+
+  const fallback = getMutagenPath();
+  return {
+    available: Boolean(fallback),
+    installed: false,
+    path: fallback,
+    warning: installed.message
+      ? `${installed.reason}: ${installed.message}`
+      : installed.reason,
+  };
+}
+
 async function resolveSelfUpdateBinaryPath(): Promise<
   | { readonly ok: true; readonly path: string }
   | { readonly ok: false; readonly error: string }
@@ -382,6 +426,7 @@ type UpdateOutput =
       };
       readonly binaryPath: string;
       readonly assetsDir: string;
+      readonly mutagen?: MutagenProvisionResult;
     }
   | {
       readonly ok: false;