refactor(onboard): extract session bootstrap flow

src/lib/onboard.ts

@@ -35,6 +35,7 @@ const sandboxMessagingPreflight: typeof import("./onboard/sandbox-messaging-pref
 const sandboxCreatePlan: typeof import("./onboard/sandbox-create-plan") = require("./onboard/sandbox-create-plan");
 const sandboxCreateLaunch: typeof import("./onboard/sandbox-create-launch") = require("./onboard/sandbox-create-launch");
 const onboardEntryOptions: typeof import("./onboard/entry-options") = require("./onboard/entry-options");
+const onboardSessionBootstrap: typeof import("./onboard/session-bootstrap") = require("./onboard/session-bootstrap");
 const channelState: typeof import("./onboard/channel-state") = require("./onboard/channel-state");
 const {
   ensureOllamaLoopbackSystemdOverride,
@@ -4881,119 +4882,34 @@ async function onboard(opts: OnboardOptions = {}): Promise<void> {
   let traceCompleted = false;
   try {
     onboardTrace = onboardTracing.startOnboardTrace(opts, process.env);
-    let session: Session | null;
     let selectedMessagingChannels: string[] = [];
-    // Merged, absolute fromDockerfile: explicit flag/env takes precedence; on
-    // resume falls back to what the original session recorded so the same image
-    // is used even when --from is omitted from the resume invocation.
-    let fromDockerfile: string | null;
-    if (resume) {
-      session = onboardSession.loadSession();
-      setOnboardBrandingAgent(opts.agent || session?.agent || process.env.NEMOCLAW_AGENT || null);
-      if (!session || session.resumable === false) {
-        console.error("  No resumable onboarding session was found.");
-        console.error("  --resume only continues an interrupted onboarding run.");
-        console.error("  To change configuration on an existing sandbox, rebuild it:");
-        console.error(`    ${cliName()} onboard`);
-        process.exit(1);
-      }
-      const sessionFrom = session?.metadata?.fromDockerfile || null;
-      fromDockerfile = requestedFromDockerfile
-        ? path.resolve(requestedFromDockerfile)
-        : sessionFrom
-          ? path.resolve(sessionFrom)
-          : null;
-      const resumeConflicts = getResumeConfigConflicts(session, {
+    let { session, fromDockerfile } = await onboardSessionBootstrap.prepareOnboardSession(
+      {
+        resume,
+        fresh,
+        requestedFromDockerfile,
+        requestedSandboxName,
+        cannotPrompt,
         nonInteractive: isNonInteractive(),
-        fromDockerfile: requestedFromDockerfile,
-        sandboxName: requestedSandboxName,
-        agent: opts.agent || null,
-      });
-      if (resumeConflicts.length > 0) {
-        for (const conflict of resumeConflicts) {
-          try {
-            await onboardRuntimeBoundary.recordResumeConflict(conflict);
-          } catch {
-            /* diagnostic-only */
-          }
-          if (conflict.field === "sandbox") {
-            console.error(
-              `  Resumable state belongs to sandbox '${conflict.recorded}', not '${conflict.requested}'.`,
-            );
-          } else if (conflict.field === "agent") {
-            console.error(
-              `  Session was started with agent '${conflict.recorded}', not '${conflict.requested}'.`,
-            );
-          } else if (conflict.field === "fromDockerfile") {
-            if (!conflict.recorded) {
-              console.error(
-                `  Session was started without --from; add --from '${conflict.requested}' to resume it.`,
-              );
-            } else if (!conflict.requested) {
-              console.error(
-                `  Session was started with --from '${conflict.recorded}'; rerun with that path to resume it.`,
-              );
-            } else {
-              console.error(
-                `  Session was started with --from '${conflict.recorded}', not '${conflict.requested}'.`,
-              );
-            }
-          } else {
-            console.error(
-              `  Resumable state recorded ${conflict.field} '${conflict.recorded}', not '${conflict.requested}'.`,
-            );
-          }
-        }
-        console.error(
-          `  Run: ${cliName()} onboard              # start a fresh onboarding session`,
-        );
-        console.error("  Or rerun with the original settings to continue that session.");
-        process.exit(1);
-      }
-      onboardSession.updateSession((current: Session) => {
-        repairResumeMachineSnapshot(current);
-        current.mode = isNonInteractive() ? "non-interactive" : "interactive";
-        current.failure = null;
-        current.status = "in_progress";
-        return current;
-      });
-      session = onboardSession.loadSession();
-      // #2753: a resumed onboard whose sandbox step did not complete has no
-      // recorded sandboxName (the onboard fix only persists it after
-      // createSandbox succeeds). Falling through would silently default to
-      // the agent's `my-assistant` instead of the user's original --name.
-      // Use `cannotPrompt` so non-TTY runs without explicit --non-interactive
-      // are also caught, and `requestedSandboxName` from
-      // resolveOnboardEntryOptions so whitespace-only env values can't satisfy
-      // the guard.
-      const sandboxStepCompleted = session?.steps?.sandbox?.status === "complete";
-      const recoveredSandboxName =
-        requestedSandboxName || (sandboxStepCompleted ? session?.sandboxName || null : null);
-      if (cannotPrompt && !recoveredSandboxName) {
-        console.error(
-          "  Cannot resume non-interactive onboard: the previous run was interrupted before sandbox creation completed,",
-        );
-        console.error(
-          "  so no sandbox name was recorded. Re-run with --name <sandbox> (or set NEMOCLAW_SANDBOX_NAME).",
-        );
-        process.exit(1);
-      }
-    } else {
-      // --fresh asks for an explicit fresh start. createSession + saveSession
-      // already overwrites any existing file, but clearing first removes the
-      // old file outright so an interrupted createSession cannot leave the
-      // previous session readable on disk.
-      if (fresh) {
-        onboardSession.clearSession();
-      }
-      fromDockerfile = requestedFromDockerfile ? path.resolve(requestedFromDockerfile) : null;
-      session = onboardSession.saveSession(
-        onboardSession.createSession({
-          mode: isNonInteractive() ? "non-interactive" : "interactive",
-          metadata: { gatewayName: "nemoclaw", fromDockerfile: fromDockerfile || null },
-        }),
-      );
-    }
+        agentFlag: opts.agent || null,
+        envAgent: process.env.NEMOCLAW_AGENT || null,
+      },
+      {
+        loadSession: onboardSession.loadSession,
+        clearSession: onboardSession.clearSession,
+        createSession: onboardSession.createSession,
+        saveSession: onboardSession.saveSession,
+        updateSession: onboardSession.updateSession,
+        repairResumeMachineSnapshot,
+        setOnboardBrandingAgent,
+        getResumeConfigConflicts,
+        recordResumeConflict: (conflict) => onboardRuntimeBoundary.recordResumeConflict(conflict),
+        resolvePath: path.resolve,
+        cliName,
+        error: (message) => console.error(message),
+        exitProcess: (code) => process.exit(code),
+      },
+    );
     await onboardRuntimeBoundary.recordOnboardStarted(resume);
     await recordStateResult(advanceTo("preflight", { metadata: { state: "init" } }));
     // Backstop for the resume path: a session may exist (so the early guard

src/lib/onboard/session-bootstrap.test.ts

@@ -0,0 +1,218 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { describe, expect, it, vi } from "vitest";
+
+import { createSession, type Session } from "../state/onboard-session";
+import { prepareOnboardSession, type OnboardSessionBootstrapDeps } from "./session-bootstrap";
+import type { ResumeConfigConflict } from "./resume-config";
+
+class ExitError extends Error {
+  constructor(readonly code: number) {
+    super(`exit ${code}`);
+  }
+}
+
+function completeSandboxStep(): Session["steps"][string] {
+  return {
+    status: "complete",
+    startedAt: "2026-06-10T00:00:00.000Z",
+    completedAt: "2026-06-10T00:01:00.000Z",
+    error: null,
+  };
+}
+
+function createDeps(
+  initialSession: Session | null = null,
+  overrides: Partial<OnboardSessionBootstrapDeps> = {},
+): { deps: OnboardSessionBootstrapDeps; getSession: () => Session | null } {
+  let session = initialSession;
+  const deps: OnboardSessionBootstrapDeps = {
+    loadSession: vi.fn(() => session),
+    clearSession: vi.fn(() => {
+      session = null;
+    }),
+    createSession: vi.fn((sessionOverrides?: Partial<Session>) => createSession(sessionOverrides)),
+    saveSession: vi.fn((next: Session) => {
+      session = next;
+      return next;
+    }),
+    updateSession: vi.fn((mutator: (session: Session) => Session | void) => {
+      const current = session ?? createSession();
+      const next = mutator(current) ?? current;
+      session = next;
+      return next;
+    }),
+    repairResumeMachineSnapshot: vi.fn((current: Session) => current),
+    setOnboardBrandingAgent: vi.fn(),
+    getResumeConfigConflicts: vi.fn(() => []),
+    recordResumeConflict: vi.fn(async () => undefined),
+    resolvePath: vi.fn((value: string) => `/abs/${value}`),
+    cliName: vi.fn(() => "nemoclaw"),
+    error: vi.fn(),
+    exitProcess: vi.fn((code: number) => {
+      throw new ExitError(code);
+    }) as (code: number) => never,
+    ...overrides,
+  };
+  return { deps, getSession: () => session };
+}
+
+describe("prepareOnboardSession", () => {
+  it("creates a fresh session and records the resolved Dockerfile", async () => {
+    const existing = createSession({ sessionId: "old-session" });
+    const { deps, getSession } = createDeps(existing);
+
+    const result = await prepareOnboardSession(
+      {
+        resume: false,
+        fresh: true,
+        requestedFromDockerfile: "Dockerfile.custom",
+        requestedSandboxName: null,
+        cannotPrompt: false,
+        nonInteractive: true,
+      },
+      deps,
+    );
+
+    expect(deps.clearSession).toHaveBeenCalledTimes(1);
+    expect(result.fromDockerfile).toBe("/abs/Dockerfile.custom");
+    expect(result.session?.mode).toBe("non-interactive");
+    expect(result.session?.metadata.fromDockerfile).toBe("/abs/Dockerfile.custom");
+    expect(getSession()?.sessionId).not.toBe("old-session");
+  });
+
+  it("resumes an existing session and falls back to the recorded Dockerfile", async () => {
+    const initial = createSession({
+      agent: "hermes",
+      failure: {
+        step: "inference",
+        message: "failed",
+        recordedAt: "2026-06-10T00:00:00.000Z",
+      },
+      metadata: { gatewayName: "nemoclaw", fromDockerfile: "Dockerfile.recorded" },
+      sandboxName: "demo",
+      status: "failed",
+      steps: {
+        ...createSession().steps,
+        sandbox: completeSandboxStep(),
+      },
+    });
+    const { deps } = createDeps(initial);
+
+    const result = await prepareOnboardSession(
+      {
+        resume: true,
+        fresh: false,
+        requestedFromDockerfile: null,
+        requestedSandboxName: null,
+        cannotPrompt: true,
+        nonInteractive: true,
+        envAgent: "openclaw",
+      },
+      deps,
+    );
+
+    expect(result.fromDockerfile).toBe("/abs/Dockerfile.recorded");
+    expect(result.session?.mode).toBe("non-interactive");
+    expect(result.session?.failure).toBeNull();
+    expect(result.session?.status).toBe("in_progress");
+    expect(deps.repairResumeMachineSnapshot).toHaveBeenCalledWith(initial);
+    expect(deps.setOnboardBrandingAgent).toHaveBeenCalledWith("hermes");
+  });
+
+  it("records and reports resume conflicts before exiting", async () => {
+    const conflict: ResumeConfigConflict = {
+      field: "fromDockerfile",
+      requested: "/abs/Dockerfile.new",
+      recorded: "/abs/Dockerfile.old",
+    };
+    const { deps } = createDeps(createSession(), {
+      getResumeConfigConflicts: vi.fn(() => [conflict]),
+    });
+
+    await expect(
+      prepareOnboardSession(
+        {
+          resume: true,
+          fresh: false,
+          requestedFromDockerfile: "Dockerfile.new",
+          requestedSandboxName: null,
+          cannotPrompt: false,
+          nonInteractive: false,
+        },
+        deps,
+      ),
+    ).rejects.toThrow(ExitError);
+
+    expect(deps.recordResumeConflict).toHaveBeenCalledWith(conflict);
+    expect(deps.error).toHaveBeenCalledWith(
+      "  Session was started with --from '/abs/Dockerfile.old', not '/abs/Dockerfile.new'.",
+    );
+    expect(deps.error).toHaveBeenCalledWith(
+      "  Run: nemoclaw onboard              # start a fresh onboarding session",
+    );
+    expect(deps.exitProcess).toHaveBeenCalledWith(1);
+  });
+
+  it("still exits on resume conflicts when diagnostic recording fails", async () => {
+    const conflict: ResumeConfigConflict = {
+      field: "sandbox",
+      requested: "new-box",
+      recorded: "old-box",
+    };
+    const { deps } = createDeps(createSession(), {
+      getResumeConfigConflicts: vi.fn(() => [conflict]),
+      recordResumeConflict: vi.fn(async () => {
+        throw new Error("diagnostic write failed");
+      }),
+    });
+
+    await expect(
+      prepareOnboardSession(
+        {
+          resume: true,
+          fresh: false,
+          requestedFromDockerfile: null,
+          requestedSandboxName: "new-box",
+          cannotPrompt: false,
+          nonInteractive: false,
+        },
+        deps,
+      ),
+    ).rejects.toThrow(ExitError);
+
+    expect(deps.recordResumeConflict).toHaveBeenCalledWith(conflict);
+    expect(deps.error).toHaveBeenCalledWith(
+      "  Resumable state belongs to sandbox 'old-box', not 'new-box'.",
+    );
+    expect(deps.exitProcess).toHaveBeenCalledWith(1);
+    expect(deps.updateSession).not.toHaveBeenCalled();
+  });
+
+  it("rejects non-interactive resume when no sandbox name can be recovered", async () => {
+    const { deps } = createDeps(createSession({ sandboxName: null }));
+
+    await expect(
+      prepareOnboardSession(
+        {
+          resume: true,
+          fresh: false,
+          requestedFromDockerfile: null,
+          requestedSandboxName: null,
+          cannotPrompt: true,
+          nonInteractive: true,
+        },
+        deps,
+      ),
+    ).rejects.toThrow(ExitError);
+
+    expect(deps.error).toHaveBeenCalledWith(
+      "  Cannot resume non-interactive onboard: the previous run was interrupted before sandbox creation completed,",
+    );
+    expect(deps.error).toHaveBeenCalledWith(
+      "  so no sandbox name was recorded. Re-run with --name <sandbox> (or set NEMOCLAW_SANDBOX_NAME).",
+    );
+    expect(deps.exitProcess).toHaveBeenCalledTimes(1);
+  });
+});