refactor(cli): enforce utils leaf-layer dependency direction (#9146)

eslint-rules/no-utils-upward-import.js

@@ -0,0 +1,115 @@
+/**
+ * @license
+ * Copyright 2026 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import path from 'node:path';
+
+/**
+ * `packages/cli/src/utils/` is the leaf layer that every other directory
+ * imports. It must not import back up into a domain directory (`config/`,
+ * `ui/`, `i18n/`, `nonInteractive/`, `commands/`, `serve/`,
+ * `acp-integration/`, ...): that is the dependency-direction invariant
+ * tracked in #9146.
+ *
+ * The only permitted "upward" references are `import type` specifiers. A
+ * type-only import is erased at compile time, so it cannot create a runtime
+ * module cycle. The two remaining instances (`Settings` in
+ * `modelConfigUtils.ts`, `CommandContext` in `sessionPaths.ts`) are this
+ * irreducible type-level coupling.
+ */
+
+const CLI_UTILS_MARKER = 'packages/cli/src/utils/';
+const TEST_OR_FIXTURE_SEGMENTS = new Set(['__tests__', 'fixtures']);
+
+function isCliUtilsProductionFile(filename) {
+  if (!filename || filename === '<input>' || filename === '<text>') {
+    return false;
+  }
+  const normalized = path.normalize(filename).replaceAll('\\', '/');
+  const start = normalized.lastIndexOf(CLI_UTILS_MARKER);
+  if (start < 0) {
+    return false;
+  }
+  const relativePath = normalized.slice(start + CLI_UTILS_MARKER.length);
+  if (/\.(test|spec)\.[cm]?[jt]sx?$/.test(relativePath)) {
+    return false;
+  }
+  return !relativePath.split('/').some((s) => TEST_OR_FIXTURE_SEGMENTS.has(s));
+}
+
+function escapesUtils(filename, importedPath) {
+  const normalized = path.normalize(filename).replaceAll('\\', '/');
+  const utilsRoot = normalized.slice(
+    0,
+    normalized.lastIndexOf(CLI_UTILS_MARKER) + CLI_UTILS_MARKER.length,
+  );
+  const resolved = path.resolve(path.dirname(filename), importedPath);
+  return path
+    .relative(utilsRoot, resolved)
+    .replaceAll('\\', '/')
+    .startsWith('..');
+}
+
+export default {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'packages/cli/src/utils must not import outside utils/ (leaf-layer dependency direction).',
+    },
+    messages: {
+      noUtilsUpwardImport:
+        'packages/cli/src/utils must not import outside utils/. ' +
+        'Invert the dependency (pass the value in) or move the module to the ' +
+        'domain directory that owns it (#9146).',
+    },
+  },
+  create(context) {
+    const { filename } = context;
+    if (!isCliUtilsProductionFile(filename)) {
+      return {};
+    }
+
+    const reportIfEscaping = (sourceNode, importedPath) => {
+      if (
+        typeof importedPath === 'string' &&
+        importedPath.startsWith('.') &&
+        escapesUtils(filename, importedPath)
+      ) {
+        context.report({ node: sourceNode, messageId: 'noUtilsUpwardImport' });
+      }
+    };
+
+    const checkStatic = (node) => {
+      // Type-only imports (`import type`, `export type ... from`) are erased at
+      // compile time and cannot create a runtime cycle.
+      if (node.importKind === 'type' || node.exportKind === 'type') {
+        return;
+      }
+      reportIfEscaping(node.source, node.source?.value);
+    };
+
+    const checkDynamic = (node) => {
+      const { source } = node;
+      if (source.type === 'Literal') {
+        reportIfEscaping(source, source.value);
+      } else if (
+        source.type === 'TemplateLiteral' &&
+        source.quasis.length === 1
+      ) {
+        reportIfEscaping(source, source.quasis[0].value.cooked);
+      }
+    };
+
+    return {
+      ImportDeclaration: checkStatic,
+      ExportNamedDeclaration: checkStatic,
+      ExportAllDeclaration: checkStatic,
+      ImportExpression: checkDynamic,
+      // TSImportType (`import('../config/x').T`) is type-only by definition, so
+      // it is intentionally not reported.
+    };
+  },
+};

eslint.config.js

@@ -16,6 +16,7 @@ import globals from 'globals';
 import storybook from 'eslint-plugin-storybook';
 import checkFile from 'eslint-plugin-check-file';
 import noCoreRootBarrelImport from './eslint-rules/no-core-root-barrel-import.js';
+import noUtilsUpwardImport from './eslint-rules/no-utils-upward-import.js';
 import { legacyFilenames } from './eslint.legacy-filenames.mjs';
 
 // General syntax restrictions applied to every TS/TSX source file. Hoisted so
@@ -109,24 +110,20 @@ export default tseslint.config(
     },
   },
   {
-    // `utils/` is the layer every other directory imports, so it must not
-    // import back into one. The daemon direction is clean and enforced here;
-    // the remaining `ui/`, `config/`, `i18n/` and `nonInteractive/` edges are
-    // tracked in #9146 and will be added to this group as they are resolved.
+    // `utils/` is the leaf layer that every other directory imports, so it
+    // must not import back up into a domain directory. Type-only imports are
+    // exempt: they are erased at compile time and cannot create a runtime
+    // cycle. See #9146.
     files: ['packages/cli/src/utils/**/*.{ts,tsx}'],
-    rules: {
-      'no-restricted-imports': [
-        'error',
-        {
-          patterns: [
-            {
-              group: ['**/serve/*', '**/serve/**'],
-              message:
-                'packages/cli/src/utils must not import serve/. Move lifecycle-free logic down into utils/ instead (#9146).',
-            },
-          ],
+    plugins: {
+      architecture: {
+        rules: {
+          'no-utils-upward-import': noUtilsUpwardImport,
         },
-      ],
+      },
+    },
+    rules: {
+      'architecture/no-utils-upward-import': 'error',
     },
   },
   {

packages/cli/src/acp-integration/acpAgent.test.ts

@@ -35,7 +35,7 @@ const { mockMcpPoolDrainAll } = vi.hoisted(() => ({
 vi.mock('../utils/cleanup.js', () => ({
   runExitCleanup: mockRunExitCleanup,
 }));
-vi.mock('../utils/housekeeping/scheduler.js', () => ({
+vi.mock('../services/housekeeping/scheduler.js', () => ({
   startNonInteractiveOpenAILogHousekeeping:
     mockStartNonInteractiveOpenAILogHousekeeping,
 }));
@@ -872,7 +872,7 @@ vi.mock('./session/Session.js', () => {
     }),
   };
 });
-vi.mock('../utils/languageUtils.js', () => ({
+vi.mock('../i18n/languageUtils.js', () => ({
   updateOutputLanguageFile: vi.fn(),
   writeOutputLanguageAndRegisterPath: vi.fn(
     (
@@ -994,7 +994,7 @@ import {
   resolveOutputLanguageOrPreserveAuto,
   updateOutputLanguageFile,
   writeOutputLanguageAndRegisterPath,
-} from '../utils/languageUtils.js';
+} from '../i18n/languageUtils.js';
 import { buildAuthMethods } from './authMethods.js';
 import {
   ACTIVE_WORK_HEARTBEAT_META_KEY,

packages/cli/src/acp-integration/acpAgent.ts

@@ -187,7 +187,7 @@ import {
   ACP_EVENT_LOOP_STALL_RESTART_MS,
   CHANNEL_PROMPT_META_KEY,
 } from '@qwen-code/channel-base';
-import { observeAcpToolResultWire } from '../utils/tool-result-boundary-diagnostics.js';
+import { observeAcpToolResultWire } from '../nonInteractive/tool-result-boundary-diagnostics.js';
 import { Readable, Writable } from 'node:stream';
 import { normalizeDisabledToolList } from '../config/normalizeDisabledTools.js';
 import { pipeline } from 'node:stream/promises';
@@ -278,11 +278,11 @@ import {
   resolveOutputLanguageOrPreserveAuto,
   getOutputLanguageFilePath,
   writeOutputLanguageAndRegisterPath,
-} from '../utils/languageUtils.js';
+} from '../i18n/languageUtils.js';
 import { runWithAcpRuntimeOutputDir } from './runtimeOutputDirContext.js';
 import { ACP_ERROR_CODES } from './errorCodes.js';
 import { runExitCleanup } from '../utils/cleanup.js';
-import { startNonInteractiveOpenAILogHousekeeping } from '../utils/housekeeping/scheduler.js';
+import { startNonInteractiveOpenAILogHousekeeping } from '../services/housekeeping/scheduler.js';
 import { appEvents, AppEvent } from '../utils/events.js';
 import {
   setLanguageAsync,

packages/cli/src/acp-integration/session/Session.ts

@@ -269,10 +269,8 @@ import type {
   AgentSideConnection,
 } from '@agentclientprotocol/sdk';
 import { SettingScope, type LoadedSettings } from '../../config/settings.js';
-import {
-  insertAfterFunctionResponses,
-  normalizePartList,
-} from '../../utils/nonInteractiveHelpers.js';
+import { insertAfterFunctionResponses } from '../../nonInteractive/nonInteractiveHelpers.js';
+import { normalizePartList } from '../../utils/normalize-part-list.js';
 import { prefixMidTurnUserMessageParts } from '../../utils/midTurnUserMessage.js';
 import {
   handleSlashCommand,
@@ -320,7 +318,7 @@ import type {
 } from './types.js';
 import { HistoryReplayer } from './history-replayer.js';
 import { projectAcpToolResultUpdate } from './acp-tool-result-text-projection.js';
-import { observeAcpToolResultProjection } from '../../utils/tool-result-boundary-diagnostics.js';
+import { observeAcpToolResultProjection } from '../../nonInteractive/tool-result-boundary-diagnostics.js';
 import { ToolCallEmitter } from './emitters/tool-call-emitter.js';
 import { ToolCallPreparationTracker } from './tool-call-preparation-tracker.js';
 import { PlanEmitter } from './emitters/PlanEmitter.js';

packages/cli/src/acp-integration/session/emitters/tool-call-emitter.ts

@@ -31,7 +31,7 @@ import {
   createTranscriptToolCallStartUpdate,
 } from '@qwen-code/acp-bridge/transcriptReplay';
 import { sanitizeTerminalText } from '../../../ui/utils/textUtils.js';
-import { associateAcpToolResultArtifact } from '../../../utils/tool-result-boundary-diagnostics.js';
+import { associateAcpToolResultArtifact } from '../../../nonInteractive/tool-result-boundary-diagnostics.js';
 
 const KIND_MAP: Record<Kind, ToolKind> = {
   [Kind.Read]: 'read',

packages/cli/src/acp-integration/session/history-replay-page.test.ts

@@ -28,10 +28,10 @@ import {
 
 const observeAcpProjectionMock = vi.hoisted(() => vi.fn());
 vi.mock(
-  '../../utils/tool-result-boundary-diagnostics.js',
+  '../../nonInteractive/tool-result-boundary-diagnostics.js',
   async (original) => ({
     ...(await original<
-      typeof import('../../utils/tool-result-boundary-diagnostics.js')
+      typeof import('../../nonInteractive/tool-result-boundary-diagnostics.js')
     >()),
     observeAcpToolResultProjection: observeAcpProjectionMock,
   }),

packages/cli/src/acp-integration/session/history-replay-page.ts

@@ -20,7 +20,7 @@ import type { SessionUpdate } from '@agentclientprotocol/sdk';
 import type { TranscriptReplayStateV1 } from '@qwen-code/acp-bridge/transcriptReplay';
 import { Buffer } from 'node:buffer';
 import { projectAcpToolResultUpdate } from './acp-tool-result-text-projection.js';
-import { observeAcpToolResultProjection } from '../../utils/tool-result-boundary-diagnostics.js';
+import { observeAcpToolResultProjection } from '../../nonInteractive/tool-result-boundary-diagnostics.js';
 import { HistoryReplayer } from './history-replayer.js';
 import type { PendingReplayToolCall } from './history-replayer.js';
 import type { CumulativeUsage, SessionEmitterContext } from './types.js';

packages/cli/src/commands/review.ts

@@ -12,7 +12,7 @@ import type { Argv, CommandModule } from 'yargs';
 import { parseArgsCommand } from './review/parse-args.js';
 import { matchRemoteCommand } from './review/match-remote.js';
 import { composeReviewCommand } from './review/compose-review.js';
-import { findingsCommand } from '../utils/findings.js';
+import { findingsCommand } from './review/findings.js';
 import { recoverFindingsCommand } from './review/recover-findings.js';
 import { fetchPrCommand } from './review/fetch-pr.js';
 import { captureLocalCommand } from './review/capture-local.js';

packages/cli/src/commands/review/compose-review.ts

@@ -37,7 +37,7 @@ import {
   SOURCES,
   type Severity,
   type Source,
-} from '../../utils/findings.js';
+} from './findings.js';
 import { BRIEFS } from './lib/agent-briefs.js';
 import {
   budgetStopDisclosure,

packages/cli/src/utils/findings.ts → packages/cli/src/commands/review/findings.ts

@@ -42,9 +42,9 @@ import {
 } from 'node:fs';
 import type { Stats } from 'node:fs';
 import { dirname, resolve, sep } from 'node:path';
-import { writeStdoutLine, writeStderrLine } from './stdioHelpers.js';
-import type { AnchorRequest } from '../commands/review/lib/anchors.js';
-import { isSameFile } from '../commands/review/lib/same-file.js';
+import { writeStdoutLine, writeStderrLine } from '../../utils/stdioHelpers.js';
+import type { AnchorRequest } from './lib/anchors.js';
+import { isSameFile } from './lib/same-file.js';
 
 // These four lists have a second consumer: the Web Shell review renderer
 // (packages/web-shell/client/components/artifacts/CodeReviewArtifactDetail.tsx)

packages/cli/src/commands/review/lib/review-settings.test.ts

@@ -36,7 +36,7 @@ vi.mock('../../../config/settings.js', async (importOriginal) => {
   return { ...actual, loadSettings: loadSettingsMock };
 });
 import { operatorReviewSettings } from './review-settings.js';
-import { getDialogSettingKeys } from '../../../utils/settingsUtils.js';
+import { getDialogSettingKeys } from '../../../config/settingsUtils.js';
 
 function setReview(review: unknown): void {
   loadSettingsMock.mockReturnValue({ merged: { review } });

packages/cli/src/commands/review/lib/shell-quote.ts

@@ -10,7 +10,7 @@
  * plain `'…'` wrap traded that for breaking on the first embedded apostrophe
  * (`~/Documents/John's Projects/…` is an ordinary macOS workspace). The
  * `'\''` dance closes both: end the quote, emit a literal `'`, reopen.
- * Same pattern as `shellQuoteForSh` in utils/standalone-update.ts.
+ * Same pattern as `shellQuoteForSh` in ui/standalone-update.ts.
  */
 export function shellQuotePath(p: string): string {
   return `'${p.replace(/'/g, "'\\''")}'`;

packages/cli/src/commands/review/publish-assets.ts

@@ -51,11 +51,7 @@ import {
   type AssetsManifest,
   type PublishedAsset,
 } from './lib/assets.js';
-import {
-  validateFindings,
-  buildReport,
-  type Finding,
-} from '../../utils/findings.js';
+import { validateFindings, buildReport, type Finding } from './findings.js';
 
 interface PublishAssetsArgs {
   pr: number;

packages/cli/src/commands/review/save-artifact.test.ts

@@ -20,7 +20,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import yargs from 'yargs';
 import type { Argv } from 'yargs';
-import { buildReport, type Finding } from '../../utils/findings.js';
+import { buildReport, type Finding } from './findings.js';
 import { saveArtifactCommand, saveReviewArtifact } from './save-artifact.js';
 
 // On a case-sensitive filesystem the alias below never exists, so that test

packages/cli/src/commands/review/save-artifact.ts

@@ -28,7 +28,7 @@ import {
   buildReport,
   type FindingsReport,
   validateFindings,
-} from '../../utils/findings.js';
+} from './findings.js';
 import { EFFORT_LEVELS, type ReviewEffort } from './parse-args.js';
 import { REVIEWS_DIR } from './lib/paths.js';
 import { isSameFile } from './lib/same-file.js';

packages/cli/src/commands/update.test.ts

@@ -52,7 +52,7 @@ vi.mock('../utils/installationInfo.js', () => ({
   getInstallationInfo,
   resolveUpdateCommand,
 }));
-vi.mock('../utils/standalone-update.js', () => ({ performStandaloneUpdate }));
+vi.mock('../ui/standalone-update.js', () => ({ performStandaloneUpdate }));
 vi.mock('../utils/package.js', () => ({ getPackageJson }));
 vi.mock('../utils/stdioHelpers.js', () => ({
   writeStdoutLine,

packages/cli/src/commands/update.ts

@@ -24,7 +24,7 @@ export const updateCommand: CommandModule = {
       import('../config/settings.js'),
       import('../ui/utils/updateCheck.js'),
       import('../utils/installationInfo.js'),
-      import('../utils/standalone-update.js'),
+      import('../ui/standalone-update.js'),
       import('../utils/stdioHelpers.js'),
       import('../utils/updateEventEmitter.js'),
     ]);

packages/cli/src/utils/dialogScopeUtils.ts → packages/cli/src/config/dialogScopeUtils.ts

@@ -4,8 +4,8 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import type { LoadedSettings } from '../config/settings.js';
-import { SettingScope } from '../config/settings.js';
+import type { LoadedSettings } from './settings.js';
+import { SettingScope } from './settings.js';
 import { settingExistsInScope } from './settingsUtils.js';
 
 /**

packages/cli/src/config/loadedSettingsAdapter.test.ts

@@ -10,9 +10,8 @@ import { SettingScope } from './settings.js';
 
 // settingsUtils makes real fs calls in backup/restore — stub them out so the
 // tests can focus on adapter behavior without touching disk.
-vi.mock('../utils/settingsUtils.js', async (importOriginal) => {
-  const actual =
-    await importOriginal<typeof import('../utils/settingsUtils.js')>();
+vi.mock('./settingsUtils.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('./settingsUtils.js')>();
   return {
     ...actual,
     backupSettingsFile: vi.fn(),

packages/cli/src/config/loadedSettingsAdapter.ts

@@ -22,7 +22,7 @@ import {
   cleanupSettingsBackup,
   restoreSettingsFromBackup,
   getNestedProperty,
-} from '../utils/settingsUtils.js';
+} from './settingsUtils.js';
 
 export function createLoadedSettingsAdapter(
   settings: LoadedSettings,