@akms/mcp 0.3.1 → 0.3.2

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to `@akms/mcp`.
 
+## [0.3.2] - 2026-10-26
+
+### Changed
+
+- Point Sync review instructions to its current menu and name the services retaining old connection entries, grouping only identical retained lists.
+- Separate runtime waits from failed changes in Register and Sync. Group retained connection names, count saved connections separately from service entries, and show semantic colors only on interactive terminals without NO_COLOR.
+- Offer unimported connections directly from Sync and compare both saved and external settings before resolving an individual entry during session migration. Wide terminals show versions side by side; narrow terminals keep wrapped values.
+- Preserve existing terminal symbols and keep status words visible when colors are disabled.
+- Document the upgrade path from 0.2.x, including pending runtimes, differing imported settings, reconnecting clients, rollback and registry migration.
+
 ## [0.3.1] - 2026-10-26
 
 ### Verification

package/README.md

@@ -48,6 +48,29 @@ akms-mcp sync
 
 Use `--help` for the command reference and `--version` for the launcher's version.
 
+## Upgrading from 0.2.x
+
+For clients with individual npx entries and no shared registry, start the current setup launcher:
+
+```sh
+npx -y --prefer-online @akms/mcp@latest
+```
+
+1. Open **Runtime**, select each MCP kind you use, and choose **Install AKMS runtime** or **Update runtime installation**.
+2. Open **Register**, select your AI services, then choose **Apply registration** and confirm the review. Matching existing connections are imported into the shared catalog, and their individual client entries are replaced by one `akms_<kind>` entry per service.
+3. Answer **Yes** to **Compare existing settings and choose which to share?** when versions differ, even if only their descriptions differ. Select the connection, choose **Use 1** or **Use 2**, keep the shared connection name to replace its old entries, and confirm **Import ... and apply it?**. If you defer this choice, use **Import existing connections** or reopen Register and Apply to return to the comparison.
+4. Run **Sync** if any saved changes remain unfinished.
+5. Restart or reconnect your AI clients to load the new entries. In Codex, start a new thread and archive the old threads whose servers you want to retire: each thread owns its MCP processes, and archiving stopped those processes in the isolated Codex 0.164.0 check.
+6. Call `db_catalog_status`, `ssh_catalog_status`, `wsl_catalog_status` or `s3_catalog_status` for each kind you use and check its loaded and skipped connections. Tools now include the connection prefix, such as `pg_alpha__db_query` or `ssh_dev__ssh_exec`.
+
+**If you registered first:** a missing-runtime result is a normal pending state. Updated setup labels this **Waiting for runtime**. Existing client entries stay in place while the runtime is missing. Install it from **Runtime**, then run **Sync** to finish applying the session entries and removing the old entries; installing the runtime alone does not finish that conversion.
+
+**Finish importing differences:** in 0.3.1, connections still awaiting import did not appear in Sync, even when only their descriptions differed. Finish the Register comparison or use **Import existing connections** to review them. Updated Sync screens show **Not yet imported** and offer **Import existing connections** on the same screen. Complete that import review even when the saved connections are already up to date.
+
+**Existing development registry:** if setup shows **Registry update available**, open **Migrate registry**, review the proposed changes and confirm them. See [Migrate an older registry](#migrate-an-older-registry).
+
+**Return to individual entries:** open **Runtime**, select the kind, choose **Switch back to per-connection entries**, then review and confirm. This restores the saved individual launch commands and credentials and removes the session entry after the replacements are verified; the registry stays version 2. Restart or reconnect clients after changing the layout.
+
 ## Shared registration
 
 ### Startup checks and updates

package/lib/cli.js

@@ -373,6 +373,8 @@ function createStyle(enabled) {
   return {
     accent: paint(36, 39),
     success: paint(32, 39),
+    warning: paint(33, 39),
+    error: paint(31, 39),
     dim: paint(2, 22),
     bold: paint(1, 22)
   };
@@ -789,7 +791,7 @@ var fieldName = (field) => {
   const names = { command: "Launch command", args: "Launch arguments", DB_HOST: "Host", SSH_HOST: "Host", DB_PORT: "Port", SSH_PORT: "Port", DB_NAME: "Database", DB_USER: "User", SSH_USER: "User", WSL_USER: "User", WSL_DISTRO: "Linux distribution", S3_BUCKET: "Bucket", S3_REGION: "Region", S3_PREFIX: "Key prefix" };
   return Object.hasOwn(names, key) ? names[key] : plainText(key);
 };
-function writeWrapped(prompter, text, indent = "", changed) {
+function writeWrapped(prompter, text, indent = "", changed, style) {
   const characters = Array.from(plainText(text));
   let line = indent;
   let width = displayWidth(indent);
@@ -804,7 +806,7 @@ function writeWrapped(prompter, text, indent = "", changed) {
     const size = displayWidth(character);
     if (width + size > prompter.width) {
       flush();
-      prompter.write(line + "\n");
+      prompter.write((style ? style(line) : line) + "\n");
       line = indent;
       width = displayWidth(indent);
     }
@@ -817,7 +819,7 @@ function writeWrapped(prompter, text, indent = "", changed) {
     width += size;
   }
   flush();
-  prompter.write(line + "\n");
+  prompter.write((style ? style(line) : line) + "\n");
 }
 function changedRange(values, index) {
   if (values.length !== 2 || values[0] === values[1]) return void 0;
@@ -839,6 +841,37 @@ function compareEntries(prompter, versions) {
     const key = field.replace(/^env\./, "");
     return versions.map(({ entry }) => field.startsWith("env.") && visibleField.test(key) ? Object.hasOwn(entry.env, key) ? plainText(entry.env[key]) || "(empty)" : "(not set)" : "(hidden)");
   });
+  if (versions.length === 2 && prompter.width >= 90) {
+    const width = Math.floor((prompter.width - 3) / 2);
+    const wrap = (value, changed) => {
+      const lines = [{ text: "", width: 0 }];
+      for (const [index, character] of Array.from(value).entries()) {
+        const size = displayWidth(character);
+        if (lines[lines.length - 1].width + size > width) lines.push({ text: "", width: 0 });
+        const line = lines[lines.length - 1];
+        line.text += changed && index >= changed[0] && index < changed[1] ? prompter.paint.accent(prompter.paint.bold(character)) : character;
+        line.width += size;
+      }
+      return lines;
+    };
+    const row = (left, right) => {
+      for (let line = 0; line < Math.max(left.length, right.length); line++) {
+        prompter.write(`${left[line]?.text ?? ""}${" ".repeat(width - (left[line]?.width ?? 0))} | ${right[line]?.text ?? ""}
+`);
+      }
+    };
+    prompter.write("\n");
+    row(wrap(`[1] ${plainText(versions[0].label)}`), wrap(`[2] ${plainText(versions[1].label)}`));
+    for (let field = 0; field < fields.length; field++) {
+      prompter.write(`
+${prompter.paint.dim(fieldName(fields[field]))}
+`);
+      row(wrap(values[field][0], changedRange(values[field], 0)), wrap(values[field][1], changedRange(values[field], 1)));
+    }
+    if (values.some((row2) => row2.includes("(hidden)"))) prompter.write(prompter.paint.dim("\nSecret values are hidden.\n"));
+    prompter.write("\n");
+    return;
+  }
   for (let index = 0; index < versions.length; index++) {
     prompter.write("\n");
     writeWrapped(prompter, `[${index + 1}] ${versions[index].label}`);
@@ -1045,10 +1078,10 @@ async function checkConnections(prompter, entries, check = checkStartup) {
     const missing = prefixes?.filter((prefix) => !covered.has(prefix)) ?? [];
     if (result.ok && missing.length) result = { ...result, ok: false, detail: `Missing connection tools: ${missing.map((prefix) => prefix.slice(0, -2)).join(", ")}. Review catalog status before reconnecting.` };
     const safe = (value) => [entry, ...maskEntries ?? []].reduce((text, source) => redactStartupText(text, source), value);
-    writeWrapped(prompter, safe(result.ok ? `OK ${name}: ${result.server}@${result.version}, ${result.tools} tools` : `FAILED ${name}: exit ${result.exitCode ?? "unavailable"}. ${result.detail ?? "Server failed to start."}`));
+    writeWrapped(prompter, safe(result.ok ? `OK ${name}: ${result.server}@${result.version}, ${result.tools} tools` : `FAILED ${name}: exit ${result.exitCode ?? "unavailable"}. ${result.detail ?? "Server failed to start."}`), "", void 0, result.ok ? prompter.paint.success : prompter.paint.error);
     if (!result.ok) {
       failed = true;
-      for (const line of result.stderr) writeWrapped(prompter, safe(line), "  ");
+      for (const line of result.stderr) writeWrapped(prompter, safe(line), "  ", void 0, prompter.paint.dim);
     }
   }
   if (failed) prompter.write("Settings remain saved. Fix failed startup checks before restarting or reconnecting your AI clients.\n");
@@ -1478,11 +1511,26 @@ var Registry = class {
   inspect() {
     return this.reconcile(this.read(), false);
   }
+  formatResults(results, prefix = "", paint, reviewHint) {
+    return formatResults(results, prefix, {
+      paint,
+      reviewHint,
+      connectionCount: Object.values(this.read().connections).filter((item) => item.entry).length
+    });
+  }
   reconcile(state, apply, kinds) {
     const results = [];
     const active = (kind) => Object.entries(state.connections).filter(([, item]) => item.kind === kind && item.entry);
     for (const kind of kinds ?? KINDS) if (this.isSessionMode(kind, state) && active(kind).length && !state.sessions?.[kind]) {
-      for (const client of state.clients) results.push({ client, name: sessionName(kind), status: "pending", detail: "Install this kind's runtime from Runtime, then run Sync. Existing client entries are kept." });
+      for (const client of state.clients) results.push({
+        client,
+        name: sessionName(kind),
+        kind,
+        connections: active(kind).map(([name]) => name),
+        status: "pending",
+        waitingFor: "runtime",
+        detail: "Install it from Runtime, then run Sync. Your existing entries keep working."
+      });
     }
     const work = [
       ...Object.entries(state.connections).filter(([, connection]) => !kinds || kinds.includes(connection.kind)).map(([name, connection]) => ({ name, connection, bundle: false })),
@@ -1498,7 +1546,15 @@ var Registry = class {
         const previous = connection.applied[client];
         if (!desired && !previous) continue;
         const target = this.targets.find((candidate) => candidate.id === client);
-        const report = (status, detail) => results.push({ client, name, status, detail });
+        const report = (status, detail, waitingFor) => results.push({
+          client,
+          name,
+          status,
+          detail,
+          kind: connection.kind,
+          connections: bundle ? active(connection.kind).map(([name2]) => name2) : [name],
+          ...waitingFor ? { waitingFor } : {}
+        });
         if (!target) {
           report("error", "Service adapter unavailable; use a newer package to retry.");
           continue;
@@ -1516,20 +1572,18 @@ var Registry = class {
             report("removed", "Removed");
           } else if (exists && (!actual || !previous || hash !== previous)) {
             report("conflict", actual && desired ? describeDifferences([desired, actual]) : actual ? "Changed outside AKMS; review before removing this entry." : "This name is used by another server type; choose another name.");
-          } else if (!apply) {
-            report("pending", desired ? "Needs applying" : "Needs removal");
           } else {
             if (!desired && state.clients.includes(client)) {
               if (!bundle && this.isSessionMode(connection.kind, state) && active(connection.kind).length) {
                 const session = state.sessions?.[connection.kind];
                 const replacement2 = entries[sessionName(connection.kind)];
                 if (!session || !replacement2 || entryHash(replacement2) !== entryHash(session.entry) || session.applied[client] !== entryHash(session.entry)) {
-                  report("pending", "Connection entry kept until the session server is applied.");
+                  report("pending", "Connection entry kept until the session server is applied.", "session");
                   continue;
                 }
               }
               if (bundle && !this.isSessionMode(connection.kind, state) && active(connection.kind).some(([connectionName, value]) => !entries[connectionName] || entryHash(entries[connectionName]) !== entryHash(value.entry))) {
-                report("pending", "Session entry kept until all connection entries are applied.");
+                report("pending", "Session entry kept until all connection entries are applied.", "connections");
                 continue;
               }
             }
@@ -1540,7 +1594,11 @@ var Registry = class {
               replacement = state.connections[replacement.replacement];
             }
             if (!desired && state.clients.includes(client) && !this.isSessionMode(connection.kind, state) && replacement && replacement.entry && replacement.applied[client] !== entryHash(replacement.entry)) {
-              report("pending", "Old name kept until the new name is applied.");
+              report("pending", "Old name kept until the new name is applied.", "rename");
+              continue;
+            }
+            if (!apply) {
+              report("pending", desired ? "Needs applying" : "Needs removal");
               continue;
             }
             const result = desired ? target.writeEntry(name, desired) : target.removeEntry(name);
@@ -1631,7 +1689,7 @@ var Registry = class {
     const registry = this;
     let snapshot;
     const expected = (name) => snapshot ? own(snapshot, name) ? entryHash(snapshot[name]) : null : void 0;
-    const saved = (results) => ({ status: "written", detail: formatResults(results, "Saved in the shared AKMS catalog.") });
+    const saved = (results) => ({ status: "written", detail: registry.formatResults(results, "Saved in the shared AKMS catalog.") });
     const prepare = (name, entry, oldName) => {
       if (!registry.read().clients.length) throw new RegistryError("Register at least one AI service before saving a connection.");
       const prior = snapshot && own(snapshot, oldName ?? name) ? snapshot[oldName ?? name] : void 0;
@@ -1660,30 +1718,58 @@ var Registry = class {
     };
   }
 };
-function formatResults(results, prefix = "") {
-  const lines = prefix ? [prefix] : [];
-  if (!results.length) return [...lines, "  No shared connections need applying."].join("\n");
-  const attention = results.filter((item) => !["synced", "removed"].includes(item.status));
-  const total = new Set(results.map((item) => item.name)).size;
-  const unresolved = new Set(attention.map((item) => item.name)).size;
-  lines.push(`  Connections: ${total - unresolved} complete \xB7 ${unresolved} need attention`);
+function formatResults(results, prefix = "", options = {}) {
+  const plain = (text) => text;
+  const paint = options.paint ?? { success: plain, warning: plain, error: plain, dim: plain, bold: plain };
+  const safe = (text) => text.replace(/[\x00-\x1f\x7f]/g, " ");
+  const lines = prefix ? [paint.bold(prefix)] : [];
+  const total = options.connectionCount ?? new Set(results.flatMap((item) => item.connections ?? [item.name])).size;
+  lines.push(`  Connections: ${total}`);
   const updated = results.filter((item) => item.status === "synced" && item.detail === "Applied").length;
   const unchanged = results.filter((item) => item.status === "synced" && item.detail !== "Applied").length;
   const removed = results.filter((item) => item.status === "removed").length;
-  lines.push(`  Service entries: ${updated} updated \xB7 ${unchanged} already up to date${removed ? ` \xB7 ${removed} removed` : ""}`);
-  for (const [heading, rows] of [
-    ["Needs review (existing settings kept)", attention.filter((item) => item.status === "conflict")],
-    ["Could not finish", attention.filter((item) => item.status !== "conflict")]
+  const failed = results.filter((item) => item.status === "error");
+  lines.push(`  Service entries: ${paint.success(`${updated} updated \xB7 ${unchanged} already up to date`)}${removed ? ` \xB7 ${paint.success(`${removed} removed`)}` : ""} \xB7 ${(failed.length ? paint.error : paint.dim)(`${failed.length} failed`)}`);
+  if (!results.length) lines.push(paint.dim("  No shared connections need applying."));
+  if (results.length && results.every((item) => item.status === "synced" || item.status === "removed")) lines.push(paint.success("  OK: all service entries are up to date."));
+  const waiting = results.filter((item) => item.status === "pending");
+  for (const kind of KINDS) {
+    const runtime = waiting.filter((item) => item.kind === kind && item.waitingFor === "runtime");
+    const kept = waiting.filter((item) => item.kind === kind && item.waitingFor === "session");
+    if (!runtime.length && !kept.length) continue;
+    lines.push(`
+${paint.warning(runtime.length ? `Waiting for runtime - ${kind.toUpperCase()}` : `Waiting for ${sessionName(kind)}`)}`);
+    if (runtime.length) lines.push("  Install it from Runtime, then run Sync. Your existing entries keep working.");
+    else lines.push("  Resolve this session entry in Sync. Existing connection entries stay until it is ready.");
+    const retained = /* @__PURE__ */ new Map();
+    for (const client of new Set(kept.map((item) => item.client))) {
+      const names = [...new Set(kept.filter((item) => item.client === client).map((item) => item.name))];
+      const key = JSON.stringify([...names].sort());
+      const group = retained.get(key);
+      if (group) group.clients.push(client);
+      else retained.set(key, { clients: [client], names });
+    }
+    for (const group of retained.values()) {
+      const clients = group.clients.map((client) => CLIENT_LABELS2[client]).join(" \xB7 ");
+      lines.push(paint.dim(`  Kept in ${clients} until ${sessionName(kind)} is applied: ${group.names.map(safe).join(", ")}`));
+    }
+  }
+  for (const [heading, rows, color] of [
+    ["Needs review (existing settings kept)", results.filter((item) => item.status === "conflict"), paint.warning],
+    ["Waiting for Sync", waiting.filter((item) => !item.waitingFor || !["runtime", "session"].includes(item.waitingFor)), paint.warning],
+    ["Could not finish", failed, paint.error]
   ]) {
     if (!rows.length) continue;
     lines.push(`
-${heading}:`);
+${color(`${heading}:`)}`);
     for (const name of new Set(rows.map((item) => item.name))) {
-      lines.push(`  ${name.replace(/[\x00-\x1f\x7f]/g, " ")}`);
-      for (const row of rows.filter((item) => item.name === name)) lines.push(`    ${CLIENT_LABELS2[row.client]}: ${row.detail}`);
+      lines.push(`  ${safe(name)}`);
+      for (const row of rows.filter((item) => item.name === name)) lines.push(`    ${row.status === "error" ? paint.error("FAILED ") : ""}${CLIENT_LABELS2[row.client]}: ${safe(row.detail)}`);
     }
   }
-  if (attention.length) lines.push("\nNext: open Sync to compare settings or retry unfinished changes.");
+  if (results.some((item) => item.status === "conflict")) lines.push(paint.warning(`
+${options.reviewHint ?? "Next: open Sync to compare settings and choose which version to use."}`));
+  if (failed.length) lines.push(paint.error("\nNext: fix the errors above, then run Sync again."));
   return lines.join("\n");
 }
 
@@ -1728,7 +1814,7 @@ async function runtimeMenu(prompter, registry, requestedKind) {
         prompter.write(`New kinds will use ${mode === "catalog" ? "session servers" : "individual entries"}. Existing kinds keep their settings.
 `);
         if (await prompter.askYesNo("Change the default for new kinds?", false)) {
-          prompter.write(`${formatResults(registry.setDefaultMode(mode), "Default for new kinds saved.")}
+          prompter.write(`${registry.formatResults(registry.setDefaultMode(mode), "Default for new kinds saved.", prompter.paint)}
 `);
           await prompter.acknowledge();
         }
@@ -1757,7 +1843,7 @@ async function runtimeMenu(prompter, registry, requestedKind) {
         if (!await prompter.askYesNo("Apply this configuration mode?", false)) continue;
         const results2 = registry.applySession(plan2);
         prompter.clearScreen();
-        prompter.write(`${formatResults(results2, "Configuration mode saved.")}
+        prompter.write(`${registry.formatResults(results2, "Configuration mode saved.", prompter.paint)}
 `);
         await registry.checkSaved(prompter, plan2.names);
         prompter.write("Restart or reconnect your AI clients to load the new server layout. Fix startup failures first.\n");
@@ -1793,7 +1879,7 @@ Convert ${plan.names.length} connection(s):
       if (!await prompter.askYesNo("Apply these launch commands to registered services?", true)) continue;
       const results = registry.applyRuntime(plan);
       prompter.clearScreen();
-      prompter.write(`${formatResults(results, "Runtime settings saved.")}
+      prompter.write(`${registry.formatResults(results, "Runtime settings saved.", prompter.paint)}
 
 Restart or reconnect AI clients to replace running npx processes.
 `);
@@ -1915,7 +2001,7 @@ async function migrationMenu(prompter, registry) {
     if (!await prompter.askYesNo("Migrate registry and apply these changes?", false)) return;
     const results = registry.applyMigration(plan);
     prompter.clearScreen();
-    prompter.write(`${formatResults(results, "Registry migration saved.")}
+    prompter.write(`${registry.formatResults(results, "Registry migration saved.", prompter.paint)}
 `);
     await registry.checkSaved(prompter, plan.kinds.filter((item) => item.status !== "individual").flatMap((item) => item.names));
     prompter.write("Reconnect affected clients after changes to their server layout. Fix startup failures first.\n");
@@ -1930,6 +2016,12 @@ async function migrationMenu(prompter, registry) {
 }
 
 // src/modules/registration/menu.ts
+function pendingImports(registry, kind) {
+  const state = registry.read();
+  const entries = registry.candidates(kind).entries.filter((candidate) => !Object.hasOwn(state.connections, candidate.name));
+  const names = [...new Set(entries.map((candidate) => candidate.name))];
+  return { names, differing: names.filter((name) => new Set(entries.filter((item) => item.name === name).map((item) => entryHash(item.entry))).size > 1).length };
+}
 function preview(prompter, entry) {
   if (!entry) {
     prompter.write("  Remove this connection from the service.\n");
@@ -2005,8 +2097,8 @@ Remove only AKMS-managed entries from these services; keep the shared catalog.
       const results = registry.register([...selected], initial.clients, plan.imports);
       prompter.clearScreen();
       prompter.write(`
-${formatResults(results, `Registration saved.
-  AI services: ${[...selected].map((id) => CLIENT_LABELS2[id]).join(" \xB7 ") || "none"}`)}
+${registry.formatResults(results, `Registration saved.
+  AI services: ${[...selected].map((id) => CLIENT_LABELS2[id]).join(" \xB7 ") || "none"}`, prompter.paint)}
 `);
       if (importNames.length) prompter.write(`Imported ${importNames.length} existing connection(s) into the shared list.
 `);
@@ -2079,7 +2171,7 @@ Import existing connections:
         if (await prompter.askYesNo("Import matching connections and apply them?", true)) {
           const results2 = registry.register(state.clients, state.clients, matching.imports);
           prompter.clearScreen();
-          prompter.write(`${formatResults(results2, "Import complete")}
+          prompter.write(`${registry.formatResults(results2, "Import complete", prompter.paint)}
 `);
           await prompter.acknowledge();
         }
@@ -2107,7 +2199,7 @@ ${plainText(name)} \xB7 Choose the settings to use on all registered services.
       const results = registry.importEntry(destination, chosen, candidates);
       prompter.clearScreen();
       prompter.write(`
-${formatResults(results, "Import complete")}
+${registry.formatResults(results, "Import complete", prompter.paint)}
 `);
       if (destination !== name) prompter.write("  The original entries were kept under their old name.\n");
       await prompter.acknowledge();
@@ -2127,19 +2219,28 @@ async function syncMenu(prompter, registry) {
     const results = pendingResults ?? registry.sync();
     pendingResults = void 0;
     prompter.write(`
-${formatResults(results, "Sync results")}
+${registry.formatResults(results, "Sync results", prompter.paint, "Next: choose an item below to compare settings and pick a version.")}
 `);
+    const imports = pendingImports(registry);
+    if (imports.names.length) prompter.write(prompter.paint.warning(`
+Not yet imported: ${imports.names.length} connection(s)${imports.differing === imports.names.length ? " with differing settings" : ""} - open Import existing connections.
+`));
     const conflicts = results.filter((result) => result.status === "conflict");
-    if (!conflicts.length) {
+    if (!conflicts.length && !imports.names.length) {
       await prompter.acknowledge();
       return;
     }
     const picked = await prompter.select("Review differences", [
       ...conflicts.map((item, index) => ({ value: String(index), label: `${CLIENT_LABELS2[item.client]} \xB7 ${item.name}` })),
+      ...imports.names.length ? [{ value: "import", key: "import", label: "Import existing connections", hint: `${imports.names.length} connection(s) to review` }] : [],
       { value: "back", key: "b", label: "Later \u2014 keep existing settings" }
     ], { cancelValue: "back" });
     if (picked === "back") return;
     try {
+      if (picked === "import") {
+        await importMenu(prompter, registry);
+        continue;
+      }
       prompter.clearScreen();
       const conflict = conflicts[Number(picked)];
       const state = registry.read();
@@ -2173,12 +2274,17 @@ ${formatResults(results, "Sync results")}
       const client = CLIENT_LABELS2[conflict.client];
       const registered = state.clients.includes(conflict.client);
       const sessionMode = registry.isSessionMode(connection.kind, state);
-      const removing = !connection.entry || !registered || sessionMode;
+      const removing = !connection.entry || !registered;
+      const retiring = sessionMode && !removing;
       const subject = connection.entry && descriptionOnly([connection.entry, actual]) ? "description" : "settings";
       writeWrapped(prompter, `Sync / ${plainText(conflict.name)}`);
       writeWrapped(prompter, `Registered services: ${state.clients.map((id) => CLIENT_LABELS2[id]).join(" \xB7 ") || "none"}`);
       prompter.write("\n");
       if (!removing && connection.entry) {
+        if (retiring) {
+          writeWrapped(prompter, `Choose settings for ${sessionName(connection.kind)} before removing the old ${client} entry.`);
+          writeWrapped(prompter, "The old entry stays until the session server is ready.");
+        }
         compareEntries(prompter, [{ label: "Saved in AKMS", entry: connection.entry }, { label: `Currently in ${client}`, entry: actual }]);
       } else {
         writeWrapped(prompter, !registered ? `${client} is no longer registered.` : sessionMode ? `This kind now uses ${sessionName(connection.kind)}. The individual client entry is no longer needed.` : "This connection was removed from AKMS.");
@@ -2190,8 +2296,8 @@ Currently in ${client}
         prompter.write("\n");
       }
       const choices = [
-        { value: "shared", label: removing ? `Remove from ${client}` : `Use 1: AKMS -> ${client}`, hint: removing ? "finish the pending removal" : `replace its ${subject} with version 1` },
-        ...registered ? [{ value: "client", label: sessionMode ? `Import ${client} settings into the catalog, then remove this entry` : removing ? `Restore from ${client}` : `Use 2: ${client} -> all ${state.clients.length} services`, hint: "save in AKMS and sync registered services" }] : [],
+        { value: "shared", label: removing ? `Remove from ${client}` : retiring ? "Use 1: keep AKMS settings" : `Use 1: AKMS -> ${client}`, hint: removing ? "finish the pending removal" : retiring ? `use version 1 in ${sessionName(connection.kind)}` : `replace its ${subject} with version 1` },
+        ...registered ? [{ value: "client", label: removing ? `Restore from ${client}` : `Use 2: ${client} -> all ${state.clients.length} services`, hint: retiring ? `save version 2 in AKMS for ${sessionName(connection.kind)}` : "save in AKMS and sync registered services" }] : [],
         { value: "back", key: "b", label: "Back without changes" }
       ];
       const choice = await prompter.select(removing ? registered ? "Remove or restore this connection?" : `Remove this connection from ${client}?` : `Which ${subject} should be used?`, choices, { cancelValue: "back" });
@@ -2200,8 +2306,9 @@ Currently in ${client}
       if (choice === "client") {
         writeWrapped(prompter, `Save the ${client} version in AKMS.`);
         writeWrapped(prompter, `Sync to: ${state.clients.map((id) => CLIENT_LABELS2[id]).join(" \xB7 ")}`);
-      } else writeWrapped(prompter, removing ? `Remove ${plainText(conflict.name)} from ${client}.` : `Copy the saved AKMS ${subject} to ${client}.`);
-      const confirmation = choice === "client" ? `Save in AKMS and sync ${state.clients.length} services?` : removing ? `Remove from ${client}?` : `Update ${client} with version 1?`;
+      } else writeWrapped(prompter, removing ? `Remove ${plainText(conflict.name)} from ${client}.` : retiring ? `Keep the saved AKMS ${subject}.` : `Copy the saved AKMS ${subject} to ${client}.`);
+      if (retiring) writeWrapped(prompter, `Keep the old ${client} entry until ${sessionName(connection.kind)} is ready, then remove it.`);
+      const confirmation = choice === "client" ? `Save in AKMS and sync ${state.clients.length} services?` : removing ? `Remove from ${client}?` : retiring ? "Keep version 1 and finish Sync?" : `Update ${client} with version 1?`;
       if (await prompter.askYesNo(confirmation, false)) {
         pendingResults = registry.resolve(conflict.client, conflict.name, actual, choice === "client");
       }
@@ -2920,7 +3027,7 @@ ${failure}
         const state = registry.read();
         const clients = state.clients;
         const migration = registry.needsMigration(state);
-        if (migration) prompter.write("Registry update available. Choose Migrate registry to review the changes.\n");
+        if (migration) prompter.write(prompter.paint.warning("Registry update available. Choose Migrate registry to review the changes.\n"));
         const picked = await prompter.select("AKMS MCP \xB7 Connection setup", [
           { value: "db", label: "Database", hint: "PostgreSQL connections" },
           { value: "ssh", label: "SSH", hint: "Remote hosts" },
@@ -3208,7 +3315,7 @@ async function main() {
   if (argumentsList.showVersion == true) {
     let version = "development";
     if (true) {
-      version = "0.3.1";
+      version = "0.3.2";
     }
     process.stdout.write(`${version}
 `);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@akms/mcp",
-    "version": "0.3.1",
+    "version": "0.3.2",
     "description": "Interactive launcher for configuring installed AKMS database, SSH, WSL and S3 MCP runtimes.",
     "keywords": [
         "mcp",