refactor(cli): group agent dashboard diagnostics and shields modules

.coderabbit.yaml

@@ -251,7 +251,7 @@ reviews:
         gh workflow run nightly-e2e.yaml --ref <branch> -f jobs=snapshot-commands-e2e,rebuild-openclaw-e2e
         ```
 
-    - path: "src/lib/shields*.ts"
+    - path: "src/lib/shields/**"
       instructions: |
         These files control shields down/up, config mutability, audit
         trail, and auto-restore timer.

bin/lib/agent-defs.js

@@ -1,7 +1,7 @@
 // SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
 //
-// Thin re-export shim — the implementation lives in src/lib/agent-defs.ts,
-// compiled to dist/lib/agent-defs.js.
+// Thin re-export shim — the implementation lives in src/lib/agent/defs.ts,
+// compiled to dist/lib/agent/defs.js.
 
-module.exports = require("../../dist/lib/agent-defs");
+module.exports = require("../../dist/lib/agent/defs");

bin/lib/agent-onboard.js

@@ -1,7 +1,7 @@
 // SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
 //
-// Thin re-export shim — the implementation lives in src/lib/agent-onboard.ts,
-// compiled to dist/lib/agent-onboard.js.
+// Thin re-export shim — the implementation lives in src/lib/agent/onboard.ts,
+// compiled to dist/lib/agent/onboard.js.
 
-module.exports = require("../../dist/lib/agent-onboard");
+module.exports = require("../../dist/lib/agent/onboard");

bin/lib/agent-runtime.js

@@ -1,7 +1,7 @@
 // SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
 //
-// Thin re-export shim — the implementation lives in src/lib/agent-runtime.ts,
-// compiled to dist/lib/agent-runtime.js.
+// Thin re-export shim — the implementation lives in src/lib/agent/runtime.ts,
+// compiled to dist/lib/agent/runtime.js.
 
-module.exports = require("../../dist/lib/agent-runtime");
+module.exports = require("../../dist/lib/agent/runtime");

scripts/check-legacy-migrated-paths.ts

@@ -26,7 +26,7 @@ const RUNTIME_MOVES: Record<string, string> = moveMap.runtimeMoves;
 const REMOVED_SHIM_MOVES: Record<string, string> = {
   "bin/lib/chat-filter.js": "src/lib/chat-filter.ts",
   "bin/lib/config-io.js": "src/lib/state/config-io.ts",
-  "bin/lib/debug.js": "src/lib/debug.ts",
+  "bin/lib/debug.js": "src/lib/diagnostics/debug.ts",
   "bin/lib/inference-config.js": "src/lib/inference-config.ts",
   "bin/lib/local-inference.js": "src/lib/local-inference.ts",
   "bin/lib/nim.js": "src/lib/nim.ts",

scripts/ts-migration-assist.ts

@@ -48,9 +48,9 @@ const SPECIAL_REWRITES: Record<string, Array<[string, string]>> = {
     ['require("./lib/runtime-recovery")', 'require("../bin/lib/runtime-recovery")'],
     ['require("./lib/usage-notice")', 'require("../bin/lib/usage-notice")'],
     ['require("./lib/services")', 'require("../bin/lib/services")'],
-    ['require("./lib/debug")', 'require("../bin/lib/debug")'],
-    ['require("./lib/debug-command")', 'require("./lib/debug-command")'],
-    ['require("../dist/lib/debug-command")', 'require("./lib/debug-command")'],
+    ['require("./lib/debug")', 'require("./lib/diagnostics/debug")'],
+    ['require("./lib/debug-command")', 'require("./lib/diagnostics/debug-command")'],
+    ['require("../dist/lib/debug-command")', 'require("./lib/diagnostics/debug-command")'],
     ['require("../dist/lib/openshell")', 'require("./lib/openshell")'],
     ['require("../dist/lib/inventory-commands")', 'require("./lib/inventory-commands")'],
     ['require("../dist/lib/deploy")', 'require("./lib/deploy")'],

src/lib/actions/onboard.ts

@@ -1,7 +1,7 @@
 // SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-import { listAgents } from "../agent-defs";
+import { listAgents } from "../agent/defs";
 import { runDeprecatedOnboardAliasCommand, runOnboardCommand } from "../onboard-command";
 import { NOTICE_ACCEPT_ENV, NOTICE_ACCEPT_FLAG } from "../usage-notice";
 

src/lib/actions/sandbox/rebuild.ts

@@ -18,8 +18,8 @@ const { LOCAL_INFERENCE_PROVIDERS, REMOTE_PROVIDER_CONFIG } = require("../../onb
   REMOTE_PROVIDER_CONFIG: Record<string, { providerName: string; credentialEnv: string | null }>;
 };
 
-import { loadAgent } from "../../agent-defs";
-import { ensureAgentBaseImage } from "../../agent-onboard";
+import { loadAgent } from "../../agent/defs";
+import { ensureAgentBaseImage } from "../../agent/onboard";
 import { getSandboxDeleteOutcome } from "../../domain/sandbox/destroy";
 import * as nim from "../../nim";
 import type { Session } from "../../onboard-session";

src/lib/agent-base-image.test.ts → src/lib/agent/base-image.test.ts

@@ -2,11 +2,11 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import { beforeEach, describe, expect, it, vi } from "vitest";
-import type { AgentDefinition } from "./agent-defs";
+import type { AgentDefinition } from "./defs";
 
-type AgentOnboardModule = typeof import("../../dist/lib/agent-onboard");
-type DockerImageModule = typeof import("../../dist/lib/adapters/docker/image");
-type DockerInspectModule = typeof import("../../dist/lib/adapters/docker/inspect");
+type AgentOnboardModule = typeof import("../../../dist/lib/agent/onboard");
+type DockerImageModule = typeof import("../../../dist/lib/adapters/docker/image");
+type DockerInspectModule = typeof import("../../../dist/lib/adapters/docker/inspect");
 
 /**
  * Build a minimal Hermes agent manifest for base-image provisioning tests.
@@ -56,14 +56,14 @@ function withMockedDocker<T>(
   }) => T,
 ): T {
   // eslint-disable-next-line @typescript-eslint/no-require-imports
-  const dockerImageModule = require("../../dist/lib/adapters/docker/image") as DockerImageModule;
+  const dockerImageModule = require("../../../dist/lib/adapters/docker/image") as DockerImageModule;
   // eslint-disable-next-line @typescript-eslint/no-require-imports
-  const dockerInspectModule = require("../../dist/lib/adapters/docker/inspect") as DockerInspectModule;
+  const dockerInspectModule = require("../../../dist/lib/adapters/docker/inspect") as DockerInspectModule;
   // eslint-disable-next-line @typescript-eslint/no-require-imports
-  const runnerModule = require("../../dist/lib/runner") as { ROOT: string };
+  const runnerModule = require("../../../dist/lib/runner") as { ROOT: string };
   const originalDockerBuild = dockerImageModule.dockerBuild;
   const originalDockerImageInspect = dockerInspectModule.dockerImageInspect;
-  const agentOnboardModulePath = require.resolve("../../dist/lib/agent-onboard");
+  const agentOnboardModulePath = require.resolve("../../../dist/lib/agent/onboard");
   delete require.cache[agentOnboardModulePath];
 
   const dockerBuildMock = vi.fn().mockReturnValue({ status: 0 });
@@ -74,7 +74,7 @@ function withMockedDocker<T>(
 
   try {
     // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const agentOnboardModule = require("../../dist/lib/agent-onboard") as AgentOnboardModule;
+    const agentOnboardModule = require("../../../dist/lib/agent/onboard") as AgentOnboardModule;
     return run({
       ensureAgentBaseImage: agentOnboardModule.ensureAgentBaseImage,
       dockerBuildMock,

src/lib/agent-defs.test.ts → src/lib/agent/defs.test.ts

@@ -11,7 +11,7 @@ import {
   getAgentChoices,
   loadAgent,
   resolveAgentName,
-} from "../../dist/lib/agent-defs";
+} from "../../../dist/lib/agent/defs";
 
 const tempAgentDirs: string[] = [];
 

src/lib/agent-defs.ts → src/lib/agent/defs.ts

@@ -7,8 +7,8 @@
 import fs from "node:fs";
 import path from "node:path";
 
-import { ROOT } from "./runner";
-import { DASHBOARD_PORT } from "./ports";
+import { ROOT } from "../runner";
+import { DASHBOARD_PORT } from "../ports";
 
 export const AGENTS_DIR = path.join(ROOT, "agents");
 

src/lib/agent-onboard.test.ts → src/lib/agent/onboard.test.ts

@@ -5,8 +5,8 @@ import { describe, it, expect, beforeEach, afterEach, afterAll, vi } from "vites
 import fs from "node:fs";
 import path from "node:path";
 // Import from compiled dist/ so coverage is attributed correctly.
-import { printDashboardUi, verifyAgentBinaryAvailable } from "../../dist/lib/agent-onboard";
-import type { AgentDefinition } from "./agent-defs";
+import { printDashboardUi, verifyAgentBinaryAvailable } from "../../../dist/lib/agent/onboard";
+import type { AgentDefinition } from "./defs";
 
 function makeAgent(overrides: Partial<AgentDefinition> = {}): AgentDefinition {
   return {
@@ -128,7 +128,7 @@ describe("printDashboardUi — regression for #2078 (port 8642 is not a chat UI)
 
 describe("handleAgentSetup guards", () => {
   it("fails onboarding instead of completing when the agent binary or health probe is missing", () => {
-    const source = fs.readFileSync(path.join(import.meta.dirname, "agent-onboard.ts"), "utf-8");
+    const source = fs.readFileSync(path.join(import.meta.dirname, "onboard.ts"), "utf-8");
 
     expect(source).toContain("verifyAgentBinaryAvailable");
     expect(source).toContain("AGENT_BINARY_CHECK_PREFIX");
@@ -146,7 +146,7 @@ describe("handleAgentSetup guards", () => {
   });
 
   it("accepts Hermes JSON health responses without substring false positives", () => {
-    const source = fs.readFileSync(path.join(import.meta.dirname, "agent-onboard.ts"), "utf-8");
+    const source = fs.readFileSync(path.join(import.meta.dirname, "onboard.ts"), "utf-8");
 
     expect(source).toContain("function isHealthProbeOk");
     expect(source).toContain("JSON.parse(body)");

src/lib/agent-onboard.ts → src/lib/agent/onboard.ts

@@ -9,14 +9,14 @@ import fs from "fs";
 import os from "os";
 import path from "path";
 
-import { dockerBuild, dockerImageInspect } from "./adapters/docker";
-import { type AgentDefinition, loadAgent, resolveAgentName } from "./agent-defs";
-import { getAgentBranding } from "./branding";
-import { getProviderSelectionConfig } from "./inference-config";
-import type { JsonObject as LooseObject, JsonValue as LooseValue } from "./json-types";
-import * as onboardSession from "./onboard-session";
-import { ROOT, redact, run, shellQuote } from "./runner";
-import { sleepSeconds } from "./wait";
+import { dockerBuild, dockerImageInspect } from "../adapters/docker";
+import { getAgentBranding } from "../branding";
+import { getProviderSelectionConfig } from "../inference-config";
+import type { JsonObject as LooseObject, JsonValue as LooseValue } from "../json-types";
+import * as onboardSession from "../onboard-session";
+import { ROOT, redact, run, shellQuote } from "../runner";
+import { sleepSeconds } from "../wait";
+import { type AgentDefinition, loadAgent, resolveAgentName } from "./defs";
 
 export interface OnboardContext {
   step: (current: number, total: number, message: string) => void;

src/lib/agent-runtime.test.ts → src/lib/agent/runtime.test.ts

@@ -7,8 +7,8 @@ import {
   buildManualRecoveryCommand,
   buildOpenClawRecoveryScript,
   buildRecoveryScript,
-} from "../../dist/lib/agent-runtime";
-import type { AgentDefinition } from "./agent-defs";
+} from "../../../dist/lib/agent/runtime";
+import type { AgentDefinition } from "./defs";
 
 function makeAgent(overrides: Partial<AgentDefinition> = {}): AgentDefinition {
   return {

src/lib/agent-runtime.ts → src/lib/agent/runtime.ts

@@ -7,11 +7,11 @@
 // When the session agent is openclaw (or absent), all functions return
 // defaults that match the hardcoded OpenClaw values on main.
 
-import * as registry from "./state/registry";
-import { DASHBOARD_PORT } from "./ports";
-import * as onboardSession from "./onboard-session";
-import { loadAgent, type AgentDefinition } from "./agent-defs";
-import { shellQuote } from "./runner";
+import { DASHBOARD_PORT } from "../ports";
+import { shellQuote } from "../runner";
+import * as onboardSession from "../onboard-session";
+import * as registry from "../state/registry";
+import { loadAgent, type AgentDefinition } from "./defs";
 
 /**
  * Resolve the agent for a sandbox. Checks the per-sandbox registry first

src/lib/commands/debug.ts

@@ -4,10 +4,10 @@
 import { Command, Flags } from "@oclif/core";
 
 import { CLI_NAME } from "../branding";
-import { runDebug } from "../debug";
-import type { DebugOptions } from "../debug";
-import type { RunDebugCommandDeps } from "../debug-command";
-import { runDebugCommandWithOptions } from "../debug-command";
+import { runDebug } from "../diagnostics/debug";
+import type { DebugOptions } from "../diagnostics/debug";
+import type { RunDebugCommandDeps } from "../diagnostics/debug-command";
+import { runDebugCommandWithOptions } from "../diagnostics/debug-command";
 import type { CaptureOpenshellResult } from "../adapters/openshell/client";
 import { captureOpenshellCommand } from "../adapters/openshell/client";
 import { OPENSHELL_PROBE_TIMEOUT_MS } from "../adapters/openshell/timeouts";

src/lib/commands/simple-global-oclif-adapters.test.ts

@@ -24,8 +24,8 @@ const mocks = vi.hoisted(() => ({
 }));
 
 vi.mock("node:child_process", () => ({ spawnSync: mocks.spawnSync }));
-vi.mock("../debug", () => ({ runDebug: vi.fn() }));
-vi.mock("../debug-command", () => ({
+vi.mock("../diagnostics/debug", () => ({ runDebug: vi.fn() }));
+vi.mock("../diagnostics/debug-command", () => ({
   runDebugCommandWithOptions: mocks.runDebugCommandWithOptions,
 }));
 vi.mock("../gateway-token-command", () => ({

src/lib/dashboard-contract.test.ts → src/lib/dashboard/contract.test.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import { describe, it, expect } from "vitest";
-import { buildChain, buildControlUiUrls } from "../../dist/lib/dashboard-contract.js";
+import { buildChain, buildControlUiUrls } from "../../../dist/lib/dashboard/contract.js";
 
 describe("buildChain", () => {
   it("returns default loopback chain with no arguments", () => {

src/lib/dashboard-contract.ts → src/lib/dashboard/contract.ts

@@ -6,8 +6,8 @@
  * Pure functions — no I/O, no process.env reads.
  */
 
-import { DASHBOARD_PORT } from "./ports";
-import { isLoopbackHostname } from "./url-utils";
+import { DASHBOARD_PORT } from "../ports";
+import { isLoopbackHostname } from "../url-utils";
 
 export interface PlatformHints {
   chatUiUrl?: string;

src/lib/dashboard-health.test.ts → src/lib/dashboard/health.test.ts

@@ -2,8 +2,8 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import { describe, it, expect } from "vitest";
-import { verifyDashboardChain } from "../../dist/lib/dashboard-health.js";
-import { buildChain } from "../../dist/lib/dashboard-contract.js";
+import { verifyDashboardChain } from "../../../dist/lib/dashboard/health.js";
+import { buildChain } from "../../../dist/lib/dashboard/contract.js";
 
 const chain = buildChain();
 

src/lib/dashboard-health.ts → src/lib/dashboard/health.ts

@@ -6,7 +6,7 @@
  * chain and produces a per-link diagnosis. All deps injected.
  */
 
-import type { DashboardDeliveryChain } from "./dashboard-contract";
+import type { DashboardDeliveryChain } from "./contract";
 
 export interface DashboardHealthDeps {
   executeSandboxCommand: (name: string, script: string) => { status: number; stdout: string } | null;

src/lib/dashboard-recover.test.ts → src/lib/dashboard/recover.test.ts

@@ -2,8 +2,8 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import { describe, it, expect, vi } from "vitest";
-import { recoverDashboardChain } from "../../dist/lib/dashboard-recover.js";
-import { buildChain } from "../../dist/lib/dashboard-contract.js";
+import { recoverDashboardChain } from "../../../dist/lib/dashboard/recover.js";
+import { buildChain } from "../../../dist/lib/dashboard/contract.js";
 
 const chain = buildChain();
 

src/lib/dashboard-recover.ts → src/lib/dashboard/recover.ts

@@ -5,9 +5,9 @@
  * Dashboard chain recovery — link-aware, idempotent. All deps injected.
  */
 
-import type { DashboardDeliveryChain } from "./dashboard-contract";
-import type { DashboardHealthDeps, ChainStatus } from "./dashboard-health";
-import { verifyDashboardChain } from "./dashboard-health";
+import type { DashboardDeliveryChain } from "./contract";
+import type { DashboardHealthDeps, ChainStatus } from "./health";
+import { verifyDashboardChain } from "./health";
 
 export interface DashboardRecoverDeps extends DashboardHealthDeps {
   restartGateway: (name: string, port: number, agent: unknown) => boolean;

src/lib/debug-command.test.ts → src/lib/diagnostics/debug-command.test.ts

@@ -9,7 +9,7 @@ import {
   printDebugHelp,
   runDebugCommand,
   runDebugCommandWithOptions,
-} from "../../dist/lib/debug-command";
+} from "../../../dist/lib/diagnostics/debug-command";
 
 function exitWithCode(code: number): never {
   throw new Error(`exit:${code}`);

src/lib/debug.test.ts → src/lib/diagnostics/debug.test.ts

@@ -6,7 +6,7 @@ import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 // Import from compiled dist/ so coverage is attributed correctly.
-import { createTarball, getDebugCompletionMessages, redact } from "../../dist/lib/debug";
+import { createTarball, getDebugCompletionMessages, redact } from "../../../dist/lib/diagnostics/debug";
 
 describe("redact", () => {
   it("redacts NVIDIA_API_KEY=value patterns", () => {

src/lib/debug.ts → src/lib/diagnostics/debug.ts

@@ -3,12 +3,12 @@
 
 import { execFileSync, spawnSync } from "node:child_process";
 import { existsSync, mkdtempSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
-import { dockerExecFileSync } from "./adapters/docker/exec";
 import { platform, tmpdir } from "node:os";
 import { basename, dirname, join } from "node:path";
 
-import { DASHBOARD_PORT } from "./ports";
-import { listSandboxes } from "./state/registry";
+import { dockerExecFileSync } from "../adapters/docker/exec";
+import { DASHBOARD_PORT } from "../ports";
+import { listSandboxes } from "../state/registry";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -54,7 +54,7 @@ function section(title: string): void {
 // Secret redaction — delegates to unified redact module (#2381).
 // ---------------------------------------------------------------------------
 
-import { redactFull as redact } from "./redact";
+import { redactFull as redact } from "../redact";
 export { redact };
 
 // ---------------------------------------------------------------------------
@@ -485,8 +485,8 @@ export function getDebugCompletionMessages(output?: string): string[] {
 export function runDebug(opts: DebugOptions = {}): void {
   const quick = opts.quick ?? false;
   const output = opts.output ?? "";
-  // Compiled location: dist/lib/debug.js → repo root is 2 levels up
-  const repoDir = join(__dirname, "..", "..");
+  // Compiled location: dist/lib/diagnostics/debug.js → repo root is 3 levels up
+  const repoDir = join(__dirname, "..", "..", "..");
 
   // Resolve sandbox name
   let sandboxName =