test(config): align optimistic write helpers

src/commands/agents.add.test.ts

@@ -3,6 +3,9 @@ import { baseConfigSnapshot, createTestRuntime } from "./test-runtime-config-hel
 
 const readConfigFileSnapshotMock = vi.hoisted(() => vi.fn());
 const writeConfigFileMock = vi.hoisted(() => vi.fn().mockResolvedValue(undefined));
+const replaceConfigFileMock = vi.hoisted(() =>
+  vi.fn(async (params: { nextConfig: unknown }) => await writeConfigFileMock(params.nextConfig)),
+);
 
 const wizardMocks = vi.hoisted(() => ({
   createClackPrompter: vi.fn(),
@@ -12,6 +15,7 @@ vi.mock("../config/config.js", async (importOriginal) => ({
   ...(await importOriginal<typeof import("../config/config.js")>()),
   readConfigFileSnapshot: readConfigFileSnapshotMock,
   writeConfigFile: writeConfigFileMock,
+  replaceConfigFile: replaceConfigFileMock,
 }));
 
 vi.mock("../wizard/clack-prompter.js", () => ({
@@ -27,6 +31,7 @@ describe("agents add command", () => {
   beforeEach(() => {
     readConfigFileSnapshotMock.mockClear();
     writeConfigFileMock.mockClear();
+    replaceConfigFileMock.mockClear();
     wizardMocks.createClackPrompter.mockClear();
     runtime.log.mockClear();
     runtime.error.mockClear();

src/commands/agents.bind.test-support.ts

@@ -1,9 +1,25 @@
 import { vi } from "vitest";
+import type { OpenClawConfig } from "../config/config.js";
 import { mergeMockedModule } from "../test-utils/vitest-module-mocks.js";
 import { createTestRuntime } from "./test-runtime-config-helpers.js";
 
+type ReplaceConfigFileResult = Awaited<
+  ReturnType<(typeof import("../config/config.js"))["replaceConfigFile"]>
+>;
+
 export const readConfigFileSnapshotMock = vi.fn();
 export const writeConfigFileMock = vi.fn().mockResolvedValue(undefined);
+export const replaceConfigFileMock = vi.fn(
+  async (params: { nextConfig: OpenClawConfig }): Promise<ReplaceConfigFileResult> => {
+    await writeConfigFileMock(params.nextConfig);
+    return {
+      path: "/tmp/openclaw.json",
+      previousHash: null,
+      snapshot: {} as never,
+      nextConfig: params.nextConfig,
+    };
+  },
+);
 
 vi.mock("../config/config.js", async (importOriginal) => {
   return await mergeMockedModule(
@@ -11,6 +27,7 @@ vi.mock("../config/config.js", async (importOriginal) => {
     () => ({
       readConfigFileSnapshot: readConfigFileSnapshotMock,
       writeConfigFile: writeConfigFileMock,
+      replaceConfigFile: replaceConfigFileMock,
     }),
   );
 });
@@ -25,6 +42,7 @@ export async function loadFreshAgentsCommandModuleForTest() {
 export function resetAgentsBindTestHarness(): void {
   readConfigFileSnapshotMock.mockClear();
   writeConfigFileMock.mockClear();
+  replaceConfigFileMock.mockClear();
   runtime.log.mockClear();
   runtime.error.mockClear();
   runtime.exit.mockClear();

src/commands/agents.identity.test.ts

@@ -4,15 +4,22 @@ import { beforeEach, describe, expect, it, vi } from "vitest";
 import { makeTempWorkspace } from "../test-helpers/workspace.js";
 import { baseConfigSnapshot, createTestRuntime } from "./test-runtime-config-helpers.js";
 
-const configMocks = vi.hoisted(() => ({
-  readConfigFileSnapshot: vi.fn(),
-  writeConfigFile: vi.fn().mockResolvedValue(undefined),
-}));
+const configMocks = vi.hoisted(() => {
+  const writeConfigFile = vi.fn().mockResolvedValue(undefined);
+  return {
+    readConfigFileSnapshot: vi.fn(),
+    writeConfigFile,
+    replaceConfigFile: vi.fn(async (params: { nextConfig: unknown }) => {
+      await writeConfigFile(params.nextConfig);
+    }),
+  };
+});
 
 vi.mock("../config/config.js", async (importOriginal) => ({
   ...(await importOriginal<typeof import("../config/config.js")>()),
   readConfigFileSnapshot: configMocks.readConfigFileSnapshot,
   writeConfigFile: configMocks.writeConfigFile,
+  replaceConfigFile: configMocks.replaceConfigFile,
 }));
 
 import { agentsSetIdentityCommand } from "./agents.js";
@@ -52,6 +59,7 @@ describe("agents set-identity command", () => {
   beforeEach(() => {
     configMocks.readConfigFileSnapshot.mockClear();
     configMocks.writeConfigFile.mockClear();
+    configMocks.replaceConfigFile.mockClear();
     runtime.log.mockClear();
     runtime.error.mockClear();
     runtime.exit.mockClear();

src/commands/channels.mock-harness.ts

@@ -5,12 +5,20 @@ function buildBundledPluginModuleId(pluginId: string, artifactBasename: string):
   return ["..", "..", "extensions", pluginId, artifactBasename].join("/");
 }
 
+const readConfigFileSnapshotMock = vi.fn() as unknown as MockFn;
+const writeConfigFileMock = vi.fn().mockResolvedValue(undefined) as unknown as MockFn;
+const replaceConfigFileMock = vi.fn(async (params: { nextConfig: unknown }) => {
+  await writeConfigFileMock(params.nextConfig);
+}) as unknown as MockFn;
+
 export const configMocks: {
   readConfigFileSnapshot: MockFn;
   writeConfigFile: MockFn;
+  replaceConfigFile: MockFn;
 } = {
-  readConfigFileSnapshot: vi.fn() as unknown as MockFn,
-  writeConfigFile: vi.fn().mockResolvedValue(undefined) as unknown as MockFn,
+  readConfigFileSnapshot: readConfigFileSnapshotMock,
+  writeConfigFile: writeConfigFileMock,
+  replaceConfigFile: replaceConfigFileMock,
 };
 
 export const offsetMocks: {
@@ -25,6 +33,7 @@ vi.mock("../config/config.js", async (importOriginal) => {
     ...actual,
     readConfigFileSnapshot: configMocks.readConfigFileSnapshot,
     writeConfigFile: configMocks.writeConfigFile,
+    replaceConfigFile: configMocks.replaceConfigFile,
   };
 });
 

src/commands/channels.resolve.test.ts

@@ -4,8 +4,9 @@ const mocks = vi.hoisted(() => ({
   resolveCommandSecretRefsViaGateway: vi.fn(),
   getChannelsCommandSecretTargetIds: vi.fn(() => []),
   loadConfig: vi.fn(),
+  readConfigFileSnapshot: vi.fn(),
   applyPluginAutoEnable: vi.fn(),
-  writeConfigFile: vi.fn(),
+  replaceConfigFile: vi.fn(),
   resolveMessageChannelSelection: vi.fn(),
   resolveInstallableChannelPlugin: vi.fn(),
   getChannelPlugin: vi.fn(),
@@ -21,7 +22,8 @@ vi.mock("../cli/command-secret-targets.js", () => ({
 
 vi.mock("../config/config.js", () => ({
   loadConfig: mocks.loadConfig,
-  writeConfigFile: mocks.writeConfigFile,
+  readConfigFileSnapshot: mocks.readConfigFileSnapshot,
+  replaceConfigFile: mocks.replaceConfigFile,
 }));
 
 vi.mock("../config/plugin-auto-enable.js", () => ({
@@ -52,8 +54,9 @@ describe("channelsResolveCommand", () => {
   beforeEach(() => {
     vi.clearAllMocks();
     mocks.loadConfig.mockReturnValue({ channels: {} });
+    mocks.readConfigFileSnapshot.mockResolvedValue({ hash: "config-1" });
     mocks.applyPluginAutoEnable.mockImplementation(({ config }) => ({ config, changes: [] }));
-    mocks.writeConfigFile.mockResolvedValue(undefined);
+    mocks.replaceConfigFile.mockResolvedValue(undefined);
     mocks.resolveCommandSecretRefsViaGateway.mockResolvedValue({
       resolvedConfig: { channels: {} },
       diagnostics: [],
@@ -106,7 +109,10 @@ describe("channelsResolveCommand", () => {
         allowInstall: true,
       }),
     );
-    expect(mocks.writeConfigFile).toHaveBeenCalledWith(installedCfg);
+    expect(mocks.replaceConfigFile).toHaveBeenCalledWith({
+      nextConfig: installedCfg,
+      baseHash: "config-1",
+    });
     expect(resolveTargets).toHaveBeenCalledWith(
       expect.objectContaining({
         cfg: installedCfg,

src/commands/channels/capabilities.test.ts

@@ -10,7 +10,8 @@ const logs: string[] = [];
 const errors: string[] = [];
 const resolveDefaultAccountId = () => DEFAULT_ACCOUNT_ID;
 const mocks = vi.hoisted(() => ({
-  writeConfigFile: vi.fn(),
+  readConfigFileSnapshot: vi.fn(),
+  replaceConfigFile: vi.fn(),
   resolveInstallableChannelPlugin: vi.fn(),
 }));
 
@@ -30,7 +31,8 @@ vi.mock("../../config/config.js", async (importOriginal) => {
   const actual = await importOriginal<typeof import("../../config/config.js")>();
   return {
     ...actual,
-    writeConfigFile: mocks.writeConfigFile,
+    readConfigFileSnapshot: mocks.readConfigFileSnapshot,
+    replaceConfigFile: mocks.replaceConfigFile,
   };
 });
 
@@ -95,7 +97,8 @@ describe("channelsCapabilitiesCommand", () => {
   beforeEach(() => {
     resetOutput();
     vi.clearAllMocks();
-    mocks.writeConfigFile.mockResolvedValue(undefined);
+    mocks.readConfigFileSnapshot.mockResolvedValue({ hash: "config-1" });
+    mocks.replaceConfigFile.mockResolvedValue(undefined);
     mocks.resolveInstallableChannelPlugin.mockResolvedValue({
       cfg: { channels: {} },
       configChanged: false,
@@ -211,11 +214,12 @@ describe("channelsCapabilitiesCommand", () => {
         allowInstall: true,
       }),
     );
-    expect(mocks.writeConfigFile).toHaveBeenCalledWith(
-      expect.objectContaining({
+    expect(mocks.replaceConfigFile).toHaveBeenCalledWith({
+      nextConfig: expect.objectContaining({
         plugins: { entries: { whatsapp: { enabled: true } } },
       }),
-    );
+      baseHash: "config-1",
+    });
     expect(logs.join("\n")).toContain("Probe: linked");
   });
 });

src/commands/configure.wizard.test.ts

@@ -1,26 +1,32 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
 
-const mocks = vi.hoisted(() => ({
-  clackIntro: vi.fn(),
-  clackOutro: vi.fn(),
-  clackSelect: vi.fn(),
-  clackText: vi.fn(),
-  clackConfirm: vi.fn(),
-  resolveSearchProviderOptions: vi.fn(),
-  setupSearch: vi.fn(),
-  readConfigFileSnapshot: vi.fn(),
-  writeConfigFile: vi.fn(),
-  resolveGatewayPort: vi.fn(),
-  ensureControlUiAssetsBuilt: vi.fn(),
-  createClackPrompter: vi.fn(),
-  note: vi.fn(),
-  printWizardHeader: vi.fn(),
-  probeGatewayReachable: vi.fn(),
-  waitForGatewayReachable: vi.fn(),
-  resolveControlUiLinks: vi.fn(),
-  summarizeExistingConfig: vi.fn(),
-}));
+const mocks = vi.hoisted(() => {
+  const writeConfigFile = vi.fn();
+  return {
+    clackIntro: vi.fn(),
+    clackOutro: vi.fn(),
+    clackSelect: vi.fn(),
+    clackText: vi.fn(),
+    clackConfirm: vi.fn(),
+    resolveSearchProviderOptions: vi.fn(),
+    setupSearch: vi.fn(),
+    readConfigFileSnapshot: vi.fn(),
+    writeConfigFile,
+    replaceConfigFile: vi.fn(async (params: { nextConfig: unknown }) => {
+      await writeConfigFile(params.nextConfig);
+    }),
+    resolveGatewayPort: vi.fn(),
+    ensureControlUiAssetsBuilt: vi.fn(),
+    createClackPrompter: vi.fn(),
+    note: vi.fn(),
+    printWizardHeader: vi.fn(),
+    probeGatewayReachable: vi.fn(),
+    waitForGatewayReachable: vi.fn(),
+    resolveControlUiLinks: vi.fn(),
+    summarizeExistingConfig: vi.fn(),
+  };
+});
 
 vi.mock("@clack/prompts", () => ({
   intro: mocks.clackIntro,
@@ -34,6 +40,7 @@ vi.mock("../config/config.js", () => ({
   CONFIG_PATH: "~/.openclaw/openclaw.json",
   readConfigFileSnapshot: mocks.readConfigFileSnapshot,
   writeConfigFile: mocks.writeConfigFile,
+  replaceConfigFile: mocks.replaceConfigFile,
   resolveGatewayPort: mocks.resolveGatewayPort,
 }));