@akms/mcp-ssh 0.3.1 → 0.3.2

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to `@akms/mcp-ssh`. Dates are `YYYY-MM-DD`.
 
+## [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

@@ -18,6 +18,14 @@ akms-mcp-ssh --help
 akms-mcp-ssh --version        # show the installed version
 ```
 
+## Upgrading from 0.2.x
+
+Open the current setup with `npx -y --prefer-online @akms/mcp@latest`, install this runtime from **Runtime**, then use **Register > Apply registration** to import existing entries. Compare differing descriptions when prompted, or use **Import existing connections** later.
+
+If you register before installing the runtime, existing entries are kept in a normal pending state. Install the runtime, run **Sync**, then restart or reconnect your client and check `ssh_catalog_status`.
+
+See the launcher's [full upgrade guide](https://github.com/juncha9/npm.akms.mcp/blob/main/README.md#upgrading-from-02x) for the comparison steps, Codex thread cleanup, rollback and **Migrate registry** for older development catalogs.
+
 ## Minimum working configuration
 
 Install the server from **Runtime** before using these manual examples. On Windows its script is `<AKMS_MCP_HOME or ~/.akms/mcp>/runtime/node_modules/@akms/mcp-ssh/lib/cli.js`; on macOS/Linux insert `lib/` before `node_modules`. Replace the placeholder below with that absolute path. Use the Node executable from `node -p "process.execPath"` as `command`. The `config` command writes both paths for you.
@@ -62,7 +70,7 @@ Managed connections start Node directly using a dedicated installation at `<AKMS
 
 Before Add or a standard-launch Edit, setup installs a missing runtime with `npm install --global --prefix "<AKMS runtime directory>" --prefer-online --no-fund --no-audit @akms/mcp-ssh@latest`. If the installed version is older than this setup package, it offers an update (default Yes); declining continues with the installed version. Linked development packages skip this prompt. Host-key saves for standard launches also check the runtime before writing. Custom launch commands keep their existing command and require no managed-runtime installation. If an update fails but an installed runtime is still usable, setup reports the error and continues with that version. Servers do not invoke npm or query updates when AI clients connect.
 
-To migrate existing entries, open `akms-mcp-ssh config`, choose **Runtime**, install the runtime if needed, then choose **Use for existing connections**. Both legacy npx entries and direct paths in ordinary global installations can be converted. Review and apply the list, then **restart or reconnect the AI clients** to replace running processes. Connection values and credentials stay intact; custom commands and external client edits are preserved for individual review. Register/import legacy entries first if they are missing from the shared list. Version-pinned npx entries switch to the installed version shown in the preview.
+For an existing catalog that still uses individual entries, open `akms-mcp-ssh config`, choose **Runtime**, install the runtime if needed, then choose **Use for existing connections**. Both legacy npx entries and direct paths in ordinary global installations can be converted. Review and apply the list, then **restart or reconnect the AI clients** to replace running processes. Connection values and credentials stay intact; custom commands and external client edits are preserved for individual review. Register/import legacy entries first if they are missing from the shared list. Version-pinned npx entries switch to the installed version shown in the preview.
 
 **Runtime > Update runtime installation** explicitly installs the latest release into this same directory. The Node executable keeps its existing alias path, allowing nvm-windows to switch Node versions while the package path stays fixed. If the Node command path or `AKMS_MCP_HOME` moves, reapply current paths from Runtime. Removing the runtime directory breaks entries that use it.
 

package/lib/cli.cjs

@@ -35,7 +35,7 @@ var SHUTDOWN_DEADLINE_MS = 5e3;
 var CWD_MARKER = "__AKMS_SSH_CWD__";
 var MAX_DIRECTORY_ENTRIES = 1e3;
 var SERVER_NAME = "akms-mcp-ssh";
-var SERVER_VERSION = "0.3.1";
+var SERVER_VERSION = "0.3.2";
 
 // src/_defs/command-rules.ts
 var CRITICAL_PATH_PATTERN = new RegExp(
@@ -968,6 +968,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)
   };
@@ -1515,7 +1517,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, indent2 = "", changed) {
+function writeWrapped(prompter, text, indent2 = "", changed, style) {
   const characters = Array.from(plainText(text));
   let line = indent2;
   let width = displayWidth(indent2);
@@ -1530,7 +1532,7 @@ function writeWrapped(prompter, text, indent2 = "", changed) {
     const size = displayWidth(character);
     if (width + size > prompter.width) {
       flush();
-      prompter.write(line + "\n");
+      prompter.write((style ? style(line) : line) + "\n");
       line = indent2;
       width = displayWidth(indent2);
     }
@@ -1543,7 +1545,7 @@ function writeWrapped(prompter, text, indent2 = "", 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;
@@ -1565,6 +1567,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}`);
@@ -1771,10 +1804,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");
@@ -2237,11 +2270,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 })),
@@ -2257,7 +2305,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;
@@ -2275,20 +2331,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;
               }
             }
@@ -2299,7 +2353,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);
@@ -2390,7 +2448,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;
@@ -2419,30 +2477,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_LABELS[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_LABELS[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_LABELS[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");
 }
 
@@ -2511,7 +2597,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();
         }
@@ -2540,7 +2626,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");
@@ -2576,7 +2662,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.
 `);
@@ -2698,7 +2784,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");
@@ -2713,6 +2799,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");
@@ -2743,22 +2835,21 @@ var ManagedSession = class {
   }
   writeStatus(prompter) {
     const state = this.registry.read();
-    if (this.registry.needsMigration(state)) prompter.write("Registry update available. Choose Migrate registry to review the changes.\n");
+    if (this.registry.needsMigration(state)) prompter.write(prompter.paint.warning("Registry update available. Choose Migrate registry to review the changes.\n"));
     prompter.write(`Services: ${state.clients.map((id) => CLIENT_LABELS[id]).join(" \xB7 ") || "none"}
 `);
-    if (!state.clients.length) prompter.write("No AI services registered. Choose Register before adding a connection.\n");
-    if (this.registry.isSessionMode(this.options.kind, state)) prompter.write(`Session server: ${sessionName(this.options.kind)}. Reconnect clients after changing connections.
-`);
-    const attention = new Set(this.registry.inspect().filter((item) => this.registry.kindForName(item.name, state) === this.options.kind && !["synced", "removed"].includes(item.status)).map((item) => item.name)).size;
-    if (attention) prompter.write(`Needs attention: ${attention} connection(s). Open Sync to review.
-`);
+    if (!state.clients.length) prompter.write(prompter.paint.warning("No AI services registered. Choose Register before adding a connection.\n"));
+    if (this.registry.isSessionMode(this.options.kind, state)) prompter.write(prompter.paint.dim(`Session server: ${sessionName(this.options.kind)}. Reconnect clients after changing connections.
+`));
+    const attention = new Set(this.registry.inspect().filter((item) => this.registry.kindForName(item.name, state) === this.options.kind && !["synced", "removed"].includes(item.status)).flatMap((item) => item.connections ?? [item.name])).size;
+    if (attention) prompter.write(prompter.paint.warning(`Needs attention: ${attention} connection(s). Open Sync to review.
+`));
     const pending = this.pendingImports();
-    if (pending) prompter.write(`Import existing connections: ${pending} connection(s) available. Existing settings are preserved.
-`);
+    if (pending) prompter.write(prompter.paint.warning(`Import available: ${pending} connection(s). Open Import existing connections.
+`));
   }
   pendingImports() {
-    const state = this.registry.read();
-    return new Set(this.registry.candidates(this.options.kind).entries.filter((candidate) => !Object.hasOwn(state.connections, candidate.name)).map((candidate) => candidate.name)).size;
+    return pendingImports(this.registry, this.options.kind).names.length;
   }
   items() {
     return [
@@ -2876,8 +2967,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_LABELS[id]).join(" \xB7 ") || "none"}`)}
+${registry.formatResults(results, `Registration saved.
+  AI services: ${[...selected].map((id) => CLIENT_LABELS[id]).join(" \xB7 ") || "none"}`, prompter.paint)}
 `);
       if (importNames.length) prompter.write(`Imported ${importNames.length} existing connection(s) into the shared list.
 `);
@@ -2950,7 +3041,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();
         }
@@ -2978,7 +3069,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();
@@ -2998,19 +3089,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_LABELS[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();
@@ -3044,12 +3144,17 @@ ${formatResults(results, "Sync results")}
       const client = CLIENT_LABELS[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_LABELS[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.");
@@ -3061,8 +3166,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" });
@@ -3071,8 +3176,9 @@ Currently in ${client}
       if (choice === "client") {
         writeWrapped(prompter, `Save the ${client} version in AKMS.`);
         writeWrapped(prompter, `Sync to: ${state.clients.map((id) => CLIENT_LABELS[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");
       }