@puddle-code/cli 0.0.33 → 0.0.34

package/dist/index.js

@@ -3905,6 +3905,29 @@ var init_attach = __esm({
 
 // src/cli/args.ts
 init_types();
+var COMPONENTS = ["cli", "daemon", "desktop"];
+function parseComponentSpec(raw) {
+  const at = raw.indexOf("@");
+  const name = at === -1 ? raw : raw.slice(0, at);
+  const versionRaw = at === -1 ? void 0 : raw.slice(at + 1);
+  if (name !== "" && !COMPONENTS.includes(name)) return null;
+  if (name === "" && versionRaw === void 0) return null;
+  let version2;
+  if (versionRaw !== void 0) {
+    version2 = versionRaw.replace(/^v/, "");
+    if (!/^\d+\.\d+\.\d+$/.test(version2)) {
+      throw new CliError(
+        "bad_arguments",
+        `'${versionRaw}' is not a release version`,
+        "versions look like @v0.0.32 (or @0.0.32)"
+      );
+    }
+  }
+  return {
+    ...name !== "" ? { what: name } : {},
+    ...version2 !== void 0 ? { version: version2 } : {}
+  };
+}
 var USAGE = `Puddle \u2014 self-hosted orchestrator for CLI coding agents
 
 usage:
@@ -3917,7 +3940,9 @@ usage:
   puddle status  [user@host]
   puddle attach  [user@host] <session> [--term <id>]
   puddle logs    [user@host] [session] [--term <id>] [-f|--follow]
-  puddle upgrade [daemon [user@host] | desktop]
+  puddle install <daemon|desktop>[@version] [user@host] [--tarball <path>]
+  puddle upgrade [cli|daemon|desktop][@version] [user@host] [--tarball <path>]
+  puddle remove  <cli|daemon|desktop> [user@host] [--yes] [--purge]
   puddle --version | --help
 
 launch serves the cockpit at http://localhost:7433 against the daemon on this
@@ -3928,9 +3953,19 @@ to stay attached; Ctrl-C then stops the cockpit). refresh stops a target's
 cockpit (even a wedged one) and runs the full launch flow again \u2014 tunnel,
 daemon restart if needed \u2014 keeping the old UI port so open tabs survive.
 list shows running cockpits; kill stops one \u2014 sessions keep running on the
-host either way. upgrade with no subject updates the CLI itself through npm;
-'daemon' updates puddled (on this machine, or on a user@host) and 'desktop'
-installs or updates the macOS app bundle (Linux AppImages update in-app).`;
+host either way.
+
+install puts a component in place: 'daemon' under ~/.puddle on this machine
+or a user@host, 'desktop' as the macOS app bundle \u2014 or, on Linux, an
+AppImage placed where you say (default ~/puddle), then opened in the file
+manager. Already installed and no @version \u2192 nothing changes.
+upgrade moves components to the newest release (or the named @version),
+installing any that are missing; with no component it covers everything
+installed on the target \u2014 the CLI last, via npm. cli and desktop are
+client-machine artefacts: user@host targets the daemon only. remove
+uninstalls a component after confirmation; 'daemon' stops it (interrupting
+its sessions), unregisters the supervisor, and keeps ~/.puddle's data \u2014
+profiles, session history, worktrees \u2014 unless you also confirm --purge.`;
 function parseArgs(argv) {
   const [cmd, ...rest] = argv;
   if (cmd === void 0 || cmd === "help" || cmd === "--help" || cmd === "-h")
@@ -4101,30 +4136,76 @@ function parseArgs(argv) {
         return { cmd: "logs", follow, ...term !== void 0 ? { term } : {} };
       return first.includes("@") ? { cmd: "logs", host: first, follow, ...term !== void 0 ? { term } : {} } : { cmd: "logs", session: first, follow, ...term !== void 0 ? { term } : {} };
     }
+    case "install": {
+      const [specRaw, host, extra] = positionals;
+      if (extra !== void 0)
+        throw new CliError("bad_arguments", "install takes at most a component + host");
+      const tarball = strFlag("--tarball");
+      expect("--tarball");
+      const spec = specRaw !== void 0 ? parseComponentSpec(specRaw) : null;
+      if (spec?.what === void 0 || spec.what === "cli") {
+        throw new CliError(
+          "bad_arguments",
+          "install takes one of: daemon | desktop (with an optional @version)",
+          spec?.what === "cli" ? "the CLI installs itself via npm: npm install -g @puddle-code/cli" : "e.g. puddle install daemon@v0.0.32 user@host"
+        );
+      }
+      return {
+        cmd: "install",
+        what: spec.what,
+        ...spec.version !== void 0 ? { version: spec.version } : {},
+        ...host !== void 0 ? { host } : {},
+        ...tarball !== void 0 ? { tarball } : {}
+      };
+    }
     case "upgrade": {
+      const tarball = strFlag("--tarball");
+      expect("--tarball");
+      if (positionals.length > 2)
+        throw new CliError("bad_arguments", "upgrade takes at most a component + host");
+      const [first, second] = positionals;
+      const spec = first !== void 0 ? parseComponentSpec(first) : null;
+      const host = spec === null ? first : second;
+      if (spec === null && second !== void 0)
+        throw new CliError(
+          "bad_arguments",
+          `'${first}' is not a component`,
+          "upgrade takes [cli|daemon|desktop][@version], then an optional user@host"
+        );
+      return {
+        cmd: "upgrade",
+        ...spec?.what !== void 0 ? { what: spec.what } : {},
+        ...spec?.version !== void 0 ? { version: spec.version } : {},
+        ...host !== void 0 ? { host } : {},
+        ...tarball !== void 0 ? { tarball } : {}
+      };
+    }
+    case "remove": {
       const [what, host, extra] = positionals;
-      if (what === void 0) {
-        expect();
-        return { cmd: "upgrade", what: "cli" };
-      }
-      if (what === "cli") {
+      if (extra !== void 0)
+        throw new CliError("bad_arguments", "remove takes at most a component + host");
+      expect("--yes", "--purge");
+      if (what === void 0 || !["cli", "daemon", "desktop"].includes(what)) {
         throw new CliError(
           "bad_arguments",
-          "`puddle upgrade cli` is now just `puddle upgrade`",
-          "run: puddle upgrade"
+          "remove needs a component: cli | daemon | desktop",
+          what !== void 0 && /^(cli|daemon|desktop)@/.test(what) ? "remove takes no @version \u2014 a removal has no version to pick" : "e.g. puddle remove daemon user@host"
         );
       }
-      if (what !== "daemon" && what !== "desktop") {
+      const purge = flags.has("--purge");
+      if (purge && what !== "daemon") {
         throw new CliError(
           "bad_arguments",
-          "upgrade takes no subject (the CLI) or one of: daemon | desktop",
-          what.includes("@") ? `to upgrade the daemon on ${what}: puddle upgrade daemon ${what}` : "see: puddle --help"
+          "--purge only applies to the daemon (it deletes ~/.puddle)"
         );
       }
-      if (extra !== void 0)
-        throw new CliError("bad_arguments", "upgrade takes at most a subject + host");
-      expect();
-      return { cmd: "upgrade", what, ...host !== void 0 ? { host } : {} };
+      return {
+        cmd: "remove",
+        what,
+        ...host !== void 0 ? { host } : {},
+        yes: flags.has("--yes"),
+        purge
+      };
     }
     default:
       throw new CliError("bad_arguments", `unknown command '${cmd}'`, "see: puddle --help");
@@ -4145,328 +4226,27 @@ function argvFor(command) {
 
 // src/cli/run.ts
 init_attach();
-import { spawn as spawn7 } from "node:child_process";
-import { existsSync as existsSync3 } from "node:fs";
-import { dirname as dirname7, join as join9 } from "node:path";
+import { existsSync as existsSync4 } from "node:fs";
+import { dirname as dirname7, join as join10 } from "node:path";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 
-// src/lib/desktop-update.ts
-import { createHash } from "node:crypto";
+// src/lib/browser.ts
 import { spawn } from "node:child_process";
-import { constants, createReadStream, createWriteStream } from "node:fs";
-import { access, chmod, mkdir, readdir, rm, writeFile } from "node:fs/promises";
-import { dirname as dirname2, join as join3 } from "node:path";
-import { Readable } from "node:stream";
-import { pipeline } from "node:stream/promises";
-
-// src/lib/paths.ts
-import { homedir } from "node:os";
-import { join } from "node:path";
-function clientHome(env = process.env) {
-  return env.PUDDLE_HOME ?? join(homedir(), ".puddle");
-}
-var HOST_HOME = '"${PUDDLE_HOME:-$HOME/.puddle}"';
-var hostPaths = {
-  home: HOST_HOME,
-  token: `${HOST_HOME}/token`,
-  config: `${HOST_HOME}/config.json`,
-  runtime: `${HOST_HOME}/runtime.json`,
-  current: `${HOST_HOME}/bin/current`,
-  cache: `${HOST_HOME}/cache`,
-  logs: `${HOST_HOME}/logs`
-};
-
-// src/lib/desktop-update.ts
-init_types();
-
-// src/lib/version.ts
-import { readFileSync } from "node:fs";
-import { dirname, join as join2 } from "node:path";
-import { fileURLToPath } from "node:url";
-function cliVersion() {
-  if (true) return "0.0.33";
-  const here = dirname(fileURLToPath(import.meta.url));
-  for (const candidate of [
-    join2(here, "..", "..", "package.json"),
-    join2(here, "..", "package.json")
-  ]) {
-    try {
-      const pkg = JSON.parse(readFileSync(candidate, "utf8"));
-      if (pkg.version !== void 0) return pkg.version;
-    } catch {
-    }
-  }
-  return "0.0.0";
-}
-function pinnedDaemonVersion() {
-  return cliVersion();
-}
-function repoSlug(env = process.env) {
-  if (env.PUDDLE_REPO !== void 0 && env.PUDDLE_REPO !== "") return env.PUDDLE_REPO;
-  if (true) return "PerceptronV/puddle-code";
-  return void 0;
-}
-
-// src/lib/desktop-update.ts
-function isNewerVersion(candidate, current) {
-  const parse3 = (v) => {
-    const match = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(v.trim());
-    return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
-  };
-  const a = parse3(candidate);
-  const b = parse3(current);
-  if (a === null || b === null) return false;
-  for (let i = 0; i < 3; i++) {
-    if (a[i] !== b[i]) return a[i] > b[i];
-  }
-  return false;
-}
-function pickDesktopAsset(assets, platform, arch) {
-  const suffix = platform === "darwin" ? "-mac.zip" : platform === "linux" ? ".AppImage" : null;
-  if (suffix === null) return null;
-  return assets.find(
-    (a) => a.name.endsWith(suffix) && a.name.includes("-arm64") === (arch === "arm64")
-  ) ?? null;
-}
-function parseSums(text) {
-  const sums = /* @__PURE__ */ new Map();
-  for (const line of text.split("\n")) {
-    const match = /^([0-9a-f]{64})\s+\*?(.+?)\s*$/.exec(line.trim());
-    if (match) sums.set(match[2], match[1]);
-  }
-  return sums;
-}
-async function checkForDesktopUpdate(currentVersion, opts = {}) {
-  const slug2 = repoSlug();
-  if (slug2 === void 0) return null;
-  const fetchFn = opts.fetchFn ?? fetch;
-  const response = await fetchFn(`https://api.github.com/repos/${slug2}/releases/latest`, {
-    headers: { accept: "application/vnd.github+json", "user-agent": "puddle-desktop" }
-  });
-  if (!response.ok) {
-    throw new CliError("not_installed", `release lookup failed (HTTP ${response.status})`);
-  }
-  const release = await response.json();
-  const version2 = (release.tag_name ?? "").replace(/^v/, "");
-  if (!isNewerVersion(version2, currentVersion)) return null;
-  const assets = release.assets ?? [];
-  const asset = pickDesktopAsset(
-    assets,
-    opts.platform ?? process.platform,
-    opts.arch ?? process.arch
-  );
-  const sums = assets.find((a) => a.name === "SHA256SUMS");
-  if (asset === null || sums === void 0) return null;
-  return {
-    version: version2,
-    asset: { name: asset.name, url: asset.browser_download_url },
-    sumsUrl: sums.browser_download_url
-  };
-}
-async function stageDesktopUpdate(update, opts = {}) {
-  const logger = opts.logger ?? silentLogger;
-  const fetchFn = opts.fetchFn ?? fetch;
-  const dir = join3(opts.cacheDir ?? join3(clientHome(), "cache", "desktop"), update.version);
-  await rm(dir, { recursive: true, force: true });
-  await mkdir(dir, { recursive: true });
+function openBrowser(url2, platform = process.platform) {
+  const command = platform === "darwin" ? { bin: "open", args: [url2] } : platform === "win32" ? { bin: "cmd", args: ["/c", "start", "", url2] } : { bin: "xdg-open", args: [url2] };
   try {
-    logger.info(`downloading ${update.asset.name}`);
-    const archive = join3(dir, update.asset.name);
-    const response = await fetchFn(update.asset.url, {
-      headers: { "user-agent": "puddle-desktop" }
-    });
-    if (!response.ok || response.body === null) {
-      throw new CliError("not_installed", `download failed (HTTP ${response.status})`);
-    }
-    await pipeline(
-      Readable.fromWeb(response.body),
-      createWriteStream(archive)
-    );
-    const sumsResponse = await fetchFn(update.sumsUrl, {
-      headers: { "user-agent": "puddle-desktop" }
+    const child = spawn(command.bin, command.args, { stdio: "ignore", detached: true });
+    child.on("error", () => {
     });
-    if (!sumsResponse.ok) {
-      throw new CliError("not_installed", `SHA256SUMS fetch failed (HTTP ${sumsResponse.status})`);
-    }
-    const expected = parseSums(await sumsResponse.text()).get(update.asset.name);
-    if (expected === void 0) {
-      throw new CliError("not_installed", `${update.asset.name} is not in SHA256SUMS`);
-    }
-    const actual = await fileSha256(archive);
-    if (actual !== expected) {
-      throw new CliError(
-        "not_installed",
-        `checksum mismatch for ${update.asset.name}`,
-        `expected ${expected}, got ${actual}`
-      );
-    }
-    if (update.asset.name.endsWith(".zip")) {
-      const extractDir = join3(dir, "extract");
-      await run("/usr/bin/ditto", ["-x", "-k", archive, extractDir]);
-      const bundle = (await readdir(extractDir)).find((name) => name.endsWith(".app"));
-      if (bundle === void 0) {
-        throw new CliError("not_installed", "the update zip contains no .app bundle");
-      }
-      logger.info(`staged ${update.version} at ${join3(extractDir, bundle)}`);
-      return {
-        version: update.version,
-        kind: "mac-app",
-        stagedPath: join3(extractDir, bundle),
-        dir
-      };
-    }
-    await chmod(archive, 493);
-    logger.info(`staged ${update.version} at ${archive}`);
-    return { version: update.version, kind: "appimage", stagedPath: archive, dir };
-  } catch (e) {
-    await rm(dir, { recursive: true, force: true });
-    throw e;
-  }
-}
-async function applyDesktopUpdate(staged, opts) {
-  const logger = opts.logger ?? silentLogger;
-  const script = swapScript(staged, opts);
-  const scriptPath = join3(staged.dir, "apply.sh");
-  await writeFile(scriptPath, script, { mode: 493 });
-  logger.info(`applying ${staged.version} via ${scriptPath}`);
-  if (opts.detach ?? true) {
-    const child = spawn("/bin/sh", [scriptPath], { detached: true, stdio: "ignore" });
     child.unref();
-    return;
-  }
-  await run("/bin/sh", [scriptPath]);
-}
-var q = (s) => `'${s.replaceAll("'", `'\\''`)}'`;
-function swapScript(staged, opts) {
-  const wait = opts.waitPid === void 0 ? [] : [
-    `i=0`,
-    `while kill -0 ${opts.waitPid} 2>/dev/null; do`,
-    `  i=$((i+1)); [ "$i" -gt 600 ] && exit 1`,
-    `  sleep 0.1`,
-    `done`
-  ];
-  if (staged.kind === "mac-app") {
-    return [
-      `#!/bin/sh`,
-      `# Puddle desktop update ${staged.version} \u2014 swap once the app exits`,
-      ...wait,
-      `target=${q(opts.targetPath)}`,
-      `target_dir=${q(dirname2(opts.targetPath))}`,
-      `staged=${q(staged.stagedPath)}`,
-      `mkdir -p "$target_dir" || exit 1`,
-      `rm -rf "$target.old"`,
-      `had_old=0`,
-      `if [ -e "$target" ]; then`,
-      `  mv "$target" "$target.old" || exit 1`,
-      `  had_old=1`,
-      `fi`,
-      `if mv "$staged" "$target" 2>/dev/null || /usr/bin/ditto "$staged" "$target"; then`,
-      // Defence in depth: the normal path never quarantines (node's fetch is
-      // not a quarantine-opted-in app, and ditto only propagates what the
-      // zip already carries), but if the bundle ever acquires the attribute
-      // the swap must not resurrect the Gatekeeper prompt.
-      `  /usr/bin/xattr -dr com.apple.quarantine "$target" 2>/dev/null`,
-      `  rm -rf "$target.old" ${q(staged.dir)}`,
-      ...opts.relaunch ? [`  open "$target"`] : [],
-      `else`,
-      `  rm -rf "$target"`,
-      `  [ "$had_old" -eq 0 ] || mv "$target.old" "$target"`,
-      `  exit 1`,
-      `fi`,
-      ``
-    ].join("\n");
-  }
-  return [
-    `#!/bin/sh`,
-    `# Puddle desktop update ${staged.version} \u2014 swap once the app exits`,
-    ...wait,
-    `target=${q(opts.targetPath)}`,
-    `cp -f ${q(staged.stagedPath)} "$target" || exit 1`,
-    `chmod +x "$target"`,
-    `rm -rf ${q(staged.dir)}`,
-    ...opts.relaunch ? [`"$target" >/dev/null 2>&1 &`] : [],
-    ``
-  ].join("\n");
-}
-async function findInstalledDesktopApp(opts = {}) {
-  if ((opts.platform ?? process.platform) !== "darwin") return null;
-  const { readFile } = await import("node:fs/promises");
-  const { homedir: homedir2 } = await import("node:os");
-  const systemApplications = opts.systemApplicationsDir ?? "/Applications";
-  const home = opts.homeDir ?? homedir2();
-  for (const appPath of [
-    join3(systemApplications, "Puddle.app"),
-    join3(home, "Applications", "Puddle.app")
-  ]) {
-    try {
-      const plist = await readFile(join3(appPath, "Contents/Info.plist"), "utf8");
-      const match = /<key>CFBundleShortVersionString<\/key>\s*<string>([^<]+)<\/string>/.exec(
-        plist
-      );
-      if (match) return { appPath, version: match[1] };
-    } catch {
-    }
-  }
-  return null;
-}
-async function desktopAppInstallPath(opts = {}) {
-  if ((opts.platform ?? process.platform) !== "darwin") return null;
-  const { homedir: homedir2 } = await import("node:os");
-  const systemApplications = opts.systemApplicationsDir ?? "/Applications";
-  const canWrite = opts.canWrite ?? (async (path) => {
-    try {
-      await access(path, constants.W_OK);
-      return true;
-    } catch {
-      return false;
-    }
-  });
-  if (await canWrite(systemApplications)) return join3(systemApplications, "Puddle.app");
-  const userApplications = join3(opts.homeDir ?? homedir2(), "Applications");
-  await mkdir(userApplications, { recursive: true });
-  return join3(userApplications, "Puddle.app");
-}
-function isDesktopAppRunning(appPath) {
-  return new Promise((resolve3) => {
-    const child = spawn("/usr/bin/pgrep", ["-f", `${appPath}/Contents/MacOS/`], {
-      stdio: "ignore"
-    });
-    child.on("error", () => resolve3(false));
-    child.on("exit", (code) => resolve3(code === 0));
-  });
-}
-function fileSha256(path) {
-  const hash2 = createHash("sha256");
-  return pipeline(createReadStream(path), hash2).then(() => hash2.digest("hex"));
-}
-function run(command, args) {
-  return new Promise((resolve3, reject) => {
-    const child = spawn(command, args, { stdio: "ignore" });
-    child.on("error", reject);
-    child.on(
-      "exit",
-      (code) => code === 0 ? resolve3() : reject(new CliError("not_installed", `${command} exited with ${code ?? "signal"}`))
-    );
-  });
-}
-
-// src/lib/browser.ts
-import { spawn as spawn2 } from "node:child_process";
-function openBrowser(url2, platform = process.platform) {
-  const command = platform === "darwin" ? { bin: "open", args: [url2] } : platform === "win32" ? { bin: "cmd", args: ["/c", "start", "", url2] } : { bin: "xdg-open", args: [url2] };
-  try {
-    const child = spawn2(command.bin, command.args, { stdio: "ignore", detached: true });
-    child.on("error", () => {
-    });
-    child.unref();
-    return true;
-  } catch {
-    return false;
+    return true;
+  } catch {
+    return false;
   }
 }
 
 // src/lib/connect.ts
-import { join as join6 } from "node:path";
+import { join as join5 } from "node:path";
 
 // ../shared/src/protocol.ts
 var PROTOCOL_VERSION = { major: 14, minor: 2 };
@@ -19974,6 +19754,23 @@ function sleep(ms) {
   return new Promise((r) => setTimeout(r, ms));
 }
 
+// src/lib/paths.ts
+import { homedir } from "node:os";
+import { join } from "node:path";
+function clientHome(env = process.env) {
+  return env.PUDDLE_HOME ?? join(homedir(), ".puddle");
+}
+var HOST_HOME = '"${PUDDLE_HOME:-$HOME/.puddle}"';
+var hostPaths = {
+  home: HOST_HOME,
+  token: `${HOST_HOME}/token`,
+  config: `${HOST_HOME}/config.json`,
+  runtime: `${HOST_HOME}/runtime.json`,
+  current: `${HOST_HOME}/bin/current`,
+  cache: `${HOST_HOME}/cache`,
+  logs: `${HOST_HOME}/logs`
+};
+
 // src/lib/daemon-client.ts
 init_types();
 var LIVE = /* @__PURE__ */ new Set(["starting", "running", "waiting_input"]);
@@ -20016,6 +19813,13 @@ var DaemonClient = class {
   sessions() {
     return this.get("/api/sessions").then((body) => sessionSchema.array().parse(body));
   }
+  profiles() {
+    return this.get("/api/profiles").then((body) => profileSchema.array().parse(body));
+  }
+  /** The live subset of sessions() — what an upgrade/removal interrupts. */
+  async liveSessions() {
+    return (await this.sessions()).filter((s) => LIVE.has(s.status));
+  }
   async liveSessionCount() {
     return (await this.sessions()).filter((s) => LIVE.has(s.status)).length;
   }
@@ -20072,9 +19876,39 @@ async function waitForToken(transport, timeoutMs) {
 
 // src/lib/bootstrap.ts
 import { existsSync, readFileSync as readFileSync2 } from "node:fs";
-import { dirname as dirname3, join as join4, resolve } from "node:path";
+import { dirname as dirname2, join as join3, resolve } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 init_types();
+
+// src/lib/version.ts
+import { readFileSync } from "node:fs";
+import { dirname, join as join2 } from "node:path";
+import { fileURLToPath } from "node:url";
+function cliVersion() {
+  if (true) return "0.0.34";
+  const here = dirname(fileURLToPath(import.meta.url));
+  for (const candidate of [
+    join2(here, "..", "..", "package.json"),
+    join2(here, "..", "package.json")
+  ]) {
+    try {
+      const pkg = JSON.parse(readFileSync(candidate, "utf8"));
+      if (pkg.version !== void 0) return pkg.version;
+    } catch {
+    }
+  }
+  return "0.0.0";
+}
+function pinnedDaemonVersion() {
+  return cliVersion();
+}
+function repoSlug(env = process.env) {
+  if (env.PUDDLE_REPO !== void 0 && env.PUDDLE_REPO !== "") return env.PUDDLE_REPO;
+  if (true) return "PerceptronV/puddle-code";
+  return void 0;
+}
+
+// src/lib/bootstrap.ts
 async function installedVersion(transport) {
   const result = await transport.exec(`readlink ${hostPaths.current}`, { timeoutMs: 15e3 });
   if (result.code !== 0) return null;
@@ -20142,11 +19976,11 @@ function lastLines(text, count = 3) {
   return text.trim().split("\n").slice(-count).join("\n");
 }
 function readInstallScript() {
-  const here = dirname3(fileURLToPath2(import.meta.url));
+  const here = dirname2(fileURLToPath2(import.meta.url));
   const candidates = [
-    join4(here, "install.sh"),
+    join3(here, "install.sh"),
     // dist/index.js → dist/install.sh
-    join4(here, "..", "..", "..", "..", "scripts", "install.sh")
+    join3(here, "..", "..", "..", "..", "scripts", "install.sh")
     // src/lib/ → repo root
   ];
   for (const candidate of candidates) {
@@ -20306,7 +20140,7 @@ function isLocalOrigin(origin) {
 
 // src/lib/serve/local-sync.ts
 import { mkdirSync, readFileSync as readFileSync3, renameSync, writeFileSync } from "node:fs";
-import { dirname as dirname4 } from "node:path";
+import { dirname as dirname3 } from "node:path";
 var MAX_BODY_BYTES = 5 * 1024 * 1024;
 function readStore(file2) {
   try {
@@ -20319,7 +20153,7 @@ function readStore(file2) {
   return { version: 1, profiles: {} };
 }
 function writeStore(file2, store) {
-  mkdirSync(dirname4(file2), { recursive: true });
+  mkdirSync(dirname3(file2), { recursive: true });
   const tmp = `${file2}.tmp-${process.pid}`;
   writeFileSync(tmp, JSON.stringify(store, null, 2) + "\n");
   renameSync(tmp, file2);
@@ -20394,8 +20228,8 @@ function recoverProxiedPath(referer, requestUrl) {
 }
 
 // src/lib/serve/static.ts
-import { createReadStream as createReadStream2, existsSync as existsSync2, statSync } from "node:fs";
-import { extname, join as join5, normalize, resolve as resolve2, sep } from "node:path";
+import { createReadStream, existsSync as existsSync2, statSync } from "node:fs";
+import { extname, join as join4, normalize, resolve as resolve2, sep } from "node:path";
 var MIME = {
   ".html": "text/html; charset=utf-8",
   ".js": "text/javascript; charset=utf-8",
@@ -20423,14 +20257,14 @@ function createStaticHandler(rootDir) {
       res.writeHead(404, { "content-type": "text/plain" }).end("not found");
       return;
     }
-    const requested = normalize(join5(root, decoded));
+    const requested = normalize(join4(root, decoded));
     const candidate = requested.startsWith(root + sep) || requested === root ? requested : root;
     const isFile = existsSync2(candidate) && statSync(candidate).isFile();
     if (!isFile && extname(pathname) !== "") {
       res.writeHead(404, { "content-type": "text/plain" }).end("not found");
       return;
     }
-    const file2 = isFile ? candidate : join5(root, "index.html");
+    const file2 = isFile ? candidate : join4(root, "index.html");
     if (!existsSync2(file2)) {
       res.writeHead(404, { "content-type": "text/plain" }).end("not found");
       return;
@@ -20443,7 +20277,7 @@ function createStaticHandler(rootDir) {
       res.end();
       return;
     }
-    createReadStream2(file2).pipe(res);
+    createReadStream(file2).pipe(res);
   };
 }
 
@@ -20708,7 +20542,7 @@ async function listen(server, startPort, strict, avoidPort) {
 }
 
 // src/lib/tunnel.ts
-import { spawn as spawn3 } from "node:child_process";
+import { spawn as spawn2 } from "node:child_process";
 init_types();
 var RECONNECT_INITIAL_MS = 500;
 var RECONNECT_MAX_MS = 1e4;
@@ -20724,7 +20558,7 @@ async function openCallbackForward(ssh, port, opts = {}) {
     return null;
   };
   if (await tcpListening(port)) return skip("local port busy");
-  const child = spawn3(
+  const child = spawn2(
     opts.sshBinary ?? "ssh",
     ssh.args("-N", "-L", `${port}:127.0.0.1:${port}`, ssh.host),
     { stdio: ["ignore", "ignore", "inherit"] }
@@ -20756,7 +20590,7 @@ async function openTunnel(ssh, remotePort, opts = {}) {
   let healthTimer = null;
   const spawnForward = async (port) => {
     if (stopping) return false;
-    const child = spawn3(
+    const child = spawn2(
       sshBinary,
       ssh.args("-N", "-L", `${port}:127.0.0.1:${remotePort}`, ssh.host),
       { stdio: ["ignore", "ignore", "inherit"] }
@@ -20879,15 +20713,15 @@ async function openTunnel(ssh, remotePort, opts = {}) {
 }
 
 // src/lib/transport/local.ts
-import { spawn as spawn4 } from "node:child_process";
+import { spawn as spawn3 } from "node:child_process";
 import { copyFileSync, mkdirSync as mkdirSync2, readFileSync as readFileSync4 } from "node:fs";
-import { dirname as dirname5 } from "node:path";
+import { dirname as dirname4 } from "node:path";
 var LocalTransport = class {
   kind = "local";
   label = "this machine";
   exec(command, opts = {}) {
     return new Promise((resolve3) => {
-      const child = spawn4("sh", ["-c", command], { stdio: ["pipe", "pipe", "pipe"] });
+      const child = spawn3("sh", ["-c", command], { stdio: ["pipe", "pipe", "pipe"] });
       let stdout = "";
       let stderr = "";
       let timer;
@@ -20922,7 +20756,7 @@ var LocalTransport = class {
   }
   copyTo(localPath, destPath) {
     const dest = expandHome(destPath);
-    mkdirSync2(dirname5(dest), { recursive: true });
+    mkdirSync2(dirname4(dest), { recursive: true });
     copyFileSync(localPath, dest);
     return Promise.resolve();
   }
@@ -20934,7 +20768,7 @@ function expandHome(path) {
 }
 
 // src/lib/transport/ssh.ts
-import { spawn as spawn5 } from "node:child_process";
+import { spawn as spawn4 } from "node:child_process";
 import { mkdirSync as mkdirSync3 } from "node:fs";
 init_types();
 var SshTransport = class {
@@ -20981,7 +20815,7 @@ var SshTransport = class {
    */
   open() {
     return new Promise((resolve3, reject) => {
-      const child = spawn5(this.ssh, this.args(this.host, "true"), { stdio: "inherit" });
+      const child = spawn4(this.ssh, this.args(this.host, "true"), { stdio: "inherit" });
       child.on(
         "error",
         (err) => reject(new CliError("ssh_unreachable", `could not run ${this.ssh}: ${err.message}`))
@@ -21004,7 +20838,7 @@ var SshTransport = class {
   isAlive() {
     if (!this.hasControlMaster) return Promise.resolve(true);
     return new Promise((resolve3) => {
-      const child = spawn5(this.ssh, this.args("-O", "check", this.host), { stdio: "ignore" });
+      const child = spawn4(this.ssh, this.args("-O", "check", this.host), { stdio: "ignore" });
       child.on("error", () => resolve3(false));
       child.on("close", (code) => resolve3(code === 0));
     });
@@ -21021,7 +20855,7 @@ var SshTransport = class {
     if (!this.hasControlMaster) return Promise.resolve();
     return new Promise((resolve3) => {
       const spec = `${localPort}:127.0.0.1:${remotePort}`;
-      const child = spawn5(this.ssh, this.args("-O", "cancel", "-L", spec, this.host), {
+      const child = spawn4(this.ssh, this.args("-O", "cancel", "-L", spec, this.host), {
         stdio: "ignore"
       });
       child.on("error", () => resolve3());
@@ -21030,7 +20864,7 @@ var SshTransport = class {
   }
   exec(command, opts = {}) {
     return new Promise((resolve3) => {
-      const child = spawn5(this.ssh, this.args(this.host, "--", `sh -c ${shellQuote(command)}`), {
+      const child = spawn4(this.ssh, this.args(this.host, "--", `sh -c ${shellQuote(command)}`), {
         stdio: ["pipe", "pipe", "pipe"]
       });
       let stdout = "";
@@ -21065,7 +20899,7 @@ var SshTransport = class {
   async copyTo(localPath, destPath) {
     await this.exec(`mkdir -p $(dirname ${destPath})`, { timeoutMs: 15e3 });
     await new Promise((resolve3, reject) => {
-      const child = spawn5(this.scp, [...this.controlArgs, localPath, `${this.host}:${destPath}`], {
+      const child = spawn4(this.scp, [...this.controlArgs, localPath, `${this.host}:${destPath}`], {
         stdio: ["ignore", "ignore", "inherit"]
       });
       child.on("error", reject);
@@ -21130,7 +20964,7 @@ async function connectRemote(opts) {
     ...opts.onRefreshRequest !== void 0 ? { control: { token: endpoint.token, onRefresh: opts.onRefreshRequest } } : {},
     // The store lives on the CLIENT machine — every cockpit here shares it,
     // whichever remote daemon each one drives.
-    localSync: { token: endpoint.token, file: join6(clientHome(), "local-sync.json") }
+    localSync: { token: endpoint.token, file: join5(clientHome(), "local-sync.json") }
   });
   tunnel.onPortChange((port) => ui.setTarget({ host: "127.0.0.1", port }));
   const eventCbs = /* @__PURE__ */ new Set();
@@ -21182,18 +21016,18 @@ async function showLogs(transport, opts) {
 
 // src/lib/registry.ts
 import { mkdirSync as mkdirSync4, readdirSync, readFileSync as readFileSync5, rmSync, writeFileSync as writeFileSync2 } from "node:fs";
-import { join as join7 } from "node:path";
+import { join as join6 } from "node:path";
 function cockpitsDir(env) {
-  return join7(clientHome(env), "cockpits");
+  return join6(clientHome(env), "cockpits");
 }
 function slug(target) {
   return target.replace(/[^A-Za-z0-9@._-]/g, "_");
 }
 function cockpitRecordPath(target) {
-  return join7(cockpitsDir(), `${slug(target)}.json`);
+  return join6(cockpitsDir(), `${slug(target)}.json`);
 }
 function cockpitLogPath(target) {
-  return join7(clientHome(), "logs", `cockpit-${slug(target)}.log`);
+  return join6(clientHome(), "logs", `cockpit-${slug(target)}.log`);
 }
 function writeCockpitRecord(record2) {
   mkdirSync4(cockpitsDir(), { recursive: true, mode: 448 });
@@ -21222,7 +21056,7 @@ function listCockpitRecords() {
   for (const name of names) {
     if (!name.endsWith(".json")) continue;
     try {
-      records.push(JSON.parse(readFileSync5(join7(cockpitsDir(), name), "utf8")));
+      records.push(JSON.parse(readFileSync5(join6(cockpitsDir(), name), "utf8")));
     } catch {
     }
   }
@@ -21254,7 +21088,7 @@ async function checkCockpit(record2) {
 }
 
 // src/lib/start.ts
-import { join as join8 } from "node:path";
+import { join as join7 } from "node:path";
 init_types();
 async function startLocal(opts) {
   const logger = opts.logger ?? silentLogger;
@@ -21277,7 +21111,7 @@ async function startLocal(opts) {
     // never squat the daemon's own port
     target: { host: "127.0.0.1", port: endpoint.port },
     ...opts.onRefreshRequest !== void 0 ? { control: { token: endpoint.token, onRefresh: opts.onRefreshRequest } } : {},
-    localSync: { token: endpoint.token, file: join8(clientHome(), "local-sync.json") }
+    localSync: { token: endpoint.token, file: join7(clientHome(), "local-sync.json") }
   });
   const eventCbs = /* @__PURE__ */ new Set();
   return {
@@ -21317,7 +21151,405 @@ async function statusReport(client) {
   return { daemon, host, sessions: sessions.filter((s) => s.status !== "archived") };
 }
 
-// src/cli/run.ts
+// src/cli/run.ts
+init_types();
+
+// src/cli/manage.ts
+import { spawn as spawn7 } from "node:child_process";
+import { existsSync as existsSync3 } from "node:fs";
+import { chmod as chmod2, copyFile, mkdir as mkdir2, rename, rm as rm2 } from "node:fs/promises";
+import { homedir as homedir2 } from "node:os";
+import { join as join9 } from "node:path";
+
+// src/lib/desktop-update.ts
+import { createHash } from "node:crypto";
+import { spawn as spawn5 } from "node:child_process";
+import { constants, createReadStream as createReadStream2, createWriteStream } from "node:fs";
+import { access, chmod, mkdir, readdir, rm, writeFile } from "node:fs/promises";
+import { dirname as dirname5, join as join8 } from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+init_types();
+function isNewerVersion(candidate, current) {
+  const parse3 = (v) => {
+    const match = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(v.trim());
+    return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
+  };
+  const a = parse3(candidate);
+  const b = parse3(current);
+  if (a === null || b === null) return false;
+  for (let i = 0; i < 3; i++) {
+    if (a[i] !== b[i]) return a[i] > b[i];
+  }
+  return false;
+}
+function pickDesktopAsset(assets, platform, arch) {
+  const suffix = platform === "darwin" ? "-mac.zip" : platform === "linux" ? ".AppImage" : null;
+  if (suffix === null) return null;
+  return assets.find(
+    (a) => a.name.endsWith(suffix) && a.name.includes("-arm64") === (arch === "arm64")
+  ) ?? null;
+}
+function parseSums(text) {
+  const sums = /* @__PURE__ */ new Map();
+  for (const line of text.split("\n")) {
+    const match = /^([0-9a-f]{64})\s+\*?(.+?)\s*$/.exec(line.trim());
+    if (match) sums.set(match[2], match[1]);
+  }
+  return sums;
+}
+async function checkForDesktopUpdate(currentVersion, opts = {}) {
+  const slug2 = repoSlug();
+  if (slug2 === void 0) return null;
+  const fetchFn = opts.fetchFn ?? fetch;
+  const response = await fetchFn(`https://api.github.com/repos/${slug2}/releases/latest`, {
+    headers: { accept: "application/vnd.github+json", "user-agent": "puddle-desktop" }
+  });
+  if (!response.ok) {
+    throw new CliError("not_installed", `release lookup failed (HTTP ${response.status})`);
+  }
+  const release = await response.json();
+  const version2 = (release.tag_name ?? "").replace(/^v/, "");
+  if (!isNewerVersion(version2, currentVersion)) return null;
+  return updateFromRelease(version2, release.assets ?? [], opts);
+}
+async function desktopUpdateAt(version2, opts = {}) {
+  const slug2 = repoSlug();
+  if (slug2 === void 0) {
+    throw new CliError(
+      "not_installed",
+      "no release source is configured for this build",
+      "set PUDDLE_REPO=owner/repo"
+    );
+  }
+  const fetchFn = opts.fetchFn ?? fetch;
+  const response = await fetchFn(`https://api.github.com/repos/${slug2}/releases/tags/v${version2}`, {
+    headers: { accept: "application/vnd.github+json", "user-agent": "puddle-desktop" }
+  });
+  if (response.status === 404) {
+    throw new CliError("not_installed", `no release v${version2} exists in ${slug2}`);
+  }
+  if (!response.ok) {
+    throw new CliError("not_installed", `release lookup failed (HTTP ${response.status})`);
+  }
+  const release = await response.json();
+  return updateFromRelease(version2, release.assets ?? [], opts);
+}
+function updateFromRelease(version2, assets, opts) {
+  const asset = pickDesktopAsset(
+    assets,
+    opts.platform ?? process.platform,
+    opts.arch ?? process.arch
+  );
+  const sums = assets.find((a) => a.name === "SHA256SUMS");
+  if (asset === null || sums === void 0) return null;
+  return {
+    version: version2,
+    asset: { name: asset.name, url: asset.browser_download_url },
+    sumsUrl: sums.browser_download_url
+  };
+}
+async function stageDesktopUpdate(update, opts = {}) {
+  const logger = opts.logger ?? silentLogger;
+  const fetchFn = opts.fetchFn ?? fetch;
+  const dir = join8(opts.cacheDir ?? join8(clientHome(), "cache", "desktop"), update.version);
+  await rm(dir, { recursive: true, force: true });
+  await mkdir(dir, { recursive: true });
+  try {
+    logger.info(`downloading ${update.asset.name}`);
+    const archive = join8(dir, update.asset.name);
+    const response = await fetchFn(update.asset.url, {
+      headers: { "user-agent": "puddle-desktop" }
+    });
+    if (!response.ok || response.body === null) {
+      throw new CliError("not_installed", `download failed (HTTP ${response.status})`);
+    }
+    await pipeline(
+      Readable.fromWeb(response.body),
+      createWriteStream(archive)
+    );
+    const sumsResponse = await fetchFn(update.sumsUrl, {
+      headers: { "user-agent": "puddle-desktop" }
+    });
+    if (!sumsResponse.ok) {
+      throw new CliError("not_installed", `SHA256SUMS fetch failed (HTTP ${sumsResponse.status})`);
+    }
+    const expected = parseSums(await sumsResponse.text()).get(update.asset.name);
+    if (expected === void 0) {
+      throw new CliError("not_installed", `${update.asset.name} is not in SHA256SUMS`);
+    }
+    const actual = await fileSha256(archive);
+    if (actual !== expected) {
+      throw new CliError(
+        "not_installed",
+        `checksum mismatch for ${update.asset.name}`,
+        `expected ${expected}, got ${actual}`
+      );
+    }
+    if (update.asset.name.endsWith(".zip")) {
+      const extractDir = join8(dir, "extract");
+      await run("/usr/bin/ditto", ["-x", "-k", archive, extractDir]);
+      const bundle = (await readdir(extractDir)).find((name) => name.endsWith(".app"));
+      if (bundle === void 0) {
+        throw new CliError("not_installed", "the update zip contains no .app bundle");
+      }
+      logger.info(`staged ${update.version} at ${join8(extractDir, bundle)}`);
+      return {
+        version: update.version,
+        kind: "mac-app",
+        stagedPath: join8(extractDir, bundle),
+        dir
+      };
+    }
+    await chmod(archive, 493);
+    logger.info(`staged ${update.version} at ${archive}`);
+    return { version: update.version, kind: "appimage", stagedPath: archive, dir };
+  } catch (e) {
+    await rm(dir, { recursive: true, force: true });
+    throw e;
+  }
+}
+async function pruneDesktopUpdateCache(keep = [], opts = {}) {
+  const dir = opts.cacheDir ?? join8(clientHome(), "cache", "desktop");
+  let entries;
+  try {
+    entries = await readdir(dir);
+  } catch {
+    return;
+  }
+  await Promise.all(
+    entries.filter((name) => !keep.includes(name)).map((name) => rm(join8(dir, name), { recursive: true, force: true }).catch(() => {
+    }))
+  );
+}
+async function applyDesktopUpdate(staged, opts) {
+  const logger = opts.logger ?? silentLogger;
+  const script = swapScript(staged, opts);
+  const scriptPath = join8(staged.dir, "apply.sh");
+  await writeFile(scriptPath, script, { mode: 493 });
+  logger.info(`applying ${staged.version} via ${scriptPath}`);
+  if (opts.detach ?? true) {
+    const child = spawn5("/bin/sh", [scriptPath], { detached: true, stdio: "ignore" });
+    child.unref();
+    return;
+  }
+  await run("/bin/sh", [scriptPath]);
+}
+var q = (s) => `'${s.replaceAll("'", `'\\''`)}'`;
+function swapScript(staged, opts) {
+  const wait = opts.waitPid === void 0 ? [] : [
+    `i=0`,
+    `while kill -0 ${opts.waitPid} 2>/dev/null; do`,
+    `  i=$((i+1)); [ "$i" -gt 600 ] && exit 1`,
+    `  sleep 0.1`,
+    `done`
+  ];
+  if (staged.kind === "mac-app") {
+    return [
+      `#!/bin/sh`,
+      `# Puddle desktop update ${staged.version} \u2014 swap once the app exits`,
+      ...wait,
+      `target=${q(opts.targetPath)}`,
+      `target_dir=${q(dirname5(opts.targetPath))}`,
+      `staged=${q(staged.stagedPath)}`,
+      `mkdir -p "$target_dir" || exit 1`,
+      `rm -rf "$target.old"`,
+      `had_old=0`,
+      `if [ -e "$target" ]; then`,
+      `  mv "$target" "$target.old" || exit 1`,
+      `  had_old=1`,
+      `fi`,
+      `if mv "$staged" "$target" 2>/dev/null || /usr/bin/ditto "$staged" "$target"; then`,
+      // Defence in depth: the normal path never quarantines (node's fetch is
+      // not a quarantine-opted-in app, and ditto only propagates what the
+      // zip already carries), but if the bundle ever acquires the attribute
+      // the swap must not resurrect the Gatekeeper prompt.
+      `  /usr/bin/xattr -dr com.apple.quarantine "$target" 2>/dev/null`,
+      `  rm -rf "$target.old" ${q(staged.dir)}`,
+      ...opts.relaunch ? [`  open "$target"`] : [],
+      `else`,
+      `  rm -rf "$target"`,
+      `  [ "$had_old" -eq 0 ] || mv "$target.old" "$target"`,
+      `  exit 1`,
+      `fi`,
+      ``
+    ].join("\n");
+  }
+  return [
+    `#!/bin/sh`,
+    `# Puddle desktop update ${staged.version} \u2014 swap once the app exits`,
+    ...wait,
+    `target=${q(opts.targetPath)}`,
+    `cp -f ${q(staged.stagedPath)} "$target" || exit 1`,
+    `chmod +x "$target"`,
+    `rm -rf ${q(staged.dir)}`,
+    ...opts.relaunch ? [`"$target" >/dev/null 2>&1 &`] : [],
+    ``
+  ].join("\n");
+}
+async function findInstalledDesktopApp(opts = {}) {
+  if ((opts.platform ?? process.platform) !== "darwin") return null;
+  const { readFile } = await import("node:fs/promises");
+  const { homedir: homedir3 } = await import("node:os");
+  const systemApplications = opts.systemApplicationsDir ?? "/Applications";
+  const home = opts.homeDir ?? homedir3();
+  for (const appPath of [
+    join8(systemApplications, "Puddle.app"),
+    join8(home, "Applications", "Puddle.app")
+  ]) {
+    try {
+      const plist = await readFile(join8(appPath, "Contents/Info.plist"), "utf8");
+      const match = /<key>CFBundleShortVersionString<\/key>\s*<string>([^<]+)<\/string>/.exec(
+        plist
+      );
+      if (match) return { appPath, version: match[1] };
+    } catch {
+    }
+  }
+  return null;
+}
+async function desktopAppInstallPath(opts = {}) {
+  if ((opts.platform ?? process.platform) !== "darwin") return null;
+  const { homedir: homedir3 } = await import("node:os");
+  const systemApplications = opts.systemApplicationsDir ?? "/Applications";
+  const canWrite = opts.canWrite ?? (async (path) => {
+    try {
+      await access(path, constants.W_OK);
+      return true;
+    } catch {
+      return false;
+    }
+  });
+  if (await canWrite(systemApplications)) return join8(systemApplications, "Puddle.app");
+  const userApplications = join8(opts.homeDir ?? homedir3(), "Applications");
+  await mkdir(userApplications, { recursive: true });
+  return join8(userApplications, "Puddle.app");
+}
+function isDesktopAppRunning(appPath) {
+  return new Promise((resolve3) => {
+    const child = spawn5("/usr/bin/pgrep", ["-f", `${appPath}/Contents/MacOS/`], {
+      stdio: "ignore"
+    });
+    child.on("error", () => resolve3(false));
+    child.on("exit", (code) => resolve3(code === 0));
+  });
+}
+function fileSha256(path) {
+  const hash2 = createHash("sha256");
+  return pipeline(createReadStream2(path), hash2).then(() => hash2.digest("hex"));
+}
+function run(command, args) {
+  return new Promise((resolve3, reject) => {
+    const child = spawn5(command, args, { stdio: "ignore" });
+    child.on("error", reject);
+    child.on(
+      "exit",
+      (code) => code === 0 ? resolve3() : reject(new CliError("not_installed", `${command} exited with ${code ?? "signal"}`))
+    );
+  });
+}
+
+// src/lib/releases.ts
+init_types();
+async function latestReleaseVersion(opts = {}) {
+  const slug2 = repoSlug();
+  if (slug2 === void 0) {
+    throw new CliError(
+      "not_installed",
+      "no release source is configured for this build",
+      "name a version and pass --tarball, or set PUDDLE_REPO=owner/repo"
+    );
+  }
+  const fetchFn = opts.fetchFn ?? fetch;
+  const res = await fetchFn(`https://api.github.com/repos/${slug2}/releases/latest`, {
+    headers: { accept: "application/vnd.github+json", "user-agent": "puddle-cli" }
+  });
+  if (!res.ok) {
+    throw new CliError(
+      "not_installed",
+      `release lookup failed (HTTP ${res.status})`,
+      "name a version explicitly, e.g. puddle install daemon@v0.0.32"
+    );
+  }
+  const tag = (await res.json()).tag_name ?? "";
+  const version2 = tag.replace(/^v/, "");
+  if (version2 === "") throw new CliError("not_installed", `${slug2} has no published releases`);
+  return version2;
+}
+
+// src/lib/remove-daemon.ts
+init_types();
+async function sweepDirtyWorktrees(transport) {
+  const script = `
+W="\${PUDDLE_HOME:-$HOME/.puddle}/worktrees"
+[ -d "$W" ] || exit 0
+for d in "$W"/*/*; do
+  [ -e "$d/.git" ] || continue
+  dirty=$(git -C "$d" status --porcelain 2>/dev/null | head -1)
+  unpushed=$(git -C "$d" log --branches --not --remotes --oneline 2>/dev/null | head -1)
+  if [ -n "$dirty" ] || [ -n "$unpushed" ]; then printf '%s\\n' "$d"; fi
+done
+exit 0`;
+  const result = await transport.exec("sh -s", { stdin: script, timeoutMs: 6e4 });
+  if (result.code !== 0) return [];
+  return result.stdout.split("\n").map((line) => line.trim()).filter((line) => line !== "");
+}
+async function removeDaemon(transport, opts = { purge: false }) {
+  const logger = opts.logger ?? silentLogger;
+  const script = `
+set -u
+HOME_DIR="\${PUDDLE_HOME:-$HOME/.puddle}"
+say() { printf 'puddled remove: %s\\n' "$1"; }
+
+# systemd user unit
+if command -v systemctl >/dev/null 2>&1 && systemctl --user show-environment >/dev/null 2>&1; then
+  systemctl --user disable --now puddled >/dev/null 2>&1 || true
+  if [ -f "$HOME/.config/systemd/user/puddled.service" ]; then
+    rm -f "$HOME/.config/systemd/user/puddled.service"
+    systemctl --user daemon-reload >/dev/null 2>&1 || true
+    say "removed the systemd user unit"
+  fi
+fi
+
+# launchd agent
+PLIST="$HOME/Library/LaunchAgents/dev.puddle.puddled.plist"
+if [ -f "$PLIST" ]; then
+  launchctl bootout "gui/$(id -u)/dev.puddle.puddled" 2>/dev/null \\
+    || launchctl unload "$PLIST" 2>/dev/null || true
+  rm -f "$PLIST"
+  say "removed the launchd agent"
+fi
+
+# nohup fallback
+if [ -f "$HOME_DIR/puddled.pid" ]; then
+  kill "$(cat "$HOME_DIR/puddled.pid")" 2>/dev/null || true
+  rm -f "$HOME_DIR/puddled.pid"
+fi
+
+if [ "\${PUDDLE_PURGE:-0}" = 1 ]; then
+  rm -rf "$HOME_DIR"
+  say "deleted $HOME_DIR"
+else
+  rm -rf "$HOME_DIR/bin" "$HOME_DIR/cache" "$HOME_DIR/runtime.json"
+  say "removed the install; data kept under $HOME_DIR"
+fi`;
+  const result = await transport.exec(`PUDDLE_PURGE=${opts.purge ? 1 : 0} sh -s`, {
+    stdin: script,
+    timeoutMs: 2 * 6e4,
+    onStdout: (chunk) => {
+      for (const line of chunk.split("\n")) if (line.trim() !== "") logger.info(line.trimEnd());
+    }
+  });
+  if (result.code !== 0) {
+    throw new CliError(
+      "not_installed",
+      `the removal failed on ${transport.label} (exit ${result.code})`,
+      result.stderr.trim().split("\n").slice(-3).join("\n")
+    );
+  }
+}
+
+// src/cli/manage.ts
 init_types();
 
 // src/lib/upgrade.ts
@@ -21476,6 +21708,427 @@ async function terminateCockpit(record2) {
   if (current === null || current.pid === record2.pid) removeCockpitRecord(record2.target);
 }
 
+// src/cli/prompt.ts
+init_types();
+import { createInterface } from "node:readline";
+async function ask(question, def) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) return def;
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await new Promise(
+      (resolve3) => rl.question(`${question} [${def}] `, resolve3)
+    );
+    return answer.trim() === "" ? def : answer.trim();
+  } finally {
+    rl.close();
+  }
+}
+async function confirm(question, opts = {}) {
+  if (opts.skip === true) return true;
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new CliError(
+      "bad_arguments",
+      "refusing to confirm without a terminal",
+      "pass --yes to proceed non-interactively"
+    );
+  }
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await new Promise(
+      (resolve3) => rl.question(`${question} [y/N] `, resolve3)
+    );
+    return /^y(es)?$/i.test(answer.trim());
+  } finally {
+    rl.close();
+  }
+}
+
+// src/cli/manage.ts
+function assertLocal(what, host, verb) {
+  if (host === void 0 || host === "local") return;
+  throw new CliError(
+    "bad_arguments",
+    `puddle ${verb} ${what} runs on the machine it ${verb}s`,
+    `ssh into ${host} and run it there \u2014 user@host targets the daemon only`
+  );
+}
+async function openTransport(host) {
+  const transport = host === void 0 || host === "local" ? new LocalTransport() : new SshTransport(host);
+  if (transport instanceof SshTransport) await transport.open();
+  return transport;
+}
+async function resolveDaemonVersion(logger) {
+  try {
+    return await latestReleaseVersion();
+  } catch (e) {
+    const pinned = pinnedDaemonVersion();
+    logger.warn(
+      `cannot resolve the newest release (${e instanceof Error ? e.message : String(e)}) \u2014 using this CLI's version train v${pinned}`
+    );
+    return pinned;
+  }
+}
+function pinWarning(logger, version2) {
+  if (version2 === cliVersion()) return;
+  logger.warn(
+    `pinning the daemon to v${version2} while this CLI is v${cliVersion()} \u2014 if the two speak different protocol majors, the next \`puddle launch\` will upgrade the daemon back (or refuse). Pin the CLI too (puddle upgrade cli@v${version2}) or launch with --no-upgrade.`
+  );
+}
+async function runInstall(cmd, logger) {
+  if (cmd.what === "desktop") {
+    assertLocal("desktop", cmd.host, "install");
+    if (cmd.tarball !== void 0) {
+      throw new CliError("bad_arguments", "--tarball applies to the daemon only");
+    }
+    return setDesktop({ version: cmd.version, verb: "install" }, logger);
+  }
+  const transport = await openTransport(cmd.host);
+  try {
+    const installed = await installedVersion(transport);
+    if (installed !== null && cmd.version === void 0) {
+      logger.info(
+        `puddled v${installed} is already installed on ${transport.label} \u2014 \`puddle upgrade daemon\` moves it to the newest release`
+      );
+      return 0;
+    }
+    if (installed !== null && installed === cmd.version) {
+      logger.info(`puddled v${installed} is already installed on ${transport.label}`);
+      return 0;
+    }
+    return installDaemonAt(transport, cmd.version, cmd.tarball, logger);
+  } finally {
+    transport.dispose();
+  }
+}
+async function installDaemonAt(transport, explicit, tarball, logger) {
+  const version2 = explicit ?? (tarball !== void 0 ? void 0 : await resolveDaemonVersion(logger));
+  if (explicit !== void 0) pinWarning(logger, explicit);
+  const result = await upgradeDaemon(transport, {
+    ...version2 !== void 0 ? { version: version2 } : {},
+    ...tarball !== void 0 ? { tarball } : {},
+    logger
+  });
+  logger.info(`puddled ${result.from ?? "(fresh install)"} \u2192 ${result.to} on ${transport.label}`);
+  return 0;
+}
+async function runUpgrade(cmd, logger) {
+  if (cmd.what !== void 0) {
+    if (cmd.what !== "daemon" && cmd.tarball !== void 0) {
+      throw new CliError("bad_arguments", "--tarball applies to the daemon only");
+    }
+    switch (cmd.what) {
+      case "cli":
+        assertLocal("cli", cmd.host, "upgrade");
+        return upgradeCli(cmd.version, logger);
+      case "desktop":
+        assertLocal("desktop", cmd.host, "upgrade");
+        return setDesktop({ version: cmd.version, verb: "upgrade" }, logger);
+      case "daemon": {
+        const transport2 = await openTransport(cmd.host);
+        try {
+          return await installDaemonAt(transport2, cmd.version, cmd.tarball, logger);
+        } finally {
+          transport2.dispose();
+        }
+      }
+    }
+  }
+  if (cmd.host !== void 0 && cmd.host !== "local") {
+    logger.info(`${cmd.host} hosts the daemon only \u2014 upgrading it`);
+    const transport2 = await openTransport(cmd.host);
+    try {
+      return await installDaemonAt(transport2, cmd.version, cmd.tarball, logger);
+    } finally {
+      transport2.dispose();
+    }
+  }
+  const transport = new LocalTransport();
+  const daemonInstalled = await installedVersion(transport) !== null;
+  const desktopInstalled = process.platform === "darwin" && await findInstalledDesktopApp() !== null;
+  if (daemonInstalled) await installDaemonAt(transport, cmd.version, cmd.tarball, logger);
+  else logger.info("no daemon installed on this machine \u2014 skipping (puddle install daemon)");
+  if (desktopInstalled) await setDesktop({ version: cmd.version, verb: "upgrade" }, logger);
+  else if (process.platform === "darwin") logger.info("no desktop app installed \u2014 skipping");
+  return upgradeCli(cmd.version, logger);
+}
+function upgradeCli(version2, logger) {
+  const spec = `@puddle-code/cli@${version2 ?? "latest"}`;
+  logger.info(`puddle CLI ${cliVersion()} \u2014 asking npm for ${version2 ?? "the latest release"}`);
+  return new Promise((resolve3, reject) => {
+    const child = spawn7("npm", ["install", "-g", spec], { stdio: "inherit" });
+    child.on(
+      "error",
+      () => reject(
+        new CliError(
+          "not_installed",
+          "npm is not on PATH",
+          `the CLI is installed and upgraded via npm: npm install -g ${spec}`
+        )
+      )
+    );
+    child.on("exit", (code) => {
+      if (code === 0) {
+        logger.info("done \u2014 `puddle --version` shows the installed version");
+        resolve3(0);
+      } else {
+        reject(new CliError("not_installed", `npm install exited with ${code ?? "a signal"}`));
+      }
+    });
+  });
+}
+async function setDesktop(opts, logger) {
+  if (process.platform === "linux") {
+    if (opts.verb !== "install") {
+      throw new CliError(
+        "not_installed",
+        "AppImages upgrade from inside the app (its toast knows $APPIMAGE)",
+        "to place a fresh copy: puddle install desktop"
+      );
+    }
+    return installDesktopAppImage(opts.version, logger);
+  }
+  const installed = await findInstalledDesktopApp();
+  const targetPath = installed?.appPath ?? await desktopAppInstallPath();
+  if (targetPath === null) {
+    throw new CliError("not_installed", "the desktop app ships for macOS and Linux only");
+  }
+  if (installed !== null && await isDesktopAppRunning(installed.appPath)) {
+    throw new CliError(
+      "already_running",
+      "Puddle is running \u2014 use its update toast, or quit it and rerun"
+    );
+  }
+  if (opts.verb === "install" && installed !== null && opts.version === void 0) {
+    logger.info(
+      `Puddle ${installed.version} is already installed at ${installed.appPath} \u2014 \`puddle upgrade desktop\` moves it to the newest release`
+    );
+    return 0;
+  }
+  if (installed !== null && installed.version === opts.version) {
+    logger.info(`Puddle ${installed.version} is already installed at ${installed.appPath}`);
+    return 0;
+  }
+  const update = opts.version !== void 0 ? await desktopUpdateAt(opts.version) : await checkForDesktopUpdate(installed?.version ?? "0.0.0");
+  if (update === null) {
+    if (opts.version !== void 0) {
+      throw new CliError(
+        "not_installed",
+        `release v${opts.version} has no desktop build for this platform/architecture`
+      );
+    }
+    if (installed === null) {
+      throw new CliError(
+        "not_installed",
+        "no Puddle desktop release is available for this macOS architecture"
+      );
+    }
+    logger.info(`Puddle ${installed.version} is already the latest release`);
+    return 0;
+  }
+  const move = installed === null ? `installing Puddle ${update.version}` : `Puddle ${installed.version} \u2192 ${update.version}` + (isNewerVersion(update.version, installed.version) ? "" : " (a downgrade)");
+  logger.info(move);
+  const staged = await stageDesktopUpdate(update, { logger });
+  await applyDesktopUpdate(staged, { targetPath, detach: false, relaunch: false, logger });
+  logger.info(`Puddle ${update.version} installed at ${targetPath}`);
+  return 0;
+}
+async function installDesktopAppImage(version2, logger) {
+  const update = version2 !== void 0 ? await desktopUpdateAt(version2) : await checkForDesktopUpdate("0.0.0");
+  if (update === null) {
+    throw new CliError(
+      "not_installed",
+      version2 !== void 0 ? `release v${version2} has no AppImage for this architecture` : "no Puddle desktop release is available for this Linux architecture"
+    );
+  }
+  const dir = expandHome2(await ask("Where should the AppImage be stored?", "~/puddle"));
+  const target = join9(dir, "Puddle.AppImage");
+  if (existsSync3(target) && version2 === void 0) {
+    logger.info(`${target} already exists \u2014 the app updates itself in-app (its update toast)`);
+    return 0;
+  }
+  logger.info(`installing Puddle ${update.version} to ${target}`);
+  const staged = await stageDesktopUpdate(update, { logger });
+  await mkdir2(dir, { recursive: true });
+  await rm2(target, { force: true });
+  try {
+    await rename(staged.stagedPath, target);
+  } catch {
+    await copyFile(staged.stagedPath, target);
+    await chmod2(target, 493);
+  }
+  await rm2(staged.dir, { recursive: true, force: true });
+  logger.info(`installed \u2014 run it directly (${target}) or add it to your launcher`);
+  const opener = spawn7("xdg-open", [dir], { stdio: "ignore", detached: true });
+  opener.on("error", () => void 0);
+  opener.unref();
+  return 0;
+}
+function expandHome2(path) {
+  if (path === "~") return homedir2();
+  return path.startsWith("~/") ? join9(homedir2(), path.slice(2)) : path;
+}
+async function runRemove(cmd, logger) {
+  switch (cmd.what) {
+    case "cli":
+      assertLocal("cli", cmd.host, "remove");
+      return removeCli(cmd.yes, logger);
+    case "desktop":
+      assertLocal("desktop", cmd.host, "remove");
+      return removeDesktop(cmd.yes, logger);
+    case "daemon":
+      return removeDaemonCmd(cmd, logger);
+  }
+}
+async function removeCli(yes, logger) {
+  const managed = await new Promise((resolve3) => {
+    const child = spawn7("npm", ["ls", "-g", "@puddle-code/cli", "--depth=0"], { stdio: "ignore" });
+    child.on("error", () => resolve3(false));
+    child.on("exit", (code) => resolve3(code === 0));
+  });
+  if (!managed) {
+    throw new CliError(
+      "not_installed",
+      "the puddle CLI is not an npm global install on this machine",
+      "a repo checkout or linked dev build is removed the way it was installed"
+    );
+  }
+  const proceed = await confirm(
+    `Remove the puddle CLI (npm uninstall -g @puddle-code/cli)? Running cockpits keep running until killed; daemons and their sessions are untouched.`,
+    { skip: yes }
+  );
+  if (!proceed) {
+    logger.info("nothing removed");
+    return 0;
+  }
+  return new Promise((resolve3, reject) => {
+    const child = spawn7("npm", ["uninstall", "-g", "@puddle-code/cli"], { stdio: "inherit" });
+    child.on("error", () => reject(new CliError("not_installed", "npm is not on PATH")));
+    child.on("exit", (code) => {
+      if (code === 0) {
+        logger.info("removed \u2014 daemons keep running (puddle remove daemon uninstalls one)");
+        resolve3(0);
+      } else {
+        reject(new CliError("not_installed", `npm uninstall exited with ${code ?? "a signal"}`));
+      }
+    });
+  });
+}
+async function removeDesktop(yes, logger) {
+  if (process.platform !== "darwin") {
+    throw new CliError(
+      "not_installed",
+      "desktop removal is macOS-only",
+      "an AppImage carries no fixed path \u2014 delete the file where you put it (puddle install desktop defaults to ~/puddle/Puddle.AppImage)"
+    );
+  }
+  const installed = await findInstalledDesktopApp();
+  if (installed === null) {
+    logger.info("no Puddle.app in /Applications or ~/Applications \u2014 nothing to remove");
+    return 0;
+  }
+  if (await isDesktopAppRunning(installed.appPath)) {
+    throw new CliError("already_running", "Puddle is running \u2014 quit it first");
+  }
+  const proceed = await confirm(
+    `Delete ${installed.appPath} (Puddle ${installed.version})? Daemons and their sessions are untouched.`,
+    { skip: yes }
+  );
+  if (!proceed) {
+    logger.info("nothing removed");
+    return 0;
+  }
+  await rm2(installed.appPath, { recursive: true, force: true });
+  await pruneDesktopUpdateCache([]);
+  logger.info(`deleted ${installed.appPath} (recent hosts kept in ~/.puddle/recent-hosts.json)`);
+  return 0;
+}
+async function removeDaemonCmd(cmd, logger) {
+  const target = cmd.host ?? "local";
+  const transport = await openTransport(cmd.host);
+  let tunnel = null;
+  try {
+    const installed = await installedVersion(transport);
+    if (installed === null) {
+      logger.info(
+        `no bootstrap-managed daemon on ${transport.label} \u2014 nothing to remove (its data, if any, stays under ~/.puddle)`
+      );
+      return 0;
+    }
+    let live = null;
+    let profileNames = null;
+    try {
+      const token = await readToken(transport);
+      if (token !== null) {
+        let port = await readDaemonPort(transport);
+        if (transport instanceof SshTransport) {
+          tunnel = await openTunnel(transport, port, {
+            ready: (localPort) => waitForHttp(`http://127.0.0.1:${localPort}/api/version`, 8e3)
+          });
+          port = tunnel.localPort;
+        }
+        const client = new DaemonClient(port, token);
+        live = await client.liveSessions();
+        profileNames = (await client.profiles()).map((p) => p.name);
+      }
+    } catch {
+    }
+    logger.info(`puddled v${installed} on ${transport.label}`);
+    if (live !== null && live.length > 0) {
+      logger.warn(`${live.length} running session(s) will be interrupted:`);
+      for (const s of live) {
+        logger.warn(`  ${s.id.slice(0, 8)}  ${s.status}  ${s.title ?? "(untitled)"}`);
+      }
+    }
+    if (profileNames !== null && profileNames.length > 0) {
+      logger.info(`profiles on this daemon: ${profileNames.join(", ")}`);
+    }
+    const proceed = await confirm(
+      `Stop puddled v${installed} on ${transport.label}, unregister its supervisor, and uninstall it?`,
+      { skip: cmd.yes }
+    );
+    if (!proceed) {
+      logger.info("nothing removed");
+      return 0;
+    }
+    let purge = cmd.purge;
+    if (!purge && !cmd.yes) {
+      purge = await confirm(
+        `Also delete ~/.puddle on ${transport.label} \u2014 profiles, session history, agent credentials, and WORKTREES?`
+      );
+    }
+    if (purge) {
+      const dirty = await sweepDirtyWorktrees(transport);
+      if (dirty.length > 0) {
+        logger.warn("these worktrees carry uncommitted or unpushed work:");
+        for (const path of dirty) logger.warn(`  ${path}`);
+        const anyway = cmd.yes ? true : await confirm("Delete them anyway?");
+        if (!anyway) {
+          purge = false;
+          logger.info("keeping ~/.puddle \u2014 only the install is removed");
+        }
+      }
+    }
+    const record2 = readCockpitRecord(target);
+    if (record2 !== null) {
+      if (await checkCockpit(record2) === "dead") removeCockpitRecord(target);
+      else {
+        await terminateCockpit(record2);
+        logger.info(`stopped the cockpit for ${target}`);
+      }
+    }
+    await tunnel?.close();
+    tunnel = null;
+    await removeDaemon(transport, { purge, logger });
+    logger.info(
+      purge ? `puddled removed from ${transport.label}; ~/.puddle deleted` : `puddled removed from ${transport.label}; data kept \u2014 \`puddle launch\` reinstalls and resumes`
+    );
+    return 0;
+  } finally {
+    await tunnel?.close();
+    transport.dispose();
+  }
+}
+
 // src/cli/output.ts
 function terminalLogger() {
   return {
@@ -21505,8 +22158,8 @@ function timestampedLogger() {
 // src/cli/run.ts
 function assetsDir() {
   const here = dirname7(fileURLToPath3(import.meta.url));
-  for (const candidate of [join9(here, "public"), join9(here, "..", "..", "dist", "public")]) {
-    if (existsSync3(join9(candidate, "index.html"))) return candidate;
+  for (const candidate of [join10(here, "public"), join10(here, "..", "..", "dist", "public")]) {
+    if (existsSync4(join10(candidate, "index.html"))) return candidate;
   }
   throw new CliError(
     "not_installed",
@@ -21788,96 +22441,13 @@ async function run2(command) {
         await target.close();
       }
     }
-    case "upgrade": {
-      const local = command.host === void 0 || command.host === "local";
-      if (command.what === "daemon") {
-        const transport = local ? new LocalTransport() : new SshTransport(command.host);
-        if (transport instanceof SshTransport) await transport.open();
-        try {
-          const result = await upgradeDaemon(transport, { logger });
-          logger.info(
-            `puddled ${result.from ?? "(unmanaged)"} \u2192 ${result.to} on ${transport.label}`
-          );
-          return 0;
-        } finally {
-          transport.dispose();
-        }
-      }
-      if (!local) {
-        throw new CliError(
-          "bad_arguments",
-          `puddle upgrade ${command.what} runs on the machine it upgrades`,
-          `ssh into ${command.host} and run it there \u2014 user@host targets the daemon only`
-        );
-      }
-      return command.what === "cli" ? upgradeCli(logger) : upgradeDesktop(logger);
-    }
-  }
-}
-function upgradeCli(logger) {
-  logger.info(`puddle CLI ${cliVersion()} \u2014 asking npm for the latest release`);
-  return new Promise((resolve3, reject) => {
-    const child = spawn7("npm", ["install", "-g", "@puddle-code/cli@latest"], {
-      stdio: "inherit"
-    });
-    child.on(
-      "error",
-      () => reject(
-        new CliError(
-          "not_installed",
-          "npm is not on PATH",
-          "the CLI is installed and upgraded via npm: npm install -g @puddle-code/cli@latest"
-        )
-      )
-    );
-    child.on("exit", (code) => {
-      if (code === 0) {
-        logger.info("done \u2014 `puddle --version` shows the installed version");
-        resolve3(0);
-      } else {
-        reject(new CliError("not_installed", `npm install exited with ${code ?? "a signal"}`));
-      }
-    });
-  });
-}
-async function upgradeDesktop(logger) {
-  const installed = await findInstalledDesktopApp();
-  const targetPath = installed?.appPath ?? await desktopAppInstallPath();
-  if (targetPath === null) {
-    throw new CliError(
-      "not_installed",
-      "no Puddle.app in /Applications or ~/Applications",
-      process.platform === "linux" ? "AppImages carry no fixed path \u2014 update from the app itself (its banner knows $APPIMAGE)" : void 0
-    );
-  }
-  if (installed !== null && await isDesktopAppRunning(installed.appPath)) {
-    throw new CliError(
-      "already_running",
-      "Puddle is running \u2014 use its update banner, or quit it and rerun"
-    );
-  }
-  const update = await checkForDesktopUpdate(installed?.version ?? "0.0.0");
-  if (update === null) {
-    if (installed === null) {
-      throw new CliError(
-        "not_installed",
-        "no Puddle desktop release is available for this macOS architecture"
-      );
-    }
-    logger.info(`Puddle ${installed.version} is already the latest release`);
-    return 0;
+    case "install":
+      return runInstall(command, logger);
+    case "upgrade":
+      return runUpgrade(command, logger);
+    case "remove":
+      return runRemove(command, logger);
   }
-  if (installed === null) logger.info(`installing Puddle ${update.version}`);
-  else logger.info(`Puddle ${installed.version} \u2192 ${update.version}`);
-  const staged = await stageDesktopUpdate(update, { logger });
-  await applyDesktopUpdate(staged, {
-    targetPath,
-    detach: false,
-    relaunch: false,
-    logger
-  });
-  logger.info(`Puddle ${update.version} installed at ${targetPath}`);
-  return 0;
 }
 async function runCockpit(command, target, terminal) {
   const detached = isCockpitChild();