create-principles-disciple 1.104.0 → 1.104.2

package/dist/installer.js

@@ -4,9 +4,12 @@ import * as path from 'path';
 import * as http from 'http';
 import { execSync, execFileSync, spawn } from 'child_process';
 import ora from 'ora';
+import { select } from '@inquirer/prompts';
 import { logger } from './utils/logger.js';
-import { checkOpenClawGateway } from './utils/env.js';
-import { generateConfigYamlContent, getConfigYamlPath, validateConfigYamlFull, readEnabledChannelsFromConfigYaml, getOpenClawDir, getPluginExtDir, getInstalledPdCliDir, getInstalledBinDir, getInstalledConsoleDir, isWindows, validateOpenClawConfig, } from './mvp-config.js';
+import { checkOpenClawGateway, stopOpenClawGateway, restartOpenClawGateway } from './utils/env.js';
+import { t } from './i18n.js';
+import { generateConfigYamlContent, getConfigYamlPath, validateConfigYamlFull, readEnabledChannelsFromConfigYaml, getOpenClawDir, getPluginExtDir, getInstalledPdCliDir, getInstalledBinDir, getInstalledConsoleDir, isWindows, } from './mvp-config.js';
+import { getHostInstallers } from './installers/index.js';
 /** PRI-343: Keep in sync with @principles/core CONVERSATION_ACCESS_CONFIG_KEY */
 export const CONVERSATION_ACCESS_CONFIG_KEY = 'allowConversationAccess';
 function isRecord(value) {
@@ -84,8 +87,8 @@ async function runNpmInstall(cwd, componentName = 'npm') {
     }
     catch (e) {
         const errorMsg = e instanceof Error ? e.message : String(e);
-        // 动态导入 i18n 以避免循环依赖
-        const { t } = await import('./i18n.js');
+        // `t` is the module-level i18n translator (imported at top of file).
+        // i18n.ts has no imports, so there is no circular dependency.
         const hint = errorMsg.includes('ETIMEDOUT') || errorMsg.includes('network') || errorMsg.includes('timeout')
             ? t('npm_hint_network_timeout').replace('{path}', cwd)
             : errorMsg.includes('EACCES') || errorMsg.includes('permission') || errorMsg.includes('EPERM')
@@ -144,20 +147,20 @@ const INSTALL_STEPS = [
     { name: 'Installing bundled @principles/core', weight: 8 },
     { name: 'Installing core dependencies', weight: 10 },
     { name: 'Installing plugin', weight: 10 },
-    { name: 'Pre-filling @principles/core for plugin', weight: 3 },
+    { name: 'Preparing core library for plugin', weight: 3 },
     { name: 'Installing plugin dependencies', weight: 20 },
     { name: 'Installing pd CLI', weight: 8 },
-    { name: 'Pre-filling @principles/core for pd-cli', weight: 3 },
+    { name: 'Preparing core library for pd-cli', weight: 3 },
     { name: 'Verifying pd CLI', weight: 3 },
     { name: 'Installing pd-console', weight: 8 },
-    { name: 'Pre-filling @principles/core for console', weight: 3 },
+    { name: 'Preparing core library for console', weight: 3 },
     { name: 'Installing console dependencies', weight: 10 },
     { name: 'Verifying pd-console', weight: 3 },
     { name: 'Copying templates', weight: 3 },
     { name: 'Generating config.yaml', weight: 2 },
     { name: 'Creating config', weight: 2 },
-    { name: 'Verifying pd demo story-a', weight: 5 },
-    { name: 'Updating OpenClaw config', weight: 3 },
+    { name: 'Verifying demo', weight: 5 },
+    { name: 'Updating host config', weight: 3 },
 ];
 const TOTAL_WEIGHT = INSTALL_STEPS.reduce((sum, step) => sum + step.weight, 0);
 function updateProgress(spinner, currentStep, message) {
@@ -213,6 +216,52 @@ function cleanupBackup(backupDir) {
         // non-fatal
     }
 }
+/**
+ * Decide how to handle a running gateway.
+ * - --stop-gateway flag → 'stop' (auto-stop, no prompt, even in interactive).
+ * - non-interactive (quiet/--json/--yes) without the flag → 'abort' (refuse
+ *   cleanly; rc-9: do NOT silently proceed into a known failure).
+ * - interactive without the flag → warn + 3-way prompt (stop / proceed / abort).
+ */
+async function resolveGatewayAction(status, opts) {
+    if (opts.stopGateway)
+        return 'stop';
+    if (!opts.interactive)
+        return 'abort';
+    const portInfo = status.port ? ` (port ${status.port})` : '';
+    const pidInfo = status.pid ? `, PID ${status.pid}` : '';
+    logger.warn(`${t('gateway_running')}${portInfo}${pidInfo}.`);
+    logger.warn(t('gateway_lock_warning'));
+    const choice = await select({
+        message: t('gateway_prompt_title'),
+        choices: [
+            { value: 'stop', name: t('gateway_choice_stop') },
+            { value: 'proceed', name: t('gateway_choice_proceed') },
+            { value: 'abort', name: t('gateway_choice_abort') },
+        ],
+    });
+    return choice;
+}
+/**
+ * Structured failure result for a gateway pre-flight refusal — either the run
+ * aborted (gateway running, not stopped) or --stop-gateway was requested but
+ * `openclaw gateway stop` failed. All components stay 'skipped': both refusal
+ * paths return before any mutation (cli-5).
+ */
+function buildGatewayRefusalResult(options, detail) {
+    return {
+        success: false,
+        workspaceDir: options.workspaceDir,
+        configYamlPath: getConfigYamlPath(options.workspaceDir),
+        templatesCount: 0,
+        components: { plugin: 'skipped', cli: 'skipped', console: 'skipped' },
+        verification: { features: 'skipped', storyA: 'skipped' },
+        enabledChannels: options.channels,
+        nextAction: detail.nextAction,
+        reason: detail.reason,
+        ...(detail.error !== undefined ? { error: detail.error } : {}),
+    };
+}
 export async function checkBuiltPlugin(pluginDir) {
     const distDir = path.join(pluginDir, 'plugin', 'dist');
     const pluginJson = path.join(pluginDir, 'plugin', 'openclaw.plugin.json');
@@ -254,98 +303,11 @@ async function installPluginToStaging(pluginDir) {
     await fse.ensureDir(extDir);
     await fse.copy(builtPluginDir, extDir, { overwrite: true });
 }
-async function updateOpenClawConfig() {
-    const configDir = getOpenClawDir();
-    const configPath = path.join(configDir, 'openclaw.json');
-    if (!existsSync(configPath))
-        return;
-    const rawConfig = readFileSync(configPath, 'utf-8');
-    const config = JSON.parse(rawConfig);
-    const validation = validateOpenClawConfig(config);
-    if (!validation.valid) {
-        throw new Error(`Malformed openclaw.json: ${validation.error}. Fix manually and re-run installer.`);
-    }
-    if (config === null || typeof config !== 'object' || Array.isArray(config))
-        return;
-    const configObj = { ...config };
-    if (!configObj.plugins)
-        configObj.plugins = {};
-    if (typeof configObj.plugins !== 'object' || configObj.plugins === null || Array.isArray(configObj.plugins)) {
-        throw new Error('openclaw.json plugins field is malformed. Fix manually and re-run installer.');
-    }
-    const plugins = { ...configObj.plugins };
-    if (!plugins.allow)
-        plugins.allow = [];
-    if (!Array.isArray(plugins.allow)) {
-        throw new Error('openclaw.json plugins.allow is not an array. Fix manually and re-run installer.');
-    }
-    const allow = plugins.allow.filter((a) => typeof a === 'string');
-    if (!allow.includes('principles-disciple')) {
-        allow.push('principles-disciple');
-    }
-    plugins.allow = allow;
-    if (!plugins.entries)
-        plugins.entries = {};
-    if (typeof plugins.entries !== 'object' || plugins.entries === null || Array.isArray(plugins.entries)) {
-        throw new Error('openclaw.json plugins.entries is malformed. Fix manually and re-run installer.');
-    }
-    const entries = { ...plugins.entries };
-    // Merge with existing config — preserve hooks, config, and other user settings
-    const existingEntry = (typeof entries['principles-disciple'] === 'object' && entries['principles-disciple'] !== null && !Array.isArray(entries['principles-disciple']))
-        ? { ...entries['principles-disciple'] }
-        : {};
-    entries['principles-disciple'] = { ...existingEntry, enabled: true };
-    plugins.entries = entries;
-    // Do NOT write plugins.installs — OpenClaw manages install records in
-    // ~/.openclaw/plugins/installs.json and strips plugins.installs from
-    // openclaw.json on every write. Writing it here causes duplicate
-    // registration and config corruption loops.
-    // PRI-343: Deep-merge allowConversationAccess: true into the config
-    // This ensures the field survives openclaw doctor --fix backup restores
-    const mergedConfigObj = ensureConversationAccess(configObj);
-    writeFileSync(configPath, JSON.stringify(mergedConfigObj, null, 2));
-    // Write install record to installs.json (the canonical store)
-    const installsDir = path.join(configDir, 'plugins');
-    const installsPath = path.join(installsDir, 'installs.json');
-    try {
-        if (!existsSync(installsDir)) {
-            mkdirSync(installsDir, { recursive: true });
-        }
-        let installs = { version: 1, installRecords: {} };
-        if (existsSync(installsPath)) {
-            const raw = readFileSync(installsPath, 'utf-8');
-            const parsed = JSON.parse(raw);
-            if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
-                installs = parsed;
-            }
-        }
-        if (!installs.installRecords || typeof installs.installRecords !== 'object') {
-            installs.installRecords = {};
-        }
-        const extDir = getPluginExtDir();
-        const pkgPath = path.join(extDir, 'package.json');
-        let version = undefined;
-        if (existsSync(pkgPath)) {
-            try {
-                const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
-                if (typeof pkg === 'object' && pkg !== null && Object.hasOwn(pkg, 'version')) {
-                    version = pkg.version;
-                }
-            }
-            catch { /* ignore */ }
-        }
-        installs.installRecords['principles-disciple'] = {
-            source: 'path',
-            installPath: extDir,
-            ...(version ? { version } : {}),
-            installedAt: new Date().toISOString(),
-        };
-        writeFileSync(installsPath, JSON.stringify(installs, null, 2));
-    }
-    catch {
-        // Non-fatal — installs.json is managed by OpenClaw and will self-heal
-    }
-}
+// ADR-0020 §2.3: The OpenClaw config write logic previously lived here as
+// `updateOpenClawConfig()`. It has been extracted to OpenClawHostInstaller
+// (./installers/openclaw-host-installer.ts) and is invoked via
+// `runHostInstallers()` below. This file no longer writes openclaw.json
+// directly — the HostInstaller interface keeps install/uninstall host-agnostic.
 async function installPluginDependencies() {
     const extDir = getPluginExtDir();
     const packageJsonPath = path.join(extDir, 'package.json');
@@ -392,6 +354,14 @@ function getNpmGlobalBinDir() {
     }
 }
 function installGlobalPdShim() {
+    // Allow skipping global shim installation in smoke tests to avoid
+    // polluting the host's npm global bin dir. The bundled pd-cli is
+    // still installed locally (getInstalledBinDir); only the global
+    // symlink/shim is skipped. Mirrors PD_SKIP_NPM_UPGRADE pattern.
+    if (process.env.PD_SKIP_GLOBAL_SHIM === '1' || process.env.PD_SKIP_GLOBAL_SHIM === 'true') {
+        logger.info('Skipping global pd shim installation (PD_SKIP_GLOBAL_SHIM set).');
+        return false;
+    }
     const globalBin = getNpmGlobalBinDir();
     if (!globalBin)
         return false;
@@ -529,7 +499,8 @@ function syncPdCli(pluginDir) {
             symlinkSync(pdLinkTarget, pdLinkPath, 'junction');
         }
         else {
-            // Relative from <ext>/pd-cli/node_modules/ to <ext>/: go up twice (node_modules → pd-cli → ext)
+            // Relative from <ext>/pd-cli/node_modules/ to <ext>/: go up twice
+            // (node_modules → pd-cli → ext)
             symlinkSync('../../', pdLinkPath, 'dir');
         }
     }
@@ -660,6 +631,14 @@ async function verifyConsole(workspaceDir) {
     if (!existsSync(serverEntry)) {
         return { ok: false, url: '', process: null, reason: 'Console server entry not found' };
     }
+    // EP-06 regression guard (PR #1169): verify the web UI bundle exists BEFORE
+    // spawning the server. Without dist/web/index.html the server returns 404
+    // "Run npm run build:ui first" on every route — a fatal first-impression bug
+    // for new users. npm install --ignore-scripts can remove dist/ in edge cases.
+    const webIndex = path.join(consoleDest, 'dist', 'web', 'index.html');
+    if (!existsSync(webIndex)) {
+        return { ok: false, url: '', process: null, reason: 'Console web UI (dist/web/index.html) not found — bundle may be corrupted or npm install removed dist/. Re-run: npx create-principles-disciple' };
+    }
     // Build a shuffled port list to avoid retrying the same port
     const portRange = [];
     for (let p = CONSOLE_PORT_RANGE_MIN; p <= CONSOLE_PORT_RANGE_MAX; p++)
@@ -945,26 +924,51 @@ async function copyPrinciplesLayer(opts) {
     }
     return count;
 }
-async function generateConfigYamlConfig(workspaceDir) {
+async function generateConfigYamlConfig(workspaceDir, runtimeProfile) {
     const configPath = getConfigYamlPath(workspaceDir);
     const configDir = path.dirname(configPath);
-    // PRI-308: preserve existing valid config.yaml
-    if (existsSync(configPath)) {
-        try {
-            validateConfigYamlFull(workspaceDir);
-            // Existing config is structurally valid — preserve it
-            logger.info(`Existing .pd/config.yaml is valid, preserving it`);
-            return configPath;
-        }
-        catch (e) {
-            // Existing config is malformed — fail loud, do not overwrite
-            const reason = e instanceof Error ? e.message : String(e);
-            throw new Error(`Existing .pd/config.yaml is malformed: ${reason}. Delete the file and re-run the installer, or fix it manually.`, { cause: e });
+    await fse.ensureDir(configDir);
+    // Fix-4 (P0-BUG-4): pass through the runtime profile so the generated
+    // config.yaml's pd.default profile is pre-filled (avoids silent LLM
+    // failures on first run).
+    // CodeQL TOCTOU fix: use 'wx' (exclusive create) instead of existsSync
+    // + default write. The 'wx' flag atomically creates the file and fails
+    // with EEXIST if it already exists — eliminating the race between a
+    // separate check and the write. If the file exists (pre-existing or
+    // created concurrently), EEXIST is caught below and we preserve the
+    // existing config (PRI-308).
+    try {
+        writeFileSync(configPath, generateConfigYamlContent(runtimeProfile), { encoding: 'utf8', flag: 'wx' });
+        return configPath;
+    }
+    catch (err) {
+        // rc-2: instanceof Error is the runtime guard; the cast extends the type
+        // with the optional `code` property present on Node.js fs errors.
+        if (!(err instanceof Error) || err.code !== 'EEXIST')
+            throw err;
+    }
+    // PRI-308: preserve existing valid config.yaml (file exists — either
+    // pre-existing or created concurrently between ensureDir and writeFileSync).
+    try {
+        validateConfigYamlFull(workspaceDir);
+        // Existing config is structurally valid — preserve it
+        logger.info(`Existing .pd/config.yaml is valid, preserving it`);
+        // rc-9-no-silent-fallback: when the user supplied a runtimeProfile via
+        // --provider/--api-key-env but an existing valid config.yaml was found,
+        // the profile is NOT written. Emit a clear warning so the user knows
+        // their --provider/--api-key-env flags were ignored and how to update
+        // the profile manually.
+        if (runtimeProfile) {
+            logger.warn(`--provider/--api-key-env were provided but an existing valid .pd/config.yaml was found. ` +
+                `The runtime profile was not written. To update it, edit .pd/config.yaml or run: pd console open --workspace "${workspaceDir}"`);
         }
+        return configPath;
+    }
+    catch (e) {
+        // Existing config is malformed — fail loud, do not overwrite
+        const reason = e instanceof Error ? e.message : String(e);
+        throw new Error(`Existing .pd/config.yaml is malformed: ${reason}. Delete the file and re-run the installer, or fix it manually.`, { cause: e });
     }
-    await fse.ensureDir(configDir);
-    writeFileSync(configPath, generateConfigYamlContent(), 'utf8');
-    return configPath;
 }
 async function createConfigFile(workspaceDir, channels) {
     const configDir = getOpenClawDir();
@@ -997,15 +1001,81 @@ async function createConfigFile(workspaceDir, channels) {
     await fse.ensureDir(configDir);
     await fse.writeJson(configPath, config, { spaces: 2 });
 }
-export async function install(options, pluginDir, quiet = false) {
+/**
+ * ADR-0020 §2.3: Run host installers for the selected HostTarget.
+ *
+ * Iterates the concrete HostInstaller instances returned by getHostInstallers()
+ * and calls install() on each. Returns an array of results — one per host.
+ *
+ * rc-9: failures in one host do NOT abort the other (e.g. if Codex adapter
+ * is missing, OpenClaw install still succeeds). Each result includes a
+ * structured reason + nextAction.
+ */
+async function runHostInstallers(host, ctx) {
+    const installers = getHostInstallers(host);
+    const results = [];
+    for (const installer of installers) {
+        try {
+            const result = await installer.install(ctx);
+            results.push(result);
+        }
+        catch (err) {
+            // rc-9: never silently swallow — record as failure with reason.
+            results.push({
+                success: false,
+                hostId: installer.hostId,
+                configAction: 'skipped',
+                reason: `Installer threw: ${err instanceof Error ? err.message : String(err)}`,
+                nextAction: `Check ${installer.hostId} host configuration and re-run: npx create-principles-disciple install --host ${installer.hostId}`,
+            });
+        }
+    }
+    return results;
+}
+export async function install(options, pluginDir, mode = {}) {
+    // `quiet` (= jsonMode) suppresses human output / spinner. `nonInteractive`
+    // (--yes/--non-interactive/--json) gates PROMPTING. They differ for `--yes`
+    // (human output on, but must NOT prompt). nonInteractive defaults to quiet
+    // because jsonMode always implies non-interactive.
+    const quiet = mode.quiet === true;
+    const nonInteractive = mode.nonInteractive ?? quiet;
+    // Gateway lock pre-flight: a running gateway holds native-module file handles
+    // that make the backup rename fail with EPERM. Decide stop/abort/proceed
+    // BEFORE mutating anything (cli-5: abort/stop-failed paths must not mutate).
+    let restartedGateway = false;
     const gatewayStatus = await checkOpenClawGateway();
     if (gatewayStatus.isRunning) {
-        const portInfo = gatewayStatus.port ? ` (port ${gatewayStatus.port})` : '';
-        const pidInfo = gatewayStatus.pid ? `, PID ${gatewayStatus.pid}` : '';
-        logger.warn(`OpenClaw gateway is running${portInfo}${pidInfo}.`);
-        logger.warn('This may cause file lock issues during installation (EPERM on native modules).');
-        logger.warn('Recommendation: stop OpenClaw first with "openclaw gateway stop", then re-run the installer.');
-        logger.warn('Proceeding anyway — if installation fails, stop OpenClaw and retry.\n');
+        const action = await resolveGatewayAction(gatewayStatus, {
+            stopGateway: options.stopGateway,
+            interactive: !nonInteractive,
+        });
+        if (action === 'abort') {
+            logger.warn(t('gateway_aborted_reason'));
+            return buildGatewayRefusalResult(options, {
+                reason: `gateway_running_aborted: ${t('gateway_aborted_reason')}`,
+                nextAction: t('gateway_aborted_next'),
+            });
+        }
+        if (action === 'stop') {
+            if (!quiet)
+                logger.info(t('gateway_stopping'));
+            const stopRes = await stopOpenClawGateway();
+            if (!stopRes.ok) {
+                logger.error(`${t('gateway_stop_failed')} ${stopRes.error ?? ''}`);
+                return buildGatewayRefusalResult(options, {
+                    reason: `gateway_stop_failed: ${t('gateway_stop_failed_reason')}${stopRes.error ? ` — ${stopRes.error}` : ''}`,
+                    nextAction: t('gateway_stop_failed_next'),
+                    error: stopRes.error,
+                });
+            }
+            if (!quiet)
+                logger.success(t('gateway_stopped'));
+            restartedGateway = true; // restart after install, even on failure
+        }
+        else {
+            // action === 'proceed': user accepted the risk of EPERM.
+            logger.warn(t('gateway_proceed_warn'));
+        }
     }
     const spinner = quiet ? null : ora('Installing...').start();
     let backupDir = null;
@@ -1050,7 +1120,7 @@ export async function install(options, pluginDir, quiet = false) {
         await installPluginToStaging(pluginDir);
         stepIndex++;
         if (spinner)
-            updateProgress(spinner, stepIndex, 'Pre-filling @principles/core for plugin...');
+            updateProgress(spinner, stepIndex, 'Preparing core library for plugin...');
         ensureCoreDependency(getPluginExtDir());
         stepIndex++;
         if (spinner)
@@ -1063,7 +1133,7 @@ export async function install(options, pluginDir, quiet = false) {
         syncPdCli(pluginDir);
         stepIndex++;
         if (spinner)
-            updateProgress(spinner, stepIndex, 'Pre-filling @principles/core for pd-cli...');
+            updateProgress(spinner, stepIndex, 'Preparing core library for pd-cli...');
         ensureCoreDependency(getInstalledPdCliDir());
         stepIndex++;
         if (spinner)
@@ -1086,7 +1156,7 @@ export async function install(options, pluginDir, quiet = false) {
         installConsole(pluginDir);
         stepIndex++;
         if (spinner)
-            updateProgress(spinner, stepIndex, 'Pre-filling @principles/core for console...');
+            updateProgress(spinner, stepIndex, 'Preparing core library for console...');
         ensureCoreDependency(getInstalledConsoleDir());
         stepIndex++;
         if (spinner)
@@ -1122,7 +1192,7 @@ export async function install(options, pluginDir, quiet = false) {
         stepIndex++;
         if (spinner)
             updateProgress(spinner, stepIndex, 'Generating config.yaml...');
-        const configYamlPath = await generateConfigYamlConfig(options.workspaceDir);
+        const configYamlPath = await generateConfigYamlConfig(options.workspaceDir, options.runtimeProfile);
         verification.features = 'passed';
         stepIndex++;
         if (spinner)
@@ -1146,7 +1216,7 @@ export async function install(options, pluginDir, quiet = false) {
         }
         stepIndex++;
         if (spinner)
-            updateProgress(spinner, stepIndex, 'Verifying pd demo story-a...');
+            updateProgress(spinner, stepIndex, 'Verifying demo...');
         try {
             const installedPdCliEntry = path.join(getInstalledPdCliDir(), 'dist', 'index.js');
             execFileSync(process.execPath, [installedPdCliEntry, 'demo', 'story-a', '--json', '--workspace', options.workspaceDir], {
@@ -1156,15 +1226,49 @@ export async function install(options, pluginDir, quiet = false) {
             verification.storyA = 'passed';
         }
         catch (e) {
-            throw new Error(`Story A demo verification failed: ${e instanceof Error ? e.message : String(e)}. Installation rolled back — plugin and CLI are not activated.`, { cause: e });
+            throw new Error(`Demo verification failed: ${e instanceof Error ? e.message : String(e)}. Installation rolled back — plugin and CLI are not activated.`, { cause: e });
         }
         stepIndex++;
         if (spinner)
-            updateProgress(spinner, stepIndex, 'Updating OpenClaw config...');
-        await updateOpenClawConfig();
+            updateProgress(spinner, stepIndex, 'Updating host config...');
+        const hostResults = await runHostInstallers(options.host, {
+            workspaceDir: options.workspaceDir,
+            pluginDir,
+            language: options.language,
+            mode: options.mode,
+            runtimeProfile: options.runtimeProfile
+                ? {
+                    provider: options.runtimeProfile.provider,
+                    model: options.runtimeProfile.model,
+                    apiKeyEnv: options.runtimeProfile.apiKeyEnv,
+                }
+                : undefined,
+        });
+        // Report host install results (rc-9: surface failures, don't silently swallow).
+        // rc-9 propagation: if ANY host installer failed, the aggregate install
+        // result is NOT successful — callers (CLI, tests) must see the failure.
+        // Previously failures were only logged, leaving `success: true` even when
+        // a host adapter failed to install (silent failure).
+        const hostFailures = [];
+        for (const hr of hostResults) {
+            if (!hr.success) {
+                const msg = `Host "${hr.hostId}": ${hr.reason ?? 'unknown failure'}. Next: ${hr.nextAction}`;
+                hostFailures.push(msg);
+                logger.warn(msg);
+            }
+            else if (hr.configAction === 'skipped') {
+                logger.info(`Host "${hr.hostId}" install: ${hr.reason ?? 'skipped'}. Next: ${hr.nextAction}`);
+            }
+        }
         cleanupBackup(backupDir);
-        if (spinner)
-            spinner.succeed('Install complete!');
+        if (spinner) {
+            if (hostFailures.length > 0) {
+                spinner.warn('Install complete with host warnings');
+            }
+            else {
+                spinner.succeed('Install complete!');
+            }
+        }
         killConsoleChild();
         // Task 8: auto-launch console via `pd console open` (reuses PRI-300
         // handleConsoleOpen — no new launcher subsystem). Opens the browser to
@@ -1173,6 +1277,10 @@ export async function install(options, pluginDir, quiet = false) {
         const actualEnabledChannels = readEnabledChannelsFromConfigYaml(options.workspaceDir);
         const cliWorking = components.cli === 'verified' || components.cli === 'verified_local_only';
         const isComplete = components.plugin === 'verified' && cliWorking && components.console === 'configured';
+        // A host installer failure means the install is not fully successful,
+        // even if all component verifications passed. The operator should see
+        // success=false and be guided to fix the failed host.
+        const hasHostFailures = hostFailures.length > 0;
         const nextActions = [];
         if (components.cli === 'verified') {
             nextActions.push(`pd runtime canary --workspace "${options.workspaceDir}" --json`);
@@ -1193,8 +1301,10 @@ export async function install(options, pluginDir, quiet = false) {
         if (launchResult.fallbackAction) {
             nextActions.push(launchResult.fallbackAction);
         }
+        // Append host-failure remediation actions so the operator knows what to fix.
+        nextActions.push(...hostFailures);
         return {
-            success: isComplete,
+            success: isComplete && !hasHostFailures,
             workspaceDir: options.workspaceDir,
             configYamlPath,
             templatesCount: templatesCount + principlesCount,
@@ -1203,6 +1313,7 @@ export async function install(options, pluginDir, quiet = false) {
             enabledChannels: actualEnabledChannels.length > 0 ? actualEnabledChannels : options.channels,
             nextAction: nextActions.join(' | '),
             consoleUrl: launchResult.consoleUrl,
+            hostResults,
         };
     }
     catch (error) {
@@ -1211,15 +1322,37 @@ export async function install(options, pluginDir, quiet = false) {
         killConsoleChild();
         const restoreResult = restoreBackup(backupDir);
         const errorMsg = error instanceof Error ? error.message : String(error);
-        const rollbackSuffix = restoreResult.restored
-            ? 'Previous install has been restored.'
-            : `CRITICAL: Rollback also failed — installation state is uncertain. ${restoreResult.error ?? ''} Resolve manually: check ${getPluginExtDir()} and ${backupDir}`;
-        const nextAction = restoreResult.restored
-            ? 'Check the error above. Previous install has been restored. Fix the issue and re-run the installer.'
-            : `Installation and rollback both failed. Check ${getPluginExtDir()} and ${backupDir} manually. Error: ${errorMsg}`;
-        const reason = restoreResult.restored
-            ? errorMsg
-            : `install_failed_rollback_failed: ${errorMsg}`;
+        // ERR-046 / rc-9: never claim a restore that didn't happen. When backupDir
+        // is null, the backup step never completed (it threw — e.g. EPERM — or
+        // there was no existing install), so the existing install was never moved
+        // and nothing was restored. The old code printed "Previous install has been
+        // restored." here, which was misleading (success-shaped, no restore).
+        const isLockError = /EPERM|EBUSY|EACCES|operation not permitted/i.test(errorMsg);
+        const extDir = getPluginExtDir();
+        // EP-11: all operator-visible failure/rollback text goes through t().
+        const rollbackSuffix = !backupDir
+            ? t('rollback_no_changes')
+            : restoreResult.restored
+                ? t('rollback_restored')
+                : t('rollback_failed')
+                    .replace('{restoreError}', restoreResult.error ?? '')
+                    .replace('{extDir}', extDir)
+                    .replace('{backupDir}', backupDir);
+        const nextAction = !backupDir
+            ? (isLockError
+                ? t('next_no_changes_lock')
+                : t('next_no_changes_other'))
+            : restoreResult.restored
+                ? t('next_restored')
+                : t('next_restore_failed')
+                    .replace('{extDir}', extDir)
+                    .replace('{backupDir}', backupDir)
+                    .replace('{errorMsg}', errorMsg);
+        const reason = !backupDir
+            ? (isLockError ? `install_aborted_lock: ${errorMsg}` : `install_failed_before_mutation: ${errorMsg}`)
+            : restoreResult.restored
+                ? errorMsg
+                : `install_failed_rollback_failed: ${errorMsg}`;
         return {
             success: false,
             workspaceDir: options.workspaceDir,
@@ -1233,5 +1366,23 @@ export async function install(options, pluginDir, quiet = false) {
             error: `${errorMsg} — ${rollbackSuffix}`,
         };
     }
+    finally {
+        // If we stopped the gateway at the pre-flight, restart it regardless of
+        // install outcome (success or failure) — never leave the gateway down.
+        // rc-9: a restart failure is reported but does not override the install
+        // result already computed above.
+        if (restartedGateway) {
+            if (!quiet)
+                logger.info(t('gateway_restarting'));
+            const restartRes = await restartOpenClawGateway();
+            if (restartRes.ok) {
+                if (!quiet)
+                    logger.success(t('gateway_restarted'));
+            }
+            else {
+                logger.error(`${t('gateway_restart_failed')} ${restartRes.error ?? ''}`);
+            }
+        }
+    }
 }
 //# sourceMappingURL=installer.js.map