refactor(cli): group state modules

.coderabbit.yaml

@@ -236,7 +236,7 @@ reviews:
         gh workflow run nightly-e2e.yaml --ref <branch> -f jobs=deployment-services-e2e
         ```
 
-    - path: "src/lib/sandbox-state.ts"
+    - path: "src/lib/state/sandbox.ts"
       instructions: |
         This file manages sandbox state (backup, restore, rebuild,
         snapshot). Changes affect data persistence across sandbox

scripts/check-legacy-migrated-paths.ts

@@ -25,15 +25,15 @@ type GuardedPath = {
 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/config-io.ts",
+  "bin/lib/config-io.js": "src/lib/state/config-io.ts",
   "bin/lib/debug.js": "src/lib/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",
   "bin/lib/onboard-session.js": "src/lib/onboard-session.ts",
   "bin/lib/platform.js": "src/lib/platform.ts",
   "bin/lib/preflight.js": "src/lib/preflight.ts",
-  "bin/lib/registry.js": "src/lib/registry.ts",
+  "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",

scripts/dev-tier-selector.js

@@ -20,7 +20,7 @@ const readline = require("readline");
 // ── Stubs ──────────────────────────────────────────────────────────────────
 const creds = require("../dist/lib/credentials.js");
 const runner = require("../dist/lib/runner.js");
-const registry = require("../dist/lib/registry.js");
+const registry = require("../dist/lib/state/registry.js");
 
 creds.ensureApiKey = async () => {};
 creds.getCredential = () => null;

scripts/ts-migration-assist.ts

@@ -27,7 +27,7 @@ const SPECIAL_REWRITES: Record<string, Array<[string, string]>> = {
     ['require("./platform")', 'require("../../bin/lib/platform")'],
     ['require("./resolve-openshell")', 'require("../../bin/lib/resolve-openshell")'],
     ['require("./credentials")', 'require("../../bin/lib/credentials")'],
-    ['require("./registry")', 'require("../../bin/lib/registry")'],
+    ['require("./state/registry")', 'require("../../bin/lib/registry")'],
     ['require("./nim")', 'require("../../bin/lib/nim")'],
     ['require("./onboard-session")', 'require("../../bin/lib/onboard-session")'],
     ['require("./policies")', 'require("../../bin/lib/policies")'],

src/lib/actions/maintenance.ts

@@ -11,9 +11,9 @@ import {
 import { dockerListImagesFormat, dockerRmi } from "../docker";
 import { findOrphanedSandboxImages, parseSandboxImageRows } from "../domain/maintenance/images";
 import { captureOpenshell } from "../adapters/openshell/runtime";
-import * as registry from "../registry";
+import * as registry from "../state/registry";
 import { parseLiveSandboxNames } from "../runtime-recovery";
-import * as sandboxState from "../sandbox-state";
+import * as sandboxState from "../state/sandbox";
 
 const useColor = !process.env.NO_COLOR && !!process.stdout.isTTY;
 const trueColor =

src/lib/actions/sandbox/connect.ts

@@ -15,13 +15,13 @@ import {
   runOpenshell,
 } from "../../adapters/openshell/runtime";
 import { OPENSHELL_PROBE_TIMEOUT_MS } from "../../adapters/openshell/timeouts";
-import * as registry from "../../registry";
+import * as registry from "../../state/registry";
 import { ROOT } from "../../runner";
 import { ensureLiveSandboxOrExit } from "./gateway-state";
 import {
   createSystemDeps as createSessionDeps,
   getActiveSandboxSessions,
-} from "../../sandbox-session-state";
+} from "../../state/sandbox-session";
 import { checkAndRecoverSandboxProcesses } from "./process-recovery";
 import * as sandboxVersion from "../../sandbox-version";
 import { D, G, R, YW } from "../../terminal-style";

src/lib/actions/sandbox/destroy.ts

@@ -15,13 +15,13 @@ import * as onboardSession from "../../onboard-session";
 import type { Session } from "../../onboard-session";
 import { OPENSHELL_PROBE_TIMEOUT_MS } from "../../adapters/openshell/timeouts";
 import { DASHBOARD_PORT } from "../../ports";
-import * as registry from "../../registry";
+import * as registry from "../../state/registry";
 import { resolveOpenshell } from "../../adapters/openshell/resolve";
 import { parseLiveSandboxNames } from "../../runtime-recovery";
 import {
   createSystemDeps as createSessionDeps,
   getActiveSandboxSessions,
-} from "../../sandbox-session-state";
+} from "../../state/sandbox-session";
 import {
   getSandboxDeleteOutcome,
   shouldCleanupGatewayAfterDestroy,

src/lib/actions/sandbox/doctor.ts

@@ -16,8 +16,8 @@ import { stripAnsi } from "../../adapters/openshell/client";
 import { captureOpenshell } from "../../adapters/openshell/runtime";
 import { OPENSHELL_PROBE_TIMEOUT_MS } from "../../adapters/openshell/timeouts";
 import { GATEWAY_PORT, OLLAMA_PORT } from "../../ports";
-import * as registry from "../../registry";
-import type { SandboxEntry } from "../../registry";
+import * as registry from "../../state/registry";
+import type { SandboxEntry } from "../../state/registry";
 import { resolveOpenshell } from "../../adapters/openshell/resolve";
 import { ROOT } from "../../runner";
 import { parseLiveSandboxNames } from "../../runtime-recovery";

src/lib/actions/sandbox/gateway-state.ts

@@ -8,7 +8,7 @@ import os from "node:os";
 import path from "node:path";
 
 import { CLI_DISPLAY_NAME, CLI_NAME } from "../../branding";
-import { parseSandboxPhase } from "../../gateway-state";
+import { parseSandboxPhase } from "../../state/gateway";
 import {
   getNamedGatewayLifecycleState,
   recoverNamedGatewayRuntime,
@@ -30,7 +30,7 @@ import {
   OPENSHELL_OPERATION_TIMEOUT_MS,
   OPENSHELL_PROBE_TIMEOUT_MS,
 } from "../../adapters/openshell/timeouts";
-import * as registry from "../../registry";
+import * as registry from "../../state/registry";
 
 type SandboxGatewayState = {
   state: string;

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

@@ -14,7 +14,7 @@ const { isNonInteractive } = require("../../onboard") as { isNonInteractive: ()
 const onboardProviders = require("../../onboard-providers");
 import * as policies from "../../policies";
 import { parsePolicyAddArgs } from "../../domain/policy-channel";
-import * as registry from "../../registry";
+import * as registry from "../../state/registry";
 import { runOpenshell } from "../../adapters/openshell/runtime";
 import { rebuildSandbox } from "./runtime";
 import {

src/lib/actions/sandbox/process-recovery.ts

@@ -18,7 +18,7 @@ import {
   runOpenshell,
 } from "../../adapters/openshell/runtime";
 import { OPENSHELL_PROBE_TIMEOUT_MS } from "../../adapters/openshell/timeouts";
-import { parseForwardList } from "../../sandbox-session-state";
+import { parseForwardList } from "../../state/sandbox-session";
 import { G, R } from "../../terminal-style";
 import { sleepSeconds } from "../../wait";
 

src/lib/actions/sandbox/rebuild.ts

@@ -26,16 +26,16 @@ import type { Session } from "../../onboard-session";
 import * as onboardSession from "../../onboard-session";
 import { captureOpenshell, runOpenshell } from "../../adapters/openshell/runtime";
 import * as policies from "../../policies";
-import * as registry from "../../registry";
+import * as registry from "../../state/registry";
 import { resolveOpenshell } from "../../adapters/openshell/resolve";
 import { parseLiveSandboxNames } from "../../runtime-recovery";
 import { removeSandboxRegistryEntry } from "./destroy";
 import { executeSandboxCommand } from "./process-recovery";
 import {
   createSystemDeps as createSessionDeps,
   getActiveSandboxSessions,
-} from "../../sandbox-session-state";
-import * as sandboxState from "../../sandbox-state";
+} from "../../state/sandbox-session";
+import * as sandboxState from "../../state/sandbox";
 import * as sandboxVersion from "../../sandbox-version";
 import { B, D, G, R, RD as _RD, YW } from "../../terminal-style";
 

src/lib/actions/sandbox/snapshot.ts

@@ -12,9 +12,9 @@ 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 registry from "../../registry";
-import type { SandboxEntry } from "../../registry";
-import * as sandboxState from "../../sandbox-state";
+import * as registry from "../../state/registry";
+import type { SandboxEntry } from "../../state/registry";
+import * as sandboxState from "../../state/sandbox";
 
 const { parseRestoreArgs } = sandboxState;
 
@@ -119,7 +119,7 @@ async function autoCreateSandboxFromSource(
   srcEntry: SandboxEntry | { name: string },
 ): Promise<void> {
   const sandboxCreateStream = require("../../sandbox-create-stream");
-  const { isSandboxReady } = require("../../gateway-state");
+  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

@@ -4,7 +4,7 @@
 /* v8 ignore start -- exercised through CLI subprocess status tests. */
 
 import { CLI_DISPLAY_NAME, CLI_NAME } from "../../branding";
-import { parseSandboxPhase } from "../../gateway-state";
+import { parseSandboxPhase } from "../../state/gateway";
 import { getNamedGatewayLifecycleState } from "../../gateway-runtime-action";
 import { parseGatewayInference } from "../../inference-config";
 import { probeProviderHealth } from "../../inference-health";
@@ -15,7 +15,7 @@ import {
   captureOpenshellForStatus,
   isCommandTimeout,
 } from "../../adapters/openshell/runtime";
-import * as registry from "../../registry";
+import * as registry from "../../state/registry";
 import { resolveOpenshell } from "../../adapters/openshell/resolve";
 import {
   getReconciledSandboxGatewayState,
@@ -27,7 +27,7 @@ import { isSandboxGatewayRunningForStatus } from "./process-recovery";
 import {
   createSystemDeps as createSessionDeps,
   getActiveSandboxSessions,
-} from "../../sandbox-session-state";
+} from "../../state/sandbox-session";
 import * as sandboxVersion from "../../sandbox-version";
 import * as shields from "../../shields";
 import { D, G, R, RD, YW } from "../../terminal-style";

src/lib/actions/upgrade-sandboxes.ts

@@ -10,7 +10,7 @@ import {
   type UpgradeSandboxesOptions,
 } from "../domain/lifecycle/options";
 import { captureOpenshell } from "../adapters/openshell/runtime";
-import * as registry from "../registry";
+import * as registry from "../state/registry";
 import { parseLiveSandboxNames } from "../runtime-recovery";
 import { rebuildSandbox } from "./sandbox/rebuild";
 import * as sandboxVersion from "../sandbox-version";

src/lib/agent-runtime.ts

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

src/lib/commands/debug.ts

@@ -11,7 +11,7 @@ import { runDebugCommandWithOptions } from "../debug-command";
 import type { CaptureOpenshellResult } from "../adapters/openshell/client";
 import { captureOpenshellCommand } from "../adapters/openshell/client";
 import { OPENSHELL_PROBE_TIMEOUT_MS } from "../adapters/openshell/timeouts";
-import * as registry from "../registry";
+import * as registry from "../state/registry";
 import { resolveOpenshell } from "../adapters/openshell/resolve";
 import { parseLiveSandboxNames } from "../runtime-recovery";
 

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

@@ -37,7 +37,7 @@ vi.mock("../actions/global", () => ({
   showVersion: mocks.showVersion,
 }));
 vi.mock("../adapters/openshell/client", () => ({ captureOpenshellCommand: mocks.captureOpenshellCommand }));
-vi.mock("../registry", () => ({ listSandboxes: mocks.listSandboxes }));
+vi.mock("../state/registry", () => ({ listSandboxes: mocks.listSandboxes }));
 vi.mock("../adapters/openshell/resolve", () => ({ resolveOpenshell: mocks.resolveOpenshell }));
 vi.mock("../services", () => ({ startAll: mocks.startAll, stopAll: mocks.stopAll }));
 vi.mock("../services-command", () => ({

src/lib/commands/tunnel/common.ts

@@ -1,7 +1,7 @@
 // SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-import * as registry from "../../registry";
+import * as registry from "../../state/registry";
 
 export function serviceDeps() {
   return {

src/lib/credentials.ts

@@ -14,7 +14,7 @@ import os from "node:os";
 import path from "node:path";
 import readline from "node:readline";
 
-import { rejectSymlinksOnPath } from "./config-io";
+import { rejectSymlinksOnPath } from "./state/config-io";
 import { isErrnoException } from "./errno";
 
 const UNSAFE_HOME_PATHS = new Set(["/tmp", "/var/tmp", "/dev/shm", "/"]);

src/lib/debug.ts

@@ -8,7 +8,7 @@ import { platform, tmpdir } from "node:os";
 import { basename, dirname, join } from "node:path";
 
 import { DASHBOARD_PORT } from "./ports";
-import { listSandboxes } from "./registry";
+import { listSandboxes } from "./state/registry";
 
 // ---------------------------------------------------------------------------
 // Types

src/lib/http-probe.ts

@@ -11,7 +11,7 @@ import {
 } from "node:child_process";
 
 import type { ProbeResult } from "./onboard-types";
-import { ROOT } from "./paths";
+import { ROOT } from "./state/paths";
 import { compactText } from "./url-utils";
 
 import { isErrnoException } from "./errno";

src/lib/list-command-deps.ts

@@ -7,7 +7,7 @@ import * as onboardSession from "./onboard-session";
 import type { ListSandboxesCommandDeps } from "./inventory-commands";
 import { parseGatewayInference } from "./inference-config";
 import { OPENSHELL_PROBE_TIMEOUT_MS } from "./adapters/openshell/timeouts";
-import { parseSshProcesses, createSystemDeps } from "./sandbox-session-state";
+import { parseSshProcesses, createSystemDeps } from "./state/sandbox-session";
 import { resolveOpenshell } from "./adapters/openshell/resolve";
 import { captureOpenshell } from "./adapters/openshell/runtime";
 import { recoverRegistryEntries } from "./registry-recovery-action";

src/lib/messaging-conflict.test.ts

@@ -3,7 +3,7 @@
 
 import { describe, expect, it, vi } from "vitest";
 
-import type { SandboxEntry } from "./registry";
+import type { SandboxEntry } from "./state/registry";
 import {
   backfillMessagingChannels,
   findAllOverlaps,

src/lib/messaging-conflict.ts

@@ -13,7 +13,7 @@
 // added have no record — can optionally backfill the channel field by probing
 // the live OpenShell gateway for known provider names.
 
-import type { SandboxEntry } from "./registry";
+import type { SandboxEntry } from "./state/registry";
 import { getChannelDef, getChannelTokenKeys } from "./sandbox-channels";
 
 type ProbeResult = "present" | "absent" | "error";

src/lib/onboard.ts

@@ -272,7 +272,7 @@ const {
   saveCredential,
 } = credentials;
 const { hashCredential }: typeof import("./credential-hash") = require("./credential-hash");
-const registry: typeof import("./registry") = require("./registry");
+const registry: typeof import("./state/registry") = require("./state/registry");
 const nim: typeof import("./nim") = require("./nim");
 const onboardSession: typeof import("./onboard-session") = require("./onboard-session");
 const policies: typeof import("./policies") = require("./policies");
@@ -293,8 +293,8 @@ const {
 const agentOnboard = require("./agent-onboard");
 const agentDefs = require("./agent-defs");
 
-const gatewayState: typeof import("./gateway-state") = require("./gateway-state");
-const sandboxState: typeof import("./sandbox-state") = require("./sandbox-state");
+const gatewayState: typeof import("./state/gateway") = require("./state/gateway");
+const sandboxState: typeof import("./state/sandbox") = require("./state/sandbox");
 const validation: typeof import("./validation") = require("./validation");
 const urlUtils: typeof import("./url-utils") = require("./url-utils");
 const buildContext = require("./build-context");
@@ -310,18 +310,18 @@ import type { AgentDefinition } from "./agent-defs";
 import type { CurlProbeResult } from "./http-probe";
 import type { GatewayInference, ProviderSelectionConfig } from "./inference-config";
 import type { GpuInfo, ValidationResult } from "./local-inference";
+import type { ContainerRuntime } from "./platform";
+import type { SandboxEntry } from "./state/registry";
 import type { Session, SessionUpdates } from "./onboard-session";
 import type {
   ModelCatalogFetchResult,
   ModelValidationResult,
   ProbeResult,
   ValidationFailureLike,
 } from "./onboard-types";
-import type { ContainerRuntime } from "./platform";
-import type { SandboxEntry } from "./registry";
 import { listChannels } from "./sandbox-channels";
 import type { StreamSandboxCreateResult } from "./sandbox-create-stream";
-import type { BackupResult } from "./sandbox-state";
+import type { BackupResult } from "./state/sandbox";
 import type { TierDefinition, TierPreset } from "./tiers";
 import type { SandboxCreateFailure, ValidationClassification } from "./validation";
 import type { ProbeRecovery } from "./validation-recovery";
@@ -505,7 +505,7 @@ async function promptYesNoOrDefault(
 
 // ── Helpers ──────────────────────────────────────────────────────
 
-// Gateway state functions — delegated to src/lib/gateway-state.ts
+// Gateway state functions — delegated to src/lib/state/gateway.ts
 const {
   isSandboxReady,
   parseSandboxStatus,

src/lib/policies.ts

@@ -11,7 +11,7 @@ const os = require("os");
 const readline = require("readline");
 const YAML = require("yaml");
 const { ROOT, run, runCapture } = require("./runner");
-const registry = require("./registry");
+const registry = require("./state/registry");
 const { loadAgent } = require("./agent-defs");
 
 const PRESETS_DIR = path.join(ROOT, "nemoclaw-blueprint", "policies", "presets");

src/lib/registry-recovery-action.test.ts

@@ -3,7 +3,7 @@
 
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
-import type { SandboxEntry } from "./registry.js";
+import type { SandboxEntry } from "./state/registry.js";
 
 interface MockRegistryState {
   sandboxes: Record<string, SandboxEntry>;
@@ -12,7 +12,7 @@ interface MockRegistryState {
 
 const mockRegistryState: MockRegistryState = { sandboxes: {}, defaultSandbox: null };
 
-vi.mock("./registry.js", () => ({
+vi.mock("./state/registry.js", () => ({
   listSandboxes: () => ({
     sandboxes: Object.values(mockRegistryState.sandboxes),
     defaultSandbox: mockRegistryState.defaultSandbox,

src/lib/registry-recovery-action.ts

@@ -6,8 +6,8 @@ import type { RecoveryResult } from "./inventory-commands";
 import * as onboardSession from "./onboard-session";
 import { OPENSHELL_PROBE_TIMEOUT_MS } from "./adapters/openshell/timeouts";
 import { captureOpenshell } from "./adapters/openshell/runtime";
-import * as registry from "./registry";
-import type { SandboxEntry } from "./registry";
+import * as registry from "./state/registry";
+import type { SandboxEntry } from "./state/registry";
 import { resolveOpenshell } from "./adapters/openshell/resolve";
 import { parseLiveSandboxNames } from "./runtime-recovery";
 import { validateName } from "./runner";