jishushell 0.6.5 → 0.7.3

package/dist/cli/core.js

@@ -4,8 +4,8 @@
  * onboard/reset/update/config/install/uninstall.
  *
  * Dependency hierarchy:
- *   cli/core.ts  →  services/core-manager.ts  (pure logic, no I/O)
- *   cli/core.ts  →  services/nomad-manager.ts  (instance management, no I/O)
+ *   cli/core.ts  →  services/setup/core-manager.ts  (pure logic, no I/O)
+ *   cli/core.ts  →  services/runtime/drivers/nomad.ts  (runtime execution)
  * All terminal output/formatting lives in this file.
  */
 import { execSync, execFileSync } from "child_process";
@@ -14,9 +14,10 @@ import { dirname, join } from "path";
 import { networkInterfaces } from "os";
 import { fileURLToPath, pathToFileURL } from "url";
 import { parsePort, hasFlag } from "./helpers.js";
-import { detectRunMode, getCorePort, isPortListening, readAlivePid, systemdStatus, startCore, stopCore, restartCore, killPortProcess, waitForPortOpen, } from "../services/core-manager.js";
-import { checkUpdate, upgradePackage, scheduleRestart, getInstalledGlobalVersion, isVersionAtLeast, markUpdateRestarting, markUpdateFailed, } from "../services/update-manager.js";
-import { listInstanceIds, readInstanceMeta, stopNomadJobInstance, getInstanceStatus, ensureNomadToken, isAppJob, } from "../services/nomad-manager.js";
+import { detectRunMode, getCorePort, isPortListening, readAlivePid, systemdStatus, startCore, stopCore, restartCore, killPortProcess, waitForPortOpen, } from "../services/setup/core-manager.js";
+import { checkUpdate, } from "../services/system/update-manager.js";
+import { executeUpgradeFinalize, getUpgradeFinalizeStatus, preflightUpgradeFinalizeRequest } from "../services/system/upgrade-finalize.js";
+import { listInstanceIds, readInstanceMeta, stopIntegrationRuntimeJob, getInstanceStatus, ensureNomadToken, isAppJob, } from "../services/runtime/drivers/nomad.js";
 import { JISHUSHELL_HOME, getCoreConfig, getNomadToken, getNomadAddr, saveCoreConfig, setOpenclawDockerImage } from "../config.js";
 import { isInitialized, initPassword, resetPassword } from "../auth.js";
 const DEFAULT_PORT = 8091;
@@ -44,6 +45,28 @@ const c = {
     dim: (s) => isTTY ? `\x1b[2m${s}\x1b[0m` : s,
 };
 function log(msg) { process.stdout.write(msg + "\n"); }
+function warningBox(lines) {
+    const width = Math.max(...lines.map((line) => line.length), 1);
+    const border = "═".repeat(width + 4);
+    log(c.yellow(`  ╔${border}╗`));
+    for (const line of lines) {
+        log(c.yellow(`  ║  ${line.padEnd(width)}  ║`));
+    }
+    log(c.yellow(`  ╚${border}╝`));
+}
+async function confirmInteractive(question) {
+    if (!process.stdin.isTTY)
+        return false;
+    const { createInterface } = await import("readline");
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise((resolve) => {
+        rl.question(`${question} [y/N] `, (input) => {
+            rl.close();
+            resolve(input.trim().toLowerCase());
+        });
+    });
+    return answer === "y" || answer === "yes";
+}
 function fmtTimeoutSeconds(timeoutMs) {
     if (!timeoutMs || timeoutMs <= 0)
         return 10;
@@ -89,13 +112,11 @@ export async function runStop(rest) {
         const instanceIds = await listInstanceIds();
         if (instanceIds.length > 0) {
             log(c.dim(`  Stopping ${instanceIds.length} Nomad job(s)…`));
+            const { stopInstance } = await import("../services/app-common/lifecycle-service.js");
             await Promise.allSettled(instanceIds.map(async (id) => {
                 const meta = readInstanceMeta(id);
                 const name = meta?.name || id;
-                const { isAppInstalled, stopApp } = await import("../services/app/app-manager.js");
-                const result = isAppInstalled(id)
-                    ? await stopApp(id)
-                    : await stopNomadJobInstance(id);
+                const result = await stopInstance(id);
                 if (result.ok) {
                     log(`    ${c.green("✓")} stopped job: ${name}`);
                 }
@@ -232,18 +253,11 @@ export async function runStatus() {
             const runtime = meta?.runtime;
             let portInfo = "";
             if (runtime) {
-                const envPort = runtime.env?.OPENCLAW_GATEWAY_PORT;
-                const args = runtime.args || [];
-                const argsPort = (() => {
-                    for (let i = 0; i < args.length - 1; i++) {
-                        if (args[i] === "--port")
-                            return args[i + 1];
-                    }
-                    return null;
-                })();
-                const gp = envPort || argsPort;
-                if (gp)
-                    portInfo = c.dim(`  gateway :${gp}`);
+                const hostPort = Array.isArray(runtime.ports)
+                    ? runtime.ports.find((port) => Number.isInteger(port?.hostPort) && port.hostPort > 0)?.hostPort
+                    : undefined;
+                if (hostPort)
+                    portInfo = c.dim(`  gateway :${hostPort}`);
             }
             const dot = statusStr === "running" ? c.green("●")
                 : statusStr === "pending" ? c.yellow("●")
@@ -452,7 +466,7 @@ export async function runReset(rest) {
     log(`    ${c.dim("•")} Reset auth credentials and LLM provider config`);
     log(`    ${c.dim("•")} Preserve infrastructure config (Docker image, service manager, port)`);
     log("");
-    log(`  ${c.bold(c.yellow("Custom openclaw_home paths outside ~/.jishushell are NOT removed."))}`);
+    log(`  ${c.bold(c.yellow("Custom integration-home paths outside ~/.jishushell are NOT removed."))}`);
     log(`  ${c.dim("After reset: restart the core at")} ${c.bold(`http://localhost:${getCorePort()}`)} ${c.dim("and reconfigure through panel or core API.")}`);
     log("");
     if (!yes) {
@@ -495,25 +509,27 @@ export async function runReset(rest) {
         for (const id of instanceIds) {
             const meta = readInstanceMeta(id);
             const name = meta?.name || id;
-            // Stop from scheduler (best-effort — may already be gone if Nomad is down)
-            await stopNomadJobInstance(id, true).catch(() => { });
             let del = { ok: true };
             if (isAppJob(id)) {
                 try {
-                    const { uninstallApp } = await import("../services/app/app-manager.js");
-                    await uninstallApp(id);
+                    const { uninstallInstance } = await import("../services/app-common/lifecycle-service.js");
+                    await uninstallInstance(id);
                 }
                 catch (e) {
                     del = { ok: false, warnings: [e.message] };
                 }
             }
-            else if (id.startsWith("openclaw-")) {
-                try {
-                    const { deleteInstance: delInst } = await import("../services/app/app-manager.js");
-                    del = await delInst(id.slice("openclaw-".length));
-                }
-                catch (e) {
-                    del = { ok: false, warnings: [e.message] };
+            else {
+                // Legacy/raw runtime cleanup only. App jobs must go through lifecycle-service.
+                await stopIntegrationRuntimeJob(id, true).catch(() => { });
+                if (id.startsWith("openclaw-")) {
+                    try {
+                        const { deleteInstance: delInst } = await import("../services/app-common/service.js");
+                        del = await delInst(id.slice("openclaw-".length));
+                    }
+                    catch (e) {
+                        del = { ok: false, warnings: [e.message] };
+                    }
                 }
             }
             if (del.ok) {
@@ -537,9 +553,10 @@ export async function runReset(rest) {
         }
         catch { /* best-effort */ }
     }
-    // 3. Selectively clear core.json: preserve infrastructure settings
-    //    (service_manager, nomad_driver, runtime_catalog, nomad_token, core_port,
-    //    npm_registry) so the user does NOT need to reinstall Docker/Nomad/OpenClaw.
+    // 3. Selectively clear core.json: preserve infrastructure settings,
+    //    including integration runtime records stored under the historical
+    //    runtime_catalog key, so the user does NOT need to reinstall
+    //    Docker/Nomad/OpenClaw.
     //    User-owned LLM provider settings are cleared.
     const CORE_CONFIG = join(JISHUSHELL_HOME, "core.json");
     const INFRA_KEYS = new Set([
@@ -601,64 +618,333 @@ export async function runUpdateCheck() {
     console.log(JSON.stringify(info));
     process.exit(info.hasUpdate ? 0 : 1);
 }
-export async function runUpdate() {
+// ── upgrade finalize ───────────────────────────────────────────────────────
+function printUpgradeFinalizeStatus() {
+    const status = getUpgradeFinalizeStatus();
     log("");
-    log(c.bold("  Updating JishuShell…"));
-    const { currentVersion, latestVersion } = await checkUpdate();
-    const expectedVersion = process.env.JISHUSHELL_UPDATE_TARGET_VERSION || latestVersion;
-    const trackedCurrentVersion = process.env.JISHUSHELL_UPDATE_CURRENT_VERSION || currentVersion;
-    const trackedWebUpdate = process.env.JISHUSHELL_WEB_UPDATE === "1";
-    log(c.dim(`  current: ${currentVersion}  →  latest: ${expectedVersion}`));
-    log(c.dim("  Running: npm install -g jishushell …"));
-    try {
-        const { output } = await upgradePackage();
-        if (output)
-            log(c.dim(output));
-        const installedVersion = getInstalledGlobalVersion();
-        if (!isVersionAtLeast(installedVersion, expectedVersion)) {
-            throw new Error(`npm -g version is still ${installedVersion}, expected at least ${expectedVersion}`);
+    log(c.bold("  JishuShell Compatibility Upgrade"));
+    log(c.dim("  ─────────────────────────────────────────────────────"));
+    log("");
+    const icon = status.phase === "completed" ? c.green("✓")
+        : status.phase === "failed" ? c.red("✗")
+            : c.yellow("!");
+    log(`  ${icon} ${c.bold(status.phase)} — ${status.message}`);
+    log("");
+    log(`  migratable: ${status.summary.migratable}`);
+    log(`  migrated:   ${status.summary.migrated}`);
+    log(`  unsupported:${status.summary.unsupported}`);
+    log(`  restart:   ${status.summary.requiresRestart}`);
+    log(`  sudo:      ${status.summary.requiresSudo}`);
+    log(`  rename:    ${status.summary.requiresRename}`);
+    if (status.affectedInstances.length > 0) {
+        log("");
+        log(c.bold("  Affected instances:"));
+        for (const item of status.affectedInstances) {
+            const flags = [
+                item.requiresRename ? "rename" : "",
+                item.requiresRestart ? "restart" : "",
+                item.requiresSudo ? "sudo" : "",
+            ].filter(Boolean).join(", ");
+            log(`    ${c.cyan(item.id)}${flags ? c.dim(` (${flags})`) : ""}`);
+            log(c.dim(`      ${item.detail}`));
         }
-        try {
-            const { repairRuntimeInstances, buildRuntimeRestartAdvisories } = await import("../services/runtime-repair.js");
-            const repair = await repairRuntimeInstances();
-            const restartRequired = await buildRuntimeRestartAdvisories(repair.results);
-            if (repair.results.length > 0) {
-                log(c.dim(`  Instance compatibility repair checked ${repair.results.length} runtime instance(s).`));
-            }
-            if (restartRequired.length > 0) {
-                log(c.yellow(`  ${restartRequired.length} runtime instance(s) should be started/restarted after reload.`));
-                for (const item of restartRequired)
-                    log(c.cyan(`    ${item.command}`));
+    }
+    if (status.blockers.length > 0) {
+        log("");
+        log(c.bold(c.red("  Blockers:")));
+        for (const item of status.blockers) {
+            log(`    ${c.red(item.id)}${item.unsupportedReason ? c.dim(` (${item.unsupportedReason})`) : ""}`);
+            log(c.dim(`      ${item.detail}`));
+        }
+    }
+    log("");
+    return status;
+}
+async function runUpgradeStatus() {
+    printUpgradeFinalizeStatus();
+}
+async function runUpgradeFinalize(rest) {
+    const status = printUpgradeFinalizeStatus();
+    const yes = hasFlag(rest, "--yes", "-y");
+    const restartInstances = hasFlag(rest, "--restart-instances");
+    if (status.requiresRestartConsent && !(yes && restartInstances)) {
+        const affected = status.affectedInstances
+            .filter((item) => item.requiresRestart)
+            .map((item) => item.id);
+        log(c.yellow("  This finalization will briefly restart running instances:"));
+        for (const id of affected)
+            log(c.cyan(`    ${id}`));
+        log("");
+        const confirmed = await confirmInteractive("Continue and allow these instance restarts?");
+        if (!confirmed) {
+            log(c.yellow("  Cancelled. No instance data was changed."));
+            log(c.dim("  For non-interactive use: sudo jishushell upgrade finalize --yes --restart-instances"));
+            log("");
+            process.exitCode = 1;
+            return;
+        }
+    }
+    const preflight = preflightUpgradeFinalizeRequest({
+        restartConsentGranted: status.requiresRestartConsent ? true : restartInstances,
+    });
+    if (preflight.code === "not-required") {
+        log(c.green("  ✓ Compatibility finalization is not required."));
+        log("");
+        return;
+    }
+    if (!preflight.ok) {
+        log(c.red(`  ✗ ${preflight.message}`));
+        log("");
+        process.exitCode = 1;
+        return;
+    }
+    log(c.bold("  Running compatibility finalization…"));
+    log("");
+    const result = await executeUpgradeFinalize({
+        restartConsentGranted: status.requiresRestartConsent ? true : restartInstances,
+    });
+    if (result.report) {
+        const { renderReport } = await import("../services/legacy-migrator/index.js");
+        log(renderReport(result.report));
+        log("");
+    }
+    if (result.restartedInstances && result.restartedInstances.length > 0) {
+        log(c.bold("Runtime instance restore:"));
+        for (const item of result.restartedInstances) {
+            const icon = item.ok ? c.green("✓") : c.red("✗");
+            log(`  ${icon} ${item.id}${item.error ? c.dim(` — ${item.error}`) : ""}`);
+        }
+        log("");
+    }
+    if (result.ok) {
+        log(c.green(`  ✓ ${result.message}`));
+    }
+    else {
+        log(c.red(`  ✗ ${result.message}`));
+        process.exitCode = 1;
+    }
+    log("");
+}
+export async function runUpgrade(rest) {
+    const subcmd = rest[0] ?? "status";
+    switch (subcmd) {
+        case "status":
+            return runUpgradeStatus();
+        case "finalize":
+            return runUpgradeFinalize(rest.slice(1));
+        default:
+            log("");
+            log(c.bold("  jishushell upgrade") + " — compatibility upgrade finalization");
+            log("");
+            log("  Usage:");
+            log(`    jishushell upgrade ${c.cyan("status")}      Show compatibility finalization status`);
+            log(`    jishushell upgrade ${c.cyan("finalize")}    Preflight compatibility finalization`);
+            log("");
+            if (subcmd) {
+                console.error(`Unknown upgrade subcommand: ${subcmd}`);
+                process.exitCode = 1;
             }
-            if (!repair.ok) {
-                log(c.yellow("  Instance compatibility repair completed with warnings; run `jishushell system repair-instances` for details."));
+    }
+}
+// ── repair ────────────────────────────────────────────────────────────────
+async function printRepairStatus() {
+    const { getRepairStatus } = await import("../services/system/repair-orchestrator.js");
+    const status = await getRepairStatus();
+    log("");
+    log(c.bold("  JishuShell Repair"));
+    log(c.dim("  ─────────────────────────────────────────────────────"));
+    log("");
+    const icon = status.phase === "completed" ? c.green("✓")
+        : status.phase === "failed" ? c.red("✗")
+            : c.yellow("!");
+    log(`  ${icon} ${c.bold(status.phase)} — ${status.message}`);
+    log("");
+    const rows = [
+        ["system reconcile", status.requirements.requiresServiceRestart],
+        ["legacy migration", status.requirements.requiresLegacyMigration],
+        ["runtime repair", status.requirements.requiresRuntimeRepair],
+        ["running instance restart", status.requirements.requiresRunningInstanceRestart],
+        ["sudo", status.requirements.requiresSudo],
+    ];
+    for (const [label, required] of rows) {
+        log(`  ${label.padEnd(24)} ${required ? c.yellow("required") : c.dim("ok")}`);
+    }
+    if (status.runningInstancesAffected.length > 0) {
+        log("");
+        log(c.bold(c.yellow("  Running instances affected:")));
+        for (const id of status.runningInstancesAffected)
+            log(`    ${c.cyan(id)}`);
+    }
+    const runningAffected = new Set(status.runningInstancesAffected);
+    const runtimeItems = status.runtime.results.filter((item) => item.status !== "ok");
+    if (runtimeItems.length > 0) {
+        log("");
+        log(c.bold("  Runtime repair items:"));
+        for (const item of runtimeItems) {
+            const restartDeferred = item.restartRequired && !runningAffected.has(item.instanceId);
+            const displayStatus = restartDeferred ? "restart-deferred" : item.status;
+            const itemIcon = item.status === "error" ? c.red("✗")
+                : restartDeferred ? c.dim("·")
+                    : item.status === "needs-restart" ? c.yellow("!")
+                        : item.status === "repaired" ? c.cyan("↻")
+                            : c.yellow("·");
+            log(`    ${itemIcon} ${item.instanceId} (${item.integrationKind}) — ${displayStatus}`);
+            for (const warning of item.warnings)
+                log(c.yellow(`        ${warning}`));
+            if (item.reason) {
+                log(restartDeferred
+                    ? c.dim(`        ${item.reason}; instance is not running, so repair will not start it`)
+                    : c.yellow(`        ${item.reason}`));
             }
+            if (item.error)
+                log(c.red(`        ${item.error}`));
         }
-        catch (repairError) {
-            log(c.yellow(`  Instance compatibility repair skipped: ${repairError?.message ?? repairError}`));
+    }
+    if (status.blockers.length > 0) {
+        log("");
+        log(c.bold(c.red("  Blockers:")));
+        for (const blocker of status.blockers) {
+            log(`    ${c.red(blocker.id)} ${c.dim(`[${blocker.source}]`)}`);
+            log(c.dim(`      ${blocker.message}`));
         }
-        if (trackedWebUpdate) {
-            markUpdateRestarting(expectedVersion, trackedCurrentVersion, installedVersion);
-            try {
-                const { inspectSystemDrift } = await import("../services/system-reconciler.js");
-                await inspectSystemDrift();
-            }
-            catch {
-                // The restarted core will run reconciliation again; update success does not depend on this hint.
+    }
+    if (status.repairRequired) {
+        log("");
+        log(c.dim(`  Command: ${status.command}`));
+    }
+    log("");
+    return status;
+}
+export async function runRepair(rest) {
+    const subcmd = rest[0];
+    if (subcmd === "status") {
+        await printRepairStatus();
+        return;
+    }
+    if (subcmd === "help" || subcmd === "--help" || subcmd === "-h") {
+        const { getRepairCommand } = await import("../services/system/repair-orchestrator.js");
+        const repairCommand = getRepairCommand();
+        const restartRepairCommand = getRepairCommand(true);
+        log("");
+        log(c.bold("  jishushell repair") + " — repair local JishuShell framework state");
+        log("");
+        log("  Usage:");
+        log(`    jishushell repair ${c.cyan("status")}      Inspect repair requirements`);
+        log(`    ${c.cyan(repairCommand)}        Repair interactively`);
+        log(`    ${c.cyan(`${repairCommand} --yes`)}  Repair non-interactively when no running instance restart is needed`);
+        log(`    ${c.cyan(`${restartRepairCommand} --yes`)}  Repair with explicit running-instance restart consent`);
+        log("");
+        return;
+    }
+    const yes = hasFlag(rest, "--yes", "-y");
+    const restartInstances = hasFlag(rest, "--restart-instances");
+    const status = await printRepairStatus();
+    if (!status.repairRequired) {
+        log(c.green("  ✓ No repair is required."));
+        log("");
+        return;
+    }
+    if (!status.canRepair) {
+        log(c.red("  ✗ Repair is blocked. Resolve the blockers above and retry."));
+        log("");
+        process.exitCode = 1;
+        return;
+    }
+    if (status.requirements.requiresSudo && process.getuid?.() !== 0) {
+        log(c.yellow("  Repair requires sudo."));
+        log(c.dim(`  Run: ${status.command}`));
+        log("");
+        process.exitCode = 1;
+        return;
+    }
+    let restartConsentGranted = false;
+    if (status.requirements.requiresRunningInstanceRestart) {
+        if (yes && !restartInstances) {
+            log(c.yellow("  Repair needs to restart running instances and cannot continue in --yes mode."));
+            log(c.dim(`  Run interactively after stopping active work: ${status.command}`));
+            log("");
+            process.exitCode = 1;
+            return;
+        }
+        if (yes && restartInstances) {
+            restartConsentGranted = true;
+        }
+        else {
+            restartConsentGranted = await confirmInteractive("Repair will restart the running instances listed above. Continue?");
+            if (!restartConsentGranted) {
+                log(c.yellow("  Cancelled. No repair was applied."));
+                log("");
+                process.exitCode = 1;
+                return;
             }
         }
     }
-    catch (err) {
-        if (trackedWebUpdate) {
-            markUpdateFailed(err.message || "Update failed", trackedCurrentVersion);
+    if (status.requirements.requiresServiceRestart) {
+        await runSystemReload();
+        if (process.exitCode)
+            return;
+        const { clearPendingPackageUpdate } = await import("../services/system/repair-orchestrator.js");
+        clearPendingPackageUpdate();
+    }
+    const { executeRepair } = await import("../services/system/repair-orchestrator.js");
+    const result = await executeRepair({
+        restartConsentGranted,
+        applySystem: false,
+    });
+    if (result.legacy?.report) {
+        const { renderReport } = await import("../services/legacy-migrator/index.js");
+        log(renderReport(result.legacy.report));
+        log("");
+    }
+    if (result.legacy?.restartedInstances && result.legacy.restartedInstances.length > 0) {
+        log(c.bold("Runtime instance restore:"));
+        for (const item of result.legacy.restartedInstances) {
+            const itemIcon = item.ok ? c.green("✓") : c.red("✗");
+            log(`  ${itemIcon} ${item.id}${item.error ? c.dim(` — ${item.error}`) : ""}`);
+        }
+        log("");
+    }
+    if (result.runtime?.results && result.runtime.results.length > 0) {
+        log(c.bold("Runtime repair:"));
+        for (const item of result.runtime.results) {
+            const itemIcon = item.status === "error" ? c.red("✗")
+                : item.status === "needs-restart" ? c.yellow("!")
+                    : item.status === "repaired" ? c.cyan("↻")
+                        : item.status === "manual" ? c.yellow("·")
+                            : c.green("✓");
+            log(`  ${itemIcon} ${item.instanceId} (${item.integrationKind}) — ${item.status}`);
+            for (const repaired of item.repaired)
+                log(c.dim(`      repaired: ${repaired}`));
+            for (const warning of item.warnings)
+                log(c.yellow(`      warning: ${warning}`));
+            if (item.reason)
+                log(c.yellow(`      restart required: ${item.reason}`));
+            if (item.error)
+                log(c.red(`      error: ${item.error}`));
+        }
+        log("");
+    }
+    if (result.runtimeRestartedInstances && result.runtimeRestartedInstances.length > 0) {
+        log(c.bold("Runtime instance restart:"));
+        for (const item of result.runtimeRestartedInstances) {
+            const itemIcon = item.ok ? (item.skipped ? c.dim("·") : c.green("✓")) : c.red("✗");
+            const suffix = item.skipped
+                ? c.dim(` — skipped (${item.status || "not running"})`)
+                : item.error
+                    ? c.dim(` — ${item.error}`)
+                    : "";
+            log(`  ${itemIcon} ${item.id}${suffix}`);
         }
-        log(c.red(`  ✗  npm install failed: ${err.message}`));
-        throw err;
+        log("");
+    }
+    if (result.ok) {
+        log(c.green(`  ✓ ${result.message}`));
     }
-    log(c.green("  ✓  Package updated."));
-    log(c.dim("  Scheduling core restart in 2 s…"));
-    scheduleRestart(2000);
-    log(c.green("  ✓  Restart scheduled — core will reconnect shortly."));
+    else {
+        log(c.red(`  ✗ ${result.message}`));
+        process.exitCode = 1;
+    }
+    log("");
 }
 // ── serve: foreground server (systemd/launchd ExecStart) ────────────────────
 export async function runServe(rest) {
@@ -763,7 +1049,8 @@ Commands:
   set <key> <value>   修改配置项
 
 Allowed keys:
-  service_manager    服务管理器类型（nomad / process）
+  service_manager    服务管理器类型（仅支持 nomad；legacy 'process' 已停止支持，
+                     旧实例请先运行 jishushell migrate legacy）
   nomad_driver       Nomad driver（docker）
   openclaw_runtime_image
                      OpenClaw runtime Docker 镜像
@@ -781,7 +1068,7 @@ Examples:
 }
 // ── install / uninstall / reconcile ──────────────────────────────────────────
 export function brief() {
-    return "  start|stop|restart|status|serve|onboard         Core 生命周期与运行管理\n  reset|config|update|version|install|uninstall    Core 维护、版本与安装\n  reconcile                                        对账系统组件";
+    return "  start|stop|restart|status|serve|onboard         Core 生命周期与运行管理\n  reset|config|update-check|upgrade|repair|version Core 维护、版本与升级\n  install|reconcile|uninstall                      对账系统组件与卸载";
 }
 export async function runInstallCmd(rest) {
     const { runInstall, parseInstallArgs } = await import("../install.js");
@@ -789,7 +1076,7 @@ export async function runInstallCmd(rest) {
     await runInstall(opts);
 }
 export async function runReconcile() {
-    const { reconcileSystem } = await import("../services/system-reconciler.js");
+    const { reconcileSystem } = await import("../services/system/system-reconciler.js");
     log("");
     log(c.bold("  Reconciling system components…"));
     log("");
@@ -840,7 +1127,7 @@ async function runSystemRepairInstances(rest) {
     log(c.bold("  JishuShell Instance Compatibility Repair"));
     log(c.dim("  ─────────────────────────────────────────────────────"));
     log("");
-    const { repairRuntimeInstances } = await import("../services/runtime-repair.js");
+    const { repairRuntimeInstances } = await import("../services/repair/runtime-repair.js");
     const result = await repairRuntimeInstances({ dryRun });
     if (dryRun)
         log(c.dim("  Dry run only; no files or Nomad variables were changed."));
@@ -855,7 +1142,7 @@ async function runSystemRepairInstances(rest) {
                 : item.status === "repaired" ? c.cyan("↻")
                     : item.status === "manual" ? c.yellow("·")
                         : c.green("✓");
-        log(`  ${icon} ${item.instanceId} (${item.agentType}) — ${item.status}`);
+        log(`  ${icon} ${item.instanceId} (${item.integrationKind}) — ${item.status}`);
         for (const repaired of item.repaired)
             log(c.dim(`      repaired: ${repaired}`));
         for (const warning of item.warnings)
@@ -869,18 +1156,14 @@ async function runSystemRepairInstances(rest) {
         process.exitCode = 1;
     log("");
 }
-async function runSystemReload(rest = []) {
-    const restartInstances = hasFlag(rest, "--restart-instances");
-    let pendingInstanceRestarts = false;
-    let runtimeAdvisoriesKnown = false;
-    let runtimeAdvisories = [];
+async function runSystemReload() {
     log("");
     log(c.bold("  JishuShell System Reload"));
     log(c.dim("  ─────────────────────────────────────────────────────"));
     log("");
     // Step 1: Reconcile
     log(c.bold("  1. Reconciling system components…"));
-    const { reconcileSystem, inspectSystemDrift } = await import("../services/system-reconciler.js");
+    const { reconcileSystem, inspectSystemDrift } = await import("../services/system/system-reconciler.js");
     const result = await reconcileSystem();
     const errors = result.items.filter(i => i.status === "error");
     const updated = result.items.filter(i => i.status === "updated");
@@ -908,63 +1191,8 @@ async function runSystemReload(rest = []) {
         return;
     }
     log("");
-    // Step 2: Repair runtime instance compatibility
-    log(c.bold("  2. Repairing runtime instance compatibility…"));
-    let repairResults = [];
-    try {
-        const { repairRuntimeInstances, buildRuntimeRestartAdvisories } = await import("../services/runtime-repair.js");
-        const repair = await repairRuntimeInstances();
-        repairResults = repair.results;
-        runtimeAdvisories = await buildRuntimeRestartAdvisories(repair.results);
-        runtimeAdvisoriesKnown = true;
-        pendingInstanceRestarts = runtimeAdvisories.length > 0;
-        if (repair.results.length === 0) {
-            log(c.green("     ✓ No OpenClaw/Hermes instances found"));
-        }
-        let printedRepairDetail = false;
-        for (const item of repair.results) {
-            if (item.status === "ok")
-                continue;
-            printedRepairDetail = true;
-            if (item.status === "error") {
-                log(`     ${c.red("✗")}  ${item.instanceId}: repair failed`);
-            }
-            else if (item.status === "manual") {
-                log(`     ${c.yellow("·")}  ${item.instanceId}: manual compatibility check required`);
-            }
-            else {
-                const repaired = item.repaired.length > 0
-                    ? `repaired ${item.repaired.join(", ")}`
-                    : "compatibility checked";
-                log(`     ${c.green("✓")}  ${item.instanceId}: ${repaired}`);
-            }
-            for (const warning of item.warnings) {
-                if (warning.startsWith("note:")) {
-                    log(c.dim(`        ${warning}`));
-                }
-                else {
-                    log(c.yellow(`        warning: ${warning}`));
-                }
-            }
-            if (item.error)
-                log(c.red(`        error: ${item.error}`));
-        }
-        if (repair.results.length > 0 && !printedRepairDetail) {
-            log(c.green("     ✓ No runtime compatibility repairs needed"));
-        }
-        if (runtimeAdvisories.length > 0) {
-            log(c.yellow(`     → ${runtimeAdvisories.length} instance(s) need a manual restart — see step 4`));
-        }
-        if (!repair.ok)
-            process.exitCode = 1;
-    }
-    catch (e) {
-        log(c.yellow(`     ! Instance compatibility repair skipped: ${e?.message ?? e}`));
-        process.exitCode = 1;
-    }
-    log("");
-    // Step 3: Restart services
-    log(c.bold("  3. Restarting services…"));
+    // Step 2: Restart Core-owned services
+    log(c.bold("  2. Restarting Core services…"));
     let panelStartedOk = false;
     try {
         const restartResult = await restartCore();
@@ -1011,67 +1239,8 @@ async function runSystemReload(rest = []) {
         }
     }
     log("");
-    // Step 4: Persist and report runtime instance advisories
-    log(c.bold("  4. Next actions for instances…"));
-    if (!runtimeAdvisoriesKnown) {
-        log(c.yellow("     ! Runtime instance advisories were not refreshed"));
-    }
-    else if (!pendingInstanceRestarts) {
-        log(c.green("     ✓ No instance start/restart actions required"));
-    }
-    else {
-        if (!restartInstances) {
-            log(c.yellow("     Restart these instances when they are idle:"));
-            log("");
-            for (const item of runtimeAdvisories) {
-                const status = item.currentStatus ? c.dim(` (currently ${item.currentStatus})`) : "";
-                log(`     ${c.yellow("·")}  ${item.instanceId}: ${item.action}${status}`);
-                log(c.cyan(`         ${item.command}`));
-            }
-            log("");
-            log(c.dim("     Note: system reload does not start or restart app instances automatically."));
-        }
-        else {
-            try {
-                const { restartRuntimeInstances } = await import("../services/runtime-repair.js");
-                const restart = await restartRuntimeInstances(repairResults);
-                const restartedIds = new Set();
-                for (const item of restart.results) {
-                    const icon = item.status === "restarted" ? c.green("✓")
-                        : item.status === "skipped" ? c.dim("·")
-                            : c.red("✗");
-                    const suffix = item.previousStatus ? c.dim(` (was ${item.previousStatus})`) : "";
-                    log(`     ${icon}  ${item.instanceId}: ${item.status}${suffix}`);
-                    if (item.status === "restarted")
-                        restartedIds.add(item.instanceId);
-                    if (item.reason)
-                        log(c.dim(`        ${item.reason}`));
-                    if (item.error)
-                        log(c.red(`        error: ${item.error}`));
-                }
-                if (!restart.ok)
-                    process.exitCode = 1;
-                runtimeAdvisories = runtimeAdvisories.filter((item) => !restartedIds.has(item.instanceId));
-                pendingInstanceRestarts = runtimeAdvisories.length > 0;
-            }
-            catch (e) {
-                log(c.red(`     ✗ Runtime instance restart failed: ${e?.message ?? e}`));
-                process.exitCode = 1;
-            }
-        }
-    }
-    if (runtimeAdvisoriesKnown) {
-        try {
-            const { persistRuntimeRestartAdvisories } = await import("../services/system-reconciler.js");
-            await persistRuntimeRestartAdvisories(runtimeAdvisories);
-        }
-        catch (e) {
-            log(c.yellow(`     ! Runtime advisory state not persisted: ${e?.message ?? e}`));
-        }
-    }
-    log("");
-    // Step 5: Verify
-    log(c.bold("  5. Verifying…"));
+    // Step 3: Verify Core-owned services
+    log(c.bold("  3. Verifying Core services…"));
     const port = getCorePort();
     if (isPortListening(port)) {
         log(c.green(`     ✓ Core listening on :${port}`));
@@ -1083,20 +1252,14 @@ async function runSystemReload(rest = []) {
     log("");
     if (!process.exitCode) {
         await inspectSystemDrift();
-        if (pendingInstanceRestarts) {
-            log(c.green("  ✓ System reload complete.") + c.dim(`  (${runtimeAdvisories.length} instance restart(s) still pending — see step 4)`));
-        }
-        else {
-            log(c.green("  ✓ System reload complete."));
-        }
+        log(c.green("  ✓ System reload complete."));
     }
     else {
         log(c.yellow("  ! System reload completed with warnings. Review output above."));
     }
     if (panelStartedOk) {
         log("");
-        log(c.dim("  Tip: refresh any open JishuShell browser tab to load the updated"));
-        log(c.dim("       UI and see pending instance restart prompts."));
+        log(c.dim("  Tip: refresh any open JishuShell browser tab to load the updated UI."));
     }
     log("");
 }
@@ -1104,7 +1267,7 @@ export async function runSystem(rest) {
     const subcmd = rest[0];
     switch (subcmd) {
         case "reload":
-            return runSystemReload(rest.slice(1));
+            return runSystemReload();
         case "status":
             return runStatus();
         case "reconcile":
@@ -1116,7 +1279,7 @@ export async function runSystem(rest) {
             log(c.bold("  jishushell system") + " — manage system-level infrastructure");
             log("");
             log("  Usage:");
-            log(`    jishushell system ${c.cyan("reload")} [--restart-instances]  Reconcile configs, restart services, and report runtime advisories`);
+            log(`    jishushell system ${c.cyan("reload")}      Reconcile host configs and restart Core services`);
             log(`    jishushell system ${c.cyan("status")}      Show system component health`);
             log(`    jishushell system ${c.cyan("reconcile")}   Check/fix system drift without restart`);
             log(`    jishushell system ${c.cyan("repair-instances")} [--dry-run]  Repair runtime instance compatibility`);
@@ -1169,15 +1332,15 @@ Core commands:
   reset                           重置 core 数据
   config  [key] [value]           查看或修改配置项
   update-check                    检查新版本
-  update                          升级到最新版本
+  upgrade status|finalize         查看或完成兼容升级 finalization
+  repair [status|--yes]           检查或修复本机 JishuShell 框架状态
   version | --version | -v        显示 CLI 版本
   install [options]               安装服务（systemd / Docker / 直接运行）
   uninstall [--yes]               卸载 core 及所有数据
   reconcile                       对账系统组件（systemd/Docker 镜像/Nomad）
 
 System commands:
-  system reload [--restart-instances]
-                                  重载系统配置并重启 core/Panel；默认只提示受影响实例
+  system reload                   对账宿主机配置并重启 core/Panel
   system status                   系统组件健康检查
   system reconcile                只对账，不重启
   system repair-instances         修复 runtime 实例兼容状态（不自动重启实例）
@@ -1197,7 +1360,8 @@ export async function run(rest) {
         case "onboard": return runOnboard(args);
         case "reset": return runReset(args);
         case "update-check": return runUpdateCheck();
-        case "update": return runUpdate();
+        case "upgrade": return runUpgrade(args);
+        case "repair": return runRepair(args);
         case "config": return runConfig(args);
         case "version":
         case "--version":
@@ -1236,7 +1400,8 @@ export async function dispatch(argv) {
         "onboard",
         "reset",
         "update-check",
-        "update",
+        "upgrade",
+        "repair",
         "config",
         "version",
         "--version",