perf(cli): keep node:http and ICU off the CLI startup path (-54% warm call)

A warm `appstate` cost 146ms; 79ms of that was startup work no local
command needs.

`node:http` was value-imported by four modules inside the eager import
closure of `src/cli.ts`, so every invocation initialized undici -- and,
under `NODE_USE_SYSTEM_CA=1`, the macOS trust store behind it. That is
~70ms of mostly off-CPU time (a blocking trustd lookup, invisible to
--cpu-prof), paid by commands that never speak HTTP: the default daemon
transport is a plain `node:net` socket. Cheap daemon-only commands paid
it in full; only commands slow enough to absorb it, like `snapshot`,
did not.

Separately, `option-schema.ts` sorted its specs with `localeCompare` at
module scope. The first `localeCompare` in a process costs ~5.4ms of ICU
collator initialization (every later one is ~0.002ms), so the CLI paid
ICU init purely to alphabetize an internal list. A case-insensitive
comparator reproduces the exact same order for the ASCII flag-key
vocabulary -- verified against all 159 keys.

Both HTTP modules are now loaded on demand, via `.default` so they stay
the same mutable module object a static import yields (the transport
tests stub `http.request` on it). Behavior is unchanged: the HTTP
transport, remote daemons and artifact upload/download all still work.

Interleaved A/B, alternating prebuilt dists in one loop, 5-min load avg
< 10, n=30 per arm:

  appstate      146.4ms -> 67.6ms   -53.8%
  session list  137.9ms -> 57.7ms   -58.2%
  snapshot -i   195.5ms -> 188.8ms   -3.4%  (device-work bound)

Without NODE_USE_SYSTEM_CA the appstate win is 73.9ms -> 57.9ms (-22%),
so this is not purely an artifact of that setting.

Measured and rejected: splitting command metadata from runtime handlers
(the facet restructure deferred by #1660). registry.js is 142kB of the
643kB eager closure but only ~1.6ms of module evaluation, and ALL module
compilation is ~9.5ms -- the whole refactor could not clear the 20ms bar
set for attempting it.

A unit test walks the eager closure of src/cli.ts and fails if any file
in it value-imports node:http/node:https again; type-only imports stay
allowed.

Author: thymikee

src/__tests__/cli-startup-import-closure.test.ts

@@ -0,0 +1,84 @@
+import { expect, test } from 'vitest';
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Every CLI invocation eagerly evaluates the static import closure of
+ * `src/cli.ts`. Importing `node:http` (or `node:https`) for a VALUE inside that
+ * closure initializes undici and, under `NODE_USE_SYSTEM_CA=1`, the platform
+ * trust store as well -- ~79ms added to every warm command on macOS, including
+ * ones that never speak HTTP (the default daemon transport is a `node:net`
+ * socket). The HTTP daemon transport, remote-artifact upload and download all
+ * load these modules on demand instead.
+ *
+ * Type-only imports are free and stay allowed; this only rejects value imports.
+ */
+
+const srcRoot = path.resolve(import.meta.dirname, '..');
+// `from './x.ts'` / `from "./x.ts"`, excluding `import type ... from`.
+const STATIC_IMPORT =
+  /(?:^|\n)\s*(?:import|export)\s+(?!type\s)([^;]*?)\s*from\s*['"]([^'"]+)['"]/g;
+
+function collectStaticImports(source: string): { clause: string; specifier: string }[] {
+  const found: { clause: string; specifier: string }[] = [];
+  STATIC_IMPORT.lastIndex = 0;
+  let match: RegExpExecArray | null = null;
+  while ((match = STATIC_IMPORT.exec(source)) !== null) {
+    found.push({ clause: match[1] ?? '', specifier: match[2] ?? '' });
+  }
+  return found;
+}
+
+function resolveRelative(fromFile: string, specifier: string): string | null {
+  const candidate = path.resolve(path.dirname(fromFile), specifier);
+  if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) return candidate;
+  for (const suffix of ['.ts', '.tsx', '/index.ts']) {
+    const withSuffix = `${candidate}${suffix}`;
+    if (fs.existsSync(withSuffix)) return withSuffix;
+  }
+  return null;
+}
+
+function eagerClosureOfCli(): string[] {
+  const queue = [path.join(srcRoot, 'cli.ts')];
+  const visited = new Set<string>();
+  while (queue.length > 0) {
+    const current = queue.pop();
+    if (!current || visited.has(current)) continue;
+    visited.add(current);
+    for (const { specifier } of collectStaticImports(fs.readFileSync(current, 'utf8'))) {
+      if (!specifier.startsWith('.')) continue;
+      const resolved = resolveRelative(current, specifier);
+      if (resolved) queue.push(resolved);
+    }
+  }
+  return [...visited];
+}
+
+test('the CLI startup import closure never value-imports node:http or node:https', () => {
+  const offenders: string[] = [];
+  for (const file of eagerClosureOfCli()) {
+    for (const { clause, specifier } of collectStaticImports(fs.readFileSync(file, 'utf8'))) {
+      if (specifier !== 'node:http' && specifier !== 'node:https') continue;
+      // `import type http from` is caught by the regex's negative lookahead;
+      // `import { type IncomingMessage } from` is a value import of nothing.
+      const importsOnlyTypes = clause
+        .replace(/^\{|\}$/g, '')
+        .split(',')
+        .every((binding) => binding.trim() === '' || binding.trim().startsWith('type '));
+      if (importsOnlyTypes) continue;
+      offenders.push(`${path.relative(srcRoot, file)} -> ${specifier}`);
+    }
+  }
+
+  expect(
+    offenders,
+    'Load node:http / node:https on demand instead: a value import here costs every warm CLI ' +
+      'command ~79ms of undici + system-CA initialization.',
+  ).toEqual([]);
+});
+
+test('the CLI startup import closure is reachable and non-trivial', () => {
+  // Guards the test above from silently passing because the walk found nothing.
+  expect(eagerClosureOfCli().length).toBeGreaterThan(50);
+});

src/cli-schema/option-schema.ts

@@ -91,7 +91,20 @@ function buildOptionSpecs(): OptionSpec[] {
         return supported.has(command);
       },
     }))
-    .sort((left, right) => left.key.localeCompare(right.key));
+    .sort((left, right) => compareOptionKeys(left.key, right.key));
+}
+
+/**
+ * Case-insensitive-then-codepoint ordering, matching what `localeCompare`
+ * produces for the ASCII flag-key vocabulary. This runs at module load on
+ * every CLI invocation, and the FIRST `localeCompare` in a process pays ~5ms
+ * of ICU collator initialization — a cost the CLI otherwise never incurs.
+ */
+function compareOptionKeys(left: string, right: string): number {
+  const leftLower = left.toLowerCase();
+  const rightLower = right.toLowerCase();
+  if (leftLower !== rightLower) return leftLower < rightLower ? -1 : 1;
+  return left < right ? -1 : left > right ? 1 : 0;
 }
 
 function primaryFlagDefinition(spec: OptionSpec): FlagDefinition {

src/daemon/client/daemon-client-progress.ts

@@ -1,5 +1,7 @@
 import type { RequestProgressEvent, RequestProgressSink } from '@agent-device/contracts/progress';
-import http from 'node:http';
+// Type-only: importing `node:http` for a value eagerly initializes undici
+// (~9ms in a fresh process), which the default socket transport never needs.
+import type http from 'node:http';
 import type { Socket } from 'node:net';
 import { AppError } from '@agent-device/kernel/errors';
 import type { DaemonRequest, DaemonResponse } from '../types.ts';

src/daemon/client/daemon-client-transport.ts

@@ -1,7 +1,5 @@
 import type { RequestProgressSink } from '@agent-device/contracts/progress';
 import net from 'node:net';
-import http from 'node:http';
-import https from 'node:https';
 import { AppError } from '@agent-device/kernel/errors';
 import { readNodeHttpResponseBody } from '../../utils/node-http.ts';
 import type { DaemonRequest, DaemonResponse } from '../types.ts';
@@ -20,6 +18,22 @@ import { DAEMON_RPC_PROTOCOL_VERSION } from '../http-health.ts';
 import { readVersion } from '../../utils/version.ts';
 
 type ResolvedDaemonTransport = 'socket' | 'http';
+type NodeHttpRequester = Pick<typeof import('node:http'), 'request'>;
+
+/**
+ * `node:http` eagerly initializes undici, which costs ~9ms of startup in a
+ * fresh process. The default local transport is a plain `node:net` socket and
+ * never issues an HTTP request, so both HTTP modules are loaded on demand —
+ * only the HTTP transport, remote daemons, and HTTP health checks pay for them.
+ */
+async function loadHttpRequester(protocol: string): Promise<NodeHttpRequester> {
+  // `.default` (not the namespace) so this stays the very same module object a
+  // static `import http from 'node:http'` yields — its `request` property is
+  // mutable, which the transport's tests rely on to stub outbound requests.
+  return protocol === 'https:'
+    ? (await import('node:https')).default
+    : (await import('node:http')).default;
+}
 type SendRequestOptions = {
   onProgress?: RequestProgressSink;
 };
@@ -102,19 +116,19 @@ export async function readRemoteDaemonHealth(info: DaemonInfo): Promise<RemoteDa
   return health;
 }
 
-function readDaemonHttpHealth(info: DaemonInfo): Promise<RemoteDaemonHealth> {
+async function readDaemonHttpHealth(info: DaemonInfo): Promise<RemoteDaemonHealth> {
   const endpoint = info.baseUrl
     ? buildDaemonHttpUrl(info.baseUrl, 'health')
     : info.httpPort
       ? `http://127.0.0.1:${info.httpPort}/health`
       : null;
-  if (!endpoint) return Promise.resolve({ reachable: false });
+  if (!endpoint) return { reachable: false };
   const url = new URL(endpoint);
-  const transport = url.protocol === 'https:' ? https : http;
+  const transport = await loadHttpRequester(url.protocol);
   const timeoutMs = info.baseUrl
     ? REMOTE_DAEMON_HEALTHCHECK_TIMEOUT_MS
     : LOCAL_DAEMON_HEALTHCHECK_TIMEOUT_MS;
-  return new Promise((resolve) => {
+  return await new Promise((resolve) => {
     const headers = info.baseUrl ? buildDaemonHttpAuthHeaders(info.token) : {};
     const req = transport.request(
       {
@@ -380,9 +394,9 @@ async function sendHttpRequest(
   if (info.baseUrl) {
     Object.assign(headers, buildDaemonHttpAuthHeaders(info.token));
   }
+  const transport = await loadHttpRequester(rpcUrl.protocol);
 
   return await new Promise((resolve, reject) => {
-    const transport = rpcUrl.protocol === 'https:' ? https : http;
     const request = transport.request(
       {
         protocol: rpcUrl.protocol,

src/remote/daemon-artifacts.ts

@@ -1,6 +1,4 @@
 import fs from 'node:fs';
-import http from 'node:http';
-import https from 'node:https';
 import path from 'node:path';
 import { pipeline } from 'node:stream/promises';
 import { AppError } from '@agent-device/kernel/errors';
@@ -349,7 +347,13 @@ type DownloadRemoteArtifactParams = {
 
 export async function downloadRemoteArtifact(params: DownloadRemoteArtifactParams): Promise<void> {
   const artifactUrl = new URL(buildDaemonArtifactUrl(params.baseUrl, params.artifactId));
-  const transport = artifactUrl.protocol === 'https:' ? https : http;
+  // Loaded on demand: `prepareRemoteRequestArtifacts` runs on every CLI
+  // request, but only a remote daemon ever downloads an artifact, and
+  // importing `node:http` for a value costs ~9ms of undici init.
+  const transport =
+    artifactUrl.protocol === 'https:'
+      ? (await import('node:https')).default
+      : (await import('node:http')).default;
   await fs.promises.mkdir(path.dirname(params.destinationPath), { recursive: true });
   await new Promise<void>((resolve, reject) => {
     let settled = false;

src/remote/upload-stream.ts

@@ -1,6 +1,5 @@
 import fs from 'node:fs';
-import http, { type IncomingHttpHeaders } from 'node:http';
-import https from 'node:https';
+import type { IncomingHttpHeaders } from 'node:http';
 import path from 'node:path';
 import { pipeline } from 'node:stream/promises';
 import { AppError } from '@agent-device/kernel/errors';
@@ -65,7 +64,13 @@ async function streamFileToHttpRequestAttempt(options: {
   startOffset: number;
   progress?: UploadStreamProgressOptions;
 }): Promise<UploadStreamResponse> {
-  const transport = options.url.protocol === 'https:' ? https : http;
+  // Loaded on demand: this module sits in the CLI's eager import closure via
+  // the remote-artifact upload client, but only a remote daemon ever uploads.
+  // Importing `node:http` for a value costs ~9ms of undici init per process.
+  const transport =
+    options.url.protocol === 'https:'
+      ? (await import('node:https')).default
+      : (await import('node:http')).default;
   const payloadSize = fs.statSync(options.payloadPath).size;
   const headers = buildUploadRequestHeaders(options.headers, options.startOffset, payloadSize);
   emitUploadAttemptStarted(options.progress, options.startOffset, payloadSize);