const mocks = vi.hoisted(() => ({

updateCommand: vi.fn(async (_opts: unknown) => {}),

updateFinalizeCommand: vi.fn(async (_opts: unknown) => {}),

updateStatusCommand: vi.fn(async (_opts: unknown) => {}),

updateWizardCommand: vi.fn(async (_opts: unknown) => {}),

defaultRuntime: {

},

}));

const { updateCommand, updateStatusCommand, updateWizardCommand, defaultRuntime } = mocks;

const {

updateCommand,

updateFinalizeCommand,

updateStatusCommand,

updateWizardCommand,

defaultRuntime,

} = mocks;

vi.mock("./update-cli/update-command.js", () => ({

updateCommand: (opts: unknown) => mocks.updateCommand(opts),

updateFinalizeCommand: (opts: unknown) => mocks.updateFinalizeCommand(opts),

}));

vi.mock("./update-cli/status.js", () => ({

describe("update cli option collisions", () => {

beforeEach(() => {

updateCommand.mockClear();

updateFinalizeCommand.mockClear();

updateStatusCommand.mockClear();

updateWizardCommand.mockClear();

defaultRuntime.log.mockClear();

expect((opts as { json?: boolean; timeout?: string } | undefined)?.timeout).toBe("9");

},

},

{

name: "forwards parent-captured --json/--timeout to hidden `update finalize`",

argv: ["update", "finalize", "--json", "--timeout", "17", "--no-restart"],

assert: () => {

expect(updateFinalizeCommand).toHaveBeenCalledTimes(1);

const opts = firstCallOptions(updateFinalizeCommand);

expect(

(opts as { json?: boolean; timeout?: string; restart?: boolean } | undefined)?.json,

).toBe(true);

expect(

(opts as { json?: boolean; timeout?: string; restart?: boolean } | undefined)?.timeout,

).toBe("17");

expect(

(opts as { json?: boolean; timeout?: string; restart?: boolean } | undefined)?.restart,

).toBe(false);

},

},

{

name: "forwards parent-captured --timeout to `update wizard`",

argv: ["update", "wizard", "--timeout", "13"],

const { runDaemonRestart, runDaemonInstall } = await import("./daemon-cli.js");

const { doctorCommand } = await import("../commands/doctor.js");

const { defaultRuntime } = await import("../runtime.js");

const { updateCommand, updateStatusCommand, updateWizardCommand } = await import("./update-cli.js");

const { updateCommand, updateFinalizeCommand, updateStatusCommand, updateWizardCommand } =

await import("./update-cli.js");

const updateCliShared = await import("./update-cli/shared.js");

const { resolveGitInstallDir } = updateCliShared;

const { spawnSync } = await import("node:child_process");

}

});

it("updateFinalizeCommand runs doctor and plugin convergence with full update env", async () => {

await withEnvAsync(

{

OPENCLAW_UPDATE_IN_PROGRESS: undefined,

OPENCLAW_UPDATE_PARENT_SUPPORTS_DOCTOR_CONFIG_WRITE: undefined,

},

async () => {

let doctorEnv: NodeJS.ProcessEnv | undefined;

vi.mocked(doctorCommand).mockImplementationOnce(async () => {

doctorEnv = { ...process.env };

});

vi.mocked(defaultRuntime.writeJson).mockClear();

await updateFinalizeCommand({ json: true, yes: true, timeout: "9", restart: false });

expect(doctorEnv?.OPENCLAW_UPDATE_IN_PROGRESS).toBe("1");

expect(doctorEnv?.OPENCLAW_UPDATE_PARENT_SUPPORTS_DOCTOR_CONFIG_WRITE).toBe("1");

expect(process.env.OPENCLAW_UPDATE_IN_PROGRESS).toBeUndefined();

expect(process.env.OPENCLAW_UPDATE_PARENT_SUPPORTS_DOCTOR_CONFIG_WRITE).toBeUndefined();

expect(doctorCommand).toHaveBeenCalledWith(defaultRuntime, {

nonInteractive: true,

yes: true,

});

expect(syncPluginCall()?.channel).toBe("stable");

expect(lastNpmPluginUpdateCall()?.timeoutMs).toBe(9_000);

const output = lastWriteJsonCall() as

| {

status?: string;

mode?: string;

restart?: boolean;

postUpdate?: { doctor?: { status?: string }; plugins?: { status?: string } };

}

| undefined;

expect(output?.status).toBe("ok");

expect(output?.mode).toBe("finalize");

expect(output?.restart).toBe(false);

expect(output?.postUpdate?.doctor?.status).toBe("ok");

expect(output?.postUpdate?.plugins?.status).toBe("ok");

},

);

});

it.each([

{

name: "update command invalid timeout",

import { formatHelpExamples } from "./help-format.js";

import {

type UpdateCommandOptions,

type UpdateFinalizeOptions,

type UpdateStatusOptions,

type UpdateWizardOptions,

} from "./update-cli/shared.js";

import { updateStatusCommand } from "./update-cli/status.js";

import { updateCommand } from "./update-cli/update-command.js";

import { updateCommand, updateFinalizeCommand } from "./update-cli/update-command.js";

import { updateWizardCommand } from "./update-cli/wizard.js";

export { updateCommand, updateStatusCommand, updateWizardCommand };

export type { UpdateCommandOptions, UpdateStatusOptions, UpdateWizardOptions };

export { updateCommand, updateFinalizeCommand, updateStatusCommand, updateWizardCommand };

export type {

UpdateCommandOptions,

UpdateFinalizeOptions,

UpdateStatusOptions,

UpdateWizardOptions,

};

function inheritedUpdateJson(command?: Command): boolean {

return Boolean(inheritOptionFromParent<boolean>(command, "json"));

}

});

update

.command("finalize", { hidden: true })

.description("Run OpenClaw update finalization after an external core runtime change")

.option("--json", "Output result as JSON", false)

.option("--channel <stable|beta|dev>", "Persist update channel for finalization")

.option(

"--timeout <seconds>",

"Timeout for update finalization steps in seconds (default: 1800)",

)

.option("--yes", "Skip confirmation prompts (non-interactive)", false)

.option("--no-restart", "Accepted for update command parity; finalization never restarts")

.action(async (opts, command) => {

try {

await updateFinalizeCommand({

json: Boolean(opts.json) || inheritedUpdateJson(command),

channel: opts.channel as string | undefined,

timeout: inheritedUpdateTimeout(opts, command),

yes: Boolean(opts.yes),

restart: Boolean(opts.restart),

});

} catch (err) {

defaultRuntime.error(String(err));

defaultRuntime.exit(1);

}

});

update

.command("wizard")

.description("Interactive update wizard")

timeout?: string;

};

export type UpdateFinalizeOptions = {

json?: boolean;

channel?: string;

timeout?: string;

yes?: boolean;

restart?: boolean;

};

export type UpdateWizardOptions = {

timeout?: string;

};

runUpdateStep,

tryWriteCompletionCache,

type UpdateCommandOptions,

type UpdateFinalizeOptions,

} from "./shared.js";

import { suppressDeprecations } from "./suppress-deprecations.js";

});

}

type UpdateFinalizeResult = {

status: "ok" | "warning" | "error";

mode: "finalize";

root: string;

channel: "stable" | "beta" | "dev";

restart: false;

postUpdate: {

doctor: {

status: "ok";

};

plugins: PostCorePluginUpdateResult;

};

};

function withUpdateFinalizationEnv<T>(run: () => Promise<T>): Promise<T> {

const previousUpdateInProgress = process.env.OPENCLAW_UPDATE_IN_PROGRESS;

const previousParentSupportsDoctorConfigWrite =

process.env[UPDATE_PARENT_SUPPORTS_DOCTOR_CONFIG_WRITE_ENV];

process.env.OPENCLAW_UPDATE_IN_PROGRESS = "1";

process.env[UPDATE_PARENT_SUPPORTS_DOCTOR_CONFIG_WRITE_ENV] = "1";

return run().finally(() => {

if (previousUpdateInProgress === undefined) {

delete process.env.OPENCLAW_UPDATE_IN_PROGRESS;

} else {

process.env.OPENCLAW_UPDATE_IN_PROGRESS = previousUpdateInProgress;

}

if (previousParentSupportsDoctorConfigWrite === undefined) {

delete process.env[UPDATE_PARENT_SUPPORTS_DOCTOR_CONFIG_WRITE_ENV];

} else {

process.env[UPDATE_PARENT_SUPPORTS_DOCTOR_CONFIG_WRITE_ENV] =

previousParentSupportsDoctorConfigWrite;

}

});

}

export async function updateFinalizeCommand(opts: UpdateFinalizeOptions): Promise<void> {

suppressDeprecations();

const timeoutMs = parseTimeoutMsOrExit(opts.timeout);

if (timeoutMs === null) {

return;

}

assertConfigWriteAllowedInCurrentMode();

const root = await resolveUpdateRoot();

let configSnapshot = await readConfigFileSnapshot();

const requestedChannel = normalizeUpdateChannel(opts.channel);

if (opts.channel && !requestedChannel) {

defaultRuntime.error(`--channel must be "stable", "beta", or "dev" (got "${opts.channel}")`);

defaultRuntime.exit(1);

return;

}

const storedChannel = configSnapshot.valid

? normalizeUpdateChannel(configSnapshot.config.update?.channel)

: null;

const channel = requestedChannel ?? storedChannel ?? DEFAULT_PACKAGE_CHANNEL;

if (requestedChannel) {

configSnapshot = await persistRequestedUpdateChannel({

configSnapshot,

requestedChannel,

});

}

const pluginInstallRecords = await loadInstalledPluginIndexInstallRecords();

const pluginUpdate = await withUpdateFinalizationEnv(async () => {

await createUpdateConfigSnapshot();

await doctorCommand(defaultRuntime, {

nonInteractive: true,

yes: opts.yes === true,

});

return await runPostCorePluginUpdate({

root,

channel,

configSnapshot,

opts: {

json: opts.json,

timeout: opts.timeout,

yes: opts.yes,

restart: false,

},

timeoutMs: timeoutMs ?? DEFAULT_UPDATE_STEP_TIMEOUT_MS,

pluginInstallRecords,

});

});

const result: UpdateFinalizeResult = {

status:

pluginUpdate.status === "error"

? "error"

: pluginUpdate.status === "warning"

? "warning"

: "ok",

mode: "finalize",

root,

channel,

restart: false,

postUpdate: {

doctor: {

status: "ok",

},

plugins: pluginUpdate,

},

};

await tryWriteCompletionCache(root, Boolean(opts.json));

if (opts.json) {

defaultRuntime.writeJson(result);

} else if (result.status === "ok") {

defaultRuntime.log(theme.muted("Update finalization completed."));

}

if (result.status === "error") {

defaultRuntime.exit(1);

}

}

async function persistRequestedUpdateChannel(params: {

configSnapshot: Awaited<ReturnType<typeof readConfigFileSnapshot>>;

requestedChannel: "stable" | "beta" | "dev" | null;