chainlesschain 0.162.142 → 0.162.147

package/src/commands/agent.js

@@ -16,6 +16,7 @@ import {
 } from "../runtime/fallback-model.js";
 import { resolveImages, resolveVisionLlm } from "../lib/image-input.js";
 import { loadConfig } from "../lib/config-manager.js";
+import { normalizeAgentSandbox } from "../lib/agent-sandbox.js";
 
 /**
  * Resolve + validate `--add-dir` values into absolute, existing, de-duped
@@ -171,6 +172,15 @@ export function registerAgentCommand(program) {
       "--worktree",
       "Run this session in a fresh git worktree (isolated branch; auto-removed when the session changes nothing)",
     )
+    .option(
+      "--sandbox [image]",
+      "Run shell commands in an ephemeral Docker sandbox (network disabled by default)",
+    )
+    .option("--sandbox-network", "Allow network access inside --sandbox")
+    .option(
+      "--bg, --background",
+      "Start as a detached background agent and return its id immediately",
+    )
     .option("--agent-id <id>", "Agent id for scoped memory recall")
     .option("--recall-limit <n>", "Top-K memories to inject into system prompt")
     .option("--recall-query <q>", "Query string for startup memory recall")
@@ -308,7 +318,29 @@ export function registerAgentCommand(program) {
       "--replay-user-messages",
       "Stream-input mode: echo each accepted stdin user message back as a `user` event (transcript/correlation)",
     )
+    .option(
+      "--allow-dangerous-bypass",
+      "Bypass all permission prompts in headless mode (DANGEROUS: auto-approves all tool calls)",
+      false,
+    )
+    .option("-y, --yolo", "Alias for --allow-dangerous-bypass", false)
+    .option(
+      "--dangerously-skip-permissions",
+      "Alias for --allow-dangerous-bypass",
+      false,
+    )
     .action(async (task, options, command) => {
+      const bypassPermissions = !!(
+        options.allowDangerousBypass ||
+        options.yolo ||
+        options.dangerouslySkipPermissions
+      );
+      if (bypassPermissions) {
+        process.env.CC_BYPASS_PERMISSIONS = "1";
+        process.stderr.write(
+          "⚠️  DANGER MODE: All permissions bypassed, no prompts will be shown.\n",
+        );
+      }
       // --safe-mode flag OR CC_SAFE_MODE / CLAUDE_CODE_SAFE_MODE env (Claude-Code
       // 2.1.169 parity): flip every customization kill-switch BEFORE anything
       // loads. Permission rules stay active.
@@ -735,7 +767,62 @@ export function registerAgentCommand(program) {
         if (piped) prompt = piped;
       }
 
+      if (options.bg && !prompt) {
+        process.stderr.write(
+          "--bg requires a task via positional text, -p, or piped stdin.\n",
+        );
+        process.exitCode = 1;
+        return;
+      }
+
       if (prompt) {
+        if (options.bg) {
+          if (options.worktree) {
+            process.stderr.write(
+              "--bg and --worktree cannot be combined yet; create the worktree first and launch the background agent from it.\n",
+            );
+            process.exitCode = 1;
+            return;
+          }
+          const { launchBackgroundAgent } =
+            await import("../lib/background-agent-supervisor.js");
+          const childArgv = process.argv
+            .slice(2)
+            .filter((arg) => arg !== "--bg" && arg !== "--background");
+          const hasSessionArg = childArgv.some(
+            (arg) =>
+              arg === "--session" ||
+              arg === "--resume" ||
+              arg === "--continue" ||
+              arg === "-c",
+          );
+          const sessionId =
+            options.session ||
+            `session-${Date.now()}-${Math.random().toString(16).slice(2, 8)}`;
+          if (!hasSessionArg) childArgv.push("--session", sessionId);
+          const promptWasPiped =
+            positional.length === 0 &&
+            !(typeof options.print === "string" && options.print.trim());
+          if (promptWasPiped) childArgv.push(prompt);
+          const state = launchBackgroundAgent({
+            argv: childArgv,
+            cwd: process.cwd(),
+            sessionId,
+            title: prompt.slice(0, 100),
+          });
+          if (options.outputFormat === "json") {
+            console.log(JSON.stringify(state));
+          } else {
+            console.log(`Background agent started: ${state.id}`);
+            console.log(`  logs: cc agents logs ${state.id}`);
+            console.log(`  stop: cc agents stop ${state.id}`);
+          }
+          return;
+        }
+        const agentSandbox = normalizeAgentSandbox(options.sandbox, {
+          cwd: process.cwd(),
+          network: options.sandboxNetwork === true,
+        });
         // Resume requested onto a session with no headless (JSONL) transcript?
         // Warn instead of silently starting empty 鈥?headless resume rebuilds
         // from the JSONL store only (DB-only sessions are not replayable here).
@@ -775,6 +862,7 @@ export function registerAgentCommand(program) {
           allowedTools: parseToolList(options.allowedTools),
           disallowedTools: parseToolList(options.disallowedTools),
           additionalDirectories,
+          sandbox: agentSandbox,
           autoCheckpoint,
           maxTurns,
           // commander maps --no-file-refs 鈫?options.fileRefs === false
@@ -884,6 +972,10 @@ export function registerAgentCommand(program) {
         parkOnExit: options.parkOnExit, // false when --no-park-on-exit
         bundlePath: options.bundle || null,
         additionalDirectories,
+        sandbox: normalizeAgentSandbox(options.sandbox, {
+          cwd: process.cwd(),
+          network: options.sandboxNetwork === true,
+        }),
         autoCheckpoint,
         // --vim: start the REPL in vim-mode editing (also CC_VIM=1 or /vim).
         vimMode: options.vim === true,

package/src/commands/agents.js

@@ -22,6 +22,74 @@ export function registerAgentsCommand(program) {
     .command("agents")
     .description("User-defined subagents (.claude/agents/*.md)");
 
+  cmd
+    .command("background")
+    .alias("bg")
+    .description("List background agent sessions")
+    .option("--all", "Include completed, failed, stopped and lost sessions")
+    .option("--json", "Output as JSON")
+    .action(async (options) => {
+      const { listBackgroundAgents } =
+        await import("../lib/background-agent-supervisor.js");
+      const sessions = listBackgroundAgents({ all: options.all === true });
+      if (options.json) {
+        console.log(JSON.stringify(sessions, null, 2));
+        return;
+      }
+      if (sessions.length === 0) {
+        logger.log(chalk.gray("No background agents."));
+        return;
+      }
+      for (const session of sessions) {
+        const elapsed = session.endedAt
+          ? session.endedAt - session.startedAt
+          : Date.now() - session.startedAt;
+        logger.log(
+          `${chalk.cyan(session.id)}  ${session.status.padEnd(9)} ${Math.max(0, Math.round(elapsed / 1000))}s  ${session.title || ""}`,
+        );
+        logger.log(chalk.gray(`  pid ${session.pid}  ${session.cwd}`));
+      }
+    });
+
+  cmd
+    .command("logs <id>")
+    .description("Print recent output from a background agent")
+    .option("-n, --lines <n>", "Number of lines", "100")
+    .action(async (id, options) => {
+      try {
+        const { readBackgroundAgentState, readBackgroundAgentLog } =
+          await import("../lib/background-agent-supervisor.js");
+        if (!readBackgroundAgentState(id)) {
+          throw new Error(`Background agent not found: ${id}`);
+        }
+        process.stdout.write(
+          readBackgroundAgentLog(id, { lines: Number(options.lines) }),
+        );
+      } catch (error) {
+        logger.error(chalk.red(error.message));
+        process.exitCode = 1;
+      }
+    });
+
+  cmd
+    .command("stop <id>")
+    .description("Stop a running background agent")
+    .option("--json", "Output as JSON")
+    .action(async (id, options) => {
+      try {
+        const { stopBackgroundAgent } =
+          await import("../lib/background-agent-supervisor.js");
+        const state = stopBackgroundAgent(id);
+        if (options.json) console.log(JSON.stringify(state, null, 2));
+        else if (state.stopped)
+          logger.log(chalk.green(`Stopped background agent ${id}`));
+        else logger.log(chalk.gray(`${id} is already ${state.status}`));
+      } catch (error) {
+        logger.error(chalk.red(error.message));
+        process.exitCode = 1;
+      }
+    });
+
   // ── list ──────────────────────────────────────────────────────────────
   cmd
     .command("list")

package/src/commands/note.js

@@ -8,6 +8,7 @@ import { numericOption } from "../lib/cli-numeric.js";
 import { logger } from "../lib/logger.js";
 import { bootstrap, shutdown } from "../runtime/bootstrap.js";
 import { likePrefix } from "../lib/sql-like.js";
+import { safeJsonParse } from "../lib/safe-json.js";
 import {
   ensureVersionsTable,
   saveVersion,
@@ -204,7 +205,7 @@ export function registerNoteCommand(program) {
         } else {
           logger.log(chalk.bold(`Notes (${notes.length}):\n`));
           for (const n of notes) {
-            const tags = JSON.parse(n.tags || "[]");
+            const tags = safeJsonParse(n.tags, []);
             const tagStr =
               tags.length > 0 ? chalk.gray(` [${tags.join(", ")}]`) : "";
             logger.log(

package/src/commands/permissions.js

@@ -53,26 +53,33 @@ export function registerPermissionsCommand(program) {
   cmd
     .command("list")
     .alias("ls")
-    .description("Show the merged permission ruleset and where each rule came from")
+    .description(
+      "Show the merged permission ruleset and where each rule came from",
+    )
     .option("--json", "Output as JSON")
     .option("--settings <file>", "Also merge an explicit settings file")
     .action(async (options) => {
       try {
         const { loadSettings } = await import("../lib/settings-loader.cjs");
-        const { rules, sources, files } = loadSettings({
+        const { rules, sources, files, managed, managedFile } = loadSettings({
           cwd: process.cwd(),
           settingsFile: options.settings,
         });
         if (options.json) {
-          console.log(JSON.stringify({ rules, sources, files }, null, 2));
+          console.log(
+            JSON.stringify(
+              { rules, sources, files, managed, managedFile },
+              null,
+              2,
+            ),
+          );
           return;
         }
-        const total =
-          rules.allow.length + rules.ask.length + rules.deny.length;
+        const total = rules.allow.length + rules.ask.length + rules.deny.length;
         if (total === 0) {
           logger.log(
             chalk.gray(
-              "No permission rules. Add one: cc permissions add deny \"Bash(rm:*)\"\n" +
+              'No permission rules. Add one: cc permissions add deny "Bash(rm:*)"\n' +
                 "(or create .claude/settings.json with a permissions block)",
             ),
           );
@@ -89,6 +96,40 @@ export function registerPermissionsCommand(program) {
         if (files.length) {
           logger.log(chalk.dim(`\nsources: ${files.join(", ")}`));
         }
+        if (managedFile) {
+          logger.log(chalk.yellow(`managed policy: ${managedFile}`));
+          if (managed?.allowManagedPermissionRulesOnly) {
+            logger.log(
+              chalk.yellow("  user/project permission rules disabled"),
+            );
+          }
+          if (
+            managed?.disableBypassPermissionsMode === true ||
+            managed?.disableBypassPermissionsMode === "disable"
+          ) {
+            logger.log(chalk.yellow("  bypassPermissions disabled"));
+          }
+          if (managed?.allowManagedHooksOnly) {
+            logger.log(chalk.yellow("  only managed hooks may run"));
+          }
+          if (managed?.allowManagedMcpServersOnly) {
+            logger.log(
+              chalk.yellow("  only managed-allowed MCP servers may connect"),
+            );
+          }
+          if (managed?.requireSignedPlugins) {
+            logger.log(chalk.yellow("  signed plugin manifests required"));
+          }
+          if (
+            Array.isArray(managed?.allowedPlugins) ||
+            Array.isArray(managed?.deniedPlugins) ||
+            Array.isArray(managed?.blockedMarketplaces)
+          ) {
+            logger.log(
+              chalk.yellow("  managed plugin supply-chain policy active"),
+            );
+          }
+        }
       } catch (err) {
         logger.error(chalk.red(`permissions list failed: ${err.message}`));
         process.exitCode = 1;
@@ -131,7 +172,13 @@ export function registerPermissionsCommand(program) {
         if (options.json) {
           console.log(
             JSON.stringify(
-              { tool: concrete, args: toolArgs, decision, rule: result.rule, source },
+              {
+                tool: concrete,
+                args: toolArgs,
+                decision,
+                rule: result.rule,
+                source,
+              },
               null,
               2,
             ),
@@ -164,14 +211,19 @@ export function registerPermissionsCommand(program) {
   cmd
     .command("add <decision> <rule>")
     .description("Append a rule (allow|ask|deny) to a settings file")
-    .option("--local", "Write to .claude/settings.local.json (personal, gitignored)")
+    .option(
+      "--local",
+      "Write to .claude/settings.local.json (personal, gitignored)",
+    )
     .option("--user", "Write to ~/.claude/settings.json (all projects)")
     .action(async (decision, rule, options) => {
       try {
         const kind = String(decision || "").toLowerCase();
         if (!["allow", "ask", "deny"].includes(kind)) {
           logger.error(
-            chalk.red(`decision must be allow | ask | deny (got "${decision}")`),
+            chalk.red(
+              `decision must be allow | ask | deny (got "${decision}")`,
+            ),
           );
           process.exitCode = 1;
           return;
@@ -188,7 +240,11 @@ export function registerPermissionsCommand(program) {
           return;
         }
 
-        const scope = options.user ? "user" : options.local ? "local" : "project";
+        const scope = options.user
+          ? "user"
+          : options.local
+            ? "local"
+            : "project";
         const { addRule } = await import("../lib/settings-loader.cjs");
         const { file, added } = addRule({
           cwd: process.cwd(),

package/src/commands/plugin.js

@@ -5,6 +5,11 @@
 
 import chalk from "chalk";
 import { logger } from "../lib/logger.js";
+import {
+  enforcePluginPolicy,
+  loadPluginManagedPolicy,
+  verifyPluginManifest,
+} from "../lib/plugin-security.js";
 import { bootstrap, shutdown } from "../runtime/bootstrap.js";
 import {
   installPlugin,
@@ -90,9 +95,32 @@ export function registerPluginCommand(program) {
     .option("--description <desc>", "Plugin description")
     .option("--author <author>", "Plugin author")
     .option("--manifest <path>", "Plugin manifest file with skill declarations")
+    .option("--source <source>", "Plugin source or marketplace identifier")
+    .option("--sha256 <hex>", "Expected SHA-256 of the manifest")
+    .option("--signature <path>", "Detached Ed25519 signature of the manifest")
+    .option("--public-key <path>", "PEM public key used to verify --signature")
     .option("--json", "Output as JSON")
     .action(async (name, options) => {
       try {
+        const managed = loadPluginManagedPolicy();
+        enforcePluginPolicy(
+          { name, source: options.source, action: "install" },
+          managed,
+        );
+        let verifiedManifest = null;
+        let parsedManifest = null;
+        if (options.manifest || managed?.requireSignedPlugins) {
+          verifiedManifest = verifyPluginManifest({
+            manifestFile: options.manifest,
+            expectedSha256: options.sha256,
+            signatureFile: options.signature,
+            publicKeyFile: options.publicKey,
+            requireSignature: managed?.requireSignedPlugins === true,
+            trustedKeySha256: managed?.trustedPluginKeySha256,
+            requireTrustedKey: managed?.requireSignedPlugins === true,
+          });
+          parsedManifest = JSON.parse(verifiedManifest.bytes.toString("utf8"));
+        }
         const ctx = await bootstrap({ verbose: program.opts().verbose });
         if (!ctx.db) {
           logger.error("Database not available");
@@ -111,8 +139,9 @@ export function registerPluginCommand(program) {
         if (options.manifest) {
           try {
             const fs = await import("fs");
-            const manifestContent = fs.readFileSync(options.manifest, "utf-8");
-            const manifest = JSON.parse(manifestContent);
+            const manifest =
+              parsedManifest ||
+              JSON.parse(fs.readFileSync(options.manifest, "utf-8"));
             if (manifest.skills && manifest.skills.length > 0) {
               const path = await import("path");
               const pluginPath = path.dirname(path.resolve(options.manifest));
@@ -131,7 +160,17 @@ export function registerPluginCommand(program) {
         if (options.json) {
           console.log(
             JSON.stringify(
-              { ...result, skills: skillResult.installed },
+              {
+                ...result,
+                skills: skillResult.installed,
+                integrity: verifiedManifest
+                  ? {
+                      sha256: verifiedManifest.sha256,
+                      signatureVerified: verifiedManifest.signatureVerified,
+                      publicKeySha256: verifiedManifest.publicKeySha256,
+                    }
+                  : null,
+              },
               null,
               2,
             ),
@@ -205,6 +244,10 @@ export function registerPluginCommand(program) {
     .argument("<name>", "Plugin name")
     .action(async (name) => {
       try {
+        enforcePluginPolicy(
+          { name, action: "enable" },
+          loadPluginManagedPolicy(),
+        );
         const ctx = await bootstrap({ verbose: program.opts().verbose });
         if (!ctx.db) {
           logger.error("Database not available");
@@ -262,6 +305,10 @@ export function registerPluginCommand(program) {
     .argument("<version>", "New version")
     .action(async (name, version) => {
       try {
+        enforcePluginPolicy(
+          { name, action: "update" },
+          loadPluginManagedPolicy(),
+        );
         const ctx = await bootstrap({ verbose: program.opts().verbose });
         if (!ctx.db) {
           logger.error("Database not available");

package/src/commands/search.js

@@ -8,6 +8,7 @@ import ora from "ora";
 import { logger } from "../lib/logger.js";
 import { bootstrap, shutdown } from "../runtime/bootstrap.js";
 import { BM25Search } from "../lib/bm25-search.js";
+import { safeJsonParse } from "../lib/safe-json.js";
 
 /**
  * Ensure the notes table exists (same as note.js)
@@ -213,7 +214,7 @@ export function registerSearchCommand(program) {
             ),
           );
           for (const r of results) {
-            const tags = JSON.parse(r.doc.tags || "[]");
+            const tags = safeJsonParse(r.doc.tags, []);
             const tagStr =
               tags.length > 0 ? chalk.gray(` [${tags.join(", ")}]`) : "";
             const snippet = (r.doc.content || "")

package/src/harness/worktree-isolator.js

@@ -857,23 +857,30 @@ function _resolveBaseBranchForMerge(repoDir, baseBranch) {
 }
 
 function _applyAutomationResolution(repoDir, candidateId, filePath) {
+  // filePath here is a conflicted filename straight from `git diff --name-only`
+  // — i.e. it reflects whatever names exist in the (possibly untrusted) branch
+  // being merged. The sibling public functions assertSafeGitPath their filePath,
+  // but this internal helper interpolated it raw into a shell command string, so
+  // a file named `x"; rm -rf ~; ".txt` was a command-injection vector. Use the
+  // array-form gitExecArgs (spawnSync, no shell) so the path is a literal arg —
+  // injection-proof and correct for filenames with spaces/special chars too.
   switch (candidateId) {
     case "accept-current":
-      gitExec(`checkout --theirs -- "${filePath}"`, repoDir);
-      gitExec(`add "${filePath}"`, repoDir);
+      gitExecArgs(["checkout", "--theirs", "--", filePath], repoDir);
+      gitExecArgs(["add", "--", filePath], repoDir);
       return;
     case "accept-incoming":
     case "restore-incoming":
-      gitExec(`checkout --ours -- "${filePath}"`, repoDir);
-      gitExec(`add "${filePath}"`, repoDir);
+      gitExecArgs(["checkout", "--ours", "--", filePath], repoDir);
+      gitExecArgs(["add", "--", filePath], repoDir);
       return;
     case "restore-current":
-      gitExec(`checkout --theirs -- "${filePath}"`, repoDir);
-      gitExec(`add "${filePath}"`, repoDir);
+      gitExecArgs(["checkout", "--theirs", "--", filePath], repoDir);
+      gitExecArgs(["add", "--", filePath], repoDir);
       return;
     case "confirm-delete":
     case "accept-delete":
-      gitExec(`rm -- "${filePath}"`, repoDir);
+      gitExecArgs(["rm", "--", filePath], repoDir);
       return;
     default:
       throw new Error(`Unsupported automation resolution: ${candidateId}`);

package/src/index.js

@@ -1,5 +1,4 @@
-import { Command } from "commander";
-import { VERSION } from "./constants.js";
+import { createBaseProgram } from "./program-base.js";
 import { maybeNotifyUpdate } from "./lib/update-notice.js";
 import { registerSetupCommand } from "./commands/setup.js";
 import { registerStartCommand } from "./commands/start.js";
@@ -391,16 +390,9 @@ import { registerPipoV2Commands } from "./commands/pipeline.js";
  *   opts.allowedCommands takes precedence over the env var.
  */
 export function createProgram(opts = {}) {
-  const program = new Command();
-
-  program
-    .name("chainlesschain")
-    .description(
-      "CLI for ChainlessChain - install, configure, and manage your personal AI management system",
-    )
-    .version(VERSION, "-v, --version")
-    .option("--verbose", "Enable verbose output")
-    .option("--quiet", "Suppress non-essential output");
+  // Base (name/version/global options) is shared with the lazy fast path
+  // (src/lazy-dispatch.js) via program-base.js so they can never drift.
+  const program = createBaseProgram();
 
   // Passive update nudge (Claude-Code parity): one sync cache read + gray
   // stderr line when a newer npm version is known; stale cache refreshes in a

package/src/lazy-dispatch.js

@@ -0,0 +1,107 @@
+/**
+ * Lazy CLI dispatch — the cold-start optimization.
+ *
+ * Importing src/index.js eagerly loads all ~154 command modules + their
+ * transitive dependency graph (~2.7s; see memory
+ * cli_cold_start_bottleneck_hub_repl). But a real `cc <cmd>` invocation only
+ * needs ONE command's module. This dispatcher resolves the target command from
+ * argv against the generated manifest (src/command-manifest.json) and imports
+ * just that module, then parses.
+ *
+ * SAFETY: anything uncertain — no command, --help, an unknown command, or a
+ * project-mode subcommand whitelist — falls back to the full eager program
+ * (src/index.js `createProgram`), i.e. exactly today's behavior. The fast path
+ * only activates when a single known command resolves cleanly. Worst case is
+ * therefore "as slow as today, still correct", never "wrong".
+ *
+ * The manifest is regenerated by scripts/gen-command-manifest.mjs and guarded
+ * against drift by lazy-dispatch.test.js.
+ */
+import { readFileSync } from "fs";
+import { createBaseProgram } from "./program-base.js";
+import { maybeNotifyUpdate } from "./lib/update-notice.js";
+
+const manifest = JSON.parse(
+  readFileSync(new URL("./command-manifest.json", import.meta.url), "utf8"),
+);
+
+// name + every alias -> manifest entry
+const byName = new Map();
+for (const entry of manifest.commands) {
+  byName.set(entry.name, entry);
+  for (const alias of entry.aliases || []) byName.set(alias, entry);
+}
+
+/**
+ * The command token is the first positional arg (the first token that is not a
+ * global option). The root program's only global options (--verbose, --quiet)
+ * and the -v/--version / -h/--help flags are all boolean and never consume a
+ * following value, so "first token not starting with '-'" is unambiguous.
+ */
+export function resolveCommandToken(argv) {
+  const rest = argv.slice(2);
+  for (const arg of rest) {
+    if (arg === "--") break;
+    if (arg.startsWith("-")) continue;
+    return arg;
+  }
+  return null;
+}
+
+function hasVersionFlag(argv) {
+  return argv.slice(2).some((a) => a === "-v" || a === "--version");
+}
+
+function notify() {
+  // Mirror index.js: passive update nudge, suppressed under vitest.
+  if (!process.env.VITEST) {
+    try {
+      maybeNotifyUpdate();
+    } catch {
+      /* fail-open — never block the CLI on the nudge */
+    }
+  }
+}
+
+/**
+ * Parse and run the CLI. Used by the bin entry in place of importing index.js
+ * directly (which would defeat lazy loading).
+ *
+ * @param {string[]} [argv] defaults to process.argv
+ * @returns {Promise<import('commander').Command>}
+ */
+export async function runCli(argv = process.argv) {
+  // Project-mode packed exes restrict the visible command set; the filtering
+  // lives in the eager createProgram, so defer to it for correctness.
+  const whitelistActive = !!process.env.CC_PROJECT_ALLOWED_SUBCOMMANDS;
+  const token = resolveCommandToken(argv);
+
+  // Fast path 1: a known command resolves cleanly.
+  if (token && !whitelistActive && byName.has(token)) {
+    const entry = byName.get(token);
+    const program = createBaseProgram();
+    notify();
+    const mod = await import(new URL(entry.module, import.meta.url));
+    const register = mod[entry.register];
+    if (typeof register === "function") {
+      register(program);
+      return program.parseAsync(argv);
+    }
+    // Manifest pointed at a missing export (should be impossible given the
+    // drift test) — fall through to the eager path rather than crash.
+  }
+
+  // Fast path 2: bare version request, no command (base program short-circuits
+  // without loading any command module).
+  if (!token && !whitelistActive && hasVersionFlag(argv)) {
+    const program = createBaseProgram();
+    notify();
+    return program.parseAsync(argv);
+  }
+
+  // Fallback: --help, no args, unknown command, or project whitelist — load the
+  // full eager program (today's behavior; createProgram fires its own update
+  // nudge so we do not call notify() here to avoid a double nudge).
+  const { createProgram } = await import("./index.js");
+  return createProgram().parseAsync(argv);
+}