Recognize CLI help regardless of argument position

Value flags were binding the next token even when it was --help or
another flag. Scan argv for help first, and reject flag-shaped tokens
as required option values.

Author: TheGreatAxios

CHANGELOG.md

@@ -13,6 +13,11 @@ parallel copies under `docs/` or `scripts/notes/`. At cut time: rename
 
 ## [Unreleased]
 
+### Fixed
+
+- CLI `--help` / `-h` is recognized in any argument position. Value flags no
+  longer swallow help or other flag-shaped tokens as their option values.
+
 ## [0.3.11] - 2026-08-31
 
 ### Changed

src/config.test.ts

@@ -741,6 +741,67 @@ describe("loadConfig", () => {
     }
   });
 
+  test("--help after flags throws CliHelpError", async () => {
+    await expect(
+      loadConfig(["--force", "--help"], { globalSettingsPath: NO_SETTINGS }),
+    ).rejects.toBeInstanceOf(CliHelpError);
+    await expect(
+      loadConfig(["--force", "-h"], { globalSettingsPath: NO_SETTINGS }),
+    ).rejects.toBeInstanceOf(CliHelpError);
+  });
+
+  test("--help after a positional throws CliHelpError", async () => {
+    await expect(
+      loadConfig(["ship it", "--help"], { globalSettingsPath: NO_SETTINGS }),
+    ).rejects.toBeInstanceOf(CliHelpError);
+  });
+
+  test("resume -h / --help throws CliHelpError instead of treating it as a session id", async () => {
+    await expect(
+      loadConfig(["resume", "-h"], { globalSettingsPath: NO_SETTINGS }),
+    ).rejects.toBeInstanceOf(CliHelpError);
+    await expect(
+      loadConfig(["resume", "--help"], { globalSettingsPath: NO_SETTINGS }),
+    ).rejects.toBeInstanceOf(CliHelpError);
+    await expect(
+      loadConfig(["continue", "-h"], { globalSettingsPath: NO_SETTINGS }),
+    ).rejects.toBeInstanceOf(CliHelpError);
+  });
+
+  test("value flags do not swallow --help / -h as their value", async () => {
+    for (const flag of ["--provider", "--model", "--cwd", "--config", "--profile"] as const) {
+      await expect(
+        loadConfig([flag, "--help"], { globalSettingsPath: NO_SETTINGS }),
+      ).rejects.toBeInstanceOf(CliHelpError);
+      await expect(
+        loadConfig([flag, "-h"], { globalSettingsPath: NO_SETTINGS }),
+      ).rejects.toBeInstanceOf(CliHelpError);
+    }
+  });
+
+  test("value flags reject other flag-shaped tokens as values", async () => {
+    await expect(
+      loadConfig(["--provider", "--force"], { globalSettingsPath: NO_SETTINGS }),
+    ).rejects.toThrow("--provider requires a value");
+    await expect(
+      loadConfig(["--model", "--cwd"], { globalSettingsPath: NO_SETTINGS }),
+    ).rejects.toThrow("--model requires a value");
+    await expect(
+      loadConfig(["exec", "--director", "--force", "ship it"], {
+        globalSettingsPath: NO_SETTINGS,
+      }),
+    ).rejects.toThrow("--director requires a value");
+  });
+
+  test("value flags still error clearly when the value is omitted", async () => {
+    await expect(loadConfig(["--provider"], { globalSettingsPath: NO_SETTINGS })).rejects.toThrow(
+      "--provider requires a value",
+    );
+    await expect(loadConfig(["--model"], { globalSettingsPath: NO_SETTINGS })).rejects.toThrow(
+      "--model requires a value",
+    );
+  });
+
   test("rejects unknown flags", async () => {
     await expect(loadConfig(["--unknown"], { globalSettingsPath: NO_SETTINGS })).rejects.toThrow(
       /unrecognized flag/,

src/config/index.ts

@@ -567,6 +567,12 @@ export async function loadConfig(
   argv: readonly string[],
   options: LoadConfigOptions = {},
 ): Promise<Config | UnconfiguredConfig> {
+  // Help wins in any position, including after subcommands and immediately
+  // after a value flag that would otherwise swallow the token as its value.
+  if (argv.some((arg) => arg === "--help" || arg === "-h")) {
+    throw new CliHelpError();
+  }
+
   const args = [...argv];
 
   // Leading subcommand: `corbits exec "prompt"` (alias: `run`). Default is TUI.
@@ -603,10 +609,6 @@ export async function loadConfig(
     }
   }
 
-  if (args[0] === "--help" || args[0] === "-h") {
-    throw new CliHelpError();
-  }
-
   let cwd = process.cwd();
   let force = false;
   let dangerouslySkipPermissions = false;
@@ -626,7 +628,10 @@ export async function loadConfig(
   const positional: string[] = [];
 
   const requireValue = (flag: string, value: string | undefined): string => {
-    if (value === undefined) {
+    // Flag-shaped tokens are never option values. `--provider --force` and a
+    // trailing `--provider` both surface as a missing value rather than binding
+    // the next flag (or accepting `--help`, which is already handled above).
+    if (value === undefined || value.startsWith("-")) {
       throw new Error(`${flag} requires a value`);
     }
     return value;