fix(runtime-host): harden remote onboarding recovery

Align managed development releases with the generated package version grammar. Preserve published credential authority after uncertain commits, persist pending Desktop pairing transactions across process loss, and dismiss interactive SSH presentation when cancellation begins.

Generated-by: Codex

Author: M4n5ter

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

@@ -7,17 +7,13 @@ import type { DesktopRuntimeHostProfileService } from '../runtime-host-profile-s
 test('persists a verified SSH profile without projecting its credential', async () => {
   const handlers = new Map<string, (...args: unknown[]) => unknown>();
   const events: unknown[] = [];
+  let resetAfterCompletion: Promise<unknown> | undefined;
   let saved: DesktopRuntimeHostProfileAddInput | undefined;
-  const profiles: DesktopRuntimeHostProfileService = {
-    getSnapshot: async () => ({ defaultProfileId: 'local', entries: [] }),
-    addAndEnable: async () => assert.fail('manual profile path must not be used'),
+  const profiles: Pick<DesktopRuntimeHostProfileService, 'addAndEnableVerified'> = {
     addAndEnableVerified: async (input) => {
       saved = input;
       return { profileId: input.profile.id };
     },
-    setEnabled: async () => assert.fail('not used'),
-    setDefault: async () => assert.fail('not used'),
-    remove: async () => assert.fail('not used'),
   };
   const onboarding = createDesktopRuntimeHostOnboarding({
     ipcMain: {
@@ -35,7 +31,14 @@ test('persists a verified SSH profile without projecting its credential', async
         credential: 'secret-access-token',
       };
     },
-    send: (snapshot) => events.push(snapshot),
+    send: (snapshot) => {
+      events.push(snapshot);
+      if (snapshot.kind === 'complete') {
+        resetAfterCompletion = handlers.get('runtime-host-onboarding:reset')?.({}) as
+          | Promise<unknown>
+          | undefined;
+      }
+    },
   });
   const start = handlers.get('runtime-host-onboarding:start');
   assert.ok(start);
@@ -55,10 +58,46 @@ test('persists a verified SSH profile without projecting its credential', async
   });
   assert.equal(saved?.credential, 'secret-access-token');
   assert.doesNotMatch(JSON.stringify(events), /secret-access-token/u);
+  await resetAfterCompletion;
+  const getSnapshot = handlers.get('runtime-host-onboarding:getSnapshot');
+  assert.ok(getSnapshot);
+  assert.equal((await getSnapshot({}) as { kind?: string }).kind, 'idle');
   await onboarding.close();
   assert.equal(handlers.size, 0);
 });
 
+test('projects invalid setup input as a recoverable failure', async () => {
+  const handlers = new Map<string, (...args: unknown[]) => unknown>();
+  const onboarding = createDesktopRuntimeHostOnboarding({
+    ipcMain: {
+      handle: (channel, handler) => handlers.set(channel, handler as (...args: unknown[]) => unknown),
+      removeHandler: (channel) => handlers.delete(channel),
+    },
+    clientInstanceId: 'stable-client',
+    profiles: {
+      addAndEnableVerified: async () => assert.fail('not used'),
+    },
+    setupPackage: { kind: 'npm', specifier: 'maka-agent@0.2.0' },
+    runSetup: async () => assert.fail('invalid input must not start SSH'),
+    send: () => undefined,
+  });
+
+  const result = await handlers.get('runtime-host-onboarding:start')?.({}, {
+    destination: '',
+  });
+  assert.deepEqual(result, {
+    kind: 'failed',
+    message: 'Remote Runtime Host setup input is invalid',
+    revision: 1,
+  });
+  await handlers.get('runtime-host-onboarding:reset')?.({});
+  assert.deepEqual(await handlers.get('runtime-host-onboarding:getSnapshot')?.({}), {
+    kind: 'idle',
+    revision: 2,
+  });
+  await onboarding.close();
+});
+
 test('finishes Host pairing after the cancellable SSH phase has completed', async () => {
   const handlers = new Map<string, (...args: unknown[]) => unknown>();
   let finishPairing!: (value: { profileId: string }) => void;
@@ -79,16 +118,11 @@ test('finishes Host pairing after the cancellable SSH phase has completed', asyn
   }>((resolve) => {
     finishSetup = resolve;
   });
-  const profiles: DesktopRuntimeHostProfileService = {
-    getSnapshot: async () => ({ defaultProfileId: 'local', entries: [] }),
-    addAndEnable: async () => assert.fail('manual profile path must not be used'),
+  const profiles: Pick<DesktopRuntimeHostProfileService, 'addAndEnableVerified'> = {
     addAndEnableVerified: async () => {
       pairingStarted = true;
       return pairing;
     },
-    setEnabled: async () => assert.fail('not used'),
-    setDefault: async () => assert.fail('not used'),
-    remove: async () => assert.fail('not used'),
   };
   const onboarding = createDesktopRuntimeHostOnboarding({
     ipcMain: {

apps/desktop/src/main/__tests__/runtime-host-profile-service.test.ts

@@ -6,6 +6,7 @@ import { afterEach, test } from "node:test";
 import {
   createClientRuntimeHostProfileCatalog,
   LOCAL_RUNTIME_HOST_PROFILE,
+  RuntimeHostPermanentReconnectError,
   type ResolvedRuntimeHostProfile,
 } from "@maka/runtime-host/client";
 import {
@@ -306,6 +307,57 @@ test("refreshes the existing profile when managed setup pairs the same Host agai
   assert.deepEqual((await catalog.read()).profiles.map((profile) => profile.id), [PROFILE.id]);
 });
 
+test("finishes a persisted pairing after Desktop restarts before finalization", async () => {
+  const root = await clientRoot();
+  const catalog = await stageInterruptedPairing(root);
+  const startup = await resolveDesktopRuntimeHostStartup(root, { catalog });
+  assert.equal(startup.pairingIntents.length, 1);
+  const finalized: string[] = [];
+  const service = createDesktopRuntimeHostProfileService({
+    clientDataRoot: root,
+    startup,
+    catalog,
+    states: () => [connectingLocal()],
+    enable: async () => undefined,
+    disable: async () => undefined,
+    setDefault: () => undefined,
+    finalizePairing: async (profileId) => {
+      finalized.push(profileId);
+    },
+  });
+
+  await service.recoverPendingPairings();
+
+  assert.deepEqual(finalized, [PROFILE.id]);
+  assert.equal((await catalog.resolve(PROFILE.id)).credential, "new-token");
+  assert.equal((await resolveDesktopRuntimeHostStartup(root, { catalog })).pairingIntents.length, 0);
+});
+
+test("restores the previous credential when an interrupted pairing can no longer authenticate", async () => {
+  const root = await clientRoot();
+  const catalog = await stageInterruptedPairing(root);
+  const startup = await resolveDesktopRuntimeHostStartup(root, { catalog });
+  const service = createDesktopRuntimeHostProfileService({
+    clientDataRoot: root,
+    startup,
+    catalog,
+    states: () => [connectingLocal()],
+    enable: async (target) => {
+      if (target.credential === "new-token") {
+        throw new RuntimeHostPermanentReconnectError("pairing credential expired");
+      }
+    },
+    disable: async () => undefined,
+    setDefault: () => undefined,
+    finalizePairing: async () => assert.fail("an expired credential cannot be finalized"),
+  });
+
+  await service.recoverPendingPairings();
+
+  assert.equal((await catalog.resolve(PROFILE.id)).credential, "old-token");
+  assert.equal((await resolveDesktopRuntimeHostStartup(root, { catalog })).pairingIntents.length, 0);
+});
+
 for (const failureAt of ["connection", "finalization"] as const) {
   test(`restores an existing profile when replacement ${failureAt} fails`, async () => {
     const root = await clientRoot();
@@ -401,6 +453,43 @@ async function clientRoot(): Promise<string> {
   return root;
 }
 
+async function stageInterruptedPairing(root: string) {
+  const catalog = createClientRuntimeHostProfileCatalog(root);
+  await catalog.create(PROFILE, "old-token");
+  await writeFile(
+    join(root, "runtime-host-profile-selection.json"),
+    `${JSON.stringify({
+      schemaVersion: 2,
+      defaultProfileId: "local",
+      enabledRemoteProfileIds: [PROFILE.id],
+    })}\n`,
+  );
+  const startup = await resolveDesktopRuntimeHostStartup(root, { catalog });
+  let finalizationStarted!: () => void;
+  const started = new Promise<void>((resolve) => {
+    finalizationStarted = resolve;
+  });
+  const service = createDesktopRuntimeHostProfileService({
+    clientDataRoot: root,
+    startup,
+    catalog,
+    states: () => [connectingLocal()],
+    enable: async () => undefined,
+    disable: async () => undefined,
+    setDefault: () => undefined,
+    finalizePairing: async () => {
+      finalizationStarted();
+      await new Promise<never>(() => undefined);
+    },
+  });
+  void service.addAndEnableVerified({
+    profile: { ...PROFILE, name: "Updated office" },
+    credential: "new-token",
+  });
+  await started;
+  return catalog;
+}
+
 function connectingLocal(): RuntimeHostDesktopTargetState {
   return connecting({ profile: LOCAL_RUNTIME_HOST_PROFILE });
 }

apps/desktop/src/main/__tests__/runtime-host-ssh-terminal.test.ts

@@ -59,7 +59,7 @@ test('does not reopen a cancelled SSH prompt for late process output', async ()
   await assert.rejects(opening, /SSH exited/u);
 
   assert.deepEqual(harness.pty.killSignals, ['SIGTERM', 'SIGKILL']);
-  assert.deepEqual(harness.eventKinds(), ['opened', 'data']);
+  assert.deepEqual(harness.eventKinds(), ['opened', 'data', 'dismissed']);
   assert.deepEqual(await harness.getSnapshot(), { kind: 'idle', revision: 3 });
   await harness.terminal.close();
 });
@@ -126,11 +126,14 @@ test('force-stops a cancelled setup when SSH ignores graceful termination', asyn
     () => undefined,
   );
   await waitFor(() => harness.pty.hasDataListener());
+  harness.pty.emitData('Password: ');
 
   controller.abort();
 
   await assert.rejects(setup, /aborted/u);
   assert.deepEqual(harness.pty.killSignals, ['SIGTERM', 'SIGKILL']);
+  assert.deepEqual(harness.eventKinds(), ['opened', 'data', 'dismissed']);
+  assert.deepEqual(await harness.getSnapshot(), { kind: 'idle', revision: 3 });
   await harness.terminal.close();
 });
 
@@ -164,7 +167,10 @@ test('uploads a development release archive before running the same remote setup
   await waitFor(() => launches.length === 1);
   assert.equal(launches[0]?.file, 'scp');
   assert.match(launches[0]?.args.at(-2) ?? '', /maka-agent-development\.tgz$/u);
-  assert.match(launches[0]?.args.at(-1) ?? '', /^operator@example\.com:\/tmp\/maka-runtime-host-setup-.+\.tgz$/u);
+  assert.match(
+    launches[0]?.args.at(-1) ?? '',
+    /^operator@example\.com:\.\/\.maka-runtime-host-setup-.+\.tgz$/u,
+  );
   launches[0]?.pty.exit(0);
 
   await waitFor(() => launches.length === 2);
@@ -175,10 +181,10 @@ test('uploads a development release archive before running the same remote setup
     /npx.*--package.*maka-runtime-host-setup-.+\.tgz.*maka.*runtime-host.*setup/u,
   );
   assert.match(remoteCommand, /--defer-pairing-commit/u);
+  assert.match(remoteCommand, /cd.*\$HOME/u);
   assert.match(remoteCommand, /rm -f/u);
   assert.match(remoteCommand, /exec \/bin\/sh -c/u);
   assert.match(remoteCommand, /maka_setup_exit/u);
-  assert.doesNotMatch(remoteCommand, /\bstatus=/u);
   launches[1]?.pty.exit(255);
   await assert.rejects(setup, /exited with code 255/u);
 

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

@@ -708,6 +708,12 @@ runtimeHostManager = await startRuntimeHostDesktopManager(
 });
 wireLifecycle();
 runtimeHostManager.setDefaultProfile(runtimeHostStartup.preferences.defaultProfileId);
+const pendingPairingProfileIds = new Set(
+  runtimeHostStartup.pairingIntents.map((intent) => intent.target.profile.id),
+);
+void runtimeHostProfileService
+  .recoverPendingPairings()
+  .catch((error) => console.error("[runtime-host] pairing recovery failed:", error));
 const unavailableDefault = runtimeHostStartup.unavailable.get(
   runtimeHostStartup.preferences.defaultProfileId,
 );
@@ -731,6 +737,7 @@ if (unavailableDefault) {
 // enabled Host behind it. Other SSH targets fail batch-mode and remain retryable.
 for (const target of runtimeHostStartup.remotes) {
   if (target.profile.kind !== "remote" || !target.credential) continue;
+  if (pendingPairingProfileIds.has(target.profile.id)) continue;
   void runtimeHostManager
     .enable({
       profile: target.profile,

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

@@ -20,7 +20,7 @@ type OnboardingState = DesktopRuntimeHostOnboardingSnapshot extends infer Snapsh
 export function createDesktopRuntimeHostOnboarding(input: {
   readonly ipcMain: Pick<IpcMain, 'handle' | 'removeHandler'>;
   readonly clientInstanceId: string;
-  readonly profiles: DesktopRuntimeHostProfileService;
+  readonly profiles: Pick<DesktopRuntimeHostProfileService, 'addAndEnableVerified'>;
   readonly runSetup: (
     input: DesktopRuntimeHostSshSetupInput,
     onProgress: (frame: { readonly phase: RuntimeHostSetupPhase }) => void,
@@ -53,8 +53,16 @@ export function createDesktopRuntimeHostOnboarding(input: {
   };
 
   const start = (value: unknown): Promise<DesktopRuntimeHostOnboardingSnapshot> => {
-    if (active) throw new Error('A remote Runtime Host setup is already in progress');
-    const request = requireOnboardingInput(value);
+    if (active) return active.task;
+    let request: DesktopRuntimeHostOnboardingInput;
+    try {
+      request = requireOnboardingInput(value);
+    } catch (error) {
+      return Promise.resolve(publish({
+        kind: 'failed',
+        message: error instanceof Error ? error.message : String(error),
+      }));
+    }
     const abort = new AbortController();
     publish({ kind: 'running', phase: 'connecting_ssh' });
     const task = Promise.resolve().then(() => run(request, abort.signal)).finally(() => {
@@ -145,8 +153,9 @@ export function createDesktopRuntimeHostOnboarding(input: {
     await current.task;
     return true;
   });
-  input.ipcMain.handle(channels[3], () => {
-    if (active) throw new Error('Remote Runtime Host setup is still running');
+  input.ipcMain.handle(channels[3], async () => {
+    if (snapshot.kind === 'running') return;
+    await active?.task;
     publish({ kind: 'idle' });
   });