jishushell 0.6.5 → 0.7.3

package/dist/cli/app.js

@@ -2,9 +2,10 @@ import { existsSync, readFileSync } from "fs";
 import { basename, extname } from "path";
 import { parseFlag } from "./helpers.js";
 import { loadManagedListEntries, printManagedList } from "./managed-list.js";
-import { ensureNomadToken, execInInstance, getInstanceLogs, getInstanceStatus, readInstanceMeta, restartNomadJobInstance, startNomadJobInstance, stopNomadJobInstance, } from "../services/nomad-manager.js";
-import { acknowledgeRuntimeRestartAdvisory } from "../services/system-reconciler.js";
-import { getTask, subscribeTask } from "../services/task-registry.js";
+import { ensureNomadToken, execInInstance, getInstanceLogs, getInstanceStatus, readInstanceMeta, submitIntegrationRuntimeJob, stopIntegrationRuntimeJob, } from "../services/runtime/drivers/nomad.js";
+import { markRuntimeRepairRestartApplied } from "../services/repair/runtime-repair.js";
+import { getTask, subscribeTask } from "../services/tasks/registry.js";
+import { resolveRuntimeCapabilityPort } from "../services/app-common/service.js";
 // ── ANSI colour helpers ───────────────────────────────────────────────────
 const isTTY = process.stdout.isTTY ?? false;
 const c = {
@@ -73,17 +74,67 @@ async function runManagedAppTask(starter, successMessage) {
     if (!started.ok) {
         log(c.red(`  ✗  ${started.error || "Task failed"}`));
         process.exitCode = 1;
-        return;
+        return false;
     }
     if (started.taskId) {
         const result = await waitForLocalTask(started.taskId);
         if (result.status === "error") {
             log(c.red(`  ✗  ${result.message || "Task failed"}`));
             process.exitCode = 1;
-            return;
+            return false;
         }
     }
     log(c.green(`  ✓  ${successMessage}`));
+    return true;
+}
+const LEGACY_RAW_RUNTIME_RESTART_SETTLE_MS = 2_000;
+function logLegacyRawRuntimeWarning(instanceId) {
+    log(c.yellow(`  !  No Core instance record found for "${instanceId}"; using legacy raw runtime operation. `
+        + "Run repair/migration before normal lifecycle operations."));
+}
+async function runLegacyRawRuntimeStart(instanceId) {
+    // Legacy/repair boundary only. Managed instances must go through lifecycle-service.
+    logLegacyRawRuntimeWarning(instanceId);
+    const result = await submitIntegrationRuntimeJob(instanceId);
+    if (result.ok) {
+        markRuntimeRepairRestartApplied(instanceId);
+        log(c.green(`  ✓  Started: ${readInstanceMeta(instanceId)?.name || instanceId}`));
+        return;
+    }
+    log(c.red(`  ✗  ${result.error || "Start failed"}`));
+    process.exitCode = 1;
+}
+async function runLegacyRawRuntimeStop(instanceId, purge) {
+    // Legacy/repair boundary only. Managed instances must go through lifecycle-service.
+    logLegacyRawRuntimeWarning(instanceId);
+    const result = await stopIntegrationRuntimeJob(instanceId, purge);
+    if (result.ok) {
+        log(c.green(`  ✓  Stopped: ${readInstanceMeta(instanceId)?.name || instanceId}${purge ? " (purged)" : ""}`));
+        return;
+    }
+    log(c.red(`  ✗  ${result.error || "Stop failed"}`));
+    process.exitCode = 1;
+}
+async function runLegacyRawRuntimeRestart(instanceId) {
+    // Legacy/repair boundary only. Managed instances must go through lifecycle-service.
+    logLegacyRawRuntimeWarning(instanceId);
+    const stopResult = await stopIntegrationRuntimeJob(instanceId);
+    if (!stopResult.ok && !stopResult.error?.includes("not running") && !stopResult.error?.includes("not found")) {
+        log(c.red(`  ✗  ${stopResult.error || "Restart failed"}`));
+        process.exitCode = 1;
+        return;
+    }
+    // Legacy raw runtime restart may need a short gap between stop/start until
+    // the repair path is retired behind canonical lifecycle state.
+    await new Promise((resolve) => setTimeout(resolve, LEGACY_RAW_RUNTIME_RESTART_SETTLE_MS));
+    const result = await submitIntegrationRuntimeJob(instanceId);
+    if (result.ok) {
+        markRuntimeRepairRestartApplied(instanceId);
+        log(c.green(`  ✓  Restarted: ${readInstanceMeta(instanceId)?.name || instanceId}`));
+        return;
+    }
+    log(c.red(`  ✗  ${result.error || "Restart failed"}`));
+    process.exitCode = 1;
 }
 function readPassword(prompt) {
     return new Promise((resolve, reject) => {
@@ -226,24 +277,19 @@ function parseCreateArgs(args) {
             parsed.description = result.value;
             i = result.nextIndex;
         }
-        else if (arg === "--runtime" || arg.startsWith("--runtime=")) {
-            const result = readFlagValue(args, i, "--runtime");
-            parsed.runtime = result.value;
-            i = result.nextIndex;
-        }
-        else if (arg === "--from" || arg.startsWith("--from=")) {
-            const result = readFlagValue(args, i, "--from");
-            parsed.fromAppId = result.value;
+        else if (arg === "--app-spec-id" || arg.startsWith("--app-spec-id=")) {
+            const result = readFlagValue(args, i, "--app-spec-id");
+            parsed.appSpecId = result.value;
             i = result.nextIndex;
         }
-        else if (arg === "--app-spec" || arg.startsWith("--app-spec=")) {
-            const result = readFlagValue(args, i, "--app-spec");
-            parsed.appSpecPath = result.value;
+        else if (arg === "--builtin" || arg.startsWith("--builtin=")) {
+            const result = readFlagValue(args, i, "--builtin");
+            parsed.appSpecId = result.value;
             i = result.nextIndex;
         }
-        else if (arg === "--app-spec-url" || arg.startsWith("--app-spec-url=")) {
-            const result = readFlagValue(args, i, "--app-spec-url");
-            parsed.appSpecUrl = result.value;
+        else if (arg === "--from" || arg.startsWith("--from=")) {
+            const result = readFlagValue(args, i, "--from");
+            parsed.cloneFromInstanceId = result.value;
             i = result.nextIndex;
         }
         else {
@@ -288,12 +334,6 @@ function fallbackTaskState(appStatus) {
         return "pending";
     return "unknown";
 }
-function resolveProvidePort(spec, provide) {
-    if (typeof provide?.port === "number")
-        return provide.port;
-    const serviceTask = spec.tasks.find((task) => (task.role ?? "service") === "service");
-    return serviceTask?.ports?.[0]?.port;
-}
 function provideAddress(port, path) {
     if (typeof port !== "number")
         return undefined;
@@ -305,7 +345,7 @@ function describeHealthTargets(targets) {
         .map((target) => `${target.method}${typeof target.port === "number" ? `:${target.port}` : ""}`)
         .join(",");
 }
-function enrichStatusForCli(status, spec) {
+function enrichStatusForCli(instanceId, status, spec) {
     const taskSpecs = new Map((spec?.tasks ?? []).map((task) => [task.name, task]));
     const taskNames = new Set([
         ...taskSpecs.keys(),
@@ -340,7 +380,7 @@ function enrichStatusForCli(status, spec) {
         };
     }
     const provides = (spec?.provides ?? []).map((provide) => {
-        const port = resolveProvidePort(spec, provide);
+        const port = resolveRuntimeCapabilityPort(instanceId, provide.capability) ?? undefined;
         return {
             capability: provide.capability,
             ...(typeof port === "number" ? { port } : {}),
@@ -393,7 +433,7 @@ async function loadBuiltinInstallYaml(source) {
     const normalizedSource = source.trim();
     if (!normalizedSource)
         return null;
-    const { listBuiltinAppSpecs } = await import("../services/app/app-manager.js");
+    const { listBuiltinAppSpecs } = await import("../services/app-common/service.js");
     const templates = listBuiltinAppSpecs();
     const normalizedWithoutExt = normalizedSource.replace(/\.ya?ml$/i, "");
     const aliasTarget = BUILTIN_INSTALL_ALIASES[normalizedWithoutExt] ?? BUILTIN_INSTALL_ALIASES[normalizedSource];
@@ -413,21 +453,8 @@ async function loadBuiltinInstallYaml(source) {
 async function loadInstallYaml(source) {
     const remoteUrl = parseRemoteYamlUrl(source);
     if (remoteUrl) {
-        let resp;
-        try {
-            resp = await fetch(remoteUrl, { signal: AbortSignal.timeout(30_000) });
-        }
-        catch (e) {
-            throw new Error(`Failed to download app YAML: ${e.message}`);
-        }
-        if (!resp.ok) {
-            throw new Error(`Failed to download app YAML: HTTP ${resp.status}`);
-        }
-        const body = await resp.text();
-        if (!body.trim()) {
-            throw new Error(`Downloaded app YAML is empty: ${remoteUrl}`);
-        }
-        return body;
+        const { loadRemoteAppSpecYaml } = await import("../services/app-common/remote-spec.js");
+        return loadRemoteAppSpecYaml(remoteUrl.toString(), { fieldName: "app install source URL" });
     }
     const builtinYaml = await loadBuiltinInstallYaml(source);
     if (builtinYaml) {
@@ -449,8 +476,8 @@ async function cmdList(args) {
     printManagedList("Managed Apps / Instances", items, c, log);
 }
 async function cmdShow(id) {
-    const { getApp, getInstance } = await import("../services/app/app-manager.js");
-    const app = getApp(id);
+    const { getInstanceInstallRecord, getInstance } = await import("../services/app-common/service.js");
+    const app = getInstanceInstallRecord(id);
     if (app) {
         console.log(JSON.stringify(app, null, 2));
         return;
@@ -465,7 +492,7 @@ async function cmdShow(id) {
 }
 async function cmdInstall(args) {
     const installSource = args[0];
-    let requestedAppId;
+    let requestedInstanceId;
     for (let index = 1; index < args.length; index += 1) {
         const value = args[index];
         if (value === "--sudo-password") {
@@ -474,20 +501,19 @@ async function cmdInstall(args) {
         }
         if (value.startsWith("--"))
             continue;
-        requestedAppId = value;
+        requestedInstanceId = value;
         break;
     }
     const yamlText = await loadInstallYaml(installSource);
-    const { installApp } = await import("../services/app/app-manager.js");
+    const { installInstance } = await import("../services/app-common/lifecycle-service.js");
     const sudoState = getCliSudoState(args);
     while (true) {
         try {
             const installOptions = sudoState.password ? { exec: { sudoPassword: sudoState.password } } : undefined;
             const result = installOptions
-                ? await installApp(yamlText, requestedAppId, installOptions)
-                : await installApp(yamlText, requestedAppId);
-            const installModeLabel = result.manifest.install_mode === "instance-dir" ? "instance" : "app";
-            log(c.green(`  ✓  Installed: ${result.manifest.id}  (${result.spec.name || ""} v${result.spec.version || "?"}, ${installModeLabel})`));
+                ? await installInstance(yamlText, requestedInstanceId, installOptions)
+                : await installInstance(yamlText, requestedInstanceId);
+            log(c.green(`  ✓  Installed: ${result.manifest.instanceId}  (${result.spec.name || ""} v${result.spec.version || "?"})`));
             return;
         }
         catch (err) {
@@ -500,14 +526,14 @@ async function cmdInstall(args) {
     }
 }
 async function cmdProvides(args) {
-    const { listProvidedCapabilities } = await import("../services/app/app-manager.js");
+    const { listProvidedCapabilities } = await import("../services/app-common/service.js");
     const provides = listProvidedCapabilities();
     if (args.includes("--json")) {
         console.log(JSON.stringify(provides, null, 2));
         return;
     }
     log("");
-    log(c.bold("  App Provides"));
+    log(c.bold("  Instance Provides"));
     log(c.dim("  ─────────────────────────────────────────────────────"));
     if (provides.length === 0) {
         log(c.dim("  (no app capabilities declared)"));
@@ -516,12 +542,12 @@ async function cmdProvides(args) {
     }
     const grouped = new Map();
     for (const provide of provides) {
-        const items = grouped.get(provide.appId) ?? [];
+        const items = grouped.get(provide.instanceId) ?? [];
         items.push(provide);
-        grouped.set(provide.appId, items);
+        grouped.set(provide.instanceId, items);
     }
-    for (const [appId, items] of grouped.entries()) {
-        log(`  ${c.cyan(appId)}`);
+    for (const [instanceId, items] of grouped.entries()) {
+        log(`  ${c.cyan(instanceId)}`);
         for (const provide of items) {
             const endpoint = provide.registeredAddress ?? provide.address ?? "-";
             const registration = provide.registered
@@ -543,7 +569,7 @@ function parseOptionalFlag(args, flag) {
     return undefined;
 }
 async function cmdProviders(args) {
-    const { listConnectionProviders } = await import("../services/connection-admin.js");
+    const { listConnectionProviders } = await import("../services/connections/admin.js");
     const capability = parseOptionalFlag(args, "--capability");
     const providers = await listConnectionProviders(capability);
     if (args.includes("--json")) {
@@ -551,7 +577,7 @@ async function cmdProviders(args) {
         return;
     }
     log("");
-    log(c.bold(capability ? `  Providers for ${capability}` : "  App Providers"));
+    log(c.bold(capability ? `  Providers for ${capability}` : "  Capability Providers"));
     log(c.dim("  ─────────────────────────────────────────────────────"));
     if (providers.length === 0) {
         log(c.dim("  (no matching providers registered)"));
@@ -583,18 +609,18 @@ function describeConnectionValue(value) {
     }
     return c.yellow("invalid");
 }
-async function cmdConnections(appId, args) {
-    const { getConnectionSummary, getConnectionStatus } = await import("../services/connection-admin.js");
+async function cmdConnections(instanceId, args) {
+    const { getConnectionSummary, getConnectionStatus } = await import("../services/connections/admin.js");
     const [summary, status] = await Promise.all([
-        getConnectionSummary(appId),
-        getConnectionStatus(appId),
+        getConnectionSummary(instanceId),
+        getConnectionStatus(instanceId),
     ]);
     if (args.includes("--json")) {
         console.log(JSON.stringify({ ...summary, status }, null, 2));
         return;
     }
     log("");
-    log(`  ${c.bold("App:")}         ${c.cyan(appId)}`);
+    log(`  ${c.bold("Instance:")}    ${c.cyan(instanceId)}`);
     log(`  ${c.bold("Connections:")} ${status.state === "ok" ? c.green(status.state) : status.state === "empty" ? c.dim(status.state) : c.yellow(status.state)}`);
     if (summary.requires.length === 0) {
         log(c.dim("  (this app does not require external capabilities)"));
@@ -654,73 +680,74 @@ function parseBindArgs(args) {
             throw new Error(`Unknown option: ${arg}`);
         }
     }
-    parsed.appId = positional[0];
+    parsed.instanceId = positional[0];
     if (positional.length > 1)
         throw new Error(`Unexpected argument: ${positional[1]}`);
     return parsed;
 }
 async function cmdBind(args) {
     const parsed = parseBindArgs(args);
-    if (!parsed.appId || !parsed.slot || !parsed.providerId || !parsed.capability) {
-        throw new Error("Usage: jishushell app bind <app-id> --slot <slot> --provider <provider-app-id> --capability <capability>");
+    if (!parsed.instanceId || !parsed.slot || !parsed.providerId || !parsed.capability) {
+        throw new Error("Usage: jishushell app bind <instance-id> --slot <slot> --provider <provider-instance-id> --capability <capability>");
     }
-    const { bindConnection } = await import("../services/connection-admin.js");
+    const { bindConnection } = await import("../services/connections/admin.js");
     await bindConnection({
-        appId: parsed.appId,
+        instanceId: parsed.instanceId,
         slot: parsed.slot,
         providerId: parsed.providerId,
         capability: parsed.capability,
         ...(parsed.selectedModelId ? { selectedModelId: parsed.selectedModelId } : {}),
     });
-    log(c.green(`  ✓  Bound ${parsed.appId}:${parsed.slot} to ${parsed.providerId}/${parsed.capability}`));
+    log(c.green(`  ✓  Bound ${parsed.instanceId}:${parsed.slot} to ${parsed.providerId}/${parsed.capability}`));
 }
-async function cmdUnbind(appId, args) {
+async function cmdUnbind(instanceId, args) {
     const slot = parseOptionalFlag(args, "--slot");
     if (!slot) {
-        throw new Error("Usage: jishushell app unbind <app-id> --slot <slot>");
+        throw new Error("Usage: jishushell app unbind <instance-id> --slot <slot>");
     }
-    const { unbindConnection } = await import("../services/connection-admin.js");
-    await unbindConnection({ appId, slot });
-    log(c.green(`  ✓  Unbound ${appId}:${slot}`));
+    const { unbindConnection } = await import("../services/connections/admin.js");
+    await unbindConnection({ instanceId, slot });
+    log(c.green(`  ✓  Unbound ${instanceId}:${slot}`));
 }
 async function cmdConfig(args) {
     const subcmd = args[0];
-    const appId = args[1];
-    if (!subcmd || !appId) {
-        throw new Error("Usage: jishushell app config <get|set|meta> <app-id> [key=value]");
+    const instanceId = args[1];
+    if (!subcmd || !instanceId) {
+        throw new Error("Usage: jishushell app config <get|set|meta> <instance-id> [key=value]");
     }
     if (subcmd === "get") {
-        const { readAppConfig } = await import("../services/app-config-admin.js");
-        const config = await readAppConfig(appId);
+        const { readAppConfig } = await import("../services/instances/config-admin.js");
+        const config = await readAppConfig(instanceId);
         console.log(JSON.stringify(config, null, 2));
         return;
     }
     if (subcmd === "meta") {
-        const { getAppConfigMeta } = await import("../services/app-config-admin.js");
-        const meta = getAppConfigMeta(appId);
+        const { getAppConfigMeta } = await import("../services/instances/config-admin.js");
+        const meta = getAppConfigMeta(instanceId);
         console.log(JSON.stringify(meta, null, 2));
         return;
     }
     if (subcmd === "set") {
         const assignment = args[2];
         if (!assignment) {
-            throw new Error("Usage: jishushell app config set <app-id> <key=value>");
+            throw new Error("Usage: jishushell app config set <instance-id> <key=value>");
         }
-        const { setAppConfigValue } = await import("../services/app-config-admin.js");
-        await setAppConfigValue(appId, assignment);
-        log(c.green(`  ✓  Updated config for ${appId}`));
+        const { setAppConfigValue } = await import("../services/instances/config-admin.js");
+        await setAppConfigValue(instanceId, assignment);
+        log(c.green(`  ✓  Updated config for ${instanceId}`));
         return;
     }
-    throw new Error("Usage: jishushell app config <get|set|meta> <app-id> [key=value]");
+    throw new Error("Usage: jishushell app config <get|set|meta> <instance-id> [key=value]");
 }
 async function cmdUninstall(id, args = []) {
-    const { uninstallAppTask, getApp, getInstance } = await import("../services/app/app-manager.js");
-    if (getApp(id)) {
-        await runManagedUninstallTask((exec) => exec ? uninstallAppTask(id, exec) : uninstallAppTask(id), `Uninstalled: ${id}`, getCliSudoState(args));
+    const { uninstallInstanceTask } = await import("../services/app-common/lifecycle-service.js");
+    const { getInstanceInstallRecord, getInstance } = await import("../services/app-common/service.js");
+    if (getInstanceInstallRecord(id)) {
+        await runManagedUninstallTask((exec) => exec ? uninstallInstanceTask(id, exec) : uninstallInstanceTask(id), `Uninstalled: ${id}`, getCliSudoState(args));
         return;
     }
     if (getInstance(id)) {
-        const { deleteInstance } = await import("../services/instance-manager.js");
+        const { deleteInstance } = await import("../services/instances/manager.js");
         const deleteResult = await deleteInstance(id);
         if (!deleteResult.ok) {
             throw new Error(`Failed to uninstall instance '${id}'`);
@@ -737,13 +764,14 @@ async function cmdUninstallAll(args = []) {
         log(c.dim("  (no managed apps or instances to uninstall)"));
         return;
     }
-    const { uninstallAppTask } = await import("../services/app/app-manager.js");
-    const { deleteInstance } = await import("../services/instance-manager.js");
+    const { uninstallInstanceTask } = await import("../services/app-common/lifecycle-service.js");
+    const { getInstanceInstallRecord } = await import("../services/app-common/service.js");
+    const { deleteInstance } = await import("../services/instances/manager.js");
     const errors = [];
     const sudoState = getCliSudoState(args);
     for (const item of items) {
         try {
-            if (item.install_mode === "legacy-instance") {
+            if (!getInstanceInstallRecord(item.id)) {
                 const deleteResult = await deleteInstance(item.id);
                 if (!deleteResult.ok) {
                     throw new Error(`Failed to uninstall instance '${item.id}'`);
@@ -751,12 +779,12 @@ async function cmdUninstallAll(args = []) {
             }
             else {
                 const started = sudoState.password
-                    ? uninstallAppTask(item.id, { sudoPassword: sudoState.password })
-                    : uninstallAppTask(item.id);
+                    ? uninstallInstanceTask(item.id, { sudoPassword: sudoState.password })
+                    : uninstallInstanceTask(item.id);
                 if (!started.ok) {
                     const startedMessage = started.error || `Failed to uninstall '${item.id}'`;
                     if (isSudoPasswordError(startedMessage) && await promptForCliSudoPassword(sudoState)) {
-                        const retried = uninstallAppTask(item.id, { sudoPassword: sudoState.password });
+                        const retried = uninstallInstanceTask(item.id, { sudoPassword: sudoState.password });
                         if (!retried.ok) {
                             throw new Error(formatSudoHint(retried.error || `Failed to uninstall '${item.id}'`, sudoState));
                         }
@@ -773,7 +801,7 @@ async function cmdUninstallAll(args = []) {
                 if (taskResult.status === "error") {
                     const taskMessage = taskResult.message || `Failed to uninstall '${item.id}'`;
                     if (isSudoPasswordError(taskMessage) && await promptForCliSudoPassword(sudoState)) {
-                        const retried = uninstallAppTask(item.id, { sudoPassword: sudoState.password });
+                        const retried = uninstallInstanceTask(item.id, { sudoPassword: sudoState.password });
                         if (!retried.ok) {
                             throw new Error(formatSudoHint(retried.error || `Failed to uninstall '${item.id}'`, sudoState));
                         }
@@ -799,11 +827,11 @@ async function cmdUninstallAll(args = []) {
         process.exitCode = 1;
     }
 }
-async function cmdCreateFromInstalledApp(appId, instanceId, name, description = "") {
-    const { createFromInstalledApp, isAppCreateFromInstalledError, } = await import("../services/app-create-from-installed.js");
+async function cmdCloneInstance(sourceInstanceId, instanceId, name, description = "") {
+    const { cloneInstance, isInstanceCloneError, } = await import("../services/instances/clone.js");
     try {
-        const result = await createFromInstalledApp({
-            appId,
+        const result = await cloneInstance({
+            sourceInstanceId,
             targetId: instanceId,
             name,
             description,
@@ -816,7 +844,7 @@ async function cmdCreateFromInstalledApp(appId, instanceId, name, description =
         }
     }
     catch (e) {
-        if (isAppCreateFromInstalledError(e)) {
+        if (isInstanceCloneError(e)) {
             log(c.red(`  ✗  ${e.message}`));
             process.exitCode = 1;
             return;
@@ -825,107 +853,90 @@ async function cmdCreateFromInstalledApp(appId, instanceId, name, description =
         process.exitCode = 1;
         return;
     }
-    log(c.green(`  ✓  Created application "${instanceId}" from app "${appId}"`));
+    log(c.green(`  ✓  Cloned instance "${sourceInstanceId}" to "${instanceId}"`));
 }
 async function cmdCreate(args) {
     const parsed = parseCreateArgs(args);
     if (!parsed.id || !parsed.name) {
         throw new Error("Usage: jishushell app create <id> --name <name>");
     }
-    if (parsed.fromAppId) {
-        if (parsed.runtime || parsed.appSpecPath || parsed.appSpecUrl) {
-            throw new Error("app create --from cannot be combined with --runtime, --app-spec, or --app-spec-url");
+    if (parsed.cloneFromInstanceId) {
+        if (parsed.appSpecId) {
+            throw new Error("app create --from cannot be combined with --builtin or --app-spec-id");
         }
-        await cmdCreateFromInstalledApp(parsed.fromAppId, parsed.id, parsed.name, parsed.description || "");
+        await cmdCloneInstance(parsed.cloneFromInstanceId, parsed.id, parsed.name, parsed.description || "");
         return;
     }
-    const { createInstance } = await import("../services/instance-admin.js");
+    const { createInstance } = await import("../services/instances/admin.js");
     const result = await createInstance({
         id: parsed.id,
         name: parsed.name,
         ...(parsed.description != null ? { description: parsed.description } : {}),
-        ...(parsed.runtime ? { agentType: parsed.runtime } : {}),
-        ...(parsed.appSpecPath ? { app_spec_yaml: readFileSync(parsed.appSpecPath, "utf-8") } : {}),
-        ...(parsed.appSpecUrl ? { app_spec_url: parsed.appSpecUrl } : {}),
+        ...(parsed.appSpecId ? { app_spec_id: parsed.appSpecId } : {}),
     });
     console.log(JSON.stringify(result, null, 2));
 }
-async function cmdCopy(sourceId) {
-    const { copyApp } = await import("../services/app/app-manager.js");
-    const result = await copyApp(sourceId);
-    log(c.green(`  ✓  Copied ${sourceId}  →  ${result.manifest.id}`));
-}
-async function cmdStart(appId) {
+async function cmdStart(instanceId) {
     ensureNomadToken();
-    const { getApp, startAppTask } = await import("../services/app/app-manager.js");
-    const app = getApp(appId);
-    if (app) {
-        await runManagedAppTask(() => startAppTask(appId), `Started: ${app.spec.name || readInstanceMeta(appId)?.name || appId}`);
-        await acknowledgeRuntimeRestartAdvisory(appId);
-        return;
-    }
-    const result = await startNomadJobInstance(appId);
-    if (result.ok) {
-        await acknowledgeRuntimeRestartAdvisory(appId);
-        log(c.green(`  ✓  Started: ${readInstanceMeta(appId)?.name || appId}`));
+    const { startInstanceTask } = await import("../services/app-common/lifecycle-service.js");
+    const { getInstanceInstallRecord, getInstance } = await import("../services/app-common/service.js");
+    const app = getInstanceInstallRecord(instanceId);
+    const instance = getInstance(instanceId);
+    if (app || instance) {
+        const ok = await runManagedAppTask(() => startInstanceTask(instanceId), `Started: ${app?.spec.name || readInstanceMeta(instanceId)?.name || instanceId}`);
+        if (ok) {
+            markRuntimeRepairRestartApplied(instanceId);
+        }
         return;
     }
-    log(c.red(`  ✗  ${result.error || "Start failed"}`));
-    process.exitCode = 1;
+    await runLegacyRawRuntimeStart(instanceId);
 }
-async function cmdStop(appId, purge) {
+async function cmdStop(instanceId, purge) {
     ensureNomadToken();
-    const { getApp, stopAppTask } = await import("../services/app/app-manager.js");
-    const app = getApp(appId);
-    if (app) {
-        await runManagedAppTask(() => stopAppTask(appId, purge), `Stopped: ${app.spec.name || readInstanceMeta(appId)?.name || appId}${purge ? " (purged)" : ""}`);
-        return;
-    }
-    const result = await stopNomadJobInstance(appId, purge);
-    if (result.ok) {
-        log(c.green(`  ✓  Stopped: ${readInstanceMeta(appId)?.name || appId}${purge ? " (purged)" : ""}`));
+    const { stopInstanceTask } = await import("../services/app-common/lifecycle-service.js");
+    const { getInstanceInstallRecord, getInstance } = await import("../services/app-common/service.js");
+    const app = getInstanceInstallRecord(instanceId);
+    const instance = getInstance(instanceId);
+    if (app || instance) {
+        await runManagedAppTask(() => stopInstanceTask(instanceId, purge), `Stopped: ${app?.spec.name || readInstanceMeta(instanceId)?.name || instanceId}${purge ? " (purged)" : ""}`);
         return;
     }
-    log(c.red(`  ✗  ${result.error || "Stop failed"}`));
-    process.exitCode = 1;
+    await runLegacyRawRuntimeStop(instanceId, purge);
 }
-async function cmdRestart(appId) {
+async function cmdRestart(instanceId) {
     ensureNomadToken();
-    const { getApp, restartAppTask } = await import("../services/app/app-manager.js");
-    const app = getApp(appId);
-    if (app) {
-        await runManagedAppTask(() => restartAppTask(appId), `Restarted: ${app.spec.name || readInstanceMeta(appId)?.name || appId}`);
-        await acknowledgeRuntimeRestartAdvisory(appId);
-        return;
-    }
-    const result = await restartNomadJobInstance(appId);
-    if (result.ok) {
-        await acknowledgeRuntimeRestartAdvisory(appId);
-        log(c.green(`  ✓  Restarted: ${readInstanceMeta(appId)?.name || appId}`));
+    const { restartInstanceTask } = await import("../services/app-common/lifecycle-service.js");
+    const { getInstanceInstallRecord, getInstance } = await import("../services/app-common/service.js");
+    const app = getInstanceInstallRecord(instanceId);
+    const instance = getInstance(instanceId);
+    if (app || instance) {
+        const ok = await runManagedAppTask(() => restartInstanceTask(instanceId), `Restarted: ${app?.spec.name || readInstanceMeta(instanceId)?.name || instanceId}`);
+        if (ok) {
+            markRuntimeRepairRestartApplied(instanceId);
+        }
         return;
     }
-    log(c.red(`  ✗  ${result.error || "Restart failed"}`));
-    process.exitCode = 1;
+    await runLegacyRawRuntimeRestart(instanceId);
 }
-async function cmdStatus(appId, json) {
+async function cmdStatus(instanceId, json) {
     ensureNomadToken();
-    const { getApp, getAppStatus, getInstance } = await import("../services/app/app-manager.js");
-    const app = getApp(appId);
+    const { getInstanceInstallRecord, getInstanceInstallRecordStatus, getInstance } = await import("../services/app-common/service.js");
+    const app = getInstanceInstallRecord(instanceId);
     if (!app) {
-        const instance = getInstance(appId);
+        const instance = getInstance(instanceId);
         if (!instance) {
-            log(c.red(`  ✗  App/instance "${appId}" not found.`));
+            log(c.red(`  ✗  Instance "${instanceId}" not found.`));
             process.exitCode = 1;
             return;
         }
-        const status = await getInstanceStatus(appId);
+        const status = await getInstanceStatus(instanceId);
         if (json) {
-            console.log(JSON.stringify({ id: appId, name: instance.name, ...status }, null, 2));
+            console.log(JSON.stringify({ id: instanceId, name: instance.name, ...status }, null, 2));
             return;
         }
         const upStr = status.uptime ? `${Math.floor(status.uptime / 3600)}h ${Math.floor((status.uptime % 3600) / 60)}m` : "—";
         log("");
-        log(`  ${c.bold("Job:")} ${c.cyan(instance.name || appId)}  ${c.dim(`(${appId})`)}`);
+        log(`  ${c.bold("Job:")} ${c.cyan(instance.name || instanceId)}  ${c.dim(`(${instanceId})`)}`);
         log(`  ${c.bold("Status:")} ${status.status === "running" ? c.green(status.status) : status.status}`);
         log(`  ${c.bold("Uptime:")} ${upStr}`);
         if (status.memory_mb)
@@ -937,10 +948,10 @@ async function cmdStatus(appId, json) {
         log("");
         return;
     }
-    const status = await getAppStatus(appId);
-    const enriched = enrichStatusForCli(status, app.spec);
+    const status = await getInstanceInstallRecordStatus(instanceId);
+    const enriched = enrichStatusForCli(instanceId, status, app.spec);
     if (json) {
-        console.log(JSON.stringify({ id: appId, ...status, tasks: enriched.tasks, provides: enriched.provides }, null, 2));
+        console.log(JSON.stringify({ id: instanceId, ...status, tasks: enriched.tasks, provides: enriched.provides }, null, 2));
         return;
     }
     const stColor = status.status === "running" ? c.green
@@ -948,7 +959,7 @@ async function cmdStatus(appId, json) {
             : status.status === "pending" ? c.yellow
                 : c.red;
     log("");
-    log(`  ${c.bold("App:")}    ${c.cyan(appId)}`);
+    log(`  ${c.bold("Instance:")} ${c.cyan(instanceId)}`);
     log(`  ${c.bold("Status:")} ${stColor(status.status)}`);
     if (status.uptime != null)
         log(`  ${c.bold("Uptime:")} ${status.uptime}s`);
@@ -977,27 +988,48 @@ async function cmdStatus(appId, json) {
         log(c.red(`  ${status.error}`));
     log("");
 }
-async function cmdLogs(appId, args) {
+async function cmdLogs(instanceId, args) {
     ensureNomadToken();
-    const { getApp, getAppLogs } = await import("../services/app/app-manager.js");
+    const { getInstanceInstallRecord, getInstanceInstallRecordLogs } = await import("../services/app-common/service.js");
     const taskArg = args.find((a) => !a.startsWith("--"));
     const lines = parseFlag(args, "--lines", 200);
     const logType = args.includes("--stdout") ? "stdout" : "stderr";
-    const logLines = getApp(appId)
-        ? await getAppLogs(appId, taskArg ?? "", lines, logType)
-        : await getInstanceLogs(appId, lines, logType);
+    const logLines = getInstanceInstallRecord(instanceId)
+        ? await getInstanceInstallRecordLogs(instanceId, taskArg ?? "", lines, logType)
+        : await getInstanceLogs(instanceId, lines, logType);
     if (logLines.length === 0) {
         log(c.dim("  (no logs)"));
         return;
     }
     process.stdout.write(logLines.join("\n") + "\n");
 }
-async function cmdExec(appId, command) {
+function parseExecArgs(args) {
+    const dashDash = args.indexOf("--");
+    if (dashDash < 0)
+        return { command: [], error: "missing command separator" };
+    const options = args.slice(0, dashDash);
+    const command = args.slice(dashDash + 1);
+    let user;
+    for (let i = 0; i < options.length; i += 1) {
+        const arg = options[i];
+        if (arg === "--user" || arg === "-u") {
+            const value = options[i + 1];
+            if (!value || value.startsWith("-"))
+                return { command, error: `${arg} requires a value` };
+            user = value;
+            i += 1;
+            continue;
+        }
+        return { command, error: `unknown exec option: ${arg}` };
+    }
+    return { command, user };
+}
+async function cmdExec(instanceId, command, options = {}) {
     ensureNomadToken();
-    const { getApp, execInApp } = await import("../services/app/app-manager.js");
-    const result = getApp(appId)
-        ? await execInApp(appId, command)
-        : await execInInstance(appId, command);
+    const { getInstanceInstallRecord, execInApp } = await import("../services/app-common/service.js");
+    const result = getInstanceInstallRecord(instanceId)
+        ? await execInApp(instanceId, command, undefined, options)
+        : await execInInstance(instanceId, command, undefined, options);
     if (result.stdout)
         process.stdout.write(result.stdout);
     if (result.stderr)
@@ -1045,9 +1077,6 @@ export async function run(rest) {
         else if (appCmd === "create") {
             await cmdCreate(rest.slice(1));
         }
-        else if (appCmd === "copy" && rest[1]) {
-            await cmdCopy(rest[1]);
-        }
         else if (appCmd === "start" && rest[1]) {
             await cmdStart(rest[1]);
         }
@@ -1064,13 +1093,14 @@ export async function run(rest) {
             await cmdLogs(rest[1], rest.slice(2));
         }
         else if (appCmd === "exec" && rest[1]) {
-            const dashDash = rest.indexOf("--");
-            const execCmd = dashDash >= 0 ? rest.slice(dashDash + 1) : [];
-            if (execCmd.length === 0) {
-                console.error("Usage: jishushell app exec <app-id> -- <command...>");
+            const parsed = parseExecArgs(rest.slice(2));
+            if (parsed.command.length === 0 || parsed.error) {
+                if (parsed.error && parsed.error !== "missing command separator")
+                    console.error(parsed.error);
+                console.error("Usage: jishushell app exec <instance-id> [--user <user>|-u <user>] -- <command...>");
                 process.exit(1);
             }
-            await cmdExec(rest[1], execCmd);
+            await cmdExec(rest[1], parsed.command, { user: parsed.user });
         }
         else if (appCmd === "help" || appCmd === "--help" || appCmd === "-h") {
             printHelp();
@@ -1093,42 +1123,44 @@ export async function dispatch(argv) {
     return true;
 }
 export function brief() {
-    return "  app <create|install|providers|connections|bind|config|start|status>  App 统一管理";
+    return "  app <create|install|providers|connections|bind|config|start|status>  实例与 AppSpec 安装管理";
 }
 export function printHelp() {
     console.log(`
 Usage: jishushell app <command> [options]
 
 Commands:
-  create <id> --name <name> [--runtime <runtime>]  创建 App（默认 runtime=openclaw）
-  create <id> --name <name> --from <app-id>        从已安装 App 派生新 App
-  list [--json]                                     列出统一受管列表（apps 下已安装应用 + instances 下遗留实例）
-  provides [--json]                                 列出已安装 App 声明/注册的能力
+  create <id> --name <name> [--builtin <builtin-id>]
+                                                    按 builtin AppSpec 创建实例（默认 builtin=openclaw-container）
+  create <id> --name <name> --from <instance-id>   从已有实例克隆一个新实例
+  list [--json]                                     列出受管实例
+  provides [--json]                                 列出实例声明/注册的能力
   providers [--capability <name>] [--json]          列出可绑定 provider
-  connections <app-id> [--json]                     查看 App 依赖能力与绑定状态
-  bind <app-id> --slot <slot> --provider <id> --capability <capability>
-                                                    绑定 App 依赖能力到 provider
-  unbind <app-id> --slot <slot>                     解除 App 能力绑定
-  config get <app-id>                               查看 App 配置
-  config set <app-id> <key=value>                   修改 App 配置字段
-  config meta <app-id>                              查看 App 配置元信息
-  show <id>                                         查看 App 或实例详情（JSON）
-  install <yaml-file|https-url|builtin-id> [app-id] [--sudo-password <password>]
-                                                    从本地、HTTPS 或内置模板安装 App，可选指定安装 id
-  uninstall <app-id> [--sudo-password <password>]   卸载单个 App 或实例（停止 + 删除目录）
-  uninstall --all [--sudo-password <password>]      卸载全部 App 与实例
-  copy <app-id>                                     复制 App 实例（singleInstance 不可 copy）
-  start <id>                                        启动 App 或实例
-  stop <id> [--purge]                               停止 App 或实例（--purge 同时清除 Nomad job）
-  restart <id>                                      重启 App 或实例
-  status <id> [--json]                              查看 App 或实例状态
+  connections <instance-id> [--json]                查看实例依赖能力与绑定状态
+  bind <instance-id> --slot <slot> --provider <id> --capability <capability>
+                                                    绑定实例依赖能力到 provider 实例
+  unbind <instance-id> --slot <slot>                解除实例能力绑定
+  config get <instance-id>                          查看实例配置
+  config set <instance-id> <key=value>              修改实例配置字段
+  config meta <instance-id>                         查看实例配置元信息
+  show <id>                                         查看实例详情（JSON）
+  install <yaml-file|https-url|builtin-id> [instance-id] [--sudo-password <password>]
+                                                    从本地、HTTPS 或内置 AppSpec 安装实例，可选指定实例 id
+  uninstall <instance-id> [--sudo-password <password>]
+                                                    卸载单个实例（停止 + 删除目录）
+  uninstall --all [--sudo-password <password>]      卸载全部实例
+  start <id>                                        启动实例
+  stop <id> [--purge]                               停止实例（--purge 同时清除 Nomad job）
+  restart <id>                                      重启实例
+  status <id> [--json]                              查看实例状态
   logs <id> [<task>] [--lines N] [--stdout]         查看日志（默认 stderr）
-  exec <id> -- <cmd...>                             在 App 或实例内执行命令
+  exec <id> -- <cmd...>                             在实例内执行命令
   help                                              显示此帮助
 
 Examples:
   jishushell app create my-openclaw --name MyOpenClaw
-  jishushell app create my-hermes --name MyHermes --runtime hermes
+  jishushell app create my-hermes --name MyHermes --builtin hermes-container
+  jishushell app create my-ollama --name MyOllama --builtin ollama-with-hollama-binary
   jishushell app create my-searxng-2 --name MySearxng2 --from my-searxng
   jishushell app install ./apps/ollama-with-hollama-binary.yaml
   jishushell app install ./apps/ollama-with-hollama-binary.yaml ollama-local
@@ -1141,7 +1173,6 @@ Examples:
   jishushell app bind my-openclaw --slot search --provider searxng --capability search-searxng
   jishushell app config get my-openclaw
   jishushell app config set my-openclaw x-jishushell.proxy.upstream.providerId=ollama
-  jishushell app copy ollama-1
   jishushell app start searxng-container
   jishushell app status ollama
   jishushell app logs ollama --lines 100