fix(desktop): recover managed Runtime Host startup

Author: M4n5ter

apps/desktop/src/main/__tests__/native-diagnostic-dialog.test.ts

@@ -28,6 +28,7 @@ import {
   showFatalStartupError,
   showMainRendererProcessGoneDialog,
   showMessageBoxWithDiagnostics,
+  showRuntimeHostStartupRecoveryDialog,
 } from '../native-diagnostic-dialog.js';
 
 const diagnosticEnvironment = () => ({
@@ -149,3 +150,32 @@ test('main Renderer loss keeps Copy Diagnostics auxiliary to recovery', async ()
   assert.match(clipboard, /Recent main-process logs \(1\)/);
   assert.doesNotMatch(clipboard, /very-secret-token/);
 });
+
+test('managed Host recovery preserves the workspace and confirms active-work interruption', async () => {
+  let shown: MessageBoxOptions | undefined;
+  const decision = await showRuntimeHostStartupRecoveryDialog(
+    {
+      startupError: new Error('managed service unavailable'),
+      repairError: new Error('service update failed'),
+      activeTasks: true,
+    },
+    {
+      locale: 'en',
+      copyDiagnostics() {},
+      showMessageBox: async (options): Promise<MessageBoxReturnValue> => {
+        shown = options;
+        return { response: 0, checkboxChecked: false };
+      },
+    },
+  );
+
+  assert.equal(decision, 'repair');
+  assert.deepEqual(shown?.buttons, [
+    'Repair and Restart Host',
+    'Exit',
+    'Copy Diagnostics',
+  ]);
+  assert.match(shown?.detail ?? '', /workspace, Host identity, credentials, and settings/);
+  assert.match(shown?.detail ?? '', /interrupt that work/);
+  assert.match(shown?.detail ?? '', /service update failed/);
+});

apps/desktop/src/main/__tests__/runtime-host-local-remote-access.test.ts

@@ -234,6 +234,62 @@ test('keeps the managed service visible when Direct peer support is unavailable'
   assert.equal(snapshot.managedService, true);
 });
 
+test('repairs an existing managed Host with the current setup package and restarts it when already current', async (t) => {
+  const base = await mkdtemp(join(tmpdir(), 'maka-local-managed-repair-'));
+  t.after(() => rm(base, { recursive: true, force: true }));
+  const clientDataRoot = join(base, 'client');
+  const rootPath = join(clientDataRoot, 'workspaces', 'default');
+  const rootId = 'a'.repeat(64);
+  const setupPackage = { kind: 'npm' as const, specifier: 'maka-agent@0.2.0' };
+  await mkdir(rootPath, { recursive: true });
+  await writeManagedLifecycle(clientDataRoot, rootPath, rootId);
+  const actions: string[] = [];
+  const service = createDesktopLocalRuntimeHostRemoteAccess({
+    ipcMain: { handle() {}, removeHandler() {} },
+    clientDataRoot,
+    rootPath,
+    rootId,
+    directPeerAvailable: true,
+    manager: () => undefined,
+    resolveSetupPackage: async () => setupPackage,
+    operator: {
+      async runUpdate(input: {
+        readonly setupPackage: unknown;
+        readonly target: { readonly rootId: string; readonly deploymentId?: string };
+        readonly allowInterruptActiveTasks?: boolean;
+      }) {
+        actions.push('update');
+        assert.equal(input.setupPackage, setupPackage);
+        assert.equal(input.target.rootId, rootId);
+        assert.equal(input.target.deploymentId, RECOVERY_DEPLOYMENT_ID);
+        assert.equal(input.allowInterruptActiveTasks, undefined);
+        return {
+          kind: 'result',
+          action: 'update',
+          update: { kind: 'already_current', version: '0.2.0' },
+        } as never;
+      },
+      async runService(input: {
+        readonly action: string;
+        readonly target: { readonly rootId: string; readonly deploymentId?: string };
+        readonly allowInterruptActiveTasks?: boolean;
+      }) {
+        actions.push(input.action);
+        assert.equal(input.action, 'restart');
+        assert.equal(input.target.rootId, rootId);
+        assert.equal(input.target.deploymentId, RECOVERY_DEPLOYMENT_ID);
+        assert.equal(input.allowInterruptActiveTasks, undefined);
+        return { kind: 'result', action: 'restart' } as never;
+      },
+      async close() {},
+    } as unknown as ReturnType<typeof createDesktopRuntimeHostLocalOperator>,
+  });
+  t.after(() => service.close());
+
+  assert.deepEqual(await service.repairManagedStartup(), { kind: 'repaired' });
+  assert.deepEqual(actions, ['update', 'restart']);
+});
+
 test('replaces a conflicting supervised Host through canonical authority without a receipt', async (t) => {
   const base = await mkdtemp(join(tmpdir(), 'maka-local-managed-conflict-'));
   t.after(() => rm(base, { recursive: true, force: true }));

apps/desktop/src/main/__tests__/runtime-host-startup-recovery.test.ts

@@ -0,0 +1,105 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+import { runtimeHostStartupError } from "@maka/runtime-host/client";
+import { startDesktopRuntimeHostWithRecovery } from "../runtime-host-startup-recovery.js";
+
+test("repairs a managed Host once and resumes startup without asking the user", async () => {
+  let starts = 0;
+  const repairModes: boolean[] = [];
+  let prompts = 0;
+
+  const result = await startDesktopRuntimeHostWithRecovery({
+    start: async () => {
+      starts += 1;
+      if (starts === 1)
+        throw runtimeHostStartupError("managed_root_requires_operator");
+      return "ready";
+    },
+    repair: async (allowInterruptActiveTasks) => {
+      repairModes.push(allowInterruptActiveTasks);
+      return { kind: "repaired" };
+    },
+    prompt: async () => {
+      prompts += 1;
+      return "exit";
+    },
+  });
+
+  assert.equal(result, "ready");
+  assert.equal(starts, 2);
+  assert.deepEqual(repairModes, [false]);
+  assert.equal(prompts, 0);
+});
+
+test("requires an explicit decision before interrupting active Host work", async () => {
+  let starts = 0;
+  const repairModes: boolean[] = [];
+  const prompts: boolean[] = [];
+
+  const result = await startDesktopRuntimeHostWithRecovery({
+    start: async () => {
+      starts += 1;
+      if (starts === 1)
+        throw runtimeHostStartupError("managed_root_requires_operator");
+      return "ready";
+    },
+    repair: async (allowInterruptActiveTasks) => {
+      repairModes.push(allowInterruptActiveTasks);
+      return allowInterruptActiveTasks
+        ? { kind: "repaired" }
+        : { kind: "active_tasks" };
+    },
+    prompt: async (input) => {
+      prompts.push(input.activeTasks);
+      return "repair";
+    },
+  });
+
+  assert.equal(result, "ready");
+  assert.deepEqual(repairModes, [false, true]);
+  assert.deepEqual(prompts, [true]);
+});
+
+test("does not offer managed repair for an unrelated startup failure", async () => {
+  const failure = new Error("renderer prerequisites failed");
+  let repairs = 0;
+  let prompts = 0;
+
+  await assert.rejects(
+    startDesktopRuntimeHostWithRecovery({
+      start: async () => {
+        throw failure;
+      },
+      repair: async () => {
+        repairs += 1;
+        return { kind: "repaired" };
+      },
+      prompt: async () => {
+        prompts += 1;
+        return "repair";
+      },
+    }),
+    failure,
+  );
+  assert.equal(repairs, 0);
+  assert.equal(prompts, 0);
+});

apps/desktop/src/main/native-diagnostic-dialog.ts

@@ -43,6 +43,12 @@ interface FatalStartupDiagnosticDialogDeps {
   readonly showMessageBox: (options: MessageBoxOptions) => Promise<MessageBoxReturnValue>;
 }
 
+export interface RuntimeHostStartupRecoveryDialogInput {
+  readonly startupError: Error;
+  readonly repairError?: Error;
+  readonly activeTasks: boolean;
+}
+
 export async function showMessageBoxWithDiagnostics(
   options: MessageBoxOptions,
   deps: DiagnosticDialogDeps,
@@ -114,6 +120,36 @@ export async function showMainRendererProcessGoneDialog(
   return result.response === 0 ? 'relaunch' : 'exit';
 }
 
+export async function showRuntimeHostStartupRecoveryDialog(
+  input: RuntimeHostStartupRecoveryDialogInput,
+  deps: DiagnosticDialogDeps,
+): Promise<'repair' | 'exit'> {
+  const copy = RUNTIME_HOST_STARTUP_RECOVERY_COPY[deps.locale];
+  const detail = [
+    copy.detail,
+    input.activeTasks ? copy.activeTasks : undefined,
+    input.repairError
+      ? `${copy.repairFailed}\n${input.repairError.message}`
+      : undefined,
+  ]
+    .filter(Boolean)
+    .join('\n\n');
+  const result = await showMessageBoxWithDiagnostics(
+    {
+      type: 'warning',
+      title: copy.title,
+      message: copy.message,
+      detail,
+      buttons: [input.activeTasks ? copy.repairAndRestart : copy.repair, copy.exit],
+      defaultId: 0,
+      cancelId: 1,
+      noLink: true,
+    },
+    deps,
+  );
+  return result.response === 0 ? 'repair' : 'exit';
+}
+
 async function copyDiagnostics(
   copy: () => void | Promise<void>,
   locale: UiLocale,
@@ -195,3 +231,29 @@ const MAIN_RENDERER_GONE_COPY = {
     exit: '退出',
   },
 } as const;
+
+const RUNTIME_HOST_STARTUP_RECOVERY_COPY = {
+  en: {
+    title: 'Maka needs to repair Runtime Host',
+    message: 'The Runtime Host for this workspace could not start.',
+    detail:
+      'Maka can repair the managed Runtime Host selected by this Desktop. Your workspace, Host identity, credentials, and settings will be preserved.',
+    activeTasks:
+      'The Host may still own active work. Continuing can interrupt that work before the Host restarts.',
+    repairFailed: 'The previous repair attempt did not finish:',
+    repair: 'Repair Runtime Host',
+    repairAndRestart: 'Repair and Restart Host',
+    exit: 'Exit',
+  },
+  zh: {
+    title: 'Maka 需要修复 Runtime Host',
+    message: '管理此工作区的 Runtime Host 无法启动。',
+    detail:
+      'Maka 可以修复此 Desktop 选择的托管 Runtime Host。工作区、Host 身份、凭证和设置都会保留。',
+    activeTasks: 'Host 可能仍有正在运行的任务。继续会先中断这些任务，再重启 Host。',
+    repairFailed: '上一次修复未能完成：',
+    repair: '修复 Runtime Host',
+    repairAndRestart: '修复并重启 Host',
+    exit: '退出',
+  },
+} as const;

apps/desktop/src/main/runtime-host-boot.ts

@@ -116,6 +116,7 @@ import {
 import {
   showMainRendererProcessGoneDialog,
   showMessageBoxWithDiagnostics,
+  showRuntimeHostStartupRecoveryDialog,
 } from "./native-diagnostic-dialog.js";
 import {
   resolveDesktopSessionWorkspace,
@@ -168,6 +169,10 @@ import {
   startRuntimeHostDesktopManager,
   type RuntimeHostDesktopManager,
 } from "./runtime-host-desktop-manager.js";
+import {
+  DesktopRuntimeHostStartupRecoveryCancelledError,
+  startDesktopRuntimeHostWithRecovery,
+} from "./runtime-host-startup-recovery.js";
 import { buildRuntimeHostQuitFailureDialog } from "./runtime-host-quit-copy.js";
 import { createRuntimeHostUpgradePrompts } from "./runtime-host-upgrade-dialog.js";
 import { registerRuntimeHostMemoryIpc } from "./runtime-host-memory-ipc-main.js";
@@ -850,8 +855,8 @@ registerNotificationsIpc({
 });
 
 const sessionCopyOwnerProcessId = randomUUID();
-await localRuntimeHostRemoteAccess.recoverBeforeLocalHostStart();
-runtimeHostManager = await startRuntimeHostDesktopManager(
+let runtimeHostStartupSettled = false;
+const startLocalRuntimeHostManager = () => startRuntimeHostDesktopManager(
   {
     rootPath: workspaceRoot,
     clientInstanceId: runtimeHostClientInstanceId,
@@ -1074,6 +1079,7 @@ runtimeHostManager = await startRuntimeHostDesktopManager(
     resolveLocalHostReplacement: (registration, signal) =>
       localRuntimeHostRemoteAccess.resolveConflictingHostReplacement(registration, signal),
     onFatalError: (error, target) => {
+      if (!runtimeHostStartupSettled && target.profile.kind === "local") return;
       if (error instanceof RuntimeHostUpgradeCancelledError) {
         if (target.profile.kind === "local") app.quit();
         return;
@@ -1082,13 +1088,53 @@ runtimeHostManager = await startRuntimeHostDesktopManager(
       if (target.profile.kind === "local") app.quit();
     },
   },
-).catch((error: unknown) => {
-  if (error instanceof RuntimeHostUpgradeCancelledError) {
+);
+runtimeHostManager = await startDesktopRuntimeHostWithRecovery({
+  start: async () => {
+    await localRuntimeHostRemoteAccess.recoverBeforeLocalHostStart();
+    return startLocalRuntimeHostManager();
+  },
+  repair: async (allowInterruptActiveTasks) => {
+    console.warn('[runtime-host] repairing the managed Local Host before startup');
+    const result = await localRuntimeHostRemoteAccess.repairManagedStartup({
+      allowInterruptActiveTasks,
+    });
+    console.log(`[runtime-host] managed Local Host repair result: ${result.kind}`);
+    return result;
+  },
+  prompt: async (input) => {
+    console.error('[runtime-host] managed Local Host startup recovery requires attention:', {
+      startupError: input.startupError,
+      repairError: input.repairError,
+      activeTasks: input.activeTasks,
+    });
+    return showRuntimeHostStartupRecoveryDialog(input, {
+      locale: desktopLocale.current(),
+      showMessageBox: (options) => dialog.showMessageBox(options),
+      copyDiagnostics: () =>
+        copyDesktopDiagnosticReport(
+          desktopDiagnostics,
+          createDesktopStartupDiagnosticInput({
+            title: 'Runtime Host startup recovery',
+            description: input.startupError.message,
+            details: [input.startupError.stack, input.repairError?.stack]
+              .filter(Boolean)
+              .join('\n\n'),
+          }),
+        ),
+    });
+  },
+}).catch((error: unknown) => {
+  if (
+    error instanceof RuntimeHostUpgradeCancelledError ||
+    error instanceof DesktopRuntimeHostStartupRecoveryCancelledError
+  ) {
     app.quit();
     return new Promise<never>(() => undefined);
   }
   throw error;
 });
+runtimeHostStartupSettled = true;
 wireLifecycle();
 runtimeHostManager.setDefaultProfile(runtimeHostStartup.preferences.defaultProfileId);
 await guestSessionMountService.start().catch((error: unknown) => {