@vellumai/cli 0.5.15 → 0.5.16

package/src/lib/hatch-local.ts

@@ -0,0 +1,403 @@
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readlinkSync,
+  rmSync,
+  symlinkSync,
+  unlinkSync,
+  writeFileSync,
+  appendFileSync,
+  readFileSync,
+} from "fs";
+import { homedir } from "os";
+import { join } from "path";
+
+// Direct import — bun embeds this at compile time so it works in compiled binaries.
+import cliPkg from "../../package.json";
+
+import {
+  allocateLocalResources,
+  findAssistantByName,
+  loadAllAssistants,
+  saveAssistantEntry,
+  setActiveAssistant,
+  syncConfigToLockfile,
+} from "./assistant-config.js";
+import type {
+  AssistantEntry,
+  LocalInstanceResources,
+} from "./assistant-config.js";
+import type { Species } from "./constants.js";
+import { writeInitialConfig } from "./config-utils.js";
+import {
+  generateLocalSigningKey,
+  startLocalDaemon,
+  startGateway,
+  stopLocalProcesses,
+} from "./local.js";
+import { maybeStartNgrokTunnel } from "./ngrok.js";
+import { httpHealthCheck } from "./http-client.js";
+import { detectOrphanedProcesses } from "./orphan-detection.js";
+import { isProcessAlive, stopProcess } from "./process.js";
+import { generateInstanceName } from "./random-name.js";
+import { leaseGuardianToken } from "./guardian-token.js";
+import { archiveLogFile, resetLogFile } from "./xdg-log.js";
+import { emitProgress } from "./desktop-progress.js";
+
+const IS_DESKTOP = !!process.env.VELLUM_DESKTOP_APP;
+
+function desktopLog(msg: string): void {
+  process.stdout.write(msg + "\n");
+}
+
+/**
+ * Attempts to place a symlink at the given path pointing to cliBinary.
+ * Returns true if the symlink was created (or already correct), false on failure.
+ */
+function trySymlink(cliBinary: string, symlinkPath: string): boolean {
+  try {
+    // Use lstatSync (not existsSync) to detect dangling symlinks —
+    // existsSync follows symlinks and returns false for broken links.
+    try {
+      const stats = lstatSync(symlinkPath);
+      if (!stats.isSymbolicLink()) {
+        // Real file — don't overwrite (developer's local install)
+        return false;
+      }
+      // Already a symlink — skip if it already points to our binary
+      const dest = readlinkSync(symlinkPath);
+      if (dest === cliBinary) return true;
+      // Stale or dangling symlink — remove before creating new one
+      unlinkSync(symlinkPath);
+    } catch (e) {
+      if ((e as NodeJS.ErrnoException)?.code !== "ENOENT") return false;
+      // Path doesn't exist — proceed to create symlink
+    }
+
+    const dir = join(symlinkPath, "..");
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+    symlinkSync(cliBinary, symlinkPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Ensures ~/.local/bin is present in the user's shell profile so that
+ * symlinks placed there are on PATH in new terminal sessions.
+ */
+function ensureLocalBinInShellProfile(localBinDir: string): void {
+  const shell = process.env.SHELL ?? "";
+  const home = homedir();
+  // Determine the appropriate shell profile to modify
+  const profilePath = shell.endsWith("/zsh")
+    ? join(home, ".zshrc")
+    : shell.endsWith("/bash")
+      ? join(home, ".bash_profile")
+      : null;
+  if (!profilePath) return;
+
+  try {
+    const contents = existsSync(profilePath)
+      ? readFileSync(profilePath, "utf-8")
+      : "";
+    // Check if ~/.local/bin is already referenced in PATH exports
+    if (contents.includes(localBinDir)) return;
+    const line = `\nexport PATH="${localBinDir}:\$PATH"\n`;
+    appendFileSync(profilePath, line);
+    console.log(`   Added ${localBinDir} to ${profilePath}`);
+  } catch {
+    // Not critical — user can add it manually
+  }
+}
+
+function installCLISymlink(): void {
+  const cliBinary = process.execPath;
+  if (!cliBinary || !existsSync(cliBinary)) return;
+
+  // Preferred location — works on most Macs where /usr/local/bin exists
+  const preferredPath = "/usr/local/bin/vellum";
+  if (trySymlink(cliBinary, preferredPath)) {
+    console.log(`   Symlinked ${preferredPath} → ${cliBinary}`);
+    return;
+  }
+
+  // Fallback — use ~/.local/bin which is user-writable and doesn't need root.
+  // On some Macs /usr/local doesn't exist and creating it requires admin privileges.
+  const localBinDir = join(homedir(), ".local", "bin");
+  const fallbackPath = join(localBinDir, "vellum");
+  if (trySymlink(cliBinary, fallbackPath)) {
+    console.log(`   Symlinked ${fallbackPath} → ${cliBinary}`);
+    ensureLocalBinInShellProfile(localBinDir);
+    return;
+  }
+
+  console.log(
+    `   ⚠ Could not create symlink for vellum CLI (tried ${preferredPath} and ${fallbackPath})`,
+  );
+}
+
+export async function hatchLocal(
+  species: Species,
+  name: string | null,
+  restart: boolean = false,
+  watch: boolean = false,
+  keepAlive: boolean = false,
+  configValues: Record<string, string> = {},
+): Promise<void> {
+  if (restart && !name && !process.env.VELLUM_ASSISTANT_NAME) {
+    console.error(
+      "Error: Cannot restart without a known assistant ID. Provide --name or ensure VELLUM_ASSISTANT_NAME is set.",
+    );
+    process.exit(1);
+  }
+
+  const instanceName = generateInstanceName(
+    species,
+    name ?? process.env.VELLUM_ASSISTANT_NAME,
+  );
+
+  emitProgress(1, 7, "Preparing workspace...");
+
+  // Clean up stale local state: if daemon/gateway processes are running but
+  // the lock file has no entries AND the daemon is not healthy, stop them
+  // before starting fresh. A healthy daemon should be reused, not killed —
+  // it may have been started intentionally via `vellum wake`.
+  const vellumDir = join(homedir(), ".vellum");
+  const existingAssistants = loadAllAssistants();
+  const localAssistants = existingAssistants.filter((a) => a.cloud === "local");
+  if (localAssistants.length === 0) {
+    const daemonPid = isProcessAlive(join(vellumDir, "vellum.pid"));
+    const gatewayPid = isProcessAlive(join(vellumDir, "gateway.pid"));
+    if (daemonPid.alive || gatewayPid.alive) {
+      // Check if the daemon is actually healthy before killing it.
+      // Default port 7821 is used when there's no lockfile entry.
+      const defaultPort = parseInt(process.env.RUNTIME_HTTP_PORT || "7821", 10);
+      const healthy = await httpHealthCheck(defaultPort);
+      if (!healthy) {
+        console.log(
+          "🧹 Cleaning up stale local processes (no lock file entry)...\n",
+        );
+        await stopLocalProcesses();
+      }
+    }
+  }
+
+  // On desktop, scan the process table for orphaned vellum processes that
+  // are not tracked by any PID file or lock file entry and kill them before
+  // starting new ones. This prevents resource leaks when the desktop app
+  // crashes or is force-quit without a clean shutdown.
+  //
+  // Skip orphan cleanup if the daemon is already healthy on the expected port
+  // — those processes are intentional (e.g. started via `vellum wake`) and
+  // startLocalDaemon() will reuse them.
+  if (IS_DESKTOP) {
+    const existingResources = findAssistantByName(instanceName);
+    const expectedPort =
+      existingResources?.cloud === "local" && existingResources.resources
+        ? existingResources.resources.daemonPort
+        : undefined;
+    const daemonAlreadyHealthy = expectedPort
+      ? await httpHealthCheck(expectedPort)
+      : false;
+
+    if (!daemonAlreadyHealthy) {
+      const orphans = await detectOrphanedProcesses();
+      if (orphans.length > 0) {
+        desktopLog(
+          `🧹 Found ${orphans.length} orphaned process${orphans.length === 1 ? "" : "es"} — cleaning up...`,
+        );
+        for (const orphan of orphans) {
+          await stopProcess(
+            parseInt(orphan.pid, 10),
+            `${orphan.name} (PID ${orphan.pid})`,
+          );
+        }
+      }
+    }
+  }
+
+  emitProgress(2, 7, "Allocating resources...");
+
+  // Reuse existing resources if re-hatching with --name that matches a known
+  // local assistant, otherwise allocate fresh per-instance ports and directories.
+  let resources: LocalInstanceResources;
+  const existingEntry = findAssistantByName(instanceName);
+  if (existingEntry?.cloud === "local" && existingEntry.resources) {
+    resources = existingEntry.resources;
+  } else {
+    resources = await allocateLocalResources(instanceName);
+  }
+
+  // Clean up stale workspace data: if the workspace directory already exists for
+  // this instance but no local lockfile entry owns it, a previous retire failed
+  // to archive it (or a managed-only retire left local data behind). Remove the
+  // workspace subtree so the new assistant starts fresh — but preserve the rest
+  // of .vellum (e.g. protected/, credentials) which may be shared.
+  if (
+    !existingEntry ||
+    (existingEntry.cloud != null && existingEntry.cloud !== "local")
+  ) {
+    const instanceWorkspaceDir = join(
+      resources.instanceDir,
+      ".vellum",
+      "workspace",
+    );
+    if (existsSync(instanceWorkspaceDir)) {
+      const ownedByOther = loadAllAssistants().some((a) => {
+        if ((a.cloud != null && a.cloud !== "local") || !a.resources)
+          return false;
+        return (
+          join(a.resources.instanceDir, ".vellum", "workspace") ===
+          instanceWorkspaceDir
+        );
+      });
+      if (!ownedByOther) {
+        console.log(
+          `🧹 Removing stale workspace at ${instanceWorkspaceDir} (not owned by any assistant)...\n`,
+        );
+        rmSync(instanceWorkspaceDir, { recursive: true, force: true });
+      }
+    }
+  }
+
+  const logsDir = join(
+    resources.instanceDir,
+    ".vellum",
+    "workspace",
+    "data",
+    "logs",
+  );
+  archiveLogFile("hatch.log", logsDir);
+  resetLogFile("hatch.log");
+
+  console.log(`🥚 Hatching local assistant: ${instanceName}`);
+  console.log(`   Species: ${species}`);
+  console.log("");
+
+  if (!process.env.APP_VERSION) {
+    process.env.APP_VERSION = cliPkg.version;
+  }
+
+  emitProgress(3, 7, "Writing configuration...");
+  const defaultWorkspaceConfigPath = writeInitialConfig(configValues);
+
+  emitProgress(4, 7, "Starting assistant...");
+  const signingKey = generateLocalSigningKey();
+  await startLocalDaemon(watch, resources, {
+    defaultWorkspaceConfigPath,
+    signingKey,
+  });
+
+  emitProgress(5, 7, "Starting gateway...");
+  let runtimeUrl = `http://127.0.0.1:${resources.gatewayPort}`;
+  try {
+    runtimeUrl = await startGateway(watch, resources, { signingKey });
+  } catch (error) {
+    // Gateway failed — stop the daemon we just started so we don't leave
+    // orphaned processes with no lock file entry.
+    console.error(
+      `\n❌ Gateway startup failed — stopping assistant to avoid orphaned processes.`,
+    );
+    await stopLocalProcesses(resources);
+    throw error;
+  }
+
+  // Lease a guardian token so the desktop app can import it on first launch
+  // instead of hitting /v1/guardian/init itself.
+  emitProgress(6, 7, "Securing connection...");
+  try {
+    await leaseGuardianToken(runtimeUrl, instanceName);
+  } catch (err) {
+    console.error(`⚠️  Guardian token lease failed: ${err}`);
+  }
+
+  // Auto-start ngrok if webhook integrations (e.g. Telegram, Twilio) are configured.
+  // Set BASE_DATA_DIR so ngrok reads the correct instance config.
+  const prevBaseDataDir = process.env.BASE_DATA_DIR;
+  process.env.BASE_DATA_DIR = resources.instanceDir;
+  const ngrokChild = await maybeStartNgrokTunnel(resources.gatewayPort);
+  if (ngrokChild?.pid) {
+    const ngrokPidFile = join(resources.instanceDir, ".vellum", "ngrok.pid");
+    writeFileSync(ngrokPidFile, String(ngrokChild.pid));
+  }
+  if (prevBaseDataDir !== undefined) {
+    process.env.BASE_DATA_DIR = prevBaseDataDir;
+  } else {
+    delete process.env.BASE_DATA_DIR;
+  }
+
+  const localEntry: AssistantEntry = {
+    assistantId: instanceName,
+    runtimeUrl,
+    localUrl: `http://127.0.0.1:${resources.gatewayPort}`,
+    cloud: "local",
+    species,
+    hatchedAt: new Date().toISOString(),
+    serviceGroupVersion: cliPkg.version ? `v${cliPkg.version}` : undefined,
+    resources: { ...resources, signingKey },
+  };
+  emitProgress(7, 7, "Saving configuration...");
+  if (!restart) {
+    saveAssistantEntry(localEntry);
+    setActiveAssistant(instanceName);
+    syncConfigToLockfile();
+
+    if (process.env.VELLUM_DESKTOP_APP) {
+      installCLISymlink();
+    }
+
+    console.log("");
+    console.log(`✅ Local assistant hatched!`);
+    console.log("");
+    console.log("Instance details:");
+    console.log(`  Name: ${instanceName}`);
+    console.log(`  Runtime: ${runtimeUrl}`);
+    console.log("");
+  }
+
+  if (keepAlive) {
+    const healthUrl = `http://127.0.0.1:${resources.gatewayPort}/healthz`;
+    const healthTarget = "Gateway";
+    const POLL_INTERVAL_MS = 5000;
+    const MAX_FAILURES = 3;
+    let consecutiveFailures = 0;
+
+    const shutdown = async (): Promise<void> => {
+      console.log("\nShutting down local processes...");
+      await stopLocalProcesses(resources);
+      process.exit(0);
+    };
+
+    process.on("SIGTERM", () => void shutdown());
+    process.on("SIGINT", () => void shutdown());
+
+    // Poll the health endpoint until it stops responding.
+    while (true) {
+      await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+      try {
+        const res = await fetch(healthUrl, {
+          signal: AbortSignal.timeout(3000),
+        });
+        if (res.ok) {
+          consecutiveFailures = 0;
+        } else {
+          consecutiveFailures++;
+        }
+      } catch {
+        consecutiveFailures++;
+      }
+      if (consecutiveFailures >= MAX_FAILURES) {
+        console.log(
+          `\n⚠️  ${healthTarget} stopped responding — shutting down.`,
+        );
+        await stopLocalProcesses(resources);
+        process.exit(1);
+      }
+    }
+  }
+}

package/src/lib/local.ts

@@ -474,108 +474,6 @@ function resolveGatewayDir(): string {
   }
 }
 
-function normalizeIngressUrl(value: unknown): string | undefined {
-  if (typeof value !== "string") return undefined;
-  const normalized = value.trim().replace(/\/+$/, "");
-  return normalized || undefined;
-}
-
-// ── Workspace config helpers ──
-
-function getWorkspaceConfigPath(instanceDir?: string): string {
-  const baseDataDir =
-    instanceDir ??
-    (process.env.BASE_DATA_DIR?.trim() || (process.env.HOME ?? homedir()));
-  return join(baseDataDir, ".vellum", "workspace", "config.json");
-}
-
-function loadWorkspaceConfig(instanceDir?: string): Record<string, unknown> {
-  const configPath = getWorkspaceConfigPath(instanceDir);
-  try {
-    if (!existsSync(configPath)) return {};
-    return JSON.parse(readFileSync(configPath, "utf-8")) as Record<
-      string,
-      unknown
-    >;
-  } catch {
-    return {};
-  }
-}
-
-function saveWorkspaceConfig(
-  config: Record<string, unknown>,
-  instanceDir?: string,
-): void {
-  const configPath = getWorkspaceConfigPath(instanceDir);
-  const dir = dirname(configPath);
-  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-  writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
-}
-
-/**
- * Write gateway operational settings to the workspace config file so the
- * gateway reads them at startup via its config.ts readWorkspaceConfig().
- */
-function writeGatewayConfig(
-  instanceDir?: string,
-  opts?: {
-    runtimeProxyEnabled?: boolean;
-    runtimeProxyRequireAuth?: boolean;
-    unmappedPolicy?: "reject" | "default";
-    defaultAssistantId?: string;
-    routingEntries?: Array<{
-      type: "conversation_id" | "actor_id";
-      key: string;
-      assistantId: string;
-    }>;
-  },
-): void {
-  const config = loadWorkspaceConfig(instanceDir);
-  const gateway = (config.gateway ?? {}) as Record<string, unknown>;
-
-  if (opts?.runtimeProxyEnabled !== undefined) {
-    gateway.runtimeProxyEnabled = opts.runtimeProxyEnabled;
-  }
-  if (opts?.runtimeProxyRequireAuth !== undefined) {
-    gateway.runtimeProxyRequireAuth = opts.runtimeProxyRequireAuth;
-  }
-  if (opts?.unmappedPolicy !== undefined) {
-    gateway.unmappedPolicy = opts.unmappedPolicy;
-  }
-  if (opts?.defaultAssistantId !== undefined) {
-    gateway.defaultAssistantId = opts.defaultAssistantId;
-  }
-  if (opts?.routingEntries !== undefined) {
-    gateway.routingEntries = opts.routingEntries;
-  }
-
-  config.gateway = gateway;
-  saveWorkspaceConfig(config, instanceDir);
-}
-
-function readWorkspaceIngressPublicBaseUrl(
-  instanceDir?: string,
-): string | undefined {
-  const baseDataDir =
-    instanceDir ??
-    (process.env.BASE_DATA_DIR?.trim() || (process.env.HOME ?? homedir()));
-  const workspaceConfigPath = join(
-    baseDataDir,
-    ".vellum",
-    "workspace",
-    "config.json",
-  );
-  try {
-    const raw = JSON.parse(
-      readFileSync(workspaceConfigPath, "utf-8"),
-    ) as Record<string, unknown>;
-    const ingress = raw.ingress as Record<string, unknown> | undefined;
-    return normalizeIngressUrl(ingress?.publicBaseUrl);
-  } catch {
-    return undefined;
-  }
-}
-
 /**
  * Check if the daemon is responsive by hitting its HTTP `/healthz` endpoint.
  * This replaces the socket-based `isSocketResponsive()` check.
@@ -973,6 +871,7 @@ export async function startLocalDaemon(
         "VELLUM_DEBUG",
         "VELLUM_DEV",
         "VELLUM_DESKTOP_APP",
+        "VELLUM_WORKSPACE_DIR",
       ]) {
         if (process.env[key]) {
           daemonEnv[key] = process.env[key]!;
@@ -1131,19 +1030,16 @@ export async function startGateway(
   const effectiveDaemonPort =
     resources?.daemonPort ?? Number(process.env.RUNTIME_HTTP_PORT || "7821");
 
-  // Write gateway operational settings to workspace config before starting
-  // the gateway process. The gateway reads these at startup from config.json.
-  writeGatewayConfig(resources?.instanceDir, {
-    runtimeProxyEnabled: true,
-    runtimeProxyRequireAuth: true,
-    unmappedPolicy: "default",
-    defaultAssistantId: "self",
-  });
-
   const gatewayEnv: Record<string, string> = {
     ...(process.env as Record<string, string>),
     RUNTIME_HTTP_PORT: String(effectiveDaemonPort),
     GATEWAY_PORT: String(effectiveGatewayPort),
+    // Pass gateway operational settings via env vars so the CLI does not
+    // need direct access to the workspace config file.
+    RUNTIME_PROXY_ENABLED: "true",
+    RUNTIME_PROXY_REQUIRE_AUTH: "true",
+    UNMAPPED_POLICY: "default",
+    DEFAULT_ASSISTANT_ID: "self",
     ...(options?.signingKey
       ? { ACTOR_TOKEN_SIGNING_KEY: options.signingKey }
       : {}),
@@ -1152,15 +1048,8 @@ export async function startGateway(
     // workspace config for this instance (mirrors the daemon env setup).
     ...(resources ? { BASE_DATA_DIR: resources.instanceDir } : {}),
   };
-  // The gateway reads the ingress URL from the workspace config file via
-  // ConfigFileCache — no env var passthrough needed. Log the resolved value
-  // for diagnostic visibility during startup.
-  const workspaceIngressPublicBaseUrl = readWorkspaceIngressPublicBaseUrl(
-    resources?.instanceDir,
-  );
-  const ingressPublicBaseUrl = workspaceIngressPublicBaseUrl ?? publicUrl;
-  if (ingressPublicBaseUrl) {
-    console.log(`   Ingress URL: ${ingressPublicBaseUrl}`);
+  if (publicUrl) {
+    console.log(`   Ingress URL: ${publicUrl}`);
   }
 
   let gateway;

package/src/lib/retire-local.ts

@@ -0,0 +1,124 @@
+import { spawn } from "child_process";
+import { existsSync, mkdirSync, renameSync, writeFileSync } from "fs";
+import { basename, dirname, join } from "path";
+
+import { getBaseDir, loadAllAssistants } from "./assistant-config.js";
+import type { AssistantEntry } from "./assistant-config.js";
+import {
+  stopOrphanedDaemonProcesses,
+  stopProcessByPidFile,
+} from "./process.js";
+import { getArchivePath, getMetadataPath } from "./retire-archive.js";
+
+export async function retireLocal(
+  name: string,
+  entry: AssistantEntry,
+): Promise<void> {
+  console.log("\u{1F5D1}\ufe0f  Stopping local assistant...\n");
+
+  if (!entry.resources) {
+    throw new Error(
+      `Local assistant '${name}' is missing resource configuration. Re-hatch to fix.`,
+    );
+  }
+  const resources = entry.resources;
+  const vellumDir = join(resources.instanceDir, ".vellum");
+
+  // Check whether another local assistant shares the same data directory.
+  const otherSharesDir = loadAllAssistants().some((other) => {
+    if (other.cloud !== "local") return false;
+    if (other.assistantId === name) return false;
+    if (!other.resources) return false;
+    const otherVellumDir = join(other.resources.instanceDir, ".vellum");
+    return otherVellumDir === vellumDir;
+  });
+
+  if (otherSharesDir) {
+    console.log(
+      `   Skipping process stop and archive — another local assistant shares ${vellumDir}.`,
+    );
+    console.log("\u2705 Local instance retired (config entry removed only).");
+    return;
+  }
+
+  const daemonPidFile = resources.pidFile;
+  const daemonStopped = await stopProcessByPidFile(daemonPidFile, "daemon");
+
+  // Stop gateway via PID file — use a longer timeout because the gateway has a
+  // drain window (5s) before it exits.
+  const gatewayPidFile = join(vellumDir, "gateway.pid");
+  await stopProcessByPidFile(gatewayPidFile, "gateway", undefined, 7000);
+
+  // Stop Qdrant — the daemon's graceful shutdown tries to stop it via
+  // qdrantManager.stop(), but if the daemon was SIGKILL'd (after 2s timeout)
+  // Qdrant may still be running as an orphan. Check both the current PID file
+  // location and the legacy location.
+  const qdrantPidFile = join(
+    vellumDir,
+    "workspace",
+    "data",
+    "qdrant",
+    "qdrant.pid",
+  );
+  const qdrantLegacyPidFile = join(vellumDir, "qdrant.pid");
+  await stopProcessByPidFile(qdrantPidFile, "qdrant", undefined, 5000);
+  await stopProcessByPidFile(qdrantLegacyPidFile, "qdrant", undefined, 5000);
+
+  // If the PID file didn't track a running daemon, scan for orphaned
+  // daemon processes that may have been started without writing a PID.
+  if (!daemonStopped) {
+    await stopOrphanedDaemonProcesses();
+  }
+
+  // For named instances (instanceDir differs from the base directory),
+  // archive and remove the entire instance directory. For the default
+  // instance, archive only the .vellum subdirectory.
+  const isNamedInstance = resources.instanceDir !== getBaseDir();
+  const dirToArchive = isNamedInstance ? resources.instanceDir : vellumDir;
+
+  // Move the data directory out of the way so the path is immediately available
+  // for the next hatch, then kick off the tar archive in the background.
+  const archivePath = getArchivePath(name);
+  const metadataPath = getMetadataPath(name);
+  const stagingDir = `${archivePath}.staging`;
+
+  if (!existsSync(dirToArchive)) {
+    console.log(
+      `   No data directory at ${dirToArchive} — nothing to archive.`,
+    );
+    console.log("\u2705 Local instance retired.");
+    return;
+  }
+
+  // Ensure the retired archive directory exists before attempting the rename
+  mkdirSync(dirname(stagingDir), { recursive: true });
+
+  try {
+    renameSync(dirToArchive, stagingDir);
+  } catch (err) {
+    // Re-throw so the caller (and the desktop app) knows the archive failed.
+    // If the rename fails, old workspace data stays in place and a subsequent
+    // hatch would inherit stale SOUL.md, IDENTITY.md, and memories.
+    throw new Error(
+      `Failed to archive ${dirToArchive}: ${err instanceof Error ? err.message : err}`,
+    );
+  }
+
+  writeFileSync(metadataPath, JSON.stringify(entry, null, 2) + "\n");
+
+  // Spawn tar + cleanup in the background and detach so the CLI can exit
+  // immediately. The staging directory is removed once the archive is written.
+  const tarCmd = [
+    `tar czf ${JSON.stringify(archivePath)} -C ${JSON.stringify(dirname(stagingDir))} ${JSON.stringify(basename(stagingDir))}`,
+    `rm -rf ${JSON.stringify(stagingDir)}`,
+  ].join(" && ");
+
+  const child = spawn("sh", ["-c", tarCmd], {
+    stdio: "ignore",
+    detached: true,
+  });
+  child.unref();
+
+  console.log(`📦 Archiving to ${archivePath} in the background.`);
+  console.log("\u2705 Local instance retired.");
+}