refactor(cli): group remaining architecture modules

.coderabbit.yaml

@@ -243,7 +243,7 @@ reviews:
     - path: "src/lib/onboard/preflight.ts"
       instructions: *e2e-overlayfs
 
-    - path: "src/lib/deploy.ts"
+    - path: "src/lib/deploy/**"
       instructions: |
         This file contains deployment lifecycle logic (start/stop,
         cloudflared tunnel, uninstall).

bin/lib/tiers.js

@@ -1,10 +1,10 @@
 // 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/tiers.ts,
-// compiled to dist/lib/tiers.js.
+// Thin re-export shim — the implementation lives in src/lib/policy/tiers.ts,
+// compiled to dist/lib/policy/tiers.js.
 
-const mod = require("../../dist/lib/tiers");
+const mod = require("../../dist/lib/policy/tiers");
 module.exports = {
   TIERS_FILE: mod.TIERS_FILE,
   listTiers: mod.listTiers,

nemoclaw-blueprint/private-networks.yaml

@@ -2,7 +2,7 @@
 # SPDX-License-Identifier: Apache-2.0
 #
 # IPv4 and IPv6 networks that SSRF validation must reject. Consumed by:
-#   - src/lib/sandbox-config.ts            (CLI `config set` literal-IP gate)
+#   - src/lib/sandbox/config.ts            (CLI `config set` literal-IP gate)
 #   - nemoclaw/src/blueprint/ssrf.ts       (plugin endpoint URL validator)
 # Both consumers build a node:net BlockList from this data at module load.
 #

scripts/benchmark-sandbox-image-build.js

@@ -10,7 +10,7 @@ const {
   collectBuildContextStats,
   stageLegacySandboxBuildContext,
   stageOptimizedSandboxBuildContext,
-} = require("../dist/lib/sandbox-build-context");
+} = require("../dist/lib/sandbox/build-context");
 
 function parseArgs(argv) {
   const args = {

scripts/check-legacy-migrated-paths.ts

@@ -36,11 +36,11 @@ const REMOVED_SHIM_MOVES: Record<string, string> = {
   "bin/lib/registry.js": "src/lib/state/registry.ts",
   "bin/lib/resolve-openshell.js": "src/lib/adapters/openshell/resolve.ts",
   "bin/lib/runtime-recovery.js": "src/lib/runtime-recovery.ts",
-  "bin/lib/sandbox-build-context.js": "src/lib/sandbox-build-context.ts",
-  "bin/lib/services.js": "src/lib/services.ts",
+  "bin/lib/sandbox-build-context.js": "src/lib/sandbox/build-context.ts",
+  "bin/lib/services.js": "src/lib/tunnel/services.ts",
   "bin/lib/version.js": "src/lib/core/version.ts",
   "bin/lib/onboard.js": "src/lib/onboard.ts",
-  "bin/lib/policies.js": "src/lib/policies.ts",
+  "bin/lib/policies.js": "src/lib/policy/index.ts",
   "bin/lib/runner.js": "src/lib/runner.ts",
 };
 

scripts/dev-tier-selector.js

@@ -55,7 +55,7 @@ const onboard = /** @type {{
  *   selectTierPresetsAndAccess: (tierName: string, allPresets: unknown[]) => Promise<unknown>;
  * }} */ (require("../dist/lib/onboard.js"));
 const { selectPolicyTier, selectTierPresetsAndAccess } = onboard;
-const policies = require("../dist/lib/policies.js");
+const policies = require("../dist/lib/policy/index.js");
 
 (async () => {
   const tier = await selectPolicyTier();

scripts/ts-migration-assist.ts

@@ -41,20 +41,20 @@ const SPECIAL_REWRITES: Record<string, Array<[string, string]>> = {
     ['require("./lib/credentials")', 'require("../bin/lib/credentials")'],
     ['require("./lib/registry")', 'require("../bin/lib/registry")'],
     ['require("./lib/nim")', 'require("../bin/lib/nim")'],
-    ['require("./lib/policies")', 'require("../bin/lib/policies")'],
+    ['require("./lib/policy")', 'require("../bin/lib/policies")'],
     ['require("./lib/inference/config")', 'require("../bin/lib/inference-config")'],
     ['require("./lib/version")', 'require("../bin/lib/version")'],
     ['require("./lib/state/onboard-session")', 'require("../bin/lib/onboard-session")'],
     ['require("./lib/runtime-recovery")', 'require("../bin/lib/runtime-recovery")'],
     ['require("./lib/onboard/usage-notice")', 'require("../bin/lib/usage-notice")'],
-    ['require("./lib/services")', 'require("../bin/lib/services")'],
+    ['require("./lib/tunnel/services")', 'require("../bin/lib/services")'],
     ['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("./lib/inventory")', 'require("./lib/inventory-commands")'],
     ['require("../dist/lib/deploy")', 'require("./lib/deploy")'],
-    ['require("../dist/lib/services-command")', 'require("./lib/services-command")'],
+    ['require("./lib/tunnel/service-command")', 'require("./lib/services-command")'],
     ['require("../dist/lib/uninstall-command")', 'require("./lib/uninstall-command")'],
   ],
 };

scripts/ts-migration/move-map.json

@@ -1,9 +1,9 @@
 {
   "runtimeMoves": {
     "bin/lib/platform.js": "src/lib/platform.ts",
-    "bin/lib/sandbox-build-context.js": "src/lib/sandbox-build-context.ts",
+    "bin/lib/sandbox-build-context.js": "src/lib/sandbox/build-context.ts",
     "bin/lib/runner.js": "src/lib/runner.ts",
-    "bin/lib/policies.js": "src/lib/policies.ts",
+    "bin/lib/policies.js": "src/lib/policy/index.ts",
     "bin/lib/onboard.js": "src/lib/onboard.ts",
     "bin/nemoclaw.js": "src/nemoclaw.ts"
   }

src/commands/README.md

@@ -0,0 +1,21 @@
+<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+
+# `src/commands`
+
+This tree is the oclif discovery surface for the packaged `nemoclaw` CLI.
+Each file is intentionally thin: it exports a command class from `src/lib/commands/**`
+and attaches NemoClaw's public display metadata.
+
+```text
+src/commands/<public command path>.ts
+  -> import command implementation from src/lib/commands/**
+  -> wrap with src/lib/cli/command-display.ts metadata
+```
+
+Keep behavior out of this tree. Product behavior belongs in `src/lib/actions/**`, pure
+planning and classification belongs in `src/lib/domain/**`, and host/runtime boundaries
+belong in `src/lib/adapters/**`.
+
+Hidden `nemoclaw internal ...` entrypoints live under `src/commands/internal/**`; see
+`src/commands/internal/README.md` for their narrower compatibility contract.

src/commands/sandbox/config/set.ts

@@ -1,7 +1,7 @@
 // SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-import Command from "../../../lib/sandbox-config-set-cli-command";
+import Command from "../../../lib/commands/sandbox/config/set";
 import { withCommandDisplay } from "../../../lib/cli/command-display";
 
 export default withCommandDisplay(Command, [

src/lib/README.md

@@ -36,17 +36,18 @@ src/lib/dashboard/**    dashboard contract, health, and recovery helpers
 src/lib/deploy/**       deploy/build-image support that is not yet action-shaped
 src/lib/diagnostics/**  debug collection and diagnostic report helpers
 src/lib/inference/**    inference config, health probes, local runtime helpers
+src/lib/inventory/**    list/status inventory shaping and presentation models
 src/lib/messaging/**    channel/messaging policy and message filtering helpers
 src/lib/onboard/**      onboarding support modules around the large legacy flow
-src/lib/policy/**       policy preset loading and application support
+src/lib/policy/**       policy preset loading, tier selection, and application support
 src/lib/runtime/**      sandbox/runtime recovery helpers
-src/lib/sandbox/**      sandbox config, build, stream, and version support
+src/lib/sandbox/**      sandbox config, build, stream, channel, and version support
 src/lib/security/**     redaction, secret patterns, and credential filtering
 src/lib/shields/**      shields orchestration, timers, and audit helpers
 src/lib/tunnel/**       local service/tunnel command support
 ```
 
-Prefer small mechanical PRs that move one cluster at a time. High-import legacy files such as `onboard.ts`, `runner.ts`, `policies.ts`, `nim.ts`, and `services.ts` should either move late or keep temporary compatibility re-export files at their old paths.
+Prefer small mechanical PRs that move one cluster at a time. High-import legacy files such as `onboard.ts`, `runner.ts`, and any remaining large top-level modules should either move late or keep temporary compatibility re-export files at their old paths.
 
 ## Suggested migration sequence
 

src/lib/actions/inference-set.test.ts

@@ -4,7 +4,7 @@
 import { describe, expect, it, vi } from "vitest";
 
 import type { ConfigObject } from "../security/credential-filter";
-import type { AgentConfigTarget } from "../sandbox-config";
+import type { AgentConfigTarget } from "../sandbox/config";
 import type { Session } from "../state/onboard-session";
 import type { SandboxEntry } from "../state/registry";
 
@@ -16,7 +16,7 @@ vi.mock("../inference/local", () => ({
   DEFAULT_OLLAMA_MODEL: "llama3.1",
 }));
 
-vi.mock("../sandbox-config", () => ({
+vi.mock("../sandbox/config", () => ({
   readSandboxConfig: vi.fn(),
   recomputeSandboxConfigHash: vi.fn(),
   resolveAgentConfig: vi.fn(),

src/lib/actions/inference-set.ts

@@ -17,7 +17,7 @@ import {
   resolveAgentConfig,
   type AgentConfigTarget,
   writeSandboxConfig,
-} from "../sandbox-config";
+} from "../sandbox/config";
 import { appendAuditEntry } from "../shields/audit";
 import * as onboardSession from "../state/onboard-session";
 import * as registry from "../state/registry";

src/lib/actions/sandbox/connect.ts

@@ -27,7 +27,7 @@ import {
   getActiveSandboxSessions,
 } from "../../state/sandbox-session";
 import { checkAndRecoverSandboxProcesses } from "./process-recovery";
-import * as sandboxVersion from "../../sandbox-version";
+import * as sandboxVersion from "../../sandbox/version";
 import { D, G, R, YW } from "../../cli/terminal-style";
 import { resolveOpenshell } from "../../adapters/openshell/resolve";
 

src/lib/actions/sandbox/destroy.ts

@@ -196,7 +196,7 @@ export function cleanupSandboxServices(
   const stopAll =
     deps.stopAll ??
     ((opts: { sandboxName: string }) => {
-      const services = require("../../services") as {
+      const services = require("../../tunnel/services") as {
         stopAll: (opts: { sandboxName: string }) => void;
       };
       services.stopAll(opts);
@@ -221,7 +221,7 @@ export function cleanupSandboxServices(
 
   if (stopHostServices) {
     // `stopAll()` already runs `unloadOllamaModels()` unconditionally —
-    // see src/lib/services.ts. Don't double-call here.
+    // see src/lib/tunnel/services.ts. Don't double-call here.
     stopAll({ sandboxName });
   } else {
     // No global stop, so `stopAll()` did not run; explicitly free Ollama

src/lib/actions/sandbox/doctor.ts

@@ -20,7 +20,7 @@ import type { SandboxEntry } from "../../state/registry";
 import { resolveOpenshell } from "../../adapters/openshell/resolve";
 import { ROOT } from "../../runner";
 import { parseLiveSandboxNames } from "../../runtime-recovery";
-import * as sandboxVersion from "../../sandbox-version";
+import * as sandboxVersion from "../../sandbox/version";
 import * as shields from "../../shields";
 import { buildStatusCommandDeps } from "../../status-command-deps";
 import { B, D, G, R, RD, YW } from "../../cli/terminal-style";

src/lib/actions/sandbox/policy-channel.ts

@@ -11,19 +11,19 @@ import { getCredential, prompt as askPrompt } from "../../credentials/store";
 import { recoverNamedGatewayRuntime } from "../../gateway-runtime-action";
 const { isNonInteractive } = require("../../onboard") as { isNonInteractive: () => boolean };
 const onboardProviders = require("../../onboard/providers");
-import * as policies from "../../policies";
+import * as policies from "../../policy";
 import { parsePolicyAddArgs } from "../../domain/policy-channel";
 import * as registry from "../../state/registry";
 import { runOpenshell } from "../../adapters/openshell/runtime";
-import { rebuildSandbox } from "./runtime";
+import { rebuildSandbox } from "./rebuild";
 import {
   KNOWN_CHANNELS,
   clearChannelTokens,
   getChannelDef,
   getChannelTokenKeys,
   knownChannelNames,
   persistChannelTokens,
-} from "../../sandbox-channels";
+} from "../../sandbox/channels";
 
 const useColor = !process.env.NO_COLOR && !!process.stdout.isTTY;
 const trueColor =

src/lib/actions/sandbox/rebuild.ts

@@ -35,7 +35,7 @@ import * as nim from "../../inference/nim";
 import type { Session } from "../../state/onboard-session";
 import * as onboardSession from "../../state/onboard-session";
 import { captureOpenshell, runOpenshell } from "../../adapters/openshell/runtime";
-import * as policies from "../../policies";
+import * as policies from "../../policy";
 import * as registry from "../../state/registry";
 import { resolveOpenshell } from "../../adapters/openshell/resolve";
 import { parseLiveSandboxNames } from "../../runtime-recovery";
@@ -46,7 +46,7 @@ import {
   getActiveSandboxSessions,
 } from "../../state/sandbox-session";
 import * as sandboxState from "../../state/sandbox";
-import * as sandboxVersion from "../../sandbox-version";
+import * as sandboxVersion from "../../sandbox/version";
 import { B, D, G, R, RD as _RD, YW } from "../../cli/terminal-style";
 
 const agentRuntime = require("../../../../bin/lib/agent-runtime");

src/lib/actions/sandbox/snapshot.ts

@@ -11,7 +11,7 @@ import { stripAnsi } from "../../adapters/openshell/client";
 import { parseLiveSandboxNames } from "../../runtime-recovery";
 import { ROOT, run, shellQuote, validateName } from "../../runner";
 import { captureOpenshell, getOpenshellBinary } from "../../adapters/openshell/runtime";
-import * as policies from "../../policies";
+import * as policies from "../../policy";
 import * as registry from "../../state/registry";
 import type { SandboxEntry } from "../../state/registry";
 import * as sandboxState from "../../state/sandbox";
@@ -125,7 +125,7 @@ async function autoCreateSandboxFromSource(
   dstName: string,
   srcEntry: SandboxEntry | { name: string },
 ): Promise<void> {
-  const sandboxCreateStream = require("../../sandbox-create-stream");
+  const sandboxCreateStream = require("../../sandbox/create-stream");
   const { isSandboxReady } = require("../../state/gateway");
   const basePolicy = path.join(ROOT, "nemoclaw-blueprint", "policies", "openclaw-sandbox.yaml");
   const openshellBin = getOpenshellBinary();

src/lib/actions/sandbox/status.ts

@@ -32,7 +32,7 @@ import {
   createSystemDeps as createSessionDeps,
   getActiveSandboxSessions,
 } from "../../state/sandbox-session";
-import * as sandboxVersion from "../../sandbox-version";
+import * as sandboxVersion from "../../sandbox/version";
 import * as shields from "../../shields";
 import { D, G, R, RD, YW } from "../../cli/terminal-style";
 

src/lib/actions/upgrade-sandboxes.ts

@@ -12,7 +12,7 @@ import { captureOpenshell } from "../adapters/openshell/runtime";
 import * as registry from "../state/registry";
 import { parseLiveSandboxNames } from "../runtime-recovery";
 import { rebuildSandbox } from "./sandbox/rebuild";
-import * as sandboxVersion from "../sandbox-version";
+import * as sandboxVersion from "../sandbox/version";
 import { B, D, G, R, YW } from "../cli/terminal-style";
 import {
   classifyUpgradeableSandboxes,

src/lib/adapters/http/README.md

@@ -0,0 +1,8 @@
+<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+
+# HTTP adapters
+
+HTTP adapter modules isolate host-side network probes and subprocess-backed HTTP
+checks from action/domain logic. Keep pure response classification in domain or
+feature modules; keep `curl`, temporary files, and network-boundary behavior here.

src/lib/http-probe.test.ts → src/lib/adapters/http/probe.test.ts

@@ -13,7 +13,7 @@ import {
   summarizeCurlFailure,
   summarizeProbeError,
   summarizeProbeFailure,
-} from "./http-probe";
+} from "./probe";
 
 describe("http-probe helpers", () => {
   it("returns explicit curl timeouts", () => {