moondesk 0.1.4 → 0.2.0

package/README.md

@@ -90,6 +90,8 @@ I tried this with GPT-5.2 before, and the results were poor. However, **GPT-5.4
 
    MoonDesk does not rely on npm lifecycle/install scripts. On the first `moondesk` run, the small npm wrapper downloads the matching native binary from the GitHub Release, verifies it against that release's `SHA256SUMS`, and stores it in a versioned user cache under `~/.moondesk/npm-bin/`. This works with npm 12's default-deny install-script policy and also keeps the running native executable outside npm's `node_modules`, which makes Windows package upgrades less likely to hit locked-file errors.
 
+   Globally installed npm copies also check `moondesk@latest` in the background. When a newer stable release is available, the Status panel shows the current version and `[u] Update & Restart`. Pressing `u` always opens a confirmation modal first: make sure no ChatGPT/MCP session or command is running because MoonDesk will restart and the active connection will be interrupted. Press `Enter` to continue or `Esc` to abort. The wrapper then installs the exact version that was shown, verifies that npm really replaced the package with that version, restarts MoonDesk in the same working directory with the same arguments, and removes older verified native/update caches on subsequent startup. Multiple MoonDesk processes serialize global npm updates so they do not race each other. Local dependency or `npx` copies never offer in-app self-update.
+
 2. Run MoonDesk from any terminal directory.
 
    ```bash

package/npm/install-binary.js

@@ -4,6 +4,7 @@ const crypto = require("node:crypto");
 const fs = require("node:fs");
 const os = require("node:os");
 const path = require("node:path");
+const { compareStableVersions, parseStableVersion } = require("./update-manager");
 
 const packageRoot = path.resolve(__dirname, "..");
 const packageJson = require(path.join(packageRoot, "package.json"));
@@ -44,12 +45,62 @@ function resolveTarget(platform = process.platform, arch = process.arch) {
   };
 }
 
+function defaultBinaryCacheRoot() {
+  return path.join(os.homedir(), ".moondesk", "npm-bin");
+}
+
 function defaultInstallDir(target) {
   if (process.env.MOONDESK_BINARY_CACHE_DIR) {
     return path.resolve(process.env.MOONDESK_BINARY_CACHE_DIR);
   }
 
-  return path.join(os.homedir(), ".moondesk", "npm-bin", releaseTag, target);
+  return path.join(defaultBinaryCacheRoot(), releaseTag, target);
+}
+
+function stableTagIsOlder(candidate, current) {
+  if (!candidate.startsWith("v") || !current.startsWith("v")) return false;
+  const candidateVersion = candidate.slice(1);
+  const currentVersionText = current.slice(1);
+  if (!parseStableVersion(candidateVersion) || !parseStableVersion(currentVersionText)) return false;
+  return compareStableVersions(candidateVersion, currentVersionText) < 0;
+}
+
+function cleanupOldBinaryVersions(options = {}) {
+  if (process.env.MOONDESK_BINARY_CACHE_DIR && !options.cacheRoot) {
+    return { removed: [], skipped: [] };
+  }
+
+  const cacheRoot = options.cacheRoot ?? defaultBinaryCacheRoot();
+  const keepTag = options.keepTag ?? releaseTag;
+  const removed = [];
+  const skipped = [];
+
+  let entries;
+  try {
+    entries = fs.readdirSync(cacheRoot, { withFileTypes: true });
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return { removed, skipped };
+    }
+    throw error;
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory() || !stableTagIsOlder(entry.name, keepTag)) {
+      continue;
+    }
+    const stalePath = path.join(cacheRoot, entry.name);
+    try {
+      fs.rmSync(stalePath, { recursive: true, force: true, maxRetries: 2, retryDelay: 100 });
+      removed.push(entry.name);
+    } catch {
+      // Another still-running MoonDesk process may hold an older Windows binary open.
+      // Leave it in place and retry on the next managed launch.
+      skipped.push(entry.name);
+    }
+  }
+
+  return { removed, skipped };
 }
 
 async function fetchRequired(fetchImpl, url, maxBytes, timeoutMs = METADATA_TIMEOUT_MS) {
@@ -331,6 +382,7 @@ async function ensureBinary(options = {}) {
 }
 
 module.exports = {
+  cleanupOldBinaryVersions,
   ensureBinary,
   expectedSha256,
   resolveTarget,

package/npm/moondesk.js

@@ -1,40 +1,250 @@
 #!/usr/bin/env node
 
+const fs = require("node:fs");
 const { spawn } = require("node:child_process");
-const { ensureBinary } = require("./install-binary");
+const { cleanupOldBinaryVersions, ensureBinary } = require("./install-binary");
+const {
+  UPDATE_EXIT_CODE,
+  acquireUpdateLock,
+  cleanupOldUpdateVersions,
+  compareStableVersions,
+  createUpdateRequestPath,
+  createUpdateStatePath,
+  installExactVersion,
+  installedWrapperVersion,
+  readUpdateRequest,
+  restartUpdatedWrapper,
+  startUpdateMonitor,
+  verifyInstalledWrapperVersion,
+} = require("./update-manager");
+
+function cleanManagedUpdateEnv(source = process.env) {
+  const env = { ...source };
+  delete env.MOONDESK_NPM_MANAGED;
+  delete env.MOONDESK_UPDATE_REQUEST_PATH;
+  delete env.MOONDESK_UPDATE_STATE_PATH;
+  return env;
+}
+
+function cleanupEphemeralUpdateFiles(statePath, requestPath) {
+  for (const filePath of [statePath, requestPath]) {
+    if (!filePath) continue;
+    try {
+      fs.rmSync(filePath, { force: true });
+    } catch {
+      // Ephemeral updater metadata must never make normal MoonDesk startup or shutdown fail.
+    }
+  }
+}
+
+function runNative(binaryPath, args, options = {}) {
+  const spawnImpl = options.spawnImpl ?? spawn;
+  return new Promise((resolve, reject) => {
+    const child = spawnImpl(binaryPath, args, {
+      cwd: options.cwd ?? process.cwd(),
+      env: options.env ?? process.env,
+      stdio: "inherit",
+    });
+    child.once("error", reject);
+    child.once("exit", (code, signal) => resolve({ code: code ?? 1, signal }));
+  });
+}
+
+async function orchestrate(options = {}) {
+  const logger = options.logger ?? console;
+  const originalArgs = options.args ?? process.argv.slice(2);
+  const originalCwd = options.cwd ?? process.cwd();
+  const baseEnv = cleanManagedUpdateEnv(options.env ?? process.env);
+  const createUpdateStatePathImpl = options.createUpdateStatePathImpl ?? createUpdateStatePath;
+  const createUpdateRequestPathImpl = options.createUpdateRequestPathImpl ?? createUpdateRequestPath;
+  let updateStatePath = options.updateStatePath ?? null;
+  let updateRequestPath = options.updateRequestPath ?? null;
+  let selfUpdateEnabled = true;
+  try {
+    updateStatePath = updateStatePath ?? createUpdateStatePathImpl();
+    updateRequestPath = updateRequestPath ?? createUpdateRequestPathImpl();
+  } catch (error) {
+    if (!options.updateStatePath) cleanupEphemeralUpdateFiles(updateStatePath, null);
+    if (!options.updateRequestPath) cleanupEphemeralUpdateFiles(null, updateRequestPath);
+    updateStatePath = null;
+    updateRequestPath = null;
+    selfUpdateEnabled = false;
+    logger.warn?.(
+      `MoonDesk disabled in-app self-update because it could not prepare update metadata: ${error.message}`,
+    );
+  }
+  const ensureBinaryImpl = options.ensureBinaryImpl ?? ensureBinary;
+  const cleanupOldBinaryVersionsImpl = options.cleanupOldBinaryVersionsImpl ?? cleanupOldBinaryVersions;
+  const cleanupOldUpdateVersionsImpl = options.cleanupOldUpdateVersionsImpl ?? cleanupOldUpdateVersions;
+  const startUpdateMonitorImpl = options.startUpdateMonitorImpl ?? startUpdateMonitor;
+  const runNativeImpl = options.runNativeImpl ?? runNative;
+  const readUpdateRequestImpl = options.readUpdateRequestImpl ?? readUpdateRequest;
+  const acquireUpdateLockImpl = options.acquireUpdateLockImpl ?? acquireUpdateLock;
+  const installedWrapperVersionImpl = options.installedWrapperVersionImpl ?? installedWrapperVersion;
+  const installExactVersionImpl = options.installExactVersionImpl ?? installExactVersion;
+  const verifyInstalledWrapperVersionImpl =
+    options.verifyInstalledWrapperVersionImpl ?? verifyInstalledWrapperVersion;
+  const restartUpdatedWrapperImpl = options.restartUpdatedWrapperImpl ?? restartUpdatedWrapper;
+  const wrapperPath = options.wrapperPath ?? __filename;
+
+  const stopUpdateMonitor = selfUpdateEnabled
+    ? startUpdateMonitorImpl({
+        statePath: updateStatePath,
+        cwd: originalCwd,
+        env: baseEnv,
+      })
+    : () => {};
 
-async function main() {
   let binaryPath;
   try {
-    binaryPath = await ensureBinary();
+    binaryPath = await ensureBinaryImpl();
   } catch (error) {
-    console.error(`MoonDesk could not prepare its native binary: ${error.message}`);
-    console.error("Check your network connection and the matching GitHub Release, then run MoonDesk again.");
-    process.exit(1);
-    return;
+    stopUpdateMonitor();
+    cleanupEphemeralUpdateFiles(updateStatePath, updateRequestPath);
+    logger.error(`MoonDesk could not prepare its native binary: ${error.message}`);
+    logger.error(
+      "Check your network connection and the matching GitHub Release, then run MoonDesk again.",
+    );
+    return { code: 1, signal: null };
   }
 
-  const child = spawn(binaryPath, process.argv.slice(2), {
-    cwd: process.cwd(),
-    env: process.env,
-    stdio: "inherit",
-  });
+  try {
+    cleanupOldBinaryVersionsImpl();
+  } catch (error) {
+    // Cache cleanup is best-effort. A locked old Windows executable must not stop MoonDesk.
+    logger.warn?.(`MoonDesk could not remove an older native cache yet: ${error.message}`);
+  }
+  try {
+    cleanupOldUpdateVersionsImpl();
+  } catch (error) {
+    logger.warn?.(`MoonDesk could not remove older update metadata yet: ${error.message}`);
+  }
 
-  child.on("error", (error) => {
-    console.error(`MoonDesk failed to start: ${error.message}`);
-    process.exit(1);
-  });
+  const childEnv = { ...baseEnv };
+  if (selfUpdateEnabled) {
+    Object.assign(childEnv, {
+      MOONDESK_NPM_MANAGED: "1",
+      MOONDESK_UPDATE_REQUEST_PATH: updateRequestPath,
+      MOONDESK_UPDATE_STATE_PATH: updateStatePath,
+    });
+  }
+
+  let result;
+  try {
+    result = await runNativeImpl(binaryPath, originalArgs, {
+      cwd: originalCwd,
+      env: childEnv,
+    });
+  } catch (error) {
+    stopUpdateMonitor();
+    cleanupEphemeralUpdateFiles(updateStatePath, updateRequestPath);
+    logger.error(`MoonDesk failed to start: ${error.message}`);
+    return { code: 1, signal: null };
+  }
+
+  stopUpdateMonitor();
+  cleanupEphemeralUpdateFiles(updateStatePath, null);
+
+  if (result.signal) {
+    cleanupEphemeralUpdateFiles(null, updateRequestPath);
+    return result;
+  }
+
+  if (result.code !== UPDATE_EXIT_CODE) {
+    cleanupEphemeralUpdateFiles(null, updateRequestPath);
+    return { code: result.code ?? 1, signal: null };
+  }
+
+  if (!selfUpdateEnabled || !updateRequestPath) {
+    logger.error("MoonDesk requested an update restart, but in-app self-update is unavailable for this launch.");
+    return { code: 1, signal: null };
+  }
+
+  const request = readUpdateRequestImpl(updateRequestPath);
+  if (!request) {
+    logger.error(
+      "MoonDesk requested an update restart, but its validated update request was missing or invalid.",
+    );
+    return { code: 1, signal: null };
+  }
 
-  child.on("exit", (code, signal) => {
-    if (signal) {
-      process.kill(process.pid, signal);
-      return;
+  logger.log(`Updating MoonDesk ${request.currentVersion} -> ${request.targetVersion}...`);
+  let releaseUpdateLock = null;
+  let restartVersion = request.targetVersion;
+  try {
+    releaseUpdateLock = await acquireUpdateLockImpl({
+      cwd: originalCwd,
+      env: baseEnv,
+    });
+
+    const alreadyInstalled = installedWrapperVersionImpl();
+    const comparison = compareStableVersions(alreadyInstalled, request.targetVersion);
+    if (comparison < 0) {
+      await installExactVersionImpl(request.targetVersion, {
+        cwd: originalCwd,
+        env: baseEnv,
+      });
+      verifyInstalledWrapperVersionImpl(request.targetVersion);
+    } else if (comparison === 0) {
+      logger.log(`MoonDesk ${request.targetVersion} was already installed by another process.`);
+    } else {
+      restartVersion = alreadyInstalled;
+      logger.log(
+        `MoonDesk ${alreadyInstalled} is already installed, so the updater will not downgrade it to ${request.targetVersion}.`,
+      );
     }
-    process.exit(code ?? 1);
-  });
+  } catch (error) {
+    logger.error(`MoonDesk update failed: ${error.message}`);
+    logger.error(
+      `Run 'npm install -g moondesk@${request.targetVersion}' manually to retry this exact version.`,
+    );
+    return { code: 1, signal: null };
+  } finally {
+    try {
+      releaseUpdateLock?.();
+    } catch (error) {
+      logger.warn?.(`MoonDesk could not remove its npm update lock yet: ${error.message}`);
+    }
+  }
+
+  logger.log(`MoonDesk ${restartVersion} is installed. Restarting...`);
+  try {
+    return await restartUpdatedWrapperImpl(wrapperPath, originalArgs, {
+      cwd: originalCwd,
+      env: baseEnv,
+    });
+  } catch (error) {
+    logger.error(`MoonDesk updated successfully but could not restart automatically: ${error.message}`);
+    logger.error("Run 'moondesk' again to start the updated version.");
+    return { code: 1, signal: null };
+  }
+}
+
+function finish(result) {
+  if (result.signal) {
+    try {
+      process.kill(process.pid, result.signal);
+    } catch (error) {
+      console.error(`MoonDesk could not propagate ${result.signal}: ${error.message}`);
+      process.exitCode = 1;
+    }
+    return;
+  }
+  process.exitCode = result.code ?? 1;
+}
+
+if (require.main === module) {
+  orchestrate()
+    .then(finish)
+    .catch((error) => {
+      console.error(`MoonDesk failed to start: ${error.message}`);
+      process.exitCode = 1;
+    });
 }
 
-main().catch((error) => {
-  console.error(`MoonDesk failed to start: ${error.message}`);
-  process.exit(1);
-});
+module.exports = {
+  cleanManagedUpdateEnv,
+  cleanupEphemeralUpdateFiles,
+  orchestrate,
+  runNative,
+};

package/npm/update-manager.js

@@ -0,0 +1,563 @@
+#!/usr/bin/env node
+
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { spawn } = require("node:child_process");
+
+const packageRoot = path.resolve(__dirname, "..");
+const packageJsonPath = path.join(packageRoot, "package.json");
+const packageJson = require(packageJsonPath);
+const currentVersion = packageJson.version;
+
+const UPDATE_EXIT_CODE = 75;
+const UPDATE_STATE_SCHEMA_VERSION = 1;
+const UPDATE_REQUEST_SCHEMA_VERSION = 1;
+const REGISTRY_LATEST_URL = "https://registry.npmjs.org/moondesk/latest";
+const UPDATE_CHECK_INTERVAL_MS = 15 * 60_000;
+const UPDATE_CHECK_TIMEOUT_MS = 15_000;
+const MAX_UPDATE_METADATA_BYTES = 64 * 1024;
+const MAX_UPDATE_REQUEST_BYTES = 16 * 1024;
+const MAX_NPM_ROOT_BYTES = 16 * 1024;
+const NPM_ROOT_TIMEOUT_MS = 10_000;
+const UPDATE_LOCK_WAIT_MS = 60_000;
+const UPDATE_LOCK_POLL_MS = 200;
+
+function parseStableVersion(input) {
+  if (typeof input !== "string") {
+    return null;
+  }
+  const match = input.match(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/);
+  if (!match) {
+    return null;
+  }
+  return match.slice(1).map((part) => BigInt(part));
+}
+
+function compareStableVersions(left, right) {
+  const a = parseStableVersion(left);
+  const b = parseStableVersion(right);
+  if (!a || !b) {
+    throw new Error(`MoonDesk update versions must be stable semantic versions: ${left} vs ${right}`);
+  }
+  for (let index = 0; index < 3; index += 1) {
+    if (a[index] < b[index]) return -1;
+    if (a[index] > b[index]) return 1;
+  }
+  return 0;
+}
+
+function updateRootDir() {
+  return path.join(os.homedir(), ".moondesk", "updates");
+}
+
+function currentUpdateDir() {
+  return path.join(updateRootDir(), `v${currentVersion}`);
+}
+
+function createUpdateStatePath() {
+  const dir = path.join(currentUpdateDir(), "state");
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  return path.join(dir, `${process.pid}-${crypto.randomBytes(12).toString("hex")}.json`);
+}
+
+function cleanupOldUpdateVersions(options = {}) {
+  const root = options.root ?? updateRootDir();
+  const currentTag = options.currentTag ?? `v${currentVersion}`;
+  const currentVersionText = currentTag.startsWith("v") ? currentTag.slice(1) : currentTag;
+  const currentParts = parseStableVersion(currentVersionText);
+  if (!currentParts) {
+    return { removed: [], skipped: [] };
+  }
+
+  const removed = [];
+  const skipped = [];
+  let entries;
+  try {
+    entries = fs.readdirSync(root, { withFileTypes: true });
+  } catch (error) {
+    if (error.code === "ENOENT") return { removed, skipped };
+    throw error;
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory() || !entry.name.startsWith("v")) continue;
+    const candidate = entry.name.slice(1);
+    const candidateParts = parseStableVersion(candidate);
+    if (!candidateParts || compareStableVersions(candidate, currentVersionText) >= 0) continue;
+    try {
+      fs.rmSync(path.join(root, entry.name), {
+        recursive: true,
+        force: true,
+        maxRetries: 2,
+        retryDelay: 100,
+      });
+      removed.push(entry.name);
+    } catch {
+      skipped.push(entry.name);
+    }
+  }
+  return { removed, skipped };
+}
+
+function updateRequestDir() {
+  return path.join(currentUpdateDir(), "requests");
+}
+
+function createUpdateRequestPath() {
+  const dir = updateRequestDir();
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  return path.join(dir, `${process.pid}-${crypto.randomBytes(12).toString("hex")}.json`);
+}
+
+function normalizePathForCompare(value, platform = process.platform) {
+  const resolved = path.resolve(value);
+  let canonical = resolved;
+  try {
+    canonical = fs.realpathSync.native(resolved);
+  } catch {
+    // The expected global package path may not exist in unit tests.
+  }
+  return platform === "win32" ? canonical.toLowerCase() : canonical;
+}
+
+function resolveGlobalNpmRoot(options = {}) {
+  const spawnImpl = options.spawnImpl ?? spawn;
+  const platform = options.platform ?? process.platform;
+  const command = npmExecutable(platform);
+  const env = options.env ?? process.env;
+  const externalSignal = options.signal;
+
+  return new Promise((resolve, reject) => {
+    const child = spawnImpl(command, ["root", "--global"], {
+      cwd: options.cwd ?? process.cwd(),
+      env,
+      stdio: ["ignore", "pipe", "ignore"],
+      shell: platform === "win32",
+      windowsHide: true,
+    });
+
+    let settled = false;
+    let timer = null;
+    let abortHandler = null;
+    let output = Buffer.alloc(0);
+    const finish = (error, value) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      if (abortHandler) externalSignal?.removeEventListener("abort", abortHandler);
+      if (error) reject(error);
+      else resolve(value);
+    };
+
+    abortHandler = () => {
+      child.kill?.();
+      finish(new Error("npm root --global was aborted"));
+    };
+    if (externalSignal?.aborted) {
+      abortHandler();
+      return;
+    }
+    externalSignal?.addEventListener("abort", abortHandler, { once: true });
+
+    timer = setTimeout(() => {
+      child.kill?.();
+      finish(new Error("npm root --global timed out"));
+    }, NPM_ROOT_TIMEOUT_MS);
+    timer.unref?.();
+
+    child.once("error", (error) => finish(error));
+    child.stdout?.on("data", (chunk) => {
+      if (settled) return;
+      output = Buffer.concat([output, Buffer.from(chunk)]);
+      if (output.length > MAX_NPM_ROOT_BYTES) {
+        child.kill?.();
+        finish(new Error("npm root --global returned too much output"));
+      }
+    });
+    child.once("exit", (code, signal) => {
+      if (settled) return;
+      if (signal) {
+        finish(new Error(`npm root --global was terminated by ${signal}`));
+        return;
+      }
+      if (code !== 0) {
+        finish(new Error(`npm root --global exited with code ${code ?? "unknown"}`));
+        return;
+      }
+      const root = output.toString("utf8").trim();
+      if (!root) {
+        finish(new Error("npm root --global returned an empty path"));
+        return;
+      }
+      finish(null, root);
+    });
+  });
+}
+
+async function isGlobalPackageInstall(options = {}) {
+  const root = await resolveGlobalNpmRoot(options);
+  const platform = options.platform ?? process.platform;
+  const actualRoot = options.packageRoot ?? packageRoot;
+  const expectedRoot = path.join(root, "moondesk");
+  return normalizePathForCompare(actualRoot, platform) === normalizePathForCompare(expectedRoot, platform);
+}
+
+function replaceFile(tempPath, destinationPath, platform = process.platform) {
+  try {
+    fs.renameSync(tempPath, destinationPath);
+    return;
+  } catch (error) {
+    const replaceConflict = ["EEXIST", "EPERM", "EACCES"].includes(error.code);
+    if (platform !== "win32" || !replaceConflict) {
+      throw error;
+    }
+  }
+
+  // Windows can reject rename-over-existing-file while another process briefly
+  // has the destination open. The TUI treats a missing state file as "no update",
+  // so a tiny replacement gap is safer than failing MoonDesk startup.
+  fs.rmSync(destinationPath, { force: true });
+  fs.renameSync(tempPath, destinationPath);
+}
+
+function atomicWriteJson(filePath, value, options = {}) {
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const temp = `${filePath}.tmp-${process.pid}-${crypto.randomBytes(8).toString("hex")}`;
+  try {
+    fs.writeFileSync(temp, `${JSON.stringify(value)}\n`, { mode: 0o600 });
+    replaceFile(temp, filePath, options.platform ?? process.platform);
+  } finally {
+    fs.rmSync(temp, { force: true });
+  }
+}
+
+async function fetchJsonLimited(fetchImpl, url, externalSignal) {
+  const controller = new AbortController();
+  const abortFromParent = () => controller.abort();
+  if (externalSignal) {
+    if (externalSignal.aborted) {
+      controller.abort();
+    } else {
+      externalSignal.addEventListener("abort", abortFromParent, { once: true });
+    }
+  }
+  const timeout = setTimeout(() => controller.abort(), UPDATE_CHECK_TIMEOUT_MS);
+  timeout.unref?.();
+
+  try {
+    const response = await fetchImpl(url, {
+      headers: {
+        Accept: "application/json",
+        "User-Agent": `moondesk-npm/${currentVersion}`,
+      },
+      signal: controller.signal,
+    });
+    if (!response.ok) {
+      throw new Error(`${url} returned HTTP ${response.status}`);
+    }
+    const contentLength = Number(response.headers.get("content-length"));
+    if (Number.isFinite(contentLength) && contentLength > MAX_UPDATE_METADATA_BYTES) {
+      controller.abort();
+      throw new Error(`MoonDesk update metadata is unexpectedly large (${contentLength} bytes)`);
+    }
+    if (!response.body || typeof response.body[Symbol.asyncIterator] !== "function") {
+      throw new Error("MoonDesk update metadata response did not include a readable body");
+    }
+
+    const chunks = [];
+    let totalBytes = 0;
+    for await (const chunk of response.body) {
+      const buffer = Buffer.from(chunk);
+      totalBytes += buffer.length;
+      if (totalBytes > MAX_UPDATE_METADATA_BYTES) {
+        controller.abort();
+        throw new Error("MoonDesk update metadata exceeded the download limit");
+      }
+      chunks.push(buffer);
+    }
+    return JSON.parse(Buffer.concat(chunks, totalBytes).toString("utf8"));
+  } finally {
+    clearTimeout(timeout);
+    externalSignal?.removeEventListener("abort", abortFromParent);
+  }
+}
+
+async function checkForUpdate(options = {}) {
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+  const statePath = options.statePath ?? createUpdateStatePath();
+  const registryUrl = options.registryUrl ?? REGISTRY_LATEST_URL;
+  const managedInstall = options.managedInstall === true;
+  if (typeof fetchImpl !== "function") {
+    return null;
+  }
+
+  const metadata = await fetchJsonLimited(fetchImpl, registryUrl, options.signal);
+  const latestVersion = metadata?.version;
+  if (metadata?.name !== "moondesk") {
+    throw new Error(`npm returned unexpected package metadata for ${String(metadata?.name)}`);
+  }
+  if (!parseStableVersion(latestVersion)) {
+    throw new Error(`npm returned an invalid MoonDesk version: ${String(latestVersion)}`);
+  }
+  if (typeof metadata?.dist?.integrity !== "string" || !metadata.dist.integrity.startsWith("sha512-")) {
+    throw new Error("npm returned MoonDesk metadata without a sha512 package integrity value");
+  }
+
+  const available = managedInstall && compareStableVersions(latestVersion, currentVersion) > 0;
+  const state = {
+    schemaVersion: UPDATE_STATE_SCHEMA_VERSION,
+    packageName: "moondesk",
+    currentVersion,
+    latestVersion,
+    managedInstall,
+    available,
+    checkedAt: new Date().toISOString(),
+  };
+  atomicWriteJson(statePath, state, options);
+  return state;
+}
+
+function startUpdateMonitor(options = {}) {
+  const intervalMs = options.intervalMs ?? UPDATE_CHECK_INTERVAL_MS;
+  const statePath = options.statePath ?? createUpdateStatePath();
+  const globalInstallCheckImpl = options.isGlobalPackageInstallImpl ?? isGlobalPackageInstall;
+  let managedInstall = null;
+  let stopped = false;
+  let checking = false;
+  let timer = null;
+  let controller = null;
+
+  const run = async () => {
+    if (stopped || checking) return;
+    checking = true;
+    controller = new AbortController();
+    try {
+      if (managedInstall === null) {
+        managedInstall = await globalInstallCheckImpl({ ...options, signal: controller.signal });
+      }
+      if (!managedInstall || stopped) {
+        fs.rmSync(statePath, { force: true });
+        return;
+      }
+      await checkForUpdate({
+        ...options,
+        statePath,
+        managedInstall: true,
+        signal: controller.signal,
+      });
+    } catch {
+      // Update checks are optional. Offline/npm/registry failures must never affect MoonDesk startup.
+    } finally {
+      if (stopped) {
+        try {
+          fs.rmSync(statePath, { force: true });
+        } catch {
+          // Removing ephemeral update state must never fail MoonDesk.
+        }
+      }
+      controller = null;
+      checking = false;
+    }
+  };
+
+  void run();
+  timer = setInterval(() => void run(), intervalMs);
+  timer.unref?.();
+
+  return () => {
+    stopped = true;
+    controller?.abort();
+    if (timer) clearInterval(timer);
+  };
+}
+
+function readUpdateRequest(requestPath) {
+  let parsed;
+  try {
+    const stat = fs.statSync(requestPath);
+    if (!stat.isFile() || stat.size <= 0 || stat.size > MAX_UPDATE_REQUEST_BYTES) {
+      return null;
+    }
+    parsed = JSON.parse(fs.readFileSync(requestPath, "utf8"));
+  } catch {
+    return null;
+  } finally {
+    fs.rmSync(requestPath, { force: true });
+  }
+
+  if (
+    parsed?.schemaVersion !== UPDATE_REQUEST_SCHEMA_VERSION ||
+    parsed.currentVersion !== currentVersion ||
+    !parseStableVersion(parsed.targetVersion) ||
+    compareStableVersions(parsed.targetVersion, currentVersion) <= 0
+  ) {
+    return null;
+  }
+  return parsed;
+}
+
+function updateLockPath() {
+  return path.join(updateRootDir(), "npm-update.lock");
+}
+
+function lockOwnerIsAlive(lockPath) {
+  try {
+    const payload = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+    const pid = Number(payload?.pid);
+    if (!Number.isSafeInteger(pid) || pid <= 0) return false;
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === "EPERM";
+  }
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function acquireUpdateLock(options = {}) {
+  const lockPath = options.lockPath ?? updateLockPath();
+  const waitMs = options.waitMs ?? UPDATE_LOCK_WAIT_MS;
+  const pollMs = options.pollMs ?? UPDATE_LOCK_POLL_MS;
+  fs.mkdirSync(path.dirname(lockPath), { recursive: true, mode: 0o700 });
+  const deadline = Date.now() + waitMs;
+
+  while (true) {
+    try {
+      const fd = fs.openSync(lockPath, "wx", 0o600);
+      try {
+        fs.writeFileSync(
+          fd,
+          `${JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() })}\n`,
+        );
+        fs.fsyncSync(fd);
+      } finally {
+        fs.closeSync(fd);
+      }
+      let released = false;
+      return () => {
+        if (released) return;
+        released = true;
+        fs.rmSync(lockPath, { force: true });
+      };
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      if (!lockOwnerIsAlive(lockPath)) {
+        fs.rmSync(lockPath, { force: true });
+        continue;
+      }
+      if (Date.now() >= deadline) {
+        throw new Error("another MoonDesk process is still updating the global npm package");
+      }
+      await sleep(pollMs);
+    }
+  }
+}
+
+function installedWrapperVersion(options = {}) {
+  const targetPackageJsonPath = options.packageJsonPath ?? packageJsonPath;
+  let installed;
+  try {
+    installed = JSON.parse(fs.readFileSync(targetPackageJsonPath, "utf8"));
+  } catch (error) {
+    throw new Error(`could not read installed MoonDesk package metadata: ${error.message}`);
+  }
+  if (installed?.name !== "moondesk" || !parseStableVersion(installed.version)) {
+    throw new Error(
+      `installed package metadata is not a stable MoonDesk release: ${String(installed?.name)}@${String(installed?.version)}`,
+    );
+  }
+  return installed.version;
+}
+
+function npmExecutable(platform = process.platform) {
+  return platform === "win32" ? "npm.cmd" : "npm";
+}
+
+function installExactVersion(targetVersion, options = {}) {
+  if (!parseStableVersion(targetVersion) || compareStableVersions(targetVersion, currentVersion) <= 0) {
+    return Promise.reject(new Error(`Refusing invalid MoonDesk update target ${targetVersion}`));
+  }
+
+  const spawnImpl = options.spawnImpl ?? spawn;
+  const platform = options.platform ?? process.platform;
+  const command = npmExecutable(platform);
+  const args = [
+    "install",
+    "--global",
+    `moondesk@${targetVersion}`,
+    "--ignore-scripts",
+    "--no-audit",
+    "--no-fund",
+  ];
+
+  return new Promise((resolve, reject) => {
+    const child = spawnImpl(command, args, {
+      cwd: options.cwd ?? process.cwd(),
+      env: options.env ?? process.env,
+      stdio: "inherit",
+      shell: platform === "win32",
+    });
+    child.once("error", reject);
+    child.once("exit", (code, signal) => {
+      if (signal) {
+        reject(new Error(`npm update was terminated by ${signal}`));
+      } else if (code !== 0) {
+        reject(new Error(`npm install exited with code ${code ?? "unknown"}`));
+      } else {
+        resolve();
+      }
+    });
+  });
+}
+
+function verifyInstalledWrapperVersion(targetVersion, options = {}) {
+  if (!parseStableVersion(targetVersion)) {
+    throw new Error(`Refusing invalid MoonDesk verification target ${targetVersion}`);
+  }
+  const installedVersion = installedWrapperVersion(options);
+  if (installedVersion !== targetVersion) {
+    throw new Error(
+      `npm reported success but installed moondesk@${installedVersion} instead of moondesk@${targetVersion}`,
+    );
+  }
+  return true;
+}
+
+function restartUpdatedWrapper(wrapperPath, args, options = {}) {
+  const spawnImpl = options.spawnImpl ?? spawn;
+  return new Promise((resolve, reject) => {
+    const child = spawnImpl(process.execPath, [wrapperPath, ...args], {
+      cwd: options.cwd ?? process.cwd(),
+      env: options.env ?? process.env,
+      stdio: "inherit",
+    });
+    child.once("error", reject);
+    child.once("exit", (code, signal) => resolve({ code: code ?? 1, signal }));
+  });
+}
+
+module.exports = {
+  UPDATE_EXIT_CODE,
+  acquireUpdateLock,
+  atomicWriteJson,
+  checkForUpdate,
+  cleanupOldUpdateVersions,
+  compareStableVersions,
+  createUpdateRequestPath,
+  createUpdateStatePath,
+  currentVersion,
+  installExactVersion,
+  installedWrapperVersion,
+  isGlobalPackageInstall,
+  parseStableVersion,
+  readUpdateRequest,
+  resolveGlobalNpmRoot,
+  restartUpdatedWrapper,
+  startUpdateMonitor,
+  verifyInstalledWrapperVersion,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moondesk",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "MoonDesk — use ChatGPT Chat as a local coding agent, by Shattermoon.",
   "author": "Shattermoon",
   "license": "MIT",
@@ -18,6 +18,7 @@
   "files": [
     "npm/moondesk.js",
     "npm/install-binary.js",
+    "npm/update-manager.js",
     "LICENSE",
     "README.md"
   ],