CLI: fix lazy maintenance command registration (#16374)

Merged via /review-pr -> /prepare-pr -> /merge-pr.

Prepared head SHA: 29d7cca6742bc33793fe8a38df456214fef0da3d
Co-authored-by: gumadeiras <5599352+gumadeiras@users.noreply.github.com>
Co-authored-by: gumadeiras <5599352+gumadeiras@users.noreply.github.com>
Reviewed-by: @gumadeiras

CHANGELOG.md

@@ -14,6 +14,7 @@ Docs: https://docs.openclaw.ai
 ### Fixes
 
 - Security/Node Host: enforce `system.run` rawCommand/argv consistency to prevent allowlist/approval bypass. Thanks @christos-eth.
+- CLI: fix lazy core command registration so top-level maintenance commands (`doctor`, `dashboard`, `reset`, `uninstall`) resolve correctly instead of exposing a non-functional `maintenance` placeholder command.
 - Security/Agents: scope CLI process cleanup to owned child PIDs to avoid killing unrelated processes on shared hosts. Thanks @aether-ai-agent.
 - Security/Agents (macOS): prevent shell injection when writing Claude CLI keychain credentials. (#15924) Thanks @aether-ai-agent.
 - Security: fix Chutes manual OAuth login state validation (thanks @aether-ai-agent). (#16058)

src/cli/program/command-registry.test.ts

@@ -1,10 +1,16 @@
 import { Command } from "commander";
 import { describe, expect, it } from "vitest";
 import type { ProgramContext } from "./context.js";
-import { getCoreCliCommandNames, registerCoreCliByName } from "./command-registry.js";
+import {
+  getCoreCliCommandNames,
+  registerCoreCliByName,
+  registerCoreCliCommands,
+} from "./command-registry.js";
 
-const stubCtx: ProgramContext = {
+const testProgramContext: ProgramContext = {
   programVersion: "0.0.0-test",
+  channelOptions: [],
+  messageChannelOptions: "",
   agentChannelOptions: "web",
 };
 
@@ -17,18 +23,38 @@ describe("command-registry", () => {
 
   it("registerCoreCliByName resolves agents to the agent entry", async () => {
     const program = new Command();
-    const found = await registerCoreCliByName(program, stubCtx, "agents");
+    const found = await registerCoreCliByName(program, testProgramContext, "agents");
     expect(found).toBe(true);
     const agentsCmd = program.commands.find((c) => c.name() === "agents");
     expect(agentsCmd).toBeDefined();
-    // The registrar also installs the singular "agent" command from the same entry
+    // The registrar also installs the singular "agent" command from the same entry.
     const agentCmd = program.commands.find((c) => c.name() === "agent");
     expect(agentCmd).toBeDefined();
   });
 
   it("registerCoreCliByName returns false for unknown commands", async () => {
     const program = new Command();
-    const found = await registerCoreCliByName(program, stubCtx, "nonexistent");
+    const found = await registerCoreCliByName(program, testProgramContext, "nonexistent");
     expect(found).toBe(false);
   });
+
+  it("registers doctor placeholder for doctor primary command", () => {
+    const program = new Command();
+    registerCoreCliCommands(program, testProgramContext, ["node", "openclaw", "doctor"]);
+
+    expect(program.commands.map((command) => command.name())).toEqual(["doctor"]);
+  });
+
+  it("treats maintenance commands as top-level builtins", async () => {
+    const program = new Command();
+
+    expect(await registerCoreCliByName(program, testProgramContext, "doctor")).toBe(true);
+
+    const names = getCoreCliCommandNames();
+    expect(names).toContain("doctor");
+    expect(names).toContain("dashboard");
+    expect(names).toContain("reset");
+    expect(names).toContain("uninstall");
+    expect(names).not.toContain("maintenance");
+  });
 });

src/cli/program/command-registry.ts

@@ -57,7 +57,15 @@ const coreEntries: CoreCliEntry[] = [
     },
   },
   {
-    commands: [{ name: "maintenance", description: "Maintenance commands" }],
+    commands: [
+      { name: "doctor", description: "Health checks + quick fixes for the gateway and channels" },
+      { name: "dashboard", description: "Open the Control UI with your current token" },
+      { name: "reset", description: "Reset local config/state (keeps the CLI installed)" },
+      {
+        name: "uninstall",
+        description: "Uninstall the gateway service + local data (CLI remains)",
+      },
+    ],
     register: async ({ program }) => {
       const mod = await import("./register.maintenance.js");
       mod.registerMaintenanceCommands(program);