refactor(snapshot): lower cognitive complexity ratchet to 184

biome.json

@@ -86,7 +86,7 @@
         "noExcessiveCognitiveComplexity": {
           "level": "error",
           "options": {
-            "maxAllowedComplexity": 186
+            "maxAllowedComplexity": 184
           }
         }
       },

src/lib/actions/sandbox/rebuild.ts

@@ -507,6 +507,16 @@ function preflightRebuildCredentials(
   return false;
 }
 
+function hydrateMessagingConfigForRebuild(sandboxName: string, log: (msg: string) => void): void {
+  const rebuildSession = onboardSession.loadSession();
+  const hydratedMessagingConfig = hydrateMessagingChannelConfig(
+    getStoredMessagingChannelConfig(sandboxName, rebuildSession),
+  );
+  if (hydratedMessagingConfig) {
+    log(`Stashed messaging config for rebuild: ${Object.keys(hydratedMessagingConfig).join(",")}`);
+  }
+}
+
 function printRebuildVersionSummary(
   sandboxName: string,
   agentName: string,
@@ -595,17 +605,7 @@ export async function rebuildSandbox(
   // destructive. The manifest plan in registry is the durable source; legacy
   // session channel fields are read only as compatibility fallback by
   // getStoredMessagingChannelConfig().
-  {
-    const rebuildSession = onboardSession.loadSession();
-    const hydratedMessagingConfig = hydrateMessagingChannelConfig(
-      getStoredMessagingChannelConfig(sandboxName, rebuildSession),
-    );
-    if (hydratedMessagingConfig) {
-      log(
-        `Stashed messaging config for rebuild: ${Object.keys(hydratedMessagingConfig).join(",")}`,
-      );
-    }
-  }
+  hydrateMessagingConfigForRebuild(sandboxName, log);
 
   // Version check — show what's changing
   const versionCheck = sandboxVersion.checkAgentVersion(sandboxName);

src/lib/actions/sandbox/snapshot.test.ts

@@ -3,13 +3,24 @@
 
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
+const shieldsMock = vi.hoisted(() => {
+  const isShieldsDownMock = vi.fn(() => true);
+  let isShieldsDownExport: unknown = isShieldsDownMock;
+  return {
+    isShieldsDownMock,
+    getIsShieldsDownExport: () => isShieldsDownExport,
+    setIsShieldsDownExport: (value: unknown) => {
+      isShieldsDownExport = value;
+    },
+  };
+});
+
 const backupSandboxStateMock = vi.fn();
 const captureOpenshellMock = vi.fn(() => ({ status: 0, output: "alpha Ready\n" }));
 const dockerInspectMock = vi.fn(() => ({ status: 0, stdout: "true\n" }));
-const getSandboxMock = vi.fn(() => null);
 const findBackupMock = vi.fn();
+const getSandboxMock = vi.fn(() => null);
 const isGatewayHealthyMock = vi.fn(() => true);
-const isShieldsDownMock = vi.fn();
 const listBackupsMock = vi.fn<() => Array<Record<string, unknown>>>(() => []);
 const parseLiveSandboxNamesMock = vi.fn(() => new Set(["alpha"]));
 const restoreSandboxStateMock = vi.fn();
@@ -47,7 +58,9 @@ vi.mock("../../runtime-recovery", () => ({
 }));
 
 vi.mock("../../shields", () => ({
-  isShieldsDown: isShieldsDownMock,
+  get isShieldsDown() {
+    return shieldsMock.getIsShieldsDownExport();
+  },
   repairMutableConfigPerms: vi.fn(() => ({ applied: true, verified: true, errors: [] })),
 }));
 
@@ -77,12 +90,13 @@ vi.mock("./destroy", () => ({
 describe("runSandboxSnapshot", () => {
   beforeEach(() => {
     vi.clearAllMocks();
+    shieldsMock.setIsShieldsDownExport(shieldsMock.isShieldsDownMock);
+    shieldsMock.isShieldsDownMock.mockReturnValue(true);
     captureOpenshellMock.mockReturnValue({ status: 0, output: "alpha Ready\n" });
     dockerInspectMock.mockReturnValue({ status: 0, stdout: "true\n" });
     findBackupMock.mockReturnValue({ match: null });
     getSandboxMock.mockReturnValue(null);
     isGatewayHealthyMock.mockReturnValue(true);
-    isShieldsDownMock.mockReturnValue(true);
     listBackupsMock.mockReturnValue([]);
     restoreSandboxStateMock.mockReturnValue({
       success: true,
@@ -99,9 +113,8 @@ describe("runSandboxSnapshot", () => {
   });
 
   it("refuses snapshot creation before backup when the shields gate helper is unavailable", async () => {
+    shieldsMock.setIsShieldsDownExport(undefined);
     const consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
-    const shields = await import("../../shields");
-    vi.mocked(shields).isShieldsDown = undefined as never;
     const { runSandboxSnapshot } = await import("./snapshot");
 
     await expect(runSandboxSnapshot("alpha", { kind: "create" })).rejects.toMatchObject({
@@ -112,7 +125,6 @@ describe("runSandboxSnapshot", () => {
     expect(consoleError.mock.calls.flat().join("\n")).toContain(
       "Cannot verify shields state. Refusing to create snapshot.",
     );
-    vi.mocked(shields).isShieldsDown = isShieldsDownMock as never;
   });
 
   it("creates a named snapshot after gateway, liveness, and shields checks pass", async () => {
@@ -172,4 +184,58 @@ describe("runSandboxSnapshot", () => {
     expect(output).toContain("/tmp/alpha/v2");
     expect(output).toContain("2 snapshot(s). Restore with:");
   });
+
+  it("refuses snapshot creation before backup when the sandbox is not live", async () => {
+    parseLiveSandboxNamesMock.mockReturnValue(new Set(["beta"]));
+    const consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
+    const { runSandboxSnapshot } = await import("./snapshot");
+
+    await expect(runSandboxSnapshot("alpha", { kind: "create" })).rejects.toMatchObject({
+      exitCode: 1,
+    });
+
+    expect(backupSandboxStateMock).not.toHaveBeenCalled();
+    expect(consoleError.mock.calls.flat().join("\n")).toContain(
+      "Sandbox 'alpha' is not running. Cannot create snapshot.",
+    );
+  });
+
+  it("prints backup error details when snapshot creation fails with an error", async () => {
+    backupSandboxStateMock.mockReturnValue({
+      success: false,
+      error: "tar exploded",
+      failedDirs: [],
+      failedFiles: [],
+    });
+    const consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
+    vi.spyOn(console, "log").mockImplementation(() => {});
+    const { runSandboxSnapshot } = await import("./snapshot");
+
+    await expect(runSandboxSnapshot("alpha", { kind: "create" })).rejects.toMatchObject({
+      exitCode: 1,
+    });
+
+    expect(backupSandboxStateMock).toHaveBeenCalledWith("alpha", { name: null });
+    expect(consoleError.mock.calls.flat().join("\n")).toContain("tar exploded");
+  });
+
+  it("prints failed dirs and files when snapshot creation fails without an error", async () => {
+    backupSandboxStateMock.mockReturnValue({
+      success: false,
+      failedDirs: ["workspace", "skills"],
+      failedFiles: ["openclaw.json"],
+    });
+    const consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
+    vi.spyOn(console, "log").mockImplementation(() => {});
+    const { runSandboxSnapshot } = await import("./snapshot");
+
+    await expect(runSandboxSnapshot("alpha", { kind: "create" })).rejects.toMatchObject({
+      exitCode: 1,
+    });
+
+    const errors = consoleError.mock.calls.flat().join("\n");
+    expect(errors).toContain("Snapshot failed.");
+    expect(errors).toContain("Failed directories: workspace, skills");
+    expect(errors).toContain("Failed files: openclaw.json");
+  });
 });

src/lib/actions/sandbox/snapshot.ts

@@ -328,9 +328,11 @@ function verifyRestoreDestinationOnOwnGateway(targetSandbox: string): void {
 }
 
 function isSnapshotCreationAllowedByShields(sandboxName: string): boolean {
-  // Snapshot creation is a shields/policy boundary. If a packaged or mocked
-  // CommonJS interop surface ever omits the helper, fail closed before any
-  // backup side effect instead of throwing an ambiguous TypeError.
+  // Snapshot creation is a shields/policy boundary. Production builds should
+  // always export this helper, but stale compiled artifacts, package-boundary
+  // skew, or test doubles can present a missing CommonJS interop surface. There
+  // is no safe runtime source fix once snapshot creation has started, so keep
+  // this as permanent defense-in-depth and fail closed before backup side effects.
   const isShieldsDown = shields.isShieldsDown;
   if (typeof isShieldsDown !== "function") {
     console.error("  Cannot verify shields state. Refusing to create snapshot.");
@@ -339,57 +341,57 @@ function isSnapshotCreationAllowedByShields(sandboxName: string): boolean {
   return isShieldsDown(sandboxName);
 }
 
+function runSnapshotCreate(
+  sandboxName: string,
+  request: Extract<SnapshotRequest, { kind: "create" }>,
+): void {
+  const liveNames = requireLiveSandboxesOnSandboxGateway(
+    sandboxName,
+    "  Failed to query live sandbox state from OpenShell.",
+  );
+  if (!liveNames.has(sandboxName)) {
+    console.error(`  Sandbox '${sandboxName}' is not running. Cannot create snapshot.`);
+    snapshotExit(1);
+  }
+  if (!isSnapshotCreationAllowedByShields(sandboxName)) {
+    console.error("  Cannot create snapshot while shields are up.");
+    console.error(`  Run \`${CLI_NAME} ${sandboxName} shields down\` first, then retry.`);
+    snapshotExit(1);
+  }
+  const label = request.name ? ` (--name ${request.name})` : "";
+  console.log(`  Creating snapshot of '${sandboxName}'${label}...`);
+  const result = sandboxState.backupSandboxState(sandboxName, { name: request.name ?? null });
+  if (result.success) {
+    const manifest = result.manifest!;
+    const entry = sandboxState.findBackup(sandboxName, manifest.timestamp).match ?? manifest;
+    const v = formatSnapshotVersion(entry);
+    const nameSuffix = entry.name ? ` name=${entry.name}` : "";
+    const itemSummary = `${result.backedUpDirs.length} directories, ${result.backedUpFiles.length} files`;
+    console.log(`  ${G}✓${R} Snapshot ${v}${nameSuffix} created (${itemSummary})`);
+    console.log(`    ${manifest.backupPath}`);
+    return;
+  }
+  if (result.error) {
+    console.error(`  ${result.error}`);
+  } else {
+    console.error("  Snapshot failed.");
+    if (result.failedDirs.length > 0) {
+      console.error(`  Failed directories: ${result.failedDirs.join(", ")}`);
+    }
+    if (result.failedFiles.length > 0) {
+      console.error(`  Failed files: ${result.failedFiles.join(", ")}`);
+    }
+  }
+  snapshotExit(1);
+}
+
 export async function runSandboxSnapshot(
   sandboxName: string,
   request: SnapshotRequest = { kind: "help" },
 ) {
   switch (request.kind) {
     case "create": {
-      // Select the sandbox's gateway before the health probe and `sandbox list`
-      // — Docker/VM-driver health and the sandbox listing both require the
-      // sandbox's gateway to be the active one, otherwise a sandbox registered
-      // on a non-default `NEMOCLAW_GATEWAY_PORT` fails health-check before the
-      // subsequent list ever runs.
-      const liveNames = requireLiveSandboxesOnSandboxGateway(
-        sandboxName,
-        "  Failed to query live sandbox state from OpenShell.",
-      );
-      if (!liveNames.has(sandboxName)) {
-        console.error(`  Sandbox '${sandboxName}' is not running. Cannot create snapshot.`);
-        snapshotExit(1);
-      }
-      if (!isSnapshotCreationAllowedByShields(sandboxName)) {
-        console.error("  Cannot create snapshot while shields are up.");
-        console.error(`  Run \`${CLI_NAME} ${sandboxName} shields down\` first, then retry.`);
-        snapshotExit(1);
-      }
-      const label = request.name ? ` (--name ${request.name})` : "";
-      console.log(`  Creating snapshot of '${sandboxName}'${label}...`);
-      const result = sandboxState.backupSandboxState(sandboxName, { name: request.name ?? null });
-      if (result.success) {
-        // Virtual snapshotVersion is only assigned by listBackups, so re-resolve
-        // the just-created snapshot by its timestamp to get a valid v<N>.
-        const manifest = result.manifest!;
-        const entry = sandboxState.findBackup(sandboxName, manifest.timestamp).match ?? manifest;
-        const v = formatSnapshotVersion(entry);
-        const nameSuffix = entry.name ? ` name=${entry.name}` : "";
-        const itemSummary = `${result.backedUpDirs.length} directories, ${result.backedUpFiles.length} files`;
-        console.log(`  ${G}\u2713${R} Snapshot ${v}${nameSuffix} created (${itemSummary})`);
-        console.log(`    ${manifest.backupPath}`);
-      } else {
-        if (result.error) {
-          console.error(`  ${result.error}`);
-        } else {
-          console.error("  Snapshot failed.");
-          if (result.failedDirs.length > 0) {
-            console.error(`  Failed directories: ${result.failedDirs.join(", ")}`);
-          }
-          if (result.failedFiles.length > 0) {
-            console.error(`  Failed files: ${result.failedFiles.join(", ")}`);
-          }
-        }
-        snapshotExit(1);
-      }
+      runSnapshotCreate(sandboxName, request);
       break;
     }
     case "list": {

src/lib/onboard.ts

@@ -25,6 +25,7 @@ const {
   applyCloudFallbackSelection,
   clearNimContainerBeforeRetry,
   createRemoteModelValidator,
+  requireProviderChoice,
 }: typeof import("./onboard/setup-nim-selection") = require("./onboard/setup-nim-selection");
 const inferenceInputCapability = require("./onboard/inference-input-capability");
 const { cleanupTempDir }: typeof import("./onboard/temp-files") = require("./onboard/temp-files");
@@ -4071,10 +4072,7 @@ async function setupNim(
         });
       }
 
-      if (!selected) {
-        console.error("  No provider was selected.");
-        process.exit(1);
-      }
+      selected = requireProviderChoice(selected);
       if (selected.key !== "hermesProvider") {
         hermesAuthMethod = null;
         hermesToolGateways = [];

src/lib/onboard/setup-nim-selection.ts

@@ -41,6 +41,14 @@ type ProviderChoice = {
   key: string;
 };
 
+export function requireProviderChoice<T extends ProviderChoice>(selected: T | undefined): T {
+  if (!selected) {
+    console.error("  No provider was selected.");
+    process.exit(1);
+  }
+  return selected;
+}
+
 type RemoteProviderConfig = {
   label: string;
   endpointUrl: string;